|
| 1 | +# AI Agent Guidelines for Vite-Plus |
| 2 | + |
| 3 | +This document helps AI coding assistants work on the **vite-plus repository**. It is repo-specific: `CLAUDE.md` points here for compatibility, while `packages/cli/AGENTS.md` is the generated guidance shipped to projects that use Vite+. |
| 4 | + |
| 5 | +Use this file to orient quickly, choose the right code area, and pick validation that matches the change. Prefer canonical source files and docs over duplicating details here. |
| 6 | + |
| 7 | +## Project Overview |
| 8 | + |
| 9 | +Vite+ is **the unified toolchain for the web** behind the `vp` CLI. It combines Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, Vite Task, runtime management, package-manager workflows, project creation/migration, and monorepo task caching. |
| 10 | + |
| 11 | +### Key Technologies |
| 12 | + |
| 13 | +- **TypeScript / Node ESM**: CLI entrypoints, create/migrate/config/staged commands, docs tooling, and package exports. |
| 14 | +- **Rust 2024**: global `vp` binary, local CLI binding, package-manager/runtime helpers, config extraction, shared utilities. |
| 15 | +- **NAPI**: bridges the TypeScript CLI package to Rust command implementations under `packages/cli/binding/`. |
| 16 | +- **pnpm workspaces**: local packages under `packages/*`. |
| 17 | +- **Vite+ config**: `vite.config.ts` configures lint, format, test, and run tasks for this repo. |
| 18 | + |
| 19 | +## Architecture |
| 20 | + |
| 21 | +High-signal repo map: |
| 22 | + |
| 23 | +``` |
| 24 | +vite-plus/ |
| 25 | +├── packages/cli/ # Published vite-plus package, JS CLI, docs, templates, snap tests, NAPI binding |
| 26 | +│ ├── src/bin.ts # JS entrypoint and local CLI dispatch |
| 27 | +│ ├── src/utils/agent.ts # Generated agent-file marker/update logic |
| 28 | +│ ├── binding/ # Rust NAPI binding used by the local CLI |
| 29 | +│ ├── snap-tests/ # Local CLI output snapshots |
| 30 | +│ └── snap-tests-global/ # Global CLI output snapshots |
| 31 | +├── packages/core/ # @voidzero-dev/vite-plus-core bundled toolchain surfaces |
| 32 | +├── packages/test/ # @voidzero-dev/vite-plus-test Vitest-compatible exports |
| 33 | +├── packages/prompts/ # Prompt UI/helpers package |
| 34 | +├── packages/tools/ # Repo tooling |
| 35 | +├── crates/vite_global_cli/ # Standalone global vp binary and top-level command routing |
| 36 | +├── crates/vite_pm_cli/ # Package-manager command surface |
| 37 | +├── crates/vite_install/ # Package-manager detection/install behavior |
| 38 | +├── crates/vite_js_runtime/ # Managed Node.js runtime support |
| 39 | +├── crates/vite_static_config/ # Static extraction of vite.config.* data |
| 40 | +└── crates/vite_shared/ # Shared Rust env config, tracing, output, utilities |
| 41 | +``` |
| 42 | + |
| 43 | +## Where to Start |
| 44 | + |
| 45 | +- **JS-backed CLI behavior**: start at `packages/cli/src/bin.ts` and nearby `packages/cli/src/**` files. |
| 46 | +- **Local CLI / NAPI-backed behavior**: start at `packages/cli/binding/src/lib.rs` and `packages/cli/binding/src/cli/mod.rs`. |
| 47 | +- **Global `vp` routing, aliases, and runtime bootstrap**: start at `crates/vite_global_cli/src/main.rs` and `crates/vite_global_cli/src/cli.rs`. |
| 48 | +- **Package-manager commands**: start at `crates/vite_pm_cli/` and `crates/vite_install/`. |
| 49 | +- **Managed Node runtime / shims**: start at `crates/vite_js_runtime/`. |
| 50 | +- **Static `vite.config.ts` extraction**: start at `crates/vite_static_config/README.md` and `packages/cli/src/resolve-vite-config.ts`. |
| 51 | +- **Bundled toolchain surfaces**: start with `packages/core/BUNDLING.md`, `packages/cli/BUNDLING.md`, and `packages/test/BUNDLING.md`. |
| 52 | +- **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. |
| 53 | +- **Product/repo docs**: root contributor docs live at the repo root and `docs/`; CLI package docs live under `packages/cli/docs/`; generated agent guidance is separate. |
| 54 | +- **CLI output behavior**: inspect the relevant code plus `packages/cli/snap-tests/` or `packages/cli/snap-tests-global/`. |
| 55 | + |
| 56 | +## Command and Config Model |
| 57 | + |
| 58 | +`vp` has built-in toolchain commands and a separate task runner: |
| 59 | + |
| 60 | +```bash |
| 61 | +vp dev # Vite dev server |
| 62 | +vp build # Vite + Rolldown build |
| 63 | +vp test # Bundled Vitest |
| 64 | +vp lint # Oxlint |
| 65 | +vp fmt # Oxfmt |
| 66 | +vp check # Format/lint/type-check workflow |
| 67 | +vp pack # Library/app packaging |
| 68 | + |
| 69 | +vp run build # Run a package.json script or configured run task |
| 70 | +vpr build # Shorthand for vp run build |
| 71 | +``` |
| 72 | + |
| 73 | +Important distinctions: |
| 74 | + |
| 75 | +- `vp test` is a built-in command. `vp run test` runs a `package.json` script or `vite.config.ts` run task named `test`. |
| 76 | +- Existing `package.json` scripts are first-class `vp run <script>` targets and are not cached by default. |
| 77 | +- Define `run.tasks` in `vite.config.ts` when a task needs explicit command config, default caching, dependencies, input tracking, or environment tracking. |
| 78 | +- A task name can come from `package.json` or `vite.config.ts`, but not both. |
| 79 | +- Do not introduce `vite-task.json`; current Vite+ task configuration lives under `run` in `vite.config.ts`. |
| 80 | +- Do not run `cargo test -p vite_task` in this repo; Vite Task crates are git dependencies, not local workspace members. |
| 81 | + |
| 82 | +Reference: `packages/cli/docs/guide/run.md` and `packages/cli/docs/config/run.md`. |
| 83 | + |
| 84 | +## Development Workflow |
| 85 | + |
| 86 | +### Initial setup |
| 87 | + |
| 88 | +```bash |
| 89 | +just init |
| 90 | +``` |
| 91 | + |
| 92 | +### Build and install from source |
| 93 | + |
| 94 | +```bash |
| 95 | +just build # Release build for Vite+ |
| 96 | +pnpm bootstrap-cli # Build packages, compile vp/NAPI, and install the global CLI |
| 97 | +vp --version |
| 98 | +``` |
| 99 | + |
| 100 | +Use `pnpm bootstrap-cli` when you need to validate the installed global CLI at `~/.vite-plus`. |
| 101 | + |
| 102 | +### Routine validation |
| 103 | + |
| 104 | +Choose checks by change type: |
| 105 | + |
| 106 | +| Change type | Useful validation | |
| 107 | +| ----------------------------- | ----------------------------------------------------------------------- | |
| 108 | +| Docs-only / agent-guide edits | Check referenced paths and commands; run `git diff --check -- <files>` | |
| 109 | +| TypeScript or JS CLI behavior | `vp check`, `pnpm test:unit`, plus focused package tests when available | |
| 110 | +| Rust CLI/crate behavior | `just check`, `just test`, `just lint` | |
| 111 | +| CLI output or command UX | Relevant snap tests, then inspect `git diff` for `snap.txt` changes | |
| 112 | +| Global CLI behavior | `pnpm bootstrap-cli`, `vp --version`, then relevant global snap tests | |
| 113 | +| Release/build behavior | `just build` | |
| 114 | +| Pre-merge/full validation | `pnpm bootstrap-cli && pnpm test && git status` | |
| 115 | + |
| 116 | +Use `vp check --fix` only when you intentionally want formatting or lint fixes applied. |
| 117 | + |
| 118 | +### Snap tests |
| 119 | + |
| 120 | +Snap tests live in `packages/cli/snap-tests/` and `packages/cli/snap-tests-global/`. |
| 121 | + |
| 122 | +```bash |
| 123 | +pnpm -F vite-plus snap-test |
| 124 | +pnpm -F vite-plus snap-test-local |
| 125 | +pnpm -F vite-plus snap-test-local <name-filter> |
| 126 | +pnpm -F vite-plus snap-test-global |
| 127 | +pnpm -F vite-plus snap-test-global <name-filter> |
| 128 | +``` |
| 129 | + |
| 130 | +Snap tests regenerate `snap.txt` and can exit successfully even when output changed. Always inspect `git diff` afterward. Ensure fixture inputs are committed or created by the test setup, not accidentally supplied by ignored local files. |
| 131 | + |
| 132 | +## Code Conventions |
| 133 | + |
| 134 | +### Rust |
| 135 | + |
| 136 | +Reference these files instead of duplicating rules here: |
| 137 | + |
| 138 | +- `.clippy.toml` — custom lint restrictions and disallowed Rust APIs/macros. |
| 139 | +- `crates/vite_shared/src/output.rs` — shared user-facing output helpers. |
| 140 | +- `crates/vite_shared/src/env_config.rs` — test-scoped environment configuration helpers. |
| 141 | +- `crates/vite_command/src/lib.rs` and `crates/vite_global_cli/src/cli.rs` — examples of `vite_path` usage in local Rust code. |
| 142 | + |
| 143 | +Prefer shared output helpers for user-facing messages and match nearby command style. New Rust code should satisfy the custom clippy restrictions. |
| 144 | + |
| 145 | +### TypeScript |
| 146 | + |
| 147 | +Reference these files instead of duplicating rules here: |
| 148 | + |
| 149 | +- `packages/cli/src/utils/terminal.ts` — shared user-facing terminal output helpers. |
| 150 | +- `tsconfig.json` — TypeScript compiler settings. |
| 151 | +- `vite.config.ts` — repository lint, format, test, and task configuration. |
| 152 | +- `packages/cli/src/utils/agent.ts` and `packages/cli/AGENTS.md` — generated/migrated project agent guidance. |
| 153 | + |
| 154 | +## Testing Strategy |
| 155 | + |
| 156 | +Use the validation matrix above as the source of truth. For behavior-bearing changes, find the nearest existing tests before editing and add or update coverage in the same area. For CLI output changes, pair focused tests with snap-test diff review. For documentation-only changes, verify referenced paths, commands, and links instead of running unrelated suites. |
| 157 | + |
| 158 | +## Common Pitfalls |
| 159 | + |
| 160 | +- **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. |
| 161 | +- **Looking for local `crates/vite_task`**: it does not exist here. Check `Cargo.toml` for git dependency wiring. |
| 162 | +- **Confusing built-ins with scripts**: `vp test` and `vp run test` can do different things. |
| 163 | +- **Trusting snap-test exit status alone**: always inspect snapshot diffs. |
| 164 | + |
| 165 | +## Debugging |
| 166 | + |
| 167 | +- Use `vp --version` to see bundled tool versions before researching tool behavior. |
| 168 | +- Use `vp help` and `vp <command> --help` to inspect command surfaces. |
| 169 | +- For command routing bugs, compare the global path (`crates/vite_global_cli/`) with the local/NAPI path (`packages/cli/src/bin.ts`, `packages/cli/binding/`). |
| 170 | +- For config-loading bugs, compare the static extractor (`crates/vite_static_config/`) with the JS resolver fallback (`packages/cli/src/resolve-vite-config.ts`). |
| 171 | +- For package-manager behavior, inspect `crates/vite_pm_cli/`, `crates/vite_install/`, and related snap tests. |
| 172 | +- For `vp check`, lint, format, or type-check behavior, validate end-to-end because bundled-tool routing can hide silent config drift. |
| 173 | + |
| 174 | +## AI Assistant Tips |
| 175 | + |
| 176 | +- Identify the ownership layer before editing: JS CLI, Rust global CLI, NAPI/local CLI, package manager, runtime, config, docs, or bundled packages. |
| 177 | +- Prefer source references over copied explanations when adding guidance; this file should help agents navigate, not replace the docs. |
| 178 | +- Keep diffs scoped to the requested area and leave unrelated tracked or untracked files alone. |
| 179 | + |
| 180 | +## References |
| 181 | + |
| 182 | +- Product overview: `README.md` |
| 183 | +- Contributor workflow: `CONTRIBUTING.md` |
| 184 | +- Root scripts: `package.json` |
| 185 | +- Repo config: `vite.config.ts` |
| 186 | +- Vite+ guide: `docs/guide/index.md` |
| 187 | +- Run guide: `packages/cli/docs/guide/run.md` |
| 188 | +- Run config: `packages/cli/docs/config/run.md` |
| 189 | +- CLI package architecture: `packages/cli/BUNDLING.md` |
| 190 | +- Core package architecture: `packages/core/BUNDLING.md` |
| 191 | +- Test package architecture: `packages/test/BUNDLING.md` |
| 192 | +- Generated agent guidance: `packages/cli/AGENTS.md`, `packages/cli/src/utils/agent.ts` |
0 commit comments