@megacode/cli 0.2.0

package/dist/adapters/skills.js

@@ -0,0 +1,163 @@
+import { execFile } from "node:child_process";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { parse } from "yaml";
+import { configDir } from "./storage.js";
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ignored = new Set([".git", "node_modules", ".megacode"]);
+const exec = promisify(execFile);
+function readSkill(directory) {
+    const file = path.join(directory, "SKILL.md");
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.size > 128 * 1024)
+        throw new Error(`Invalid or oversized SKILL.md: ${file}`);
+    const text = readFileSync(file, "utf8").replace(/^\uFEFF/, "");
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        throw new Error(`Missing YAML frontmatter: ${file}`);
+    const metadata = parse(match[1], { maxAliasCount: 0 });
+    if (!metadata || typeof metadata.name !== "string" || !NAME.test(metadata.name) || metadata.name.length > 64)
+        throw new Error(`Skill name must be lowercase letters/digits separated by hyphens (max 64): ${file}`);
+    if (typeof metadata.description !== "string" || !metadata.description.trim() || metadata.description.length > 1024)
+        throw new Error(`Skill needs a description of 1–1024 characters: ${file}`);
+    return { name: metadata.name, description: metadata.description.trim(), file };
+}
+function roots({ cwd = process.cwd(), home }) {
+    const global = home ? path.join(home, ".megacode") : configDir();
+    return [path.resolve(global, "skills"), path.resolve(cwd, ".megacode", "skills")];
+}
+/** Project skills override global skills with the same name. Broken skills don't prevent startup. */
+export function discoverSkills(options = {}) {
+    const skills = new Map();
+    const warnings = [];
+    for (const root of roots(options)) {
+        if (!existsSync(root))
+            continue;
+        try {
+            for (const entry of readdirSync(root, { withFileTypes: true })) {
+                if (!entry.isDirectory() || entry.name.startsWith("."))
+                    continue;
+                try {
+                    const skill = readSkill(path.join(root, entry.name));
+                    skills.set(skill.name, skill);
+                }
+                catch (error) {
+                    warnings.push(String(error));
+                }
+            }
+        }
+        catch (error) {
+            warnings.push(String(error));
+        }
+    }
+    return { skills: [...skills.values()].sort((a, b) => a.name.localeCompare(b.name)), warnings };
+}
+/** Only HTTPS GitHub repositories (or owner/repo shorthand), never arbitrary git transports. */
+function githubUrl(source) {
+    const match = /^(?:https:\/\/github\.com\/)?([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(source);
+    if (!match || match[1] === "." || match[1] === ".." || match[2] === "." || match[2] === "..")
+        throw new Error("Expected an existing local directory, owner/repo, or https://github.com/owner/repo (no branch/subdirectory URLs).");
+    return `https://github.com/${match[1]}/${match[2]}.git`;
+}
+function findSkills(directory) {
+    const found = [];
+    let visited = 0;
+    function walk(dir, depth) {
+        if (++visited > 10000 || depth > 20)
+            throw new Error("Skill source is too large or deeply nested.");
+        if (!lstatSync(dir).isDirectory())
+            throw new Error(`Expected a real directory: ${dir}`);
+        if (existsSync(path.join(dir, "SKILL.md"))) {
+            found.push(dir);
+            return;
+        }
+        for (const entry of readdirSync(dir, { withFileTypes: true }))
+            if (entry.isDirectory() && !ignored.has(entry.name))
+                walk(path.join(dir, entry.name), depth + 1);
+    }
+    walk(directory, 0);
+    if (!found.length)
+        throw new Error("No SKILL.md files found in the source.");
+    return found;
+}
+function validateTree(directory) {
+    let bytes = 0;
+    let files = 0;
+    function walk(file, depth) {
+        const stat = lstatSync(file);
+        if (++files > 10000 || depth > 30 || (bytes += stat.size) > 50 * 1024 * 1024)
+            throw new Error("Skill exceeds installation limits (50 MiB / 10000 entries / 30 levels).");
+        if (stat.isDirectory()) {
+            for (const name of readdirSync(file))
+                if (!ignored.has(name))
+                    walk(path.join(file, name), depth + 1);
+        }
+        else if (!stat.isFile())
+            throw new Error(`Symlinks and special files are not supported: ${file}`);
+    }
+    walk(directory, 0);
+}
+export async function installSkills(source, options = {}) {
+    let temporary;
+    try {
+        let directory = path.resolve(source);
+        if (!existsSync(directory)) {
+            const url = githubUrl(source);
+            temporary = mkdtempSync(path.join(os.tmpdir(), "megacode-skills-"));
+            directory = path.join(temporary, "repo");
+            await exec("git", ["-c", "core.hooksPath=/dev/null", "clone", "--depth", "1", "--", url, directory], {
+                timeout: 120000, maxBuffer: 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+            });
+        }
+        const sources = findSkills(directory);
+        const skills = sources.map(readSkill);
+        const root = roots(options)[options.global ? 0 : 1];
+        const names = new Set();
+        for (const [i, skill] of skills.entries()) {
+            if (names.has(skill.name))
+                throw new Error(`Duplicate skill name: ${skill.name}`);
+            names.add(skill.name);
+            if (existsSync(path.join(root, skill.name)))
+                throw new Error(`Skill already installed: ${skill.name}. Remove its directory before reinstalling.`);
+            validateTree(sources[i]);
+        }
+        mkdirSync(root, { recursive: true });
+        const created = [];
+        try {
+            for (const [i, skill] of skills.entries()) {
+                const target = path.join(root, skill.name);
+                mkdirSync(target); // Exclusive reservation: never overwrite another installation.
+                created.push(target);
+                cpSync(sources[i], target, { recursive: true, filter: (file) => !ignored.has(path.basename(file)) });
+            }
+        }
+        catch (error) {
+            for (const target of created)
+                rmSync(target, { recursive: true, force: true });
+            throw error;
+        }
+        return skills.map((skill) => ({ ...skill, file: path.join(root, skill.name, "SKILL.md") }));
+    }
+    finally {
+        if (temporary)
+            rmSync(temporary, { recursive: true, force: true });
+    }
+}
+export const SKILLS_HELP = "Usage: skills [list | install <local-directory|owner/repo|GitHub-URL> [--global]]";
+/** Shared by the standalone CLI and /skills. */
+export async function runSkillsCommand(args, options = {}) {
+    if (!args.length || (args.length === 1 && args[0] === "list")) {
+        const { skills, warnings } = discoverSkills(options);
+        return [skills.length ? skills.map((s) => `${s.name}: ${s.description}\n  ${s.file}`).join("\n") : "No skills installed.", ...warnings, SKILLS_HELP].join("\n");
+    }
+    if (args[0] !== "install")
+        throw new Error(SKILLS_HELP);
+    const global = args.includes("--global");
+    const sources = args.slice(1).filter((arg) => arg !== "--global");
+    if (sources.length !== 1 || sources[0].startsWith("--"))
+        throw new Error(SKILLS_HELP);
+    const installed = await installSkills(sources[0], { ...options, global });
+    return installed.map((s) => `Installed ${s.name} at ${s.file}`).join("\n");
+}

package/dist/adapters/storage.js

@@ -0,0 +1,30 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+let dir = path.join(os.homedir(), ".megacode");
+/** Where megacode persists everything: ~/.megacode unless the entry point chose another folder. */
+export const configDir = () => dir;
+/** Points all persistence at another folder ($MEGACODE_CONFIG_DIR in the CLI, a temporary one in tests). */
+export function setConfigDir(next) {
+    dir = next;
+}
+export function readJson(file, fallback) {
+    try {
+        return JSON.parse(readFileSync(path.join(dir, file), "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeJson(file, data, opts = {}) {
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const p = path.join(dir, file);
+        writeFileSync(p, JSON.stringify(data, null, 2), { mode: opts.secret ? 0o600 : 0o644 });
+        if (opts.secret)
+            chmodSync(p, 0o600); // mode is ignored when the file already exists
+    }
+    catch {
+        // persistence is a convenience; ignore write failures
+    }
+}

package/dist/adapters/tools/files.js

@@ -0,0 +1,113 @@
+import { glob, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { compactOutput, filePage } from "./output.js";
+import { displayPath, resolvePath } from "./paths.js";
+const IGNORE = ["**/node_modules/**", "**/.git/**"];
+const MAX_LISTED = 1000;
+/** File contents, or null if it doesn't exist. */
+const readIfExists = (file) => readFile(file, "utf8").catch((error) => {
+    if (error.code === "ENOENT")
+        return null;
+    throw error;
+});
+/**
+ * Asks the user to approve the change, then writes it only if the file is still exactly what was
+ * previewed, so edits made while the dialog was open are never overwritten. Null if denied.
+ */
+async function applyChange(ctx, p) {
+    const change = { file: p.file, before: p.before ?? "", after: p.after, ...(p.before === null ? { created: true } : {}) };
+    const title = `${p.action === "write" ? "Write" : "Edit"} ${displayPath(p.file)}`;
+    if (!(await ctx.approve({ tool: p.tool, title, change })))
+        return null;
+    if ((await readIfExists(p.file)) !== p.before)
+        throw new Error(`File changed while awaiting approval. Read it again before retrying the ${p.action}.`);
+    await mkdir(path.dirname(p.file), { recursive: true });
+    await writeFile(p.file, p.after);
+    return change;
+}
+export const readFileTool = {
+    name: "read_file",
+    description: "Read numbered text lines. Large results include a continuation offset.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Relative or absolute path" },
+            offset: { type: "integer", minimum: 1, description: "1-based line to start from" },
+            limit: { type: "integer", minimum: 1, description: "Max lines (default 200); also bounded by character budget" },
+        },
+        required: ["path"],
+    },
+    async run({ path, offset, limit }) {
+        return filePage(await readFile(resolvePath(path), "utf8"), offset, limit);
+    },
+};
+export const writeFileTool = {
+    name: "write_file",
+    description: "Create or overwrite a file with the given content. Prefer edit_file for changes to existing files.",
+    parameters: {
+        type: "object",
+        properties: { path: { type: "string" }, content: { type: "string" } },
+        required: ["path", "content"],
+    },
+    async run({ path, content }, ctx) {
+        const file = resolvePath(path);
+        const before = await readIfExists(file);
+        const change = await applyChange(ctx, { tool: "write_file", action: "write", file, before, after: content });
+        if (!change)
+            return "User denied the write.";
+        return { output: `Wrote ${file}`, isError: false, change };
+    },
+};
+export const editFile = {
+    name: "edit_file",
+    description: "Replace an exact string in a file. old_string must match exactly (including whitespace) and be unique unless replace_all is true.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            old_string: { type: "string" },
+            new_string: { type: "string" },
+            replace_all: { type: "boolean" },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    async run({ path, old_string, new_string, replace_all = false }, ctx) {
+        if (old_string === "")
+            throw new Error("old_string must not be empty.");
+        const file = resolvePath(path);
+        const before = await readFile(file, "utf8");
+        const matches = before.split(old_string).length - 1;
+        if (matches === 0)
+            throw new Error("old_string not found in file");
+        if (matches > 1 && !replace_all)
+            throw new Error(`old_string matches ${matches} times; add context to make it unique or set replace_all`);
+        // A replacer function keeps `$&` and friends in new_string literal.
+        const after = replace_all ? before.replaceAll(old_string, () => new_string) : before.replace(old_string, () => new_string);
+        const change = await applyChange(ctx, { tool: "edit_file", action: "edit", file, before, after });
+        if (!change)
+            return "User denied the edit.";
+        const replaced = replace_all ? matches : 1;
+        return { output: `Edited ${file} (${replaced} replacement${replaced === 1 ? "" : "s"})`, isError: false, change };
+    },
+};
+export const listFiles = {
+    name: "list_files",
+    description: "List files matching a glob pattern (e.g. 'src/**/*.ts'). Ignores node_modules and .git.",
+    parameters: {
+        type: "object",
+        properties: { pattern: { type: "string", description: "Glob pattern, default '**/*'" } },
+    },
+    async run({ pattern = "**/*" }) {
+        const files = [];
+        let truncated = false;
+        for await (const f of glob(pattern, { cwd: process.cwd(), exclude: IGNORE })) {
+            if (files.length >= MAX_LISTED) {
+                truncated = true;
+                break;
+            }
+            files.push(f);
+        }
+        const output = files.length ? await compactOutput(files.sort().join("\n")) : "No files found.";
+        return output + (truncated ? `\n[Only ${MAX_LISTED} entries listed; narrow the glob pattern]` : "");
+    },
+};

package/dist/adapters/tools/image.js

@@ -0,0 +1,63 @@
+import { open } from "node:fs/promises";
+import { resolvePath } from "./paths.js";
+const MAX_BYTES = 5 * 1024 * 1024;
+const TOO_LARGE = "Image exceeds 5 MiB; resize it before viewing.";
+const ascii = (data, start, end) => data.toString("ascii", start, end);
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Magic-byte signatures. The file extension is never trusted. */
+const SIGNATURES = [
+    ["image/png", (d) => d.subarray(0, PNG.length).equals(PNG)],
+    ["image/jpeg", (d) => d[0] === 0xff && d[1] === 0xd8 && d[2] === 0xff],
+    ["image/gif", (d) => ["GIF87a", "GIF89a"].includes(ascii(d, 0, 6))],
+    ["image/webp", (d) => ascii(d, 0, 4) === "RIFF" && ascii(d, 8, 12) === "WEBP"],
+];
+export const detectImageType = (data) => SIGNATURES.find(([, matches]) => matches(data))?.[0];
+/**
+ * Reads a regular file of at most `maxBytes`. The size is checked before reading and again while
+ * reading, since the file can grow in between; it never reads more than `maxBytes + 1`.
+ */
+async function readBounded(file, maxBytes) {
+    const handle = await open(file, "r");
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error("Image path must be a regular file.");
+        if (info.size > maxBytes)
+            throw new Error(TOO_LARGE);
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let size = 0;
+        while (size < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, size, buffer.length - size, null);
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+        }
+        if (size > maxBytes)
+            throw new Error(TOO_LARGE);
+        return buffer.subarray(0, size);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export const viewImage = {
+    name: "view_image",
+    description: "View a local PNG, JPEG, GIF, or WebP image (up to 5 MiB). Use for screenshots and other visual files; requires a vision-capable model.",
+    parameters: {
+        type: "object",
+        properties: { path: { type: "string", description: "Relative or absolute image path" } },
+        required: ["path"],
+    },
+    async run({ path }) {
+        const file = resolvePath(path);
+        const data = await readBounded(file, MAX_BYTES);
+        const mediaType = detectImageType(data);
+        if (!mediaType)
+            throw new Error("Unsupported image format. Use PNG, JPEG, GIF, or WebP.");
+        return {
+            output: `Image: ${file} (${mediaType}, ${data.length} bytes)`,
+            isError: false,
+            images: [{ mediaType, data: data.toString("base64") }],
+        };
+    },
+};

package/dist/adapters/tools/index.js

@@ -0,0 +1,26 @@
+import { editFile, listFiles, readFileTool, writeFileTool } from "./files.js";
+import { viewImage } from "./image.js";
+import { askQuestions } from "./questions.js";
+import { bash, grep } from "./shell.js";
+import { validateArguments } from "./validation.js";
+const TOOLS = [askQuestions, viewImage, readFileTool, writeFileTool, editFile, bash, listFiles, grep];
+const byName = new Map(TOOLS.map((t) => [t.name, t]));
+/** The tools megacode ships with. Failures come back as error results, never as exceptions. */
+export const builtinTools = {
+    specs: () => TOOLS.map(({ name, description, parameters }) => ({ name, description, parameters })),
+    has: (name) => byName.has(name),
+    async execute(call, ctx) {
+        const tool = byName.get(call.name);
+        if (!tool)
+            return { output: `Unknown tool: ${call.name}`, isError: true };
+        try {
+            const input = validateArguments(call.input, tool.parameters);
+            ctx.signal?.throwIfAborted();
+            const result = await tool.run(input, ctx);
+            return typeof result === "string" ? { output: result, isError: false } : result;
+        }
+        catch (e) {
+            return { output: `Error: ${e.message}`, isError: true };
+        }
+    },
+};

package/dist/adapters/tools/output.js

@@ -0,0 +1,56 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { loadSettings } from "../settings.js";
+/** Character budgets are provider-neutral bounds, not token estimates. */
+export const OUTPUT_CHARS = 12_000;
+export const READ_LINES = 200;
+/** Keep both setup/errors at the start and summaries/failures at the end. */
+export function elideMiddle(text, budget = OUTPUT_CHARS) {
+    if (text.length <= budget)
+        return text;
+    const head = Math.ceil(budget / 2);
+    const tail = Math.floor(budget / 2);
+    return `${text.slice(0, head)}\n... [${text.length - budget} chars omitted]\n${text.slice(-tail)}`;
+}
+/**
+ * Fits output into the "Max tool output" budget (see /config), keeping both ends. The full text goes to a
+ * temporary file the model can read, so nothing is lost without filling every later request.
+ */
+export async function compactOutput(text, budget = loadSettings().maxToolOutput) {
+    if (text.length <= budget)
+        return text;
+    try {
+        const dir = await mkdtemp(path.join(tmpdir(), "megacode-output-"));
+        const file = path.join(dir, "output.txt");
+        await writeFile(file, text, { mode: 0o600 });
+        return `${elideMiddle(text, budget)}\n[Full output: ${file}; read_file or search this file]`;
+    }
+    catch {
+        // Do not silently discard evidence if the temporary directory is unavailable.
+        return text;
+    }
+}
+/** Never cut a source line silently. A single oversized line is returned in full. */
+export function filePage(text, offset = 1, limit = READ_LINES) {
+    if (!Number.isInteger(offset) || offset < 1 || !Number.isInteger(limit) || limit < 1)
+        throw new Error("offset and limit must be positive integers");
+    const lines = text.split("\n");
+    if (lines.length > 1 && lines.at(-1) === "")
+        lines.pop(); // a final newline ends the last line; it isn't another one
+    if (offset > lines.length)
+        return `[EOF: ${lines.length} lines]`;
+    const page = [];
+    let size = 0;
+    let next = offset;
+    for (; next <= lines.length && next < offset + limit; next++) {
+        const line = `${next}\t${lines[next - 1]}`;
+        if (page.length && size + line.length + 1 > OUTPUT_CHARS)
+            break;
+        page.push(line);
+        size += line.length + 1;
+    }
+    if (next <= lines.length)
+        page.push(`[${lines.length} lines total; continue with offset=${next}]`);
+    return page.join("\n");
+}

package/dist/adapters/tools/paths.js

@@ -0,0 +1,5 @@
+import path from "node:path";
+/** Tool paths are relative to the session's working directory. */
+export const resolvePath = (p) => path.resolve(process.cwd(), p);
+/** Short form for titles and messages. */
+export const displayPath = (abs) => path.relative(process.cwd(), abs);

package/dist/adapters/tools/questions.js

@@ -0,0 +1,52 @@
+const MAX_QUESTIONS = 8;
+const MAX_OPTIONS = 8;
+const MAX_QUESTION_LENGTH = 1000;
+const MAX_OPTION_LENGTH = 200;
+const isText = (v, max) => typeof v === "string" && !!v.trim() && v.length <= max;
+const inRange = (list, max) => list.length >= 1 && list.length <= max;
+function parseQuestion(item) {
+    const { question, options } = (item && typeof item === "object" ? item : {});
+    if (!isText(question, MAX_QUESTION_LENGTH))
+        throw new Error(`Each question must have non-empty question text (up to ${MAX_QUESTION_LENGTH} characters).`);
+    if (options === undefined)
+        return { question: question.trim() };
+    if (!Array.isArray(options) || !inRange(options, MAX_OPTIONS) || !options.every((o) => isText(o, MAX_OPTION_LENGTH)))
+        throw new Error(`options must contain 1 to ${MAX_OPTIONS} non-empty strings (up to ${MAX_OPTION_LENGTH} characters each).`);
+    return { question: question.trim(), options: options.map((o) => o.trim()) };
+}
+/** Validate model-supplied input before opening an interactive form. */
+export function parseQuestions(input) {
+    if (!Array.isArray(input) || !inRange(input, MAX_QUESTIONS))
+        throw new Error(`questions must contain between 1 and ${MAX_QUESTIONS} questions.`);
+    return input.map(parseQuestion);
+}
+export const askQuestions = {
+    name: "ask_questions",
+    description: "Ask the user for clarification or preferences using an interactive questionnaire. Use when you need user input before proceeding. Each question accepts a suggested option or a custom text answer. Never invent answers or repeat a cancelled/unavailable questionnaire.",
+    parameters: {
+        type: "object",
+        properties: {
+            questions: {
+                type: "array", minItems: 1, maxItems: 8,
+                items: {
+                    type: "object",
+                    properties: {
+                        question: { type: "string", description: "The question to ask" },
+                        options: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8, description: "Optional suggested answers; custom text is always allowed" },
+                    },
+                    required: ["question"],
+                },
+            },
+        },
+        required: ["questions"],
+    },
+    async run({ questions }, { askQuestions, signal }) {
+        const parsed = parseQuestions(questions);
+        if (!askQuestions)
+            return { output: "Interactive questionnaires are unavailable in this mode. Ask your questions in your text response instead.", isError: true };
+        const answers = await askQuestions(parsed, signal);
+        return answers === null
+            ? { output: "Questionnaire cancelled by user. No answers submitted.", isError: true }
+            : JSON.stringify({ answers });
+    },
+};

package/dist/adapters/tools/shell.js

@@ -0,0 +1,73 @@
+import { spawn } from "node:child_process";
+import { loadSettings } from "../settings.js";
+import { compactOutput } from "./output.js";
+const MAX_CAPTURE = 10_000_000; // bound memory for runaway commands; the model sees a compacted view anyway
+/** Runs a process with combined stdout/stderr, bounded in memory and compacted for the model. Never rejects. */
+function runProcess(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: process.cwd(),
+            shell: opts.shell,
+            timeout: opts.timeout ?? 120_000,
+            signal: opts.signal,
+            stdio: ["ignore", "pipe", "pipe"], // never let a command grab the terminal
+        });
+        let out = "";
+        let dropped = 0;
+        const collect = (data) => {
+            const room = Math.max(0, MAX_CAPTURE - out.length);
+            out += data.slice(0, room);
+            dropped += data.length - Math.min(data.length, room);
+        };
+        // Decode each stream incrementally so split UTF-8 characters are preserved.
+        child.stdout.setEncoding("utf8").on("data", collect);
+        child.stderr.setEncoding("utf8").on("data", collect);
+        let finished = false;
+        const finish = async (isError, ...notes) => {
+            if (finished)
+                return; // "error" and "close" can both fire
+            finished = true;
+            const text = (await compactOutput(out)).trimEnd();
+            resolve({ output: [text, dropped ? `[${dropped} more chars not captured]` : "", ...notes].filter(Boolean).join("\n"), isError });
+        };
+        child.on("error", (e) => finish(true, e.name === "AbortError" ? "[interrupted]" : `Error: ${e.message}`));
+        child.on("close", (code, signal) => {
+            const success = !signal && code !== null && (opts.successCodes ?? [0]).includes(code);
+            finish(!success, !success && code !== null ? `[exit code ${code}]` : "", signal ? `[killed: ${signal}]` : "");
+        });
+    });
+}
+export const bash = {
+    name: "bash",
+    description: "Run a shell command in the working directory. Returns combined stdout/stderr.",
+    parameters: {
+        type: "object",
+        properties: {
+            command: { type: "string" },
+            timeout_ms: { type: "integer", minimum: 0, description: "Timeout in milliseconds (default set by the user, usually 120000)" },
+        },
+        required: ["command"],
+    },
+    async run({ command, timeout_ms }, { approve, signal }) {
+        if (!(await approve({ tool: "bash", title: "Bash command", body: command })))
+            return "User denied the command.";
+        const result = await runProcess(command, [], { shell: true, timeout: timeout_ms ?? loadSettings().bashTimeoutMs, signal });
+        return { ...result, output: result.output || "(no output)" };
+    },
+};
+export const grep = {
+    name: "grep",
+    description: "Search file contents with a regular expression. Returns matching lines with file:line prefixes.",
+    parameters: {
+        type: "object",
+        properties: {
+            pattern: { type: "string" },
+            path: { type: "string", description: "Directory or file to search, default '.'" },
+        },
+        required: ["pattern"],
+    },
+    async run({ pattern, path: p = "." }, { signal }) {
+        const result = await runProcess("grep", ["-rnIE", "--exclude-dir=node_modules", "--exclude-dir=.git", "--", pattern, p], { signal, successCodes: [0, 1] });
+        return { ...result, output: result.output || "No matches." };
+    },
+};

