@hasna/terminal 2.3.1 → 3.0.1

package/dist/ai.js

@@ -0,0 +1,296 @@
+import { cacheGet, cacheSet } from "./cache.js";
+import { getProvider } from "./providers/index.js";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { discoverProjectHints, discoverSafetyHints, formatHints } from "./context-hints.js";
+// ── model routing ─────────────────────────────────────────────────────────────
+// Config-driven model selection. Defaults per provider, user can override in ~/.terminal/config.json
+const COMPLEX_SIGNALS = [
+    /\b(undo|revert|rollback|previous|last)\b/i,
+    /\b(all files?|recursively|bulk|batch)\b/i,
+    /\b(pipeline|chain|then|and then|after)\b/i,
+    /\b(if|when|unless|only if)\b/i,
+    /\b(go into|go to|navigate|cd into|enter)\b.*\b(and|then)\b/i,
+    /\b(inside|within|under)\b/i,
+    /[|&;]{2}/,
+];
+/** Default models per provider — user can override in ~/.terminal/config.json under "models" */
+const MODEL_DEFAULTS = {
+    cerebras: { fast: "qwen-3-235b-a22b-instruct-2507", smart: "qwen-3-235b-a22b-instruct-2507" },
+    groq: { fast: "openai/gpt-oss-120b", smart: "moonshotai/kimi-k2-instruct" },
+    xai: { fast: "grok-code-fast-1", smart: "grok-4-fast-non-reasoning" },
+    anthropic: { fast: "claude-haiku-4-5-20251001", smart: "claude-sonnet-4-6" },
+};
+/** Load user model overrides from ~/.terminal/config.json (cached 30s) */
+let _modelOverrides = null;
+let _modelOverridesAt = 0;
+function loadModelOverrides() {
+    const now = Date.now();
+    if (_modelOverrides && now - _modelOverridesAt < 30_000)
+        return _modelOverrides;
+    try {
+        const configPath = join(process.env.HOME ?? "~", ".terminal", "config.json");
+        if (existsSync(configPath)) {
+            const config = JSON.parse(readFileSync(configPath, "utf8"));
+            _modelOverrides = config.models ?? {};
+            _modelOverridesAt = now;
+            return _modelOverrides;
+        }
+    }
+    catch { }
+    _modelOverrides = {};
+    _modelOverridesAt = now;
+    return _modelOverrides;
+}
+/** Model routing per provider — config-driven with defaults */
+function pickModel(nl) {
+    const isComplex = COMPLEX_SIGNALS.some((r) => r.test(nl)) || nl.split(" ").length > 10;
+    const provider = getProvider();
+    const defaults = MODEL_DEFAULTS[provider.name] ?? MODEL_DEFAULTS.cerebras;
+    const overrides = loadModelOverrides()[provider.name] ?? {};
+    return {
+        fast: overrides.fast ?? defaults.fast,
+        smart: overrides.smart ?? defaults.smart,
+        pick: isComplex ? "smart" : "fast",
+    };
+}
+// ── irreversibility ───────────────────────────────────────────────────────────
+const IRREVERSIBLE_PATTERNS = [
+    /\brm\s/, /\brmdir\b/, /\btruncate\b/, /\bdrop\s+table\b/i,
+    /\bdelete\s+from\b/i, /\bmv\b.*\/dev\/null/, /\becho\b.*>\s*[^>]/, /\bcat\b.*>\s*[^>]/,
+    /\bdd\b/, /\bmkfs\b/, /\bformat\b/, /\bshred\b/,
+    // Process/service killing
+    /\bkill\b/, /\bkillall\b/, /\bpkill\b/,
+    // Git push/force operations
+    /\bgit\s+push\b/, /\bgit\s+reset\s+--hard\b/, /\bgit\s+force\b/,
+    // Code modification / package installation (security risk)
+    /\bnpx\s+\S+/, /\bnpm\s+install\b/, /\bbun\s+add\b/, /\bpip\s+install\b/,
+    /\bcodemod\b/, /\bsed\s+-i\b/, /\bawk\s.*>\s*\S+\.\w+/, /\bperl\s+-[pi]\b/,
+    // File creation/modification (READ-ONLY terminal)
+    /\btouch\b/, /\bmkdir\b/, /\becho\s.*>/, /\btee\b/, /\bcp\b/, /\bmv\b/,
+    // Starting servers/processes (dangerous from NL)
+    /\b(bun|npm|pnpm|yarn)\s+run\s+dev\b/, /\b(bun|npm)\s+start\b/,
+];
+// Commands that are ALWAYS safe (read-only git, etc.)
+const SAFE_OVERRIDES = [
+    /^\s*git\s+(log|show|diff|branch|status|blame|tag|remote|stash\s+list)\b/,
+    /^\s*git\s+log\b/,
+    // find -exec with read-only tools is safe
+    /\bfind\b.*-exec\s+(wc|cat|head|tail|grep|stat|file|du|ls)\b/,
+    // find without -exec is always safe
+    /^\s*find\b(?!.*-exec\s+(rm|mv|chmod|chown|sed))/,
+    // xargs with read-only tools is safe
+    /\bxargs\s+(wc|cat|head|tail|grep|stat|file|du|ls|git\s+log|git\s+show|git\s+blame)\b/,
+    /\bxargs\s+-I\s*\S+\s+(wc|cat|head|tail|grep|stat|git)\b/,
+];
+export function isIrreversible(command) {
+    // Safe overrides take priority
+    if (SAFE_OVERRIDES.some((r) => r.test(command)))
+        return false;
+    return IRREVERSIBLE_PATTERNS.some((r) => r.test(command));
+}
+// ── permissions ───────────────────────────────────────────────────────────────
+const DESTRUCTIVE_PATTERNS = [/\brm\b/, /\brmdir\b/, /\btruncate\b/, /\bdrop\s+table\b/i, /\bdelete\s+from\b/i];
+const NETWORK_PATTERNS = [/\bcurl\b/, /\bwget\b/, /\bssh\b/, /\bscp\b/, /\bping\b/, /\bnc\b/, /\bnetcat\b/];
+const SUDO_PATTERNS = [/\bsudo\b/];
+const INSTALL_PATTERNS = [/\bbrew\s+install\b/, /\bnpm\s+install\s+-g\b/, /\bpip\s+install\b/, /\bapt\s+install\b/, /\byum\s+install\b/];
+const WRITE_OUTSIDE_PATTERNS = [/\s(\/etc|\/usr|\/var|\/opt|\/root|~\/[^.])/, />\s*\//];
+export function checkPermissions(command, perms) {
+    if (!perms.destructive && DESTRUCTIVE_PATTERNS.some((r) => r.test(command)))
+        return "destructive commands are disabled";
+    if (!perms.network && NETWORK_PATTERNS.some((r) => r.test(command)))
+        return "network commands are disabled";
+    if (!perms.sudo && SUDO_PATTERNS.some((r) => r.test(command)))
+        return "sudo is disabled";
+    if (!perms.install && INSTALL_PATTERNS.some((r) => r.test(command)))
+        return "package installation is disabled";
+    if (!perms.write_outside_cwd && WRITE_OUTSIDE_PATTERNS.some((r) => r.test(command)))
+        return "writing outside cwd is disabled";
+    return null;
+}
+// ── correction memory ───────────────────────────────────────────────────────
+/** Load past corrections relevant to a prompt — injected as negative examples */
+function loadCorrectionHints(prompt) {
+    try {
+        // Dynamic import to avoid circular deps
+        const { findSimilarCorrections } = require("./sessions-db.js");
+        const corrections = findSimilarCorrections(prompt, 3);
+        if (corrections.length === 0)
+            return "";
+        const lines = corrections.map((c) => `AVOID: "${c.failed_command}" (failed: ${c.error_type}). USE: "${c.corrected_command}" instead.`);
+        return `\n\nLEARNED CORRECTIONS (from past failures):\n${lines.join("\n")}`;
+    }
+    catch {
+        return "";
+    }
+}
+// ── project context (powered by context-hints) ──────────────────────────────
+function detectProjectContext() {
+    const hints = discoverProjectHints(process.cwd());
+    return hints.length > 0 ? `\n\n${formatHints(hints)}` : "";
+}
+// ── system prompt ─────────────────────────────────────────────────────────────
+function buildSystemPrompt(perms, sessionEntries, currentPrompt) {
+    const nl = currentPrompt?.toLowerCase() ?? "";
+    const restrictions = [];
+    if (!perms.destructive)
+        restrictions.push("- NEVER generate commands that delete, remove, or overwrite files/data");
+    if (!perms.network)
+        restrictions.push("- NEVER generate commands that make network requests (curl, wget, ssh, etc.)");
+    if (!perms.sudo)
+        restrictions.push("- NEVER generate commands requiring sudo");
+    if (!perms.write_outside_cwd)
+        restrictions.push("- NEVER write to paths outside the current working directory");
+    if (!perms.install)
+        restrictions.push("- NEVER install packages (brew, npm -g, pip, apt, etc.)");
+    const restrictionBlock = restrictions.length > 0
+        ? `\n\nRESTRICTIONS:\n${restrictions.join("\n")}\nIf restricted, output: BLOCKED: <reason>`
+        : "";
+    let contextBlock = "";
+    if (sessionEntries.length > 0) {
+        const lines = [];
+        for (const e of sessionEntries.slice(-5)) {
+            lines.push(`> ${e.nl}`);
+            lines.push(`$ ${e.cmd}`);
+            if (e.output)
+                lines.push(e.output);
+            if (e.error)
+                lines.push("(command failed)");
+        }
+        contextBlock = `\n\nSESSION HISTORY (user intent > command $ output):\n${lines.join("\n")}`;
+    }
+    const projectContext = detectProjectContext();
+    const safetyBlock = sessionEntries.length > 0
+        ? (() => {
+            const lastCmd = sessionEntries[sessionEntries.length - 1]?.cmd;
+            if (lastCmd) {
+                const safetyHints = discoverSafetyHints(lastCmd);
+                return safetyHints.length > 0 ? `\n\nLAST COMMAND SAFETY:\n${safetyHints.join("\n")}` : "";
+            }
+            return "";
+        })()
+        : "";
+    // ── Conditional sections (only included when relevant) ──
+    const wantsStructure = /\b(function|class|interface|export|symbol|structure|hierarchy|outline)\b/i.test(nl);
+    const astBlock = wantsStructure ? `\nAST-POWERED QUERIES: For code STRUCTURE questions, use "terminal symbols" instead of grep. It uses AST parsing for TypeScript, Python, Go, Rust.` : "";
+    const wantsMultiple = /\b(and|both|also|plus|as well)\b/i.test(nl);
+    const compoundBlock = wantsMultiple ? `\nCOMPOUND QUESTIONS: Prefer ONE command that captures all info. NEVER split into separate expensive commands.` : "";
+    const wantsAnalysis = /\b(quality|lint|coverage|complexity|unused|dead code|security|audit|scan|dependency)\b/i.test(nl);
+    const blockedAltBlock = wantsAnalysis ? `\nBLOCKED ALTERNATIVES: If your preferred command needs installing packages, try READ-ONLY alternatives (grep, cat, wc, awk). NEVER give up on analysis questions.` : "";
+    return `You are a terminal assistant. Output ONLY the exact shell command — no explanation, no markdown, no backticks.
+
+RULES:
+- SIMPLICITY FIRST: Use the simplest command. Prefer grep | sort | head over 10-pipe chains.
+- ALWAYS use grep -rn when searching directories. NEVER grep without -r on a directory.
+- When user refers to items from previous output, use EXACT names shown.
+- For text search use grep -rn, NOT nm or objdump.
+- macOS/BSD tools: du -d 1 (not --max-depth), NEVER grep -P, use grep -E for extended regex.
+- NEVER invent commands. Stick to standard Unix/macOS.
+- NEVER install packages. READ-ONLY terminal.
+- NEVER modify source code. Only observe.
+- Search src/ not dist/ or node_modules/.
+- Use exact file paths from project context. Do NOT guess paths.
+- For DESTRUCTIVE requests: output BLOCKED: <reason>.
+- ACTION vs CONCEPTUAL: "run/test/build/check" → executable command. "explain/what does X mean" → read docs.
+- EXISTENCE CHECKS: "is there/does X exist" → use ls/find/test, NEVER run/launch.${astBlock}${compoundBlock}${blockedAltBlock}
+cwd: ${process.cwd()}
+shell: zsh / macOS${projectContext}${safetyBlock}${restrictionBlock}${contextBlock}${currentPrompt ? loadCorrectionHints(currentPrompt) : ""}`;
+}
+// ── streaming translate ───────────────────────────────────────────────────────
+export async function translateToCommand(nl, perms, sessionEntries, onToken) {
+    // Only use cache when there's no session context (context makes same NL produce different commands)
+    if (sessionEntries.length === 0) {
+        const cached = cacheGet(nl);
+        if (cached) {
+            onToken?.(cached);
+            return cached;
+        }
+    }
+    const provider = getProvider();
+    const routing = pickModel(nl);
+    const model = routing.pick === "smart" ? routing.smart : routing.fast;
+    const system = buildSystemPrompt(perms, sessionEntries, nl);
+    let text;
+    if (onToken) {
+        text = await provider.stream(nl, { model, maxTokens: 256, temperature: 0, stop: ["\n"], system }, {
+            onToken: (partial) => onToken(partial),
+        });
+    }
+    else {
+        text = await provider.complete(nl, { model, maxTokens: 256, temperature: 0, stop: ["\n"], system });
+    }
+    if (text.startsWith("BLOCKED:"))
+        throw new Error(text);
+    // Strip AI reasoning — extract ONLY the shell command (first line)
+    let cleaned = text.trim();
+    // Remove ALL markdown code blocks and their content markers
+    cleaned = cleaned.replace(/```(?:bash|sh|shell)?\n?/g, "").replace(/```/g, "");
+    // Split into lines and find the FIRST one that looks like a SHELL COMMAND
+    const lines = cleaned.split("\n");
+    let command = "";
+    for (const line of lines) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        // Skip lines that are clearly English prose, not commands
+        if (/^(Based on|I |This |The |Let me|Here|Note:|Since|Looking|To |However|BLOCKED:|If |You |We |For |It |A |An |That )/.test(t))
+            continue;
+        if (/^[A-Z][a-z].*[.;:!?,]/.test(t))
+            continue; // English sentence with punctuation anywhere
+        if (t.split(" ").length > 15 && !/[|&;><$]/.test(t))
+            continue; // Long line without shell operators = prose
+        // Must start with a plausible command character (lowercase, /, ., $, or common tool)
+        if (/^[a-z./$~(]/.test(t) || /^[A-Z]+[_=]/.test(t)) {
+            command = t;
+            break;
+        }
+    }
+    cleaned = command || lines[0]?.trim() || cleaned;
+    cacheSet(nl, cleaned);
+    return cleaned;
+}
+// ── prefetch ──────────────────────────────────────────────────────────────────
+export function prefetchNext(lastNl, perms, sessionEntries) {
+    if (sessionEntries.length === 0 && cacheGet(lastNl))
+        return;
+    translateToCommand(lastNl, perms, sessionEntries).catch(() => { });
+}
+// ── explain ───────────────────────────────────────────────────────────────────
+export async function explainCommand(command) {
+    const provider = getProvider();
+    const routing = pickModel("explain"); // simple = fast model
+    return provider.complete(command, {
+        model: routing.fast,
+        maxTokens: 128,
+        temperature: 0,
+        system: "Explain what this shell command does in one plain English sentence. No markdown, no code blocks.",
+    });
+}
+// ── auto-fix ──────────────────────────────────────────────────────────────────
+export async function fixCommand(originalNl, failedCommand, errorOutput, perms, _sessionEntries) {
+    const provider = getProvider();
+    const routing = pickModel(originalNl);
+    // Lightweight fix prompt — no full project context, just rules + restrictions
+    const restrictions = [];
+    if (!perms.destructive)
+        restrictions.push("- NEVER delete/remove/overwrite files");
+    if (!perms.network)
+        restrictions.push("- NEVER make network requests");
+    if (!perms.install)
+        restrictions.push("- NEVER install packages");
+    const fixSystem = `You are a terminal assistant. Output ONLY the corrected shell command — no explanation.
+macOS/BSD tools. NEVER use grep -P. Use grep -E for extended regex.
+NEVER install packages. READ-ONLY terminal.
+cwd: ${process.cwd()}${restrictions.length > 0 ? `\nRESTRICTIONS:\n${restrictions.join("\n")}` : ""}`;
+    const text = await provider.complete(`I wanted to: ${originalNl}\nI ran: ${failedCommand}\nError:\n${errorOutput.slice(0, 2000)}\n\nGive me the corrected command only.`, {
+        model: routing.smart,
+        maxTokens: 256,
+        temperature: 0,
+        stop: ["\n"],
+        system: fixSystem,
+    });
+    if (text.startsWith("BLOCKED:"))
+        throw new Error(text);
+    return text.trim();
+}
+// summarizeOutput() removed — all output processing goes through processOutput() in output-processor.ts

package/dist/cache.js

@@ -0,0 +1,42 @@
+// In-memory LRU cache + disk persistence for command translations
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const CACHE_FILE = join(homedir(), ".terminal", "cache.json");
+const MAX_ENTRIES = 500;
+let mem = {};
+export function loadCache() {
+    if (!existsSync(CACHE_FILE))
+        return;
+    try {
+        mem = JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+    }
+    catch { }
+}
+function persistCache() {
+    try {
+        writeFileSync(CACHE_FILE, JSON.stringify(mem));
+    }
+    catch { }
+}
+/** Normalize a natural language query for cache lookup.
+ *  Keeps . / - _ which are meaningful in file paths and shell context. */
+export function normalizeNl(nl) {
+    return nl
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9\s.\/_-]/g, "") // keep meaningful shell chars
+        .replace(/\s+/g, " ");
+}
+export function cacheGet(nl) {
+    return mem[normalizeNl(nl)] ?? null;
+}
+export function cacheSet(nl, command) {
+    const key = normalizeNl(nl);
+    // evict oldest if full
+    const keys = Object.keys(mem);
+    if (keys.length >= MAX_ENTRIES)
+        delete mem[keys[0]];
+    mem[key] = command;
+    persistCache();
+}

