fix(pglite): fail loudly on $bunfs data-dir paths (#250)

[RyanAlberts]

Summary

When gbrain is compiled with bun build --compile, Bun mounts the bundled files under $bunfs:// — a virtual filesystem that PGLite's WASM module cannot read. The existing failure mode was either an opaque WASM panic or silent corruption of the on-disk brain state, leaving users with a half-initialized brain and no actionable signal about what went wrong.

This PR adds a small guard — assertRealFilesystemPath() — called at the top of PGLiteEngine.connect(), before the file lock or PGLite itself is touched. The guard detects the $bunfs prefix and throws with an actionable error pointing at the documented workarounds:

• Run from source: bun run src/cli.ts <command>
• Or pass --database-path with a real on-disk path

Coverage

The detector covers every documented $bunfs shape:

• $bunfs://... (URL-style)
• $bunfs/... (bare prefix)
• /$bunfs/... (absolute-path style, seen on Linux)
• /<anything>/$bunfs/... (nested)

Null / undefined / empty paths (in-memory PGLite, no data-dir) are unaffected.

Test plan

• 9 new unit tests in test/pglite-path-guard.test.ts:
  • isBunfsPath returns true for each documented shape
  • isBunfsPath returns false for normal paths and empty inputs
  • assertRealFilesystemPath throws with a message that mentions PGLite, the offending path, the bun run src/cli.ts workaround, --database-path, and the issue number for context
  • no-op on normal/undefined paths
• Existing pglite-lock.test.ts + engine-factory.test.ts still pass.
• Full bun test suite: 1926 pass, 0 fail, 174 skip.
• E2E suite not run.

Non-goals

This PR doesn't fix the underlying "compiled binary can't use PGLite" limitation — that likely needs PGLite WASM upstream work to read from $bunfs, or a one-time copy-to-tmp dance during startup. What this PR does is replace "opaque WASM panic / silent corruption" with "clear, actionable error pointing at the workaround", so the ~20 users who hit this in #250 stop losing time to it.

Fixes #250

Made with Cursor

[qodo-ai-reviewer]

Hi, assertRealFilesystemPath() tells users to pass --database-path, but the CLI uses --path to set config.database_path; there is no --database-path flag implemented. Users hitting the new error will try the suggested workaround and fail again, defeating the purpose of the change.

Severity: action required | Category: correctness

How to fix: Use correct CLI flag name

Agent prompt to fix - you can give this to your LLM of choice:

Issue description

assertRealFilesystemPath() throws an error instructing users to pass --database-path, but the CLI actually uses --path to specify a PGLite database directory/path. This makes the suggested workaround non-functional.

Issue Context

• gbrain init parses --path and stores it in config.database_path.
• Other commands (e.g., migrate) also use --path.
• Tests currently assert the message contains --database-path, so they need updating too.

Fix Focus Areas

• src/core/pglite-path-guard.ts[40-49]
• test/pglite-path-guard.test.ts[44-77]
• (Optional) ensure any docs/help text align with --path

---

Found by Qodo code review. FYI, Qodo is free for open-source.