v5: remove setup (WS7) + patch UI streamlining (WS8)

[Mikola Lysenko (mikolalysenko)]

Draft. Covers WS7, WS8, the "Remaining small follow-ups" in docs/design/v5-plan.md, and the review follow-ups in c4f3625.

WS7: remove setup

• Deleted the setup subcommand and everything only it used: core setup/**, the setup-only package_json helpers, commands/setup.rs, its tests and the setup-matrix suites, the setup-e2e feature, the setup-matrix CI job, tests/setup_matrix, scripts/setup-matrix.sh, and the setup-only gem Dockerfiles.
• vex's install-hook "Property 7" filter is gone. A manifest setup block still parses, but nothing reads it.
• The socket-patch-hook wheel and the socket-patch-bundler gem are no longer built or published (publish workflows, build-pypi-wheels.py, version-sync.sh), and the socket-patch[hook] extra is dropped.
  • Owner decision pending: their sources under pypi/socket-patch-hook/ and gem/socket-patch-bundler/ are kept, frozen, with a deprecation README. Deleting them and yanking the published packages is noted in the plan.
• The README's new "Upgrading from setup" section gives each ecosystem's hook to delete, plus how to move to hosted mode or keep agent mode. The CHANGELOG and the frozen package READMEs link to it.
• Follow-ups:
  • dropped the core crate's deprecated re-export aliases, and the CI grep that guarded them
  • dropped the unused tool_command
  • dropped the vacuous e2e_cargo/e2e_golang e2e rows
  • added the gem patches 01019627 and 9c2b4925 to GEM_PATCHES
  • retired the backtest-poetry "known crawler gap" label

WS8: patch UI streamlining

• Help: the root help groups commands by task:

  • patch: scan, get, list
  • undo: remove, rollback
  • ship: vex, vendor
  • agent mode: apply, repair

  The subcommand list and the README command reference follow the same order.

• Short help: -h lists about 8 options per command, including --json, --dry-run, --cwd, --ecosystems and --offline. --help is unchanged. scan --apply/--vendor are hidden but still accepted.

• Warning codes: human warnings drop the (code) tag (Warning: …, GC: skipped: …); the JSON keeps every code. Error lines keep Error (<code>) so --silent output stays grep-able.

• Wording: human text says "hosted" instead of "redirect", e.g. Switched N packages to hosted patches; rewrote M files.. JSON keys and codes are unchanged.

• npm allow-remote: the notice is one line; --verbose and --json keep the full text.

• Next steps: hosted and vendored runs share one numbered block from ui::next_steps.

• get prompts: hosted and vendored get never prompt. Like scan, they take the top-ranked patch, in JSON too, so there is no selection_required outside agent mode. Agent-mode get keeps its picker and confirmation.

• Empty list (BREAKING): a project with no manifest and no ledger record exits 0. It prints No patches in this project. Run \socket-patch scan`., or under --jsonthe success envelope withevents: []`. Only an unreadable or invalid manifest exits 1.

• Shared strings: one cancel line (Cancelled; no changes made.) and one paid-plan upsell line.

• Exit codes: get's own flag-conflict errors and rollback --one-off now exit 2 (previously 1), like every other usage error.

• Not done: one result type and json_envelope output for scan/get. I've proposed a separate workstream for it; see the review reply.

• Docs: CLI_CONTRACT has a new "Human output conventions" section plus updated exit-code and prompt rows. README, CHANGELOG and the plan status are updated.

Testing

• cargo clippy --workspace --all-targets --all-features -- -D warnings: clean.
• cargo test --workspace --all-features --no-fail-fast -j4: the only failures were ones this sandbox or the base branch explains:
  • Write-failure tests that make directories read-only with chmod. The sandbox runs as root, so the writes still succeed. I re-ran those targets as an unprivileged user and they pass.
  • The two e2e_redirect_cargo_build offline-vex cases, which also fail on the base branch (see the CI comment).
• CI failures that also occur on the base branch: e2e_redirect_cargo_build on every OS, and covgap_commands_scan_mod on Windows.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PQaKzoW5dSw9u5pgAAvVRj

[Mikola Lysenko (mikolalysenko)]

CI failure summary. Current commit: f200524.

Also failing on the base branch (release/v5-prerelease @ 8ae7dc3, CI run 36352437716), so not caused by this PR:

• e2e_redirect_cargo_build (test on all OSes, test-release, coverage). Two cases, cargo_hosted_fresh_checkout_fetch_pulls_patched_crate_and_vex_verifies and cargo_get_uuid_hosted_fresh_checkout_fetch, fail at step (3): vex --offline with the ledgers deleted exits 0, but the test expects exit 1 / record_unavailable. It reproduces locally on an untouched copy of the base branch. This is hosted-ledger/VEX code, which WS1 (ledger-free hosted mode) rewrites. No fix to port yet.
• covgap_commands_scan_mod on test (windows-latest). The base's Windows job fails on the same target. It passes on Linux and macOS.

Fixed in this PR:

• install-proof (vlt compatibility, every version) failed in vlt_pinned_matrix_agent_get_and_remove. The test ran plain get <uuid>, which now defaults to hosted. c3d4b38 adds --mode agent.
• coverage failed in covgap_commands_remove because two assertions still expected the old wording ("hosted redirect ledger" → "hosted ledger"). Fixed in f200524.

Likely flaky, to be re-run once:

• e2e_vlt on test (ubuntu-latest). It passes on macOS and locally, and its one test that doesn't need vlt installed has a 3.5 s timing check.
• native (macos-latest, 1.3.0) (bun compatibility). Only hosted legs fail, alongside two 180 s bun install timeouts. Every other bun job that finished passed, including Ubuntu on 1.3.0.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

v5 review at f200524f — removing install-hook setup is the largest concrete simplification in this stack. Keep that deletion and the explicit CI apply escape hatch.

A few interface changes would make this a simpler product, beyond hiding flags:

• Make an empty project a successful empty list. I built this head and checked both forms: human output says “No patches in this project” but exits 1; --json exits 1 with manifest_not_found. Absence of an agent manifest is normal for hosted v5. Return one consistent empty result in both renderers; reserve failure for unreadable/corrupt state. This is an intentional v5 contract improvement, not a claim that this PR introduced the old exit code.
• Fix the primary help's command grouping. It calls get and rollback “older agent-mode commands”, while get defaults to hosted and rollback is needed to undo hosted wiring. Describe the lifecycle by user intent, with agent-specific commands in their own group. Short help currently keeps --prune but hides --cwd, --ecosystems, and --offline; prioritize the hosted workflow's useful controls.
• Consolidate results before rendering. The deferred scan/get JSON-envelope work is worth doing in this major release: one typed operation result, one exit-status rule, human and JSON renderers. The current split preserves a large amount of branching and lets their stories drift.
• Make the removal actionable for existing users. Include a short upgrade recipe for existing npm/Composer scripts and installed Python/Bundler hooks, alongside the frozen-package notices. Keep explicit apply instructions for users retaining agent mode.

Validation: built this head; exercised root/scan help and empty list in human/JSON modes. I have not run the full compatibility matrix.

[Mikola Lysenko (mikolalysenko)]

Thanks for the review. c4f3625 makes three of the four changes. I've held back the fourth and propose a plan for it below.

• Empty list: a project with no manifest and no ledger record now exits 0. Human output prints No patches in this project. Run \socket-patch scan`., and --jsonprints the success envelope withevents: []. Only an unreadable or invalid manifest (manifest_unreadable/manifest_invalid`) still exits 1. CLI_CONTRACT, README and CHANGELOG are updated to match.

• Help: the root help now groups commands by what you're doing:

  • patch: scan, get, list
  • undo: remove, rollback
  • ship: vex, vendor
  • agent mode: apply, repair

  The subcommand list and the README command reference follow the same order, and the "older agent-mode commands" wording is gone. -h now shows --cwd, --ecosystems and --offline, and scan --prune moves to --help.

• Upgrade recipe: the README has a new "Upgrading from setup" section.

  • Step 1 is choosing a mode. To move to hosted, run rollback, then scan, then commit. To keep agent mode, run apply in CI after every install.
  • Step 2 lists the exact hook to delete for each ecosystem: the package.json postinstall/dependencies command, the Composer script entries, socket-patch[hook] plus pip uninstall socket-patch-hook, and the Bundler plugin block, directory and stamp.
  • The CHANGELOG and both frozen package READMEs link to it.

Not done: one result type for scan/get, with human and JSON renderers. I agree it belongs in v5, but I think it needs its own PR. scan and get build their JSON ad hoc in about 120 places across roughly 24k lines. About 1,350 test assertions read those shapes (redirect, patches, scannedPackages, errorCode, …), and many of them are in real-toolchain suites I can't run locally. The pipenv, poetry and pdm backtest scripts read those shapes too, and socket-cli and depscan probably do as well. Proposed plan:

1. One typed result. Add a single OperationResult for scan and get, with one exit-status rule. Render today's JSON and human output from it, byte-for-byte unchanged, so the existing tests prove nothing drifted.
2. Switch the JSON. Move scan and get onto json_envelope in one contract-breaking step. Update CLI_CONTRACT, the CHANGELOG and the backtest scripts in the same commit, and coordinate the socket-cli and depscan changes for the same release.

If you'd rather have it in this PR anyway, say so and I'll start on step 1 here.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Restack request from the v5 coordinator (please act now).

#280 (ledger-free hosted) is now merged into release/v5-prerelease as 686e5fb4. Please merge origin/release/v5-prerelease into this branch, resolve the conflicts, get CI to "base-inherited reds only", and mark the PR ready for review (not draft) when done.

• Resolve toward v5 WS1+WS2: ledger-free hosted mode, upstream-restore rollback, vendor ejects hosted projects #280's model. There is no hosted ledger any more: rollback/remove/vendor restore upstream via patch::redirect::upstream. Don't reintroduce redirect-state.json writes or fragment-replay paths. Keep this PR's own intent on top.
• Landing order: WS5: one VendoredBackend for vendored apply/revert/repair; cut repair's ledger rebuild #283 → WS3: one lockfile model per ecosystem #281 → v5: remove setup (WS7) + patch UI streamlining (WS8) #279 → v5 WS4/WS6: one hosted engine for disk + memory; unified Ledgers view #282, then the design PRs (docs: v5 waste review + repacking-to-depscan design #286 docs, NuGet vendoring v2: design + opt-in unique-version fallback layout prototype #285/Vendored Maven and Gradle: design and prototype #287). After each one lands, the next ones merge the base again. Expect a small second round of conflicts.
• Base-inherited reds that aren't yours to fix: vlt install-proof (vlt_pinned_matrix_agent_get_and_remove; fixed on v5: remove setup (WS7) + patch UI streamlining (WS8) #279) and Windows covgap_commands_scan_mod.
• The repo only allows squash merges. Post a comment with your final head SHA and CI summary when you're ready.

[Mikola Lysenko (mikolalysenko)]

Owner decision (via coordinator): land this PR without the shared scan/get result type. Do that as a follow-up PR against release/v5-prerelease once the stack has landed. Priority now: merge the base (#280), resolve conflicts, get green, and mark ready.