@documonster/mcp 0.8.0-canary.sha.09791dab

package/dist/tools/sheet-write.js

@@ -0,0 +1,290 @@
+/**
+ * `sheet_write` — create a workbook from a declarative spec.
+ *
+ * Declarative rather than incremental for two reasons. A model driving twenty
+ * `set_cell` calls burns twenty round trips and has to hold the intermediate
+ * state; and `fromCsv` lets a source file be referenced by path so the rows
+ * never pass through the model's context at all — which is the difference
+ * between summarising three 4000-row CSVs and running out of budget trying.
+ *
+ * The schema is deliberately shallow. Every field here is sent to the model on
+ * every request, so styling is limited to the handful of options that actually
+ * change a report's usefulness; the deep option trees stay in `documonster_help`.
+ */
+import { Cell, Workbook, Worksheet } from "documonster/excel";
+import { readCsvFile } from "documonster/excel/csv";
+import { calculateFormulas } from "documonster/excel/formula";
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { assertWritable, outputDisplay, resolveInRoot, resolveOutputPath } from "../sandbox.js";
+import { addChart, chartSchema, generateSchema, writeGenerated } from "./chart.js";
+import { assertNonMacroOutput } from "./document.js";
+import { writeWithPolicy } from "./fs-helpers.js";
+import { textResult } from "./result.js";
+import { normalizeFormula, parseRange, toArgb } from "./spreadsheet.js";
+import { defineTool } from "./types.js";
+/** A single cell value in `rows`. `null` writes a blank. */
+const cellValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const styleSchema = z
+    .object({
+    bold: z.boolean().optional(),
+    italic: z.boolean().optional(),
+    fontColor: z.string().optional().describe('Hex RGB without "#", e.g. "C00000".'),
+    fillColor: z
+        .string()
+        .optional()
+        .describe('Solid background, hex RGB without "#", e.g. "FFEB3B".'),
+    numFmt: z
+        .string()
+        .optional()
+        .describe('Excel number format, e.g. "#,##0.00" or "0.0%" or "yyyy-mm-dd".')
+})
+    .describe("Formatting applied to a range.");
+const sheetSchema = z.object({
+    name: z.string().min(1).max(31).describe("Sheet name (Excel allows at most 31 characters)."),
+    fromCsv: z
+        .string()
+        .optional()
+        .describe("Path to a CSV to load as this sheet's contents, resolved on the server. Prefer this over `rows` for existing data: the rows never enter your context."),
+    csvDelimiter: z
+        .string()
+        .length(1)
+        .optional()
+        .describe("Delimiter for fromCsv. Omit to use a comma; doc_inspect reports the real one."),
+    generate: generateSchema
+        .optional()
+        .describe("Generate synthetic rows server-side instead of supplying them. Use this for test data — a few lines of column definitions beat emitting thousands of rows yourself."),
+    rows: z
+        .array(z.array(cellValueSchema))
+        .optional()
+        .describe("Row-major literal data, written from A1. Combine with fromCsv only if you mean to overwrite."),
+    cells: z
+        .record(z.string(), cellValueSchema)
+        .optional()
+        .describe('Individual cells by address, e.g. { "D1": "Total" }. Applied after rows.'),
+    formulas: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Formulas by address, e.g. { "B10": "=SUM(B2:B9)" }. A leading "=" is optional. Cross-sheet references work.'),
+    columnWidths: z
+        .array(z.number().positive())
+        .optional()
+        .describe("Column widths in characters, left to right."),
+    freezeRows: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Freeze this many top rows — use 1 when row 1 is a header."),
+    merges: z.array(z.string()).optional().describe('Ranges to merge, e.g. ["A1:D1"].'),
+    styles: z
+        .array(z.object({ range: z.string(), style: styleSchema }))
+        .optional()
+        .describe('Formatting per range, e.g. [{ range: "A1:D1", style: { bold: true } }].'),
+    charts: z
+        .array(chartSchema)
+        .optional()
+        .describe("Charts to place on this sheet. Ranges are plain A1 — the sheet qualification is added for you.")
+});
+export const sheetWriteTool = defineTool({
+    name: "sheet_write",
+    group: "excel",
+    title: "Write a spreadsheet",
+    description: "Create an .xlsx from a declarative spec: one call describes every sheet, its data, formulas, widths, freeze panes, merges and formatting. Use `fromCsv` to pull existing data in server-side instead of copying rows through your reply. Formulas are evaluated before saving unless recalculate is false.",
+    inputSchema: {
+        path: z
+            .string()
+            .min(1)
+            .describe("Output .xlsx path below --output-root; returned as @output/<path>."),
+        sheets: z.array(sheetSchema).min(1).describe("One entry per worksheet, in order."),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("Replace the file if it already exists. Defaults to false so existing work is never lost silently."),
+        recalculate: z
+            .boolean()
+            .optional()
+            .describe("Evaluate formulas and store their results so other tools can read values. Defaults to true.")
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+    },
+    mutates: true,
+    handler: async (args, context) => {
+        const { config } = context;
+        assertWritable(config);
+        assertNonMacroOutput(args.path);
+        const target = await resolveOutputPath(config, args.path);
+        for (const sheet of args.sheets) {
+            assertLegalSheetName(sheet.name);
+        }
+        assertUniqueNames(args.sheets.map(sheet => sheet.name));
+        const wb = Workbook.create();
+        const report = [];
+        for (const spec of args.sheets) {
+            const ws = await buildSheet(wb, spec, config, report);
+            applyLayout(ws, spec, report);
+        }
+        const recalculate = args.recalculate ?? true;
+        let formulaNote = "formulas not evaluated (recalculate: false)";
+        if (recalculate) {
+            try {
+                calculateFormulas(wb);
+                formulaNote = "formulas evaluated";
+            }
+            catch (cause) {
+                // A bad formula must not lose the whole document — save it and say so,
+                // which leaves the model a file it can inspect and repair.
+                formulaNote = `formula evaluation failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+            }
+        }
+        // Written to a sibling and renamed, so a failure part-way through cannot
+        // leave a truncated workbook where a valid one used to be. `ensureParent`
+        // is handled by the atomic writer, since a model writes "out/report.xlsx"
+        // without checking that "out" exists.
+        await writeWithPolicy(target, args.overwrite === true, temporary => Workbook.writeFile(wb, temporary));
+        return textResult(config, [
+            `Wrote **${outputDisplay(args.path)}** (${args.sheets.length} sheet(s)): ${args.sheets.map(sheet => JSON.stringify(sheet.name)).join(", ")}`,
+            `- ${formulaNote}`,
+            ...report,
+            "",
+            "Read the returned @output path with sheet_read to verify before reporting success."
+        ].join("\n"));
+    }
+});
+/** Create one worksheet and fill it from CSV and/or literal data. */
+async function buildSheet(wb, spec, config, report) {
+    let ws;
+    if (spec.fromCsv !== undefined) {
+        const source = await resolveInRoot(config, spec.fromCsv, { mustExist: true });
+        // readCsvFile appends a new sheet named after the file, so rename it to the
+        // requested name afterwards rather than creating a second, empty sheet.
+        ws = await readCsvFile(wb, source, spec.csvDelimiter === undefined ? undefined : { delimiter: spec.csvDelimiter });
+        Worksheet.setModel(ws, { ...Worksheet.getModel(ws), name: spec.name });
+        report.push(`- sheet ${JSON.stringify(spec.name)}: loaded ${Worksheet.actualRowCount(ws)} row(s) from ${spec.fromCsv} server-side`);
+    }
+    else {
+        ws = Workbook.addWorksheet(wb, spec.name);
+    }
+    if (spec.generate !== undefined) {
+        report.push(`- sheet ${JSON.stringify(spec.name)}: ${writeGenerated(ws, spec.generate)}`);
+    }
+    if (spec.rows !== undefined && spec.rows.length > 0) {
+        // addAoa intentionally skips nulls, which is useful for sparse imports but
+        // violates this schema's "null writes a blank" contract when rows overlay
+        // fromCsv/generated data. Write the matrix explicitly so null clears the
+        // previous value.
+        for (const [rowOffset, row] of spec.rows.entries()) {
+            for (const [columnOffset, value] of row.entries()) {
+                Cell.setValue(ws, rowOffset + 1, columnOffset + 1, value);
+            }
+        }
+    }
+    for (const [address, value] of Object.entries(spec.cells ?? {})) {
+        Cell.setValue(ws, normalizeAddress(address), value);
+    }
+    for (const [address, formula] of Object.entries(spec.formulas ?? {})) {
+        // Strip the leading "=" — the core stores formula text without it, and
+        // leaving it in makes every function resolve to #NAME?.
+        Cell.setValue(ws, normalizeAddress(address), { formula: normalizeFormula(formula) });
+    }
+    return ws;
+}
+/** Apply widths, freeze panes, merges and styles. */
+function applyLayout(ws, spec, report) {
+    if (spec.columnWidths !== undefined && spec.columnWidths.length > 0) {
+        Worksheet.setColumns(ws, spec.columnWidths.map(width => ({ width })));
+    }
+    if (spec.freezeRows !== undefined && spec.freezeRows > 0) {
+        ws.views = [{ state: "frozen", ySplit: spec.freezeRows }];
+    }
+    for (const range of spec.merges ?? []) {
+        try {
+            Worksheet.merge(ws, range);
+        }
+        catch (cause) {
+            throw toolError.invalidInput(`could not merge ${JSON.stringify(range)} on sheet ${JSON.stringify(spec.name)}`, "Merges must not overlap each other.", { cause });
+        }
+    }
+    for (const entry of spec.styles ?? []) {
+        applyStyle(ws, entry.range, entry.style);
+    }
+    // Charts last, so a default anchor sees the sheet's final used area.
+    for (const chart of spec.charts ?? []) {
+        report.push(`- sheet ${JSON.stringify(spec.name)}: ${addChart(ws, chart)}`);
+    }
+}
+/**
+ * Cells one `styles` entry may touch.
+ *
+ * Styling is applied cell by cell, so an unbounded range like `A1:XFD1048576`
+ * would hang the server. A model that wants a whole-column look can restrict
+ * itself to the rows that actually hold data.
+ */
+const MAX_STYLED_CELLS = 100_000;
+/** Apply one style to every cell of a range. */
+function applyStyle(ws, range, style) {
+    const window = parseRange(range);
+    const cells = (window.bottom - window.top + 1) * (window.right - window.left + 1);
+    if (cells > MAX_STYLED_CELLS) {
+        throw toolError.tooLarge(`style range ${JSON.stringify(range)} covers ${cells} cells, over the ${MAX_STYLED_CELLS} limit`, "Style only the rows that hold data, e.g. the header row plus the populated range.");
+    }
+    for (let row = window.top; row <= window.bottom; row += 1) {
+        for (let column = window.left; column <= window.right; column += 1) {
+            if (style.bold !== undefined || style.italic !== undefined || style.fontColor !== undefined) {
+                Cell.setFont(ws, row, column, {
+                    ...(Cell.getFont(ws, row, column) ?? {}),
+                    ...(style.bold === undefined ? {} : { bold: style.bold }),
+                    ...(style.italic === undefined ? {} : { italic: style.italic }),
+                    ...(style.fontColor === undefined ? {} : { color: { argb: toArgb(style.fontColor) } })
+                });
+            }
+            if (style.fillColor !== undefined) {
+                Cell.setFill(ws, row, column, {
+                    type: "pattern",
+                    pattern: "solid",
+                    fgColor: { argb: toArgb(style.fillColor) }
+                });
+            }
+            if (style.numFmt !== undefined) {
+                Cell.setNumFmt(ws, row, column, style.numFmt);
+            }
+        }
+    }
+}
+function normalizeAddress(address) {
+    const upper = address.trim().toUpperCase();
+    if (!/^[A-Z]{1,3}[1-9][0-9]*$/.test(upper)) {
+        throw toolError.invalidInput(`${JSON.stringify(address)} is not a cell address`, 'Use A1 notation for a single cell, e.g. "B10".');
+    }
+    return upper;
+}
+/**
+ * Characters Excel forbids in a sheet name.
+ *
+ * Writing one produces a package Excel refuses to open, which the model would
+ * see as a mysterious "corrupt file" much later — so reject it at the source.
+ */
+const ILLEGAL_SHEET_NAME = /[[\]:*?/\\]/;
+function assertLegalSheetName(name) {
+    if (ILLEGAL_SHEET_NAME.test(name)) {
+        throw toolError.invalidInput(`sheet name ${JSON.stringify(name)} contains a character Excel forbids`, "Sheet names may not contain any of : \\ / ? * [ ]");
+    }
+    if (name.startsWith("'") || name.endsWith("'")) {
+        throw toolError.invalidInput(`sheet name ${JSON.stringify(name)} may not start or end with an apostrophe`);
+    }
+}
+function assertUniqueNames(names) {
+    const seen = new Set();
+    for (const name of names) {
+        const key = name.toLowerCase();
+        if (seen.has(key)) {
+            throw toolError.invalidInput(`duplicate sheet name ${JSON.stringify(name)}`, "Excel sheet names must be unique, ignoring case.");
+        }
+        seen.add(key);
+    }
+}
+//# sourceMappingURL=sheet-write.js.map

package/dist/tools/sheet-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheet-write.js","sourceRoot":"","sources":["../../src/tools/sheet-write.ts"],"names":[],"mappings":"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"}

package/dist/tools/spreadsheet.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared spreadsheet helpers.
+ *
+ * Three concerns that every spreadsheet tool needs and must not re-derive:
+ * grid geometry, formula normalization, and rendering a grid as a table a model
+ * can address by cell reference.
+ */
+import { Workbook } from "documonster/excel";
+/** A workbook handle, as the public API hands it back. */
+export type WorkbookHandle = ReturnType<typeof Workbook.create>;
+/** A worksheet handle. */
+export type SheetHandle = ReturnType<typeof Workbook.addWorksheet>;
+/** 1-based inclusive grid window, matching `Worksheet.dimensions`. */
+export interface GridWindow {
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+/** Excel worksheet limits (ECMA-376 / modern Excel). */
+export declare const MAX_EXCEL_ROWS = 1048576;
+export declare const MAX_EXCEL_COLUMNS = 16384;
+/**
+ * Read a worksheet's name.
+ *
+ * The handle has no public `name` property — `ws.name` is `undefined` — so the
+ * model record is the only public route. Verified empirically; do not "simplify"
+ * this to `ws.name`.
+ */
+export declare function sheetName(ws: SheetHandle): string;
+/** Every worksheet name in workbook order. */
+export declare function sheetNames(wb: WorkbookHandle): string[];
+/**
+ * Resolve a sheet by name or 1-based index, failing with a list of what does
+ * exist — a model that picked the wrong name can then correct itself in one
+ * step instead of guessing again.
+ */
+export declare function requireSheet(wb: WorkbookHandle, sheet: string | number | undefined): SheetHandle;
+/**
+ * Parse an A1 range into a 1-based window.
+ *
+ * `Address.decodeRange` returns 0-based `{ s, e }`; `Worksheet.dimensions`
+ * returns 1-based `{ top, left, bottom, right }`. Mixing the two is the easiest
+ * off-by-one in this package, so the conversion happens exactly here.
+ */
+export declare function parseRange(range: string): GridWindow;
+/**
+ * The used area of a sheet, as a 1-based window. Empty sheets yield `undefined`.
+ *
+ * An empty sheet reports `{ top: 0, left: 0, bottom: 0, right: 0 }` — verified
+ * empirically, both freshly created and after a file round-trip. That satisfies
+ * `bottom >= top`, so checking only for an inverted rectangle lets zeroes through
+ * and the first `columnLetter(0)` then throws `ColumnOutOfBoundsError`. Hence the
+ * explicit `>= 1` checks.
+ */
+export declare function usedWindow(ws: SheetHandle): GridWindow | undefined;
+/**
+ * Strip a leading `=` from a formula.
+ *
+ * Essential, not cosmetic: the core stores formula text WITHOUT the `=`, and
+ * passing `"=SUM(A1:A2)"` makes every function resolve to `#NAME?` — including
+ * plain arithmetic, so the failure does not even look like a formula problem.
+ * Verified empirically. A model will always write the Excel-looking form with
+ * the `=`, so normalizing here is what makes the tools usable at all.
+ */
+export declare function normalizeFormula(formula: string): string;
+/** Column letter for a 1-based column index. */
+export declare function columnLetter(column: number): string;
+/** `"B7"` for 1-based row/column. */
+export declare function cellRef(row: number, column: number): string;
+/** How a cell should be rendered into the output table. */
+export type CellMode = "values" | "formulas" | "both";
+/**
+ * Render one cell as table text.
+ *
+ * Uses `Cell.getDisplayText`, which applies the cell's number format — so a
+ * currency cell reads `1,234.50` rather than `1234.5`, matching what the user
+ * sees in Excel and what they will quote back to the model.
+ */
+export declare function renderCell(ws: SheetHandle, row: number, column: number, mode: CellMode): string;
+/**
+ * Render a grid window as a Markdown table with spreadsheet coordinates.
+ *
+ * The column-letter header row and row-number first column are the point: they
+ * let the model answer "which cell is that" and reference `D7` in its next call.
+ * A bare table without them forces it to count columns, which it gets wrong.
+ */
+export declare function renderGrid(ws: SheetHandle, window: GridWindow, mode: CellMode): string;
+/** Inclusive integer range as an array. */
+export declare function rangeOf(from: number, to: number): number[];
+/** `"A1:C10"` for a window. */
+export declare function describeWindow(window: GridWindow): string;
+/**
+ * Convert a hex colour to the ARGB string Excel styles use.
+ *
+ * Accepts `RGB` or `AARRGGBB`, with or without a leading `#`, because a model
+ * writes all three.
+ */
+export declare function toArgb(color: string): string;
+//# sourceMappingURL=spreadsheet.d.ts.map

package/dist/tools/spreadsheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spreadsheet.d.ts","sourceRoot":"","sources":["../../src/tools/spreadsheet.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAiB,QAAQ,EAAa,MAAM,mBAAmB,CAAC;AAIvE,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEhE,0BAA0B;AAC1B,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,YAAY,CAAC,CAAC;AAEnE,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wDAAwD;AACxD,eAAO,MAAM,cAAc,UAAY,CAAC;AACxC,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAEjD;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,EAAE,EAAE,cAAc,GAAG,MAAM,EAAE,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CA8BhG;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAyCpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,CAgBlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,qCAAqC;AACrC,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAc/F;AAYD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAatF;AAED,2CAA2C;AAC3C,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAM1D;AAED,+BAA+B;AAC/B,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY5C"}

package/dist/tools/spreadsheet.js

@@ -0,0 +1,210 @@
+/**
+ * Shared spreadsheet helpers.
+ *
+ * Three concerns that every spreadsheet tool needs and must not re-derive:
+ * grid geometry, formula normalization, and rendering a grid as a table a model
+ * can address by cell reference.
+ */
+import { Address, Cell, Workbook, Worksheet } from "documonster/excel";
+import { toolError } from "../errors.js";
+/** Excel worksheet limits (ECMA-376 / modern Excel). */
+export const MAX_EXCEL_ROWS = 1_048_576;
+export const MAX_EXCEL_COLUMNS = 16_384; // XFD
+/**
+ * Read a worksheet's name.
+ *
+ * The handle has no public `name` property — `ws.name` is `undefined` — so the
+ * model record is the only public route. Verified empirically; do not "simplify"
+ * this to `ws.name`.
+ */
+export function sheetName(ws) {
+    return Worksheet.getModel(ws).name;
+}
+/** Every worksheet name in workbook order. */
+export function sheetNames(wb) {
+    return Workbook.getWorksheets(wb).map(sheetName);
+}
+/**
+ * Resolve a sheet by name or 1-based index, failing with a list of what does
+ * exist — a model that picked the wrong name can then correct itself in one
+ * step instead of guessing again.
+ */
+export function requireSheet(wb, sheet) {
+    const names = sheetNames(wb);
+    if (sheet === undefined) {
+        const first = Workbook.getWorksheets(wb)[0];
+        if (first === undefined) {
+            throw toolError.invalidInput("this workbook has no worksheets");
+        }
+        return first;
+    }
+    if (typeof sheet === "number") {
+        const found = Workbook.getWorksheets(wb)[sheet - 1];
+        if (found === undefined) {
+            throw toolError.invalidInput(`sheet index ${sheet} is out of range (workbook has ${names.length})`, `Available sheets: ${names.map(name => JSON.stringify(name)).join(", ")}`);
+        }
+        return found;
+    }
+    const found = Workbook.getWorksheet(wb, sheet);
+    if (found === undefined) {
+        throw toolError.invalidInput(`no sheet named ${JSON.stringify(sheet)}`, `Available sheets: ${names.map(name => JSON.stringify(name)).join(", ")}`);
+    }
+    return found;
+}
+/**
+ * Parse an A1 range into a 1-based window.
+ *
+ * `Address.decodeRange` returns 0-based `{ s, e }`; `Worksheet.dimensions`
+ * returns 1-based `{ top, left, bottom, right }`. Mixing the two is the easiest
+ * off-by-one in this package, so the conversion happens exactly here.
+ */
+export function parseRange(range) {
+    const trimmed = range.trim();
+    if (trimmed.length === 0) {
+        throw toolError.invalidInput("range must not be empty");
+    }
+    let decoded;
+    try {
+        decoded = Address.decodeRange(trimmed.toUpperCase());
+    }
+    catch (cause) {
+        throw toolError.invalidInput(`could not parse range ${JSON.stringify(range)}`, 'Use A1 notation, e.g. "B2:D10" or "A1".', { cause });
+    }
+    const window = {
+        top: decoded.s.r + 1,
+        left: decoded.s.c + 1,
+        bottom: decoded.e.r + 1,
+        right: decoded.e.c + 1
+    };
+    if (!Number.isFinite(window.top) ||
+        !Number.isFinite(window.left) ||
+        window.top < 1 ||
+        window.left < 1 ||
+        window.bottom < window.top ||
+        window.right < window.left ||
+        window.bottom > MAX_EXCEL_ROWS ||
+        window.right > MAX_EXCEL_COLUMNS) {
+        throw toolError.invalidInput(`range ${JSON.stringify(range)} is not a valid rectangle`, 'Use A1 notation with the top-left cell first, within A1:XFD1048576, e.g. "B2:D10".');
+    }
+    return window;
+}
+/**
+ * The used area of a sheet, as a 1-based window. Empty sheets yield `undefined`.
+ *
+ * An empty sheet reports `{ top: 0, left: 0, bottom: 0, right: 0 }` — verified
+ * empirically, both freshly created and after a file round-trip. That satisfies
+ * `bottom >= top`, so checking only for an inverted rectangle lets zeroes through
+ * and the first `columnLetter(0)` then throws `ColumnOutOfBoundsError`. Hence the
+ * explicit `>= 1` checks.
+ */
+export function usedWindow(ws) {
+    const dimensions = Worksheet.dimensions(ws);
+    if (dimensions.top < 1 ||
+        dimensions.left < 1 ||
+        dimensions.bottom < dimensions.top ||
+        dimensions.right < dimensions.left) {
+        return undefined;
+    }
+    return {
+        top: dimensions.top,
+        left: dimensions.left,
+        bottom: dimensions.bottom,
+        right: dimensions.right
+    };
+}
+/**
+ * Strip a leading `=` from a formula.
+ *
+ * Essential, not cosmetic: the core stores formula text WITHOUT the `=`, and
+ * passing `"=SUM(A1:A2)"` makes every function resolve to `#NAME?` — including
+ * plain arithmetic, so the failure does not even look like a formula problem.
+ * Verified empirically. A model will always write the Excel-looking form with
+ * the `=`, so normalizing here is what makes the tools usable at all.
+ */
+export function normalizeFormula(formula) {
+    const trimmed = formula.trim();
+    return trimmed.startsWith("=") ? trimmed.slice(1).trim() : trimmed;
+}
+/** Column letter for a 1-based column index. */
+export function columnLetter(column) {
+    return Address.encodeCol(column - 1);
+}
+/** `"B7"` for 1-based row/column. */
+export function cellRef(row, column) {
+    return Address.encodeCell({ r: row - 1, c: column - 1 });
+}
+/**
+ * Render one cell as table text.
+ *
+ * Uses `Cell.getDisplayText`, which applies the cell's number format — so a
+ * currency cell reads `1,234.50` rather than `1234.5`, matching what the user
+ * sees in Excel and what they will quote back to the model.
+ */
+export function renderCell(ws, row, column, mode) {
+    const formula = Cell.getFormula(ws, row, column);
+    if (mode === "formulas") {
+        return formula === undefined
+            ? escapeCell(Cell.getDisplayText(ws, row, column))
+            : escapeCell(`=${formula}`);
+    }
+    const display = escapeCell(Cell.getDisplayText(ws, row, column));
+    if (mode === "both" && formula !== undefined) {
+        return `${display} \`=${escapeCell(formula)}\``;
+    }
+    return display;
+}
+/**
+ * Escape a value for a Markdown table cell.
+ *
+ * A raw `|` would silently split one cell into two and shift every subsequent
+ * column, which the model has no way to detect.
+ */
+function escapeCell(text) {
+    return text.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+/**
+ * Render a grid window as a Markdown table with spreadsheet coordinates.
+ *
+ * The column-letter header row and row-number first column are the point: they
+ * let the model answer "which cell is that" and reference `D7` in its next call.
+ * A bare table without them forces it to count columns, which it gets wrong.
+ */
+export function renderGrid(ws, window, mode) {
+    const header = ["", ...rangeOf(window.left, window.right).map(columnLetter)];
+    const divider = header.map(() => "---");
+    const lines = [`| ${header.join(" | ")} |`, `| ${divider.join(" | ")} |`];
+    for (const row of rangeOf(window.top, window.bottom)) {
+        const cells = rangeOf(window.left, window.right).map(column => renderCell(ws, row, column, mode));
+        lines.push(`| ${[String(row), ...cells].join(" | ")} |`);
+    }
+    return lines.join("\n");
+}
+/** Inclusive integer range as an array. */
+export function rangeOf(from, to) {
+    const out = [];
+    for (let value = from; value <= to; value += 1) {
+        out.push(value);
+    }
+    return out;
+}
+/** `"A1:C10"` for a window. */
+export function describeWindow(window) {
+    return `${cellRef(window.top, window.left)}:${cellRef(window.bottom, window.right)}`;
+}
+/**
+ * Convert a hex colour to the ARGB string Excel styles use.
+ *
+ * Accepts `RGB` or `AARRGGBB`, with or without a leading `#`, because a model
+ * writes all three.
+ */
+export function toArgb(color) {
+    const hex = color.replace(/^#/, "").toUpperCase();
+    if (/^[0-9A-F]{8}$/.test(hex)) {
+        return hex;
+    }
+    if (/^[0-9A-F]{6}$/.test(hex)) {
+        return `FF${hex}`;
+    }
+    throw toolError.invalidInput(`${JSON.stringify(color)} is not a hex colour`, 'Use RRGGBB or AARRGGBB, e.g. "C00000".');
+}
+//# sourceMappingURL=spreadsheet.js.map

package/dist/tools/spreadsheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spreadsheet.js","sourceRoot":"","sources":["../../src/tools/spreadsheet.ts"],"names":[],"mappings":"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"}

package/dist/tools/template.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `template_inspect` and `template_fill` — Word templating.
+ *
+ * The best-shaped pair of tools in this server, because the model's job is
+ * reduced to supplying data:
+ *
+ *   template_inspect  →  "this template wants client.name, items[], signature"
+ *   template_fill     →  here is that data as JSON
+ *
+ * `listTemplateTags` is effectively a self-describing schema, so nothing about
+ * the document's internals has to enter the model's context, and the styling,
+ * fonts, headers and numbering are whatever the template author set — the model
+ * cannot break them. Compared with generating a document from scratch, the
+ * surface for error is an order of magnitude smaller.
+ */
+export declare const templateInspectTool: import("./types.js").AnyToolDefinition;
+export declare const templateFillTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=template.d.ts.map

package/dist/tools/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/tools/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH,eAAO,MAAM,mBAAmB,wCAkE9B,CAAC;AAEH,eAAO,MAAM,gBAAgB,wCA6G3B,CAAC"}