@theowlops/boombot 0.0.0-stage → 1.1.1

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

@@ -0,0 +1,178 @@
+export const FILE_READ_TOOL_NAME = 'file.read';
+export const FILE_WRITE_TOOL_NAME = 'file.write';
+export const FILE_EDIT_TOOL_NAME = 'file.edit';
+export const FILE_GLOB_TOOL_NAME = 'file.glob';
+export const FILE_GREP_TOOL_NAME = 'file.grep';
+/** All tool names in this group — used for policy allow grants. */
+export const FILE_TOOL_NAMES = [
+    FILE_READ_TOOL_NAME,
+    FILE_WRITE_TOOL_NAME,
+    FILE_EDIT_TOOL_NAME,
+    FILE_GLOB_TOOL_NAME,
+    FILE_GREP_TOOL_NAME,
+];
+/** Byte cap per read for `file.read`. */
+export const MAX_READ_BYTES = 256 * 1024;
+/** Result line cap for `file.glob`. */
+export const MAX_GLOB_RESULTS = 200;
+/** Match line cap for `file.grep`. */
+export const MAX_GREP_MATCHES = 200;
+/** Files larger than this are skipped by `file.grep` (not read). */
+export const MAX_GREP_FILE_BYTES = 1024 * 1024;
+/** Character cap for `file.grep`'s `pattern`. */
+export const MAX_PATTERN_LENGTH = 512;
+/** Cap on entries visited during glob/grep, guards against unbounded scans. */
+export const MAX_WALK_ENTRIES = 20_000;
+/**
+ * Directory (and file) names skipped during traversal.
+ *
+ * `file.*`'s root is the project directory, so without this list a single
+ * `file.glob` would swallow `node_modules` whole, hit `MAX_WALK_ENTRIES` before
+ * reaching `src/`, and return results that are both slow and WRONG — just the
+ * head of the tree presented as if it were the whole tree. This is the search
+ * tool's default, not a security limit: to inspect `node_modules`, change
+ * `files.root` or read directly with `file.read`.
+ */
+export const WALK_IGNORES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.turbo',
+    'target',
+    '__pycache__',
+    '.venv',
+    'vendor',
+    'win-unpacked',
+]);
+/** Minified files: content is unreadable by eye, so always skipped. */
+export const MINIFIED_FILE_RE = /\.min\.[^./\\]+$/i;
+/** Leading bytes used for binary detection, instead of loading the whole file. */
+export const BINARY_SNIFF_BYTES = 8 * 1024;
+/** Files `file.grep` reads in parallel per batch. */
+export const GREP_READ_CONCURRENCY = 8;
+export const fileReadDefinition = {
+    name: FILE_READ_TOOL_NAME,
+    description: 'Reads a text file in the project directory and returns its content. ' +
+        'Paths escaping the root are refused, including via symlink. ' +
+        `Content is truncated at ${MAX_READ_BYTES} bytes. Use nextOffset as the offset to continue reading.`,
+    parameters: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'File path, relative to the project directory.',
+            },
+            maxBytes: {
+                type: 'number',
+                description: `Byte cap for this read. Defaults to ${MAX_READ_BYTES}.`,
+            },
+            offset: {
+                type: 'integer',
+                description: 'Starting byte position (default 0). Use nextOffset from the previous read.',
+            },
+        },
+        required: ['path'],
+        additionalProperties: false,
+    },
+};
+export const fileWriteDefinition = {
+    name: FILE_WRITE_TOOL_NAME,
+    description: 'Overwrites a file in the project directory (creates it if missing, auto-creates ' +
+        'parent directories). Paths escaping the root are refused. Replaces all old content.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'File path, relative to the project directory.',
+            },
+            content: {
+                type: 'string',
+                description: 'New content. An empty string makes an empty file.',
+            },
+        },
+        required: ['path', 'content'],
+        additionalProperties: false,
+    },
+};
+export const fileEditDefinition = {
+    name: FILE_EDIT_TOOL_NAME,
+    description: 'Replaces a text span in a file. `oldText` must appear EXACTLY ONCE — ' +
+        'zero or multiple matches are refused to avoid editing the wrong spot.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'File path, relative to the project directory.',
+            },
+            oldText: {
+                type: 'string',
+                description: 'Text span to replace. Must match exactly once.',
+            },
+            newText: {
+                type: 'string',
+                description: 'Replacement text.',
+            },
+        },
+        required: ['path', 'oldText', 'newText'],
+        additionalProperties: false,
+    },
+};
+export const fileGlobDefinition = {
+    name: FILE_GLOB_TOOL_NAME,
+    description: 'Lists files matching a glob pattern in THIS machine\'s PROJECT DIRECTORY — this is ' +
+        'how to find local files; do NOT use research.search for questions about files in the project. ' +
+        'Example "**/*.ts" or "src/*.json". ' +
+        'Supports `*` (one level), `**` (any depth), `?` (one character). ' +
+        `Returns at most ${MAX_GLOB_RESULTS} results. Skips node_modules, .git, dist, build, ` +
+        'coverage and minified files. Symlinks are not followed.',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: {
+                type: 'string',
+                description: 'Glob pattern, e.g. "**/*.test.ts". Use "/" as the level separator.',
+            },
+            path: {
+                type: 'string',
+                description: 'Base directory to search, relative to the project directory. Defaults to the whole project.',
+            },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+    },
+};
+export const fileGrepDefinition = {
+    name: FILE_GREP_TOOL_NAME,
+    description: 'Finds lines matching a regular expression (JavaScript regex) in text ' +
+        'files under THIS machine\'s PROJECT DIRECTORY — this is how to search content in ' +
+        'local files; do NOT use research.search for questions about files in the project. ' +
+        'Returns "path:line: content". ' +
+        `Returns at most ${MAX_GREP_MATCHES} matching lines. Skips node_modules, .git, dist, ` +
+        `build, coverage, minified files and files larger than ${MAX_GREP_FILE_BYTES} bytes.`,
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: {
+                type: 'string',
+                description: 'JavaScript regular expression, e.g. "resolveWithin\\\\(".',
+            },
+            path: {
+                type: 'string',
+                description: 'Base directory to search, relative to the project directory. Defaults to the whole project.',
+            },
+            glob: {
+                type: 'string',
+                description: 'Additional glob filter, e.g. "**/*.ts".',
+            },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+    },
+};
+// ---------------------------------------------------------------------------
+// Argument parsing — throws plain `Error`, the caller wraps it into a ToolResult.

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

