@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/commands/dashboard.js

@@ -0,0 +1,52 @@
+/**
+ * unerr dashboard — open the local intelligence dashboard in the default browser.
+ *
+ * Reads `.unerr/state/server.json` written by the in-process Hono server when the
+ * proxy starts. If the proxy is not running, the file is absent and this command
+ * explains how to start it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { openUrlInDefaultBrowser } from "../utils/exec.js";
+import { isGitRepo } from "../utils/git.js";
+import { startupLog } from "../utils/startup-log.js";
+function readServerJson(cwd) {
+    const p = join(cwd, ".unerr", "state", "server.json");
+    if (!existsSync(p))
+        return null;
+    try {
+        const raw = readFileSync(p, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function registerDashboardCommand(program) {
+    program
+        .command("dashboard")
+        .description("Open the local web dashboard in your browser")
+        .action(async () => {
+        const cwd = process.cwd();
+        if (!(await isGitRepo(cwd))) {
+            startupLog.error("Not inside a git repository. Run from your project root.");
+            process.exit(1);
+        }
+        const server = readServerJson(cwd);
+        if (!server?.url) {
+            startupLog.warn("No dashboard metadata found.");
+            startupLog.detail("Start the proxy with: unerr");
+            startupLog.detail("The dashboard URL appears when the HTTP server binds.");
+            process.exit(1);
+        }
+        try {
+            await openUrlInDefaultBrowser(server.url);
+            startupLog.done(`Opened ${server.url}`);
+        }
+        catch (err) {
+            startupLog.error(err instanceof Error ? err.message : "Could not open browser.");
+            startupLog.detail(`Open manually: ${server.url}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/debug.js

@@ -0,0 +1,200 @@
+/**
+ * unerr debug — Diagnostics dump for support.
+ *
+ * Outputs: Node version, CLI version, OS, .unerr/ directory listing,
+ * CozoDB file sizes, proxy PID status, credentials status (redacted),
+ * git context, MCP config location, last 20 lines of proxy log.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { arch, homedir, platform, release } from "node:os";
+import { join } from "node:path";
+import { getCurrentBranch, getRemoteUrl } from "../utils/git.js";
+const UNERR_DIR = join(homedir(), ".unerr");
+export function registerDebugCommand(program) {
+    program
+        .command("debug")
+        .description("Diagnostics dump for support")
+        .action(async () => {
+        const sections = [];
+        // Header
+        sections.push("=== unerr debug ===\n");
+        // System info
+        sections.push("## System");
+        sections.push(`  Node:     ${process.version}`);
+        sections.push(`  OS:       ${platform()} ${release()} ${arch()}`);
+        sections.push("  CLI:      0.1.0");
+        sections.push("");
+        // Settings
+        sections.push("## Settings");
+        const settingsPath = join(UNERR_DIR, "settings.json");
+        if (existsSync(settingsPath)) {
+            try {
+                const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+                for (const [key, value] of Object.entries(settings)) {
+                    if (key === "anthropicApiKey" && typeof value === "string") {
+                        sections.push(`  ${key}: ${value.slice(0, 8)}...`);
+                    }
+                    else {
+                        sections.push(`  ${key}: ${String(value)}`);
+                    }
+                }
+            }
+            catch {
+                sections.push("  (unreadable)");
+            }
+        }
+        else {
+            sections.push("  (not found)");
+        }
+        sections.push("");
+        // Git context
+        sections.push("## Git Context");
+        const cwd = process.cwd();
+        const remote = await getRemoteUrl(cwd);
+        const branch = await getCurrentBranch(cwd);
+        sections.push(`  Remote:   ${remote ?? "(none)"}`);
+        sections.push(`  Branch:   ${branch ?? "(detached)"}`);
+        sections.push("");
+        // .unerr/config.json
+        sections.push("## Project Config (.unerr/config.json)");
+        const configPath = join(process.cwd(), ".unerr", "config.json");
+        if (existsSync(configPath)) {
+            try {
+                const config = JSON.parse(readFileSync(configPath, "utf-8"));
+                for (const [key, value] of Object.entries(config)) {
+                    sections.push(`  ${key}: ${String(value)}`);
+                }
+            }
+            catch {
+                sections.push("  (unreadable)");
+            }
+        }
+        else {
+            sections.push("  (not found)");
+        }
+        sections.push("");
+        // Proxy PID
+        sections.push("## Proxy Status");
+        const pidPath = join(process.cwd(), ".unerr", "state", "proxy.pid");
+        if (existsSync(pidPath)) {
+            try {
+                const pid = Number.parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
+                let alive = false;
+                try {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+                catch {
+                    /* not alive */
+                }
+                sections.push(`  PID:      ${pid} (${alive ? "RUNNING" : "STALE"})`);
+            }
+            catch {
+                sections.push("  PID:      (unreadable)");
+            }
+        }
+        else {
+            sections.push("  PID:      (not running)");
+        }
+        sections.push("");
+        // .unerr/ directory listing (repo-local)
+        sections.push("## .unerr/ Directory (repo-local)");
+        const localUnerrDir = join(process.cwd(), ".unerr");
+        if (existsSync(localUnerrDir)) {
+            listDir(localUnerrDir, "  ", sections, 0, 2);
+        }
+        else {
+            sections.push("  (not found)");
+        }
+        sections.push("");
+        // Snapshot sizes
+        sections.push("## Snapshots");
+        const snapshotsDir = join(localUnerrDir, "snapshots");
+        if (existsSync(snapshotsDir)) {
+            const files = readdirSync(snapshotsDir);
+            if (files.length === 0) {
+                sections.push("  (empty)");
+            }
+            for (const file of files) {
+                const filePath = join(snapshotsDir, file);
+                const stat = statSync(filePath);
+                sections.push(`  ${file}: ${formatBytes(stat.size)}`);
+            }
+        }
+        else {
+            sections.push("  (no snapshots directory)");
+        }
+        sections.push("");
+        // MCP config locations
+        sections.push("## MCP Config Locations");
+        const mcpLocations = [
+            join(process.cwd(), ".cursor", "mcp.json"),
+            join(process.cwd(), ".vscode", "mcp.json"),
+            join(homedir(), ".claude", "claude_desktop_config.json"),
+            join(homedir(), "Library", "Application Support", "Cursor", "User", "globalStorage", "cursor.mcp", "mcp.json"),
+        ];
+        for (const loc of mcpLocations) {
+            const exists = existsSync(loc);
+            sections.push(`  ${exists ? "[x]" : "[ ]"} ${loc.replace(homedir(), "~")}`);
+        }
+        sections.push("");
+        // Last 20 lines of proxy log
+        sections.push("## Recent Log (last 20 lines)");
+        const logsDir = join(process.cwd(), ".unerr", "logs");
+        if (existsSync(logsDir)) {
+            const logFiles = readdirSync(logsDir)
+                .filter((f) => f.endsWith(".log"))
+                .sort()
+                .reverse();
+            if (logFiles.length > 0 && logFiles[0]) {
+                const logPath = join(logsDir, logFiles[0]);
+                try {
+                    const content = readFileSync(logPath, "utf-8");
+                    const lines = content.split("\n").filter(Boolean);
+                    const last20 = lines.slice(-20);
+                    for (const line of last20) {
+                        sections.push(`  ${line}`);
+                    }
+                }
+                catch {
+                    sections.push("  (unreadable)");
+                }
+            }
+            else {
+                sections.push("  (no log files)");
+            }
+        }
+        else {
+            sections.push("  (no logs directory)");
+        }
+        // Output to stderr (stdout is reserved for MCP)
+        console.error(sections.join("\n"));
+    });
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function listDir(dirPath, indent, out, depth, maxDepth) {
+    if (depth > maxDepth)
+        return;
+    try {
+        const entries = readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                out.push(`${indent}${entry.name}/`);
+                listDir(join(dirPath, entry.name), `${indent}  `, out, depth + 1, maxDepth);
+            }
+            else {
+                const size = formatBytes(statSync(join(dirPath, entry.name)).size);
+                out.push(`${indent}${entry.name} (${size})`);
+            }
+        }
+    }
+    catch {
+        out.push(`${indent}(permission denied)`);
+    }
+}

