Closes#383 item 2.
`aqe upgrade` is a read-only advisory command that detects which optional
native bindings load on this platform and recommends installs / flag
changes. It does NOT mutate feature flags, env vars, or config files — it
only tells the user what they'd gain.
Detects:
- better-sqlite3, web-tree-sitter (required)
- hnswlib-node (canonical HNSW, default since ADR-090)
- @ruvector/rvf-node (persistent HNSW + RVF export)
- @ruvector/solver-node (sublinear PageRank)
- @ruvector/attention (Flash Attention SIMD)
- @ruvector/gnn (GraphMAE acceleration)
Output:
- Platform + AQE version
- Per-package status (loaded / missing / required-missing) with the
first line of any load error
- Current flag state (after RUVECTOR_* env overrides)
- Recommendations: install hints for missing optionals, warnings when
a RUVECTOR_* forces a flag on but the native is missing
- Summary line with required-OK status and optional loaded/total
Flags:
--json machine-readable report
--strict exit 1 if any recommended optional native is missing
Exit codes:
0 all good (or --strict not passed with optionals missing)
1 --strict and ≥1 optional missing
2 a required native failed to load
Tests:
- 17 unit tests (tests/unit/cli-upgrade.test.ts) exercise pure
detection / recommendation / exit-code logic with injected probes
- 5 integration tests (tests/integration/cli/upgrade-command.test.ts)
spawn the built CLI and assert the JSON contract, human sections,
exit-code contract, and RUVECTOR_* env override plumbing
Also fixes a pre-existing lint error (unused originalConsoleInfo in
src/cli/index.ts) per the edit-touched-file convention.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>