docs: update RFC to document wrapper package pattern and new install flows

Author: fengmk2

rfcs/merge-global-and-local-cli.md

@@ -50,13 +50,62 @@ packages/cli/
 │       ├── create.js
 │       ├── migrate.js
 │       └── version.js
-├── install.sh / install.ps1  # Global install scripts (from global)
-├── templates/                # Project templates (from global)
-├── rules/                    # Oxlint rules (from global)
+├── install.sh / install.ps1  # Global install scripts
+├── templates/                # Project templates
+├── rules/                    # Oxlint rules
 ├── snap-tests/               # Local CLI snap tests
-└── snap-tests-global/        # Global CLI snap tests (from global)
+└── snap-tests-global/        # Global CLI snap tests
 ```
 
+### Global Install Directory (`~/.vite-plus/`)
+
+The global install directory uses a wrapper package pattern. Each version directory
+declares `vite-plus` as an npm dependency instead of extracting its internals directly.
+This decouples the `vp` binary from vite-plus's internal file layout.
+
+```
+~/.vite-plus/
+├── bin/
+│   └── vp                            # Symlink to current/bin/vp
+├── current -> <version>/             # Symlink to active version
+├── <version>/
+│   ├── bin/
+│   │   └── vp                        # Rust binary (from platform package)
+│   ├── package.json                  # Wrapper: { "dependencies": { "vite-plus": "<version>" } }
+│   └── node_modules/
+│       ├── vite-plus/                # Installed as npm dependency
+│       │   ├── dist/bin.js           # JS entry point (found by Rust binary)
+│       │   ├── dist/global/          # Bundled global commands
+│       │   ├── binding/              # NAPI loader
+│       │   ├── templates/            # Project templates
+│       │   ├── rules/                # Oxlint rules
+│       │   └── package.json          # Real vite-plus package.json
+│       ├── @voidzero-dev/            # Platform package (via optionalDeps)
+│       │   └── vite-plus-<platform>/ # Contains .node NAPI binary
+│       └── [other transitive deps]
+├── env, env.fish, env.ps1            # Shell PATH configuration
+└── packages/                         # Globally installed packages (vp install -g)
+```
+
+**Install flows:**
+
+- **Production** (`curl -fsSL https://viteplus.dev/install.sh | bash`):
+  Downloads platform tarball (extracts only `vp` binary), generates wrapper `package.json`,
+  runs `vp install --silent` which installs `vite-plus` + all transitive deps via npm.
+
+- **Upgrade** (`vp upgrade`):
+  Downloads platform tarball (binary only), generates wrapper `package.json`,
+  runs `vp install --silent`. No main tarball download needed.
+
+- **Local dev** (`pnpm bootstrap-cli`):
+  Copies `vp` binary, generates wrapper `package.json`, symlinks
+  `node_modules/vite-plus` to `packages/cli/` source with transitive deps
+  symlinked from `packages/cli/node_modules/`.
+
+- **CI** (`pnpm bootstrap-cli:ci --tgz <path>`):
+  Copies `vp` binary, generates wrapper `package.json` with `file:` protocol
+  refs to tgz files, runs `npm install`.
+
 ### Command Routing
 
 The Rust `vp` binary (`crates/vite_global_cli/`) routes commands in two categories:
@@ -107,6 +156,19 @@ The Rust `vp` binary (`crates/vite_global_cli/`) routes commands in two categori
 - **Category A (Package Manager)**: `install`, `add`, `remove`, `update`, etc. — Handled directly in Rust
 - **Category B (JavaScript)**: All other commands (`build`, `test`, `lint`, `create`, `migrate`, `--version`, etc.) — Rust uses `oxc_resolver` to find the project's local `vite-plus/dist/bin.js` and runs it. Falls back to the global installation's `dist/bin.js` if no local installation exists. The unified `bin.ts` entry point then routes to either NAPI bindings (task commands) or rolldown-bundled modules in `dist/global/` (create, migrate, version).
 
+### Global scripts_dir Resolution (Rust)
+
+The `vp` binary auto-detects the JS scripts directory from its own location:
+
+```rust
+// Auto-detect from binary location
+// ~/.vite-plus/<version>/bin/vp -> ~/.vite-plus/<version>/node_modules/vite-plus/dist/
+let exe_path = std::env::current_exe()?;
+let bin_dir = exe_path.parent()?;           // ~/.vite-plus/<version>/bin/
+let version_dir = bin_dir.parent()?;        // ~/.vite-plus/<version>/
+let scripts_dir = version_dir.join("node_modules").join("vite-plus").join("dist");
+```
+
 ### Local vite-plus Resolution (Rust)
 
 ```rust
@@ -160,33 +222,43 @@ if (command === 'create') {
    - Removed JS shim layer — no more `dist/index.js` intermediary
    - Updated all command entry points from `index.js` to `bin.js`
    - Changed `MAIN_PACKAGE_NAME` from `vite-plus-cli` to `vite-plus`
-   - Added `binding/` to install entries for upgrade command
+   - Scripts dir resolution: `version_dir/node_modules/vite-plus/dist/`
+
+4. **Restructured global install directory** (`~/.vite-plus/<version>/`):
+   - Wrapper `package.json` declares `vite-plus` as a dependency
+   - `vite-plus` installed into `node_modules/` by npm (not extracted from tarball)
+   - `.node` NAPI binaries installed via npm optionalDependencies (not manually copied)
+   - Removed `extract_main_package()`, `strip_dev_dependencies()`, `MAIN_PACKAGE_ENTRIES`
+   - Added `generate_wrapper_package_json()` for upgrade command
+   - Simplified install scripts: only extract `vp` binary + generate wrapper
+   - Simplified `install-global-cli.ts`: symlink-based local dev, wrapper-based CI
 
-4. **Updated build system**:
+5. **Updated build system**:
    - Added `rolldown.config.ts` to bundle global CLI modules into `dist/global/`
    - `treeshake: false` required for dynamic imports
    - Plugin to fix binding import paths in rolldown output
    - Simplified root `package.json` build scripts (removed global package steps)
 
-5. **Updated CI/CD**:
+6. **Updated CI/CD**:
    - Simplified `build-upstream` action (removed global package build steps)
    - Simplified `release.yml` (removed global package publish, now 3 packages instead of 4)
-   - Bumped cache key from `v2` to `v3`
+   - `get_cli_version()` reads from `node_modules/vite-plus/package.json`
 
-6. **Removed `vite` bin alias** — Only `vp` binary entry remains
+7. **Removed `vite` bin alias** — Only `vp` binary entry remains
 
-7. **Updated package.json**:
+8. **Updated package.json**:
    - Added runtime deps: `cross-spawn`, `picocolors`
    - Added devDeps from global: `semver`, `yaml`, `glob`, `minimatch`, `mri`, etc.
    - Added `snap-test-global` script
    - Added `files` entries: `AGENTS.md`, `rules`, `templates`
 
-8. **Updated documentation**: `CLAUDE.md`, `CONTRIBUTING.md`
+9. **Updated documentation**: `CLAUDE.md`, `CONTRIBUTING.md`
 
 ## Verification
 
 - `cargo test -p vite_global_cli` — Rust unit tests pass
 - `pnpm -F vite-plus snap-test-local` — Local CLI snap tests pass
 - `pnpm -F vite-plus snap-test-global` — Global CLI snap tests pass
 - `pnpm bootstrap-cli` — Full build and global install succeeds
+- `VITE_PLUS_VERSION=test bash packages/cli/install.sh` — Production install from npm works
 - Manual testing: `vp create`, `vp migrate`, `vp --version`, `vp build`, `vp test` all work