Skip to content

Commit a02e336

Browse files
committed
docs(rfc): sync RFC with latest implementation changes
- Update interactive menu examples to show "enabled"/"disabled" instead of "auto-detect" (value is now pre-computed) - Add Node.js Manager Auto-Detection section with priority table documenting the full auto-detect logic matching install.ps1/install.sh - Restructure Installation Flow diagram: local version check before HTTP, split resolve_version into resolve_version_string + resolve_platform_package, same-version repair path skips to CONFIGURE, cleanup moved to ACTIVATE - Update Existing Installation Handling: same version now repairs instead of exiting early - Document best-effort post-activation behavior and failure recovery - Update function mapping table with split registry functions - Update Test Workflow snippet to match actual single-job structure - Update Phase 2 description (winreg, pre-computed node manager, repair)
1 parent f65a93a commit a02e336

1 file changed

Lines changed: 73 additions & 44 deletions

File tree

rfcs/windows-installer.md

Lines changed: 73 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -137,30 +137,32 @@ Welcome to Vite+ Installer!
137137
138138
This will install the vp CLI and monorepo task runner.
139139
140-
Install directory: C:\Users\alice\.vite-plus
141-
PATH modification: C:\Users\alice\.vite-plus\bin → User PATH
142-
Version: latest
143-
Node.js manager: auto-detect
140+
Install directory: C:\Users\alice\.vite-plus
141+
PATH modification: C:\Users\alice\.vite-plus\bin → User PATH
142+
Version: latest
143+
Node.js manager: enabled
144144
145-
1) Proceed with installation (default)
146-
2) Customize installation
147-
3) Cancel
145+
1) Proceed with installation (default)
146+
2) Customize installation
147+
3) Cancel
148148
149-
>
149+
>
150150
```
151151

152+
The Node.js manager value is pre-computed via auto-detection before the menu is shown (see [Node.js Manager Auto-Detection](#nodejs-manager-auto-detection)). The user can override it in the customize submenu before proceeding.
153+
152154
Customization submenu:
153155

154156
```
155157
Customize installation:
156158
157159
1) Version: [latest]
158160
2) npm registry: [(default)]
159-
3) Node.js manager: [auto-detect]
161+
3) Node.js manager: [enabled]
160162
4) Modify PATH: [yes]
161163
162164
Enter option number to change, or press Enter to go back:
163-
>
165+
>
164166
```
165167

166168
### Silent Mode (CI)
@@ -208,18 +210,24 @@ The installer replicates the same result as `install.ps1`, implemented in Rust v
208210
│ ┌─ detect platform ──────── win32-x64-msvc │
209211
│ │ win32-arm64-msvc │
210212
│ │ │
211-
│ ├─ resolve version ──────── query npm registry │
212-
│ │ "latest" → "0.3.0" │
213+
│ ├─ check existing ──────── read %VP_HOME%\current │
213214
│ │ │
214-
│ └─ check existing ──────── read %VP_HOME%\current │
215-
│ same version? → exit early │
215+
│ └─ resolve version ──────── resolve_version_string() │
216+
│ 1 HTTP call: "latest" → "0.3.0" │
217+
│ same version? → skip to │
218+
│ CONFIGURE (repair path) │
216219
└─────────────────────────────────────────────────────────────┘
217220
221+
(only if version differs)
222+
218223
219224
┌─────────────────────────────────────────────────────────────┐
220225
│ DOWNLOAD & VERIFY │
221226
│ │
222-
│ ┌─ download tarball ─────── GET tarball URL from registry │
227+
│ ┌─ resolve platform pkg ── resolve_platform_package() │
228+
│ │ 2nd HTTP call: tarball URL + SRI │
229+
│ │ │
230+
│ ├─ download tarball ─────── GET tarball URL from registry │
223231
│ │ progress spinner via indicatif │
224232
│ │ │
225233
│ └─ verify integrity ─────── SHA-512 SRI hash comparison │
@@ -248,26 +256,27 @@ The installer replicates the same result as `install.ps1`, implemented in Rust v
248256
│ ┌─ save previous version ── .previous-version (rollback) │
249257
│ │ (only if upgrading existing) │
250258
│ │ │
251-
│ └─ swap current ────────── mklink /J current → {version} │
252-
│ (junction on Windows, │
253-
│ atomic symlink on Unix) │
259+
│ ├─ swap current ────────── mklink /J current → {version} │
260+
│ │ (junction on Windows, │
261+
│ │ atomic symlink on Unix) │
262+
│ │ │
263+
│ └─ cleanup old versions ── keep last 5 by creation time │
264+
│ protects new + previous version │
254265
└─────────────────────────────────────────────────────────────┘
255266
256267
257268
┌─────────────────────────────────────────────────────────────┐
258-
│ CONFIGURE │
269+
│ CONFIGURE (best-effort, always runs, │
270+
│ even for same-version repair) │
259271
│ │
260272
│ ┌─ create bin shims ────── copy vp-shim.exe → bin\vp.exe │
261273
│ │ (rename-to-.old if running) │
262274
│ │ │
263-
│ ├─ Node.js manager ────── if enabled:
275+
│ ├─ Node.js manager ────── if enabled (pre-computed):
264276
│ │ spawn: vp env setup --refresh │
265277
│ │ if disabled: │
266278
│ │ spawn: vp env setup --env-only │
267279
│ │ │
268-
│ ├─ cleanup old versions ── keep last 5 by creation time │
269-
│ │ (non-fatal on error) │
270-
│ │ │
271280
│ └─ modify User PATH ────── if --no-modify-path not set: │
272281
│ HKCU\Environment\Path │
273282
│ prepend %VP_HOME%\bin │
@@ -283,8 +292,9 @@ Each phase maps to `vite_setup` library functions shared with `vp upgrade`:
283292
| Phase | Key function | Crate |
284293
| ----------------- | ------------------------------------------ | ---------------- |
285294
| Resolve | `platform::detect_platform_suffix()` | `vite_setup` |
286-
| Resolve | `registry::resolve_version()` | `vite_setup` |
287295
| Resolve | `install::read_current_version()` | `vite_setup` |
296+
| Resolve | `registry::resolve_version_string()` | `vite_setup` |
297+
| Download & Verify | `registry::resolve_platform_package()` | `vite_setup` |
288298
| Download & Verify | `HttpClient::get_bytes()` | `vite_install` |
289299
| Download & Verify | `integrity::verify_integrity()` | `vite_setup` |
290300
| Install | `install::extract_platform_package()` | `vite_setup` |
@@ -293,11 +303,32 @@ Each phase maps to `vite_setup` library functions shared with `vp upgrade`:
293303
| Install | `install::install_production_deps()` | `vite_setup` |
294304
| Activate | `install::save_previous_version()` | `vite_setup` |
295305
| Activate | `install::swap_current_link()` | `vite_setup` |
306+
| Activate | `install::cleanup_old_versions()` | `vite_setup` |
296307
| Configure | `install::refresh_shims()` | `vite_setup` |
297-
| Configure | `install::cleanup_old_versions()` | `vite_setup` |
298308
| Configure | `windows_path::add_to_user_path()` | `vite_installer` |
299309

300-
On failure before the **Activate** phase, the version directory is cleaned up and the existing installation remains untouched. After the **Activate** phase (junction swap), the update has already succeeded — subsequent configure steps are best-effort (non-fatal on error).
310+
**Same-version repair**: When the resolved version matches the installed version, the DOWNLOAD/INSTALL/ACTIVATE phases are skipped entirely (saving 1 HTTP request + all I/O). The CONFIGURE phase always runs to repair shims, env files, and PATH if needed.
311+
312+
**Failure recovery**: Before the **Activate** phase, failures clean up the version directory and leave the existing installation untouched. After **Activate**, all CONFIGURE steps are best-effort — failures log a warning but do not cause exit code 1. Rerunning the installer always retries CONFIGURE.
313+
314+
## Node.js Manager Auto-Detection
315+
316+
The Node.js manager decision (`enabled`/`disabled`) is pre-computed before the interactive menu is shown, so the user sees the resolved value and can override it via the customize submenu. No prompts occur during the installation phase.
317+
318+
The auto-detection logic matches `install.ps1`/`install.sh`:
319+
320+
| Priority | Condition | Result |
321+
| -------- | ----------------------------------------- | -------- |
322+
| 1 | `--no-node-manager` CLI flag | disabled |
323+
| 2 | `VP_NODE_MANAGER=yes` | enabled |
324+
| 3 | `VP_NODE_MANAGER=no` | disabled |
325+
| 4 | `bin/node.exe` shim already exists | enabled |
326+
| 5 | CI / Codespaces / DevContainer / DevPod | enabled |
327+
| 6 | No system `node` found | enabled |
328+
| 7 | System `node` present, interactive mode | enabled |
329+
| 8 | System `node` present, silent mode (`-y`) | disabled |
330+
331+
In interactive mode (rules 7), the default matches `install.ps1`'s Y/n prompt where pressing Enter enables it. The user can disable it in the customize menu before installation begins. In silent mode (rule 8), shims are not created unless explicitly requested, avoiding silently taking over an existing Node toolchain.
301332

302333
## Windows-Specific Details
303334

@@ -342,13 +373,13 @@ The binary uses the console subsystem (default for Rust binaries on Windows). Wh
342373

343374
### Existing Installation Handling
344375

345-
| Scenario | Behavior |
346-
| ----------------------------------------- | ------------------------------------------------------- |
347-
| No existing install | Fresh install |
348-
| Same version installed | Print "already up to date", exit 0 |
349-
| Different version installed | Upgrade to target version |
350-
| Corrupt/partial install (broken junction) | Recreate directory structure |
351-
| Running `vp.exe` in bin/ | Rename to `.old`, copy new (same as trampoline pattern) |
376+
| Scenario | Behavior |
377+
| ----------------------------------------- | ------------------------------------------------------------ |
378+
| No existing install | Fresh install |
379+
| Same version installed | Skip download, rerun CONFIGURE phase (repair shims/PATH/env) |
380+
| Different version installed | Upgrade to target version |
381+
| Corrupt/partial install (broken junction) | Recreate directory structure |
382+
| Running `vp.exe` in bin/ | Rename to `.old`, copy new (same as trampoline pattern) |
352383

353384
## Add/Remove Programs Registration
354385

@@ -416,28 +447,24 @@ In `release.yml`, installer artifacts are uploaded per-target, renamed with the
416447

417448
### Test Workflow
418449

419-
`test-standalone-install.yml` includes a `test-vp-setup-exe` job that builds the installer from source and tests silent installation across three shells:
450+
`test-standalone-install.yml` includes a `test-vp-setup-exe` job that builds the installer from source, installs via pwsh, and verifies from all three shells (pwsh, cmd, bash):
420451

421452
```yaml
422453
test-vp-setup-exe:
423-
name: Test vp-setup.exe (${{ matrix.shell }})
454+
name: Test vp-setup.exe (pwsh)
424455
runs-on: windows-latest
425-
strategy:
426-
matrix:
427-
shell: [cmd, pwsh, bash]
428456
steps:
429457
- uses: actions/checkout@v4
430458
- uses: oxc-project/setup-rust@v1
431459
- name: Build vp-setup.exe
432460
run: cargo build --release -p vite_installer
433461
- name: Install via vp-setup.exe (silent)
462+
shell: pwsh
434463
run: ./target/release/vp-setup.exe -y
435464
env:
436465
VP_VERSION: alpha
437-
- name: Verify installation
438-
run: |
439-
vp --version
440-
vp --help
466+
- name: Verify installation (pwsh/cmd/bash)
467+
# verifies from all three shells after a single install
441468
```
442469

443470
The workflow triggers on changes to `crates/vite_installer/**` and `crates/vite_setup/**`.
@@ -513,11 +540,13 @@ Embed the PowerShell script in a self-extracting exe. Fragile, still requires Po
513540

514541
- Created `crates/vite_installer/` with `[[bin]] name = "vp-setup"`
515542
- Implemented CLI argument parsing (clap) with env var merging
516-
- Implemented installation flow calling `vite_setup`
517-
- Implemented Windows PATH modification via raw Win32 FFI
543+
- Implemented installation flow calling `vite_setup` with same-version repair path
544+
- Implemented Windows PATH modification via `winreg` crate
518545
- Implemented interactive prompts with customization submenu
546+
- Implemented Node.js manager auto-detection (pre-computed, no mid-install prompts)
519547
- Implemented progress spinner for downloads
520548
- Added DLL security mitigations (build.rs linker flag + runtime `SetDefaultDllDirectories`)
549+
- Post-activation steps are best-effort (non-fatal on error)
521550

522551
### Phase 3: CI Integration (done)
523552

0 commit comments

Comments
 (0)