Print one JSON envelope from every command (v5.0)

[Mikola Lysenko (mikolalysenko)]

Every command's --json output now uses the one envelope shape for v5.0. scan, get and rollback were the last commands printing their own pre-v3 shapes. This finishes the migration that CLI_CONTRACT.md listed as pending. This is a breaking change on purpose (v5.0, MAJOR).

Stacked on #1273 (one GC shape and rollback counters); merge that first.

Closes #931. Closes #1062.

What every command now prints

• command, status, dryRun, events, summary, warnings, plus error: {code, message} on failure, and gc when a sweep ran.
• status comes from one camelCase set: success, partialFailure, error, noManifest, paidRequired, notFound, notInstalled, noMatch, noPackages, selectionRequired. No snake_case statuses or actions remain.
• Every per-package outcome is an event, recorded so that summary always equals the event counts. New action: rolledBack.
• Events from the vendored and hosted legs carry details.mode: "vendored" | "hosted", the convention list already used.
• Warnings are always top-level {code, detail}. There are no string warnings and no nested *.warnings arrays.
• Usage, lock and early errors also print a full envelope.
• Each command's own data stays as top-level keys beside the shared ones, through Envelope::extra. Examples: scan's packages, rollout, policy and redirectState; rollback's paths and hosted.editedFiles.

Per command

• rollback: rolledBack, alreadyOriginal, failed, results[], vendored*, manifest and hosted.{reverted,failed,unsupported} became events:

  • a restored copy is rolledBack
  • an already-original copy is skipped already_original
  • a not-installed package is skipped package_not_installed
  • a failure is failed with a specific code (hash_mismatch, vendor_revert_kept, hosted_restore_refused, …)
  • a removed manifest entry is removed with details.manifest: true
  • a dry run reports its previews as verified

  gc: {skipped: true} became an absent gc plus a gc_skipped warning. Exit codes are unchanged.

• scan / get:

  • apply.patches, download, the nested vendor envelope and redirect.patches all merged into events.
  • The count keys (found, totalPatches, redirected, …) are replaced by summary.
  • would_add/would_pin/would_vendor became verified. already_vendored and dry-run refusals became skipped with a code.
  • options[].published_at became publishedAt.
  • Removed --prune manifest entries are removed events, and the sweep is the envelope's gc.

• Corrupt manifest (An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931): one mapping, manifest_load_error, on every command. An unparseable manifest is manifest_invalid; an unreadable one is manifest_unreadable. This replaces apply_failed, repair_failed, the undocumented invalid_manifest, and the manifest_unreadable that apply --check / vendor --check / vex / get / rollback used for an unparseable file. Agent-mode scan now fails on an unloadable manifest. The other scan modes add a warning with the same code.

• remove:

  • The GC event's details are {count, checked}, matching repair's.
  • Each restored installed copy is its own rolledBack event (it was details.rolledBack).
  • Sweep failures appear as cleanup_failed warnings.

• Sidecars: SidecarFileAction / SidecarSeverity serialize camelCase. Every value is one word, so the output bytes don't change.

Bugs fixed on the way

• scan --mode agent --json printed two JSON documents when the lock was held or the manifest was unreadable. The download engine now only records into the caller's envelope and never prints.

• scan exits 1 in human output but 0 with --json when every patch query returns nothing #1062: human and --json scan now share each decision, so they agree:

  • A successful but empty patch-detail answer exits 0 in both.
  • Report-only --json fetches details under the same rule as human.
  • Hosted --json --prune respects the socket.yml write gate.
  • Human vendored --dry-run --prune previews the GC like --json does.

  The logic from Fix scan human/JSON exit and prune forks (#1062) #1298 and Fix human vendored --prune skipping GC (#1127) #1338 is included here, so whichever lands second needs a mechanical rebase.

Contract

• The CLI_CONTRACT.md envelope, event, action matrix, error-code tables, rollback contract, scan/get JSON section and jq recipes all describe the new shape.
• "Migration status" now lists every command as ✅.
• The legacy helpers (legacy_error, set_error, is_legacy_shape, …) are deleted.

Tests

• cargo test -p socket-patch-cli -p socket-patch-core --tests --lib --no-fail-fast (local, macOS arm64): 13,307 passed, 2 failed. The 2 failures are e2e_vendor_cargo_build cases that need x86 cargo toolchains, which don't run on this machine ("Bad CPU type"). They are unrelated to this change.
• New tests:
  • envelope invariants for scan/get/rollback (command present, status from the enum, summary equal to the event counts, error paths print a full envelope)
  • a manifest-load error matrix over 8 commands, with corrupt and unreadable fixtures
  • scan exits 1 in human output but 0 with --json when every patch query returns nothing #1062 parity: 4 modes × wet/dry × human/JSON exit codes
  • a single JSON document when the lock is held
• E2E suites gated on toolchains or production were updated by reading them and still need CI: e2e_scan, e2e_npm, e2e_redirect_*_build, e2e_vendored_production, e2e_vex_*, e2e_bun_lockb, e2e_hosted_production, and others.
• cargo clippy --locked --workspace --all-features -- -D warnings and cargo fmt --all -- --check are clean.
• CHANGELOG.md is untouched, per AGENTS.md.

🤖 Generated with Claude Code

---

Note

High Risk
Breaking v5.0 JSON contract for automation consuming CLI output, plus broad changes to get/scan/apply error and manifest paths that affect exit codes and failure reporting.

Overview
Completes the v5.0 breaking migration so every command emits a single shared JSON envelope (command, status, events, summary, structured warnings, optional error) instead of legacy per-command shapes. get, scan, and rollback paths now record PatchEvent outcomes (e.g. downloaded, applied, failed, skipped) and derive counts from summary; the agent download engine writes into a caller-owned Envelope and no longer prints JSON itself (fixes double-document output on lock/manifest errors).

Manifest handling is unified via manifest_load_error (manifest_invalid vs manifest_unreadable) across apply, get, vendor, list, and related flows, replacing ad hoc codes like apply_failed for bad manifests. Nested apply failures fold through record_apply_outcome instead of mutating patches[] JSON.

CI switches Rust installs from rustup show to scripts/rustup-retry.sh toolchain install (retries download blips; explicit install). vlt-compatibility adds a changes gate (vlt-compat-gate.py) to skip the heavy matrix when only unrelated ci.yml edits triggered the workflow. Bun lockb e2e adds a matrix filter for binary_shared_bundled_record_hosted_pin_is_managed.

^{Reviewed by Cursor Bugbot for commit 48c63c6. Configure here.}