@hasna/terminal 2.3.1 → 3.0.1

package/dist/parsers/tests.js

@@ -0,0 +1,89 @@
+// Parser for test runner output (jest, vitest, bun test, pytest, go test)
+export const testParser = {
+    name: "test",
+    detect(command, output) {
+        if (/\b(jest|vitest|bun\s+test|pytest|go\s+test|mocha|ava|tap)\b/.test(command))
+            return true;
+        if (/\b(npm|bun|pnpm|yarn)\s+(run\s+)?test\b/.test(command))
+            return true;
+        // Detect by output patterns
+        return /Tests:\s+\d+/.test(output) || /\d+\s+(passing|passed|failed)/.test(output) || /PASS|FAIL/.test(output);
+    },
+    parse(_command, output) {
+        const failures = [];
+        let passed = 0, failed = 0, skipped = 0, duration;
+        // Jest/Vitest style: Tests: 5 passed, 2 failed, 7 total
+        const jestMatch = output.match(/Tests:\s+(?:(\d+)\s+passed)?[,\s]*(?:(\d+)\s+failed)?[,\s]*(?:(\d+)\s+skipped)?[,\s]*(\d+)\s+total/);
+        if (jestMatch) {
+            passed = parseInt(jestMatch[1] ?? "0");
+            failed = parseInt(jestMatch[2] ?? "0");
+            skipped = parseInt(jestMatch[3] ?? "0");
+        }
+        // Bun test style: 5 pass, 2 fail
+        const bunMatch = output.match(/(\d+)\s+pass.*?(\d+)\s+fail/);
+        if (!jestMatch && bunMatch) {
+            passed = parseInt(bunMatch[1]);
+            failed = parseInt(bunMatch[2]);
+        }
+        // Pytest style: 5 passed, 2 failed
+        const pytestMatch = output.match(/(\d+)\s+passed(?:.*?(\d+)\s+failed)?/);
+        if (!jestMatch && !bunMatch && pytestMatch) {
+            passed = parseInt(pytestMatch[1]);
+            failed = parseInt(pytestMatch[2] ?? "0");
+        }
+        // Go test: ok/FAIL + count
+        const goPassMatch = output.match(/ok\s+\S+\s+([\d.]+s)/);
+        const goFailMatch = output.match(/FAIL\s+\S+/);
+        if (!jestMatch && !bunMatch && !pytestMatch && (goPassMatch || goFailMatch)) {
+            const passLines = (output.match(/--- PASS/g) || []).length;
+            const failLines = (output.match(/--- FAIL/g) || []).length;
+            passed = passLines;
+            failed = failLines;
+            if (goPassMatch)
+                duration = goPassMatch[1];
+        }
+        // Duration
+        const timeMatch = output.match(/Time:\s+([\d.]+\s*(?:s|ms|m))/i) || output.match(/in\s+([\d.]+\s*(?:s|ms|m))/i);
+        if (timeMatch)
+            duration = timeMatch[1];
+        // Extract failure details: lines starting with FAIL or ✗ or ×
+        const lines = output.split("\n");
+        let capturingFailure = false;
+        let currentTest = "";
+        let currentError = [];
+        for (const line of lines) {
+            const failMatch = line.match(/(?:FAIL|✗|×|✕)\s+(.+)/);
+            if (failMatch) {
+                if (capturingFailure && currentTest) {
+                    failures.push({ test: currentTest, error: currentError.join("\n").trim() });
+                }
+                currentTest = failMatch[1].trim();
+                currentError = [];
+                capturingFailure = true;
+                continue;
+            }
+            if (capturingFailure) {
+                if (line.match(/^(PASS|✓|✔|FAIL|✗|×|✕)\s/) || line.match(/^Tests:|^\d+ pass/)) {
+                    failures.push({ test: currentTest, error: currentError.join("\n").trim() });
+                    capturingFailure = false;
+                    currentTest = "";
+                    currentError = [];
+                }
+                else {
+                    currentError.push(line);
+                }
+            }
+        }
+        if (capturingFailure && currentTest) {
+            failures.push({ test: currentTest, error: currentError.join("\n").trim() });
+        }
+        return {
+            passed,
+            failed,
+            skipped,
+            total: passed + failed + skipped,
+            duration,
+            failures,
+        };
+    },
+};

