Six CLI commands crashed on every fresh database produced by
`ruvector create`:
$ ruvector create /tmp/x.db -d 384
$ ruvector insert /tmp/x.db /tmp/v.json
SyntaxError: Unexpected token 'r', "redb…" is not valid JSON
Root cause: `bin/cli.js` `insert`, `search`, `stats`, `export`, and
`import` all did `JSON.parse(fs.readFileSync(dbPath, 'utf8'))` to
recover the dimension. But `<dbPath>` is a redb (Rust binary) file
managed by `@ruvector/core` — not a JSON document. The first byte
("r") tripped the parser before any other code ran.
Compounding: the same handlers called methods that don't exist on
`VectorDBWrapper` (`db.load`, `db.save`, `db.stats`) and didn't
`await` the async wrapper methods that do exist (`insert`,
`insertBatch`, `search`, `len`).
Fix:
- Persist construction args (dimensions, metric, schema version)
in `<dbPath>.meta.json` from `create`. `insert`/`search`/`stats`
read the sidecar and pass them straight to the wrapper
constructor — no more JSON-parsing of redb bytes.
- Drop calls to the phantom `db.load`/`db.save`/`db.stats` API.
Persistence is automatic via `storagePath`; counting goes through
`await db.len()`.
- Make every CLI handler `async` and `await` the wrapper calls.
Includes `benchmark`, whose previously-dropped promises meant the
reported insert/search rates were 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.
Verified end-to-end with a new test on Node 22.22.2:
$ 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`
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)
Out of scope (deliberately): the `export`/`import` handlers also
called the same phantom API. Those need the wrapper to grow an
enumeration method (`db.entries()` or similar) before they can do
honest work — file-only metadata-export is misleading. Tracked in a
follow-up; the existing handlers are left untouched here.
The ONNX-bundle half of #417 ships in a separate PR (#354).
Closes#417
Co-Authored-By: claude-flow <ruv@ruv.net>
3b00a565eb