agentic-qe 3.9.15 → 3.9.16

package/dist/cli/commands/upgrade.js

@@ -0,0 +1,342 @@
+/**
+ * `aqe upgrade` — read-only advisory
+ *
+ * Detects which optional native bindings load on this platform and prints a
+ * report with recommendations. Does NOT modify feature flags, env vars, or
+ * config files — it only tells the user what they'd gain by installing the
+ * missing optional deps.
+ *
+ * Related: issue #383 item 2.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createRequire } from 'node:module';
+import { platform, arch } from 'node:os';
+import { getRuVectorFeatureFlags } from '../../integrations/ruvector/feature-flags.js';
+// ============================================================================
+// Native catalog
+// ============================================================================
+/**
+ * The set of packages `aqe upgrade` inspects. Order controls the report
+ * rendering order.
+ */
+export const NATIVE_CATALOG = [
+    {
+        packageName: 'better-sqlite3',
+        role: 'SQLite storage (required — memory.db, patterns, audit)',
+        fallback: 'n/a — required',
+        affectsFlags: [],
+        required: true,
+    },
+    {
+        packageName: 'web-tree-sitter',
+        role: 'Tree-sitter WASM parser runtime (required — code intelligence)',
+        fallback: 'n/a — required',
+        affectsFlags: [],
+        required: true,
+    },
+    {
+        packageName: 'hnswlib-node',
+        role: 'Canonical HNSW vector index (default since ADR-090)',
+        fallback: 'ProgressiveHnswBackend (JS) — correct but slower on large codebases',
+        affectsFlags: ['useNativeHNSW'],
+        required: false,
+    },
+    {
+        packageName: '@ruvector/rvf-node',
+        role: 'Persistent HNSW pattern store + RVF brain export format',
+        fallback: 'SQLite-backed HNSW + JSONL brain export',
+        affectsFlags: ['useRVFPatternStore'],
+        required: false,
+    },
+    {
+        packageName: '@ruvector/solver-node',
+        role: 'Sublinear PageRank on the pattern citation graph',
+        fallback: 'TypeScript power iteration — O(n·m) (practical cap ≈ 50K nodes)',
+        affectsFlags: ['useSublinearSolver'],
+        required: false,
+    },
+    {
+        packageName: '@ruvector/attention',
+        role: 'Flash Attention with SIMD acceleration',
+        fallback: 'Plain attention — 2.5–7× slower on large sequences',
+        affectsFlags: ['useQEFlashAttention'],
+        required: false,
+    },
+    {
+        packageName: '@ruvector/gnn',
+        role: 'GraphMAE native acceleration',
+        fallback: 'TypeScript GraphMAE — correct but slower',
+        affectsFlags: ['useGraphMAEEmbeddings'],
+        required: false,
+    },
+];
+/** Default probe — uses a CJS require relative to this module's location. */
+export function createDefaultLoadProbe() {
+    const req = createRequire(import.meta.url);
+    return (packageName) => {
+        try {
+            req(packageName);
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err : new Error(String(err)) };
+        }
+    };
+}
+export function detectNatives(catalog, probe) {
+    return catalog.map((check) => {
+        const result = probe(check.packageName);
+        if (result.ok) {
+            return { ...check, status: 'loaded' };
+        }
+        const missingModule = isModuleNotFound(result.error);
+        const status = check.required
+            ? 'required-missing'
+            : missingModule
+                ? 'missing'
+                : 'missing';
+        return { ...check, status, loadError: result.error.message };
+    });
+}
+function isModuleNotFound(err) {
+    return err.code === 'MODULE_NOT_FOUND';
+}
+// ============================================================================
+// Environment overrides
+// ============================================================================
+/**
+ * Map of RUVECTOR_* env vars → feature flag names that aqe upgrade cares about.
+ * Only includes flags tied to optional natives — the full list is in
+ * feature-flags.ts.
+ */
+const ENV_VAR_TO_FLAG = {
+    RUVECTOR_USE_RVF_PATTERN_STORE: 'useRVFPatternStore',
+    RUVECTOR_USE_SUBLINEAR_SOLVER: 'useSublinearSolver',
+    RUVECTOR_USE_NATIVE_HNSW: 'useNativeHNSW',
+    RUVECTOR_USE_GNN_INDEX: 'useQEGNNIndex',
+    RUVECTOR_USE_FLASH_ATTENTION: 'useQEFlashAttention',
+    RUVECTOR_USE_GRAPH_MAE_EMBEDDINGS: 'useGraphMAEEmbeddings',
+};
+export function readEnvOverrides(env) {
+    const out = [];
+    for (const [envVar, flagName] of Object.entries(ENV_VAR_TO_FLAG)) {
+        const v = env[envVar];
+        if (v !== undefined)
+            out.push({ envVar, value: v, flagName });
+    }
+    return out;
+}
+export function buildRecommendations(input) {
+    const recs = [];
+    const nativeByName = new Map(input.natives.map((n) => [n.packageName, n]));
+    // Missing required deps are a hard error.
+    for (const n of input.natives) {
+        if (n.status === 'required-missing') {
+            recs.push({
+                severity: 'error',
+                message: `Required dependency missing: ${n.packageName} — ${n.role}`,
+                action: `npm install ${n.packageName}`,
+            });
+        }
+    }
+    // Missing optional deps: suggest install, note fallback.
+    for (const n of input.natives) {
+        if (n.status === 'missing' && !n.required) {
+            recs.push({
+                severity: 'warn',
+                message: `Optional native missing: ${n.packageName} — falls back to ${n.fallback}`,
+                action: `npm install ${n.packageName}`,
+            });
+        }
+    }
+    // Env override conflicts: user forced a flag ON but the native isn't loadable.
+    const flagByName = { ...input.flags };
+    for (const override of input.envOverrides) {
+        const natives = input.natives.filter((n) => n.affectsFlags.includes(override.flagName));
+        const anyLoaded = natives.some((n) => n.status === 'loaded');
+        const wantsOn = override.value === 'true' || override.value === '1';
+        if (wantsOn && natives.length > 0 && !anyLoaded) {
+            const missing = natives.map((n) => n.packageName).join(', ');
+            recs.push({
+                severity: 'warn',
+                message: `${override.envVar}=${override.value} requests flag ${override.flagName}=true, ` +
+                    `but required native(s) not loaded: ${missing}. The flag will silently fall back.`,
+                action: natives[0] ? `npm install ${natives[0].packageName}` : undefined,
+            });
+        }
+    }
+    void flagByName; // reserved for future rules
+    void nativeByName;
+    // All optionals loaded → positive-confirmation info line.
+    const optionalMissing = input.natives.filter((n) => !n.required && n.status === 'missing');
+    if (optionalMissing.length === 0 && input.natives.every((n) => n.status !== 'required-missing')) {
+        recs.push({
+            severity: 'info',
+            message: 'All recommended native bindings are loaded — no action required.',
+        });
+    }
+    return recs;
+}
+export function buildReport(input) {
+    const natives = detectNatives(NATIVE_CATALOG, input.probe);
+    const envOverrides = readEnvOverrides(input.env);
+    const recommendations = buildRecommendations({
+        natives,
+        flags: input.flags,
+        envOverrides,
+    });
+    const optionalLoadedCount = natives.filter((n) => !n.required && n.status === 'loaded').length;
+    const optionalMissingCount = natives.filter((n) => !n.required && n.status === 'missing').length;
+    const requiredOk = natives.filter((n) => n.required).every((n) => n.status === 'loaded');
+    return {
+        aqeVersion: input.aqeVersion,
+        platform: {
+            os: platform(),
+            arch: arch(),
+            node: process.version,
+        },
+        natives,
+        flags: input.flags,
+        envOverrides,
+        recommendations,
+        summary: {
+            requiredOk,
+            optionalMissingCount,
+            optionalLoadedCount,
+        },
+    };
+}
+// ============================================================================
+// Exit-code policy
+// ============================================================================
+export function exitCodeFor(report, strict) {
+    if (!report.summary.requiredOk)
+        return 2;
+    if (strict && report.summary.optionalMissingCount > 0)
+        return 1;
+    return 0;
+}
+// ============================================================================
+// Rendering
+// ============================================================================
+export function renderReportHuman(report) {
+    const lines = [];
+    const push = (s = '') => lines.push(s);
+    push('');
+    push(chalk.bold.blue('  aqe upgrade — native binding report'));
+    push(chalk.gray('  ──────────────────────────────────────'));
+    push('');
+    push(`  AQE:       ${chalk.cyan(report.aqeVersion)}`);
+    push(`  Platform:  ${chalk.cyan(`${report.platform.os} ${report.platform.arch}`)}`);
+    push(`  Node:      ${chalk.cyan(report.platform.node)}`);
+    push('');
+    push(chalk.blue('  Native bindings:'));
+    for (const n of report.natives) {
+        const status = statusBadge(n.status);
+        push(`    ${status} ${chalk.bold(n.packageName.padEnd(28))} ${chalk.gray(n.role)}`);
+        if (n.status !== 'loaded' && n.loadError) {
+            // Node's MODULE_NOT_FOUND error message carries a multi-line "Require
+            // stack:" trailer that adds no signal here — keep the first line only.
+            push(`        ${chalk.gray(n.loadError.split('\n')[0])}`);
+        }
+    }
+    push('');
+    push(chalk.blue('  Flag state (after env overrides):'));
+    const flagEntries = Object.entries(report.flags);
+    for (const [name, value] of flagEntries) {
+        const badge = value ? chalk.green('on ') : chalk.yellow('off');
+        push(`    ${badge}  ${name}`);
+    }
+    if (report.envOverrides.length > 0) {
+        push('');
+        push(chalk.blue('  Env overrides in effect:'));
+        for (const o of report.envOverrides) {
+            push(`    ${chalk.cyan(o.envVar)}=${chalk.cyan(o.value)}  ${chalk.gray(`→ ${o.flagName}`)}`);
+        }
+    }
+    push('');
+    push(chalk.blue('  Recommendations:'));
+    if (report.recommendations.length === 0) {
+        push(chalk.gray('    (none)'));
+    }
+    else {
+        for (const rec of report.recommendations) {
+            const prefix = recommendationPrefix(rec.severity);
+            push(`    ${prefix} ${rec.message}`);
+            if (rec.action)
+                push(`        ${chalk.gray('→')} ${chalk.cyan(rec.action)}`);
+        }
+    }
+    push('');
+    const okBadge = report.summary.requiredOk ? chalk.green('OK') : chalk.red('FAIL');
+    push(`  Summary:   required ${okBadge}    ` +
+        `optional loaded ${chalk.cyan(report.summary.optionalLoadedCount)} / ` +
+        `${chalk.cyan(report.summary.optionalLoadedCount + report.summary.optionalMissingCount)}`);
+    push('');
+    return lines.join('\n');
+}
+function statusBadge(status) {
+    switch (status) {
+        case 'loaded':
+            return chalk.green('✓');
+        case 'missing':
+            return chalk.yellow('…');
+        case 'required-missing':
+            return chalk.red('✗');
+    }
+}
+function recommendationPrefix(severity) {
+    switch (severity) {
+        case 'info':
+            return chalk.green('✓');
+        case 'warn':
+            return chalk.yellow('!');
+        case 'error':
+            return chalk.red('✗');
+    }
+}
+export function createUpgradeCommand(cleanupAndExit) {
+    const cmd = new Command('upgrade')
+        .description('Detect optional native bindings and recommend install / flag changes (read-only)')
+        .option('--json', 'Emit the report as JSON to stdout', false)
+        .option('--strict', 'Exit non-zero if any recommended optional native is missing', false)
+        .action(async (options) => {
+        const aqeVersion = resolveAqeVersion();
+        const rvFlags = getRuVectorFeatureFlags();
+        const report = buildReport({
+            aqeVersion,
+            probe: createDefaultLoadProbe(),
+            env: process.env,
+            flags: {
+                useRVFPatternStore: rvFlags.useRVFPatternStore,
+                useSublinearSolver: rvFlags.useSublinearSolver,
+                useNativeHNSW: rvFlags.useNativeHNSW,
+                useGraphMAEEmbeddings: rvFlags.useGraphMAEEmbeddings,
+                useQEFlashAttention: rvFlags.useQEFlashAttention,
+            },
+        });
+        if (options.json) {
+            process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(renderReportHuman(report));
+        }
+        await cleanupAndExit(exitCodeFor(report, options.strict === true));
+    });
+    return cmd;
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function resolveAqeVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        const pkg = req('../../../package.json');
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/cli/completions/index.d.ts

@@ -152,6 +152,33 @@ export declare const COMMANDS: {
             };
         };
     };
