feat(test): PTY-based interactive CLI snapshot tests

.claude/skills/bump-vite-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bump-vite-task
-description: Bump vite-task git dependency to the latest main commit. Use when you need to update the vite-task crates (fspy, vite_glob, vite_path, vite_str, vite_task, vite_workspace) in vite-plus.
+description: Bump vite-task git dependency to the latest main commit. Use when you need to update the vite-task git-dependency crates (vite_task, fspy, pty_terminal_test, and friends; the authoritative set lives in Cargo.toml) in vite-plus.
 allowed-tools: Read, Grep, Glob, Edit, Bash, Agent, WebFetch
 ---
 
@@ -12,15 +12,16 @@ Update the vite-task git dependency in `Cargo.toml` to the latest commit on the
 
 ### 1. Get current and target commits
 
-- Read `Cargo.toml` and find the current `rev = "..."` for any vite-task git dependency (e.g., `vite_task`, `vite_path`, `fspy`, `vite_glob`, `vite_str`, `vite_workspace`). They all share the same revision.
+- Read `Cargo.toml` and find the current `rev = "..."` for any vite-task git dependency; enumerate the full set with `grep 'voidzero-dev/vite-task' Cargo.toml` instead of trusting a hardcoded list. They all share the same revision.
 - Get the latest commit hash on vite-task's main branch:
   ```bash
   git ls-remote https://github.com/voidzero-dev/vite-task.git refs/heads/main
   ```
 
 ### 2. Update Cargo.toml
 
-- Replace **all** occurrences of the old commit hash with the new one in `Cargo.toml`. There are 6 crate entries that reference the same vite-task revision: `fspy`, `vite_glob`, `vite_path`, `vite_str`, `vite_task`, `vite_workspace`.
+- Replace **all** occurrences of the old commit hash with the new one in `Cargo.toml`. The set of crates sharing the vite-task revision changes over time; the grep from step 1 is the authoritative list, so update every entry it returns.
+- The commented `[patch."https://github.com/voidzero-dev/vite-task.git"]` section near the bottom of `Cargo.toml` mirrors the same crates for local vite-task development; keep it in sync when crates are added or removed (a plain rev bump does not touch it).
 
 ### 3. Ensure upstream dependencies are cloned
 
@@ -39,26 +40,32 @@ Update the vite-task git dependency in `Cargo.toml` to the latest commit on the
 - Run `cargo test -p vite_command -p vite_error -p vite_install -p vite_js_runtime -p vite_migration -p vite_shared -p vite_static_config -p vite-plus-cli -p vite_global_cli` to run the vite-plus crate tests.
 - Note: Some tests require network access (e.g., `vite_install::package_manager` tests, `vite_global_cli::commands::env` tests). These may fail in sandboxed environments. Verify they also fail on the main branch before dismissing them.
 - Note: `cargo test -p vite_task` will NOT work because vite_task is a git dependency, not a workspace member.
+- The PTY snapshot suite (`crates/vite_cli_snapshots`) is excluded from `just test`; it is covered in step 6.
 
-### 6. Update snap tests
+### 6. Update snapshot tests
 
-vite-task changes often affect CLI output, which means snap tests need updating. Common output changes:
+vite-task changes often affect CLI output, which means snapshot tests need updating. Common output changes:
 
 - **Status icons**: e.g., cache hit/miss indicators may change
 - **New CLI options**: e.g., new flags added to `vp run` that show up in help output
 - **Cache behavior messages**: e.g., new summary lines about cache status
 - **Task output formatting**: e.g., step numbering, separator lines
 