package/dist/commands/enrich.js

@@ -0,0 +1,184 @@
+/**
+ * `unerr enrich` — BYO-LLM Business Context Generation (Sprint L8.2).
+ *
+ * Uses the local LLM chat endpoint to generate `purpose`, `taxonomy`, and
+ * `feature_area` for entities that lack business context. Results are stored
+ * in the CozoDB `justifications` relation so `get_business_context` returns
+ * enriched data.
+ *
+ * This is opt-in (never runs automatically) per Decision TL.11.
+ */
+// ── Prompt Builder ─────────────────────────────────────────────
+function buildEnrichmentPrompt(entities) {
+    const entityBlock = entities
+        .map((e, i) => `[${i + 1}] ${e.kind} "${e.name}" in ${e.filePath}\n    Signature: ${e.signature || "(none)"}`)
+        .join("\n");
+    return `You are a code analysis assistant. For each code entity below, generate:
+1. **purpose**: A single sentence describing what this entity does and why it exists.
+2. **taxonomy**: A domain category (e.g., "authentication", "data-access", "ui-rendering", "error-handling", "configuration", "testing", "api-integration").
+3. **feature_area**: The product feature area this entity belongs to (e.g., "user-auth", "payment-processing", "dashboard", "notifications").
+
+Respond with a JSON array. Each element must have: { "index": <number>, "purpose": "<string>", "taxonomy": "<string>", "feature_area": "<string>" }
+
+Entities:
+${entityBlock}
+
+Respond ONLY with the JSON array, no other text.`;
+}
+// ── Response Parser ────────────────────────────────────────────
+function parseEnrichmentResponse(text, count) {
+    // Extract JSON array from response (may be wrapped in markdown code blocks)
+    const jsonMatch = text.match(/\[[\s\S]*\]/);
+    if (!jsonMatch) {
+        return Array.from({ length: count }, () => ({
+            purpose: "",
+            taxonomy: "unknown",
+            feature_area: "unknown",
+        }));
+    }
+    try {
+        const parsed = JSON.parse(jsonMatch[0]);
+        // Map by index (1-based) or by position
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            const entry = parsed.find((p) => p.index === i + 1) ?? parsed[i] ?? {};
+            results.push({
+                purpose: entry.purpose ?? "",
+                taxonomy: entry.taxonomy ?? "unknown",
+                feature_area: entry.feature_area ?? "unknown",
+            });
+        }
+        return results;
+    }
+    catch {
+        return Array.from({ length: count }, () => ({
+            purpose: "",
+            taxonomy: "unknown",
+            feature_area: "unknown",
+        }));
+    }
+}
+// ── Core Enrichment Logic ──────────────────────────────────────
+export async function runEnrich(opts) {
+    const cwd = process.cwd();
+    // 1. Load settings + verify BYO-LLM
+    const { loadSettings } = await import("../config/settings.js");
+    const settings = loadSettings(cwd);
+    if (!settings.localLlm) {
+        process.stderr.write("[unerr] Error: BYO-LLM required for enrichment.\n" +
+            "[unerr] Configure localLlm in ~/.unerr/settings.json:\n" +
+            '[unerr]   { "localLlm": { "provider": "ollama", "chatModel": "llama3" } }\n');
+        process.exit(1);
+    }
+    // 2. Load persistent graph
+    const { openPersistentDb, hasPersistedGraph } = await import("../intelligence/persistent-db.js");
+    if (!hasPersistedGraph(cwd)) {
+        process.stderr.write("[unerr] No persistent graph found. Run 'unerr index' first.\n");
+        process.exit(1);
+    }
+    const { CozoGraphStore } = await import("../intelligence/local-graph.js");
+    const { db } = await openPersistentDb(cwd);
+    const graph = await CozoGraphStore.create(db);
+    // 3. Get entities without justifications (or all if --force)
+    let entities;
+    if (opts.force) {
+        const result = await db.run("?[key, kind, name, file_path, signature] := *entities{key, kind, name, file_path, signature}");
+        entities = result.rows.map((row) => ({
+            key: row[0],
+            kind: row[1],
+            name: row[2],
+            filePath: row[3],
+            signature: row[4],
+        }));
+    }
+    else {
+        // Entities that DON'T have a justification yet
+        const result = await db.run(`?[key, kind, name, file_path, signature] :=
+        *entities{key, kind, name, file_path, signature},
+        not *justifications{entity_key: key}`);
+        entities = result.rows.map((row) => ({
+            key: row[0],
+            kind: row[1],
+            name: row[2],
+            filePath: row[3],
+            signature: row[4],
+        }));
+    }
+    if (opts.limit && opts.limit > 0) {
+        entities = entities.slice(0, opts.limit);
+    }
+    if (entities.length === 0) {
+        process.stderr.write("[unerr] All entities already have business context. Use --force to re-enrich.\n");
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify({ enriched: 0, total: 0, skipped: true })}\n`);
+        }
+        return;
+    }
+    process.stderr.write(`[unerr] Enriching ${entities.length} entities via ${settings.localLlm.chatModel ?? settings.localLlm.provider}...\n`);
+    // 4. Create chat provider for LLM calls
+    const { LocalChatProvider } = await import("../core/local-chat-provider.js");
+    const chatProvider = new LocalChatProvider(settings.localLlm);
+    // 5. Process in batches
+    const t0 = performance.now();
+    let enriched = 0;
+    const batchSize = opts.batchSize;
+    for (let i = 0; i < entities.length; i += batchSize) {
+        const batch = entities.slice(i, i + batchSize);
+        const prompt = buildEnrichmentPrompt(batch);
+        try {
+            const response = await chatProvider.streamChat([{ role: "user", content: prompt }], [], "You are a precise code analysis assistant. Always respond with valid JSON.", 4096, () => { } // No streaming UI needed for enrichment
+            );
+            const results = parseEnrichmentResponse(response.text, batch.length);
+            for (let j = 0; j < batch.length; j++) {
+                const entity = batch[j];
+                const result = results[j];
+                if (!entity || !result)
+                    continue;
+                await graph.loadJustifications([
+                    {
+                        entity_key: entity.key,
+                        purpose: result.purpose,
+                        taxonomy: result.taxonomy,
+                        feature_area: result.feature_area,
+                        confidence: 0.7, // local LLM confidence
+                    },
+                ]);
+                enriched++;
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[unerr] Batch ${Math.floor(i / batchSize) + 1} failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        process.stderr.write(`[unerr] Enriched ${enriched}/${entities.length} entities...\n`);
+    }
+    const elapsed = ((performance.now() - t0) / 1000).toFixed(1);
+    // Justifications are persisted directly in CozoDB — no snapshot re-export needed.
+    process.stderr.write(`[unerr] Enrichment complete: ${enriched} entities via ${settings.localLlm.chatModel ?? settings.localLlm.provider} in ${elapsed}s\n`);
+    process.stderr.write("[unerr]   get_business_context now returns full context for enriched entities\n");
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({
+            enriched,
+            total: entities.length,
+            model: settings.localLlm.chatModel,
+            elapsedSeconds: Number.parseFloat(elapsed),
+        })}\n`);
+    }
+}
+// ── Commander Registration ─────────────────────────────────────
+export function registerEnrichCommand(program) {
+    program
+        .command("enrich")
+        .description("Generate business context (purpose, taxonomy, feature_area) for code entities via BYO-LLM")
+        .option("--batch-size <n>", "Entities per LLM batch", "10")
+        .option("--limit <n>", "Max entities to enrich")
+        .option("--force", "Re-enrich already-enriched entities")
+        .option("--json", "Output results as JSON")
+        .action(async (opts) => {
+        await runEnrich({
+            batchSize: Number.parseInt(opts.batchSize, 10) || 10,
+            limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
+            force: opts.force,
+            json: opts.json,
+        });
+    });
+}

