kritya 0.8.2-beta

package/dist/tools/document/xlsx.js

@@ -0,0 +1,87 @@
+import ExcelJS from "exceljs";
+const CELL_REF_RE = /^[A-Za-z]{1,3}[1-9][0-9]*$/;
+export async function readXlsx(buf) {
+    const workbook = new ExcelJS.Workbook();
+    // exceljs's bundled types pin an older @types/node Buffer shape; the
+    // runtime accepts any Node Buffer.
+    await workbook.xlsx.load(buf);
+    const parts = [];
+    workbook.eachSheet((sheet) => {
+        parts.push(`## ${sheet.name}`);
+        sheet.eachRow((row) => {
+            const cells = row.values.slice(1).map((v) => cellToString(v));
+            parts.push(cells.join("\t"));
+        });
+        parts.push("");
+    });
+    return parts.join("\n");
+}
+function cellToString(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "object" && "text" in v) {
+        return String(v.text);
+    }
+    if (typeof v === "object" && "result" in v) {
+        return String(v.result);
+    }
+    return String(v);
+}
+/** Display an existing or new cell value as a short string, including formulas. */
+function describeValue(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "object" && "formula" in v) {
+        return "=" + String(v.formula);
+    }
+    return cellToString(v);
+}
+/** Convert a model-supplied value into what exceljs expects; a leading "=" becomes a formula. */
+function toCellValue(value) {
+    if (typeof value === "string" && value.startsWith("=")) {
+        return { formula: value.slice(1), date1904: false };
+    }
+    return value;
+}
+/**
+ * Change specific cells of an existing workbook in place, preserving every
+ * other cell, formula, and sheet. Returns the new file bytes and a record of
+ * what changed (old -> new) for the permission preview and result message.
+ */
+export async function editXlsx(buf, edits) {
+    const workbook = new ExcelJS.Workbook();
+    await workbook.xlsx.load(buf);
+    const applied = [];
+    for (const edit of edits) {
+        if (!CELL_REF_RE.test(edit.cell)) {
+            throw new Error(`Invalid cell reference "${edit.cell}" (expected A1 notation like "B7")`);
+        }
+        const ws = edit.sheet ? workbook.getWorksheet(edit.sheet) : workbook.worksheets[0];
+        if (!ws) {
+            const names = workbook.worksheets.map((w) => w.name).join(", ");
+            throw new Error(`Worksheet "${edit.sheet}" not found. Sheets: ${names}`);
+        }
+        const cell = ws.getCell(edit.cell.toUpperCase());
+        const oldValue = describeValue(cell.value);
+        cell.value = toCellValue(edit.value);
+        applied.push({
+            sheet: ws.name,
+            cell: edit.cell.toUpperCase(),
+            oldValue,
+            newValue: describeValue(cell.value),
+        });
+    }
+    const arrayBuffer = await workbook.xlsx.writeBuffer();
+    return { buf: Buffer.from(arrayBuffer), applied };
+}
+export async function writeXlsx(sheets) {
+    const workbook = new ExcelJS.Workbook();
+    for (const sheet of sheets) {
+        const ws = workbook.addWorksheet(sheet.name);
+        for (const row of sheet.rows) {
+            ws.addRow(row);
+        }
+    }
+    const arrayBuffer = await workbook.xlsx.writeBuffer();
+    return Buffer.from(arrayBuffer);
+}

package/dist/tools/document.js

