feat: REST API for remote data management, recall, and import

[BYK]

Summary

• Add /api/v1/ REST API endpoints enabling lore data, lore recall, and lore import to work against a remote gateway when LORE_REMOTE_URL is set
• Add resolveProjectByRemoteOrPath() in core for read-only project lookup preferring git_remote over path
• Support zstd-compressed request bodies (Content-Encoding: zstd) for efficient import payloads

API Endpoints

Data reads:

• GET /api/v1/projects — list all projects
• GET /api/v1/stats — global stats
• GET /api/v1/projects/:id/{knowledge,sessions,distillations} — project-scoped lists
• GET /api/v1/{knowledge,sessions,distillations}/:id — show single entry

Data mutations:

• DELETE /api/v1/{knowledge,sessions,distillations,projects}/:id
• POST /api/v1/projects/:id/{clear,dedup}
• POST /api/v1/projects/merge (guarded against hosted mode)
• POST /api/v1/reindex — global embedding backfill (DB-wide, not project-scoped)

Recall:

• GET /api/v1/recall?q=...&git_remote=... — with query expansion (gateway has LLM client)
• Scope parameter validated against allowed values

Import:

• POST /api/v1/import/extract — accept chunks, run curator LLM, store results
• POST /api/v1/import/record — mark session as imported
• GET /api/v1/import/history — list import records

CLI Remote Wiring

All CLI commands (data, recall, import) check LORE_REMOTE_URL early and delegate to the REST API. Local codepaths are unchanged. Commands that require local filesystem access (recover, clear --all) error with a clear message in remote mode.

Self-Review Fixes (a591e38)

Addressed 11 findings from thorough self-review:

Critical:

• C2: Fix null body crash in handleClearProject (JSON null → TypeError)
• C3: Move reindex to global POST /api/v1/reindex (backfill is DB-wide, not project-scoped)
• C4: Guard handleMergeProjects against hosted mode (backfillGitRemotes runs git on local FS)
• C5: Add DELETE to CORS access-control-allow-methods

Medium:

• M1: Remove dead variables in cmdListRemote knowledge case
• M3: Handle non-JSON error responses in remote.ts (e.g. nginx 502)
• M5: Validate scope parameter in recall endpoint
• M6: Call setLastImportAt + exportLoreFile in importRemote
• M7: Check literal routes before parameterized routes in dispatcher

Low:

• L3: Remove dead endpoint variable in cmdDedupRemote
• L4: Fix test to actually test git_remote/path query param resolution

Deferred (acceptable):

• C1 (no auth): Consistent with existing proxy routes which also have no auth — auth is a separate concern for the gateway as a whole
• M2 (project resolution caching): Optimization, not correctness
• M4 (chunk size limits): Good follow-up, not blocking
• M8/L8 (Bun-only zstd): CLI remote helper only runs via Bun binary, not CJS bundle
• L7 (session delete 200 vs 404): 200 with zero counts is valid REST for idempotent deletes

Files Changed

File	Change
packages/core/src/db.ts	Add resolveProjectByRemoteOrPath() + projectPath()
packages/core/src/index.ts	Export new functions
packages/gateway/src/api.ts	New — REST API route dispatcher + all handlers
packages/gateway/src/server.ts	Add /api/ route (lazy-imported), add DELETE to CORS
packages/gateway/src/cli/remote.ts	New — CLI remote HTTP client + helpers
packages/gateway/src/cli/data.ts	Add remote proxying for all subcommands
packages/gateway/src/cli/recall-cmd.ts	Add remote proxying
packages/gateway/src/cli/import.ts	Split: local detect + remote extract
packages/gateway/test/api.test.ts	New — 33 tests for all API endpoints

Test Results

• 33 API tests (scope validation, null body, git_remote resolution, etc.)
• 1524 total tests passing, 0 failures
• Clean typecheck across all 4 packages