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

package/dist/tools/formula-evaluate.js

@@ -0,0 +1,192 @@
+/**
+ * `formula_evaluate` — run a spreadsheet formula against a supplied cell context.
+ *
+ * The most distinctive tool here. A model asked "is this XLOOKUP right?" can
+ * only answer from memory of Excel semantics, and it is often confidently wrong
+ * about match modes, error propagation and date serials. This turns the
+ * question into an execution: build a throwaway workbook, populate the context,
+ * evaluate with the real engine (450-odd functions, spill support), read back
+ * what Excel would actually show.
+ *
+ * Touches no files, so it is safe under --readonly.
+ */
+import { Address, Cell, Workbook } from "documonster/excel";
+import { calculateFormulas } from "documonster/excel/formula";
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { textResult } from "./result.js";
+import { MAX_EXCEL_COLUMNS, MAX_EXCEL_ROWS, normalizeFormula, renderCell } from "./spreadsheet.js";
+import { defineTool } from "./types.js";
+/** Default formula location, clear of typical context but with room to spill. */
+const DEFAULT_PROBE = "Z1";
+/** Cap on spilled cells reported back. */
+const MAX_SPILL_REPORTED = 200;
+/** Furthest a spill is probed in either direction. */
+const MAX_SPILL_SPAN = 500;
+export const formulaEvaluateTool = defineTool({
+    name: "formula_evaluate",
+    group: "excel",
+    title: "Evaluate a spreadsheet formula",
+    description: "Evaluate an Excel formula against cell values you supply, using the real calculation engine (450+ functions including XLOOKUP, LET, LAMBDA, dynamic arrays, financial and statistical functions). Use it to check a formula's result or semantics instead of reasoning about Excel from memory. Reads and writes no files.",
+    inputSchema: {
+        formula: z
+            .string()
+            .min(1)
+            .describe('The formula, with or without a leading "=", e.g. "=SUM(A1:A3)*1.08".'),
+        context: z
+            .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+            .optional()
+            .describe('Cell values the formula references, by address: { "A1": 10, "A2": 20, "B1": "widget" }. Omit for self-contained formulas.'),
+        contextFormulas: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe("Context cells that are themselves formulas, by address — for testing dependency chains."),
+        cell: z
+            .string()
+            .optional()
+            .describe('Cell where the formula is evaluated. Defaults to "Z1". Set this when testing ROW(), COLUMN() or relative references. It must not also appear in context.')
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    mutates: false,
+    handler: async (args, context) => {
+        const wb = Workbook.create();
+        const ws = Workbook.addWorksheet(wb, "Sheet1");
+        for (const [address, value] of Object.entries(args.context ?? {})) {
+            Cell.setValue(ws, requireAddress(address, "context"), value);
+        }
+        for (const [address, formula] of Object.entries(args.contextFormulas ?? {})) {
+            Cell.setValue(ws, requireAddress(address, "contextFormulas"), {
+                formula: normalizeFormula(formula)
+            });
+        }
+        const probe = requireAddress(args.cell ?? DEFAULT_PROBE, "cell");
+        if (probe in (args.context ?? {}) || probe in (args.contextFormulas ?? {})) {
+            throw toolError.invalidInput(`probe cell ${probe} is also present in the context`, "Choose a different `cell`; the formula result would otherwise overwrite that context value.");
+        }
+        const probeAddress = Address.decodeCell(probe);
+        Cell.setValue(ws, probe, { formula: normalizeFormula(args.formula) });
+        try {
+            calculateFormulas(wb);
+        }
+        catch (cause) {
+            throw toolError.invalidInput(`the formula could not be evaluated: ${cause instanceof Error ? cause.message : String(cause)}`, "Check the syntax — argument separators are commas, and sheet-qualified references need a sheet that exists in `context`.", { cause });
+        }
+        const lines = [
+            "# formula_evaluate",
+            "",
+            `- formula: \`=${normalizeFormula(args.formula)}\``,
+            `- evaluated at: \`${probe}\``,
+            `- result: **${describeResult(ws, probe)}**`,
+            `- displayed as: \`${Cell.getDisplayText(ws, probe)}\``
+        ];
+        const spill = collectSpill(ws, probeAddress.r + 1, probeAddress.c + 1);
+        if (spill.length > 0) {
+            lines.push(`- this is a dynamic array: it spills over ${spill.length + 1} cells`, "", "Spilled values:", "", ...[
+                `| offset | value |`,
+                `| --- | --- |`,
+                `| 0 (anchor) | ${Cell.getDisplayText(ws, probe)} |`
+            ], ...spill.slice(0, MAX_SPILL_REPORTED).map(entry => `| ${entry.label} | ${entry.text} |`), ...(spill.length > MAX_SPILL_REPORTED
+                ? [`[${spill.length - MAX_SPILL_REPORTED} more spilled value(s) not listed]`]
+                : []));
+        }
+        const contextCells = Object.keys(args.context ?? {}).length + Object.keys(args.contextFormulas ?? {}).length;
+        if (contextCells > 0) {
+            lines.push("", `Evaluated with ${contextCells} context cell(s).`);
+            const derived = Object.keys(args.contextFormulas ?? {});
+            if (derived.length > 0) {
+                lines.push("", "Context formula results:", "", ...derived.map(address => {
+                    const upper = requireAddress(address, "contextFormulas");
+                    return `- \`${upper}\` = ${Cell.getDisplayText(ws, upper)}`;
+                }));
+            }
+        }
+        return textResult(context.config, lines.join("\n"));
+    }
+});
+/**
+ * Describe the evaluated result, naming an Excel error explicitly.
+ *
+ * `#SPILL!` / `#NAME?` / `#DIV/0!` are answers, not failures — the caller
+ * usually asked precisely to find out whether one occurs, so they are reported
+ * as results rather than raised as tool errors.
+ */
+function describeResult(ws, address) {
+    const value = Cell.getValue(ws, address);
+    if (value !== null && typeof value === "object" && "result" in value) {
+        const result = value.result;
+        if (result !== null &&
+            typeof result === "object" &&
+            result !== undefined &&
+            "error" in result) {
+            const code = result.error;
+            return `${String(code)} (an Excel error value, not a tool failure)`;
+        }
+        return formatScalar(result);
+    }
+    return formatScalar(value);
+}
+function formatScalar(value) {
+    if (value === null || value === undefined) {
+        return "(blank)";
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Find cells the probe spilled into.
+ *
+ * Grows the rectangle outward from the anchor rather than sweeping the used
+ * area: the used area also contains the caller's context cells, so a sweep
+ * would cost thousands of reads and could report unrelated values as spill.
+ * A spill is contiguous, so stopping at the first empty row and column is both
+ * cheaper and more accurate.
+ */
+function collectSpill(ws, anchorRow, anchorColumn) {
+    const width = measureRun(column => Cell.getValue(ws, anchorRow, anchorColumn + column), Math.min(MAX_SPILL_SPAN, MAX_EXCEL_COLUMNS - anchorColumn + 1));
+    const height = measureRun(row => Cell.getValue(ws, anchorRow + row, anchorColumn), Math.min(MAX_SPILL_SPAN, MAX_EXCEL_ROWS - anchorRow + 1));
+    const found = [];
+    for (let row = 0; row < height; row += 1) {
+        for (let column = 0; column < width; column += 1) {
+            if (row === 0 && column === 0) {
+                continue;
+            }
+            const value = Cell.getValue(ws, anchorRow + row, anchorColumn + column);
+            if (value === null || value === undefined) {
+                continue;
+            }
+            found.push({
+                label: `r+${row},c+${column}`,
+                text: renderCell(ws, anchorRow + row, anchorColumn + column, "values")
+            });
+        }
+    }
+    return found;
+}
+/** Length of the contiguous non-empty run starting at offset 0. */
+function measureRun(read, limit) {
+    let length = 0;
+    while (length < limit) {
+        const value = read(length);
+        if (value === null || value === undefined) {
+            break;
+        }
+        length += 1;
+    }
+    return Math.max(1, length);
+}
+function requireAddress(address, field) {
+    const upper = address.trim().toUpperCase();
+    if (!/^[A-Z]{1,3}[1-9][0-9]*$/.test(upper)) {
+        throw toolError.invalidInput(`${field} key ${JSON.stringify(address)} is not a cell address`, 'Use plain A1 notation, e.g. "B2".');
+    }
+    return upper;
+}
+//# sourceMappingURL=formula-evaluate.js.map

package/dist/tools/formula-evaluate.js.map

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

package/dist/tools/fs-helpers.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Filesystem helpers shared by the write tools.
+ *
+ * Centralised because every tool that edits a user's file needs the same three
+ * behaviours, and six divergent copies is six chances to get one of them wrong:
+ * do not clobber silently, do not lose the original, and never leave a
+ * half-written file behind.
+ */
+import type { WriteTarget } from "../sandbox.js";
+/** True when a path exists. A missing file is not an error here. */
+export declare function exists(target: string): Promise<boolean>;
+/**
+ * Create a write target's parent directory.
+ *
+ * Needed because a model naturally writes `out/report.xlsx` without first
+ * checking that `out` exists, and none of the underlying writers create it.
+ */
+export declare function ensureParent(target: string): Promise<void>;
+/** Byte size of a file. */
+export declare function sizeOf(target: string): Promise<number>;
+/** Minimal optimistic-concurrency token for a file being edited. */
+export interface FileFingerprint {
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly ino: number;
+}
+/** Capture the version a tool is about to read and edit. */
+export declare function fingerprint(target: string): Promise<FileFingerprint>;
+/**
+ * Refuse to overwrite a file another process changed while this tool worked.
+ *
+ * This closes the common lost-update race: read A, somebody saves B, then this
+ * tool writes an output derived from A over B. Node cannot bind every later
+ * operation to an `openat` directory descriptor cross-platform, but a version
+ * check immediately before backup/install prevents accidental concurrent edits
+ * from being silently discarded.
+ */
+export declare function assertUnchanged(target: string, expected: FileFingerprint): Promise<void>;
+/**
+ * Write bytes to `target` with atomic POSIX replacement / Windows rollback.
+ *
+ * The naive `writeFile(target, bytes)` truncates the destination before the new
+ * content is complete, so a serialization error, a full disk or a killed
+ * process destroys the user's file — which is precisely the outcome the
+ * "atomic" claim in the edit tools is supposed to rule out. Writing a sibling
+ * temporary file and renaming it makes the replacement a single filesystem
+ * operation on POSIX: either the old file or the new one, never a truncated
+ * hybrid. Windows uses the rollback-safe two-rename path described below.
+ *
+ * The temporary file is a sibling rather than in the OS temp directory so the
+ * rename stays within one filesystem; `rename` across devices fails with
+ * `EXDEV`.
+ */
+export declare function writeFileAtomic(target: string, bytes: Uint8Array | string): Promise<void>;
+/**
+ * Run `produce` to build a file's new bytes, then replace `target` atomically.
+ *
+ * Used where a library insists on writing to a path itself: it writes to the
+ * temporary sibling and the rename happens only after it returns successfully.
+ */
+export declare function replaceAtomically(target: string, produce: (temporaryPath: string) => Promise<void>): Promise<void>;
+/**
+ * Install a complete file only when `target` does not already exist.
+ *
+ * A pre-check followed by rename has a race: another process can create the
+ * target in between and POSIX rename will silently replace it. `link` is an
+ * atomic no-clobber operation on the same filesystem: it either installs the
+ * already-complete inode or fails with EEXIST.
+ */
+export declare function writeFileNoClobber(target: string, produce: (temporaryPath: string) => Promise<void>): Promise<void>;
+/** Select atomic replace or atomic no-clobber from a public overwrite flag. */
+export declare function writeWithPolicy(target: string, overwrite: boolean, produce: (temporaryPath: string) => Promise<void>): Promise<void>;
+/** Byte/string counterpart of {@link writeWithPolicy}. */
+export declare function writeBytesWithPolicy(target: string, overwrite: boolean, bytes: Uint8Array | string): Promise<void>;
+/**
+ * Copy the original aside before an in-place edit.
+ *
+ * Never overwrites an existing backup. A second edit would otherwise replace the
+ * only copy of the user's original with the output of the first edit, which
+ * defeats the purpose — the `.bak` a user reaches for is the pristine one, not
+ * the previous intermediate state. Later backups get a numbered suffix.
+ *
+ * @returns The path written, or `undefined` when the source does not exist.
+ */
+export declare function backupOnce(target: WriteTarget): Promise<string | undefined>;
+/** Describe a backup for a tool's report, relative to the caller's own path. */
+export declare function describeBackup(display: string, backupPath: string | undefined): string[];
+/**
+ * True when two resolved paths denote the same file.
+ *
+ * `out: "./report.xlsx"` resolves to the same file as `path: "report.xlsx"`, and
+ * a tool that decides "in place or not" by asking whether `out` was supplied
+ * would then skip the backup while still overwriting the input.
+ */
+export declare function isSameFile(a: string, b: string): boolean;
+/**
+ * Refuse an input document larger than the configured ceiling.
+ *
+ * `doc_inspect` tells the model that an oversized file "will be rejected", so
+ * every tool that opens a document has to honour that — otherwise the limit is
+ * advice, and a single huge file can exhaust the server's memory.
+ */
+export declare function assertReadableSize(config: {
+    readonly maxFileSize: number;
+}, target: string, display: string): Promise<number>;
+//# sourceMappingURL=fs-helpers.d.ts.map

package/dist/tools/fs-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-helpers.d.ts","sourceRoot":"","sources":["../../src/tools/fs-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,oEAAoE;AACpE,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7D;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED,2BAA2B;AAC3B,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE5D;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,4DAA4D;AAC5D,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAG1E;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CASf;AAED,+EAA+E;AAC/E,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,0DAA0D;AAC1D,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,OAAO,EAClB,KAAK,EAAE,UAAU,GAAG,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC,CAEf;AAgDD;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAUjF;AAeD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAOxF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/dist/tools/fs-helpers.js

@@ -0,0 +1,257 @@
+/**
+ * Filesystem helpers shared by the write tools.
+ *
+ * Centralised because every tool that edits a user's file needs the same three
+ * behaviours, and six divergent copies is six chances to get one of them wrong:
+ * do not clobber silently, do not lose the original, and never leave a
+ * half-written file behind.
+ */
+import { constants } from "node:fs";
+import { chmod, copyFile, link, mkdir, mkdtemp, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { McpToolError } from "../errors.js";
+/** True when a path exists. A missing file is not an error here. */
+export async function exists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create a write target's parent directory.
+ *
+ * Needed because a model naturally writes `out/report.xlsx` without first
+ * checking that `out` exists, and none of the underlying writers create it.
+ */
+export async function ensureParent(target) {
+    await mkdir(path.dirname(target), { recursive: true });
+}
+/** Byte size of a file. */
+export async function sizeOf(target) {
+    return (await stat(target)).size;
+}
+/** Capture the version a tool is about to read and edit. */
+export async function fingerprint(target) {
+    const current = await stat(target);
+    return { size: current.size, mtimeMs: current.mtimeMs, ino: current.ino };
+}
+/**
+ * Refuse to overwrite a file another process changed while this tool worked.
+ *
+ * This closes the common lost-update race: read A, somebody saves B, then this
+ * tool writes an output derived from A over B. Node cannot bind every later
+ * operation to an `openat` directory descriptor cross-platform, but a version
+ * check immediately before backup/install prevents accidental concurrent edits
+ * from being silently discarded.
+ */
+export async function assertUnchanged(target, expected) {
+    const current = await fingerprint(target);
+    if (current.size !== expected.size ||
+        current.mtimeMs !== expected.mtimeMs ||
+        current.ino !== expected.ino) {
+        throw new McpToolError("invalid_input", "the input file changed while this operation was running", {
+            hint: "Nothing was written. Read the latest file and retry so another process's changes are not lost."
+        });
+    }
+}
+/**
+ * Write bytes to `target` with atomic POSIX replacement / Windows rollback.
+ *
+ * The naive `writeFile(target, bytes)` truncates the destination before the new
+ * content is complete, so a serialization error, a full disk or a killed
+ * process destroys the user's file — which is precisely the outcome the
+ * "atomic" claim in the edit tools is supposed to rule out. Writing a sibling
+ * temporary file and renaming it makes the replacement a single filesystem
+ * operation on POSIX: either the old file or the new one, never a truncated
+ * hybrid. Windows uses the rollback-safe two-rename path described below.
+ *
+ * The temporary file is a sibling rather than in the OS temp directory so the
+ * rename stays within one filesystem; `rename` across devices fails with
+ * `EXDEV`.
+ */
+export async function writeFileAtomic(target, bytes) {
+    const temporary = await createPrivateTemporary(target);
+    try {
+        await writeFile(temporary, bytes);
+        await preserveMode(target, temporary);
+        await replaceInstalledFile(temporary, target);
+    }
+    finally {
+        await rm(path.dirname(temporary), { recursive: true, force: true });
+    }
+}
+/**
+ * Run `produce` to build a file's new bytes, then replace `target` atomically.
+ *
+ * Used where a library insists on writing to a path itself: it writes to the
+ * temporary sibling and the rename happens only after it returns successfully.
+ */
+export async function replaceAtomically(target, produce) {
+    const temporary = await createPrivateTemporary(target);
+    try {
+        await produce(temporary);
+        await preserveMode(target, temporary);
+        await replaceInstalledFile(temporary, target);
+    }
+    finally {
+        await rm(path.dirname(temporary), { recursive: true, force: true });
+    }
+}
+/**
+ * Install a complete file only when `target` does not already exist.
+ *
+ * A pre-check followed by rename has a race: another process can create the
+ * target in between and POSIX rename will silently replace it. `link` is an
+ * atomic no-clobber operation on the same filesystem: it either installs the
+ * already-complete inode or fails with EEXIST.
+ */
+export async function writeFileNoClobber(target, produce) {
+    const temporary = await createPrivateTemporary(target);
+    try {
+        await produce(temporary);
+        await link(temporary, target);
+        await unlink(temporary);
+    }
+    finally {
+        await rm(path.dirname(temporary), { recursive: true, force: true });
+    }
+}
+/** Select atomic replace or atomic no-clobber from a public overwrite flag. */
+export async function writeWithPolicy(target, overwrite, produce) {
+    if (overwrite) {
+        await replaceAtomically(target, produce);
+    }
+    else {
+        try {
+            await writeFileNoClobber(target, produce);
+        }
+        catch (cause) {
+            if (cause.code === "EEXIST") {
+                throw new McpToolError("invalid_input", `${target} already exists`, {
+                    hint: "Pass overwrite: true to replace it, or choose a different path.",
+                    cause
+                });
+            }
+            throw cause;
+        }
+    }
+}
+/** Byte/string counterpart of {@link writeWithPolicy}. */
+export async function writeBytesWithPolicy(target, overwrite, bytes) {
+    await writeWithPolicy(target, overwrite, temporary => writeFile(temporary, bytes));
+}
+/** A random, private sibling temporary path on the target filesystem. */
+async function createPrivateTemporary(target) {
+    await ensureParent(target);
+    const directory = await mkdtemp(path.join(path.dirname(target), ".documonster-"));
+    // mkdtemp normally uses 0700; enforce it so a permissive umask or platform
+    // implementation cannot expose a document while it is being written.
+    await chmod(directory, 0o700);
+    return path.join(directory, path.basename(target));
+}
+/** Carry the original file's Unix permissions onto its replacement. */
+async function preserveMode(target, temporary) {
+    try {
+        const current = await stat(target);
+        await chmod(temporary, current.mode & 0o777);
+    }
+    catch (cause) {
+        if (cause.code !== "ENOENT") {
+            throw cause;
+        }
+    }
+}
+/**
+ * Replace an installed file.
+ *
+ * POSIX rename atomically replaces an existing file. Windows commonly refuses
+ * that operation, so use a rollback rename there: the target is never deleted,
+ * and a failure to install the new file restores the old one.
+ */
+async function replaceInstalledFile(temporary, target) {
+    if (process.platform !== "win32" || !(await exists(target))) {
+        await rename(temporary, target);
+        return;
+    }
+    const rollback = `${target}.rollback-${process.pid.toString(36)}-${Date.now().toString(36)}`;
+    await rename(target, rollback);
+    try {
+        await rename(temporary, target);
+        await rm(rollback, { force: true });
+    }
+    catch (cause) {
+        await rename(rollback, target).catch(() => undefined);
+        throw cause;
+    }
+}
+/**
+ * Copy the original aside before an in-place edit.
+ *
+ * Never overwrites an existing backup. A second edit would otherwise replace the
+ * only copy of the user's original with the output of the first edit, which
+ * defeats the purpose — the `.bak` a user reaches for is the pristine one, not
+ * the previous intermediate state. Later backups get a numbered suffix.
+ *
+ * @returns The path written, or `undefined` when the source does not exist.
+ */
+export async function backupOnce(target) {
+    if (!(await exists(target.path))) {
+        return undefined;
+    }
+    const chosen = await firstFreeBackupPath(target.backupPath);
+    // COPYFILE_EXCL: fail rather than follow or overwrite anything that appeared
+    // between the check above and this call.
+    await copyFile(target.path, chosen, constants.COPYFILE_EXCL);
+    return chosen;
+}
+async function firstFreeBackupPath(base) {
+    if (!(await exists(base))) {
+        return base;
+    }
+    for (let index = 2; index < 1000; index += 1) {
+        const candidate = `${base}.${index}`;
+        if (!(await exists(candidate))) {
+            return candidate;
+        }
+    }
+    throw new Error(`could not find a free backup filename beside ${base}`);
+}
+/** Describe a backup for a tool's report, relative to the caller's own path. */
+export function describeBackup(display, backupPath) {
+    if (backupPath === undefined) {
+        return [];
+    }
+    return [
+        `- original copied to ${display}${backupPath.endsWith(".bak") ? ".bak" : `.bak (${path.basename(backupPath)})`}`
+    ];
+}
+/**
+ * True when two resolved paths denote the same file.
+ *
+ * `out: "./report.xlsx"` resolves to the same file as `path: "report.xlsx"`, and
+ * a tool that decides "in place or not" by asking whether `out` was supplied
+ * would then skip the backup while still overwriting the input.
+ */
+export function isSameFile(a, b) {
+    return path.resolve(a) === path.resolve(b);
+}
+/**
+ * Refuse an input document larger than the configured ceiling.
+ *
+ * `doc_inspect` tells the model that an oversized file "will be rejected", so
+ * every tool that opens a document has to honour that — otherwise the limit is
+ * advice, and a single huge file can exhaust the server's memory.
+ */
+export async function assertReadableSize(config, target, display) {
+    const size = await sizeOf(target);
+    if (size > config.maxFileSize) {
+        throw new McpToolError("too_large", `${display} is ${size} bytes, over the ${config.maxFileSize} byte limit`, {
+            hint: "Ask the user to raise --max-file-size, or work with a smaller extract of the document."
+        });
+    }
+    return size;
+}
+//# sourceMappingURL=fs-helpers.js.map

package/dist/tools/fs-helpers.js.map

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