fix(installer): document directory behavior and fix CI

Author: fengmk2

.github/workflows/test-standalone-install.yml

@@ -1253,6 +1253,10 @@ jobs:
             }
           }
 
+          # Each installer process must fail in this test. Reset the native
+          # exit code after the assertions so the PowerShell step succeeds.
+          $global:LASTEXITCODE = 0
+
       - name: vp-setup.exe pre-split fallback leaves no split roots
         shell: pwsh
         run: |

rfcs/directory-layout.md

@@ -146,6 +146,13 @@ Thus, `user_home` and `dirs` cannot use different home directories. Directory
 resolution reads only `VP_HOME`, `VP_*_DIR`, and `XDG_*`. It does not read
 `HOME` or `USERPROFILE`.
 
+`crates/vp_shared/src/dirs/env_overrides.rs` classifies `VP_HOME`,
+`VP_BIN_DIR`, `VP_DATA_DIR`, and `VP_CACHE_DIR` as unset, absolute, or
+relative. Runtime resolution accepts absolute candidates and skips invalid
+candidates. `validate_vp_dir_env` applies the installer policy to the same
+classification. The function returns an error for a relative `VP_HOME`, an
+incomplete split group, or a relative path in a complete split group.
+
 Directory resolution has no test-only branches. Tests use the process
 environment to run the production resolution chain. See
 [Test configuration](#test-configuration).
@@ -242,16 +249,17 @@ A restricted service or CI environment can prevent the known-folder query.
 When this occurs, Vite+ uses `AppData\Local` and `AppData\Roaming` under the
 resolved user home. Thus, a known home always produces a complete layout.
 
-| Source                                            | Behavior                                                                                            |
+| Source                                            | Runtime behavior                                                                                    |
 | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
 | **`VP_HOME`**                                     | Vite+ puts the **monolithic mapping** for all categories under this root.                           |
 | **`~/.vite-plus`**                                | Vite+ uses the monolithic mapping when this directory contains a `current` link.                    |
 | **`VP_BIN_DIR` / `VP_DATA_DIR` / `VP_CACHE_DIR`** | All three values must be set to absolute paths. An incomplete or invalid group has no effect.       |
 | **`XDG_*`** (Unix)                                | Vite+ uses absolute XDG category roots with the app name `vite-plus`. Bin resolves to `<DATA>/bin`. |
 | **Platform defaults**                             | [Category mapping](#category-mapping) defines the Unix and Windows defaults.                        |
 
-Vite+ ignores relative `VP_*` and `XDG_*` values. This behavior follows the XDG
-Base Directory Specification.
+Runtime resolution ignores relative `VP_*` and `XDG_*` values. This behavior
+follows the XDG Base Directory Specification. Installers apply stricter rules
+before they create installation roots.
 
 ### Category mapping
 
@@ -314,12 +322,19 @@ root. Features must not store machine identity or durable state in these files.
 `install.sh`, `install.ps1`, and the local `install-global-cli` use the CLI
 resolution chain:
 
-1. If `VP_HOME` is set, use that root for the **monolithic** layout.
+1. If `VP_HOME` contains an absolute path, use that root for the
+   **monolithic** layout.
 2. Otherwise, check the default `~/.vite-plus` directory or its Windows
    equivalent. If it contains a `current` link, keep the monolithic root.
 3. Otherwise, use a complete `VP_*_DIR` group, `XDG_*`, or platform defaults
    for the **split** layout.
 
+The script installers reject an incomplete or relative `VP_*_DIR` group.
+`vp-setup` rejects those groups and a relative `VP_HOME`. It calls
+`vp_shared::validate_vp_dir_env` before `EnvConfig` resolves paths. A validation
+error makes `vp-setup` exit with status 1 before it creates a requested or
+default installation root.
+
 Each platform has one install script. There is no separate script for each
 layout. Local bootstrap does not set `VP_HOME`. It resolves the install data
 directory through the same chain.
@@ -387,8 +402,8 @@ However, the installer still exits with status 0:
 **Detection.** Each installer downloads the platform payload before it selects
 the final layout. This includes `install.sh`, `install.ps1`, and `vp-setup`. The
 installer then runs the payload binary once with `VP_DUMP_DIRS=1`. The shell and
-PowerShell installers do not resolve `VP_*_DIR`, XDG variables, platform
-defaults, or legacy installs themselves:
+PowerShell installers validate the split override group, but they do not
+resolve `VP_*_DIR`, XDG variables, platform defaults, or legacy installs:
 
 - A current split-aware binary prints the layout mode and one tab-separated line
   for each category root. The categories are `bin`, `data`, `cache`, `config`,
@@ -431,7 +446,10 @@ directories for the success summary.
 The wrapper install uses managed Node.js and pnpm. These tools get their paths
 from the process-wide `EnvConfig`, which resolves before the fallback. Therefore,
 the tools first go into the unused split data root. `do_install` removes this
-root if the current run created it.
+root if the current run created it. Before the probe, `vp-setup` records
+whether the split data parent exists. After a legacy fallback, it removes that
+parent with a non-recursive operation if the current run created it and left it
+empty. Existing parents and parents with new contents remain in place.
 
 The interactive menu has one known limit. It shows the split directories before
 the download. For a pinned pre-split version, the user confirms those
@@ -452,6 +470,11 @@ define the boundary.
 pre-split release without `VP_HOME`. They check the monolithic layout, the
 absence of split roots, and commands that run through `PATH`.
 
+The `test-vp-setup-exe` job rejects each incomplete split-variable combination,
+a relative `VP_HOME`, and a relative complete split group. It checks that
+validation creates no requested or default roots. The pinned `0.2.9` case
+checks that the legacy install works and that no empty split root remains.
+
 This mechanism also keeps fresh default installs of `latest` functional before
 the 0.3.0 release becomes available.
 

rfcs/windows-installer.md

@@ -188,7 +188,7 @@ vp-setup.exe --version 0.3.0 --no-node-manager --registry https://registry.npmmi
 | `-q` / `--quiet`       | Suppress output except errors | false                        |
 | `--version <VER>`      | Install specific version      | latest                       |
 | `--tag <TAG>`          | npm dist-tag                  | latest                       |
-| `--install-dir <PATH>` | Installation directory        | `%USERPROFILE%\.vite-plus`   |
+| `--install-dir <PATH>` | Installation directory        | resolved Vite+ layout        |
 | `--registry <URL>`     | npm registry URL              | `https://registry.npmjs.org` |
 | `--no-node-manager`    | Skip Node.js manager setup    | auto-detect                  |
 | `--no-modify-path`     | Don't modify User PATH        | modify                       |
@@ -198,12 +198,20 @@ vp-setup.exe --version 0.3.0 --no-node-manager --registry https://registry.npmmi
 | Variable                  | Maps to             |
 | ------------------------- | ------------------- |
 | `VP_VERSION`              | `--version`         |
-| `VP_HOME`                 | `--install-dir`     |
+| `VP_HOME`                 | single-root layout  |
+| `VP_BIN_DIR`              | split bin root      |
+| `VP_DATA_DIR`             | split data root     |
+| `VP_CACHE_DIR`            | split cache root    |
 | `NPM_CONFIG_REGISTRY`     | `--registry`        |
 | `VP_NODE_MANAGER=yes\|no` | `--no-node-manager` |
 
 CLI flags take precedence over environment variables.
 
+`vp-setup.exe` requires an absolute `VP_HOME`. Callers that set a split root
+must set all three `VP_*_DIR` variables to absolute paths. The installer calls
+the shared `vp_shared::validate_vp_dir_env` check before it resolves or creates
+installation roots. The installer returns exit code 1 for invalid configuration.
+
 ## Installation Flow
 
 The installer replicates the same result as `install.ps1`, implemented in Rust via `vp_setup`.
@@ -215,7 +223,7 @@ The installer replicates the same result as `install.ps1`, implemented in Rust v
 │  ┌─ detect platform ──────── win32-x64-msvc                 │
 │  │                           win32-arm64-msvc                │
 │  │                                                          │
-│  ├─ check existing ──────── read %VP_HOME%\current           │
+│  ├─ check existing ──────── read <DATA>\current              │
 │  │                                                          │
 │  └─ resolve version ──────── resolve_version_string()        │
 │                              1 HTTP call: "latest" → "0.3.0" │
@@ -242,7 +250,7 @@ The installer replicates the same result as `install.ps1`, implemented in Rust v
 ┌─────────────────────────────────────────────────────────────┐
 │                      INSTALL                                │
 │                                                             │
-│  ┌─ extract binary ──────── %VP_HOME%\{version}\bin\         │
+│  ┌─ extract binary ──────── <DATA>\{version}\bin\            │
 │  │                          vp.exe + vp-shim.exe             │
 │  │                                                          │
 │  ├─ generate package.json ─ wrapper with vite-plus dep       │
@@ -274,7 +282,7 @@ The installer replicates the same result as `install.ps1`, implemented in Rust v
 │       CONFIGURE         (best-effort, always runs,           │
 │                          even for same-version repair)        │
 │                                                             │
-│  ┌─ create bin shims ────── copy vp-shim.exe → bin\vp.exe   │
+│  ┌─ create bin shims ────── copy vp-shim.exe → <BIN>\vp.exe │
 │  │                          (rename-to-.old if running)      │
 │  │                                                          │
 │  ├─ Node.js manager ────── if enabled (pre-computed):        │
@@ -284,7 +292,7 @@ The installer replicates the same result as `install.ps1`, implemented in Rust v
 │  │                                                          │
 │  └─ modify User PATH ────── if --no-modify-path not set:     │
 │                              HKCU\Environment\Path           │
-│                              prepend %VP_HOME%\bin           │
+│                              prepend <BIN>                   │
 │                              broadcast WM_SETTINGCHANGE      │
 └─────────────────────────────────────────────────────────────┘
                               │
@@ -464,8 +472,12 @@ test-vp-setup-exe:
       # verifies from all three shells after a single install
 ```
 
-The workflow triggers on changes to `crates/vp_installer/**`, `crates/vp_pm_cli/**`, and
-`crates/vp_setup/**`.
+The workflow path filter covers the installer, shared directory resolution,
+setup helpers, shims, global CLI, install scripts, and the workflow file.
+
+The job checks invalid directory overrides and a pinned `0.2.9` install.
+Invalid overrides must leave requested and default roots absent. The old-version
+case must produce a working monolithic install and leave no empty split root.
 
 ## Code Signing
 
@@ -572,6 +584,8 @@ Embed the PowerShell script in a self-extracting exe. Fragile, still requires Po
 - Fresh install from cmd.exe, PowerShell, Git Bash
 - Silent mode (`-y`) installation
 - Custom registry, custom install dir
+- Invalid `VP_HOME` and `VP_*_DIR` configuration
+- Pre-split fallback without an empty split root
 - Upgrade over existing installation
 - Verify `vp --version` works after install
 - Verify PATH is modified correctly