fix: support fs.watch on non-recursive platforms and make better-sqlite3 optional

[httpsVishu]

What

Fixes cross-platform issues with fs.watch and improves handling of optional dependencies.

Why

While setting up and running the project on a Linux/WSL environment, fs.watch with recursive support caused runtime errors, and better-sqlite3 being treated as required also broke tests when not installed. This PR ensures smoother setup and execution across platforms.

Results

• Tests pass successfully on Linux/WSL
• No runtime crashes due to unsupported fs.watch options
• Cleaner handling of optional dependencies

Checklist

• Tests added or updated
• npm run check passes
• Documentation updated (if public API changed)
• CHANGELOG.md updated (if user-facing change)

---

Summary by cubic

Fix cross-platform file watching by probing for recursive support and falling back when unsupported. Make better-sqlite3 optional with safe loading and graceful provider disablement; SQLite-only tests auto-skip when the module or bindings are missing.

• Bug Fixes
  • Try fs.watch with { recursive: true }; on failure, warn and reopen without recursion so top-level changes still trigger.
  • Load better-sqlite3 via require and handle MODULE_NOT_FOUND/ERR_DLOPEN_FAILED/bindings-missing; disable the OpenCode provider instead of crashing, and propagate non-availability errors only when unrelated.
  • Update provider/test types to use better-sqlite3’s Database and allow _testDb injection; add hasSqlite in fixtures to gate database/provider tests.

^{Written for commit d156c87. Summary will update on new commits.}

[cubic-dev-ai]

3 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/providers/shared/watch.ts">

<violation number="1" location="src/providers/shared/watch.ts:36">
P2: Platform allowlist incorrectly disables recursive fs.watch on Linux runtimes that support it, causing potential missed nested file change events.</violation>
</file>

<file name="src/providers/opencode/provider.ts">

<violation number="1" location="src/providers/opencode/provider.ts:30">
P2: Using top-level CommonJS `require("better-sqlite3")` in an ESM-distributed package can fail in ESM runtime paths and silently disable the OpenCode provider.</violation>
</file>

<file name="tests/opencode-fixtures.ts">

<violation number="1" location="tests/opencode-fixtures.ts:6">
P2: Catching all errors when requiring `better-sqlite3` can hide real runtime/dependency failures by silently skipping sqlite tests.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[vtemian]

Thanks for the contribution! The problems you're solving (Linux fs.watch compat, optional native deps) are real and valuable. However, the implementation needs some changes to align with the project's coding standards:

1. No any types — the project strictly forbids any (see CLAUDE.md). All the any usages (betterSqlite3: any, _testDb?: any, db: any, etc.) need to be replaced with proper typing using unknown + type guards or conditional dynamic imports.

2. require() in ESM — package.json has "type": "module", so bare require() won't work correctly. Use await import("better-sqlite3") with a lazy init pattern instead.

3. Silent catch {} — the empty catch hides real errors (native build failures, ABI mismatch). Please narrow to MODULE_NOT_FOUND and re-throw other errors.

4. Missing warning for non-recursive watch — on Linux, only top-level directory changes are detected without recursive watch. The code should emit a warning when recursive: true is unavailable so users know about the limitation.

5. Test describe string — opencode-provider.test.ts changes the describe label to "..." (literal dots), losing the actual suite name.

Would love to see a v2 addressing these. The direction is right, just needs implementation cleanup.

[httpsVishu]

implemented the required changes, let me know in case of any discrepancy