@hasna/terminal 2.3.1 → 3.0.1

package/dist/context-hints.js

@@ -0,0 +1,285 @@
+// Context hints — discover context via lightweight checks, inject into AI prompt
+// Regex DISCOVERS, AI DECIDES. No hardcoded logic that makes decisions.
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+/** Discover project context from the filesystem */
+export function discoverProjectHints(cwd) {
+    const hints = [];
+    // Package managers and project files
+    const projectFiles = [
+        ["package.json", "Node.js/TypeScript"],
+        ["pyproject.toml", "Python"],
+        ["requirements.txt", "Python"],
+        ["go.mod", "Go"],
+        ["Cargo.toml", "Rust"],
+        ["pom.xml", "Java/Maven"],
+        ["build.gradle", "Java/Gradle"],
+        ["build.gradle.kts", "Java/Gradle (Kotlin DSL)"],
+        ["Makefile", "Has Makefile"],
+        ["Dockerfile", "Has Docker"],
+        ["docker-compose.yml", "Has Docker Compose"],
+        ["docker-compose.yaml", "Has Docker Compose"],
+        [".github/workflows", "Has GitHub Actions CI"],
+        ["Gemfile", "Ruby"],
+        ["composer.json", "PHP"],
+        ["mix.exs", "Elixir"],
+        ["build.zig", "Zig"],
+        ["CMakeLists.txt", "C/C++ (CMake)"],
+    ];
+    for (const [file, lang] of projectFiles) {
+        if (existsSync(join(cwd, file))) {
+            hints.push(`Project type: ${lang} (${file} found)`);
+        }
+    }
+    // Extract metadata from package.json — trimmed to save tokens
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            if (pkg.name)
+                hints.push(`Package: ${pkg.name}@${pkg.version ?? "?"}`);
+            if (pkg.scripts) {
+                // Only top-5 most useful scripts
+                const priority = ["dev", "build", "test", "lint", "start", "typecheck", "check"];
+                const scripts = Object.keys(pkg.scripts);
+                const top = priority.filter(s => scripts.includes(s));
+                const rest = scripts.filter(s => !priority.includes(s)).slice(0, Math.max(0, 5 - top.length));
+                hints.push(`Scripts: ${[...top, ...rest].join(", ")}`);
+            }
+            if (pkg.dependencies) {
+                // Only framework/major deps — skip utility libs
+                const major = ["react", "next", "express", "fastify", "hono", "vue", "angular", "svelte",
+                    "prisma", "drizzle", "mongoose", "typeorm", "zod", "trpc", "graphql", "tailwindcss",
+                    "electron", "bun", "elysia", "nest", "nuxt", "remix", "astro", "vite"];
+                const deps = Object.keys(pkg.dependencies);
+                const found = deps.filter(d => major.some(m => d.includes(m)));
+                if (found.length > 0)
+                    hints.push(`Key deps: ${found.slice(0, 10).join(", ")}`);
+            }
+        }
+        catch { }
+    }
+    // Extract from pyproject.toml
+    const pyPath = join(cwd, "pyproject.toml");
+    if (existsSync(pyPath)) {
+        try {
+            const py = readFileSync(pyPath, "utf8");
+            const name = py.match(/name\s*=\s*"([^"]+)"/)?.[1];
+            if (name)
+                hints.push(`Python package: ${name}`);
+        }
+        catch { }
+    }
+    // Extract from go.mod
+    const goPath = join(cwd, "go.mod");
+    if (existsSync(goPath)) {
+        try {
+            const go = readFileSync(goPath, "utf8");
+            const mod = go.match(/module\s+(\S+)/)?.[1];
+            if (mod)
+                hints.push(`Go module: ${mod}`);
+        }
+        catch { }
+    }
+    // Extract from Cargo.toml
+    const cargoPath = join(cwd, "Cargo.toml");
+    if (existsSync(cargoPath)) {
+        try {
+            const cargo = readFileSync(cargoPath, "utf8");
+            const name = cargo.match(/name\s*=\s*"([^"]+)"/)?.[1];
+            if (name)
+                hints.push(`Rust crate: ${name}`);
+        }
+        catch { }
+    }
+    // Monorepo detection
+    if (existsSync(join(cwd, "packages"))) {
+        try {
+            const pkgs = readdirSync(join(cwd, "packages")).filter(d => !d.startsWith("."));
+            hints.push(`MONOREPO: ${pkgs.length} packages in packages/ — search packages/ not src/`);
+            hints.push(`Packages: ${pkgs.slice(0, 10).join(", ")}`);
+        }
+        catch { }
+    }
+    if (existsSync(join(cwd, "apps"))) {
+        hints.push("MONOREPO: apps/ directory detected");
+    }
+    // Makefile targets
+    if (existsSync(join(cwd, "Makefile"))) {
+        try {
+            const { execSync } = require("child_process");
+            const targets = execSync("grep -E '^[a-zA-Z_-]+:' Makefile | head -10 | cut -d: -f1", { cwd, encoding: "utf8", timeout: 1000 }).trim();
+            if (targets)
+                hints.push(`Makefile targets: ${targets.split("\n").join(", ")}`);
+        }
+        catch { }
+    }
+    // Source directory structure — max 20 files to save tokens
+    try {
+        const { execSync } = require("child_process");
+        const srcDirs = ["src", "lib", "app", "packages"];
+        for (const dir of srcDirs) {
+            if (existsSync(join(cwd, dir))) {
+                const tree = execSync(`find ${dir} -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/dist/*' -not -name '*.test.*' -not -name '*.spec.*' 2>/dev/null | sort | head -20`, { cwd, encoding: "utf8", timeout: 2000 }).trim();
+                if (tree)
+                    hints.push(`Files in ${dir}/:\n${tree}`);
+                break;
+            }
+        }
+    }
+    catch { }
+    return hints;
+}
+/** Discover output-specific hints (observations about command output) */
+export function discoverOutputHints(output, command) {
+    const hints = [];
+    const lines = output.split("\n");
+    hints.push(`Output: ${lines.length} lines, ${output.length} chars`);
+    // Only detect test results from actual test runners (not grep output containing "pass"/"fail" in code)
+    const isGrepOutput = /^\s*(src\/|\.\/|packages\/).*:\d+:/.test(output);
+    if (!isGrepOutput) {
+        const passMatch = output.match(/(\d+)\s+pass(?:ed|ing)?\b/i);
+        const failMatch = output.match(/(\d+)\s+fail(?:ed|ing|ure)?\b/i);
+        if (passMatch)
+            hints.push(`Test results detected: ${passMatch[0]}`);
+        if (failMatch)
+            hints.push(`Test results detected: ${failMatch[0]}`);
+        // Error patterns (only from actual command output, not code search)
+        if (output.match(/error\s*TS\d+/i))
+            hints.push("TypeScript errors detected in output");
+        if (output.match(/ENOENT|EACCES|EADDRINUSE/))
+            hints.push("System error code detected in output");
+    }
+    // Coverage patterns
+    if (output.match(/%\s*Funcs|%\s*Lines|coverage/i))
+        hints.push("Code coverage data detected in output");
+    // Large/repetitive output
+    if (lines.length > 100)
+        hints.push(`Large output (${lines.length} lines) — consider summarizing`);
+    const uniqueLines = new Set(lines.map(l => l.trim())).size;
+    if (uniqueLines < lines.length * 0.5)
+        hints.push("Output has many duplicate/similar lines");
+    // Sensitive data (only env var assignments, not code containing the word KEY/TOKEN)
+    if (output.match(/^[A-Z_]+(KEY|TOKEN|SECRET|PASSWORD)\s*=\s*\S+/m))
+        hints.push("Output may contain sensitive data — redact credentials");
+    // Error block extraction — state machine that captures multi-line errors
+    if (!isGrepOutput) {
+        const errorBlocks = extractErrorBlocks(output);
+        if (errorBlocks.length > 0) {
+            const summary = errorBlocks.slice(0, 3).map(b => b.trim().split("\n").slice(0, 5).join("\n")).join("\n---\n");
+            hints.push(`ERROR BLOCKS FOUND (${errorBlocks.length}):\n${summary}`);
+        }
+    }
+    return hints;
+}
+/** Extract multi-line error blocks using a state machine */
+function extractErrorBlocks(output) {
+    const lines = output.split("\n");
+    const blocks = [];
+    let currentBlock = [];
+    let inErrorBlock = false;
+    let blankCount = 0;
+    // Patterns that START an error block
+    const errorStarters = [
+        /^error/i, /^Error:/i, /^ERROR/,
+        /^Traceback/i, /^panic:/i, /^fatal:/i,
+        /^FAIL/i, /^✗/, /^✘/,
+        /error\s*TS\d+/i, /error\[E\d+\]/,
+        /^SyntaxError/i, /^TypeError/i, /^ReferenceError/i,
+        /^Unhandled/i, /^Exception/i,
+        /ENOENT|EACCES|EADDRINUSE|ECONNREFUSED/,
+    ];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            blankCount++;
+            if (inErrorBlock) {
+                currentBlock.push(line);
+                // 2+ blank lines = end of error block
+                if (blankCount >= 2) {
+                    blocks.push(currentBlock.join("\n").trim());
+                    currentBlock = [];
+                    inErrorBlock = false;
+                }
+            }
+            continue;
+        }
+        blankCount = 0;
+        // Check if this line starts a new error block
+        if (!inErrorBlock && errorStarters.some(p => p.test(trimmed))) {
+            inErrorBlock = true;
+            currentBlock = [line];
+            continue;
+        }
+        if (inErrorBlock) {
+            // Continuation: indented lines, "at ..." stack frames, "--->" pointers, "File ..." python traces
+            const isContinuation = /^\s+/.test(line) ||
+                /^\s*at\s/.test(trimmed) ||
+                /^\s*-+>/.test(trimmed) ||
+                /^\s*\|/.test(trimmed) ||
+                /^\s*File "/.test(trimmed) ||
+                /^\s*\d+\s*\|/.test(trimmed) || // rust/compiler line numbers
+                /^Caused by:/i.test(trimmed);
+            if (isContinuation) {
+                currentBlock.push(line);
+            }
+            else {
+                // Non-continuation, non-blank = end of error block
+                blocks.push(currentBlock.join("\n").trim());
+                currentBlock = [];
+                inErrorBlock = false;
+                // Check if THIS line starts a new error block
+                if (errorStarters.some(p => p.test(trimmed))) {
+                    inErrorBlock = true;
+                    currentBlock = [line];
+                }
+            }
+        }
+    }
+    // Flush remaining block
+    if (currentBlock.length > 0) {
+        blocks.push(currentBlock.join("\n").trim());
+    }
+    return blocks;
+}
+/** Discover safety hints about a command */
+export function discoverSafetyHints(command) {
+    const hints = [];
+    // Observations about the command (AI decides if it's safe)
+    if (command.match(/\brm\b|\brmdir\b|\btruncate\b/))
+        hints.push("SAFETY: command contains file deletion (rm/rmdir/truncate)");
+    if (command.match(/\bkill\b|\bkillall\b|\bpkill\b/))
+        hints.push("SAFETY: command kills processes");
+    if (command.match(/\bgit\s+push\b|\bgit\s+reset\s+--hard\b/))
+        hints.push("SAFETY: command pushes/resets git");
+    if (command.match(/\bnpx\b|\bnpm\s+install\b|\bpip\s+install\b/))
+        hints.push("SAFETY: command installs packages");
+    if (command.match(/\bsed\s+-i\b|\bcodemod\b/))
+        hints.push("SAFETY: command modifies files in-place");
+    if (command.match(/\btouch\b|\bmkdir\b/))
+        hints.push("SAFETY: command creates files/directories");
+    if (command.match(/>\s*\S+\.\w+/))
+        hints.push("SAFETY: command writes to a file via redirect");
+    if (command.match(/\b(bun|npm|pnpm)\s+run\s+dev\b|\bstart\b/))
+        hints.push("SAFETY: command starts a server/process");
+    // Read-only observations
+    if (command.match(/^\s*git\s+(log|show|diff|status|branch|blame|tag)\b/))
+        hints.push("This is a read-only git command");
+    if (command.match(/^\s*(ls|cat|head|tail|grep|find|wc|du|df|uptime|whoami|pwd)\b/))
+        hints.push("This is a read-only command");
+    return hints;
+}
+/** Format all hints for system prompt injection */
+export function formatHints(project, output, safety) {
+    const sections = [];
+    if (project.length > 0) {
+        sections.push("PROJECT CONTEXT:\n" + project.join("\n"));
+    }
+    if (output && output.length > 0) {
+        sections.push("OUTPUT OBSERVATIONS:\n" + output.join("\n"));
+    }
+    if (safety && safety.length > 0) {
+        sections.push("SAFETY OBSERVATIONS:\n" + safety.join("\n"));
+    }
+    return sections.join("\n\n");
+}