package/dist/adapters/tools/validation.js

@@ -0,0 +1,34 @@
+const TYPE_CHECKS = {
+    string: (v) => typeof v === "string",
+    boolean: (v) => typeof v === "boolean",
+    number: (v) => typeof v === "number" && Number.isFinite(v),
+    integer: (v) => Number.isSafeInteger(v),
+    array: Array.isArray,
+    object: (v) => !!v && typeof v === "object" && !Array.isArray(v),
+};
+/**
+ * Checks model-supplied arguments against a tool's top-level schema: required keys, each property's
+ * `type` and `minimum`. Nested structure is left to the tool. Throws a message the model can act on.
+ */
+export function validateArguments(input, schema) {
+    if (!TYPE_CHECKS.object(input))
+        throw new Error("Tool arguments must be a JSON object.");
+    const args = input;
+    if ("_invalid_json" in args)
+        throw new Error("Tool arguments were not valid JSON.");
+    const missing = (schema.required ?? []).filter((key) => args[key] === undefined);
+    if (missing.length)
+        throw new Error(`Missing required arguments: ${missing.join(", ")}`);
+    for (const [key, property] of Object.entries(schema.properties)) {
+        const value = args[key];
+        if (value === undefined || !property.type)
+            continue;
+        const check = TYPE_CHECKS[property.type];
+        if (check && !check(value))
+            throw new Error(`${key} must be ${article(property.type)} ${property.type}.`);
+        if (property.minimum !== undefined && value < property.minimum)
+            throw new Error(`${key} must be at least ${property.minimum}.`);
+    }
+    return args;
+}
+const article = (word) => (/^[aeiou]/.test(word) ? "an" : "a");

package/dist/args.js

@@ -0,0 +1,30 @@
+import { parseArgs } from "node:util";
+import { WORKTREE_NAME } from "./adapters/git/worktree.js";
+/**
+ * Parses command-line arguments. -w takes an optional name (`megacode -w`, `megacode -w fix-auth "prompt"`),
+ * which parseArgs can't express: the next argument is the name if it looks like one, otherwise it's left for the prompt.
+ */
+export function parseCliArgs(argv) {
+    const args = [...argv];
+    let worktree;
+    const wi = args.findIndex((a) => a === "-w" || a === "--worktree" || a.startsWith("--worktree="));
+    if (wi !== -1) {
+        const [flag] = args.splice(wi, 1);
+        if (flag.startsWith("--worktree="))
+            worktree = { name: flag.slice("--worktree=".length) || undefined };
+        else if (args[wi] !== undefined && WORKTREE_NAME.test(args[wi]))
+            worktree = { name: args.splice(wi, 1)[0] };
+        else
+            worktree = {};
+    }
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            model: { type: "string", short: "m" },
+            ask: { type: "boolean", short: "a" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    return { model: values.model, ask: !!values.ask, help: !!values.help, worktree, prompt: positionals.join(" ") };
+}