fix(ruvector): CLI works on fresh DBs via meta sidecar (#417)

[ruvnet]

Summary

• Closes CLI commands that take a <database> path are broken on freshly-created DBs (and embed text fails on missing ONNX bundle) #417 — six CLI commands (insert, search, stats, export, import, plus the benchmark rate numbers) crashed on every fresh database produced by ruvector create. They tried to JSON.parse(fs.readFileSync(dbPath)) to recover the dimension, but <dbPath> is a redb (Rust binary) file managed by @ruvector/core — not JSON. The first byte ("r") tripped the parser. They also called methods that don't exist on VectorDBWrapper (db.load, db.save, db.stats) and never awaited the async ones that do.
• The ONNX-bundle half of CLI commands that take a <database> path are broken on freshly-created DBs (and embed text fails on missing ONNX bundle) #417 (build script not copying WASM payload) ships separately in fix(ruvector): bundle ONNX runtime into dist/ on build (#354) #434.

Fix

• Persist construction args in <dbPath>.meta.json from create; insert/search/stats read the sidecar instead of parsing redb bytes.
• Drop calls to the phantom db.load/db.save/db.stats. Persistence is automatic via storagePath; counting goes through await db.len().
• Every CLI handler becomes async and awaits the wrapper. benchmark numbers are now real (previously the dropped promises meant the rate was just spinner timing).
• Coerce numeric ids to strings inside insert — the native binding rejects integer ids.
• Surface a clear, actionable error when a DB exists without a sidecar (e.g. created by an older CLI), instead of an opaque parse failure.
• New regression test test/cli-fresh-db.test.mjs exercises the full create → insert → search → stats path against a real redb file in os.tmpdir().

Proof

Reproduction from the issue (v0.2.25, Node 22.22.2) before this PR:

$ npx ruvector create /tmp/x.db -d 8 -m cosine
$ npx ruvector insert /tmp/x.db /tmp/v.json
✖ Failed to insert vectors
Unexpected token 'r', \"redb…\" is not valid JSON

After this PR (node test/cli-fresh-db.test.mjs):

  ok: `ruvector create` exits 0
  ok: redb file exists at dbPath
  ok: sidecar metadata file exists
  ok: sidecar.dimensions = 8
  ok: sidecar.metric = cosine
  ok: `ruvector insert` exits 0
  ok: insert does not crash JSON.parsing the redb binary
  ok: `ruvector search` exits 0
  ok: search prints `Found N results` (across stdout/stderr)
  ok: search renders at least one hit row
  ok: `ruvector stats` exits 0
  ok: stats prints Vector Count
  ok: stats fails fast on orphan DB without sidecar
  ok: orphan-DB error message mentions sidecar

ruvector fresh-DB CLI smoke OK (issue #417)

Test plan

• create writes <dbPath>.meta.json with dimensions + metric + schema version.
• insert reopens the redb via storagePath (no JSON.parse), reads dimensions from sidecar, coerces numeric ids, and reports Total vectors: N from await db.len().
• search returns real hits (not undefined), respects -k, applies -t threshold post-hoc.
• stats prints actual count from await db.len().
• benchmark waits on every await db.search(), so the reported QPS reflects native completion (not spinner timing).
• Orphan DB without sidecar fails fast with a sidecar-mention error.
• Manual: npx ruvector create/insert/search against a 384-dim DB on a clean install (requires the ONNX bundling fix in fix(ruvector): bundle ONNX runtime into dist/ on build (#354) #434 to land for npx ruvector embed text to also work end-to-end).

Out of scope (deliberately)

export/import also called the phantom db.save/db.load API. Honest export needs the wrapper to grow an enumeration method (db.entries() or similar) before the handler can do real work — file-only metadata export would mislead users. Those handlers are left untouched here and tracked separately.

🤖 Generated with claude-flow