package/dist/cli.js

@@ -471,7 +471,7 @@ else if (args.length > 0) {
     const { rewriteCommand } = await import("./command-rewriter.js");
     const { shouldBeLazy, toLazy } = await import("./lazy-executor.js");
     const { saveOutput, formatOutputHint } = await import("./output-store.js");
-    const { parseOutput, estimateTokens } = await import("./parsers/index.js");
+    const { estimateTokens } = await import("./tokens.js");
     const { recordSaving, recordUsage } = await import("./economy.js");
     const { isTestOutput, trackTests, formatWatchResult } = await import("./test-watchlist.js");
     const { detectLoop } = await import("./loop-detector.js");

package/dist/command-rewriter.js

@@ -0,0 +1,64 @@
+// Command rewriter — auto-optimize commands to produce less output
+// Only rewrites when semantic result is identical
+const rules = [
+    // find | grep -v node_modules → find -not -path
+    {
+        pattern: /find\s+(\S+)\s+(.*?)\|\s*grep\s+-v\s+node_modules/,
+        rewrite: (m, cmd) => cmd.replace(m[0], `find ${m[1]} ${m[2]}-not -path '*/node_modules/*'`),
+        reason: "avoid pipe, filter in-kernel",
+    },
+    // cat file | grep X → grep X file
+    {
+        pattern: /cat\s+(\S+)\s*\|\s*grep\s+(.*)/,
+        rewrite: (m) => `grep ${m[2]} ${m[1]}`,
+        reason: "useless cat",
+    },
+    // find without node_modules exclusion → add it
+    {
+        pattern: /^find\s+\.\s+(.*)(?!.*node_modules)/,
+        rewrite: (m, cmd) => {
+            if (cmd.includes("node_modules") || cmd.includes("-not -path"))
+                return cmd;
+            return cmd.replace(/^find\s+\.\s+/, "find . -not -path '*/node_modules/*' -not -path '*/.git/*' ");
+        },
+        reason: "auto-exclude node_modules and .git",
+    },
+    // git log without limit → add --oneline -20
+    {
+        pattern: /^git\s+log\s*$/,
+        rewrite: () => "git log --oneline -20",
+        reason: "prevent unbounded log output",
+    },
+    // git diff without stat → add --stat for overview
+    {
+        pattern: /^git\s+diff\s*$/,
+        rewrite: () => "git diff --stat",
+        reason: "stat overview is usually sufficient",
+    },
+    // npm ls without depth → add --depth=0
+    {
+        pattern: /^npm\s+ls\s*$/,
+        rewrite: () => "npm ls --depth=0",
+        reason: "full tree is massive, top-level usually enough",
+    },
+    // ps aux without filter → sort by memory and head (macOS compatible)
+    {
+        pattern: /^ps\s+aux\s*$/,
+        rewrite: () => "ps aux | sort -k4 -rn | head -20",
+        reason: "full process list is noise, show top consumers",
+    },
+];
+/** Rewrite a command to produce less output */
+export function rewriteCommand(cmd) {
+    const trimmed = cmd.trim();
+    for (const rule of rules) {
+        const match = trimmed.match(rule.pattern);
+        if (match) {
+            const rewritten = rule.rewrite(match, trimmed);
+            if (rewritten !== trimmed) {
+                return { original: trimmed, rewritten, changed: true, reason: rule.reason };
+            }
+        }
+    }
+    return { original: trimmed, rewritten: trimmed, changed: false };
+}

package/dist/command-validator.js

@@ -0,0 +1,86 @@
+// Command validator — catch invalid commands BEFORE executing
+// Prevents shell errors from hallucinated flags, wrong paths, bad syntax
+import { existsSync } from "fs";
+import { join } from "path";
+/** Extract file paths referenced in a command */
+function extractPaths(command) {
+    const paths = [];
+    // Match quoted paths
+    const quoted = command.match(/["']([^"']+\.\w+)["']/g);
+    if (quoted)
+        paths.push(...quoted.map(q => q.replace(/["']/g, "")));
+    // Match unquoted paths with extensions or directory separators
+    const tokens = command.split(/\s+/);
+    for (const t of tokens) {
+        if (t.includes("/") && !t.startsWith("-") && !t.startsWith("|") && !t.startsWith("&")) {
+            // Clean shell operators from end
+            const clean = t.replace(/[;|&>]+$/, "");
+            if (clean && !clean.startsWith("-"))
+                paths.push(clean);
+        }
+    }
+    return [...new Set(paths)];
+}
+/** Check for obviously broken shell syntax */
+function checkSyntax(command) {
+    const issues = [];
+    // Unmatched quotes
+    const singleQuotes = (command.match(/'/g) || []).length;
+    const doubleQuotes = (command.match(/"/g) || []).length;
+    if (singleQuotes % 2 !== 0)
+        issues.push("unmatched single quote");
+    if (doubleQuotes % 2 !== 0)
+        issues.push("unmatched double quote");
+    // Unmatched parentheses
+    const openParens = (command.match(/\(/g) || []).length;
+    const closeParens = (command.match(/\)/g) || []).length;
+    if (openParens !== closeParens)
+        issues.push("unmatched parentheses");
+    // Empty pipe targets
+    if (/\|\s*$/.test(command))
+        issues.push("pipe with no target");
+    if (/^\s*\|/.test(command))
+        issues.push("pipe with no source");
+    return issues;
+}
+/** Validate a command before execution */
+export function validateCommand(command, cwd) {
+    const issues = [];
+    // Check syntax
+    issues.push(...checkSyntax(command));
+    // Check file paths exist
+    const paths = extractPaths(command);
+    for (const p of paths) {
+        const fullPath = p.startsWith("/") ? p : join(cwd, p);
+        if (p.includes("*") || p.includes("?"))
+            continue; // skip globs
+        if (p.startsWith("-"))
+            continue; // skip flags
+        if ([".", "..", "/", "~"].includes(p))
+            continue; // skip special
+        if (!existsSync(fullPath) && !existsSync(p)) {
+            // Only flag source file paths, not output paths
+            if (/\.(ts|tsx|js|jsx|json|md|yaml|yml|py|go|rs)$/.test(p)) {
+                issues.push(`file not found: ${p}`);
+            }
+        }
+    }
+    // Check for common GNU flags on macOS
+    const gnuFlags = command.match(/--max-depth|--color=|--sort=|--field-type|--no-deps/g);
+    if (gnuFlags) {
+        issues.push(`GNU flag on macOS: ${gnuFlags.join(", ")}`);
+    }
+    // Complexity guard — extreme pipe chains are fragile
+    const pipeCount = (command.match(/\|/g) || []).length;
+    if (pipeCount > 7) {
+        issues.push(`too complex: ${pipeCount} pipes — simplify`);
+    }
+    // grep -P (PCRE) doesn't exist on macOS
+    if (/grep\s+.*-[a-zA-Z]*P/.test(command)) {
+        issues.push("grep -P (PCRE) not available on macOS — use grep -E");
+    }
+    return {
+        valid: issues.length === 0,
+        issues,
+    };
+}

package/dist/compression.js

@@ -0,0 +1,85 @@
+// Token compression engine — reduces CLI output to fit within token budgets
+// No regex parsing — just ANSI stripping, deduplication, and smart truncation.
+// All intelligent output processing goes through AI via processOutput().
+import { estimateTokens } from "./tokens.js";
+/** Strip ANSI escape codes from text */
+export function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "");
+}
+/** Deduplicate consecutive similar lines (e.g., "Compiling X... Compiling Y...") */
+function deduplicateLines(lines) {
+    if (lines.length <= 3)
+        return lines;
+    const result = [];
+    let repeatCount = 0;
+    let repeatPattern = "";
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const pattern = line.replace(/[0-9]+/g, "N").replace(/\/\S+/g, "/PATH").replace(/\s+/g, " ").trim();
+        if (pattern === repeatPattern) {
+            repeatCount++;
+        }
+        else {
+            if (repeatCount > 2) {
+                result.push(`  ... (${repeatCount} similar lines)`);
+            }
+            else if (repeatCount > 0) {
+                for (let j = i - repeatCount; j < i; j++) {
+                    result.push(lines[j]);
+                }
+            }
+            result.push(line);
+            repeatPattern = pattern;
+            repeatCount = 0;
+        }
+    }
+    if (repeatCount > 2) {
+        result.push(`  ... (${repeatCount} similar lines)`);
+    }
+    else {
+        for (let j = lines.length - repeatCount; j < lines.length; j++) {
+            result.push(lines[j]);
+        }
+    }
+    return result;
+}
+/** Smart truncation: keep first 60% + last 40% of lines */
+function smartTruncate(text, maxTokens) {
+    const lines = text.split("\n");
+    const currentTokens = estimateTokens(text);
+    if (currentTokens <= maxTokens)
+        return text;
+    const targetLines = Math.floor((maxTokens * lines.length) / currentTokens);
+    const firstCount = Math.ceil(targetLines * 0.6);
+    const lastCount = Math.floor(targetLines * 0.4);
+    if (firstCount + lastCount >= lines.length)
+        return text;
+    const first = lines.slice(0, firstCount);
+    const last = lines.slice(-lastCount);
+    const hiddenCount = lines.length - firstCount - lastCount;
+    return [...first, `\n--- ${hiddenCount} lines hidden ---\n`, ...last].join("\n");
+}
+/** Compress command output — ANSI strip, dedup, truncate. No parsing. */
+export function compress(command, output, options = {}) {
+    const { maxTokens, stripAnsi: doStrip = true } = options;
+    const originalTokens = estimateTokens(output);
+    // Step 1: Strip ANSI codes
+    let text = doStrip ? stripAnsi(output) : output;
+    // Step 2: Deduplicate similar lines
+    const lines = text.split("\n");
+    const deduped = deduplicateLines(lines);
+    text = deduped.join("\n");
+    // Step 3: Smart truncation if over budget
+    if (maxTokens) {
+        text = smartTruncate(text, maxTokens);
+    }
+    const compressedTokens = estimateTokens(text);
+    return {
+        content: text,
+        originalTokens,
+        compressedTokens,
+        tokensSaved: Math.max(0, originalTokens - compressedTokens),
+        savingsPercent: originalTokens > 0 ? Math.round(((originalTokens - compressedTokens) / originalTokens) * 100) : 0,
+    };
+}