@shrkcrft/cli 0.1.0-alpha.11 → 0.1.0-alpha.12

package/dist/commands/watch.command.js

@@ -0,0 +1,456 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch as fsWatch, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildTaskPacket, inspectSharkcraft } from '@shrkcrft/inspector';
+import { SemanticIndex, buildFocusedContext, classifyTask, parseTaskTypeOverride, } from '@shrkcrft/embeddings';
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+const FEED_DIR = nodePath.join('.sharkcraft', 'feed');
+const DEFAULT_DEBOUNCE_MS = 750;
+const DEFAULT_INTERVAL_MS = 0; // off by default; --interval to enable
+const MANIFEST_SCHEMA = 'sharkcraft.shrk-watch-manifest/v1';
+function manifestPath(cwd, slug) {
+    return nodePath.join(cwd, FEED_DIR, `${slug}.pid.json`);
+}
+function readManifest(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const m = JSON.parse(readFileSync(path, 'utf8'));
+        if (m.schema !== MANIFEST_SCHEMA || typeof m.pid !== 'number')
+            return null;
+        return m;
+    }
+    catch {
+        return null;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `shrk watch "<task>"` — emit a fresh task-focused context bundle on
+ * stdout JSONL each time the workspace changes.
+ *
+ * Designed to run in a terminal *next to* Claude Code so the agent has
+ * a continuously-refreshed "feed" of the most relevant code for the
+ * current task — no extra LLM calls, just BGE-ranked deltas.
+ *
+ * Surfaces:
+ *   - stdout: one JSON line per packet, NDJSON-style.
+ *   - filesystem: same packet appended to
+ *     `.sharkcraft/feed/<slug>.jsonl` so other tools (or the user)
+ *     can tail it from elsewhere.
+ *
+ * Cost: every emission is O(BGE-search + re-rank) — typically
+ * 100–300 ms for ~10 candidate files. We never call a generative LLM.
+ */
+export const watchCommand = {
+    name: 'watch',
+    description: 'Emit a focused-context packet on stdout JSONL each time the workspace changes (or every --interval seconds). No LLM calls.',
+    usage: 'shrk watch "<task>" [--interval N] [--debounce ms] [--task-type <type>] [--once] [--quiet] [--json]',
+    async run(args) {
+        const task = args.positional.join(' ').trim();
+        if (!task) {
+            process.stderr.write('Usage: shrk watch "<task>" [--interval N] [--once] [--debounce ms]\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const once = flagBool(args, 'once');
+        const quiet = flagBool(args, 'quiet') || flagBool(args, 'json');
+        const debounceMs = flagNumber(args, 'debounce') ?? DEFAULT_DEBOUNCE_MS;
+        const intervalSec = flagNumber(args, 'interval') ?? 0;
+        const intervalMs = intervalSec > 0 ? intervalSec * 1000 : DEFAULT_INTERVAL_MS;
+        const overrideRaw = flagString(args, 'task-type');
+        const taskTypeOverride = parseTaskTypeOverride(overrideRaw);
+        const index = await SemanticIndex.tryLoad(cwd);
+        if (!index) {
+            process.stderr.write('[shrk watch] no semantic index — run `shrk smart-context embeddings-build` first.\n');
+            return 1;
+        }
+        const slug = slugify(task);
+        const feedDir = nodePath.join(cwd, FEED_DIR);
+        mkdirSync(feedDir, { recursive: true });
+        const feedPath = nodePath.join(feedDir, `${slug}.jsonl`);
+        const manifestFilePath = manifestPath(cwd, slug);
+        // Daemon manifest check — one watcher per (cwd, slug). Allows the agent
+        // and the human to know which watcher owns which feed, and prevents two
+        // processes from racing on the same JSONL.
+        if (!once) {
+            const existing = readManifest(manifestFilePath);
+            if (existing && isProcessAlive(existing.pid)) {
+                if (flagBool(args, 'replace')) {
+                    try {
+                        process.kill(existing.pid, 'SIGTERM');
+                    }
+                    catch {
+                        // best effort
+                    }
+                    // Give the old process a moment to clean up.
+                    await new Promise((r) => setTimeout(r, 250));
+                }
+                else {
+                    process.stderr.write(`[shrk watch] another watcher is already running for slug "${slug}" (pid ${existing.pid}).\n` +
+                        `  → Use \`shrk watch list\` to see active feeds.\n` +
+                        `  → Use \`shrk watch stop ${slug}\` to stop it.\n` +
+                        `  → Pass --replace to take over.\n`);
+                    return 1;
+                }
+            }
+            else if (existing) {
+                // Stale manifest (pid not alive) — clean up.
+                try {
+                    rmSync(manifestFilePath, { force: true });
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            const manifest = {
+                schema: MANIFEST_SCHEMA,
+                pid: process.pid,
+                slug,
+                task,
+                startedAt: new Date().toISOString(),
+                feedPath,
+                intervalMs,
+                debounceMs,
+            };
+            writeFileSync(manifestFilePath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+        }
+        if (!quiet) {
+            process.stderr.write(`[shrk watch] task: "${task}"\n[shrk watch] feed: ${feedPath}\n[shrk watch] press Ctrl+C to stop.\n`);
+        }
+        let lastHash = '';
+        let lastEmittedAt = 0;
+        const emit = async (reason) => {
+            const packet = await buildPacket({
+                cwd,
+                task,
+                index,
+                taskTypeOverride,
+                reason,
+            });
+            const fingerprint = packet.fingerprint;
+            if (fingerprint === lastHash) {
+                // Same content — skip noisy duplicate emissions.
+                return;
+            }
+            lastHash = fingerprint;
+            lastEmittedAt = Date.now();
+            const line = asJson(packet);
+            process.stdout.write(line + '\n');
+            try {
+                appendFileSync(feedPath, line + '\n', 'utf8');
+            }
+            catch (e) {
+                process.stderr.write(`[shrk watch] feed write failed: ${e.message}\n`);
+            }
+        };
+        // Initial emission.
+        await emit('start');
+        if (once)
+            return 0;
+        let debounceTimer = null;
+        const scheduleEmit = (reason) => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                debounceTimer = null;
+                void emit(reason);
+            }, debounceMs);
+        };
+        const watchers = [];
+        const roots = ['packages', 'examples', 'sharkcraft', 'docs', 'libs']
+            .map((p) => nodePath.join(cwd, p))
+            .filter((abs) => existsSync(abs));
+        for (const root of roots) {
+            try {
+                const w = fsWatch(root, { recursive: true }, (_event, filename) => {
+                    if (!filename)
+                        return;
+                    if (!shouldReactTo(String(filename)))
+                        return;
+                    scheduleEmit(`change:${filename}`);
+                });
+                watchers.push(w);
+            }
+            catch (e) {
+                process.stderr.write(`[shrk watch] could not watch ${root}: ${e.message}\n`);
+            }
+        }
+        // Optional interval-based emission so an idle workspace still
+        // produces fresh packets (handy for "every N seconds, refresh").
+        const intervalHandle = intervalMs > 0
+            ? setInterval(() => {
+                if (Date.now() - lastEmittedAt < intervalMs / 2)
+                    return;
+                scheduleEmit('interval');
+            }, intervalMs)
+            : null;
+        return new Promise((resolve) => {
+            const shutdown = (code) => {
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                if (intervalHandle)
+                    clearInterval(intervalHandle);
+                for (const w of watchers) {
+                    try {
+                        w.close();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                try {
+                    if (existsSync(manifestFilePath)) {
+                        const cur = readManifest(manifestFilePath);
+                        if (cur && cur.pid === process.pid)
+                            rmSync(manifestFilePath, { force: true });
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+                if (!quiet)
+                    process.stderr.write('\n[shrk watch] stopped.\n');
+                resolve(code);
+            };
+            const onSignal = () => shutdown(0);
+            process.once('SIGINT', onSignal);
+            process.once('SIGTERM', onSignal);
+        });
+    },
+};
+/** `shrk watch list` — show all active and stale watch manifests. */
+export const watchListCommand = {
+    name: 'list',
+    description: 'List active shrk-watch daemons by reading manifests in .sharkcraft/feed/.',
+    usage: 'shrk watch list [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const json = flagBool(args, 'json');
+        const dir = nodePath.join(cwd, FEED_DIR);
+        if (!existsSync(dir)) {
+            if (json)
+                process.stdout.write(asJson({ active: [], stale: [] }) + '\n');
+            else
+                process.stdout.write('No watch feeds yet.\n');
+            return 0;
+        }
+        const entries = readdirSync(dir).filter((n) => n.endsWith('.pid.json'));
+        const active = [];
+        const stale = [];
+        for (const name of entries) {
+            const m = readManifest(nodePath.join(dir, name));
+            if (!m)
+                continue;
+            if (isProcessAlive(m.pid)) {
+                let feedSize;
+                try {
+                    feedSize = statSync(m.feedPath).size;
+                }
+                catch {
+                    /* ignore */
+                }
+                active.push({ ...m, ...(feedSize !== undefined ? { feedSize } : {}) });
+            }
+            else {
+                stale.push({ slug: m.slug, pid: m.pid, startedAt: m.startedAt });
+            }
+        }
+        if (json) {
+            process.stdout.write(asJson({ active, stale }) + '\n');
+            return 0;
+        }
+        if (active.length === 0 && stale.length === 0) {
+            process.stdout.write('No watch feeds.\n');
+            return 0;
+        }
+        if (active.length > 0) {
+            process.stdout.write(`Active watchers (${active.length}):\n`);
+            for (const w of active) {
+                process.stdout.write(`  ${w.slug.padEnd(50)}  pid ${String(w.pid).padEnd(8)}  ${w.startedAt}\n    → ${w.feedPath}${w.feedSize !== undefined ? ` (${w.feedSize} bytes)` : ''}\n`);
+            }
+        }
+        if (stale.length > 0) {
+            process.stdout.write(`\nStale manifests (process not alive):\n`);
+            for (const w of stale) {
+                process.stdout.write(`  ${w.slug} (pid ${w.pid}, started ${w.startedAt})\n`);
+            }
+            process.stdout.write('  → Run `shrk watch prune` to clean them up.\n');
+        }
+        return 0;
+    },
+};
+/** `shrk watch stop <slug>` — SIGTERM the matching watcher. */
+export const watchStopCommand = {
+    name: 'stop',
+    description: 'Stop a running shrk-watch daemon by slug (sends SIGTERM and waits for it to exit).',
+    usage: 'shrk watch stop <slug> [--json]',
+    async run(args) {
+        const slug = args.positional[0]?.trim();
+        if (!slug) {
+            process.stderr.write('Usage: shrk watch stop <slug>\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const json = flagBool(args, 'json');
+        const path = manifestPath(cwd, slug);
+        const m = readManifest(path);
+        if (!m) {
+            if (json)
+                process.stdout.write(asJson({ status: 'not-found', slug }) + '\n');
+            else
+                process.stderr.write(`No watcher manifest found for slug "${slug}".\n`);
+            return 1;
+        }
+        if (!isProcessAlive(m.pid)) {
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                /* ignore */
+            }
+            if (json)
+                process.stdout.write(asJson({ status: 'stale', slug, pid: m.pid }) + '\n');
+            else
+                process.stdout.write(`Watcher for "${slug}" was stale (pid ${m.pid}); cleaned up manifest.\n`);
+            return 0;
+        }
+        try {
+            process.kill(m.pid, 'SIGTERM');
+        }
+        catch (e) {
+            process.stderr.write(`Failed to signal pid ${m.pid}: ${e.message}\n`);
+            return 1;
+        }
+        // Wait briefly for the process to exit and clean its own manifest.
+        for (let i = 0; i < 20; i += 1) {
+            await new Promise((r) => setTimeout(r, 100));
+            if (!isProcessAlive(m.pid))
+                break;
+        }
+        if (json)
+            process.stdout.write(asJson({ status: 'stopped', slug, pid: m.pid }) + '\n');
+        else
+            process.stdout.write(`Stopped watcher "${slug}" (pid ${m.pid}).\n`);
+        return 0;
+    },
+};
+/** `shrk watch prune` — remove stale manifests. */
+export const watchPruneCommand = {
+    name: 'prune',
+    description: 'Remove stale shrk-watch manifests (pid not alive). Safe to run anytime.',
+    usage: 'shrk watch prune [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const json = flagBool(args, 'json');
+        const dir = nodePath.join(cwd, FEED_DIR);
+        if (!existsSync(dir)) {
+            if (json)
+                process.stdout.write(asJson({ removed: [] }) + '\n');
+            else
+                process.stdout.write('No feed directory; nothing to prune.\n');
+            return 0;
+        }
+        const removed = [];
+        for (const name of readdirSync(dir).filter((n) => n.endsWith('.pid.json'))) {
+            const path = nodePath.join(dir, name);
+            const m = readManifest(path);
+            if (!m || !isProcessAlive(m.pid)) {
+                try {
+                    rmSync(path, { force: true });
+                    removed.push(m?.slug ?? name);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        if (json)
+            process.stdout.write(asJson({ removed }) + '\n');
+        else
+            process.stdout.write(removed.length === 0 ? 'No stale manifests.\n' : `Pruned: ${removed.join(', ')}\n`);
+        return 0;
+    },
+};
+async function buildPacket(input) {
+    const inspection = await inspectSharkcraft({ cwd: input.cwd });
+    const packet = buildTaskPacket(inspection, input.task, { maxTokens: 3500 });
+    const focused = await buildFocusedContext({
+        cwd: input.cwd,
+        task: input.task,
+        index: input.index,
+        rules: packet.relevantRules,
+        verificationCommands: packet.verificationCommands,
+    });
+    const taskType = input.taskTypeOverride ?? classifyTask(input.task).type;
+    const summarisedFiles = focused.files.map((f) => ({
+        path: f.path,
+        fileSimilarity: f.fileSimilarity,
+        summary: f.summary,
+        blocks: f.blocks.map((b) => ({
+            name: b.name,
+            kind: b.kind,
+            startLine: b.startLine,
+            similarity: b.similarity,
+        })),
+    }));
+    // Fingerprint = which files + their similarities + which blocks ranked.
+    // Same diff round-trip = same fingerprint = no re-emission.
+    const fp = createHash('sha1')
+        .update(JSON.stringify({ taskType, files: summarisedFiles }))
+        .digest('hex')
+        .slice(0, 16);
+    return {
+        schema: 'sharkcraft.shrk-watch-packet/v1',
+        task: input.task,
+        taskSlug: slugify(input.task),
+        taskType,
+        emittedAt: new Date().toISOString(),
+        reason: input.reason,
+        fingerprint: fp,
+        focused: {
+            model: focused.model,
+            approxTokens: focused.approxTokens,
+            files: focused.files,
+            rules: focused.rules,
+            docHits: focused.docHits,
+            verificationCommands: focused.verificationCommands,
+        },
+        hints: {
+            pull: 'shrk smart-context "<task>" --focused --tiny-only --json',
+            plan: 'shrk smart-context "<task>" --focused --plan --save',
+            spike: 'shrk spike <slug>',
+        },
+    };
+}
+function shouldReactTo(filename) {
+    if (filename.startsWith('.git/'))
+        return false;
+    if (filename.includes('node_modules/'))
+        return false;
+    if (filename.includes('/dist/') || filename.endsWith('/dist'))
+        return false;
+    if (filename.includes('.sharkcraft/'))
+        return false; // never feed our own writes back in
+    if (filename.includes('.next/'))
+        return false;
+    if (/\.(ts|tsx|js|jsx|mjs|cjs|md|json|yml|yaml)$/.test(filename))
+        return true;
+    return false;
+}
+function slugify(s) {
+    return (s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-+|-+$)/g, '')
+        .slice(0, 60) || 'task');
+}

package/dist/env/load-dotenv.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal `.env` loader for the Node-based `shrk` binary.
+ *
+ * Bun auto-loads `.env`; Node does not. This walks from `cwd` up to the
+ * filesystem root looking for a `.env` file and merges any KEY=VALUE
+ * pairs into `process.env` — but only when the key is not already set,
+ * so an actual shell export always wins.
+ *
+ * No dependency on `dotenv`. Parser is intentionally small: lines that
+ * start with `#` are comments, blank lines are skipped, surrounding
+ * single/double quotes on the value are stripped, and escaped `\n`
+ * sequences inside double-quoted values become real newlines.
+ */
+export declare function loadDotenv(startDir: string): void;
+//# sourceMappingURL=load-dotenv.d.ts.map

package/dist/env/load-dotenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-dotenv.d.ts","sourceRoot":"","sources":["../../src/env/load-dotenv.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAmBjD"}

package/dist/env/load-dotenv.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+/**
+ * Minimal `.env` loader for the Node-based `shrk` binary.
+ *
+ * Bun auto-loads `.env`; Node does not. This walks from `cwd` up to the
+ * filesystem root looking for a `.env` file and merges any KEY=VALUE
+ * pairs into `process.env` — but only when the key is not already set,
+ * so an actual shell export always wins.
+ *
+ * No dependency on `dotenv`. Parser is intentionally small: lines that
+ * start with `#` are comments, blank lines are skipped, surrounding
+ * single/double quotes on the value are stripped, and escaped `\n`
+ * sequences inside double-quoted values become real newlines.
+ */
+export function loadDotenv(startDir) {
+    const envPath = findEnvFile(startDir);
+    if (!envPath)
+        return;
+    let body;
+    try {
+        body = readFileSync(envPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    for (const rawLine of body.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!isValidKey(key))
+            continue;
+        if (process.env[key] !== undefined)
+            continue;
+        process.env[key] = unquote(line.slice(eq + 1).trim());
+    }
+}
+function isValidKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+function unquote(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if (first === '"' && last === '"') {
+            return value.slice(1, -1).replace(/\\n/g, '\n').replace(/\\r/g, '\r').replace(/\\t/g, '\t');
+        }
+        if (first === "'" && last === "'") {
+            return value.slice(1, -1);
+        }
+    }
+    const hash = value.indexOf(' #');
+    return hash === -1 ? value : value.slice(0, hash).trimEnd();
+}
+function findEnvFile(startDir) {
+    let dir = nodePath.resolve(startDir);
+    while (true) {
+        const candidate = nodePath.join(dir, '.env');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = nodePath.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EACL,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAmW/B,wBAAgB,aAAa,IAAI,eAAe,CAqW/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAkGD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAgX/B,wBAAgB,aAAa,IAAI,eAAe,CAmX/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAkGD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}

package/dist/main.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { loadDotenv } from "./env/load-dotenv.js";
 import { CommandRegistry, extractGlobalCwd, parseArgs, } from "./command-registry.js";
 import { initCommand } from "./commands/init.command.js";
 import { inspectCommand } from "./commands/inspect.command.js";
@@ -55,6 +56,12 @@ import { dashboardCommand } from "./commands/dashboard.command.js";
 import { dashboardDiffCommand, dashboardExportCommand, } from "./commands/dashboard-export.command.js";
 import { importCommand } from "./commands/import.command.js";
 import { askCommand } from "./commands/ask.command.js";
+import { smartContextCommand, smartContextEmbeddingsBuildCommand, smartContextEmbeddingsStatusCommand, smartContextListCommand, smartContextPlanAheadCommand, smartContextShowCommand, } from "./commands/smart-context.command.js";
+import { spikeCommand } from "./commands/spike.command.js";
+import { depsAuditCommand } from "./commands/deps-audit.command.js";
+import { scaffoldValidateCommand } from "./commands/scaffold-validate.command.js";
+import { movePlanCommand } from "./commands/move-plan.command.js";
+import { watchCommand, watchListCommand, watchPruneCommand, watchStopCommand } from "./commands/watch.command.js";
 import { mcpCommand } from "./commands/mcp.command.js";
 import { versionCommand } from "./commands/version.command.js";
 import { makeHelpCommand } from "./commands/help.command.js";
@@ -204,6 +211,20 @@ export function buildRegistry() {
     registry.register(planParentCommand);
     registry.register(devCommand);
     registry.register(askCommand);
+    registry.register(smartContextCommand);
+    registry.registerSubcommand('smart-context', smartContextPlanAheadCommand);
+    registry.registerSubcommand('smart-context', smartContextListCommand);
+    registry.registerSubcommand('smart-context', smartContextShowCommand);
+    registry.registerSubcommand('smart-context', smartContextEmbeddingsBuildCommand);
+    registry.registerSubcommand('smart-context', smartContextEmbeddingsStatusCommand);
+    registry.register(spikeCommand);
+    registry.register(depsAuditCommand);
+    registry.register(scaffoldValidateCommand);
+    registry.register(movePlanCommand);
+    registry.register(watchCommand);
+    registry.registerSubcommand('watch', watchListCommand);
+    registry.registerSubcommand('watch', watchStopCommand);
+    registry.registerSubcommand('watch', watchPruneCommand);
     registry.register(mcpCommand);
     registry.register(versionCommand);
     registry.register(qualityCommand);
@@ -804,9 +825,69 @@ if (isMain ||
     entryPath.endsWith('shrk') ||
     entryPath.endsWith('shrk.js') ||
     entryPath.endsWith('shrk.cmd')) {
+    loadDotenv(process.cwd());
     const argv = process.argv.slice(2);
-    runCli(argv).then((code) => process.exit(code), (err) => {
+    const cleanShutdown = async (code) => {
+        // Best-effort teardown of shared native runtimes. Without this,
+        // commands that loaded native libs (ONNX via embeddings; Metal
+        // via node-llama-cpp) abort during `process.exit` AFTER the
+        // work completed — the user sees their result then `zsh: abort`.
+        // Dynamic imports keep these off the hot path for commands that
+        // never touched them.
+        try {
+            const mod = (await import('@shrkcrft/embeddings'));
+            if (typeof mod.disposeSemanticIndexPipeline === 'function') {
+                await mod.disposeSemanticIndexPipeline();
+            }
+        }
+        catch {
+            // Best-effort; never block the exit on teardown failure.
+        }
+        try {
+            const mod = (await import('@shrkcrft/ai'));
+            if (typeof mod.disposeLlamaCppRuntime === 'function') {
+                await mod.disposeLlamaCppRuntime();
+            }
+        }
+        catch {
+            // Best-effort.
+        }
+        // Flush stdio synchronously before bypassing C++ destructors.
+        // `_exit` skips all libc finalizers, which is exactly what we
+        // need (see below), but it also doesn't wait for buffered
+        // writes to drain. Two synchronous write callbacks force the
+        // current buffers through.
+        try {
+            await new Promise((resolve) => process.stdout.write('', () => resolve()));
+            await new Promise((resolve) => process.stderr.write('', () => resolve()));
+        }
+        catch {
+            // ignore flush failures
+        }
+        // Prefer `_exit` over `exit` on Node. Even after our explicit
+        // disposes above, node-llama-cpp's libggml-metal destructor
+        // still aborts in `__cxa_finalize_ranges` because the Metal
+        // device list isn't drained by the current dispose API
+        // (`GGML_ASSERT([rsets->data count] == 0)` fires from
+        // `ggml_metal_device_free`, surfacing as `zsh: abort` AFTER
+        // the user's result has already printed). `process._exit`
+        // skips the libc++ static-destructor pass entirely, which is
+        // safe here because we have already torn down the runtimes
+        // we care about above and the OS will reclaim the rest.
+        //
+        // Bun's process object doesn't expose `_exit`, but Bun also
+        // doesn't drive shutdown through libuv + libc++ static
+        // destructors the same way Node does, so the Metal crash
+        // doesn't reproduce there. Fall back to `process.exit` when
+        // `_exit` is unavailable.
+        const lowLevelExit = process._exit;
+        if (typeof lowLevelExit === 'function') {
+            lowLevelExit(code);
+        }
+        process.exit(code);
+    };
+    runCli(argv).then((code) => cleanShutdown(code), (err) => {
         process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
-        process.exit(1);
+        return cleanShutdown(1);
     });
 }