package/dist/commands/exec.js

@@ -0,0 +1,233 @@
+/**
+ * `unerr exec -- <shell command>` — run via bash, compress stdout (Layer 6 FE-D).
+ *
+ * Supports two invocation modes:
+ *   unerr exec -- <shell command>       (legacy, argv-joined)
+ *   unerr exec --b64 <base64-string>    (preferred, lossless encoding)
+ *
+ * On shell parse errors, falls back to raw output so compression
+ * never breaks the underlying command execution.
+ */
+import { formatDriftNudge, isDriftCommand } from "../proxy/drift-detector.js";
+import { readNudgeState, updateNudgeState } from "../proxy/nudge-state.js";
+import { compressShellOutput } from "../proxy/shell-compressor.js";
+import { exec } from "../utils/exec.js";
+import { initFileLog, startupLog } from "../utils/startup-log.js";
+// ── Exec nudge — rotating tool adoption reminder appended to stdout ──
+// Rotating tool-adoption reminders. Each line follows the "why → what → when"
+// pattern: leads with the benefit/category, then names the MCP tools that fill
+// that slot. Tight enough that rotation across Bash calls teaches the toolset
+// without repeating wallpaper.
+const EXEC_NUDGES = [
+    // #5 TRIM — code navigation set
+    "[unerr] Code nav (<5ms, graph-backed): search_code · get_references · file_read",
+    // #6 TRIM — read protocol set
+    "[unerr] Read code: file_read (Read built-in: only pre-Edit) · Search: search_code (not grep) · Structure: file_outline",
+    // #7 TRIM — entity / convention / fact set
+    "[unerr] Entity details: get_entity · Before writing: get_conventions · For prior decisions: recall_facts",
+    // #8 KEEP — pre-edit nudge already tight, why+what clear
+    "[unerr] Before editing: get_references to check callers. get_critical_nodes for chokepoint awareness.",
+    // #9 TRIM — structural analysis set, with when-tags per tool for discoverability
+    "[unerr] Structure: get_critical_nodes (chokepoints) · get_cross_boundary_links (surprise coupling) · file_connections · get_test_coverage · get_project_stats",
+    // #10 TRIM — narrative markers with when-tags
+    "[unerr] Markers: mark_intent (task start) · mark_decision (choice) · mark_blocker (stuck) · mark_resolution (fixed) — power timeline + resume",
+];
+/**
+ * Append a brief tool adoption nudge to stdout (Nudge v2).
+ *
+ * Three universal gates apply BEFORE any tier (N4):
+ *   1. UNERR_QUIET / CI — silent (kept verbatim from v1).
+ *   2. Zero-output gate — empty/whitespace command output → silent.
+ *      Kills the "clean eslint" case where nudge would be the entire output.
+ *   3. Size gate — `nudge.length > 0.1 × output.length` → silent.
+ *      Kills the `npm version` case where the nudge is 6.8× the output.
+ *
+ * When `UNERR_NUDGE_V2=1` is set we additionally:
+ *   - Skip the generic rotating nudge entirely.
+ *   - Run the drift detector and emit a targeted, content-specific nudge
+ *     only when the command matches a known drift pattern AND that
+ *     drift kind has not been nudged yet this session.
+ *
+ * v1 behaviour (the rotating generic nudge) remains the default so we
+ * don't regress drift correction rates on existing installs.
+ */
+const NUDGE_MIN_OUTPUT_BYTES = 200; // ≥ 10× the nudge byte-length
+/**
+ * Universal gates applied to ANY nudge (drift or v1 rotating).
+ * The zero-output and quiet gates are always-on. The size gate is applied
+ * only to the v1 rotating nudge (see appendExecNudge) — drift nudges
+ * bypass it because (a) they are rare (once-per-kind-per-session) and
+ * (b) the agent's mistake was the COMMAND choice, not the output volume.
+ * Suppressing drift on small outputs would teach the wrong lesson.
+ */
+function isHardSuppressed(outputBytes) {
+    if (process.env.UNERR_QUIET || process.env.CI)
+        return true;
+    if (outputBytes <= 0)
+        return true; // zero-output silence
+    return false;
+}
+function shouldEmitV1Nudge(outputBytes) {
+    if (isHardSuppressed(outputBytes))
+        return false;
+    if (outputBytes < NUDGE_MIN_OUTPUT_BYTES)
+        return false; // v1-only size gate
+    return true;
+}
+function appendExecNudge(cmd, outputBytes) {
+    // Phase B / N3 — content-specific Tier-1 drift nudge (opt-in flag).
+    // Drift fires regardless of output size; only quiet/zero gates apply.
+    if (process.env.UNERR_NUDGE_V2 === "1") {
+        if (isHardSuppressed(outputBytes))
+            return;
+        const hint = isDriftCommand(cmd);
+        if (!hint)
+            return; // no drift → no nudge
+        const cwd = process.cwd();
+        const state = readNudgeState(cwd);
+        if (state.tier1_emitted_kinds.includes(hint.kind)) {
+            // Already nudged this drift kind once this session; still bump the
+            // counter for Tier-2 escalation but don't print again.
+            updateNudgeState(cwd, (s) => {
+                s.drift_count++;
+            });
+            return;
+        }
+        process.stdout.write(`\n${formatDriftNudge(hint)}\n`);
+        const post = updateNudgeState(cwd, (s) => {
+            s.drift_count++;
+            if (!s.tier1_emitted_kinds.includes(hint.kind)) {
+                s.tier1_emitted_kinds.push(hint.kind);
+            }
+        });
+        // N5 — Tier 2 escalation: 3+ drifts uncorrected → one stronger reminder
+        if (post.drift_count >= 3 &&
+            !post.tier2_emitted &&
+            !post.last_unerr_tool_at) {
+            // Table row #4 TRIM — why (cost) leads, tool roster follows, drop preamble.
+            process.stdout.write(`[unerr] ${post.drift_count}× drift this session — search_code/file_read/get_references cut 10-30× tokens for code-nav\n`);
+            updateNudgeState(cwd, (s) => {
+                s.tier2_emitted = true;
+            });
+        }
+        return;
+    }
+    // v1 default — rotating generic nudge, applies the size gate (the v1
+    // nudge fires on every call, so suppressing it on small outputs prevents
+    // the "nudge bigger than output" UX failure).
+    if (!shouldEmitV1Nudge(outputBytes))
+        return;
+    const nudge = EXEC_NUDGES[Math.floor(Date.now() / 60000) % EXEC_NUDGES.length];
+    process.stdout.write(`\n${nudge}\n`);
+}
+/** Parse argv for tokens after `exec`, optionally after `--`. */
+export function parseExecCommandLine(argv) {
+    const i = argv.indexOf("exec");
+    const rest = i >= 0 ? argv.slice(i + 1) : argv;
+    // --b64 mode: next token is a base64-encoded command string
+    if (rest[0] === "--b64" && rest[1]) {
+        return Buffer.from(rest[1], "base64").toString("utf-8");
+    }
+    const withoutDash = rest[0] === "--" ? rest.slice(1) : rest;
+    return withoutDash.join(" ").trim();
+}
+/** Detect shell parse errors that indicate the command itself couldn't be parsed. */
+function isShellParseError(combined, exitCode) {
+    if (exitCode === undefined || exitCode === 0)
+        return false;
+    // zsh: "parse error", "unmatched", "bad pattern"
+    // bash/sh: "syntax error", "unexpected EOF", "unexpected end of file"
+    return /(?:parse error|syntax error|unexpected EOF|unexpected end of file|unmatched|bad pattern)/i.test(combined);
+}
+/**
+ * Detect grep-style "no match" results — exit 1 with empty stdout is the documented
+ * signal for grep/rg/egrep/fgrep when the pattern didn't match. It's not an error.
+ */
+function isGrepNoMatch(cmd, exitCode, stdout) {
+    if (exitCode !== 1)
+        return false;
+    if (stdout.length > 0)
+        return false;
+    return /(?:^|[\s|;&(])(?:grep|rg|egrep|fgrep)\b/.test(cmd);
+}
+export async function runExecMain(argv) {
+    const cmd = parseExecCommandLine(argv);
+    if (!cmd) {
+        process.stderr.write("usage: unerr exec -- <shell command>\n");
+        return 1;
+    }
+    initFileLog(process.cwd());
+    // Use the user's actual shell (not hardcoded bash) so nvm/fnm/volta load correctly
+    const shell = process.env.SHELL || "/bin/sh";
+    const result = await exec(shell, ["-lc", cmd], { throwOnError: false });
+    const exitCode = typeof result.exitCode === "number" ? result.exitCode : 0;
+    const combined = (result.stdout ?? "") +
+        (result.stderr && result.stdout ? "\n" : "") +
+        (result.stderr ?? "");
+    // If the shell couldn't parse the command, emit raw output without compression.
+    // This ensures compression never disrupts the underlying command execution.
+    if (isShellParseError(combined, exitCode)) {
+        startupLog.fileOnly("warn", `shell parse error, skipping compression: ${cmd.slice(0, 120)}`);
+        process.stderr.write(`[unerr:exec] command failed (exit ${exitCode}): ${cmd.slice(0, 120)}\n`);
+        process.stderr.write("[unerr:exec] ↑ this error is from the command itself, not unerr\n");
+        process.stdout.write(combined);
+        if (combined.length > 0 && !combined.endsWith("\n"))
+            process.stdout.write("\n");
+        return exitCode;
+    }
+    // Tee file bypass: when the agent reads a .unerr/tee/ file to recover raw output,
+    // skip compression — re-compressing defeats the purpose of the tee backup.
+    const TEE_RAW_LINE_LIMIT = 150;
+    if (/\.unerr\/tee\/[^\s]*\.txt/.test(cmd)) {
+        const lines = combined.split("\n");
+        if (lines.length > TEE_RAW_LINE_LIMIT) {
+            const truncated = lines.slice(0, TEE_RAW_LINE_LIMIT).join("\n");
+            process.stdout.write(truncated);
+            process.stdout.write(`\n\n[unerr] Truncated ${TEE_RAW_LINE_LIMIT}/${lines.length} lines — use grep/head/tail to recover specific sections\n`);
+        }
+        else {
+            process.stdout.write(combined);
+            if (combined.length > 0 && !combined.endsWith("\n"))
+                process.stdout.write("\n");
+        }
+        appendExecNudge(cmd, combined.length);
+        return exitCode;
+    }
+    try {
+        const out = await compressShellOutput(cmd, combined, {
+            cwd: process.cwd(),
+            exitCode: exitCode || undefined,
+        });
+        process.stdout.write(out.text);
+        if (!out.text.endsWith("\n"))
+            process.stdout.write("\n");
+    }
+    catch (err) {
+        // Compression failed — log the error and fall back to raw output
+        const msg = err instanceof Error ? err.message : String(err);
+        startupLog.fileOnly("warn", `shell compression failed, falling back to raw output: ${msg}`);
+        process.stderr.write(`[unerr:exec] compression failed, showing raw output: ${msg}\n`);
+        process.stdout.write(combined);
+        if (combined.length > 0 && !combined.endsWith("\n"))
+            process.stdout.write("\n");
+    }
+    // Append tool adoption nudge (N4 gates: suppressed in CI, UNERR_QUIET, zero/tiny output)
+    appendExecNudge(cmd, combined.length);
+    // Attribution for non-zero exits so users don't blame unerr for command failures.
+    // Suppress for grep-style commands exiting 1 with empty stdout — that's a legitimate
+    // "no match" signal, not an error.
+    if (exitCode !== 0 && !isGrepNoMatch(cmd, exitCode, result.stdout ?? "")) {
+        startupLog.fileOnly("warn", `command exited with code ${exitCode}: ${cmd.slice(0, 120)}`);
+    }
+    return exitCode;
+}
+export function registerExecCommand(program) {
+    program
+        .command("exec")
+        .description("Run shell command and print compressed output (for PreToolUse hooks)")
+        .allowUnknownOption(true)
+        .action(async () => {
+        const code = await runExecMain(process.argv);
+        process.exit(code);
+    });
+}