@hasna/terminal 0.3.1 → 0.5.0

package/dist/smart-display.js

@@ -78,6 +78,10 @@ function collapseNodeModules(paths) {
 export function smartDisplay(lines) {
     if (lines.length <= 5)
         return lines;
+    // Try ls -la table compression first
+    const lsCompressed = compressLsTable(lines);
+    if (lsCompressed)
+        return lsCompressed;
     if (!looksLikePaths(lines))
         return compressGeneric(lines);
     const paths = lines.map(l => l.trim()).filter(l => l);
@@ -114,7 +118,9 @@ export function smartDisplay(lines) {
             const sorted = files.sort();
             const pattern = findPattern(sorted);
             if (pattern) {
-                result.push(`  ${dir}/${pattern}  ×${files.length}`);
+                const dateRange = collapseDateRange(sorted);
+                const rangeStr = dateRange ? ` (${dateRange})` : "";
+                result.push(`  ${dir}/${pattern}  ×${files.length}${rangeStr}`);
             }
             else {
                 result.push(`  ${dir}/ (${files.length} files)`);
@@ -150,6 +156,96 @@ export function smartDisplay(lines) {
     }
     return result;
 }
+/** Detect date range in timestamps and collapse */
+function collapseDateRange(files) {
+    const timestamps = [];
+    for (const f of files) {
+        const match = f.match(/(\d{4})-(\d{2})-(\d{2})T?(\d{2})?/);
+        if (match) {
+            const [, y, m, d, h] = match;
+            timestamps.push(new Date(`${y}-${m}-${d}T${h ?? "00"}:00:00`));
+        }
+    }
+    if (timestamps.length < 2)
+        return null;
+    timestamps.sort((a, b) => a.getTime() - b.getTime());
+    const first = timestamps[0];
+    const last = timestamps[timestamps.length - 1];
+    const fmt = (d) => `${d.getMonth() + 1}/${d.getDate()}`;
+    if (first.toDateString() === last.toDateString()) {
+        return `${fmt(first)}`;
+    }
+    return `${fmt(first)}–${fmt(last)}`;
+}
+/** Detect and compress ls -la style table output */
+function compressLsTable(lines) {
+    // Detect ls -la format: permissions size date name
+    const lsPattern = /^[dlcbps-][rwxsStT-]{9}\s+\d+\s+\S+\s+\S+\s+\S+\s+\w+\s+\d+\s+[\d:]+\s+.+$/;
+    const isLsOutput = lines.filter(l => lsPattern.test(l.trim())).length > lines.length * 0.5;
+    if (!isLsOutput)
+        return null;
+    const result = [];
+    const dirs = [];
+    const files = [];
+    let totalSize = 0;
+    for (const line of lines) {
+        const match = line.trim().match(/^([dlcbps-])[rwxsStT-]{9}\s+\d+\s+\S+\s+\S+\s+(\S+)\s+\w+\s+\d+\s+[\d:]+\s+(.+)$/);
+        if (!match) {
+            if (line.trim().startsWith("total "))
+                continue;
+            result.push(line);
+            continue;
+        }
+        const [, type, sizeStr, name] = match;
+        const size = parseInt(sizeStr) || 0;
+        totalSize += size;
+        if (type === "d") {
+            dirs.push(name);
+        }
+        else {
+            files.push({ name, size: formatSize(size) });
+        }
+    }
+    // Compact display
+    if (dirs.length > 0) {
+        result.push(`  📁 ${dirs.join("  ")}${dirs.length > 5 ? ` (+${dirs.length - 5} more)` : ""}`);
+    }
+    if (files.length <= 8) {
+        for (const f of files) {
+            result.push(`  ${f.size.padStart(6)}  ${f.name}`);
+        }
+    }
+    else {
+        // Show top 5 by size + count
+        const sorted = files.sort((a, b) => parseSize(b.size) - parseSize(a.size));
+        for (const f of sorted.slice(0, 5)) {
+            result.push(`  ${f.size.padStart(6)}  ${f.name}`);
+        }
+        result.push(`  ... +${files.length - 5} more files (${formatSize(totalSize)} total)`);
+    }
+    return result;
+}
+function formatSize(bytes) {
+    if (bytes >= 1_000_000)
+        return `${(bytes / 1_000_000).toFixed(1)}M`;
+    if (bytes >= 1_000)
+        return `${(bytes / 1_000).toFixed(1)}K`;
+    return `${bytes}B`;
+}
+function parseSize(s) {
+    const match = s.match(/([\d.]+)([BKMG])?/);
+    if (!match)
+        return 0;
+    const n = parseFloat(match[1]);
+    const unit = match[2];
+    if (unit === "K")
+        return n * 1000;
+    if (unit === "M")
+        return n * 1000000;
+    if (unit === "G")
+        return n * 1000000000;
+    return n;
+}
 /** Compress non-path generic output by deduplicating similar lines */
 function compressGeneric(lines) {
     if (lines.length <= 10)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/terminal",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Smart terminal wrapper for AI agents and humans — structured output, token compression, MCP server, natural language",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@typescript/vfs": "^1.6.4",
     "better-sqlite3": "^12.8.0",
     "ink": "^5.0.1",
     "react": "^18.2.0",
@@ -34,6 +35,6 @@
     "@types/node": "^20.0.0",
     "@types/react": "^18.2.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.9.3"
   }
 }

package/src/App.tsx

@@ -11,6 +11,7 @@ import Browse from "./Browse.js";
 import FuzzyPicker from "./FuzzyPicker.js";
 import { createSession, endSession, logInteraction, updateInteraction } from "./sessions-db.js";
 import { smartDisplay } from "./smart-display.js";
+import { processOutput, shouldProcess } from "./output-processor.js";
 
 loadCache();
 
@@ -134,10 +135,21 @@ export default function App() {
   const pushScroll = (entry: Omit<ScrollEntry, "expanded">) =>
     updateTab(t => ({ ...t, scroll: [...t.scroll, { ...entry, expanded: false }] }));
 
-  const commitStream = (nl: string, cmd: string, lines: string[], error: boolean) => {
+  const commitStream = async (nl: string, cmd: string, lines: string[], error: boolean) => {
     const filePaths = !error ? extractFilePaths(lines) : [];
-    // Smart display: compress repetitive output (paths, duplicates, patterns)
-    const displayLines = !error && lines.length > 5 ? smartDisplay(lines) : lines;
+    // Smart display: first try pattern-based compression, then AI if still large
+    let displayLines = !error && lines.length > 5 ? smartDisplay(lines) : lines;
+
+    // AI-powered processing for large outputs (no hardcoded patterns)
+    if (!error && shouldProcess(lines.join("\n"))) {
+      try {
+        const processed = await processOutput(cmd, lines.join("\n"));
+        if (processed.aiProcessed && processed.tokensSaved > 50) {
+          displayLines = processed.summary.split("\n");
+        }
+      } catch { /* fallback to smartDisplay result */ }
+    }
+
     const truncated = displayLines.length > MAX_LINES;
     // Build short output summary for session context (first 10 lines of ORIGINAL output)
     const shortOutput = lines.slice(0, 10).join("\n") + (lines.length > 10 ? `\n... (${lines.length} lines total)` : "");
@@ -185,14 +197,15 @@ export default function App() {
               updateTab(t => ({ ...t, cwd: newCwd }));
             } catch {}
           }
-          commitStream(nl, command, lines, code !== 0);
-          abortRef.current = null;
-          if (code !== 0 && !raw) {
-            setPhase({ type: "autofix", nl, command, errorOutput: lines.join("\n") });
-          } else {
-            inputPhase({ raw });
-          }
-          resolve();
+          commitStream(nl, command, lines, code !== 0).then(() => {
+            abortRef.current = null;
+            if (code !== 0 && !raw) {
+              setPhase({ type: "autofix", nl, command, errorOutput: lines.join("\n") });
+            } else {
+              inputPhase({ raw });
+            }
+            resolve();
+          });
         },
         abort.signal
       );

package/src/cli.tsx

@@ -152,6 +152,36 @@ else if (args[0] === "sessions") {
   }
 }
 
+// ── Repo command ─────────────────────────────────────────────────────────────
+
+else if (args[0] === "repo") {
+  const { execSync } = await import("child_process");
+  const run = (cmd: string) => { try { return execSync(cmd, { encoding: "utf8", cwd: process.cwd() }).trim(); } catch { return ""; } };
+  const branch = run("git branch --show-current");
+  const status = run("git status --short");
+  const log = run("git log --oneline -8 --decorate");
+  console.log(`Branch: ${branch}`);
+  if (status) { console.log(`\nChanges:\n${status}`); }
+  else { console.log("\nClean working tree"); }
+  console.log(`\nRecent:\n${log}`);
+}
+
+// ── Symbols command ──────────────────────────────────────────────────────────
+
+else if (args[0] === "symbols" && args[1]) {
+  const { extractSymbolsFromFile } = await import("./search/semantic.js");
+  const { resolve } = await import("path");
+  const filePath = resolve(args[1]);
+  const symbols = extractSymbolsFromFile(filePath);
+  if (symbols.length === 0) { console.log("No symbols found."); }
+  else {
+    for (const s of symbols) {
+      const exp = s.exported ? "⬡" : "·";
+      console.log(`  ${exp} ${s.kind.padEnd(10)} L${String(s.line).padStart(4)}  ${s.name}`);
+    }
+  }
+}
+
 // ── Snapshot command ─────────────────────────────────────────────────────────
 
 else if (args[0] === "snapshot") {

package/src/file-cache.ts

@@ -0,0 +1,95 @@
+// Universal session file cache — cache any file read, serve from memory on repeat
+
+import { statSync, readFileSync } from "fs";
+
+interface CachedFile {
+  content: string;
+  mtime: number;
+  readCount: number;
+  firstReadAt: number;
+  lastReadAt: number;
+}
+
+const cache = new Map<string, CachedFile>();
+
+/** Read a file with session caching. Returns content + cache metadata. */
+export function cachedRead(
+  filePath: string,
+  options: { offset?: number; limit?: number } = {}
+): { content: string; cached: boolean; readCount: number } {
+  const { offset, limit } = options;
+
+  try {
+    const stat = statSync(filePath);
+    const mtime = stat.mtimeMs;
+    const existing = cache.get(filePath);
+
+    // Cache hit — file unchanged
+    if (existing && existing.mtime === mtime) {
+      existing.readCount++;
+      existing.lastReadAt = Date.now();
+
+      const lines = existing.content.split("\n");
+      if (offset !== undefined || limit !== undefined) {
+        const start = offset ?? 0;
+        const end = limit !== undefined ? start + limit : lines.length;
+        return {
+          content: lines.slice(start, end).join("\n"),
+          cached: true,
+          readCount: existing.readCount,
+        };
+      }
+
+      return { content: existing.content, cached: true, readCount: existing.readCount };
+    }
+
+    // Cache miss or stale — read from disk
+    const content = readFileSync(filePath, "utf8");
+    cache.set(filePath, {
+      content,
+      mtime,
+      readCount: 1,
+      firstReadAt: Date.now(),
+      lastReadAt: Date.now(),
+    });
+
+    const lines = content.split("\n");
+    if (offset !== undefined || limit !== undefined) {
+      const start = offset ?? 0;
+      const end = limit !== undefined ? start + limit : lines.length;
+      return { content: lines.slice(start, end).join("\n"), cached: false, readCount: 1 };
+    }
+
+    return { content, cached: false, readCount: 1 };
+  } catch (e: any) {
+    return { content: `Error: ${e.message}`, cached: false, readCount: 0 };
+  }
+}
+
+/** Invalidate cache for a file (call after writes) */
+export function invalidateFile(filePath: string): void {
+  cache.delete(filePath);
+}
+
+/** Invalidate all files matching a pattern */
+export function invalidatePattern(pattern: RegExp): void {
+  for (const key of cache.keys()) {
+    if (pattern.test(key)) cache.delete(key);
+  }
+}
+
+/** Get cache stats */
+export function cacheStats(): { files: number; totalReads: number; cacheHits: number } {
+  let totalReads = 0;
+  let cacheHits = 0;
+  for (const entry of cache.values()) {
+    totalReads += entry.readCount;
+    cacheHits += Math.max(0, entry.readCount - 1); // first read is never cached
+  }
+  return { files: cache.size, totalReads, cacheHits };
+}
+
+/** Clear the entire cache */
+export function clearFileCache(): void {
+  cache.clear();
+}

package/src/mcp/server.ts

@@ -7,12 +7,14 @@ import { spawn } from "child_process";
 import { compress, stripAnsi } from "../compression.js";
 import { parseOutput, tokenSavings, estimateTokens } from "../parsers/index.js";
 import { summarizeOutput } from "../ai.js";
-import { searchFiles, searchContent } from "../search/index.js";
+import { searchFiles, searchContent, semanticSearch } from "../search/index.js";
 import { listRecipes, listCollections, getRecipe, createRecipe } from "../recipes/storage.js";
 import { substituteVariables } from "../recipes/model.js";
 import { bgStart, bgStatus, bgStop, bgLogs, bgWaitPort } from "../supervisor.js";
 import { diffOutput } from "../diff-cache.js";
+import { processOutput } from "../output-processor.js";
 import { listSessions, getSessionInteractions, getSessionStats } from "../sessions-db.js";
+import { cachedRead, cacheStats } from "../file-cache.js";
 import { getEconomyStats, recordSaving } from "../economy.js";
 import { captureSnapshot } from "../snapshots.js";
 
@@ -127,6 +129,35 @@ export function createServer(): McpServer {
     }
   );
 
+  // ── execute_smart: AI-powered output processing ────────────────────────────
+
+  server.tool(
+    "execute_smart",
+    "Run a command and get AI-summarized output. The AI decides what's important — errors, failures, key results are kept; verbose logs, progress bars, passing tests are dropped. Saves 80-95% tokens vs raw output. Best tool for agents.",
+    {
+      command: z.string().describe("Shell command to execute"),
+      cwd: z.string().optional().describe("Working directory"),
+      timeout: z.number().optional().describe("Timeout in ms (default: 30000)"),
+    },
+    async ({ command, cwd, timeout }) => {
+      const result = await exec(command, cwd, timeout ?? 30000);
+      const output = (result.stdout + result.stderr).trim();
+      const processed = await processOutput(command, output);
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          exitCode: result.exitCode,
+          summary: processed.summary,
+          structured: processed.structured,
+          duration: result.duration,
+          totalLines: output.split("\n").length,
+          tokensSaved: processed.tokensSaved,
+          aiProcessed: processed.aiProcessed,
+        }) }],
+      };
+    }
+  );
+
   // ── browse: list files/dirs as structured JSON ────────────────────────────
 
   server.tool(
@@ -238,6 +269,28 @@ export function createServer(): McpServer {
     }
   );
 