package/dist/providers/anthropic.js

@@ -0,0 +1,43 @@
+import Anthropic from "@anthropic-ai/sdk";
+export class AnthropicProvider {
+    name = "anthropic";
+    client;
+    constructor() {
+        this.client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+    }
+    isAvailable() {
+        return !!process.env.ANTHROPIC_API_KEY;
+    }
+    async complete(prompt, options) {
+        const message = await this.client.messages.create({
+            model: options.model ?? "claude-haiku-4-5-20251001",
+            max_tokens: options.maxTokens ?? 256,
+            temperature: options.temperature ?? 0,
+            ...(options.stop ? { stop_sequences: options.stop } : {}),
+            system: [{ type: "text", text: options.system, cache_control: { type: "ephemeral" } }],
+            messages: [{ role: "user", content: prompt }],
+        });
+        const block = message.content[0];
+        if (block.type !== "text")
+            throw new Error("Unexpected response type");
+        return block.text.trim();
+    }
+    async stream(prompt, options, callbacks) {
+        let result = "";
+        const stream = await this.client.messages.stream({
+            model: options.model ?? "claude-haiku-4-5-20251001",
+            max_tokens: options.maxTokens ?? 256,
+            temperature: options.temperature ?? 0,
+            ...(options.stop ? { stop_sequences: options.stop } : {}),
+            system: [{ type: "text", text: options.system, cache_control: { type: "ephemeral" } }],
+            messages: [{ role: "user", content: prompt }],
+        });
+        for await (const chunk of stream) {
+            if (chunk.type === "content_block_delta" && chunk.delta.type === "text_delta") {
+                result += chunk.delta.text;
+                callbacks.onToken(result.trim());
+            }
+        }
+        return result.trim();
+    }
+}

package/dist/providers/base.js

@@ -0,0 +1,4 @@
+// Provider interface for LLM backends (Anthropic, Cerebras, etc.)
+export const DEFAULT_PROVIDER_CONFIG = {
+    provider: "auto",
+};

package/dist/providers/cerebras.js

@@ -0,0 +1,8 @@
+// Cerebras provider — fast inference on Qwen/Llama models
+import { OpenAICompatibleProvider } from "./openai-compat.js";
+export class CerebrasProvider extends OpenAICompatibleProvider {
+    name = "cerebras";
+    baseUrl = "https://api.cerebras.ai/v1";
+    defaultModel = "qwen-3-235b-a22b-instruct-2507";
+    apiKeyEnvVar = "CEREBRAS_API_KEY";
+}

package/dist/providers/groq.js

@@ -0,0 +1,8 @@
+// Groq provider — ultra-fast inference
+import { OpenAICompatibleProvider } from "./openai-compat.js";
+export class GroqProvider extends OpenAICompatibleProvider {
+    name = "groq";
+    baseUrl = "https://api.groq.com/openai/v1";
+    defaultModel = "openai/gpt-oss-120b";
+    apiKeyEnvVar = "GROQ_API_KEY";
+}

package/dist/providers/index.js

