Skip to content

docs: refresh root agent guide #2072

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fengmk2 merged 1 commit into from
Jul 7, 2026
Merged

docs: refresh root agent guide #2072

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 37 additions & 27 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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`).

Expand All @@ -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
Expand All @@ -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 <script>` targets and are not cached by default.
- Define `run.tasks` in `vite.config.ts` when a task needs explicit command config, default caching, dependencies, input tracking, or environment tracking.
- A task name can come from `package.json` or `vite.config.ts`, but not both.
Expand Down Expand Up @@ -108,15 +117,15 @@ Use `pnpm bootstrap-cli` when you need to validate the installed global CLI at `

Choose checks by change type:

| Change type | Useful validation |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| Docs-only / agent-guide edits | Check referenced paths and commands; run `git diff --check -- <files>` |
| TypeScript or JS CLI behavior | `vp check`, `pnpm test:unit`, plus focused package tests when available |
| Rust CLI/crate behavior | `just check`, `just test`, `just lint` |
| CLI output or command UX | `just snapshot-test <filter>` (new PTY runner); legacy snap tests + `git diff` while migration lasts |
| Global CLI behavior | `pnpm bootstrap-cli`, `vp --version`, then relevant global snap tests |
| Release/build behavior | `just build` |
| Pre-merge/full validation | `pnpm bootstrap-cli && pnpm test && git status` |
| Change type | Useful validation |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| Docs-only / agent-guide edits | Check referenced paths and commands; run `git diff --check -- <files>` |
| TypeScript or JS CLI behavior | `vp check`, `pnpm test:unit`, plus focused package tests when available |
| Rust CLI/crate behavior | `just check`, `just test`, `just lint` |
| CLI output or command UX | `just snapshot-test <filter>` (PTY runner); `UPDATE_SNAPSHOTS=1` to accept reviewed changes |
| Global CLI behavior | `pnpm bootstrap-cli`, `vp --version`, or `just snapshot-test-global <filter>` |
| Release/build behavior | `just build` |
| Pre-merge/full validation | `pnpm bootstrap-cli && pnpm test && git status` |

Use `vp check --fix` only when you intentionally want formatting or lint fixes applied.

Expand All @@ -127,14 +136,15 @@ Use `vp check --fix` only when you intentionally want formatting or lint fixes a
```bash
just snapshot-test # build vp, run everything
just snapshot-test <name-filter>
just snapshot-test-global <name-filter> # skip local flavor when no JS build is available
UPDATE_SNAPSHOTS=1 just snapshot-test <name-filter> # record/accept snapshots
```

Snapshot mismatches fail the run with a unified diff and write `<case>.md.new`; recorded `.md` snapshots are reviewed like code and committed with the fixture. Steps are argv arrays (no shell); use `vpt` subcommands instead of coreutils so cases stay platform-identical.
Snapshot mismatches fail the run with a unified diff and write `<case>.md.new`; recorded `.md` snapshots are reviewed like code and committed with the fixture. Steps are argv arrays (no shell); use `vpt` subcommands instead of coreutils so cases stay platform-identical. Cases declare `vp = "local" | "global" | ["local", "global"]`; local-flavor cases require a fresh `packages/cli/dist`.

### Snap tests (legacy, being migrated)

The old trees `packages/cli/snap-tests/` and `packages/cli/snap-tests-global/` still run in CI during the migration but must not receive new cases; convert them with `tool migrate-snap-tests` instead (see the runner README).
The old trees `packages/cli/snap-tests/` and `packages/cli/snap-tests-global/` still run in CI during the migration but must not receive new cases; convert them with `node packages/tools/src/bin.js migrate-snap-tests ...` instead (see the runner README).

```bash
pnpm -F vite-plus snap-test
Expand Down Expand Up @@ -173,7 +183,7 @@ Use the validation matrix above as the source of truth. For behavior-bearing cha
## Common Pitfalls

- **Treating Vite+ as only Vite Task**: Vite Task is integrated, but this repo spans CLI, runtime, package management, bundled packages, create/migrate, docs, and upstream integration.
- **Looking for local `crates/vite_task`**: it does not exist here. Check `Cargo.toml` for git dependency wiring.
- **Looking for local `packages/test` or `crates/vite_task`**: neither is tracked here. Check `packages/cli/BUNDLING.md` for test shims and `Cargo.toml` for Vite Task git dependency wiring.
- **Confusing built-ins with scripts**: `vp test` and `vp run test` can do different things.
- **Trusting snap-test exit status alone**: always inspect snapshot diffs.

Expand Down Expand Up @@ -203,5 +213,5 @@ Use the validation matrix above as the source of truth. For behavior-bearing cha
- Run config: `docs/config/run.md`
- CLI package architecture: `packages/cli/BUNDLING.md`
- Core package architecture: `packages/core/BUNDLING.md`
- Test package architecture: `packages/test/BUNDLING.md`
- CLI snapshot runner: `crates/vite_cli_snapshots/tests/cli_snapshots/README.md`
- Generated agent guidance: `packages/cli/AGENTS.md`, `packages/cli/src/utils/agent.ts`
Loading