@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/gateway/turns/file-tool.js

@@ -0,0 +1,302 @@
+/**
+ * File tools — `file.glob` and `file.grep` handlers plus tool registration.
+ *
+ * Single responsibility: the two search operations and `registerFileTools`.
+ * Tool schemas live in `file-tool-defs.ts`, traversal in `file-tool-scan.ts`,
+ * single-file ops (`read`/`write`/`edit`) in `file-tool-ops.ts`.
+ *
+ * Security boundary reminder: every fs operation goes through `resolveWithin`
+ * (`@boombot/sandbox`) — the harness guard does not inspect `file.*` params.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { open, readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { resolveWithin } from '@boombot/sandbox';
+import { BINARY_SNIFF_BYTES, MAX_GLOB_RESULTS, MAX_GREP_FILE_BYTES, MAX_GREP_MATCHES, MAX_PATTERN_LENGTH, GREP_READ_CONCURRENCY, fileEditDefinition, fileGlobDefinition, fileGrepDefinition, fileReadDefinition, fileWriteDefinition, } from './file-tool-defs.js';
+import { executeEdit, executeRead, executeWrite, makeFail, makeOk } from './file-tool-ops.js';
+// Re-exported for `src/turns/index.ts` and tests (import from './file-tool.js').
+export { FILE_EDIT_TOOL_NAME, FILE_GLOB_TOOL_NAME, FILE_GREP_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_TOOL_NAMES, FILE_WRITE_TOOL_NAME, MAX_READ_BYTES } from './file-tool-defs.js';
+export { globStaticPrefix, globToRegExp } from './file-tool-scan.js';
+import { globToRegExp, messageOf, optStrArg, prunedBase, strArg, walkFiles, } from './file-tool-scan.js';
+async function executeGlob(call, options) {
+    const fail = makeFail(call);
+    const ok = makeOk(call);
+    let pattern;
+    let base;
+    try {
+        pattern = strArg(call.arguments, 'pattern');
+        base = optStrArg(call.arguments, 'path') ?? '.';
+    }
+    catch (err) {
+        return fail(`file.glob: invalid arguments: ${messageOf(err)}`);
+    }
+    let absBase;
+    try {
+        absBase = await resolveWithin(options.workspaceRoot, base);
+    }
+    catch (err) {
+        return fail(`file.glob refused: ${messageOf(err)}`);
+    }
+    let matcher;
+    try {
+        matcher = globToRegExp(pattern);
+    }
+    catch (err) {
+        return fail(`file.glob: invalid pattern: ${messageOf(err)}`);
+    }
+    try {
+        const info = await stat(absBase);
+        if (!info.isDirectory()) {
+            return fail(`file.glob refused: '${base}' is not a directory`);
+        }
+        // 1. High-speed native Rust glob accelerator (0% Node GC overhead)
+        const nativeHost = [
+            resolve(options.workspaceRoot, 'native/host/target/release/boombot-native-host.exe'),
+            resolve(options.workspaceRoot, 'native/host/target/release/boombot-native-host'),
+            resolve(options.workspaceRoot, `apps/cli/dist/native/${process.platform}-${process.arch}/boombot-native-host.exe`),
+            resolve(options.workspaceRoot, `apps/cli/dist/native/${process.platform}-${process.arch}/boombot-native-host`),
+        ].find((p) => existsSync(p));
+        if (nativeHost) {
+            try {
+                const stdout = execFileSync(nativeHost, [], {
+                    input: `${JSON.stringify({
+                        action: 'glob',
+                        pattern: pattern === '*' || pattern === '**' ? undefined : pattern,
+                        path: absBase,
+                        maxResults: MAX_GLOB_RESULTS,
+                    })}\n`,
+                    encoding: 'utf8',
+                    maxBuffer: 4 * 1024 * 1024,
+                    timeout: 4000,
+                });
+                const parsed = JSON.parse(stdout.trim());
+                if (parsed.ok && Array.isArray(parsed.paths)) {
+                    if (parsed.paths.length === 0) {
+                        return ok(`file.glob: no files match '${pattern}'.`);
+                    }
+                    const header = `file.glob: ${parsed.paths.length} file(s) match '${pattern}'`;
+                    return ok(`${header}\n${parsed.paths.join('\n')}`);
+                }
+            }
+            catch {
+                // Fall back gracefully to JS walkFiles
+            }
+        }
+        // 2. Fallback JS walkFiles
+        const walkRoot = await prunedBase(options.workspaceRoot, base, absBase, pattern);
+        const hits = [];
+        let capped = false;
+        await walkFiles(options.workspaceRoot, walkRoot, async ({ rel }) => {
+            if (!matcher.test(rel))
+                return true;
+            if (hits.length >= MAX_GLOB_RESULTS) {
+                capped = true;
+                return false;
+            }
+            hits.push(rel);
+            return true;
+        });
+        hits.sort();
+        if (hits.length === 0) {
+            return ok(`file.glob: no files match '${pattern}'.`);
+        }
+        const header = `file.glob: ${hits.length} file(s) match '${pattern}'` +
+            (capped ? ` (capped at ${MAX_GLOB_RESULTS})` : '');
+        return ok(`${header}\n${hits.join('\n')}`);
+    }
+    catch (err) {
+        return fail(`file.glob failed: ${messageOf(err)}`);
+    }
+}
+async function executeGrep(call, options) {
+    const fail = makeFail(call);
+    const ok = makeOk(call);
+    let pattern;
+    let base;
+    let globFilter;
+    try {
+        pattern = strArg(call.arguments, 'pattern');
+        base = optStrArg(call.arguments, 'path') ?? '.';
+        globFilter = optStrArg(call.arguments, 'glob');
+    }
+    catch (err) {
+        return fail(`file.grep: invalid arguments: ${messageOf(err)}`);
+    }
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        return fail(`file.grep refused: pattern longer than ${MAX_PATTERN_LENGTH} characters`);
+    }
+    let absBase;
+    try {
+        absBase = await resolveWithin(options.workspaceRoot, base);
+    }
+    catch (err) {
+        return fail(`file.grep refused: ${messageOf(err)}`);
+    }
+    let matcher;
+    let fileMatcher;
+    try {
+        matcher = new RegExp(pattern);
+        fileMatcher = globFilter === undefined ? undefined : globToRegExp(globFilter);
+    }
+    catch (err) {
+        return fail(`file.grep: invalid pattern: ${messageOf(err)}`);
+    }
+    try {
+        const info = await stat(absBase);
+        if (!info.isDirectory()) {
+            return fail(`file.grep refused: '${base}' is not a directory`);
+        }
+        // 1. High-speed native Rust grep accelerator (WalkDir + Regex in C/Rust)
+        const nativeHost = [
+            resolve(options.workspaceRoot, 'native/host/target/release/boombot-native-host.exe'),
+            resolve(options.workspaceRoot, 'native/host/target/release/boombot-native-host'),
+            resolve(options.workspaceRoot, `apps/cli/dist/native/${process.platform}-${process.arch}/boombot-native-host.exe`),
+            resolve(options.workspaceRoot, `apps/cli/dist/native/${process.platform}-${process.arch}/boombot-native-host`),
+        ].find((p) => existsSync(p));
+        if (nativeHost && globFilter === undefined) {
+            try {
+                const stdout = execFileSync(nativeHost, [], {
+                    input: `${JSON.stringify({
+                        action: 'grep',
+                        pattern,
+                        path: absBase,
+                        maxResults: MAX_GREP_MATCHES,
+                    })}\n`,
+                    encoding: 'utf8',
+                    maxBuffer: 4 * 1024 * 1024,
+                    timeout: 5000,
+                });
+                const parsed = JSON.parse(stdout.trim());
+                if (parsed.ok && Array.isArray(parsed.matches)) {
+                    if (parsed.matches.length === 0) {
+                        return ok(`file.grep: no matches for /${pattern}/.`);
+                    }
+                    const formatted = parsed.matches.map((m) => `${m.path}:${m.line}: ${m.content}`);
+                    return ok(`file.grep: ${parsed.matches.length} match(es) for /${pattern}/\n${formatted.join('\n')}`);
+                }
+            }
+            catch {
+                // Fall back gracefully to JS walkFiles + scanFile
+            }
+        }
+        // 2. Fallback JS walkFiles
+        const walkRoot = await prunedBase(options.workspaceRoot, base, absBase, pattern);
+        const files = [];
+        await walkFiles(options.workspaceRoot, walkRoot, async (entry) => {
+            if (fileMatcher !== undefined && !fileMatcher.test(entry.rel))
+                return true;
+            files.push(entry);
+            return true;
+        });
+        const hits = [];
+        let capped = false;
+        let skippedLarge = 0;
+        let skippedBinary = 0;
+        let unreadable = 0;
+        for (let i = 0; i < files.length && !capped; i += GREP_READ_CONCURRENCY) {
+            const chunk = files.slice(i, i + GREP_READ_CONCURRENCY);
+            const scanned = await Promise.all(chunk.map(async (entry) => ({ entry, scan: await scanFile(entry, matcher) })));
+            // Assembled in chunk order, so the same tree always yields the same
+            // result list even though the reads finish in any order.
+            for (const { scan } of scanned) {
+                if (scan.kind === 'large') {
+                    skippedLarge += 1;
+                    continue;
+                }
+                if (scan.kind === 'binary') {
+                    skippedBinary += 1;
+                    continue;
+                }
+                if (scan.kind === 'unreadable') {
+                    unreadable += 1;
+                    continue;
+                }
+                for (const line of scan.lines) {
+                    if (hits.length >= MAX_GREP_MATCHES) {
+                        capped = true;
+                        break;
+                    }
+                    hits.push(line);
+                }
+                if (capped)
+                    break;
+            }
+        }
+        const notes = [];
+        if (capped)
+            notes.push(`capped at ${MAX_GREP_MATCHES}`);
+        if (skippedLarge > 0)
+            notes.push(`${skippedLarge} large file(s) skipped`);
+        if (skippedBinary > 0)
+            notes.push(`${skippedBinary} binary file(s) skipped`);
+        if (unreadable > 0)
+            notes.push(`${unreadable} unreadable entry(ies) skipped`);
+        const suffix = notes.length > 0 ? ` (${notes.join(', ')})` : '';
+        if (hits.length === 0) {
+            return ok(`file.grep: no matches for /${pattern}/${suffix}.`);
+        }
+        return ok(`file.grep: ${hits.length} match(es) for /${pattern}/${suffix}\n${hits.join('\n')}`);
+    }
+    catch (err) {
+        return fail(`file.grep failed: ${messageOf(err)}`);
+    }
+}
+/**
+ * Scans one file: detects binary via the first `BINARY_SNIFF_BYTES` bytes instead
+ * of loading the whole file then hunting for NUL bytes, and applies the
+ * `MAX_GREP_FILE_BYTES` cap before reading. Only files passing both gates are
+ * actually read and matched.
+ */
+async function scanFile(entry, matcher) {
+    const handle = await open(entry.abs, 'r').catch(() => null);
+    if (handle === null)
+        return { kind: 'unreadable' };
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            return { kind: 'unreadable' };
+        if (info.size > MAX_GREP_FILE_BYTES)
+            return { kind: 'large' };
+        const head = Buffer.allocUnsafe(BINARY_SNIFF_BYTES);
+        const { bytesRead } = await handle.read(head, 0, BINARY_SNIFF_BYTES, 0);
+        if (head.subarray(0, bytesRead).includes(0))
+            return { kind: 'binary' };
+    }
+    catch {
+        return { kind: 'unreadable' };
+    }
+    finally {
+        await handle.close();
+    }
+    const buf = await readFile(entry.abs).catch(() => null);
+    if (buf === null)
+        return { kind: 'unreadable' };
+    const lines = buf.toString('utf8').split('\n');
+    const matched = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (matcher.test(line))
+            matched.push(`${entry.rel}:${i + 1}: ${line.trim()}`);
+    }
+    return { kind: 'text', lines: matched };
+}
+/**
+ * Registers all 5 file tools on `registry`. Throws when `workspaceRoot` is
+ * missing — without a confinement root there is no security boundary, so this
+ * is a programming error, not a runnable state.
+ *
+ * The abort signal is not forwarded, like `shell.exec`: the executor already
+ * checked the signal before calling the handler, and every operation here is
+ * capped (`maxBytes`, `MAX_WALK_ENTRIES`, `MAX_GREP_FILE_BYTES`).
+ */
+export function registerFileTools(registry, options) {
+    if (options.workspaceRoot === undefined || options.workspaceRoot === null) {
+        throw new Error('registerFileTools: workspaceRoot is required');
+    }
+    registry.registerTool(fileReadDefinition, (call) => executeRead(call, options));
+    registry.registerTool(fileWriteDefinition, (call) => executeWrite(call, options));
+    registry.registerTool(fileEditDefinition, (call) => executeEdit(call, options));
+    registry.registerTool(fileGlobDefinition, (call) => executeGlob(call, options));
+    registry.registerTool(fileGrepDefinition, (call) => executeGrep(call, options));
+}