@@ -0,0 +1,389 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeFileAtomic } from "../atomicWrite.js";
+import { resolveSafe, truncateResult } from "./common.js";
+import { readDocx, writeDocx } from "./document/docx.js";
+import { readXlsx, writeXlsx, editXlsx } from "./document/xlsx.js";
+import { readPptx, writePptx } from "./document/pptx.js";
+import { readPdf, writePdf, editPdf } from "./document/pdf.js";
+const READABLE_EXTENSIONS = [".docx", ".xlsx", ".pptx", ".pdf"];
+const BLOCK_SCHEMA = {
+    type: "array",
+    description: "Flowed content blocks, in document order.",
+    items: {
+        type: "object",
+        properties: {
+            type: {
+                type: "string",
+                enum: ["heading1", "heading2", "heading3", "paragraph", "bullet", "numbered"],
+            },
+            text: { type: "string" },
+        },
+        required: ["type", "text"],
+    },
+};
+export const readDocumentTool = {
+    name: "read_document",
+    description: "Read a Word (.docx), Excel (.xlsx), PowerPoint (.pptx), or PDF (.pdf) file from the " +
+        "workspace and return its text content. For plain text, Markdown, or CSV files use read_file instead.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path relative to the workspace root" },
+        },
+        required: ["path"],
+    },
+    requiresPermission: false,
+    summarize: (args) => `Read ${args.path}`,
+    async execute(args, ctx) {
+        const relPath = String(args.path);
+        const abs = resolveSafe(ctx.workspace, relPath);
+        const ext = path.extname(abs).toLowerCase();
+        const buf = await fs.readFile(abs);
+        switch (ext) {
+            case ".docx":
+                return truncateResult(await readDocx(buf));
+            case ".xlsx":
+                return truncateResult(await readXlsx(buf));
+            case ".pptx":
+                return truncateResult(await readPptx(buf));
+            case ".pdf":
+                return truncateResult(await readPdf(buf));
+            default:
+                throw new Error(`Unsupported extension "${ext}" for read_document. Supported: ` +
+                    `${READABLE_EXTENSIONS.join(", ")}. For text formats such as .md, .txt, or .csv, use read_file.`);
+        }
+    },
+};
+export const writeDocumentTool = {
+    name: "write_document",
+    description: "Create or overwrite a Word (.docx), Excel (.xlsx), PowerPoint (.pptx), or PDF (.pdf) file " +
+        "in the workspace from structured content. Always replaces the whole document. " +
+        "For .docx and .pdf, pass `content.blocks`. For .xlsx, pass `content.sheets`. For .pptx, pass `content.slides`.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path relative to the workspace root" },
+            content: {
+                type: "object",
+                properties: {
+                    blocks: BLOCK_SCHEMA,
+                    sheets: {
+                        type: "array",
+                        description: "Worksheets, for .xlsx.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: { type: "string" },
+                                rows: {
+                                    type: "array",
+                                    items: {
+                                        type: "array",
+                                        items: { type: ["string", "number", "boolean", "null"] },
+                                    },
+                                },
+                            },
+                            required: ["name", "rows"],
+                        },
+                    },
+                    slides: {
+                        type: "array",
+                        description: "Slides, for .pptx. Every slide needs its body text in `bullets` — a slide with " +
+                            "only a `title` renders as a single line on an otherwise empty slide.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                title: { type: "string", description: "Slide heading, one short line." },
+                                bullets: {
+                                    type: "array",
+                                    items: { type: "string" },
+                                    description: "The slide's body, one string per bullet. Put all visible content here; " +
+                                        "aim for 3-6 bullets of at most ~15 words each.",
+                                },
+                                notes: {
+                                    type: "string",
+                                    description: "Speaker notes; not shown on the slide itself.",
+                                },
+                            },
+                            required: ["title", "bullets"],
+                        },
+                    },
+                },
+            },
+        },
+        required: ["path", "content"],
+    },
+    requiresPermission: true,
+    summarize: (args) => `Write ${args.path}`,
+    async preview(args) {
+        const content = extractContent(args);
+        if (content.blocks)
+            return `${content.blocks.length} content block(s)`;
+        if (content.sheets)
+            return `${content.sheets.length} sheet(s)`;
+        if (content.slides)
+            return `${content.slides.length} slide(s)`;
+        return null;
+    },
+    async execute(args, ctx) {
+        const relPath = String(args.path);
+        const abs = resolveSafe(ctx.workspace, relPath);
+        const ext = path.extname(abs).toLowerCase();
+        const content = extractContent(args);
+        let buf;
+        switch (ext) {
+            case ".docx":
+                buf = await writeDocx(requireField(content.blocks, "blocks", ext, args));
+                break;
+            case ".pdf":
+                buf = await writePdf(requireField(content.blocks, "blocks", ext, args));
+                break;
+            case ".xlsx":
+                buf = await writeXlsx(requireField(content.sheets, "sheets", ext, args));
+                break;
+            case ".pptx":
+                buf = await writePptx(requireField(content.slides, "slides", ext, args));
+                break;
+            default:
+                throw new Error(`Unsupported extension "${ext}" for write_document. Supported: ` +
+                    `${READABLE_EXTENSIONS.join(", ")}. For text formats such as .md, .txt, or .csv, use write_file.`);
+        }
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        ctx.undo?.snapshot(abs, relPath);
+        await writeFileAtomic(abs, buf);
+        return `Wrote ${relPath}`;
+    },
+};
+export const editSpreadsheetTool = {
+    name: "edit_spreadsheet",
+    description: "Change specific cells of an existing Excel (.xlsx) file in place, leaving every other cell, " +
+        "formula, and sheet untouched. Pass one or more edits, each with a cell in A1 notation and a " +
+        'new value; a value beginning with "=" is stored as a formula. Use read_document first to ' +
+        "see the sheet. To create a new spreadsheet or replace one wholesale, use write_document instead.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path relative to the workspace root" },
+            edits: {
+                type: "array",
+                description: "Cell changes to apply, in order.",
+                items: {
+                    type: "object",
+                    properties: {
+                        sheet: {
+                            type: "string",
+                            description: "Sheet name; defaults to the first worksheet if omitted.",
+                        },
+                        cell: { type: "string", description: 'Cell in A1 notation, e.g. "B7".' },
+                        value: {
+                            type: ["string", "number", "boolean", "null"],
+                            description: 'New value; a string starting with "=" becomes a formula.',
+                        },
+                    },
+                    required: ["cell", "value"],
+                },
+            },
+        },
+        required: ["path", "edits"],
+    },
+    requiresPermission: true,
+    summarize: (args) => {
+        const edits = (args.edits ?? []);
+        return `Edit ${args.path} (${edits.length} cell${edits.length === 1 ? "" : "s"})`;
+    },
+    async preview(args, ctx) {
+        const edits = (args.edits ?? []);
+        if (edits.length === 0)
+            return null;
+        try {
+            const abs = resolveSafe(ctx.workspace, String(args.path));
+            const buf = await fs.readFile(abs);
+            const { applied } = await editXlsx(buf, edits);
+            return applied
+                .map((a) => `${a.sheet}!${a.cell}:  ${a.oldValue || "(empty)"}  →  ${a.newValue}`)
+                .join("\n");
+        }
+        catch {
+            // Fall back to a value-only preview if the file can't be read yet.
+            return edits
+                .map((e) => `${e.sheet ? e.sheet + "!" : ""}${e.cell} → ${String(e.value)}`)
+                .join("\n");
+        }
+    },
+    async execute(args, ctx) {
+        const relPath = String(args.path);
+        const abs = resolveSafe(ctx.workspace, relPath);
+        const ext = path.extname(abs).toLowerCase();
+        if (ext !== ".xlsx") {
+            throw new Error(`edit_spreadsheet only supports .xlsx files, got "${ext}"`);
+        }
+        const edits = (args.edits ?? []);
+        if (edits.length === 0)
+            throw new Error("edit_spreadsheet: `edits` must be non-empty");
+        const buf = await fs.readFile(abs);
+        const { buf: out, applied } = await editXlsx(buf, edits);
+        ctx.undo?.snapshot(abs, relPath);
+        await writeFileAtomic(abs, out);
+        const detail = applied.map((a) => `${a.sheet}!${a.cell}=${a.newValue}`).join(", ");
+        return `Updated ${applied.length} cell(s) in ${relPath}: ${detail}`;
+    },
+};
+/** Build a validated PdfEdit from the tool arguments. */
+function toPdfEdit(args) {
+    const op = String(args.op);
+    const asPages = (v, field) => {
+        if (!Array.isArray(v) || v.length === 0) {
+            throw new Error(`edit_pdf: "${field}" must be a non-empty array of page numbers`);
+        }
+        return v.map(Number);
+    };
+    switch (op) {
+        case "delete_pages":
+            return { op, pages: asPages(args.pages, "pages") };
+        case "extract_pages":
+            return { op, pages: asPages(args.pages, "pages") };
+        case "reorder_pages":
+            return { op, order: asPages(args.order, "order") };
+        case "rotate_page":
+            if (args.page === undefined || args.degrees === undefined) {
+                throw new Error('edit_pdf: rotate_page requires "page" and "degrees"');
+            }
+            return { op, page: Number(args.page), degrees: Number(args.degrees) };
+        default:
+            throw new Error(`edit_pdf: unknown op "${op}"`);
+    }
+}
+export const editPdfTool = {
+    name: "edit_pdf",
+    description: "Modify the pages of an existing PDF (.pdf) in place: delete_pages, rotate_page, " +
+        "reorder_pages, or extract_pages (write chosen pages to a new file). Page numbers are " +
+        "1-based. This does structural page operations only — PDF text cannot be reliably " +
+        "find-and-replaced. To create a PDF from text, use write_document.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path relative to the workspace root" },
+            op: {
+                type: "string",
+                enum: ["delete_pages", "rotate_page", "reorder_pages", "extract_pages"],
+            },
+            pages: {
+                type: "array",
+                items: { type: "number" },
+                description: "1-based page numbers, for delete_pages and extract_pages.",
+            },
+            page: { type: "number", description: "1-based page number, for rotate_page." },
+            degrees: {
+                type: "number",
+                description: "Rotation in multiples of 90 (added to the page's current angle), for rotate_page.",
+            },
+            order: {
+                type: "array",
+                items: { type: "number" },
+                description: "New page order as a permutation of every page 1..N, for reorder_pages.",
+            },
+            out_path: {
+                type: "string",
+                description: "Destination for extract_pages (a new .pdf); the source file is left unchanged.",
+            },
+        },
+        required: ["path", "op"],
+    },
+    requiresPermission: true,
+    summarize: (args) => `Edit ${args.path} (${args.op})`,
+    async preview(args, ctx) {
+        try {
+            const abs = resolveSafe(ctx.workspace, String(args.path));
+            const buf = await fs.readFile(abs);
+            const { summary } = await editPdf(buf, toPdfEdit(args));
+            return summary;
+        }
+        catch (err) {
+            return err instanceof Error ? err.message : null;
+        }
+    },
+    async execute(args, ctx) {
+        const relPath = String(args.path);
+        const abs = resolveSafe(ctx.workspace, relPath);
+        if (path.extname(abs).toLowerCase() !== ".pdf") {
+            throw new Error(`edit_pdf only supports .pdf files, got "${path.extname(abs)}"`);
+        }
+        const edit = toPdfEdit(args);
+        const buf = await fs.readFile(abs);
+        const { buf: out, summary } = await editPdf(buf, edit);
+        // extract_pages writes a new file and leaves the source untouched; every other op edits in place.
+        if (edit.op === "extract_pages") {
+            if (args.out_path === undefined)
+                throw new Error("extract_pages requires `out_path`");
+            const outRel = String(args.out_path);
+            const outAbs = resolveSafe(ctx.workspace, outRel);
+            if (path.extname(outAbs).toLowerCase() !== ".pdf") {
+                throw new Error(`out_path must be a .pdf file, got "${path.extname(outAbs)}"`);
+            }
+            await fs.mkdir(path.dirname(outAbs), { recursive: true });
+            ctx.undo?.snapshot(outAbs, outRel);
+            await writeFileAtomic(outAbs, out);
+            return `${summary} → ${outRel}`;
+        }
+        ctx.undo?.snapshot(abs, relPath);
+        await writeFileAtomic(abs, out);
+        return `${summary} in ${relPath}`;
+    },
+};
+/** The payload field each extension is written from. */
+const CONTENT_FIELD = {
+    ".docx": "blocks",
+    ".pdf": "blocks",
+    ".xlsx": "sheets",
+    ".pptx": "slides",
+};
+/**
+ * Pull blocks/sheets/slides out of the arguments however the model arranged
+ * them. The documented shape is `{path, content: {slides: [...]}}`, but models
+ * routinely flatten it to `{path, slides: [...]}` or send `content` as a JSON
+ * string. Rejecting those was a dead end for the caller: the payload was right
+ * there and the write failed anyway.
+ */
+function extractContent(args) {
+    let raw = args.content;
+    if (typeof raw === "string") {
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch {
+            raw = undefined; // fall through to the top-level fields
+        }
+    }
+    const nested = (raw && typeof raw === "object" ? raw : {});
+    const pick = (key) => {
+        for (const source of [nested, args]) {
+            const value = source[key];
+            if (Array.isArray(value) && value.length > 0)
+                return value;
+        }
+        return undefined;
+    };
+    return {
+        blocks: pick("blocks"),
+        sheets: pick("sheets"),
+        slides: pick("slides"),
+    };
+}
+function requireField(value, fieldName, ext, args) {
+    if (!value || value.length === 0) {
+        // Name what did arrive: the usual cause is content for a different
+        // extension, e.g. `blocks` sent to a .pptx.
+        const present = ["blocks", "sheets", "slides"].filter((k) => extractContent(args)[k]?.length);
+        const mismatch = present.length
+            ? ` Received "${present.join('", "')}" instead — that content belongs to ` +
+                `${present
+                    .map((k) => Object.keys(CONTENT_FIELD)
+                    .filter((e) => CONTENT_FIELD[e] === k)
+                    .join("/"))
+                    .join(", ")} files.`
+            : "";
+        throw new Error(`write_document: ${ext} files are written from "${fieldName}", which is required and must be ` +
+            `non-empty. Pass it as content.${fieldName} (a top-level "${fieldName}" is also accepted).${mismatch}`);
+    }
+    return value;
+}