@@ -0,0 +1,122 @@
+// Provider auto-detection and management — with fallback on failure
+import { DEFAULT_PROVIDER_CONFIG } from "./base.js";
+import { AnthropicProvider } from "./anthropic.js";
+import { CerebrasProvider } from "./cerebras.js";
+import { GroqProvider } from "./groq.js";
+import { XaiProvider } from "./xai.js";
+export { DEFAULT_PROVIDER_CONFIG } from "./base.js";
+let _provider = null;
+let _failedProviders = new Set();
+/** Get the active LLM provider. Auto-detects based on available API keys. */
+export function getProvider(config) {
+    if (_provider && !_failedProviders.has(_provider.name))
+        return _provider;
+    const cfg = config ?? DEFAULT_PROVIDER_CONFIG;
+    _provider = resolveProvider(cfg);
+    return _provider;
+}
+/** Reset the cached provider (useful when config changes). */
+export function resetProvider() {
+    _provider = null;
+    _failedProviders.clear();
+}
+/** Get a fallback-wrapped provider that tries alternatives on failure */
+export function getProviderWithFallback(config) {
+    const primary = getProvider(config);
+    return new FallbackProvider(primary);
+}
+function resolveProvider(config) {
+    if (config.provider !== "auto") {
+        const providers = {
+            cerebras: () => new CerebrasProvider(),
+            anthropic: () => new AnthropicProvider(),
+            groq: () => new GroqProvider(),
+            xai: () => new XaiProvider(),
+        };
+        const factory = providers[config.provider];
+        if (factory) {
+            const p = factory();
+            if (!p.isAvailable())
+                throw new Error(`${config.provider.toUpperCase()}_API_KEY not set`);
+            return p;
+        }
+    }
+    // auto: prefer Cerebras, then xAI, then Groq, then Anthropic — skip failed
+    const candidates = [
+        new CerebrasProvider(),
+        new XaiProvider(),
+        new GroqProvider(),
+        new AnthropicProvider(),
+    ];
+    for (const p of candidates) {
+        if (p.isAvailable() && !_failedProviders.has(p.name))
+            return p;
+    }
+    // If all failed, clear failures and try again
+    if (_failedProviders.size > 0) {
+        _failedProviders.clear();
+        for (const p of candidates) {
+            if (p.isAvailable())
+                return p;
+        }
+    }
+    throw new Error("No API key found. Set one of:\n" +
+        "  export CEREBRAS_API_KEY=your-key  (free, open-source)\n" +
+        "  export GROQ_API_KEY=your-key      (free, fast)\n" +
+        "  export XAI_API_KEY=your-key       (Grok, code-optimized)\n" +
+        "  export ANTHROPIC_API_KEY=your-key  (Claude)");
+}
+/** Provider wrapper that falls back to alternatives on API errors */
+class FallbackProvider {
+    name;
+    primary;
+    constructor(primary) {
+        this.primary = primary;
+        this.name = primary.name;
+    }
+    isAvailable() {
+        return this.primary.isAvailable();
+    }
+    async complete(prompt, options) {
+        try {
+            return await this.primary.complete(prompt, options);
+        }
+        catch (err) {
+            const fallback = this.getFallback();
+            if (fallback)
+                return fallback.complete(prompt, options);
+            throw err;
+        }
+    }
+    async stream(prompt, options, callbacks) {
+        try {
+            return await this.primary.stream(prompt, options, callbacks);
+        }
+        catch (err) {
+            const fallback = this.getFallback();
+            if (fallback)
+                return fallback.complete(prompt, options); // fallback doesn't stream
+            throw err;
+        }
+    }
+    getFallback() {
+        _failedProviders.add(this.primary.name);
+        _provider = null; // force re-resolve
+        try {
+            const next = getProvider();
+            if (next.name !== this.primary.name)
+                return next;
+        }
+        catch { }
+        return null;
+    }
+}
+/** List available providers (for onboarding UI). */
+export function availableProviders() {
+    return [
+        { name: "cerebras", available: new CerebrasProvider().isAvailable() },
+        { name: "groq", available: new GroqProvider().isAvailable() },
+        { name: "xai", available: new XaiProvider().isAvailable() },
+        { name: "anthropic", available: new AnthropicProvider().isAvailable() },
+    ];
+}

package/dist/providers/openai-compat.js

@@ -0,0 +1,93 @@
+// Shared base class for OpenAI-compatible providers (Cerebras, Groq, xAI)
+// Eliminates ~200 lines of duplicated streaming SSE parsing
+export class OpenAICompatibleProvider {
+    get apiKey() {
+        return process.env[this.apiKeyEnvVar] ?? "";
+    }
+    isAvailable() {
+        return !!process.env[this.apiKeyEnvVar];
+    }
+    async complete(prompt, options) {
+        const res = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: options.model ?? this.defaultModel,
+                max_tokens: options.maxTokens ?? 256,
+                temperature: options.temperature ?? 0,
+                ...(options.stop ? { stop: options.stop } : {}),
+                messages: [
+                    { role: "system", content: options.system },
+                    { role: "user", content: prompt },
+                ],
+            }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`${this.name} API error ${res.status}: ${text}`);
+        }
+        const json = (await res.json());
+        return (json.choices?.[0]?.message?.content ?? "").trim();
+    }
+    async stream(prompt, options, callbacks) {
+        const res = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: options.model ?? this.defaultModel,
+                max_tokens: options.maxTokens ?? 256,
+                temperature: options.temperature ?? 0,
+                stream: true,
+                ...(options.stop ? { stop: options.stop } : {}),
+                messages: [
+                    { role: "system", content: options.system },
+                    { role: "user", content: prompt },
+                ],
+            }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`${this.name} API error ${res.status}: ${text}`);
+        }
+        let result = "";
+        const reader = res.body?.getReader();
+        if (!reader)
+            throw new Error("No response body");
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith("data: "))
+                    continue;
+                const data = trimmed.slice(6);
+                if (data === "[DONE]")
+                    break;
+                try {
+                    const parsed = JSON.parse(data);
+                    const delta = parsed.choices?.[0]?.delta?.content;
+                    if (delta) {
+                        result += delta;
+                        callbacks.onToken(result.trim());
+                    }
+                }
+                catch {
+                    // skip malformed chunks
+                }
+            }
+        }
+        return result.trim();
+    }
+}