@@ -0,0 +1,178 @@
+/**
+ * File tool operations — `file.read`, `file.write`, `file.edit` handlers.
+ *
+ * Single responsibility: the three single-file operations. Glob/grep live in
+ * `file-tool.ts`; shared parsing/traversal in `file-tool-scan.ts`.
+ */
+import { mkdir, open, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { resolveWithin } from '@boombot/sandbox';
+import { MAX_READ_BYTES } from './file-tool-defs.js';
+import { messageOf, optPosIntArg, strArg, textArg } from './file-tool-scan.js';
+export function makeFail(call) {
+    return (message) => ({
+        callId: call.id,
+        name: call.name,
+        output: message,
+        error: true,
+    });
+}
+export function makeOk(call) {
+    return (output) => ({
+        callId: call.id,
+        name: call.name,
+        output,
+        error: false,
+    });
+}
+export async function executeRead(call, options) {
+    const fail = makeFail(call);
+    const ok = makeOk(call);
+    let target;
+    let maxBytes;
+    let offset;
+    try {
+        target = strArg(call.arguments, 'path');
+        maxBytes = Math.min(optPosIntArg(call.arguments, 'maxBytes') ?? MAX_READ_BYTES, options.maxReadBytes ?? MAX_READ_BYTES, MAX_READ_BYTES);
+        const rawOffset = call.arguments['offset'] ?? 0;
+        if (typeof rawOffset !== 'number' || !Number.isSafeInteger(rawOffset) || rawOffset < 0) {
+            throw new Error("'offset' must be a non-negative safe integer");
+        }
+        offset = rawOffset;
+    }
+    catch (err) {
+        return fail(`file.read: invalid arguments: ${messageOf(err)}`);
+    }
+    let abs;
+    try {
+        abs = await resolveWithin(options.workspaceRoot, target);
+    }
+    catch (err) {
+        return fail(`file.read refused: ${messageOf(err)}`);
+    }
+    try {
+        const info = await stat(abs);
+        if (!info.isFile()) {
+            return fail(`file.read refused: '${target}' is not a regular file`);
+        }
+        if (offset > info.size)
+            return fail(`file.read: offset is beyond the end (${info.size} bytes)`);
+        const want = Math.min(info.size - offset, maxBytes);
+        const handle = await open(abs, 'r');
+        let buf;
+        try {
+            buf = Buffer.alloc(want);
+            let total = 0;
+            while (total < want) {
+                const { bytesRead } = await handle.read(buf, total, want - total, offset + total);
+                if (bytesRead === 0)
+                    break;
+                total += bytesRead;
+            }
+            buf = buf.subarray(0, total);
+        }
+        finally {
+            await handle.close();
+        }
+        if (buf.includes(0)) {
+            return ok(`file.read: '${target}' looks binary (${info.size} bytes) — not shown.`);
+        }
+        // Keep incomplete UTF-8 characters for the next page, including Vietnamese text.
+        const body = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buf, {
+            stream: offset + buf.length < info.size,
+        });
+        if (buf.length > 0 && body.length === 0) {
+            return fail('file.read: maxBytes is too small for a UTF-8 character; use at least 4');
+        }
+        const nextOffset = offset + Buffer.byteLength(body, 'utf8');
+        const truncated = nextOffset < info.size;
+        const header = truncated
+            ? `file.read: '${target}' — bytes ${offset}–${nextOffset} of ${info.size} (truncated; nextOffset=${nextOffset})`
+            : `file.read: '${target}' (${info.size} bytes)`;
+        return ok(`${header}\n---\n${body}`);
+    }
+    catch (err) {
+        return fail(`file.read failed: ${messageOf(err)}`);
+    }
+}
+export async function executeWrite(call, options) {
+    const fail = makeFail(call);
+    const ok = makeOk(call);
+    let target;
+    let content;
+    try {
+        target = strArg(call.arguments, 'path');
+        content = textArg(call.arguments, 'content');
+    }
+    catch (err) {
+        return fail(`file.write: invalid arguments: ${messageOf(err)}`);
+    }
+    let abs;
+    try {
+        abs = await resolveWithin(options.workspaceRoot, target);
+    }
+    catch (err) {
+        return fail(`file.write refused: ${messageOf(err)}`);
+    }
+    try {
+        // Overwriting a directory would throw a cryptic EISDIR; say so upfront.
+        const existing = await stat(abs).catch(() => null);
+        if (existing?.isDirectory() === true) {
+            return fail(`file.write refused: '${target}' is a directory`);
+        }
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, content, 'utf8');
+        const bytes = Buffer.byteLength(content, 'utf8');
+        return ok(`file.write: '${target}' written (${bytes} bytes).`);
+    }
+    catch (err) {
+        return fail(`file.write failed: ${messageOf(err)}`);
+    }
+}
+export async function executeEdit(call, options) {
+    const fail = makeFail(call);
+    const ok = makeOk(call);
+    let target;
+    let oldText;
+    let newText;
+    try {
+        target = strArg(call.arguments, 'path');
+        oldText = strArg(call.arguments, 'oldText');
+        newText = textArg(call.arguments, 'newText');
+    }
+    catch (err) {
+        return fail(`file.edit: invalid arguments: ${messageOf(err)}`);
+    }
+    let abs;
+    try {
+        abs = await resolveWithin(options.workspaceRoot, target);
+    }
+    catch (err) {
+        return fail(`file.edit refused: ${messageOf(err)}`);
+    }
+    try {
+        const info = await stat(abs);
+        if (!info.isFile()) {
+            return fail(`file.edit refused: '${target}' is not a regular file`);
+        }
+        const before = await readFile(abs, 'utf8');
+        // The match must be UNIQUE: 0 hits means wrong location, many means ambiguous.
+        // Both are refused rather than guessed — editing the wrong spot in a user's
+        // file is worse than an error.
+        const first = before.indexOf(oldText);
+        if (first === -1) {
+            return fail(`file.edit refused: oldText not found in '${target}'`);
+        }
+        if (before.indexOf(oldText, first + oldText.length) !== -1) {
+            return fail(`file.edit refused: oldText appears more than once in '${target}' — ` +
+                `include more surrounding context to make it unique.`);
+        }
+        const after = before.slice(0, first) + newText + before.slice(first + oldText.length);
+        await writeFile(abs, after, 'utf8');
+        const lineNo = before.slice(0, first).split('\n').length;
+        return ok(`file.edit: '${target}' updated at line ${lineNo}.`);
+    }
+    catch (err) {
+        return fail(`file.edit failed: ${messageOf(err)}`);
+    }
+}

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