package/dist/diff-cache.js

@@ -0,0 +1,107 @@
+// Diff-aware output caching — when same command runs again, return only what changed
+import { estimateTokens } from "./tokens.js";
+const cache = new Map();
+function cacheKey(command, cwd) {
+    return `${cwd}:${command}`;
+}
+/** Compute a simple line diff between two outputs */
+function lineDiff(prev, curr) {
+    const prevLines = new Set(prev.split("\n"));
+    const currLines = curr.split("\n");
+    const added = [];
+    const removed = [];
+    let unchanged = 0;
+    for (const line of currLines) {
+        if (prevLines.has(line)) {
+            unchanged++;
+            prevLines.delete(line);
+        }
+        else {
+            added.push(line);
+        }
+    }
+    for (const line of prevLines) {
+        removed.push(line);
+    }
+    return { added, removed, unchanged };
+}
+/** Generate a human-readable diff summary */
+function summarizeDiff(diff) {
+    const parts = [];
+    if (diff.added.length > 0)
+        parts.push(`+${diff.added.length} new lines`);
+    if (diff.removed.length > 0)
+        parts.push(`-${diff.removed.length} removed lines`);
+    parts.push(`${diff.unchanged} unchanged`);
+    return parts.join(", ");
+}
+/** Run diffing on command output. Caches the output for next comparison. */
+export function diffOutput(command, cwd, output) {
+    const key = cacheKey(command, cwd);
+    const prev = cache.get(key);
+    // Store current for next time
+    cache.set(key, { command, cwd, output, timestamp: Date.now() });
+    if (!prev) {
+        return {
+            full: output,
+            hasPrevious: false,
+            added: [],
+            removed: [],
+            diffSummary: "first run",
+            unchanged: false,
+            tokensSaved: 0,
+        };
+    }
+    if (prev.output === output) {
+        const fullTokens = estimateTokens(output);
+        return {
+            full: output,
+            hasPrevious: true,
+            added: [],
+            removed: [],
+            diffSummary: "identical to previous run",
+            unchanged: true,
+            tokensSaved: fullTokens - 10, // ~10 tokens for the "unchanged" message
+        };
+    }
+    const diff = lineDiff(prev.output, output);
+    const total = diff.added.length + diff.removed.length + diff.unchanged;
+    const similarity = total > 0 ? diff.unchanged / total : 0;
+    // Fuzzy threshold: if >80% similar, return diff-only (massive token savings)
+    const fullTokens = estimateTokens(output);
+    if (similarity > 0.8 && diff.added.length + diff.removed.length > 0) {
+        const diffContent = [
+            ...diff.added.map(l => `+ ${l}`),
+            ...diff.removed.map(l => `- ${l}`),
+        ].join("\n");
+        const diffTokens = estimateTokens(diffContent);
+        return {
+            full: output,
+            hasPrevious: true,
+            added: diff.added,
+            removed: diff.removed,
+            diffSummary: `${Math.round(similarity * 100)}% similar — ${summarizeDiff(diff)}`,
+            unchanged: false,
+            tokensSaved: Math.max(0, fullTokens - diffTokens),
+        };
+    }
+    // Less than 80% similar — return full output with diff info
+    const diffContent = [
+        ...diff.added.map(l => `+ ${l}`),
+        ...diff.removed.map(l => `- ${l}`),
+    ].join("\n");
+    const diffTokens = estimateTokens(diffContent);
+    return {
+        full: output,
+        hasPrevious: true,
+        added: diff.added,
+        removed: diff.removed,
+        diffSummary: summarizeDiff(diff),
+        unchanged: false,
+        tokensSaved: Math.max(0, fullTokens - diffTokens),
+    };
+}
+/** Clear the diff cache */
+export function clearDiffCache() {
+    cache.clear();
+}