-To update snap tests:
+**PTY snapshot suite (`crates/vite_cli_snapshots`)**, the primary suite:
+
+- A bump can break it two ways: runner compilation (it consumes vite-task's `pty_terminal_test`, `pty_terminal_test_client`, and `snapshot_test` crates directly, so their API changes surface here; fix in the runner) and recorded CLI output.
+- Unlike the legacy trees, output changes are handled locally with real assertions: `UPDATE_SNAPSHOTS=1 just snapshot-test`, then review the `.md` diffs like code. Without a built `packages/cli/dist`, run the global flavor only: `VP_SNAP_SKIP_FLAVORS=local UPDATE_SNAPSHOTS=1 just snapshot-test`.
+- Windows runs in the `CLI snapshot test (Windows)` CI job via a cross-compiled nextest archive; snapshots are OS-shared, so a Windows-only diff there means a redaction gap, not a re-record.
+- Reference: `crates/vite_cli_snapshots/tests/cli_snapshots/README.md`.
+
+**Legacy snap trees** (`packages/cli/snap-tests/*/snap.txt`, `packages/cli/snap-tests-global/*/snap.txt`, being migrated; do not add cases):
 
 1. Push your changes and let CI run the snap tests.
 2. CI will show the diff in the E2E test logs if snap tests fail.
 3. Extract the diff from CI logs and apply it locally.
 4. Check all three platforms (Linux, Mac, Windows) since they may have slightly different snap test coverage.
 5. Watch for trailing newline issues - ensure snap files end consistently.
 
-Snap test files are at `packages/cli/snap-tests/*/snap.txt` and `packages/cli/snap-tests-global/*/snap.txt`.
-
 ### 7. Review changelog and update docs
 
 - Fetch the vite-task `CHANGELOG.md` diff between old and new commits to see what changed:
@@ -90,7 +97,8 @@ After creating the PR, automatically watch CI without asking the user first. Ens
 
 - **Lint**: Clippy and format checks
 - **Test** (Linux, Mac, Windows): Rust unit tests
-- **CLI E2E test** (Linux, Mac, Windows): Snap tests - most likely to fail on a vite-task bump
+- **CLI snapshot test** (Linux, Mac, Windows): the PTY snapshot suite - most likely to fail on a vite-task bump (runner compiles against vite-task crates AND asserts CLI output)
+- **CLI E2E test** (Linux, Mac, Windows): legacy snap tests during the migration
 - **Run task**: Task runner integration tests
 - **Cargo Deny**: License/advisory checks (may have pre-existing failures unrelated to bump)
 

.github/actions/compute-native-cache-input-hash/action.yml

@@ -15,6 +15,11 @@ runs:
       run: |
         echo "hash=$NATIVE_CACHE_INPUT_HASH" >> "$GITHUB_OUTPUT"
       env:
+        # crates/vite_cli_snapshots is excluded: the snapshot suite (runner,
+        # vpt, fixtures, recorded .md baselines) never feeds the native
+        # binaries, and its dependency changes surface in the hashed root
+        # Cargo.toml/Cargo.lock anyway. Without the exclusion, every
+        # fixture-only change would rebuild the bindings on all platforms.
         NATIVE_CACHE_INPUT_HASH: >-
           ${{
             hashFiles(
@@ -24,6 +29,7 @@ runs:
               'Cargo.toml',
               '.cargo/config.toml',
               'crates/**',
+              '!crates/vite_cli_snapshots/**',
               'packages/cli/binding/src/**',
               'packages/cli/binding/build.rs',
               'packages/cli/binding/Cargo.toml',

.github/workflows/ci.yml

@@ -11,8 +11,13 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      - '**/*.md'
+    # `paths` with negations instead of paths-ignore: PTY snapshot baselines
+    # are .md files (crates/vite_cli_snapshots/**/snapshots/*.md) and a
+    # baseline-only push must still run CI. Later patterns win.
+    paths:
+      - '**'
+      - '!**/*.md'
+      - 'crates/vite_cli_snapshots/**'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
@@ -44,7 +49,10 @@ jobs:
       contents: read
       pull-requests: read
     outputs:
-      code-changed: ${{ steps.filter.outputs.code }}
+      # snapshots is OR-ed in because the PTY runner stores its assertions
+      # as .md files (fixtures/**/snapshots/*.md), which the code filter's
+      # markdown exclusion would otherwise classify as docs-only.
+      code-changed: ${{ steps.filter.outputs.code == 'true' || steps.filter.outputs.snapshots == 'true' }}
     steps:
       - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
       - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
@@ -58,6 +66,8 @@ jobs:
               - '!.github/workflows/deploy-docs-preview.yml'
               - '!.github/workflows/deploy-docs.yml'
               - '!netlify.toml'
+            snapshots:
+              - 'crates/vite_cli_snapshots/**'
 
   docs-fmt:
     name: Docs format check
@@ -183,11 +193,13 @@ jobs:
           cargo check --all-targets --all-features --target x86_64-pc-windows-msvc
 
       # Keep the package selection in sync with the `test` recipe in justfile.
+      # vite_cli_snapshots is excluded there too: its snapshot suite needs a
+      # built vp and node at runtime and joins the Windows archive later.
       - name: Build test archive
         run: |
           eval "$(cargo xwin env --target x86_64-pc-windows-msvc | grep '^export ')"
           unset RUSTFLAGS
-          cargo nextest archive $(for d in crates/*/; do echo -n "-p $(basename $d) "; done) -p vite-plus-cli \
+          cargo nextest archive $(for d in crates/*/; do n=$(basename $d); [ "$n" = "vite_cli_snapshots" ] || echo -n "-p $n "; done) -p vite-plus-cli \
             --target x86_64-pc-windows-msvc --archive-file windows-tests.tar.zst
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -196,6 +208,25 @@ jobs:
           path: windows-tests.tar.zst
           retention-days: 7
 
+      # Separate archive for the PTY snapshot suite (excluded from the
+      # unit-test archive above): its suite needs vp, node, and a built
+      # packages/cli/dist at runtime, which only cli-snapshot-test-windows
+      # provides. The archive carries the cli_snapshots test binary plus the
+      # vpt helper; nextest rewrites CARGO_MANIFEST_DIR/CARGO_BIN_EXE_vpt at
+      # run time so the relocated binaries find fixtures and helpers.
+      - name: Build snapshot test archive
+        run: |
+          eval "$(cargo xwin env --target x86_64-pc-windows-msvc | grep '^export ')"
+          unset RUSTFLAGS
+          cargo nextest archive -p vite_cli_snapshots \
+            --target x86_64-pc-windows-msvc --archive-file windows-snapshot-tests.tar.zst
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: windows-snapshot-test-archive
+          path: windows-snapshot-tests.tar.zst
+          retention-days: 7
+
   test-windows:
     needs: build-windows-tests
     name: Test (Windows)
@@ -996,6 +1027,162 @@ jobs:
         env:
           RUST_MIN_STACK: 8388608
 
+  # Runs the PTY snapshot suite (crates/vite_cli_snapshots) with BOTH vp
+  # flavors on Linux and macOS: the local flavor uses the packages/cli build
+  # from this job, the global flavor reuses the installed release binary via
+  # VP_SNAP_GLOBAL_VP (no vite_global_cli compile; build-upstream builds or
+  # cache-restores it). One leg per OS: the suite is not sharded. Windows
+  # runs in cli-snapshot-test-windows via the cross-compiled archive.
+  cli-snapshot-test:
+    name: CLI snapshot test (${{ matrix.target }})
+    needs:
+      - download-previous-rolldown-binaries
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: namespace-profile-linux-x64-default
+            target: x86_64-unknown-linux-gnu
+          - os: namespace-profile-mac-default
+            target: aarch64-apple-darwin
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
+      - uses: ./.github/actions/clone
+
+      - uses: oxc-project/setup-rust@68c3199c5339f965e6e163924c3c450773eba42b # main (pending v1.0.17 — Swatinem/rust-cache v2.9.1 for node24)
+        with:
+          save-cache: ${{ github.ref_name == 'main' }}
+          cache-key: cli-snapshot-test-${{ matrix.target }}
+
+      - uses: oxc-project/setup-node@4c588e9266bd930b6ddc34307df0659ed511d187 # v1.3.1
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: rolldown-binaries
+          path: ./rolldown/packages/rolldown/src
+          merge-multiple: true
+
+      - name: Build with upstream
+        uses: ./.github/actions/build-upstream
+        with:
+          target: ${{ matrix.target }}
+
+      - name: Install Global CLI vp
+        run: pnpm bootstrap-cli:ci
+
+      # Provision the managed runtime once into the real home so cases can
+      # seed from it (seed-runtime) instead of each downloading ~50MB.
+      # Best-effort: without a seed, cases that need the runtime download it
+      # themselves.
+      - name: Prewarm managed runtime
+        run: |
+          "$HOME/.vite-plus/bin/vp" node --version \
+            || echo "prewarm failed; cases will download the runtime on demand"
+
+      - name: Run PTY snapshot tests
+        run: |
+          VP_SNAP_GLOBAL_VP="$HOME/.vite-plus/bin/vp" \
+          VP_SNAP_JS_RUNTIME_DIR="$HOME/.vite-plus/js_runtime" \
+          cargo test -p vite_cli_snapshots
+        env:
+          RUST_BACKTRACE: '1'
+
+  # Runs the PTY snapshot suite (crates/vite_cli_snapshots) on Windows with
+  # BOTH vp flavors, without a Rust toolchain on the runner: the test binary
+  # and vpt arrive cross-compiled in the nextest archive from
+  # build-windows-tests, the global vp comes prebuilt from build-windows-cli,
+  # and the JS CLI is built here (skip-native) for the local flavor.
+  cli-snapshot-test-windows:
+    name: CLI snapshot test (Windows)
+    needs:
+      - download-previous-rolldown-binaries
+      - build-windows-cli
+      - build-windows-tests
+    runs-on: windows-latest
+    steps:
+      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
+      - uses: ./.github/actions/clone
+
+      # Same Dev Drive TEMP routing as cli-snap-test: staged fixture
+      # workspaces live under os.tmpdir() and must resolve pnpm junction
+      # reparse points cleanly (see that job for the full story).
+      - name: Setup Dev Drive
+        uses: samypr100/setup-dev-drive@30f0f98ae5636b2b6501e181dfb3631b9974818d # v4.0.0
+        with:
+          drive-size: 12GB
+          drive-format: ReFS
+          env-mapping: |
+            TEMP,{{ DEV_DRIVE }}/Temp
+            TMP,{{ DEV_DRIVE }}/Temp
+
+      - name: Create TEMP/TMP on Dev Drive
+        shell: bash
+        run: mkdir -p "$TEMP" "$TMP"
+
+      - uses: oxc-project/setup-node@4c588e9266bd930b6ddc34307df0659ed511d187 # v1.3.1
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: rolldown-binaries
+          path: ./rolldown/packages/rolldown/src
+          merge-multiple: true
+
+      # See the cli-e2e-test job for details on the prebuilt binaries.
+      - name: Download prebuilt Windows binaries
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: windows-cli-binaries
+
+      - name: Build with upstream
+        uses: ./.github/actions/build-upstream
+        with:
+          target: x86_64-pc-windows-msvc
+          skip-native: true
+
+      - name: Install Global CLI vp
+        shell: bash
+        run: pnpm bootstrap-cli:ci
+
+      # Provision the managed runtime once into the real home so cases can
+      # seed from it (seed-runtime) instead of each downloading ~50MB.
+      # Best-effort: without a seed, cases that need the runtime download it
+      # themselves.
+      - name: Prewarm managed runtime
+        shell: bash
+        run: |
+          "$USERPROFILE/.vite-plus/bin/vp.exe" node --version \
+            || echo "prewarm failed; cases will download the runtime on demand"
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: windows-snapshot-test-archive
+
+      - uses: taiki-e/install-action@7a79fe8c3a13344501c80d99cae481c1c9085912 # v2.81.10
+        with:
+          tool: cargo-nextest
+
+      # `cargo-nextest` is invoked directly so the job never depends on the
+      # runner's Rust toolchain. --workspace-remap makes nextest rewrite
+      # CARGO_MANIFEST_DIR and CARGO_BIN_EXE_vpt to this checkout, which is
+      # how the relocated test binary finds fixtures and helpers.
+      - name: Run PTY snapshot tests
+        shell: bash
+        run: |
+          # current/bin, not bin: on Windows bin\vp.exe is the trampoline,
+          # which re-execs %VP_HOME%\current\bin\vp.exe; the runner gives
+          # each case an isolated VP_HOME with no install inside, so the
+          # trampoline would fail. current\bin\vp.exe is the real CLI.
+          export VP_SNAP_GLOBAL_VP="$USERPROFILE/.vite-plus/current/bin/vp.exe"
+          export VP_SNAP_JS_RUNTIME_DIR="$USERPROFILE/.vite-plus/js_runtime"
+          # --no-fail-fast: on a snapshot suite every diff is diagnostic
+          # signal; cancelling on the first failure hides the rest.
+          cargo-nextest nextest run --archive-file windows-snapshot-tests.tar.zst --workspace-remap . --no-fail-fast
+        env:
+          RUST_BACKTRACE: '1'
+          # Keep Windows env parity with the `test` recipe in justfile.
+          __COMPAT_LAYER: RunAsInvoker
+
   cli-e2e-test-musl:
     name: CLI E2E test (Linux x64 musl)
     needs:
@@ -1280,6 +1467,8 @@ jobs:
       - cli-e2e-test
       - cli-e2e-test-musl
       - cli-snap-test
+      - cli-snapshot-test
+      - cli-snapshot-test-windows
       # Skipped on unlabeled PRs; counted on push-to-main and labeled PRs.
       # `contains(needs.*.result, 'failure')` ignores "skipped" results.
       - install-e2e-test-sfw

.gitignore

@@ -9,3 +9,6 @@ rolldown-vite
 vite
 /crates/vite_global_cli/vp
 .void/
+
+# Generated by `tool migrate-snap-tests`; batch PRs summarize it in the description instead
+crates/vite_cli_snapshots/tests/cli_snapshots/MIGRATION-REPORT.md