praana 0.5.0

package/dist/tools/search-code.js

@@ -0,0 +1,390 @@
+import { defineTool } from "./tool-def.js";
+import { z } from "zod";
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { resolve as resolvePath, isAbsolute, normalize } from "node:path";
+import { homedir } from "node:os";
+const searchCodeSchema = z.object({
+    pattern: z
+        .string()
+        .min(1)
+        .describe("Regex pattern to search for (ripgrep regex syntax)"),
+    path: z
+        .string()
+        .optional()
+        .describe("Directory or file to search (default: working directory)"),
+    glob: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe("Include glob filter(s), e.g. '*.ts' or ['*.ts', '*.tsx']"),
+    glob_exclude: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe("Exclude glob filter(s)"),
+    case_insensitive: z
+        .boolean()
+        .optional()
+        .describe("Case-insensitive search (-i)"),
+    context: z
+        .number()
+        .int()
+        .min(0)
+        .max(50)
+        .optional()
+        .describe("Lines of context before and after each match (-C). Default 0."),
+    max_results: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Stop after this many matches are found"),
+    file_type: z
+        .string()
+        .optional()
+        .describe("ripgrep file type filter (e.g. 'ts', 'rust', 'py')"),
+    include_hidden: z
+        .boolean()
+        .optional()
+        .describe("Search hidden files and directories (--hidden)"),
+    no_ignore: z
+        .boolean()
+        .optional()
+        .describe("Don't respect .gitignore/.ignore (--no-ignore)"),
+    multiline: z
+        .boolean()
+        .optional()
+        .describe("Allow patterns to match across multiple lines (-U)"),
+    timeout: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Timeout in milliseconds (default 30000)"),
+});
+/**
+ * Build the ripgrep argv for the given arguments.
+ *
+ * Pattern is passed as `--` then `pattern` so it can't be misinterpreted as
+ * a flag even if it starts with `-`.
+ */
+export function buildRipgrepArgs(args, searchPath) {
+    const argv = [
+        "--json",
+        "--no-heading",
+        "--no-messages",
+        // --no-config: ignore the user's ~/.ripgreprc / RIPGREP_CONFIG_PATH so the
+        // tool's behavior is deterministic across machines. Custom ripgrep configs
+        // (e.g. --type-add) are NOT honored by this tool.
+        "--no-config",
+    ];
+    if (args.case_insensitive)
+        argv.push("-i");
+    if (args.multiline)
+        argv.push("-U");
+    if (args.include_hidden)
+        argv.push("--hidden");
+    if (args.no_ignore)
+        argv.push("--no-ignore");
+    if (args.file_type)
+        argv.push("--type", args.file_type);
+    const ctx = args.context ?? 0;
+    if (ctx > 0)
+        argv.push("-C", String(ctx));
+    for (const g of args.glob ? (Array.isArray(args.glob) ? args.glob : [args.glob]) : []) {
+        argv.push("--glob", g);
+    }
+    for (const g of args.glob_exclude
+        ? Array.isArray(args.glob_exclude)
+            ? args.glob_exclude
+            : [args.glob_exclude]
+        : []) {
+        argv.push("--glob", "!" + g);
+    }
+    argv.push("--", args.pattern, searchPath);
+    return argv;
+}
+/** Return null if the path is allowed by the sandbox, else a human-readable error. */
+function sandboxBlockReason(path, sandbox) {
+    if (!sandbox?.enabled || sandbox.allowed_paths.length === 0)
+        return null;
+    const resolve = (p) => {
+        const expanded = p.replace(/^~/, homedir());
+        const normalized = normalize(expanded);
+        if (!existsSync(normalized))
+            return normalized;
+        try {
+            return realpathSync(normalized);
+        }
+        catch {
+            return normalized;
+        }
+    };
+    const resolved = resolve(path);
+    const allowed = sandbox.allowed_paths.some((ap) => {
+        const apResolved = resolve(ap);
+        return resolved === apResolved || resolved.startsWith(apResolved + "/");
+    });
+    return allowed
+        ? null
+        : `Blocked by sandbox: path not in allowed list: ${path}`;
+}
+export function createParseState() {
+    return {
+        matches: [],
+        totalMatches: 0,
+        truncated: false,
+        _currentFile: null,
+        _currentFileLineMap: new Map(),
+        _lastMatchInFile: null,
+    };
+}
+function processEvent(state, ev, context, maxResults, onTruncate) {
+    if (ev.type === "begin") {
+        state._currentFile = ev.data.path?.text ?? null;
+        state._currentFileLineMap = new Map();
+        state._lastMatchInFile = null;
+        return;
+    }
+    if (ev.type === "end") {
+        if (state._lastMatchInFile && context > 0 && state._currentFile) {
+            const after = [];
+            for (let i = 1; i <= context; i++) {
+                const t = state._currentFileLineMap.get(state._lastMatchInFile.line + i);
+                if (t !== undefined)
+                    after.push(t);
+            }
+            state._lastMatchInFile.context_after = after;
+        }
+        return;
+    }
+    if (ev.type === "context") {
+        const ln = ev.data.line_number;
+        const text = ev.data.lines?.text ?? "";
+        if (ln !== undefined) {
+            const trimmed = text.endsWith("\n") ? text.slice(0, -1) : text;
+            state._currentFileLineMap.set(ln, trimmed);
+            if (state._lastMatchInFile &&
+                context > 0 &&
+                ln > state._lastMatchInFile.line &&
+                ln <= state._lastMatchInFile.line + context) {
+                state._lastMatchInFile.context_after.push(trimmed);
+            }
+        }
+        return;
+    }
+    if (ev.type === "match") {
+        if (state.truncated)
+            return;
+        if (maxResults !== undefined && state.totalMatches >= maxResults) {
+            state.truncated = true;
+            onTruncate();
+            return;
+        }
+        const file = ev.data.path?.text ?? "";
+        const line = ev.data.line_number ?? 0;
+        const sub = ev.data.submatches?.[0];
+        const column = (sub?.start ?? 0) + 1;
+        const rawText = ev.data.lines?.text ?? "";
+        const text = rawText.endsWith("\n") ? rawText.slice(0, -1) : rawText;
+        const before = [];
+        if (context > 0) {
+            for (let i = context; i >= 1; i--) {
+                const t = state._currentFileLineMap.get(line - i);
+                if (t !== undefined)
+                    before.push(t);
+            }
+        }
+        const m = {
+            file,
+            line,
+            column,
+            text,
+            context_before: before,
+            context_after: [],
+        };
+        state.matches.push(m);
+        state._lastMatchInFile = m;
+        state.totalMatches++;
+        return;
+    }
+}
+/** Feed raw rg --json lines into the parse state. Triggers `onTruncate` on cap. */
+export function feedParseState(state, rawLines, context, maxResults, onTruncate) {
+    for (const raw of rawLines) {
+        if (state.truncated)
+            break;
+        if (!raw)
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(raw);
+        }
+        catch {
+            // Malformed line — rg should not produce these, skip defensively.
+            continue;
+        }
+        processEvent(state, ev, context, maxResults, onTruncate);
+    }
+}
+/** Convenience wrapper: feed a complete log at once. Used by tests. */
+export function parseRipgrepEvents(rawLines, context, maxResults, onTruncate) {
+    const state = createParseState();
+    feedParseState(state, rawLines, context, maxResults, onTruncate);
+    const filesWithMatches = new Set(state.matches.map((m) => m.file)).size;
+    return {
+        matches: state.matches,
+        totalMatches: state.totalMatches,
+        filesWithMatches,
+        truncated: state.truncated,
+    };
+}
+/** Spawn ripgrep, return structured result. */
+export async function runRipgrep(args, rgBin, cwd, sandbox, getAbortSignal) {
+    const started = Date.now();
+    const searchPath = args.path
+        ? isAbsolute(args.path)
+            ? args.path
+            : resolvePath(cwd, args.path)
+        : cwd;
+    const blockReason = sandboxBlockReason(searchPath, sandbox);
+    if (blockReason)
+        return { ok: false, error: blockReason };
+    const argv = buildRipgrepArgs(args, searchPath);
+    const ctx = args.context ?? 0;
+    const maxResults = args.max_results;
+    const timeoutMs = args.timeout ?? 30_000;
+    const signal = getAbortSignal?.();
+    if (signal?.aborted)
+        return { ok: false, error: "Interrupted" };
+    return new Promise((resolve) => {
+        const child = spawn(rgBin, argv, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            // Node 22 resolves a bare "rg" against PATH on POSIX.
+        });
+        let stdoutBuf = "";
+        let resolved = false;
+        const stderrChunks = [];
+        const state = createParseState();
+        const kill = (sig) => {
+            if (!child.killed)
+                child.kill(sig);
+        };
+        /** Stop the child and drop the stdout pipe so no more bytes enter the buffer. */
+        const truncateNow = () => {
+            child.stdout?.destroy();
+            // SIGKILL is the right signal here: we no longer care about rg's
+            // cleanup, only that it stops writing to the pipe.
+            kill("SIGKILL");
+        };
+        const finish = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            kill("SIGTERM");
+            setTimeout(() => kill("SIGKILL"), 500).unref();
+            resolve(result);
+        };
+        const onAbort = () => finish({ ok: false, error: "Interrupted" });
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const timer = setTimeout(() => {
+            finish({ ok: false, error: `search_code timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            if (state.truncated)
+                return; // backpressure: stop buffering post-cap bytes
+            stdoutBuf += chunk.toString("utf-8");
+            let nl;
+            const newLines = [];
+            while ((nl = stdoutBuf.indexOf("\n")) !== -1) {
+                newLines.push(stdoutBuf.slice(0, nl));
+                stdoutBuf = stdoutBuf.slice(nl + 1);
+            }
+            if (newLines.length > 0) {
+                feedParseState(state, newLines, ctx, maxResults, truncateNow);
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrChunks.push(chunk);
+            if (stderrChunks.length > 64)
+                stderrChunks.shift();
+        });
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                finish({
+                    ok: false,
+                    error: "ripgrep ('rg') not found in PATH. Install ripgrep (https://github.com/BurntSushi/ripgrep) or set search_code.rg_path in praana.config.toml to point at the binary.",
+                });
+                return;
+            }
+            finish({ ok: false, error: `Failed to run ripgrep: ${err.message}` });
+        });
+        child.on("close", (code) => {
+            if (resolved) {
+                // finish() already ran (abort / timeout / error). Drop any tail bytes.
+                stdoutBuf = "";
+                return;
+            }
+            if (stdoutBuf.length > 0) {
+                feedParseState(state, [stdoutBuf], ctx, maxResults, truncateNow);
+                stdoutBuf = "";
+            }
+            const stderrTail = Buffer.concat(stderrChunks).toString("utf-8").trim();
+            // rg exit codes: 0 = matches, 1 = no matches, 2 = error.
+            if (code === 2) {
+                finish({
+                    ok: false,
+                    error: stderrTail
+                        ? `ripgrep error: ${stderrTail}`
+                        : "ripgrep exited with code 2 (regex parse error or other failure)",
+                });
+                return;
+            }
+            if (code === 0 || code === 1 || state.matches.length > 0) {
+                const filesWithMatches = new Set(state.matches.map((m) => m.file)).size;
+                finish({
+                    ok: true,
+                    pattern: args.pattern,
+                    path: searchPath,
+                    matches: state.matches,
+                    stats: {
+                        totalMatches: state.totalMatches,
+                        filesWithMatches,
+                        truncated: state.truncated,
+                        dropped: state.truncated ? 1 : 0, // exact count unknown; >= 1
+                    },
+                    duration_ms: Date.now() - started,
+                });
+                return;
+            }
+            finish({
+                ok: false,
+                error: stderrTail
+                    ? `ripgrep failed: ${stderrTail}`
+                    : `ripgrep exited with code ${code}`,
+            });
+        });
+    });
+}
+export function createSearchCodeTool(ctx) {
+    return {
+        search_code: defineTool({
+            description: "Fast structured code search powered by ripgrep. Returns file:line:column matches with optional context lines. Use instead of `shell grep` for codebase exploration.",
+            parameters: searchCodeSchema,
+            execute: async (raw) => {
+                const parsed = searchCodeSchema.safeParse(raw);
+                if (!parsed.success) {
+                    return {
+                        ok: false,
+                        error: `Invalid arguments: ${parsed.error.issues
+                            .map((i) => `${i.path.join(".")}: ${i.message}`)
+                            .join("; ")}`,
+                    };
+                }
+                return runRipgrep(parsed.data, ctx.rgPath ?? "rg", ctx.cwd, ctx.sandbox, ctx.getAbortSignal);
+            },
+        }),
+    };
+}

package/dist/tools/system.d.ts

@@ -0,0 +1,16 @@
+import type { SandboxConfig } from "../types.js";
+export interface SystemToolContext {
+    cwd: string;
+    getAbortSignal?: () => AbortSignal | undefined;
+    sandbox?: SandboxConfig;
+    editConfirm?: boolean;
+}
+export declare function createSystemTools(ctx: SystemToolContext): {
+    shell: import("./tool-def.js").ToolDefinition;
+    read_file: import("./tool-def.js").ToolDefinition;
+    read_and_summarize: import("./tool-def.js").ToolDefinition;
+    write_file: import("./tool-def.js").ToolDefinition;
+    edit_file: import("./tool-def.js").ToolDefinition;
+    batch_write: import("./tool-def.js").ToolDefinition;
+    batch_edit: import("./tool-def.js").ToolDefinition;
+};