package/dist/discover.js

@@ -0,0 +1,212 @@
+// Discover — scan Claude Code session history to find token savings opportunities
+// Reads ~/.claude/projects/*/sessions/*.jsonl, extracts Bash commands + output sizes,
+// estimates how much terminal would have saved.
+import { readdirSync, readFileSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import { estimateTokens } from "./tokens.js";
+/** Find all Claude session JSONL files */
+function findSessionFiles(claudeDir, maxAge) {
+    const files = [];
+    const projectsDir = join(claudeDir, "projects");
+    if (!existsSync(projectsDir))
+        return files;
+    const now = Date.now();
+    const cutoff = maxAge ? now - maxAge : 0;
+    try {
+        for (const project of readdirSync(projectsDir)) {
+            const projectPath = join(projectsDir, project);
+            // Look for session JSONL files (not subagents)
+            try {
+                for (const entry of readdirSync(projectPath)) {
+                    if (entry.endsWith(".jsonl")) {
+                        const filePath = join(projectPath, entry);
+                        try {
+                            const stat = statSync(filePath);
+                            if (stat.mtimeMs > cutoff)
+                                files.push(filePath);
+                        }
+                        catch { }
+                    }
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return files;
+}
+/** Extract Bash commands and their output sizes from a session file */
+function extractCommands(sessionFile) {
+    const commands = [];
+    try {
+        const content = readFileSync(sessionFile, "utf8");
+        const lines = content.split("\n").filter(l => l.trim());
+        // Track tool_use IDs to match with tool_results
+        const pendingToolUses = new Map(); // id -> command
+        for (const line of lines) {
+            try {
+                const obj = JSON.parse(line);
+                const msg = obj.message;
+                if (!msg?.content || !Array.isArray(msg.content))
+                    continue;
+                for (const block of msg.content) {
+                    // Capture Bash tool_use commands
+                    if (block.type === "tool_use" && block.name === "Bash" && block.input?.command) {
+                        pendingToolUses.set(block.id, block.input.command);
+                    }
+                    // Capture tool_result outputs and match to commands
+                    if (block.type === "tool_result" && block.tool_use_id) {
+                        const command = pendingToolUses.get(block.tool_use_id);
+                        if (command) {
+                            let outputText = "";
+                            if (typeof block.content === "string") {
+                                outputText = block.content;
+                            }
+                            else if (Array.isArray(block.content)) {
+                                outputText = block.content
+                                    .filter((c) => c.type === "text")
+                                    .map((c) => c.text)
+                                    .join("\n");
+                            }
+                            if (outputText.length > 0) {
+                                commands.push({
+                                    command,
+                                    outputTokens: estimateTokens(outputText),
+                                    outputChars: outputText.length,
+                                    sessionFile,
+                                });
+                            }
+                            pendingToolUses.delete(block.tool_use_id);
+                        }
+                    }
+                }
+            }
+            catch { } // skip malformed lines
+        }
+    }
+    catch { } // skip unreadable files
+    return commands;
+}
+/** Categorize a command into a bucket */
+function categorizeCommand(cmd) {
+    const trimmed = cmd.trim();
+    if (/^git\b/.test(trimmed))
+        return "git";
+    if (/\b(bun|npm|yarn|pnpm)\s+(test|run\s+test)/.test(trimmed))
+        return "test";
+    if (/\b(bun|npm|yarn|pnpm)\s+run\s+(build|typecheck|lint)/.test(trimmed))
+        return "build";
+    if (/^(grep|rg)\b/.test(trimmed))
+        return "grep";
+    if (/^find\b/.test(trimmed))
+        return "find";
+    if (/^(cat|head|tail|less)\b/.test(trimmed))
+        return "read";
+    if (/^(ls|tree|du|wc)\b/.test(trimmed))
+        return "list";
+    if (/^(curl|wget|fetch)\b/.test(trimmed))
+        return "network";
+    if (/^(docker|kubectl|helm)\b/.test(trimmed))
+        return "infra";
+    if (/^(python|pip|pytest)\b/.test(trimmed))
+        return "python";
+    if (/^(cargo|rustc)\b/.test(trimmed))
+        return "rust";
+    if (/^(go\s|golangci)\b/.test(trimmed))
+        return "go";
+    return "other";
+}
+/** Normalize command for grouping (strip variable parts like paths, hashes) */
+function normalizeCommand(cmd) {
+    return cmd
+        .replace(/[0-9a-f]{7,40}/g, "{hash}") // git hashes
+        .replace(/\/[\w./-]+\.(ts|tsx|js|json|py|rs|go)\b/g, "{file}") // file paths
+        .replace(/\d{4}-\d{2}-\d{2}/g, "{date}") // dates
+        .replace(/:\d+/g, ":{line}") // line numbers
+        .trim();
+}
+/** Run discover across all Claude sessions */
+export function discover(options = {}) {
+    const claudeDir = join(process.env.HOME ?? "~", ".claude");
+    const maxAge = (options.maxAgeDays ?? 30) * 24 * 60 * 60 * 1000;
+    const minTokens = options.minTokens ?? 50;
+    const sessionFiles = findSessionFiles(claudeDir, maxAge);
+    const allCommands = [];
+    for (const file of sessionFiles) {
+        allCommands.push(...extractCommands(file));
+    }
+    // Filter to commands with meaningful output
+    const significant = allCommands.filter(c => c.outputTokens >= minTokens);
+    // Group by normalized command
+    const groups = new Map();
+    for (const cmd of significant) {
+        const key = normalizeCommand(cmd.command);
+        const existing = groups.get(key) ?? { count: 0, totalTokens: 0, example: cmd.command };
+        existing.count++;
+        existing.totalTokens += cmd.outputTokens;
+        groups.set(key, existing);
+    }
+    // Top commands by total tokens
+    const topCommands = [...groups.entries()]
+        .map(([cmd, data]) => ({
+        command: data.example,
+        count: data.count,
+        totalTokens: data.totalTokens,
+        avgTokens: Math.round(data.totalTokens / data.count),
+    }))
+        .sort((a, b) => b.totalTokens - a.totalTokens)
+        .slice(0, 20);
+    // Category breakdown
+    const commandsByCategory = {};
+    for (const cmd of significant) {
+        const cat = categorizeCommand(cmd.command);
+        if (!commandsByCategory[cat])
+            commandsByCategory[cat] = { count: 0, tokens: 0 };
+        commandsByCategory[cat].count++;
+        commandsByCategory[cat].tokens += cmd.outputTokens;
+    }
+    const totalOutputTokens = significant.reduce((sum, c) => sum + c.outputTokens, 0);
+    // Conservative 70% compression estimate (RTK claims 60-90%)
+    const estimatedSavings = Math.round(totalOutputTokens * 0.7);
+    // Each saved input token is repeated across ~5 turns on average before compaction
+    const multipliedSavings = estimatedSavings * 5;
+    // At Opus rates ($5/M input tokens)
+    const estimatedSavingsUsd = (multipliedSavings * 5) / 1_000_000;
+    return {
+        totalSessions: sessionFiles.length,
+        totalCommands: significant.length,
+        totalOutputTokens,
+        estimatedSavings,
+        estimatedSavingsUsd,
+        topCommands,
+        commandsByCategory,
+    };
+}
+/** Format discover report for CLI display */
+export function formatDiscoverReport(report) {
+    const lines = [];
+    lines.push(`📊 Terminal Discover — Token Savings Analysis`);
+    lines.push(`   Scanned ${report.totalSessions} sessions, ${report.totalCommands} commands with >50 token output\n`);
+    lines.push(`💰 Estimated savings with open-terminal:`);
+    lines.push(`   Output tokens: ${report.totalOutputTokens.toLocaleString()}`);
+    lines.push(`   Compressible:  ${report.estimatedSavings.toLocaleString()} tokens (70% avg)`);
+    lines.push(`   Repeated ~5x before compaction = ${(report.estimatedSavings * 5).toLocaleString()} billable tokens`);
+    lines.push(`   At Opus rates: $${report.estimatedSavingsUsd.toFixed(2)} saved\n`);
+    if (report.topCommands.length > 0) {
+        lines.push(`🔝 Top commands by token cost:`);
+        for (const cmd of report.topCommands.slice(0, 15)) {
+            const avg = cmd.avgTokens.toLocaleString().padStart(6);
+            const total = cmd.totalTokens.toLocaleString().padStart(8);
+            lines.push(`   ${String(cmd.count).padStart(4)}× ${avg} avg → ${total} total  ${cmd.command.slice(0, 60)}`);
+        }
+        lines.push("");
+    }
+    if (Object.keys(report.commandsByCategory).length > 0) {
+        lines.push(`📁 By category:`);
+        const sorted = Object.entries(report.commandsByCategory).sort((a, b) => b[1].tokens - a[1].tokens);
+        for (const [cat, data] of sorted) {
+            lines.push(`   ${cat.padEnd(10)} ${String(data.count).padStart(5)} cmds  ${data.tokens.toLocaleString().padStart(10)} tokens`);
+        }
+    }
+    return lines.join("\n");
+}