+  // ── search_semantic: AST-powered code search ───────────────────────────────
+
+  server.tool(
+    "search_semantic",
+    "Semantic code search — find functions, classes, components, hooks, types by meaning. Uses AST parsing, not string matching. Much more precise than grep for code navigation.",
+    {
+      query: z.string().describe("What to search for (e.g., 'auth functions', 'React components', 'database hooks')"),
+      path: z.string().optional().describe("Search root (default: cwd)"),
+      kinds: z.array(z.enum(["function", "class", "interface", "type", "variable", "export", "import", "component", "hook"])).optional().describe("Filter by symbol kind"),
+      exportedOnly: z.boolean().optional().describe("Only show exported symbols (default: false)"),
+      maxResults: z.number().optional().describe("Max results (default: 30)"),
+    },
+    async ({ query, path, kinds, exportedOnly, maxResults }) => {
+      const result = await semanticSearch(query, path ?? process.cwd(), {
+        kinds: kinds as any,
+        exportedOnly,
+        maxResults,
+      });
+      return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
+    }
+  );
+
   // ── list_recipes: list saved command recipes ──────────────────────────────
 
   server.tool(
@@ -487,6 +540,97 @@ export function createServer(): McpServer {
     }
   );
 
+  // ── read_file: cached file reading ─────────────────────────────────────────
+
+  server.tool(
+    "read_file",
+    "Read a file with session caching. Second read of unchanged file returns instantly from cache. Supports offset/limit for pagination without re-reading.",
+    {
+      path: z.string().describe("File path"),
+      offset: z.number().optional().describe("Start line (0-indexed)"),
+      limit: z.number().optional().describe("Max lines to return"),
+    },
+    async ({ path, offset, limit }) => {
+      const result = cachedRead(path, { offset, limit });
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          content: result.content,
+          cached: result.cached,
+          readCount: result.readCount,
+          ...(result.cached ? { note: `Served from cache (read #${result.readCount})` } : {}),
+        }) }],
+      };
+    }
+  );
+
+  // ── repo_state: git status + diff + log in one call ───────────────────────
+
+  server.tool(
+    "repo_state",
+    "Get full repository state in one call — branch, status, staged/unstaged files, recent commits. Replaces the common 3-command pattern: git status + git diff --stat + git log.",
+    {
+      path: z.string().optional().describe("Repo path (default: cwd)"),
+    },
+    async ({ path }) => {
+      const cwd = path ?? process.cwd();
+      const [statusResult, diffResult, logResult] = await Promise.all([
+        exec("git status --porcelain", cwd),
+        exec("git diff --stat", cwd),
+        exec("git log --oneline -12 --decorate", cwd),
+      ]);
+
+      const branchResult = await exec("git branch --show-current", cwd);
+
+      const staged: string[] = [];
+      const unstaged: string[] = [];
+      const untracked: string[] = [];
+      for (const line of statusResult.stdout.split("\n").filter(l => l.trim())) {
+        const x = line[0], y = line[1], file = line.slice(3);
+        if (x === "?" && y === "?") untracked.push(file);
+        else if (x !== " " && x !== "?") staged.push(file);
+        if (y !== " " && y !== "?") unstaged.push(file);
+      }
+
+      const commits = logResult.stdout.split("\n").filter(l => l.trim()).map(l => {
+        const match = l.match(/^([a-f0-9]+)\s+(.+)$/);
+        return match ? { hash: match[1], message: match[2] } : { hash: "", message: l };
+      });
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          branch: branchResult.stdout.trim(),
+          dirty: staged.length + unstaged.length + untracked.length > 0,
+          staged, unstaged, untracked,
+          diffSummary: diffResult.stdout.trim() || "no changes",
+          recentCommits: commits,
+        }) }],
+      };
+    }
+  );
+
+  // ── symbols: file structure outline ───────────────────────────────────────
+
+  server.tool(
+    "symbols",
+    "Get a structured outline of a source file — functions, classes, interfaces, exports with line numbers. Replaces the common grep pattern: grep -n '^export|class|function' file.",
+    {
+      path: z.string().describe("File path to extract symbols from"),
+    },
+    async ({ path: filePath }) => {
+      const { semanticSearch } = await import("../search/semantic.js");
+      const dir = filePath.replace(/\/[^/]+$/, "") || ".";
+      const file = filePath.split("/").pop() ?? filePath;
+      const result = await semanticSearch(file.replace(/\.\w+$/, ""), dir, { maxResults: 50 });
+      // Filter to only symbols from the requested file
+      const fileSymbols = result.symbols.filter(s =>
+        s.file.endsWith(filePath) || s.file.endsWith("/" + filePath)
+      );
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(fileSymbols) }],
+      };
+    }
+  );
+
   return server;
 }
 

