fix(watch): accept -d/--db to point at a graph.db outside cwd

[carlos-alm]

Summary

Every other command that operates on a graph DB (build, stats, query, fn-impact, impact, diff-impact, export, embed, search, triage, complexity, audit, roles, cycles, map, plot, co-change, owners, batch, check, children) accepts -d, --db <path>. watch did not — it rejected the flag with error: unknown option '--db', forcing users in monorepo and multi-repo MCP setups to cd into the watched directory.

Add the option, plumb it through watchProject → setupWatcher, and fall back to <rootDir>/.codegraph/graph.db when it's absent.

Found during

Dogfooding v3.9.4 — see #984

Test plan

• codegraph watch --help shows -d, --db <path>
• codegraph watch <dir> --db <path> runs against the specified DB from a different cwd
• codegraph watch <dir> --db /missing.db errors cleanly with No graph.db found. Run \codegraph build` first.`
• codegraph watch <dir> (no --db) behaves exactly as before (default .codegraph/graph.db under the watched dir)
• npm run typecheck clean
• npm run lint clean

[claude]

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

---

PR Review: Add --db flag to watch command

Todo List:

• Read changed files to understand implementation
• Perform root cause analysis
• Check for configuration changes and test integrity
• Assess code quality and security
• Evaluate backlog compliance
• Provide final rating and recommendation

Root Cause Analysis

Problem Being Solved: The watch command was the only command lacking the -d, --db <path> flag that all other 23 commands support. This forced users in monorepo/multi-repo setups to cd into watched directories instead of pointing to external DB files.
Why This Approach: Simple flag addition with consistent parameter passing pattern matching other commands - minimal, surgical fix.
Risk Assessment: Very low risk - purely additive change with established patterns.

Configuration & Test Integrity Check

✅ No configuration changes - No linting rules, test timeouts, or build configs modified
✅ No test weakening - No test files changed or assertions removed
✅ No eslint-disable - No suppression comments added
✅ Small focused PR - Only 2 files, 8 line changes, single concern

Code Quality & Security Assessment

✅ Follows established patterns - Identical to 23 other commands using opts.db → dbPath parameter
✅ Proper path resolution - path.resolve(opts.db) handles relative paths correctly (line 26)
✅ Safe error handling - DbError thrown with clear message when DB missing (line 171)
✅ No security risks - Path resolution is standard, no command injection
✅ Clean implementation -

• src/cli/commands/watch.ts:9,26 adds flag and passes to watchProject
• src/domain/graph/watcher.ts:168,169 accepts and uses dbPath with fallback

Minor observation: The implementation correctly defaults to <rootDir>/.codegraph/graph.db when --db is omitted, maintaining backward compatibility.

Backlog Compliance

• Zero-dep: ✓ — No new dependencies, uses existing path and filesystem APIs
• Foundation-aligned: ✓ — Fully compliant, improves CLI consistency without violating any principles
• Problem-fit: 4 — Improves agent usability by eliminating cd requirement in multi-repo setups, reducing friction for AI agents navigating codebases
• Breaking: No — Purely additive, existing behavior unchanged when flag omitted
• Tier: 1 (zero-dep ✓ + foundation-aligned ✓)

Critical Concerns

None. This is a textbook example of a well-executed consistency fix.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: Clean, minimal implementation that fills an obvious consistency gap. The PR author properly tested all scenarios including error cases. No risk of regression, follows established patterns perfectly.

Only minor deduction: This is maintenance work rather than innovation, hence 4/5 instead of 5/5.

[greptile-apps]

Greptile Summary

This PR adds the missing -d, --db <path> flag to the watch command, bringing it in line with every other DB-consuming command in the CLI. The implementation is minimal and correct: path.resolve normalises the user-supplied path at the CLI boundary, ?? provides the existing default fallback inside setupWatcher, and the watchProject signature is extended with a matching optional field.

Confidence Score: 5/5

Safe to merge — change is minimal, isolated, and behaviorally backward-compatible.

No logic errors, no security concerns, and no regressions. All four test plan scenarios map correctly to the implementation. Only P2-level observations (journal/change-event writes always use rootDir, not the DB parent directory — expected and documented behaviour for the watcher).

No files require special attention.

Important Files Changed

Filename	Overview
src/cli/commands/watch.ts	Adds -d, --db <path> option; resolves to absolute path and passes as dbPath to watchProject
src/domain/graph/watcher.ts	Accepts optional dbPath in setupWatcher and watchProject opts; falls back to <rootDir>/.codegraph/graph.db via nullish coalescing

Sequence Diagram

sequenceDiagram
    participant CLI as watch.ts (CLI)
    participant WP as watchProject()
    participant SW as setupWatcher()
    participant FS as fs / SQLite

    CLI->>CLI: path.resolve(opts.db) → dbPath (or undefined)
    CLI->>WP: watchProject(rootDir, { ..., dbPath })
    WP->>SW: setupWatcher(rootDir, { engine, dbPath })
    SW->>SW: dbPath ?? path.join(rootDir, '.codegraph/graph.db')
    SW->>FS: fs.existsSync(dbPath)
    alt DB missing
        FS-->>SW: false
        SW-->>CLI: throw DbError
    else DB found
        FS-->>SW: true
        SW->>FS: openDb(dbPath)
        SW-->>WP: WatcherContext
    end
    WP->>WP: startPollingWatcher / startNativeWatcher (rootDir)

Loading

_{Reviews (1): Last reviewed commit: "fix(watch): accept -d/--db to point at a..." | Re-trigger Greptile}

[github-actions]

Codegraph Impact Analysis

3 functions changed → 2 callers affected across 2 files

• execute in src/cli/commands/watch.ts:14 (0 transitive callers)
• setupWatcher in src/domain/graph/watcher.ts:168 (2 transitive callers)
• watchProject in src/domain/graph/watcher.ts:298 (1 transitive callers)