docs(e2e): move ipc_client_test + vite_build_cache comments into toml fields

Follows the convention introduced in main (#347): per-`[[e2e]]` and per-
step descriptions use the TOML `comment` field instead of bare `#` lines,
so they render under the snapshot headings and inside each step's block.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: branchseer

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots.toml

@@ -1,56 +1,54 @@
-# E2E tests for @voidzero-dev/vite-task-client. Each case exercises one IPC
-# method by running a Node script inside a real cached task and observing the
-# runner's cache behaviour.
-
-# ignoreInput: the runner treats cache_like/ as non-input, so mutations to it
-# between runs do not invalidate the cache.
 [[e2e]]
 name = "ignore_input_keeps_cache_valid"
+comment = """
+Exercises `ignoreInput` through `@voidzero-dev/vite-task-client`.
+The runner treats `cache_like/` as non-input, so mutations to it between
+runs do not invalidate the cache.
+"""
 ignore = true
 steps = [
-  # First run populates the cache.
-  ["vt", "run", "ignore-input"],
-  # Mutate the ignored directory between runs; this would invalidate the cache
-  # if the runner had tracked it as an input.
-  ["vtt", "write-file", "cache_like/other.txt", "after"],
-  # Second run must still be a cache hit.
+  { argv = ["vt", "run", "ignore-input"], comment = "populate the cache" },
+  { argv = ["vtt", "write-file", "cache_like/other.txt", "after"], comment = "mutate the ignored directory — would invalidate if tracked" },
   { argv = ["vt", "run", "ignore-input"], comment = "cache hit: cache_like/ was ignored via ignoreInput" },
 ]
 
-# ignoreOutput: the task reads and writes sidecar/tmp.txt. If the runner
-# didn't honour ignoreOutput, the read-write overlap check would refuse to
-# cache the run ("read and wrote 'sidecar/tmp.txt'").
 [[e2e]]
 name = "ignore_output_allows_read_write_overlap"
+comment = """
+Exercises `ignoreOutput`. The task reads and writes `sidecar/tmp.txt`;
+without the ignore the runner's read-write overlap check would refuse to
+cache the run ("read and wrote 'sidecar/tmp.txt'").
+"""
 ignore = true
 steps = [
-  ["vt", "run", "ignore-output"],
-  ["vtt", "rm", "dist/out.txt"],
-  # Cache hit proves ignoreOutput suppressed the overlap error.
+  { argv = ["vt", "run", "ignore-output"], comment = "first run populates the cache" },
+  { argv = ["vtt", "rm", "dist/out.txt"], comment = "remove the real output so the cache-hit restore is observable" },
   { argv = ["vt", "run", "ignore-output"], comment = "cache hit: sidecar/ writes were ignored" },
-  ["vtt", "print-file", "dist/out.txt"],
+  { argv = ["vtt", "print-file", "dist/out.txt"], comment = "restored from the cache archive" },
 ]
 
-# disableCache: the tool asks the runner not to cache this run, so the next
-# invocation re-executes.
 [[e2e]]
 name = "disable_cache_forces_reexecution"
+comment = """
+Exercises `disableCache`. The tool asks the runner not to cache this run,
+so the next invocation re-executes instead of hitting a prior entry.
+"""
 ignore = true
 steps = [
-  ["vt", "run", "disable-cache"],
-  # Second run is a cache miss (NotFound) because nothing was cached.
-  { argv = ["vt", "run", "disable-cache"], comment = "cache miss: tool called disableCache" },
+  { argv = ["vt", "run", "disable-cache"], comment = "first run — tool calls disableCache" },
+  { argv = ["vt", "run", "disable-cache"], comment = "cache miss (NotFound) because nothing was cached" },
 ]
 
-# fetchEnv (tracked: true) — the env value becomes part of the post-run
-# fingerprint. Same value → cache hit; different value → cache miss.
 [[e2e]]
 name = "fetch_env_tracked_invalidates_on_change"
+comment = """
+Exercises `fetchEnv(name, { tracked: true })`. The env value becomes part
+of the post-run fingerprint: the same value still hits, a different value
+misses with `tracked env 'PROBE_ENV' changed`.
+"""
 ignore = true
 steps = [
-  { argv = ["vt", "run", "fetch-env"], envs = [["PROBE_ENV", "first"]] },
-  # Same value → cache hit.
+  { argv = ["vt", "run", "fetch-env"], envs = [["PROBE_ENV", "first"]], comment = "first run captures PROBE_ENV=first in the fingerprint" },
   { argv = ["vt", "run", "fetch-env"], envs = [["PROBE_ENV", "first"]], comment = "cache hit: PROBE_ENV unchanged" },
-  # Different value → cache miss (tracked env changed).
   { argv = ["vt", "run", "fetch-env"], envs = [["PROBE_ENV", "second"]], comment = "cache miss: tracked env changed" },
 ]

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/disable_cache_forces_reexecution.md

@@ -1,14 +1,19 @@
 # disable_cache_forces_reexecution
 
+Exercises `disableCache`. The tool asks the runner not to cache this run,
+so the next invocation re-executes instead of hitting a prior entry.
+
 ## `vt run disable-cache`
 
+first run — tool calls disableCache
+
 ```
 $ node scripts/disable_cache.mjs
 ```
 
 ## `vt run disable-cache`
 
-cache miss: tool called disableCache
+cache miss (NotFound) because nothing was cached
 
 ```
 $ node scripts/disable_cache.mjs

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_env_tracked_invalidates_on_change.md

@@ -1,7 +1,13 @@
 # fetch_env_tracked_invalidates_on_change
 
+Exercises `fetchEnv(name, { tracked: true })`. The env value becomes part
+of the post-run fingerprint: the same value still hits, a different value
+misses with `tracked env 'PROBE_ENV' changed`.
+
 ## `PROBE_ENV=first vt run fetch-env`
 
+first run captures PROBE_ENV=first in the fingerprint
+
 ```
 $ node scripts/fetch_env.mjs
 ```

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/ignore_input_keeps_cache_valid.md

@@ -1,13 +1,21 @@
 # ignore_input_keeps_cache_valid
 
+Exercises `ignoreInput` through `@voidzero-dev/vite-task-client`.
+The runner treats `cache_like/` as non-input, so mutations to it between
+runs do not invalidate the cache.
+
 ## `vt run ignore-input`
 
+populate the cache
+
 ```
 $ node scripts/ignore_input.mjs
 ```
 
 ## `vtt write-file cache_like/other.txt after`
 
+mutate the ignored directory — would invalidate if tracked
+
 ```
 ```
 

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/ignore_output_allows_read_write_overlap.md

@@ -1,13 +1,21 @@
 # ignore_output_allows_read_write_overlap
 
+Exercises `ignoreOutput`. The task reads and writes `sidecar/tmp.txt`;
+without the ignore the runner's read-write overlap check would refuse to
+cache the run ("read and wrote 'sidecar/tmp.txt'").
+
 ## `vt run ignore-output`
 
+first run populates the cache
+
 ```
 $ node scripts/ignore_output.mjs
 ```
 
 ## `vtt rm dist/out.txt`
 
+remove the real output so the cache-hit restore is observable
+
 ```
 ```
 
@@ -24,6 +32,8 @@ vt run: cache hit.
 
 ## `vtt print-file dist/out.txt`
 
+restored from the cache archive
+
 ```
 ok
 ```

crates/vite_task_bin/tests/e2e_snapshots/fixtures/vite_build_cache/snapshots.toml

@@ -1,41 +1,37 @@
-# Vite build end-to-end: `vt run --cache build` must produce a cache hit on
-# the second run without any manual input/output configuration. The patched
-# vite (see patches/vite.patch) reports ignoreInputs/ignoreOutputs on its
-# cacheDir/outDir so fspy-detected reads of `dist/` and writes to
-# `node_modules/.vite/` don't poison the cache.
-
 [[e2e]]
 name = "vite_build_caches_and_restores_outputs"
+comment = """
+`vt run --cache build` must produce a cache hit on the second run without
+any manual input/output configuration. Vite reports
+`ignoreInput(outDir)` + `ignoreInput/Output(cacheDir)` via
+`@voidzero-dev/vite-task-client`, so fspy-detected reads of `dist/` and
+writes to `node_modules/.vite/` don't poison the cache.
+"""
 ignore = true
 steps = [
-  ["vt", "run", "--cache", "build"],
-  # Verify the build emitted output (existence check; content is Vite's
-  # minified JS and would make the snapshot brittle across Vite versions).
-  ["vtt", "stat-file", "dist/assets/main.js"],
-  # Delete the output artefact and re-run — the cache hit should restore it.
-  ["vtt", "rm", "dist/assets/main.js"],
+  { argv = ["vt", "run", "--cache", "build"], comment = "first run: cache miss, emits dist/" },
+  { argv = ["vtt", "stat-file", "dist/assets/main.js"], comment = "existence check — content would drift across Vite versions" },
+  { argv = ["vtt", "rm", "dist/assets/main.js"], comment = "remove the artefact so the cache-hit restore is observable" },
   { argv = ["vt", "run", "--cache", "build"], comment = "cache hit: outputs restored without manual config" },
-  ["vtt", "stat-file", "dist/assets/main.js"],
+  { argv = ["vtt", "stat-file", "dist/assets/main.js"], comment = "restored from the cache archive" },
 ]
 
-# NODE_ENV is picked up by Vite via `fetchEnv("NODE_ENV", { tracked: true })`
-# in the patched `resolveConfig`. Flipping its value between runs must both
-# invalidate the cache AND change the build output — Vite's `define` plugin
-# substitutes `process.env.NODE_ENV` at build time, so dead-code elimination
-# leaves only the branch matching the current mode.
 [[e2e]]
 name = "node_env_change_invalidates_cache"
+comment = """
+NODE_ENV is picked up by Vite via `fetchEnv("NODE_ENV", { tracked: true })`
+in `resolveConfig`. Flipping its value between runs must both invalidate
+the cache AND change the build output — Vite's `define` plugin substitutes
+`process.env.NODE_ENV` at build time, so dead-code elimination leaves only
+the branch matching the current mode.
+"""
 ignore = true
 steps = [
-  { argv = ["vt", "run", "--cache", "build"], envs = [["NODE_ENV", "production"]] },
-  # Production build: only the PROD marker survives DCE.
-  ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_PROD"],
-  ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_DEV"],
-  # Same NODE_ENV — cache hit, output unchanged.
+  { argv = ["vt", "run", "--cache", "build"], envs = [["NODE_ENV", "production"]], comment = "first run: production build" },
+  { argv = ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_PROD"], comment = "production build: PROD marker survived DCE" },
+  { argv = ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_DEV"], comment = "dev branch is gone" },
   { argv = ["vt", "run", "--cache", "build"], envs = [["NODE_ENV", "production"]], comment = "cache hit: NODE_ENV unchanged" },
-  # Different NODE_ENV — cache miss via tracked env reported by Vite.
   { argv = ["vt", "run", "--cache", "build"], envs = [["NODE_ENV", "development"]], comment = "cache miss: Vite's fetchEnv marked NODE_ENV as tracked" },
-  # Development build: PROD marker gone, DEV marker in.
-  ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_PROD"],
-  ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_DEV"],
+  { argv = ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_PROD"], comment = "PROD marker gone after the dev rebuild" },
+  { argv = ["vtt", "grep-file", "dist/assets/main.js", "BUILD_MODE_DEV"], comment = "DEV marker now in the bundle" },
 ]

crates/vite_task_bin/tests/e2e_snapshots/fixtures/vite_build_cache/snapshots/node_env_change_invalidates_cache.md

@@ -1,19 +1,31 @@
 # node_env_change_invalidates_cache
 
+NODE_ENV is picked up by Vite via `fetchEnv("NODE_ENV", { tracked: true })`
+in `resolveConfig`. Flipping its value between runs must both invalidate
+the cache AND change the build output — Vite's `define` plugin substitutes
+`process.env.NODE_ENV` at build time, so dead-code elimination leaves only
+the branch matching the current mode.
+
 ## `NODE_ENV=production vt run --cache build`
 
+first run: production build
+
 ```
 $ vite build
 ```
 
 ## `vtt grep-file dist/assets/main.js BUILD_MODE_PROD`
 
+production build: PROD marker survived DCE
+
 ```
 dist/assets/main.js: found "BUILD_MODE_PROD"
 ```
 
 ## `vtt grep-file dist/assets/main.js BUILD_MODE_DEV`
 
+dev branch is gone
+
 ```
 dist/assets/main.js: missing "BUILD_MODE_DEV"
 ```
@@ -39,12 +51,16 @@ $ vite build ○ cache miss: tracked env 'NODE_ENV' changed, executing
 
 ## `vtt grep-file dist/assets/main.js BUILD_MODE_PROD`
 
+PROD marker gone after the dev rebuild
+
 ```
 dist/assets/main.js: missing "BUILD_MODE_PROD"
 ```
 
 ## `vtt grep-file dist/assets/main.js BUILD_MODE_DEV`
 
+DEV marker now in the bundle
+
 ```
 dist/assets/main.js: found "BUILD_MODE_DEV"
 ```

crates/vite_task_bin/tests/e2e_snapshots/fixtures/vite_build_cache/snapshots/vite_build_caches_and_restores_outputs.md

@@ -1,19 +1,31 @@
 # vite_build_caches_and_restores_outputs
 
+`vt run --cache build` must produce a cache hit on the second run without
+any manual input/output configuration. Vite reports
+`ignoreInput(outDir)` + `ignoreInput/Output(cacheDir)` via
+`@voidzero-dev/vite-task-client`, so fspy-detected reads of `dist/` and
+writes to `node_modules/.vite/` don't poison the cache.
+
 ## `vt run --cache build`
 
+first run: cache miss, emits dist/
+
 ```
 $ vite build
 ```
 
 ## `vtt stat-file dist/assets/main.js`
 
+existence check — content would drift across Vite versions
+
 ```
 dist/assets/main.js: exists
 ```
 
 ## `vtt rm dist/assets/main.js`
 
+remove the artefact so the cache-hit restore is observable
+
 ```
 ```
 
@@ -30,6 +42,8 @@ vt run: cache hit.
 
 ## `vtt stat-file dist/assets/main.js`
 
+restored from the cache archive
+
 ```
 dist/assets/main.js: exists
 ```