arceus-s 1.6.4

package/dist/cli/analyze.js

@@ -0,0 +1,525 @@
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .arc/
+ *
+ * Delegates core analysis to the shared runFullAnalysis orchestrator.
+ * This CLI wrapper handles: heap management, progress bar, SIGINT,
+ * skill generation (--skills), summary output, and process.exit().
+ */
+import path from 'path';
+import { execFileSync } from 'child_process';
+import v8 from 'v8';
+import cliProgress from 'cli-progress';
+import { closeLbug } from '../core/lbug/lbug-adapter.js';
+import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
+import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { runFullAnalysis } from '../core/run-analyze.js';
+import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
+import { warnMissingOptionalGrammars } from './optional-grammars.js';
+import { glob } from 'glob';
+import fs from 'fs/promises';
+import { cliError, binName } from './cli-message.js';
+import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
+// Capture stderr.write at module load BEFORE anything (LadybugDB native
+// init, progress bar, console redirection) can monkey-patch it. The
+// fatal handlers below MUST reach the user even when the analyze path
+// has redirected console.* through the progress bar's bar.log() — the
+// previous behaviour silently swallowed stack traces and made #1169
+// indistinguishable from a no-op success on Windows.
+const realStderrWrite = process.stderr.write.bind(process.stderr);
+const writeFatalToStderr = (label, err) => {
+    const isErr = err instanceof Error;
+    const message = isErr ? err.message : String(err);
+    realStderrWrite(`\n  ${label}: ${message}\n`);
+    if (isErr && err.stack)
+        realStderrWrite(`${err.stack}\n`);
+};
+let fatalHandlersInstalled = false;
+/**
+ * Install one-shot `unhandledRejection` / `uncaughtException` handlers
+ * that surface the failure to the real stderr (bypassing any console
+ * redirection installed by the progress bar) and force a non-zero exit
+ * code. Without these, an async error escaping {@link analyzeCommand}'s
+ * try/catch was reported as exit 0 with no diagnostic — the silent
+ * failure mode tracked in #1169.
+ */
+const installFatalHandlers = () => {
+    if (fatalHandlersInstalled)
+        return;
+    fatalHandlersInstalled = true;
+    process.on('unhandledRejection', (err) => {
+        writeFatalToStderr('Analysis failed (unhandled rejection)', err);
+        process.exit(1);
+    });
+    process.on('uncaughtException', (err) => {
+        writeFatalToStderr('Analysis failed (uncaught exception)', err);
+        process.exit(1);
+    });
+};
+const HEAP_MB = 8192;
+const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
+/** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
+const STACK_KB = 4096;
+const STACK_FLAG = `--stack-size=${STACK_KB}`;
+/** Re-exec the process with an 8GB heap and larger stack if we're currently below that. */
+function ensureHeap() {
+    const nodeOpts = process.env.NODE_OPTIONS || '';
+    if (nodeOpts.includes('--max-old-space-size'))
+        return false;
+    const v8Heap = v8.getHeapStatistics().heap_size_limit;
+    if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
+        return false;
+    // --stack-size is a V8 flag not allowed in NODE_OPTIONS on Node 24+,
+    // so pass it only as a direct CLI argument, not via the environment.
+    const cliFlags = [HEAP_FLAG];
+    if (!nodeOpts.includes('--stack-size'))
+        cliFlags.push(STACK_FLAG);
+    try {
+        execFileSync(process.execPath, [...cliFlags, ...process.argv.slice(1)], {
+            stdio: 'inherit',
+            env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
+        });
+    }
+    catch (e) {
+        process.exitCode = e.status ?? 1;
+    }
+    return true;
+}
+/**
+ * Whether the post-index skill step should run.
+ *
+ * The gated block does two things in sequence: (1) generates the community
+ * skill files from `--skills`, and (2) re-runs `generateAIContextFiles` so
+ * AGENTS.md/CLAUDE.md can reference the freshly written skills. Both are
+ * suppressed together — `--index-only` drops the entire step, not just the
+ * community-skill write. Name retained for the test contract; see call site
+ * in `analyzeCommand` for the AGENTS.md/CLAUDE.md re-generation it also gates.
+ *
+ * Kept as a pure helper so the `--index-only --skills` contract is unit-tested
+ * without booting the full analyze pipeline (#742 review).
+ */
+export const shouldGenerateCommunitySkillFiles = (options, pipelineResult) => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
+export const analyzeCommand = async (inputPath, options) => {
+    if (ensureHeap())
+        return;
+    // Install fatal handlers immediately after re-exec resolution so any
+    // async error that escapes the try/catch below (#1169) surfaces with
+    // a stack trace and a non-zero exit code instead of a silent exit 0.
+    installFatalHandlers();
+    if (options?.verbose) {
+        process.env.ARC_VERBOSE = '1';
+    }
+    if (options?.maxFileSize) {
+        process.env.ARC_MAX_FILE_SIZE = options.maxFileSize;
+    }
+    if (options?.workerTimeout) {
+        const workerTimeoutSeconds = Number(options.workerTimeout);
+        if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
+            cliError('  --worker-timeout must be at least 1 second.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.ARC_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
+    }
+    // Parse `--embeddings [limit]`: `true` → default cap, string → numeric cap
+    // (0 disables the cap entirely). Validated up here so failures match the
+    // sibling-validation pattern (exit before bar.start() — otherwise
+    // process.exit() leaves the progress bar's hidden cursor uncleared).
+    let embeddingsNodeLimit;
+    if (typeof options?.embeddings === 'string') {
+        const parsed = Number(options.embeddings);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            cliError(`  --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
+                `Pass 0 to disable the safety cap, or omit the value to keep the default.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        embeddingsNodeLimit = parsed;
+    }
+    const embeddingsEnabled = !!options?.embeddings;
+    const setPositiveEnv = (optionName, envName, value) => {
+        if (value === undefined)
+            return true;
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            cliError(`  ${optionName} must be a positive integer.\n`);
+            process.exitCode = 1;
+            return false;
+        }
+        process.env[envName] = String(parsed);
+        return true;
+    };
+    if (!setPositiveEnv('--embedding-threads', 'ARC_EMBEDDING_THREADS', options?.embeddingThreads) ||
+        !setPositiveEnv('--embedding-batch-size', 'ARC_EMBEDDING_BATCH_SIZE', options?.embeddingBatchSize) ||
+        !setPositiveEnv('--embedding-sub-batch-size', 'ARC_EMBEDDING_SUB_BATCH_SIZE', options?.embeddingSubBatchSize)) {
+        return;
+    }
+    if (options?.embeddingDevice) {
+        const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
+        if (!allowed.has(options.embeddingDevice)) {
+            cliError('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.ARC_EMBEDDING_DEVICE = options.embeddingDevice;
+    }
+    console.log('\n  Arceus Analyzer\n');
+    // `--index-only` is the stronger contract — it suppresses every form of file
+    // injection, including community skill writes that `--skills` would normally
+    // produce. Surface the override explicitly so users don't wonder why a
+    // pipeline re-index ran but no skill files appeared. The pipeline still
+    // re-runs (see `force: options?.force || options?.skills` below); the warning
+    // is purely about the dropped post-index write step.
+    if (options?.indexOnly && options?.skills) {
+        console.log('  Note: --index-only overrides --skills; community skill files will not be written.\n');
+    }
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else if (options?.skipGit) {
+        // --skip-git: treat cwd as the index root, do not walk up to a parent git repo.
+        repoPath = path.resolve(process.cwd());
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            console.log('  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    const repoHasGit = hasGitDir(repoPath);
+    if (!repoHasGit && !options?.skipGit) {
+        console.log('  Not a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (!repoHasGit) {
+        console.log('  Warning: no .git directory found \u2014 commit-tracking and incremental updates disabled.\n');
+    }
+    // If the target repo contains files an optional grammar would parse but
+    // that grammar's native binding is absent, warn before analysis so users
+    // learn why those files end up unparsed instead of silently getting a
+    // degraded index.
+    try {
+        const matches = await glob(['**/*.dart', '**/*.proto'], {
+            cwd: repoPath,
+            ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
+            dot: false,
+            nodir: true,
+            absolute: false,
+        });
+        if (matches.length > 0) {
+            const present = new Set();
+            for (const m of matches) {
+                const ext = path.extname(m).toLowerCase();
+                if (ext)
+                    present.add(ext);
+            }
+            warnMissingOptionalGrammars({ context: 'analyze', relevantExtensions: present });
+        }
+    }
+    catch {
+        // Best-effort warning \u2014 never block analyze on the precheck.
+    }
+    // KuzuDB migration cleanup is handled by runFullAnalysis internally.
+    // Note: --skills is handled after runFullAnalysis using the returned pipelineResult.
+    if (process.env.ARC_NO_GITIGNORE) {
+        console.log('  ARC_NO_GITIGNORE is set — skipping .gitignore (still reading .arcignore)\n');
+    }
+    const maxFileSizeBanner = getMaxFileSizeBannerMessage();
+    if (maxFileSizeBanner) {
+        console.log(`${maxFileSizeBanner}\n`);
+    }
+    // ── CLI progress bar setup ─────────────────────────────────────────
+    const bar = new cliProgress.SingleBar({
+        format: '  {bar} {percentage}% | {phase}',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
+        hideCursor: true,
+        barGlue: '',
+        autopadding: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    }, cliProgress.Presets.shades_grey);
+    bar.start(100, 0, { phase: 'Initializing...' });
+    // Graceful SIGINT handling. Pino's default destination is `sync: false`
+    // (buffered) — flush before exit so in-flight records reach stderr.
+    // See `arc/src/core/logger.ts:flushLoggerSync`.
+    let aborted = false;
+    const sigintHandler = () => {
+        if (aborted)
+            process.exit(1);
+        aborted = true;
+        bar.stop();
+        console.log('\n  Interrupted — cleaning up...');
+        closeLbug()
+            .catch(() => { })
+            .finally(async () => {
+            const { flushLoggerSync } = await import('../core/logger.js');
+            flushLoggerSync();
+            process.exit(130);
+        });
+    };
+    process.on('SIGINT', sigintHandler);
+    // Route console output through bar.log() to prevent progress bar corruption.
+    // This is a deliberate UI pattern (not a logging concern): analyze runs a
+    // long-lived progress bar on stdout; any concurrent console.* write would
+    // overwrite the bar mid-render. We capture originals, swap to barLog for
+    // the lifetime of the run, and restore on completion/error/SIGINT.
+    const origLog = console.log.bind(console);
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    const origWarn = console.warn.bind(console);
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    const origError = console.error.bind(console);
+    let barCurrentValue = 0;
+    const barLog = (...args) => {
+        process.stdout.write('\x1b[2K\r');
+        origLog(args.map((a) => (typeof a === 'string' ? a : String(a))).join(' '));
+        bar.update(barCurrentValue);
+    };
+    console.log = barLog;
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    console.warn = barLog;
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    console.error = barLog;
+    // Track elapsed time per phase
+    let lastPhaseLabel = 'Initializing...';
+    let phaseStart = Date.now();
+    const updateBar = (value, phaseLabel) => {
+        barCurrentValue = value;
+        if (phaseLabel !== lastPhaseLabel) {
+            lastPhaseLabel = phaseLabel;
+            phaseStart = Date.now();
+        }
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        const display = elapsed >= 3 ? `${phaseLabel} (${elapsed}s)` : phaseLabel;
+        bar.update(value, { phase: display });
+    };
+    const elapsedTimer = setInterval(() => {
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        if (elapsed >= 3) {
+            bar.update({ phase: `${lastPhaseLabel} (${elapsed}s)` });
+        }
+    }, 1000);
+    const t0 = Date.now();
+    // ── Run shared analysis orchestrator ───────────────────────────────
+    try {
+        const skipAll = options?.indexOnly;
+        const skipAgentsMd = skipAll || options?.skipAgentsMd;
+        const skipSkills = skipAll || options?.skipSkills;
+        const result = await runFullAnalysis(repoPath, {
+            // Pipeline re-index — OR'd with --skills because skill generation
+            // needs a fresh pipelineResult. Has no bearing on the registry
+            // collision guard (see allowDuplicateName below).
+            force: options?.force || options?.skills,
+            embeddings: embeddingsEnabled,
+            embeddingsNodeLimit,
+            dropEmbeddings: options?.dropEmbeddings,
+            skipGit: options?.skipGit,
+            skipAgentsMd,
+            skipSkills,
+            noStats: options?.noStats,
+            registryName: options?.name,
+            // Registry-collision bypass — its own CLI flag, intentionally NOT
+            // overloading --force. A user who hits the collision guard should
+            // be able to accept the duplicate name without also paying the
+            // cost of a full pipeline re-index. See #829 review round 2.
+            allowDuplicateName: options?.allowDuplicateName,
+        }, {
+            onProgress: (_phase, percent, message) => {
+                updateBar(percent, message);
+            },
+            onLog: barLog,
+        });
+        if (result.alreadyUpToDate) {
+            // Even the fast path must prove the repo is discoverable. A prior
+            // run can write meta.json and then fail before registerRepo(); in
+            // that half-finalized state, runFullAnalysis returns alreadyUpToDate
+            // on the next invocation unless we check the registry here too.
+            await assertAnalysisFinalized(repoPath);
+            clearInterval(elapsedTimer);
+            process.removeListener('SIGINT', sigintHandler);
+            console.log = origLog;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+            console.warn = origWarn;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+            console.error = origError;
+            bar.stop();
+            console.log('  Already up to date\n');
+            // Safe to return without process.exit(0) — the early-return path in
+            // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
+            return;
+        }
+        // Post-finalize invariant (#1169): runFullAnalysis nominally writes
+        // meta.json and registers the repo, but on Windows it has been
+        // observed to return successfully with neither artifact present
+        // (banner-only output, exit 0). Verify both before declaring
+        // success so the silent-finalize state surfaces with a non-zero
+        // exit code and an actionable error instead of being mistaken for
+        // a healthy index.
+        await assertAnalysisFinalized(repoPath);
+        // Skill generation (CLI-only, uses pipeline result from analysis).
+        // Gated so `--index-only --skills` skips community skill writes too
+        // (`shouldGenerateCommunitySkillFiles` — see unit test).
+        if (shouldGenerateCommunitySkillFiles(options, result.pipelineResult)) {
+            updateBar(99, 'Generating skill files...');
+            try {
+                const { generateSkillFiles } = await import('./skill-gen.js');
+                const { generateAIContextFiles } = await import('./ai-context.js');
+                const skillResult = await generateSkillFiles(repoPath, result.repoName, result.pipelineResult);
+                if (skillResult.skills.length > 0) {
+                    barLog(`  Generated ${skillResult.skills.length} skill files`);
+                    // Re-generate AI context files now that we have skill info
+                    const s = result.stats;
+                    const communityResult = result.pipelineResult?.communityResult;
+                    let aggregatedClusterCount = 0;
+                    if (communityResult?.communities) {
+                        const groups = new Map();
+                        for (const c of communityResult.communities) {
+                            const label = c.heuristicLabel || c.label || 'Unknown';
+                            groups.set(label, (groups.get(label) || 0) + c.symbolCount);
+                        }
+                        aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
+                    }
+                    const { storagePath: sp } = getStoragePaths(repoPath);
+                    await generateAIContextFiles(repoPath, sp, result.repoName, {
+                        files: s.files ?? 0,
+                        nodes: s.nodes ?? 0,
+                        edges: s.edges ?? 0,
+                        communities: s.communities,
+                        clusters: aggregatedClusterCount,
+                        processes: s.processes,
+                    }, skillResult.skills, { skipAgentsMd, skipSkills, noStats: options?.noStats });
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        const totalTime = ((Date.now() - t0) / 1000).toFixed(1);
+        clearInterval(elapsedTimer);
+        process.removeListener('SIGINT', sigintHandler);
+        console.log = origLog;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.warn = origWarn;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.error = origError;
+        bar.update(100, { phase: 'Done' });
+        bar.stop();
+        // ── Summary ────────────────────────────────────────────────────
+        const s = result.stats;
+        console.log(`\n  Repository indexed successfully (${totalTime}s)\n`);
+        console.log(`  ${(s.nodes ?? 0).toLocaleString()} nodes | ${(s.edges ?? 0).toLocaleString()} edges | ${s.communities ?? 0} clusters | ${s.processes ?? 0} flows`);
+        console.log(`  ${repoPath}`);
+        try {
+            await fs.access(getGlobalRegistryPath());
+        }
+        catch {
+            console.log(`\n  Tip: Run \`${binName} setup\` to configure MCP for your editor.`);
+        }
+        console.log('');
+    }
+    catch (err) {
+        clearInterval(elapsedTimer);
+        process.removeListener('SIGINT', sigintHandler);
+        console.log = origLog;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.warn = origWarn;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.error = origError;
+        bar.stop();
+        const msg = err.message || String(err);
+        // Registry name-collision from --name (#829) — surface as an
+        // actionable error rather than a generic stack-trace.
+        if (err instanceof RegistryNameCollisionError) {
+            cliError(`\n  Registry name collision:\n` +
+                `    "${err.registryName}" is already used by "${err.existingPath}".\n\n` +
+                `  Options:\n` +
+                `    • Pick a different alias:  ${binName} analyze --name <alias>\n` +
+                `    • Allow the duplicate:     ${binName} analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)\n`, { registryName: err.registryName, existingPath: err.existingPath });
+            process.exitCode = 1;
+            return;
+        }
+        // Finalize invariant failure (#1169) — keep the rich actionable
+        // message intact and write through realStderrWrite so it can't be
+        // erased by a leftover bar refresh on slow terminals.
+        if (err instanceof AnalysisNotFinalizedError) {
+            writeFatalToStderr('Analysis did not finalize', err);
+            realStderrWrite(`\n  Diagnostic checklist:\n` +
+                `    1. Re-run "${binName} analyze" - transient native errors often clear on retry.\n` +
+                `    2. Inspect ${err.storagePath} - a leftover lbug.wal indicates an aborted write.\n` +
+                `    3. If the failure persists, run with NODE_OPTIONS="--max-old-space-size=8192 --trace-exit"\n` +
+                `       and attach the trace to the Arceus issue tracker.\n\n`);
+            process.exitCode = 1;
+            return;
+        }
+        // HF download failure — show clean guidance without the raw stack trace.
+        // Checked before writeFatalToStderr so the user sees one focused message
+        // rather than a stack-trace dump followed by a second remediation block.
+        if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
+            cliError(`  The embedding model could not be downloaded.\n` +
+                `  huggingface.co may be unreachable from your network\n` +
+                `  (e.g. behind a corporate proxy or a regional firewall).\n` +
+                `  Suggestions:\n` +
+                `    1. Set HF_ENDPOINT to a mirror and retry:\n` +
+                `         HF_ENDPOINT=https://hf-mirror.com npx arceus-s analyze --embeddings\n` +
+                `         (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx arceus-s analyze --embeddings)\n` +
+                `    2. Check your proxy / VPN settings.\n` +
+                `    3. Once downloaded the model is cached — future runs work offline.\n`, { recoveryHint: 'hf-endpoint-unreachable' });
+            process.exitCode = 1;
+            return;
+        }
+        // Bypass the redirected console.error and write the full stack to
+        // the real stderr captured at module load. The redirected
+        // console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)
+        // and forces a bar.update() afterwards, which on some Windows
+        // terminals visually erases the failure message — the canonical
+        // shape of the silent-exit symptom in #1169.
+        writeFatalToStderr('Analysis failed', err);
+        // Provide helpful guidance for known failure modes
+        if (msg.includes('Maximum call stack size exceeded') ||
+            msg.includes('call stack') ||
+            msg.includes('Map maximum size') ||
+            msg.includes('Invalid array length') ||
+            msg.includes('Invalid string length') ||
+            msg.includes('allocation failed') ||
+            msg.includes('heap out of memory') ||
+            msg.includes('JavaScript heap')) {
+            cliError(`  This error typically occurs on very large repositories.\n` +
+                `  Suggestions:\n` +
+                `    1. Add large vendored/generated directories to .arcignore\n` +
+                `    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"\n` +
+                `    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"\n`, { recoveryHint: 'large-repo' });
+        }
+        else if (msg.includes('ERESOLVE') || msg.includes('Could not resolve dependency')) {
+            // Note: the original arborist "Cannot destructure property 'package' of
+            // 'node.target'" crash happens inside npm *before* arc code runs,
+            // so it can't be caught here.  This branch handles dependency-resolution
+            // errors that surface at runtime (e.g. dynamic require failures).
+            cliError(`  This looks like an npm dependency resolution issue.\n` +
+                `  Suggestions:\n` +
+                `    1. Clear the npm cache:    npm cache clean --force\n` +
+                `    2. Update npm:             npm install -g npm@latest\n` +
+                `    3. Reinstall Arceus:       npm install -g arceus-s\n` +
+                `    4. Or try npx directly:    npx arceus-s analyze\n`, { recoveryHint: 'npm-resolution' });
+        }
+        else if (msg.includes('MODULE_NOT_FOUND') ||
+            msg.includes('Cannot find module') ||
+            msg.includes('ERR_MODULE_NOT_FOUND')) {
+            cliError(`  A required module could not be loaded. The installation may be corrupt.\n` +
+                `  Suggestions:\n` +
+                `    1. Reinstall:   npm install -g arceus-s\n` +
+                `    2. Clear cache: npm cache clean --force && npx arceus-s analyze\n`, { recoveryHint: 'module-not-found' });
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // LadybugDB's native module holds open handles that prevent Node from exiting.
+    // ONNX Runtime also registers native atexit hooks that segfault on some
+    // platforms (#38, #40). Force-exit to ensure clean termination.
+    process.exit(0);
+};

package/dist/cli/augment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor postToolUse hooks.
+ *
+ * Usage: arc augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+export declare function augmentCommand(pattern: string): Promise<void>;

package/dist/cli/augment.js

@@ -0,0 +1,33 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor postToolUse hooks.
+ *
+ * Usage: arc augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+import { augment } from '../core/augmentation/engine.js';
+export async function augmentCommand(pattern) {
+    if (!pattern || pattern.length < 3) {
+        process.exit(0);
+    }
+    try {
+        const result = await augment(pattern, process.cwd());
+        if (result) {
+            // IMPORTANT: Write to stderr, NOT stdout.
+            // LadybugDB's native module captures stdout fd at OS level during init,
+            // which makes stdout permanently broken in subprocess contexts.
+            // stderr is never captured, so it works reliably everywhere.
+            // The hook reads from the subprocess's stderr.
+            process.stderr.write(result + '\n');
+        }
+    }
+    catch {
+        // Graceful failure — never break the calling hook
+        process.exit(0);
+    }
+}

package/dist/cli/clean.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Clean Command
+ *
+ * Removes the .arc index from the current repository.
+ * Also unregisters it from the global registry.
+ */
+export declare const cleanCommand: (options?: {
+    force?: boolean;
+    all?: boolean;
+}) => Promise<void>;

package/dist/cli/clean.js

@@ -0,0 +1,79 @@
+/**
+ * Clean Command
+ *
+ * Removes the .arc index from the current repository.
+ * Also unregisters it from the global registry.
+ */
+import fs from 'fs/promises';
+import { logger } from '../core/logger.js';
+import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+export const cleanCommand = async (options) => {
+    // --all flag: clean all indexed repos
+    if (options?.all) {
+        if (!options?.force) {
+            const entries = await listRegisteredRepos();
+            if (entries.length === 0) {
+                console.log('No indexed repositories found.');
+                return;
+            }
+            console.log(`This will delete Arceus indexes for ${entries.length} repo(s):`);
+            for (const entry of entries) {
+                console.log(`  - ${entry.name} (${entry.path})`);
+            }
+            console.log('\nRun with --force to confirm deletion.');
+            return;
+        }
+        const entries = await listRegisteredRepos();
+        for (const entry of entries) {
+            // Safety guard (#1003 review — @magyargergo): same rationale as
+            // remove.ts. `~/.arc/registry.json` is user-writable, so a
+            // corrupted or hand-edited entry could point storagePath at the
+            // repo root, an empty string, or anywhere else — and
+            // fs.rm(recursive: true) on any of those would be catastrophic.
+            // Skip poisoned entries without touching disk, but keep going
+            // through the rest of the registry (preserves the existing
+            // per-repo error-tolerance semantics of `clean --all`).
+            try {
+                assertSafeStoragePath(entry);
+            }
+            catch (err) {
+                if (err instanceof UnsafeStoragePathError) {
+                    logger.error(`Refusing to clean ${entry.name}: ${err.message}`);
+                    continue;
+                }
+                throw err;
+            }
+            try {
+                await fs.rm(entry.storagePath, { recursive: true, force: true });
+                await unregisterRepo(entry.path);
+                console.log(`Deleted: ${entry.name} (${entry.storagePath})`);
+            }
+            catch (err) {
+                logger.error({ err }, `Failed to delete ${entry.name}:`);
+            }
+        }
+        return;
+    }
+    // Default: clean current repo
+    const cwd = process.cwd();
+    const repo = await findRepo(cwd);
+    if (!repo) {
+        console.log('No indexed repository found in this directory.');
+        return;
+    }
+    const repoName = repo.repoPath.split(/[/\\]/).pop() || repo.repoPath;
+    if (!options?.force) {
+        console.log(`This will delete the Arceus index for: ${repoName}`);
+        console.log(`   Path: ${repo.storagePath}`);
+        console.log('\nRun with --force to confirm deletion.');
+        return;
+    }
+    try {
+        await fs.rm(repo.storagePath, { recursive: true, force: true });
+        await unregisterRepo(repo.repoPath);
+        console.log(`Deleted: ${repo.storagePath}`);
+    }
+    catch (err) {
+        logger.error({ err }, 'Failed to delete:');
+    }
+};