[wan9chi]

Motivation

Coding agents and CI need a dry run's answer as data, without parsing text: which tasks would run, in what order, and why each would hit or miss (#791, voidzero-dev/vite-plus#2848). The dry-run RFC specifies the run plan that vp run --dry-run --json prints, and this PR implements it through a new reporter. For now, a task whose command runs vp run fails and says so; #967 adds nested plans.

Changes

// vp run --dry-run --json build, after a.txt changed (indented in a terminal, one line when captured)
{
  "$schema": "file:///tmp/vp_run-1000/run-plan_<hash>.json",
  "version": 1,
  "workspaceRoot": "/…",
  "plan": {
    "build": {
      "package": ".",
      "name": "build",
      "steps": [{
        "program": "node_modules/.bin/vtt",
        "args": ["print-file", "a.txt", "b.txt"],
        "cache": {
          "status": "changed",
          "baseline": { "durationMs": 12 },
          "changes": [{ "kind": "file", "path": "a.txt", "change": "changed" }],
          "changesPartial": true
        }
      }]
    }
  }
}

• CLI. --json is no longer exclusive. It conflicts with an explicit --log, and RunCommand::resolve checks the rest once, with clap-style errors. --json alone resolves to the task graph, and with --dry-run to a run whose RunMode is DryJson. With a task but no --dry-run, the error says --json is only supported with --dry-run for now. With other flags and no task, it's the same conflict error as before. Without a task, --dry-run --json fails when it's planned, as --dry-run does. The session matches on that, so nothing re-checks --json later, and plan_from_cli_run resolves its command the same way. It's never interactive: a task that isn't found is an error on stderr, not the task list on stdout. An empty plan, such as when --filter matches nothing, prints "plan": {}.
• Cache data. Comparison gains the baseline's duration and changes_partial. changes_partial is set when the file check stopped at the first changed file, or couldn't check some files. After a command, config or env change, only the previous run's key is compared, so the step is changed with its key changes, changesPartial, and no baseline; the RFC's baseline is optional for that case. Program, args and cwd changes keep what they changed from and to. vt_plan gets a program accessor on the spawn fingerprint, and name and args accessors on built-ins.
• Reporter (session/reporter/json/).
  • When it's created, it lays out from the graph each task's ID, its sorted dependsOn, and its steps (program, args, cwd, hook).
  • Each leaf's start fills in its cache: hit, changed, noBaseline, error or disabled, or absent for a built-in.
  • At the end, it serializes the whole document and writes it once.
  • A run cancelled with Ctrl-C prints nothing. A failed cache lookup stops the run, as it stops a real run. As with any error that stops the document, the error goes to stderr and nothing is printed.
• Document. Rust types with doc comments, deriving schemars under cfg(test). A test regenerates the committed schemas/run-plan.json. artifact! embeds it, and each run copies it to the user's temp folder for $schema, as for vp run --json. Both documents are written by one json::write_document, which serializes into memory first, so an error partway prints nothing.
• Tests.
  • run_plan_json covers the plan's layout: -r edges and --parallel, hooks, programs inside and outside the workspace, --no-cache and --cache, forwarded args, the shell, cd and the cwd setting, built-ins, and encoded task IDs.
  • Its selection case covers which tasks are planned: a task that some or all selected packages lack, an unknown package, and a filter that matches nothing, with and without --fail-if-no-match.
  • dry_run_json covers the cache statuses and flags that combine with --dry-run --json, or that are passed to the task when they come after its name.
  • Its errors case covers --json with a task but no --dry-run, with --log, with --last-details, or with flags but no task; --dry-run --json without a task; and a task that isn't found.
  • In the plan snapshots, only the expected --json build error message changes.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches CLI parsing, session dispatch, and cache comparison shapes used by dry runs and reporters; behavior is well snapshot-tested but flag combinations and cache edge cases warrant review.

