From 71084bc9c58ef58df1be8afc7b0858483ca8c1dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=A2=85=EA=B2=BD?= Date: Tue, 7 Jul 2026 09:18:46 +0900 Subject: [PATCH] docs: refresh root agent guide --- AGENTS.md | 64 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 45202d3b24..f34d4aa1d0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,25 +22,33 @@ High-signal repo map: ``` vite-plus/ -├── packages/cli/ # Published vite-plus package, JS CLI, docs, templates, snap tests, NAPI binding +├── packages/cli/ # Published vite-plus package, JS CLI, docs, templates, legacy snap tests, NAPI binding │ ├── src/bin.ts # JS entrypoint and local CLI dispatch +│ ├── src/resolve-test.ts # Resolves upstream Vitest for `vp test` │ ├── src/utils/agent.ts # Generated agent-file marker/update logic │ ├── binding/ # Rust NAPI binding used by the local CLI -│ ├── snap-tests/ # Local CLI output snapshots -│ └── snap-tests-global/ # Global CLI output snapshots -├── packages/core/ # @voidzero-dev/vite-plus-core bundled toolchain surfaces -├── packages/test/ # @voidzero-dev/vite-plus-test Vitest-compatible exports -├── packages/prompts/ # Prompt UI/helpers package -├── packages/tools/ # Repo tooling -├── crates/vite_cli_snapshots/ # PTY snapshot test runner + vpt helper (dev-only, new CLI tests) +│ ├── snap-tests/ # Legacy local CLI output snapshots +│ └── snap-tests-global/ # Legacy global CLI output snapshots +├── packages/core/ # @voidzero-dev/vite-plus-core bundled Vite/Rolldown/tsdown/VitePress surfaces +├── packages/prompts/ # Prompt UI/helpers package, including snapshot milestones +├── packages/tools/ # Repo tooling, local npm registry, legacy snap migrator +├── crates/vite_cli_snapshots/ # PTY snapshot test runner + vpt helper (new CLI tests) +├── crates/vite_command/ # Shared command execution helpers +├── crates/vite_error/ # Shared error types ├── crates/vite_global_cli/ # Standalone global vp binary and top-level command routing -├── crates/vite_pm_cli/ # Package-manager command surface ├── crates/vite_install/ # Package-manager detection/install behavior +├── crates/vite_installer/ # Installer binary support ├── crates/vite_js_runtime/ # Managed Node.js runtime support +├── crates/vite_migration/ # Rust migration helpers +├── crates/vite_pm_cli/ # Package-manager command surface +├── crates/vite_setup/ # Setup helpers +├── crates/vite_shared/ # Shared Rust env config, tracing, output, utilities ├── crates/vite_static_config/ # Static extraction of vite.config.* data -└── crates/vite_shared/ # Shared Rust env config, tracing, output, utilities +└── crates/vite_trampoline/ # Windows shim trampoline ``` +`packages/test` is no longer tracked. The public test API is `vite-plus/test*`, generated by `packages/cli/build.ts` as shims over upstream `vitest` and `@vitest/browser*` exports. + ## Where to Start - **JS-backed CLI behavior**: start at `packages/cli/src/bin.ts` and nearby `packages/cli/src/**` files. @@ -51,10 +59,10 @@ vite-plus/ - **Static `vite.config.ts` extraction**: start at `crates/vite_static_config/README.md` and `packages/cli/src/resolve-vite-config.ts`. - **Migration behavior**: `docs/guide/migrate-rules.md`. - **Migrator code (`vp migrate`)**: category modules under `packages/cli/src/migration/migrator/` behind the `migrator.ts` barrel; follow `migrator/README.md` when changing migrator code. -- **Bundled toolchain surfaces**: start with `packages/core/BUNDLING.md`, `packages/cli/BUNDLING.md`, and `packages/test/BUNDLING.md`. +- **Bundled toolchain surfaces**: start with `packages/core/BUNDLING.md` and `packages/cli/BUNDLING.md`. - **Generated project agent guidance**: `packages/cli/AGENTS.md` and `packages/cli/src/utils/agent.ts`; do not edit these when the task is only to improve root repo guidance. - **Product/repo docs**: root contributor docs live at the repo root and the VitePress site under `docs/` (`docs/guide/`, `docs/config/`); generated agent guidance is separate. -- **CLI output behavior**: inspect the relevant code plus `crates/vite_cli_snapshots/tests/cli_snapshots/` (new PTY snapshot suite; write new cases here) or the legacy `packages/cli/snap-tests/` / `packages/cli/snap-tests-global/` trees. +- **CLI output behavior**: inspect the relevant code plus `crates/vite_cli_snapshots/tests/cli_snapshots/` (PTY snapshot suite; write new cases here). Legacy `packages/cli/snap-tests/` and `packages/cli/snap-tests-global/` are migration-only. - **Interactive CLI testing (prompts, pickers, keystrokes)**: `crates/vite_cli_snapshots/tests/cli_snapshots/README.md` and `rfcs/interactive-snapshot-tests.md`. - **Install-testing against the local build**: `packages/tools/src/local-npm-registry.ts` serves the packed checkout behind a real registry interface; used by install snap fixtures (`localVitePlusPackages`), ecosystem e2e (`ecosystem-ci/patch-project.ts`), and local `vp migrate`/`vp create` iteration (see `CONTRIBUTING.md`). @@ -65,7 +73,7 @@ vite-plus/ ```bash vp dev # Vite dev server vp build # Vite + Rolldown build -vp test # Bundled Vitest +vp test # Bundled upstream Vitest vp lint # Oxlint vp fmt # Oxfmt vp check # Format/lint/type-check workflow @@ -77,7 +85,8 @@ vpr build # Shorthand for vp run build Important distinctions: -- `vp test` is a built-in command. `vp run test` runs a `package.json` script or `vite.config.ts` run task named `test`. +- `vp test` is a built-in command that executes upstream Vitest. `vp run test` runs a `package.json` script or `vite.config.ts` run task named `test`. +- User-facing test imports should stay on `vite-plus/test*`; do not recreate `@voidzero-dev/vite-plus-test`. - Existing `package.json` scripts are first-class `vp run