vcli-cli: user-facing CLI over framed-JSON IPC (plan 5)

[blaksmatic]

Summary

Ships the user-facing vcli binary — a thin client over the framed-JSON IPC protocol that speaks to the vcli-daemon (#10). Every v0 command supports --json; exit codes match spec §589 exactly (0 success, 1 generic, 2 validation, 3 not found, 4 daemon not running).

Architecture

• Depends on vcli-ipc (transport), vcli-dsl (local preflight on submit), vcli-core (ids, state, errors, events).
• #![forbid(unsafe_code)] at crate root. Daemon-spawn path uses CommandExt::process_group(0) and CommandExt::exec(), both safe stable Rust.
• clap derive gives us structured parsing and auto-generated --help.
• Output layer: a format module with Pretty/Json backends so every command gets both for free.
• run() returns i32; main.rs is a three-liner.
• Local preflight via vcli_dsl::validate_value on submit is a UX optimization (Decision F4); the daemon still re-validates authoritatively.

Commands

submit, list, cancel, logs, resume, daemon {start|run|stop|status}, health, gc.

What's in this PR

20 plan tasks across 21 commits, per docs/superpowers/plans/2026-04-17-vcli-cli.md. Highlights:

• CliError + ExitCode mapping (spec §589)
• clap derive Cli/Command skeleton for every v0 command
• util — socket resolution, file read, ISO-8601 formatter (Howard Hinnant civil_from_days)
• client::connect maps ENOENT/ECONNREFUSED → DaemonDown
• format — Table + render_value
• Every command implementation with per-command tests
• daemon start detaches via process_group(0); daemon run execs for launchd/systemd
• lib::run dispatcher wiring every Command to its handler
• Integration tests: argv parse coverage, full e2e against FakeHandler, binary-level smoke tests via assert_cmd

Stacking

This PR is built on top of #10 (plan-4 vcli-daemon). It targets master — the diff will narrow to only vcli-cli commits once #10 merges. Please review/merge #10 first.

Test Plan

• cargo test --workspace --locked green on macOS (574 tests)
• cargo clippy --workspace --all-targets -- -D warnings clean
• cargo fmt --all -- --check clean
• #![forbid(unsafe_code)] at crate root
• Reviewer: pull and run the gate locally

🤖 Generated with Claude Code