package/dist/tools/edit.js

@@ -0,0 +1,56 @@
+import fs from "node:fs/promises";
+import { writeFileAtomic } from "../atomicWrite.js";
+import { resolveSafe } from "./common.js";
+import { diffLines } from "./diff.js";
+import { applyEdit } from "./fuzzyMatch.js";
+import { formatSecretWarning, scanForSecrets } from "./secretScan.js";
+export const editFileTool = {
+    name: "edit_file",
+    description: "Replace a string in a file. Prefer an exact match of old_string (including whitespace); " +
+        "if the exact text isn't found, a whitespace-tolerant line match is attempted as a fallback. " +
+        "old_string must be unique in the file unless replace_all is true.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path relative to the workspace root" },
+            old_string: { type: "string", description: "Exact text to find" },
+            new_string: { type: "string", description: "Text to replace it with" },
+            replace_all: {
+                type: "boolean",
+                description: "Replace every occurrence instead of requiring uniqueness",
+            },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    requiresPermission: true,
+    resultSummary: (output) => output.split("\n")[0].replace(/ in \S+$/, ""),
+    summarize: (args) => `Edit ${args.path}`,
+    async preview(args) {
+        return diffLines(String(args.old_string ?? ""), String(args.new_string ?? ""));
+    },
+    async execute(args, ctx) {
+        const abs = resolveSafe(ctx.workspace, String(args.path));
+        const oldStr = String(args.old_string);
+        const newStr = String(args.new_string);
+        const replaceAll = Boolean(args.replace_all);
+        if (oldStr === newStr)
+            throw new Error("old_string and new_string are identical");
+        const secrets = scanForSecrets(newStr);
+        if (secrets.length > 0) {
+            throw new Error(formatSecretWarning(secrets, String(args.path)));
+        }
+        const content = await fs.readFile(abs, "utf8");
+        const match = applyEdit(content, oldStr, newStr, replaceAll);
+        if (!match.matched) {
+            throw new Error(`old_string not found in ${args.path} (tried exact and whitespace-tolerant matching). ` +
+                `Read the file and retry with text copied from it.`);
+        }
+        if (match.count > 1 && !replaceAll) {
+            throw new Error(`old_string occurs ${match.count} times in ${args.path}. Provide a longer unique string or set replace_all.`);
+        }
+        ctx.undo?.snapshot(abs, String(args.path));
+        await writeFileAtomic(abs, match.result);
+        const fuzzy = match.strategy === "line-trimmed" ? " (matched ignoring whitespace)" : "";
+        return `Replaced ${replaceAll ? match.count : 1} occurrence(s) in ${args.path}${fuzzy}`;
+    },
+};