+    readonly brain: {
+        readonly description: "Export, import, and inspect QE brain state";
+        readonly subcommands: {
+            readonly export: {
+                readonly options: readonly ["-o", "--output", "--format", "--db"];
+            };
+            readonly import: {
+                readonly options: readonly ["-i", "--input", "--strategy", "--dry-run", "--db"];
+            };
+            readonly info: {
+                readonly options: readonly ["-i", "--input"];
+            };
+            readonly diff: {
+                readonly options: readonly ["--table", "--verbose", "--json"];
+            };
+            readonly search: {
+                readonly options: readonly ["-i", "--input", "--table", "--domain", "--pattern-type", "--since", "--until", "-q", "--query", "-l", "--limit", "--json"];
+            };
+            readonly 'witness-backfill': {
+                readonly options: readonly ["--db"];
+            };
+        };
+    };
+    readonly upgrade: {
+        readonly description: "Detect optional native bindings and recommend install / flag changes";
+        readonly options: readonly ["--json", "--strict"];
+    };
 };
 /**
  * Task types for completion

package/dist/cli/completions/index.js

@@ -231,6 +231,23 @@ export const COMMANDS = {
             install: { options: ['--shell'] },
         },
     },
+    // Brain export/import/diff/search
+    brain: {
+        description: 'Export, import, and inspect QE brain state',
+        subcommands: {
+            export: { options: ['-o', '--output', '--format', '--db'] },
+            import: { options: ['-i', '--input', '--strategy', '--dry-run', '--db'] },
+            info: { options: ['-i', '--input'] },
+            diff: { options: ['--table', '--verbose', '--json'] },
+            search: { options: ['-i', '--input', '--table', '--domain', '--pattern-type', '--since', '--until', '-q', '--query', '-l', '--limit', '--json'] },
+            'witness-backfill': { options: ['--db'] },
+        },
+    },
+    // Native binding advisor
+    upgrade: {
+        description: 'Detect optional native bindings and recommend install / flag changes',
+        options: ['--json', '--strict'],
+    },
 };
 /**
  * Task types for completion
@@ -284,40 +301,40 @@ export function generateBashCompletion() {
 
 # Helper function to complete test files (*.test.ts, *.spec.ts, *.test.js, etc.)
 _aqe_complete_test_files() {
-    local cur="\$1"
+    local cur="$1"
     local IFS=$'\\n'
     local files=()
 
     # Complete test files with common test file patterns
     # Use find for more reliable glob matching across directories
-    if [[ -z "\$cur" || "\$cur" == "." ]]; then
+    if [[ -z "$cur" || "$cur" == "." ]]; then
         # No prefix - search from current directory
         while IFS= read -r file; do
-            files+=("\$file")
+            files+=("$file")
         done < <(find . -maxdepth 3 -type f \\( -name "*.test.ts" -o -name "*.spec.ts" -o -name "*.test.js" -o -name "*.spec.js" -o -name "*.test.tsx" -o -name "*.spec.tsx" \\) 2>/dev/null | head -30)
     else
         # Has prefix - use compgen with glob patterns
-        files+=(\$(compgen -f -X '!*.test.ts' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.spec.ts' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.test.js' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.spec.js' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.test.tsx' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.spec.tsx' -- "\$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.test.ts' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.spec.ts' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.test.js' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.spec.js' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.test.tsx' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.spec.tsx' -- "$cur" 2>/dev/null))
     fi
 
     # Also include directories for navigation
-    COMPREPLY=(\$(compgen -d -- "\$cur"))
+    COMPREPLY=($(compgen -d -- "$cur"))
 
     # Add test files to completions
     for file in "\${files[@]}"; do
-        [[ -n "\$file" ]] && COMPREPLY+=("\$file")
+        [[ -n "$file" ]] && COMPREPLY+=("$file")
     done
 }
 
 # Helper function to complete directories
 _aqe_complete_directories() {
-    local cur="\$1"
-    COMPREPLY=( \$(compgen -d -- "$cur") )
+    local cur="$1"
+    COMPREPLY=( $(compgen -d -- "$cur") )
 }
 
 # Main completion function (version-agnostic name per ADR-042)
@@ -325,12 +342,13 @@ _aqe_completions() {
     local cur prev words cword
     _init_completion || return
 
-    local commands="init status health task agent domain protocol test coverage quality security code migrate hypergraph completions"
+    local commands="init status health task agent domain protocol test coverage quality security code migrate hypergraph completions brain upgrade"
     local task_subcmds="submit list cancel status"
     local agent_subcmds="list spawn"
     local domain_subcmds="list health"
     local protocol_subcmds="run"
     local completions_subcmds="bash zsh fish powershell install"
+    local brain_subcmds="export import info diff search witness-backfill"
     local code_actions="index search impact deps"
     local test_actions="generate execute"
 
@@ -663,6 +681,48 @@ _aqe_completions() {
                     ;;
             esac
             ;;
+        brain)
+            case "\${words[2]}" in
+                export)
+                    COMPREPLY=( $(compgen -W "-o --output --format --db" -- "$cur") )
+                    return
+                    ;;
+                import)
+                    COMPREPLY=( $(compgen -W "-i --input --strategy --dry-run --db" -- "$cur") )
+                    return
+                    ;;
+                info)
+                    COMPREPLY=( $(compgen -W "-i --input" -- "$cur") )
+                    return
+                    ;;
+                diff)
+                    COMPREPLY=( $(compgen -W "--table --verbose --json" -- "$cur") )
+                    return
+                    ;;
+                search)
+                    case "$prev" in
+                        --domain)
+                            COMPREPLY=( $(compgen -W "$domains" -- "$cur") )
+                            return
+                            ;;
+                    esac
+                    COMPREPLY=( $(compgen -W "-i --input --table --domain --pattern-type --since --until -q --query -l --limit --json" -- "$cur") )
+                    return
+                    ;;
+                witness-backfill)
+                    COMPREPLY=( $(compgen -W "--db" -- "$cur") )
+                    return
+                    ;;
+                *)
+                    COMPREPLY=( $(compgen -W "$brain_subcmds" -- "$cur") )
+                    return
+                    ;;
+            esac
+            ;;
+        upgrade)
+            COMPREPLY=( $(compgen -W "--json --strict" -- "$cur") )
+            return
+            ;;
         *)
             COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
             return
@@ -722,6 +782,8 @@ _aqe() {
         'hypergraph:Query the code knowledge hypergraph'
         'migrate:V2 to V3 migration'
         'completions:Generate shell completions'
+        'brain:Export, import, and inspect QE brain state'
+        'upgrade:Detect optional native bindings and recommend flags'
     )
 
     domains=(
@@ -1016,6 +1078,30 @@ _aqe() {
                             ;;
                     esac
                     ;;
+                brain)
+                    local -a brain_commands
+                    brain_commands=(
+                        'export:Export brain state to a portable file/directory'
+                        'import:Import a brain export into the local database'
+                        'info:Show manifest metadata for a brain export'
+                        'diff:Compare two brain exports'
+                        'search:Filtered search over a JSONL brain export'
+                        'witness-backfill:Create witness chain entries for legacy patterns'
+                    )
+                    _arguments -C \\
+                        '1:brain subcommand:->brain_cmd' \\
+                        '*::arg:->brain_args'
+                    case "$state" in
+                        brain_cmd)
+                            _describe -t commands 'brain subcommands' brain_commands
+                            ;;
+                    esac
+                    ;;
+                upgrade)
+                    _arguments \\
+                        '--json[Emit the report as JSON]' \\
+                        '--strict[Exit non-zero if any optional native is missing]'
+                    ;;
             esac
             ;;
     esac
@@ -1063,6 +1149,16 @@ complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_
 complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "impacted" -d "Find impacted tests"
 complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "gaps" -d "Find coverage gaps"
 complete -c aqe -n "__fish_use_subcommand" -a "migrate" -d "V2 to V3 migration"
+complete -c aqe -n "__fish_use_subcommand" -a "brain" -d "Export, import, and inspect QE brain state"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "export" -d "Export brain state"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "import" -d "Import a brain export"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "info" -d "Show manifest info"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "diff" -d "Compare two brain exports"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "search" -d "Filtered search over a JSONL brain export"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "witness-backfill" -d "Backfill witness chain entries"
+complete -c aqe -n "__fish_use_subcommand" -a "upgrade" -d "Detect optional native bindings and recommend install / flag changes"
+complete -c aqe -n "__fish_seen_subcommand_from upgrade" -l json -d "Emit the report as JSON"
+complete -c aqe -n "__fish_seen_subcommand_from upgrade" -l strict -d "Exit non-zero if any optional native is missing"
 complete -c aqe -n "__fish_use_subcommand" -a "completions" -d "Generate shell completions"
 
 # Domains list
@@ -1267,6 +1363,8 @@ $script:AQE_COMMANDS = @{
     'hypergraph' = 'Query the code knowledge hypergraph'
     'migrate' = 'V2 to V3 migration'
     'completions' = 'Generate shell completions'
+    'brain' = 'Export, import, and inspect QE brain state'
+    'upgrade' = 'Detect optional native bindings and recommend flags'
 }
 
 Register-ArgumentCompleter -Native -CommandName 'aqe' -ScriptBlock {

package/dist/cli/handlers/brain-handler.d.ts

@@ -16,6 +16,8 @@ export declare class BrainHandler implements ICommandHandler {
     private executeExport;
     private executeImport;
     private executeInfo;
+    private executeDiff;
+    private executeSearch;
     private executeWitnessBackfill;
     getHelp(): string;
 }