fix(cli): accept -d/--db on build to match every other DB-scoped command

[carlos-alm]

Summary

• codegraph build [dir] --db <path> was rejected with error: unknown option '--db', even though every other DB-scoped command (stats, query, where, watch, snapshot, …) honors it. The asymmetry blocked dogfooding workflows that need an isolated DB and surprised users who reasonably expected the flag to work on the most DB-scoped command.
• Adds -d, --db <path> to build, plumbs it through BuildGraphOpts.dbPath, and lets setupPipeline resolve it absolute (falling back to <rootDir>/.codegraph/graph.db). Mirrors watch's pattern from fix(watch): accept -d/--db to point at a graph.db outside cwd #987 verbatim.
• Native orchestrator path is unaffected — NativeDatabase.openReadWrite(ctx.dbPath) already drives the Rust side off the same ctx.dbPath, so the override flows through both engines.

Closes #1177.

Test plan

• npx vitest run tests/integration/build.test.ts — 21/21 pass, including 2 new tests in the buildGraph with custom dbPath (issue #1177) block (verifies DB lands at the custom path AND that <rootDir>/.codegraph/graph.db is NOT created).
• npx vitest run tests/integration/cli.test.ts — 29/29 pass.
• tsc --noEmit clean.
• End-to-end: codegraph build <dir> --db /tmp/custom.db writes there; --help shows the new flag with default annotation.

Notes

The change journal still writes to <rootDir>/.codegraph/journal.ndjson regardless of --db, matching watch's existing precedent — --db overrides the DB location only, not the project's .codegraph/ directory. If full isolation is needed for dogfooding workflows, that's a small follow-up (the journal path is computed independently in journal.rs and journal.ts).

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review Complete ✅

Root Cause Analysis

Problem Being Solved: Legitimate UX inconsistency where codegraph build was the only DB-scoped command that didn't accept the --db flag, breaking workflows that require isolated database paths for testing/dogfooding.

Why This Approach: Mirrors the exact pattern used by the watch command (#987), ensuring consistency across the CLI surface. The implementation reuses existing pipeline infrastructure in setupPipeline that already supports dbPath resolution.

Risk Assessment: Very low risk - purely additive change with comprehensive tests and no modification of existing behavior.

Backlog Compliance

• Zero-dep: ✓ — No new dependencies added
• Foundation-aligned: ✓ — Improves CLI consistency without violating any core principles
• Problem-fit: 4/5 — Directly addresses CLI UX friction that impacts developer workflows, though not core to the "AI agents getting lost" problem
• Breaking: No — Purely additive, all existing behavior preserved
• Tier: 1 (zero-dep ✓ + foundation-aligned ✓)

Code Quality Assessment

✅ Strengths:

• Pattern consistency - Exact match to watch command implementation (fix(watch): accept -d/--db to point at a graph.db outside cwd #987)
• Surgical precision - Only 4 files changed, minimal surface area
• Strong test coverage - Integration tests verify both positive case (custom DB created) and negative case (default not created)
• Type safety - Proper TypeScript interface extension in BuildGraphOpts
• Path handling - Correctly resolves relative paths to absolute
• Pipeline integration - Leverages existing setupPipeline infrastructure cleanly

✅ Architecture alignment:

• Follows the established CLI→options→pipeline→context flow
• Reuses ctx.opts.dbPath resolution logic already present
• No duplication of path handling logic
• Maintains separation between CLI parsing and business logic

✅ Testing quality:

• Integration-level tests cover the full CLI→buildGraph flow
• Tests verify both the positive case and absence of side effects
• Follows existing test patterns in the file
• Proper cleanup of temporary files including WAL/SHM sidecars

Critical Concerns

None. This is a well-executed, low-risk consistency fix.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: High-quality implementation of a legitimate UX fix. The change is minimal, well-tested, follows established patterns, and addresses a real developer pain point. The only reason for 4/5 instead of 5/5 is that this is a CLI consistency fix rather than a core feature advancement, but the execution is exemplary.

This PR should be merged. It resolves issue #1177 cleanly without introducing any technical debt or architectural concerns.

---

[greptile-apps]

Greptile Summary

Closes a UX gap where codegraph build --db <path> was rejected as an unknown option even though every other DB-scoped subcommand honors it. The fix is surgical: add -d, --db <path> to the build command definition, surface it through BuildGraphOpts.dbPath, and let setupPipeline respect the override when set.

• build.ts mirrors watch.ts verbatim: resolves the user-supplied path absolute before passing it as opts.dbPath.
• pipeline.ts/setupPipeline now prefers opts.dbPath over the <rootDir>/.codegraph/graph.db default; both the JS pipeline and the native Rust orchestrator (which already uses ctx.dbPath) benefit automatically.
• Two new integration tests verify the DB lands at the custom path and that the default location is left untouched.

Confidence Score: 5/5

Safe to merge — the change is minimal and confined to option plumbing with no side-effects on existing defaults.

The diff touches four files, all in straightforward ways: a new CLI flag, a one-field type extension, a two-line conditional in setupPipeline, and two integration tests. The default path is preserved exactly when --db is absent, so no existing workflow is affected. The native Rust orchestrator already consumed ctx.dbPath, so the override flows through both engines without any additional changes.

No files require special attention.

Important Files Changed

Filename	Overview
src/cli/commands/build.ts	Adds -d, --db <path> option; resolves it absolute before passing as dbPath — mirrors watch.ts exactly.
src/domain/graph/builder/pipeline.ts	setupPipeline now respects opts.dbPath; falls back to default when absent. Double-resolve is a no-op for CLI callers but correctly handles relative paths from programmatic callers.
src/types.ts	Adds optional dbPath?: string to BuildGraphOpts with clear JSDoc. No issues.
tests/integration/build.test.ts	Adds two integration tests covering custom DB path; follows existing test patterns, cleans up all sidecar files in afterAll.

_{Reviews (1): Last reviewed commit: "fix(cli): accept -d/--db on build to mat..." | Re-trigger Greptile}

[github-actions]

Codegraph Impact Analysis

3 functions changed → 6 callers affected across 5 files

• execute in src/cli/commands/build.ts:17 (0 transitive callers)
• setupPipeline in src/domain/graph/builder/pipeline.ts:168 (6 transitive callers)
• BuildGraphOpts.dbPath in src/types.ts:1080 (0 transitive callers)