package/dist/providers/xai.js

@@ -0,0 +1,8 @@
+// xAI/Grok provider — code-optimized models
+import { OpenAICompatibleProvider } from "./openai-compat.js";
+export class XaiProvider extends OpenAICompatibleProvider {
+    name = "xai";
+    baseUrl = "https://api.x.ai/v1";
+    defaultModel = "grok-code-fast-1";
+    apiKeyEnvVar = "XAI_API_KEY";
+}

package/dist/recipes/model.js

@@ -0,0 +1,20 @@
+// Recipes data model — reusable command templates with collections and projects
+/** Generate a short random ID */
+export function genId() {
+    return Math.random().toString(36).slice(2, 10);
+}
+/** Substitute variables in a command template */
+export function substituteVariables(command, vars) {
+    let result = command;
+    for (const [name, value] of Object.entries(vars)) {
+        result = result.replace(new RegExp(`\\{${name}\\}`, "g"), value);
+    }
+    return result;
+}
+/** Extract variable placeholders from a command */
+export function extractVariables(command) {
+    const matches = command.match(/\{(\w+)\}/g);
+    if (!matches)
+        return [];
+    return [...new Set(matches.map(m => m.slice(1, -1)))];
+}

package/dist/recipes/storage.js

@@ -0,0 +1,136 @@
+// Recipes storage — global (~/.terminal/recipes.json) + per-project (.terminal/recipes.json)
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { genId, extractVariables } from "./model.js";
+const GLOBAL_DIR = join(homedir(), ".terminal");
+const GLOBAL_FILE = join(GLOBAL_DIR, "recipes.json");
+function projectFile(projectPath) {
+    return join(projectPath, ".terminal", "recipes.json");
+}
+function loadStore(filePath) {
+    if (!existsSync(filePath))
+        return { recipes: [], collections: [] };
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return { recipes: [], collections: [] };
+    }
+}
+function saveStore(filePath, store) {
+    const dir = filePath.replace(/\/[^/]+$/, "");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, JSON.stringify(store, null, 2));
+}
+// ── CRUD operations ──────────────────────────────────────────────────────────
+/** Get all recipes (merged: global + project-scoped) */
+export function listRecipes(projectPath) {
+    const global = loadStore(GLOBAL_FILE).recipes;
+    if (!projectPath)
+        return global;
+    const project = loadStore(projectFile(projectPath)).recipes;
+    return [...project, ...global]; // project recipes first (higher priority)
+}
+/** Get recipes filtered by collection */
+export function listByCollection(collection, projectPath) {
+    return listRecipes(projectPath).filter(r => r.collection === collection);
+}
+/** Get a recipe by name */
+export function getRecipe(name, projectPath) {
+    return listRecipes(projectPath).find(r => r.name === name) ?? null;
+}
+/** Create a recipe */
+export function createRecipe(opts) {
+    const filePath = opts.project ? projectFile(opts.project) : GLOBAL_FILE;
+    const store = loadStore(filePath);
+    // Prevent duplicates — update existing if same name
+    const existingIdx = store.recipes.findIndex(r => r.name === opts.name);
+    if (existingIdx >= 0) {
+        store.recipes[existingIdx].command = opts.command;
+        store.recipes[existingIdx].updatedAt = Date.now();
+        if (opts.description)
+            store.recipes[existingIdx].description = opts.description;
+        if (opts.tags)
+            store.recipes[existingIdx].tags = opts.tags;
+        if (opts.collection)
+            store.recipes[existingIdx].collection = opts.collection;
+        saveStore(filePath, store);
+        return store.recipes[existingIdx];
+    }
+    // Auto-detect variables from command if not explicitly provided
+    const detectedVars = extractVariables(opts.command);
+    const variables = opts.variables ?? detectedVars.map(name => ({ name, required: true }));
+    const recipe = {
+        id: genId(),
+        name: opts.name,
+        description: opts.description,
+        command: opts.command,
+        tags: opts.tags ?? [],
+        collection: opts.collection,
+        project: opts.project,
+        variables,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    };
+    store.recipes.push(recipe);
+    saveStore(filePath, store);
+    return recipe;
+}
+/** Delete a recipe by name — tries project first, then global */
+export function deleteRecipe(name, projectPath) {
+    // Try project-scoped first
+    if (projectPath) {
+        const pFile = projectFile(projectPath);
+        const pStore = loadStore(pFile);
+        const before = pStore.recipes.length;
+        pStore.recipes = pStore.recipes.filter(r => r.name !== name);
+        if (pStore.recipes.length < before) {
+            saveStore(pFile, pStore);
+            return true;
+        }
+    }
+    // Fall back to global
+    const store = loadStore(GLOBAL_FILE);
+    const before = store.recipes.length;
+    store.recipes = store.recipes.filter(r => r.name !== name);
+    if (store.recipes.length < before) {
+        saveStore(GLOBAL_FILE, store);
+        return true;
+    }
+    return false;
+}
+// ── Collections ──────────────────────────────────────────────────────────────
+export function listCollections(projectPath) {
+    const global = loadStore(GLOBAL_FILE).collections;
+    if (!projectPath)
+        return global;
+    const project = loadStore(projectFile(projectPath)).collections;
+    return [...project, ...global];
+}
+export function createCollection(opts) {
+    const filePath = opts.project ? projectFile(opts.project) : GLOBAL_FILE;
+    const store = loadStore(filePath);
+    // Prevent duplicates — return existing if same name
+    const existing = store.collections.find(c => c.name === opts.name);
+    if (existing)
+        return existing;
+    const collection = {
+        id: genId(),
+        name: opts.name,
+        description: opts.description,
+        project: opts.project,
+        createdAt: Date.now(),
+    };
+    store.collections.push(collection);
+    saveStore(filePath, store);
+    return collection;
+}
+/** Initialize project-scoped recipes file */
+export function initProject(projectPath) {
+    const file = projectFile(projectPath);
+    if (!existsSync(file)) {
+        saveStore(file, { recipes: [], collections: [] });
+    }
+}