Overview
Adds vp run --dry-run --json, which emits a single run-plan JSON document (tasks, dependsOn, per-step program/args/cwd/hook, and projected cache status) for CI and agents, with a committed schemas/run-plan.json and $schema materialized like the task graph.

CLI: --json is no longer exclusive-only; with a task it requires --dry-run (otherwise a clap-style error). Bare vp run --json still dumps the task graph. Resolution flows through RunCommand::resolve / RunMode::DryJson, and --json conflicts with --log.

Cache / JSON payload: Comparison and Change now carry baseline duration, changesPartial, and from/to details for program, args, and cwd so misses serialize faithfully; validation returns Checked with partial file lists.

Execution path: A new JSON reporter lays out the graph up front, fills cache on each dry leaf start, writes once at the end (or stderr-only on lookup failure / cancel / nested vp run, which is rejected). Shared json::write_document and schema snapshot tests cover both JSON outputs.

Tests / docs: E2E fixtures for plan layout, cache statuses, flags, and errors; dry-run RFC examples updated for optional baseline and changesPartial.

^{Reviewed by Cursor Bugbot for commit 220dbb0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

fspy benchmark

linux

dynamic/launch             change  +1.79%  [ -5.66% ..  +8.99%]  overhead   +63.29%
dynamic/access             change  +0.81%  [ -4.09% ..  +6.80%]  overhead   +19.49%
dynamic/access-relative    change  -1.20%  [ -8.19% ..  +2.09%]  overhead   +69.37%
dynamic/access-contended   change  -2.10%  [-10.15% .. +12.06%]  overhead    +9.54%
static/launch              change  -0.62%  [ -8.29% ..  +4.86%]  overhead  +201.49%
static/access              change  -0.45%  [-11.09% ..  +5.65%]  overhead +1424.27%
static/access-relative     change  +0.17%  [ -4.89% ..  +8.22%]  overhead +1792.88%
static/access-contended    change  -0.08%  [ -7.77% ..  +6.84%]  overhead +1157.70%

macos

dynamic/launch             change  +0.90%  [ -3.79% ..  +4.78%]  overhead  +259.90%
dynamic/access             change  +0.00%  [ -5.67% ..  +8.03%]  overhead    +0.70%
dynamic/access-relative    change  +1.07%  [ -8.23% .. +110.74%]  overhead  +248.49%
dynamic/access-contended   change  +1.72%  [ -8.47% .. +302.93%]  overhead    +0.83%

windows

dynamic/launch             change  +1.07%  [ -6.31% ..  +7.65%]  overhead   +26.04%
dynamic/access             change  -0.18%  [-15.57% .. +17.51%]  overhead    +2.09%
dynamic/access-relative    change  -0.30%  [-14.87% .. +16.52%]  overhead    +3.86%
dynamic/access-contended   change  +0.28%  [-11.03% .. +16.94%]  overhead    +3.30%

[cursor]

Stale Bugbot comment from a previous run.

[wan9chi]

Why not directly write into a bufwriter?

[wan9chi]

To keep stdout empty when serializing fails. A BufWriter writes out what it holds whenever its buffer fills, and again when it's dropped. So an error partway through, such as a workspace root that isn't valid UTF-8 (workspaceRoot serializes through Path, which rejects that), would leave half a document on stdout. Serializing into a Vec first means stdout is either the whole document or nothing. It's held in memory once more, but the document is small. The doc comment now gives this reason (744608b).

🤖 Generated with Claude Code

[wan9chi]

This error message is confusing. We should mention that --json is only supported with --dry-run right now.

[wan9chi]

Changed in 744608b. vp run --json build now says:

error: with a task, '--json' is only supported with '--dry-run' for now

vp run --dry-run --json without a task used to get the same conflict message, although the two flags go together. It now fails like vp run --dry-run does: No task specifier provided for 'run' command. vp run --json -r keeps clap's message, which is accurate there because the task graph takes no other argument. errors.md now covers all three, plus --json --last-details.

🤖 Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 744608b. Configure here.}