@@ -0,0 +1,182 @@
+/**
+ * File tool scanning utilities — argument parsing, glob matching, and filesystem traversal.
+ *
+ * Single responsibility: pure helpers for finding files. No tool definitions
+ * (`file-tool-defs.ts`) and no tool execution (`file-tool.ts`) here.
+ * `walkFiles` is the shared traversal used by `file.glob` and `file.grep`.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { resolveWithin } from '@boombot/sandbox';
+import { MAX_WALK_ENTRIES, MINIFIED_FILE_RE, WALK_IGNORES, } from './file-tool-defs.js';
+// ---------------------------------------------------------------------------
+export function strArg(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`'${key}' must be a non-empty string`);
+    }
+    return v;
+}
+/** Like `strArg` but allows empty strings (empty `content` is valid). */
+export function textArg(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string') {
+        throw new Error(`'${key}' must be a string`);
+    }
+    return v;
+}
+export function optStrArg(args, key) {
+    const v = args[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`'${key}' must be a non-empty string when provided`);
+    }
+    return v;
+}
+export function optPosIntArg(args, key) {
+    const v = args[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
+        throw new Error(`'${key}' must be a positive integer when provided`);
+    }
+    return v;
+}
+export function messageOf(err) {
+    return err instanceof Error ? err.message : 'unknown error';
+}
+// ---------------------------------------------------------------------------
+// Glob
+// ---------------------------------------------------------------------------
+/**
+ * Translates a glob pattern to a doubly-anchored RegExp. `**` crosses levels,
+ * `*` stays within one level, `?` matches one character. Everything else is escaped.
+ *
+ * Note: a double star immediately before a separator becomes
+ * `(?:.*[/\\])?` — e.g. the pattern `**` + `/*.ts` matches both root-level `a.ts`
+ * and `src/a.ts`. That's the behavior users expect, not a bug.
+ */
+export function globToRegExp(pattern) {
+    let out = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            if (pattern[i + 1] === '*') {
+                i++;
+                const after = pattern[i + 1];
+                if (after === '/' || after === '\\') {
+                    i++;
+                    out += '(?:.*[/\\\\])?';
+                }
+                else {
+                    out += '.*';
+                }
+            }
+            else {
+                out += '[^/\\\\]*';
+            }
+        }
+        else if (ch === '?') {
+            out += '[^/\\\\]';
+        }
+        else {
+            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+/**
+ * The STATIC directory prefix of a glob pattern: the pattern's head up to the
+ * first wildcard, cut back to the last separator within it. This lets `walkFiles`
+ * skip subtrees that can't match — `src/**` only walks `src`.
+ *
+ * Returns `'.'` when nothing can be pruned (pattern starts with `*`, or is just
+ * a filename at the root). Being conservative is deliberate: a wrong prune
+ * would drop correct results.
+ */
+export function globStaticPrefix(pattern) {
+    // A pattern starting with a separator is never a valid prefix relative to root,
+    // and resolving it is meaningless (it might even escape root), so reject it outright.
+    if (pattern.startsWith('/') || pattern.startsWith('\\'))
+        return '.';
+    const wildcardAt = pattern.search(/[*?]/);
+    const literal = wildcardAt === -1 ? pattern : pattern.slice(0, wildcardAt);
+    const cut = Math.max(literal.lastIndexOf('/'), literal.lastIndexOf('\\'));
+    if (cut <= 0)
+        return '.';
+    return literal.slice(0, cut);
+}
+/** Normalizes relative paths to "/" so glob patterns use one separator style. */
+function toPosix(p) {
+    return sep === '/' ? p : p.split(sep).join('/');
+}
+/**
+ * Walks files under `base` (already inside root). Return `false` from `visit` to stop.
+ *
+ * Symlinks are skipped ENTIRELY, even ones pointing inside the root: following
+ * them would require per-step containment checks and opens infinite loops. This
+ * is a deliberate limitation, documented in the tool description.
+ *
+ * `ignore` prunes whole subtrees by entry name (see `WALK_IGNORES`): an ignored
+ * directory is never pushed onto the stack, so no extra `readdir` is spent. Minified
+ * files are also skipped because they have no readable content.
+ */
+export async function walkFiles(root, base, visit, ignore = WALK_IGNORES) {
+    const stack = [base];
+    let seen = 0;
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // unreadable directory: skip it, don't fail the whole walk
+        }
+        for (const entry of entries) {
+            if (++seen > MAX_WALK_ENTRIES)
+                return;
+            if (ignore.has(entry.name))
+                continue;
+            const abs = join(dir, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (MINIFIED_FILE_RE.test(entry.name))
+                continue;
+            const keepGoing = await visit({ abs, rel: toPosix(relative(root, abs)) });
+            if (!keepGoing)
+                return;
+        }
+    }
+}
+/**
+ * Start directory for a glob pattern: `relBase` joined with the pattern's static
+ * prefix (`globStaticPrefix`). Falls back to `absBase` — the resolved ABSOLUTE path —
+ * when nothing can be pruned, when the prefix isn't a directory, or when it points
+ * outside root. Pruning is only an optimization: it must never corrupt results, and
+ * must never widen the walk scope.
+ */
+export async function prunedBase(root, relBase, absBase, pattern) {
+    const prefix = globStaticPrefix(pattern);
+    if (prefix === '.')
+        return absBase;
+    const joined = relBase === '.' ? prefix : join(relBase, prefix);
+    try {
+        const candidate = await resolveWithin(root, joined);
+        const info = await stat(candidate);
+        return info.isDirectory() ? candidate : absBase;
+    }
+    catch {
+        return absBase;
+    }
+}
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------