package/dist/search/content-search.js

@@ -0,0 +1,68 @@
+// Smart content search — structured grep/ripgrep with grouping and dedup
+import { spawn } from "child_process";
+import { DEFAULT_EXCLUDE_DIRS, relevanceScore } from "./filters.js";
+function exec(command, cwd) {
+    return new Promise((resolve) => {
+        const proc = spawn("/bin/zsh", ["-c", command], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        proc.stdout?.on("data", (d) => { out += d.toString(); });
+        proc.on("close", () => resolve(out));
+    });
+}
+export async function searchContent(pattern, cwd, options = {}) {
+    const { fileType, maxResults = 30, contextLines = 0 } = options;
+    // Prefer ripgrep, fall back to grep
+    const excludeArgs = DEFAULT_EXCLUDE_DIRS.map(d => `--glob '!${d}'`).join(" ");
+    const typeArg = fileType ? `--type ${fileType}` : "";
+    const contextArg = contextLines > 0 ? `-C ${contextLines}` : "";
+    // Try rg first, fall back to grep
+    const rgCmd = `rg --line-number --no-heading ${contextArg} ${typeArg} ${excludeArgs} '${pattern.replace(/'/g, "'\\''")}' 2>/dev/null | head -500`;
+    const grepCmd = `grep -rn ${contextArg} '${pattern.replace(/'/g, "'\\''")}' . --include='*.ts' --include='*.js' --include='*.py' --include='*.go' --include='*.rs' --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist 2>/dev/null | head -500`;
+    let raw = await exec(rgCmd, cwd);
+    if (!raw.trim()) {
+        raw = await exec(grepCmd, cwd);
+    }
+    const lines = raw.split("\n").filter(l => l.trim());
+    const fileMap = new Map();
+    let filteredCount = 0;
+    for (const line of lines) {
+        // Format: path:line:content
+        const match = line.match(/^([^:]+):(\d+):(.*)$/);
+        if (!match)
+            continue;
+        const [, path, lineNum, content] = match;
+        if (DEFAULT_EXCLUDE_DIRS.some(d => path.includes(`/${d}/`))) {
+            filteredCount++;
+            continue;
+        }
+        if (!fileMap.has(path))
+            fileMap.set(path, []);
+        fileMap.get(path).push({
+            line: parseInt(lineNum),
+            content: content.trim(),
+        });
+    }
+    // Sort files by relevance
+    const files = [...fileMap.entries()]
+        .map(([path, matches]) => ({
+        path,
+        matches: matches.slice(0, 5), // max 5 matches per file
+        relevance: relevanceScore(path),
+    }))
+        .sort((a, b) => b.relevance - a.relevance)
+        .slice(0, maxResults);
+    const totalMatches = [...fileMap.values()].reduce((sum, m) => sum + m.length, 0);
+    const filtered = filteredCount > 0 ? [{ count: filteredCount, reason: "excluded directories" }] : [];
+    const rawTokens = Math.ceil(raw.length / 4);
+    const result = { query: pattern, totalMatches, files, filtered };
+    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.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/dist/search/file-search.js

@@ -0,0 +1,61 @@
+// Smart file search — structured, filtered, token-efficient results
+import { spawn } from "child_process";
+import { DEFAULT_EXCLUDE_DIRS, isSourceFile, isExcludedDir, relevanceScore } from "./filters.js";
+function exec(command, cwd) {
+    return new Promise((resolve) => {
+        const proc = spawn("/bin/zsh", ["-c", command], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        proc.stdout?.on("data", (d) => { out += d.toString(); });
+        proc.stderr?.on("data", (d) => { out += d.toString(); });
+        proc.on("close", () => resolve(out));
+    });
+}
+export async function searchFiles(pattern, cwd, options = {}) {
+    const { includeNodeModules = false, maxResults = 50 } = options;
+    // Build find command
+    const excludes = includeNodeModules
+        ? DEFAULT_EXCLUDE_DIRS.filter(d => d !== "node_modules")
+        : DEFAULT_EXCLUDE_DIRS;
+    const excludeArgs = excludes.map(d => `-not -path '*/${d}/*'`).join(" ");
+    const command = `find . -name '${pattern}' -type f ${excludeArgs} 2>/dev/null | head -${maxResults * 3}`;
+    const raw = await exec(command, cwd);
+    const allPaths = raw.split("\n").filter(l => l.trim());
+    // Categorize
+    const source = [];
+    const config = [];
+    const other = [];
+    const filteredCounts = {};
+    for (const path of allPaths) {
+        if (isExcludedDir(path)) {
+            const dir = DEFAULT_EXCLUDE_DIRS.find(d => path.includes(`/${d}/`)) ?? "other";
+            filteredCounts[dir] = (filteredCounts[dir] ?? 0) + 1;
+            continue;
+        }
+        if (isSourceFile(path)) {
+            source.push(path);
+        }
+        else if (path.match(/\.(json|yaml|yml|toml|ini|env)/)) {
+            config.push(path);
+        }
+        else {
+            other.push(path);
+        }
+    }
+    // Sort by relevance
+    source.sort((a, b) => relevanceScore(b) - relevanceScore(a));
+    // Limit results
+    const filtered = Object.entries(filteredCounts).map(([reason, count]) => ({ reason, count }));
+    // Estimate token savings
+    const rawTokens = Math.ceil(raw.length / 4);
+    const result = {
+        query: pattern,
+        total: allPaths.length,
+        source: source.slice(0, maxResults),
+        config: config.slice(0, 10),
+        other: other.slice(0, 10),
+        filtered,
+    };
+    const resultTokens = Math.ceil(JSON.stringify(result).length / 4);
+    result.tokensSaved = Math.max(0, rawTokens - resultTokens);
+    return result;
+}