package/src/output-processor.ts

@@ -0,0 +1,125 @@
+// AI-powered output processor — uses cheap AI to intelligently summarize any output
+// NOTHING is hardcoded. The AI decides what's important, what's noise, what to keep.
+
+import { getProvider } from "./providers/index.js";
+import { estimateTokens } from "./parsers/index.js";
+import { recordSaving } from "./economy.js";
+
+export interface ProcessedOutput {
+  /** AI-generated summary (concise, structured) */
+  summary: string;
+  /** Full original output (always available) */
+  full: string;
+  /** Structured JSON if the AI could extract it */
+  structured?: Record<string, unknown>;
+  /** How many tokens were saved */
+  tokensSaved: number;
+  /** Whether AI processing was used (vs passthrough) */
+  aiProcessed: boolean;
+}
+
+const MIN_LINES_TO_PROCESS = 15;
+const MAX_OUTPUT_FOR_AI = 8000; // chars to send to AI (truncate if longer)
+
+const SUMMARIZE_PROMPT = `You are an output summarizer for a terminal. Given command output, return a CONCISE structured summary.
+
+RULES:
+- Return ONLY the summary, no explanations
+- For test output: show pass count, fail count, and ONLY the failing test names + errors
+- For build output: show status (ok/fail), error count, warning count
+- For install output: show package count, time, vulnerabilities
+- For file listings: show directory count, file count, notable files
+- For git output: show branch, status, key info
+- For logs: show line count, error count, latest error
+- For search results: show match count, top files
+- For ANY output: keep errors/failures/warnings, drop verbose/repetitive/progress lines
+- Use symbols: ✓ for success, ✗ for failure, ⚠ for warnings
+- Maximum 8 lines in your summary
+- If there are errors, ALWAYS include them verbatim`;
+
+/**
+ * Process command output through AI summarization.
+ * Cheap AI call (~100 tokens) saves 1000+ tokens downstream.
+ */
+export async function processOutput(
+  command: string,
+  output: string,
+): Promise<ProcessedOutput> {
+  const lines = output.split("\n");
+
+  // Short output — pass through, no AI needed
+  if (lines.length <= MIN_LINES_TO_PROCESS) {
+    return {
+      summary: output,
+      full: output,
+      tokensSaved: 0,
+      aiProcessed: false,
+    };
+  }
+
+  // Truncate very long output before sending to AI
+  let toSummarize = output;
+  if (toSummarize.length > MAX_OUTPUT_FOR_AI) {
+    const headChars = Math.floor(MAX_OUTPUT_FOR_AI * 0.6);
+    const tailChars = Math.floor(MAX_OUTPUT_FOR_AI * 0.3);
+    toSummarize = output.slice(0, headChars) +
+      `\n\n... (${lines.length} total lines, middle truncated) ...\n\n` +
+      output.slice(-tailChars);
+  }
+
+  try {
+    const provider = getProvider();
+    const summary = await provider.complete(
+      `Command: ${command}\nOutput (${lines.length} lines):\n${toSummarize}`,
+      {
+        system: SUMMARIZE_PROMPT,
+        maxTokens: 300,
+      }
+    );
+
+    const originalTokens = estimateTokens(output);
+    const summaryTokens = estimateTokens(summary);
+    const saved = Math.max(0, originalTokens - summaryTokens);
+
+    if (saved > 0) {
+      recordSaving("compressed", saved);
+    }
+
+    // Try to extract structured JSON if the AI returned it
+    let structured: Record<string, unknown> | undefined;
+    try {
+      const jsonMatch = summary.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        structured = JSON.parse(jsonMatch[0]);
+      }
+    } catch { /* not JSON, that's fine */ }
+
+    return {
+      summary,
+      full: output,
+      structured,
+      tokensSaved: saved,
+      aiProcessed: true,
+    };
+  } catch {
+    // AI unavailable — fall back to simple truncation
+    const head = lines.slice(0, 5).join("\n");
+    const tail = lines.slice(-5).join("\n");
+    const fallback = `${head}\n  ... (${lines.length - 10} lines hidden) ...\n${tail}`;
+
+    return {
+      summary: fallback,
+      full: output,
+      tokensSaved: Math.max(0, estimateTokens(output) - estimateTokens(fallback)),
+      aiProcessed: false,
+    };
+  }
+}
+
+/**
+ * Lightweight version — just decides IF output should be processed.
+ * Returns true if the output would benefit from AI summarization.
+ */
+export function shouldProcess(output: string): boolean {
+  return output.split("\n").length > MIN_LINES_TO_PROCESS;
+}

package/src/search/content-search.ts

@@ -93,5 +93,13 @@ export async function searchContent(
   const resultTokens = Math.ceil(JSON.stringify(result).length / 4);
   result.tokensSaved = Math.max(0, rawTokens - resultTokens);
 
+  // Overflow guard — warn when results are truncated
+  if (totalMatches > maxResults * 3) {
+    (result as any).overflow = {
+      warning: `${totalMatches} total matches across ${fileMap.size} files — showing top ${files.length}`,
+      suggestion: "Try a more specific pattern, add fileType filter, or use -l to list files only",
+    };
+  }
+
   return result;
 }

package/src/search/index.ts

@@ -5,3 +5,5 @@ export type { FileSearchResult } from "./file-search.js";
 export { searchContent } from "./content-search.js";
 export type { ContentSearchResult, ContentFileMatch, ContentMatch } from "./content-search.js";
 export { DEFAULT_EXCLUDE_DIRS, SOURCE_EXTENSIONS, isSourceFile, isExcludedDir, relevanceScore } from "./filters.js";
+export { semanticSearch, findExports, findComponents, findHooks } from "./semantic.js";
+export type { CodeSymbol, SemanticSearchResult } from "./semantic.js";