fix(cli): graceful error for cycles, export, embed when no graph.db exists

[carlos-alm]

Summary

• codegraph cycles, codegraph export, and codegraph embed crashed with a better-sqlite3 stack trace when run without a graph.db
• Fixed by using openReadonlyOrFail() in cli.js and adding fs.existsSync() guard in embedder.js
• Also exports ./package.json in the package exports map so require('@optave/codegraph/package.json') works

Found during

Dogfooding v2.2.3-dev.44e8146 — see #77 and #78

Test plan

• codegraph cycles without graph → graceful error message
• codegraph export without graph → graceful error message
• codegraph embed without graph → graceful error message
• All three commands work normally with a graph
• npm test passes (29/29 test files, 476/476 tests)
• npm run lint passes (0 warnings)

[greptile-apps]

Greptile Summary

Fixed crashes in codegraph cycles, codegraph export, and codegraph embed commands when no graph.db exists by adding graceful error handling.

• Replaced manual Database instantiation with openReadonlyOrFail() helper in cycles and export commands
• Added fs.existsSync() guard in buildEmbeddings() before opening database
• Added ./package.json to package exports map for programmatic access
• All three commands now display clear error message directing users to run codegraph build first
• Error handling is consistent across commands: search already used openReadonlyOrFail() via _prepareSearch()

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Straightforward bug fix that adds error handling without changing logic. All tests pass (476/476), lint passes, and test plan verified all three commands work both with and without graph.db. Changes are minimal, focused, and follow existing patterns from the codebase (openReadonlyOrFail() is already used elsewhere).
• No files require special attention

Important Files Changed

Filename	Overview
package.json	added ./package.json export to enable require('@optave/codegraph/package.json')
src/cli.js	replaced manual database opening with openReadonlyOrFail() in export and cycles commands for consistent error handling
src/embedder.js	added fs.existsSync() check in buildEmbeddings() to prevent better-sqlite3 crash when graph.db is missing

_{Last reviewed commit: 1d822e7}

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[claude]

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

---

PR Review: Graceful Error Handling for Missing graph.db

Todo List:

• Read and analyze changed files
• Perform root cause analysis
• Check for configuration changes and test integrity
• Evaluate code quality and approach
• Provide comprehensive review feedback

Root Cause Analysis

Problem Being Solved: The codegraph cycles, codegraph export, and codegraph embed commands were crashing with raw better-sqlite3 stack traces when run without an existing graph.db file, instead of providing helpful error messages.

Why This Approach: The fix standardizes error handling across CLI commands by:

1. Using the existing openReadonlyOrFail() helper that provides user-friendly errors
2. Adding explicit fs.existsSync() guard in buildEmbeddings() (which creates a writable DB)
3. Following established patterns already used by other commands like search

Risk Assessment: Very Low Risk - This is a pure defensive fix that only adds error checking without changing core logic.

Critical Concerns

None found. This is a straightforward, well-implemented bug fix that:

✅ Fixes real crashes - Prevents better-sqlite3 stack traces when DB is missing
✅ Follows existing patterns - Uses openReadonlyOrFail() consistently like other commands
✅ No configuration relaxation - Zero lint rule changes or test weakening
✅ Proper error messages - Clear user guidance to run codegraph build first
✅ Minimal scope - Only touches error handling paths, no logic changes

Code Quality Assessment

Excellent implementation:

1. cli.js:277,316 - Perfect use of openReadonlyOrFail() instead of manual Database construction. This helper already exists at db.js:136 and provides the exact same error message and process.exit(1) behavior.

2. embedder.js:327-333 - Proper fs.existsSync() guard before opening DB. The error message matches the pattern used in openReadonlyOrFail(), ensuring consistent UX.

3. package.json:11 - Adding ./package.json export is a minor improvement that enables programmatic access via require('@optave/codegraph/package.json').

Technical correctness:

• Error handling follows established patterns (openReadonlyOrFail used 16x in codebase)
• Consistent error messages across all three commands
• Proper process.exit(1) for CLI failure scenarios
• No SQL injection, security, or performance concerns

Test coverage verified:

• PR author tested all three commands both with and without graph.db
• All 476 tests pass with 0 lint warnings
• Changes are in error-handling paths that don't affect normal operation

Final Recommendation

• Rating: ⭐⭐⭐⭐⭐ (5/5)
• Action: APPROVE
• Reasoning: Exceptional fix - solves a real UX problem with minimal, correct changes that follow established patterns. Zero risk of regression, excellent test coverage, and improves user experience by replacing cryptic stack traces with clear guidance.

This is exactly how error handling should be implemented in CLI tools. The consistency with existing openReadonlyOrFail() usage across the codebase demonstrates good engineering practices.

---