Implement orbit-graph-cli crate with seven subcommands

[danieljhkim]

Task

ORB-00318 — Implement orbit-graph-cli crate with seven subcommands

Description

Problem

GRAPH_SPEC.md §9 defines seven user-facing commands: sync, search, show, refs, callees, impact, trace. After Phase 4 lands the Graph API methods, this task wraps them in a CLI binary orbit-graph-cli exposing orbit graph <cmd> subcommands per 2_design.md §1. The CLI does no semantic work — only argument parsing, Graph::open, method dispatch, JSON serialization, and error mapping.

Why It Matters

This is the first reachable surface for orbit-graph. Without it, the Graph API only runs from Rust callers. Landing the CLI enables manual smoke testing on real worktrees, lets the equivalence harness (ORB-00297) drive v2 outputs side-by-side with v1, and unlocks broader integration with the orbit ecosystem (orbit binary subcommand wiring, skills that shell out, etc.).

Constraints / Notes

• Crate path: crates/orbit-graph-cli/ per GRAPH_SPEC.md §5. Add to workspace Cargo.toml members.
• Use the workspace clap dep with the derive feature (matches other CLI crates in the workspace).
• CLI surface: each subcommand maps 1:1 to a Graph method. Subcommand list per GRAPH_SPEC.md §9 (seven query commands) plus three admin commands from §3 (version, db-path, clean) — these admin commands are not counted against the seven-command query surface but they belong in the same binary.
• Default SyncPolicy for the CLI: Manual per GRAPH_SPEC.md §8.3. CLI users are explicit — sync is its own subcommand.
• Output: JSON to stdout via serde-json. No human-readable formatting in this task — the orbit binary handles pretty-printing one layer up if needed.
• Errors: typed at the crate boundary per docs/design-patterns/error_translation.md; mapped to non-zero exit codes at main(); JSON error payloads to stderr for machine consumers.
• Diagnostic logging via tracing per CLAUDE.md — no eprint! / println! calls. The workspace tracing-subscriber init pattern from other CLI crates applies.
• The CLI must NOT depend on orbit-knowledge. Only orbit-graph + orbit-graph-extract + workspace deps.
• No MCP code in this task — that is P5.2.
• Sibling test layout per docs/design-patterns/test_layout.md. Subprocess-driven integration tests via assert_cmd over a temp-dir worktree are appropriate.

Plan ID: P5.1. Depends on all five Phase 4 tasks: ORB-00313 (search + show), ORB-00315 (refs), ORB-00314 (callees), ORB-00316 (impact), ORB-00317 (trace). Gates P5.2 (MCP wrappers) and Phase 6 harness wiring.

Acceptance Criteria

• crates/orbit-graph-cli/Cargo.toml exists with [lints] workspace = true, declares dependencies on orbit-graph and orbit-graph-extract, declares clap with the derive feature
• Workspace root Cargo.toml [workspace] members lists crates/orbit-graph-cli
• src/main.rs entry point; src/commands/ subdirectory contains one file per subcommand
• Seven query subcommands implemented per GRAPH_SPEC.md §9: sync (with --full flag), search (with --kind, --lang, --limit flags), show (with --max-bytes flag), refs (with --confidence and --kind flags), callees, impact (with --depth flag), trace (with --depth flag)
• Three admin subcommands implemented per GRAPH_SPEC.md §3: version (prints crate version + EXTRACTOR_VERSION), db-path (prints the resolved DB path for the current worktree + branch), clean (deletes old extractor-version DB files in .orbit/graph/)
• CLI passes SyncPolicy::Manual to Graph::open — CLI users are explicit per GRAPH_SPEC.md §8.3
• All command output is JSON written to stdout via serde-json; output field shapes match the JSON contracts in GRAPH_SPEC.md §9
• Errors map to non-zero exit codes; error payloads written to stderr as JSON; diagnostic logging uses tracing per CLAUDE.md (no eprint! / println! calls)
• No dependency on crates/orbit-knowledge — verified with cargo tree -p orbit-graph-cli not showing orbit-knowledge
• Integration tests under crates/orbit-graph-cli/tests/ create a temp worktree with a small rust fixture, run each subcommand via assert_cmd or equivalent, and assert the output JSON shape
• cargo build -p orbit-graph-cli succeeds
• cargo test -p orbit-graph-cli passes
• cargo clippy -p orbit-graph-cli -- -D warnings passes under workspace lint config

Execution Summary

Click to expand

Outcome: success

Changes:

• Added the orbit-graph-cli workspace crate with JSON stdout/stderr handling, tracing initialization, and one command module per sync/search/show/refs/callees/impact/trace/version/db-path/clean subcommand.
• Wired all graph commands through Graph::open(..., SyncPolicy::Manual) and serialized API results to the GRAPH_SPEC-shaped JSON surfaces.
• Added graph support for exposing the resolved DB path, serializing callee edges, and cleaning old extractor-version DB files.
• Updated workspace membership, dependency-direction/stability architecture metadata, and moved shared test dependencies to workspace-managed declarations.
• Added assert_cmd integration tests that build a temp git worktree, sync a Rust fixture, exercise every subcommand, and assert JSON output/error shape.

Assessment: The crate builds, tests, and passes clippy under workspace lints; cargo tree -p orbit-graph-cli --edges all has no orbit-knowledge dependency.

Validation

• Not reported

Branch Freshness

• Base ref: origin/agent-main
• Head ref: orbit/ORB-00318-6a13d535
• Behind base: 0
• Ahead of base: 1