xlvane 1.1.0 → 1.2.0

package/README.md

@@ -58,7 +58,7 @@ xlvane help edit                          # usage and examples of one command
 - `--json` prints one JSON document per command with a documented schema ([docs/cli-json.md](https://github.com/DevXord/xlvane/blob/main/docs/cli-json.md)). Exit codes: 0 success, 1 a check found something (`diff`, `validate`), 2 usage error, 3 input or file error.
 - Colour (red errors, yellow warnings, green results, bold headings) is used only on a terminal and never carries information alone; `NO_COLOR` or `TERM=dumb` turn it off, `FORCE_COLOR=1` turns it on. Control characters from files, such as an escape character in a cell, are shown as `\x1b` and never reach the terminal.
 - Tables and summaries go to separate streams: `xlvane read report.xlsx > out.txt` writes only the table; the row count and warnings notes go to stderr.
-- `xlvane migrate` prepares a project for `@xlvane/compat`.
+- `xlvane migrate` prepares a project for `@xlvane/compat`, and `xlvane mcp` starts the MCP server from `@xlvane/mcp` (a separate package; [its README](https://github.com/DevXord/xlvane/blob/main/packages/mcp/README.md)).
 
 ## Reading a workbook
 
@@ -385,10 +385,10 @@ Limits can be changed per call, for example `readWorkbook(bytes, { limits: { max
 | `maxXmlDepth` | 128 | deeply nested XML |
 | `maxXmlAttributes` | 256 | elements with huge numbers of attributes |
 | `maxXmlNameLength` | 1 024 | huge element or attribute names |
-| `maxXmlTextLength` | 8 Mi characters | huge text nodes or attribute values |
+| `maxXmlTextLength` | 8 Mi characters | huge text nodes, attribute values, comments or processing instructions |
 | `maxXmlTreeElements` | 1 000 000 | huge workbook, styles or relationship parts (elements plus attributes) |
-| `maxCells` | 5 000 000 | workbooks too large to hold in memory (measured: about 180 bytes per numeric cell, Node.js 26) |
-| `maxSharedStringChars` | 512 Mi characters | many cells pointing at one huge shared string (a few MB that become many GB when values are copied) |
+| `maxCells` | 5 000 000 | workbooks too large to hold in memory (measured: about 180 bytes per numeric cell, Node.js 26); also bounds the output of `toCSV`, `readTable`, `toJSON` and `readTableStream` to `max(maxCells, 16 × cells read)` positions |
+| `maxSharedStringChars` | 512 Mi characters | many cells pointing at one huge shared string (a few MB that become many GB when values are copied); counted separately, the same for cells sharing one huge formula |
 
 ## Package size
 
@@ -403,6 +403,7 @@ Limits can be changed per call, for example `readWorkbook(bytes, { limits: { max
 
 ## Links
 
+- Website with the guide and an in-browser demo: [xlvane.github.io](https://xlvane.github.io)
 - Changes in each version: [CHANGELOG.md](https://github.com/DevXord/xlvane/blob/main/CHANGELOG.md)
 - Bugs and questions: [GitHub issues](https://github.com/DevXord/xlvane/issues)
 - Reporting a vulnerability: [SECURITY.md](https://github.com/DevXord/xlvane/blob/main/SECURITY.md)

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { Bt as suggest, En as XlvError, _ as isoDate, b as readWorkbook, g as inspect, ln as parseRange } from "./options-CwSp2pA4.js";
-import { a as appendRows, c as fromCSV, d as fromJSON, f as pickSheet, h as toJSON, l as inferValue, n as insertRows, o as editCells, p as readTable, s as diff, t as deleteRows, u as toCSV } from "./rows-DKwlr0rg.js";
-import { i as readInput } from "./node-files-B0iqSJIJ.js";
+import { On as XlvError, Vt as suggest, _ as isoDate, b as readWorkbook, dn as parseRange, g as inspect } from "./options-Ba1iWD-Z.js";
+import { a as appendRows, c as fromCSV, d as fromJSON, f as pickSheet, h as toJSON, l as inferValue, n as insertRows, o as editCells, p as readTable, s as diff, t as deleteRows, u as toCSV } from "./rows-IWKIxHt9.js";
+import { i as readInput } from "./node-files-CDb6TyZb.js";
 import { existsSync, readFileSync } from "node:fs";
-import { chmod, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, lstat, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import process from "node:process";
 import { createRequire } from "node:module";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -463,8 +463,15 @@ var Output = class {
 		this.color = color;
 		this.width = width;
 	}
+	/**
+	* Colour codes are written with {@link STYLE_MARK} in place of ESC, and an ESC already in the
+	* text (from a file) is escaped, so that the final filter ({@link terminalSafe}) can tell the
+	* CLI's own colour codes from the same bytes in a sheet name or cell (D-H01).
+	*/
 	style(format, text) {
-		return this.color && text !== "" ? nodeUtil.styleText(format, text, { validateStream: false }) : text;
+		if (!this.color || text === "") return text;
+		const safe = text.includes("\x1B") ? text.split("\x1B").join("\\x1b") : text;
+		return nodeUtil.styleText(format, safe, { validateStream: false }).split("\x1B").join(STYLE_MARK);
 	}
 	bold(text) {
 		return this.style("bold", text);
@@ -519,7 +526,8 @@ function oneLine(text) {
 * which includes the 8-bit CSI U+009B) written as `\x1b`, and bidirectional formatting characters
 * written as `\u202e`, so text from a file, such as a cell
 * holding `_x001B_]0;title_x0007_`, cannot move the cursor, change the window title or hide
-* output (docs/decisions.md D-R02). Used for all human-readable output; `--json` is unchanged.
+* output (docs/decisions.md D-R02). Used for all human-readable output; `--json` writes the same
+* characters as `\uXXXX` escapes instead (D-H01).
 */
 function escapeControls(text) {
 	return text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`).replace(BIDI, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
@@ -531,27 +539,40 @@ function escapeControls(text) {
 * `\u202e` in human-readable output, like other control characters (D-R08).
 */
 const BIDI = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
-/** The colour sequences `Output` writes (styleText: bold, dim, red, green, yellow, cyan and their resets). */
-const OWN_STYLES = /\u001b\[(?:1|2|22|31|32|33|36|39)m/y;
+/**
+* Stands for ESC in the colour codes `Output` writes until {@link terminalSafe} turns it back:
+* NUL and 16 random hexadecimal digits, new for each process, so text from a file cannot contain
+* it by chance or design. Before 1.1.1 the filter kept every ESC sequence that looked like one of
+* the CLI's colours, including ones from a sheet name (D-H01).
+*/
+const STYLE_MARK = `\u0000${Array.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8)), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+/** The colour sequences `Output` writes (styleText: bold, dim, red, green, yellow, cyan and their resets), after the mark. */
+const OWN_STYLE = /^\[(?:1|2|22|31|32|33|36|39)m/;
+const MARKED_STYLE = new RegExp(`${STYLE_MARK}\\[[0-9;]*m`, "g");
 /**
 * Final filter for human-readable output: escapes every control character (see
-* {@link escapeControls}) except line feeds, tabs and, when `keepStyles` is true, the exact
-* colour sequences that `Output` itself writes. Applied to everything the CLI prints for people.
+* {@link escapeControls}) except line feeds and tabs. When `keepStyles` is true, the colour codes
+* that `Output` wrote (marked with {@link STYLE_MARK}) are turned into ESC sequences; any ESC in
+* the text itself is escaped. Applied to everything the CLI prints for people.
 */
 function terminalSafe(text, keepStyles) {
+	if (!text.includes(STYLE_MARK)) return controlsSafe(text);
+	const parts = text.split(STYLE_MARK);
+	let result = controlsSafe(parts[0] ?? "");
+	for (const part of parts.slice(1)) {
+		const own = OWN_STYLE.exec(part)?.[0];
+		if (own === void 0) result += controlsSafe(part);
+		else result += (keepStyles ? `\u001b${own}` : "") + controlsSafe(part.slice(own.length));
+	}
+	return result;
+}
+/** Escapes the control characters of text (see {@link escapeControls}) except line feeds and tabs. */
+function controlsSafe(text) {
 	let result = "";
 	let start = 0;
 	for (let i = 0; i < text.length; i++) {
 		const code = text.charCodeAt(i);
 		if (!(code < 32 && code !== 10 && code !== 9 || code >= 127 && code <= 159 || code === 1564 || code === 8206 || code === 8207 || code >= 8234 && code <= 8238 || code >= 8294 && code <= 8297)) continue;
-		if (keepStyles && code === 27) {
-			OWN_STYLES.lastIndex = i;
-			const m = OWN_STYLES.exec(text);
-			if (m !== null) {
-				i += m[0].length - 1;
-				continue;
-			}
-		}
 		result += text.slice(start, i) + escapeControls(text[i]);
 		start = i + 1;
 	}
@@ -591,6 +612,7 @@ const segmenter = typeof Intl === "object" && typeof Intl.Segmenter === "functio
 */
 function displayWidth(text) {
 	if (text.includes("\x1B")) text = text.replace(/\u001b\[[0-9;]*m/g, "");
+	if (text.includes(STYLE_MARK)) text = text.replace(MARKED_STYLE, "");
 	let width = 0;
 	for (let i = 0; i < text.length; i++) {
 		const code = text.charCodeAt(i);
@@ -913,7 +935,7 @@ function welcome(out, version, commands) {
 		"",
 		`${out.bold("Commands:")} ${commands.map((c) => c.name).join(", ")}`,
 		`${out.bold("More:")}  xlvane help <command>   ·   Docs: ${DOCS_URL}`,
-		`For AI agents and scripts: add --json to any command (${DOCS_IN_PACKAGE}/cli-json.md)`,
+		`For AI agents and scripts: add --json to any command (${DOCS_IN_PACKAGE}/cli-json.md), or run "xlvane mcp"`,
 		""
 	].join("\n");
 }
@@ -1334,7 +1356,7 @@ const DEFAULT_LIMIT$1 = 50;
 function showCell(c) {
 	if (c === null) return "(empty)";
 	const value = c.value === null ? "" : typeof c.value === "string" ? JSON.stringify(c.value) : String(c.value);
-	return c.formula !== null ? `=${c.formula}${value !== "" ? ` (${value})` : ""}` : value === "" ? "(no value)" : value;
+	return c.formula !== null ? `=${escapeControls(c.formula)}${value !== "" ? ` (${value})` : ""}` : value === "" ? "(no value)" : value;
 }
 function kindLabel(out, kind) {
 	const text = kind.padEnd(7);
@@ -1393,14 +1415,14 @@ const diffCommand = {
 			result: r,
 			exitCode: r.equal ? 0 : 1,
 			render: (out) => {
-				if (r.equal) return `${out.green("No differences")} between ${a} and ${b}.`;
+				if (r.equal) return `${out.green("No differences")} between ${escapeControls(a)} and ${escapeControls(b)}.`;
 				const s = r.summary;
-				const lines = [`${out.bold(`${a} → ${b}`)}: ${plural(s.cellsChanged, "cell")} changed, ${String(s.cellsAdded)} added, ${String(s.cellsRemoved)} removed` + (s.sheetsAdded + s.sheetsRemoved > 0 ? `; sheets added: ${String(s.sheetsAdded)}, removed: ${String(s.sheetsRemoved)}` : "")];
-				for (const name of r.sheetsAdded) lines.push(`${out.green("added sheet")}   "${name}"`);
-				for (const name of r.sheetsRemoved) lines.push(`${out.red("removed sheet")} "${name}"`);
+				const lines = [`${out.bold(`${escapeControls(a)} → ${escapeControls(b)}`)}: ${plural(s.cellsChanged, "cell")} changed, ${String(s.cellsAdded)} added, ${String(s.cellsRemoved)} removed` + (s.sheetsAdded + s.sheetsRemoved > 0 ? `; sheets added: ${String(s.sheetsAdded)}, removed: ${String(s.sheetsRemoved)}` : "")];
+				for (const name of r.sheetsAdded) lines.push(`${out.green("added sheet")}   "${escapeControls(name)}"`);
+				for (const name of r.sheetsRemoved) lines.push(`${out.red("removed sheet")} "${escapeControls(name)}"`);
 				for (const sheet of r.sheets) {
 					if (sheet.cells.length === 0 && !sheet.state) continue;
-					lines.push("", out.bold(`Sheet "${sheet.name}"`));
+					lines.push("", out.bold(`Sheet "${escapeControls(sheet.name)}"`));
 					if (sheet.state) lines.push(`  ${out.yellow("changed")} visibility: ${sheet.state.before} → ${sheet.state.after}`);
 					for (const c of sheet.cells.slice(0, limit)) {
 						const style = c.kind === "changed" && showCell(c.before) === showCell(c.after) ? " (formatting)" : "";
@@ -1757,17 +1779,17 @@ const inspectCommand = {
 	}
 };
 function renderReport(out, file, r, verbose) {
-	const lines = [`${out.bold(file)}: ${r.format}, ${plural(r.sheetCount, "sheet")}, date system ${r.dateSystem}${r.conformance === "strict" ? ", Strict conformance" : ""}`];
+	const lines = [`${out.bold(escapeControls(file))}: ${r.format}, ${plural(r.sheetCount, "sheet")}, date system ${r.dateSystem}${r.conformance === "strict" ? ", Strict conformance" : ""}`];
 	if (r.hasMacros) lines.push("Contains macros (not run).");
 	if (r.externalLinkCount > 0) lines.push(`Links to ${plural(r.externalLinkCount, "other workbook")} (not followed).`);
 	const props = Object.entries(r.properties);
 	if (props.length > 0) {
 		const keyWidth = Math.max(...props.map(([k]) => k.length));
-		lines.push(out.bold("Properties:"), ...props.map(([k, v]) => `  ${k.padEnd(keyWidth)}  ${v}`));
+		lines.push(out.bold("Properties:"), ...props.map(([k, v]) => `  ${k.padEnd(keyWidth)}  ${escapeControls(String(v))}`));
 	}
 	const names = verbose ? r.definedNames : r.definedNames.filter((n) => !(n.hidden && n.name.startsWith("_xlnm.")));
 	if (names.length > 0) {
-		const shown = names.slice(0, 5).map((n) => `${n.name}${n.sheet === null ? "" : ` (sheet "${n.sheet}")`}${n.hidden ? " (hidden)" : ""} =${n.refersTo}`);
+		const shown = names.slice(0, 5).map((n) => `${escapeControls(n.name)}${n.sheet === null ? "" : ` (sheet "${escapeControls(n.sheet)}")`}${n.hidden ? " (hidden)" : ""} =${escapeControls(n.refersTo)}`);
 		const more = names.length > 5 || r.definedNamesTruncated ? `, … (${r.definedNamesTruncated ? "more than " : ""}${String(names.length)} in total; see --json)` : "";
 		lines.push(`${out.bold("Defined names:")} ${shown.join(", ")}${more}`);
 	}
@@ -1775,16 +1797,16 @@ function renderReport(out, file, r, verbose) {
 		lines.push("");
 		const state = s.state === "visible" ? "" : ` (${s.state})`;
 		if (s.kind !== "worksheet") {
-			lines.push(`${out.bold(`Sheet "${s.name}"`)}${state}: ${s.kind}, no cells`);
+			lines.push(`${out.bold(`Sheet "${escapeControls(s.name)}"`)}${state}: ${s.kind}, no cells`);
 			continue;
 		}
 		if (s.usedRange === null) {
-			lines.push(`${out.bold(`Sheet "${s.name}"`)}${state}: empty`);
+			lines.push(`${out.bold(`Sheet "${escapeControls(s.name)}"`)}${state}: empty`);
 			continue;
 		}
-		lines.push(`${out.bold(`Sheet "${s.name}"`)}${state}: ${s.usedRange}, ${plural(s.rowCount, "row")} × ${plural(s.columnCount, "column")}, ${plural(s.cellCount, "cell")}, ${plural(s.formulaCount, "formula")}`);
+		lines.push(`${out.bold(`Sheet "${escapeControls(s.name)}"`)}${state}: ${s.usedRange}, ${plural(s.rowCount, "row")} × ${plural(s.columnCount, "column")}, ${plural(s.cellCount, "cell")}, ${plural(s.formulaCount, "formula")}`);
 		lines.push(s.headerRow ? `  Header row: ${String(s.headerRow.row)} (${s.headerRow.confidence} confidence)` : "  Header row: none detected");
-		if (s.mergedRangeCount > 0) lines.push(`  Merged: ${s.mergedRanges.slice(0, 10).join(", ")}${s.mergedRangeCount > 10 ? `, … (${String(s.mergedRangeCount)} in total)` : ""}`);
+		if (s.mergedRangeCount > 0) lines.push(`  Merged: ${escapeControls(s.mergedRanges.slice(0, 10).join(", "))}${s.mergedRangeCount > 10 ? `, … (${String(s.mergedRangeCount)} in total)` : ""}`);
 		if (s.columns.length > 0) {
 			lines.push(out.table([
 				"Column",
@@ -1799,29 +1821,98 @@ function renderReport(out, file, r, verbose) {
 			]), "  "));
 			if (s.columnsTruncated) lines.push(`  … ${plural(s.columnCount - s.columns.length, "more column")}; use --max-columns ${String(s.columnCount)} to see them`);
 		}
-		if (s.formulas.length > 0) lines.push(`  Formulas: ${s.formulas.slice(0, 3).map((f) => `${f.cell} =${f.formula ?? "(shared)"}`).join(", ")}`);
+		if (s.formulas.length > 0) lines.push(`  Formulas: ${s.formulas.slice(0, 3).map((f) => `${f.cell} =${escapeControls(f.formula ?? "(shared)")}`).join(", ")}`);
 		if (s.richTextCellCount > 0) lines.push(`  Rich text: ${plural(s.richTextCellCount, "cell")} (${s.richTextCells.slice(0, 5).join(", ")}${s.richTextCellCount > 5 ? ", …" : ""})`);
 		if (s.styledColumns.length > 0) lines.push(`  Column styles: ${s.styledColumns.slice(0, 10).join(", ")}${s.styledColumns.length > 10 ? ", …" : ""}`);
 		if (s.hyperlinkCount > 0) {
-			const shown = s.hyperlinks.slice(0, 3).map((l) => `${l.ref} → ${l.target ?? ""}${l.location === null ? "" : `${l.target === null ? "" : "#"}${l.location}`}`);
+			const shown = s.hyperlinks.slice(0, 3).map((l) => `${l.ref} → ${escapeControls(l.target ?? "")}${l.location === null ? "" : `${l.target === null ? "" : "#"}${escapeControls(l.location)}`}`);
 			lines.push(`  Hyperlinks: ${plural(s.hyperlinkCount, "link")} (${shown.join(", ")}${s.hyperlinkCount > 3 ? ", …" : ""})`);
 		}
 		if (s.imageCount > 0) lines.push(`  Images: ${plural(s.imageCount, "picture")} (${s.images.slice(0, 5).map((i) => `${i.cell ?? "absolute"} ${i.format ?? "other"}`).join(", ")}${s.imageCount > 5 ? ", …" : ""})`);
 		if (s.noteCount > 0) lines.push(`  Notes: ${plural(s.noteCount, "note")} (${s.notes.slice(0, 5).join(", ")}${s.noteCount > 5 ? ", …" : ""})`);
-		if (s.tables.length > 0) lines.push(`  Tables: ${s.tables.slice(0, 5).map((t) => `${t.name} ${t.ref}`).join(", ")}${s.tables.length > 5 ? ", …" : ""}`);
+		if (s.tables.length > 0) lines.push(`  Tables: ${s.tables.slice(0, 5).map((table) => `${escapeControls(table.name)} ${escapeControls(table.ref)}`).join(", ")}${s.tables.length > 5 ? ", …" : ""}`);
 		if (s.dataValidationCount > 0 || s.conditionalFormatCount > 0) {
 			const parts = [s.dataValidationCount > 0 ? plural(s.dataValidationCount, "data validation") : null, s.conditionalFormatCount > 0 ? plural(s.conditionalFormatCount, "conditional format rule") : null];
 			lines.push(`  Rules: ${parts.filter((p) => p !== null).join(", ")}`);
 		}
 		if (s.protected) lines.push("  Protected: yes");
 		if (s.printArea !== null || s.pageBreakCount > 0) {
-			const parts = [s.printArea === null ? null : `print area ${s.printArea.join(", ")}`, s.pageBreakCount > 0 ? plural(s.pageBreakCount, "page break") : null];
+			const parts = [s.printArea === null ? null : `print area ${escapeControls(s.printArea.join(", "))}`, s.pageBreakCount > 0 ? plural(s.pageBreakCount, "page break") : null];
 			lines.push(`  Printing: ${parts.filter((p) => p !== null).join(", ")}`);
 		}
 	}
 	if (r.warnings.length > 0) lines.push("", ...warningsBlock(out, r.warnings));
 	return lines.join("\n");
 }
+// src/cli/commands/mcp.ts
+/** The package that holds the MCP server; xlvane does not depend on it (docs/PLAN.md section 3). */
+const MCP_PACKAGE = "@xlvane/mcp";
+/**
+* Whether loading failed because @xlvane/mcp itself is missing. A missing dependency of an
+* installed @xlvane/mcp has the same error code but names that dependency (D-I04).
+*/
+function isModuleNotFound(error) {
+	const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+	const message = error instanceof Error ? error.message : "";
+	return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && (message.includes(`'@xlvane/mcp'`) || message.includes(`"@xlvane/mcp"`));
+}
+/** Options of the xlvane command line itself, which the server does not take. */
+const OWN_OPTIONS = /* @__PURE__ */ new Set([
+	"--quiet",
+	"-q",
+	"--verbose"
+]);
+const mcpCommand = {
+	name: "mcp",
+	summary: "Start the MCP server for AI agents",
+	description: "Starts the Model Context Protocol server from the separate package @xlvane/mcp over stdin and stdout, so that an AI agent can inspect, read, convert and compare spreadsheets through tools instead of code. The arguments after \"mcp\" are passed to the server: --root <dir> (required, repeatable) names a directory the tools may use, --allow-write adds the tools that write files, and --max-file-size <bytes>, --max-rows <n> and --max-response-chars <n> set its limits. --json is not available, because stdout carries the protocol. If @xlvane/mcp is not installed, the command prints how to install it. The exit code is the server's: 0 when the client closed the connection, 2 for wrong arguments, 3 for a directory that cannot be used.",
+	usage: "[server options]",
+	positionals: {
+		min: 0,
+		max: Number.POSITIVE_INFINITY,
+		names: []
+	},
+	passThrough: true,
+	options: {},
+	examples: [{
+		command: "xlvane mcp --root ./data",
+		description: "Serve the files in ./data, read-only"
+	}, {
+		command: "xlvane mcp --root ./data --allow-write",
+		description: "Also allow writing files there"
+	}],
+	related: ["inspect", "read"],
+	async run(ctx) {
+		if (ctx.json) throw usageError("\"xlvane mcp\" does not take --json: the server uses stdout for the protocol.", "Run \"xlvane mcp --root <dir>\" without --json; the server reports its own errors as MCP results.", {
+			command: "mcp",
+			option: "--json"
+		});
+		let mod;
+		try {
+			mod = await ctx.io.importModule(MCP_PACKAGE);
+		} catch (error) {
+			if (!isModuleNotFound(error)) throw error;
+			throw new XlvError("XLV_E_NOT_INSTALLED", `The MCP server is in the separate package ${MCP_PACKAGE}, which is not installed.`, {
+				hint: `Install it next to xlvane with "npm install ${MCP_PACKAGE}", then run "xlvane mcp" again.`,
+				details: { package: MCP_PACKAGE },
+				cause: error
+			});
+		}
+		if (typeof mod.runCli !== "function") throw new XlvError("XLV_E_NOT_SUPPORTED", `The installed ${MCP_PACKAGE} does not contain the MCP server yet.`, {
+			hint: `Update ${MCP_PACKAGE} to a version that provides the server.`,
+			details: {
+				package: MCP_PACKAGE,
+				feature: "runCli"
+			}
+		});
+		const code = await mod.runCli(ctx.argv.filter((a) => !OWN_OPTIONS.has(a)));
+		return {
+			result: { exitCode: code },
+			exitCode: code === 0 || code === 1 || code === 2 ? code : 3,
+			render: () => ""
+		};
+	}
+};
 // src/cli/commands/migrate.ts
 /** The dependency value that installs @xlvane/compat under the name exceljs (npm alias). */
 const ALIAS = "npm:@xlvane/compat@^1";
@@ -1866,10 +1957,11 @@ async function sourceFiles(root) {
 			const path = join(dir, name);
 			let info;
 			try {
-				info = await stat(path);
+				info = await lstat(path);
 			} catch {
 				continue;
 			}
+			if (info.isSymbolicLink()) continue;
 			if (info.isDirectory()) await walk(path);
 			else if (info.isFile() && SOURCE.test(name) && info.size <= MAX_FILE_BYTES) files.push(path);
 		}
@@ -1898,6 +1990,75 @@ function scanSource(file, text) {
 	});
 	return findings;
 }
+/**
+* Offsets `[start, end)` of the string value (with its quotes) at `path` in valid JSON text, the
+* one JSON.parse reads when keys repeat, or `null`. Keys are compared after decoding their
+* escapes. Values off the path are skipped without recursion.
+*/
+function stringValueSpan(text, path) {
+	let i = 0;
+	const space = () => {
+		while (i < text.length && " 	\r\n".includes(text[i])) i++;
+	};
+	/** Skips a string starting at i (on its opening quote); returns its raw text. */
+	const string = () => {
+		const start = i++;
+		while (text[i] !== "\"") i += text[i] === "\\" ? 2 : 1;
+		i++;
+		return text.slice(start, i);
+	};
+	/** Skips any value starting at i, iteratively. */
+	const skip = () => {
+		let depth = 0;
+		do {
+			const c = text[i];
+			if (c === "\"") string();
+			else {
+				if (c === "{" || c === "[") depth++;
+				else if (c === "}" || c === "]") depth--;
+				i++;
+				if (depth === 0 && c !== "{" && c !== "[") while (i < text.length && !",]} 	\r\n".includes(text[i])) i++;
+			}
+		} while (depth > 0 && i < text.length);
+	};
+	const value = (level) => {
+		space();
+		if (level === path.length) {
+			if (text[i] !== "\"") {
+				skip();
+				return null;
+			}
+			const start = i;
+			string();
+			return [start, i];
+		}
+		if (text[i] !== "{") {
+			skip();
+			return null;
+		}
+		i++;
+		let found = null;
+		space();
+		if (text[i] === "}") {
+			i++;
+			return null;
+		}
+		for (;;) {
+			space();
+			const key = JSON.parse(string());
+			space();
+			i++;
+			if (key === path[level]) found = value(level + 1);
+			else {
+				space();
+				skip();
+			}
+			space();
+			if (text[i++] === "}") return found;
+		}
+	};
+	return value(0);
+}
 function jsonError(path, cause) {
 	return new XlvError("XLV_E_JSON_INVALID", `"${path}" is not a valid package.json.`, {
 		hint: "Fix the JSON syntax of package.json and run the command again.",
@@ -1945,11 +2106,14 @@ async function run$1(ctx) {
 	}
 	let write = null;
 	if (changes.length > 0 && flag(ctx.args, "force")) {
-		let updated = text;
-		for (const c of changes) {
-			const escaped = c.from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-			updated = updated.replace(new RegExp(`("exceljs"\\s*:\\s*)"${escaped}"`), `$1"${ALIAS}"`);
+		const spans = changes.map((c) => stringValueSpan(text, [c.section, "exceljs"])).filter((s) => s !== null);
+		let updated = "";
+		let at = 0;
+		for (const [start, end] of spans.sort((a, b) => a[0] - b[0])) {
+			updated += `${text.slice(at, start)}"${ALIAS}"`;
+			at = end;
 		}
+		updated += text.slice(at);
 		write = await writeOutput(ctx, pkgPath, updated, {
 			force: true,
 			dryRun: flag(ctx.args, "dry-run")
@@ -2326,7 +2490,8 @@ const COMMANDS = [
 			};
 		}
 	},
-	migrateCommand
+	migrateCommand,
+	mcpCommand
 ];
 /** Exit codes (docs/cli-json.md). */
 const EXIT = {
@@ -2350,14 +2515,14 @@ async function run(argv, io) {
 	const err = new Output(useColor(io.env, io.stderrIsTTY), io.stderrIsTTY ? width : 100);
 	const stdout = (text) => io.stdout(terminalSafe(text, out.color));
 	const stderr = (text) => io.stderr(terminalSafe(text, err.color));
-	const toJson = (value) => `${io.stdoutIsTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value)}\n`;
+	const toJson = (value) => `${jsonSafe(io.stdoutIsTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value))}\n`;
 	const json = optionArgs(argv).includes("--json");
 	const [first, ...rest] = argv;
 	let spec;
 	const state = { lastFile: null };
 	try {
 		if (first === void 0 || first === "--json" && rest.length === 0) {
-			io.stdout(welcome(out, io.version, COMMANDS));
+			stdout(welcome(out, io.version, COMMANDS));
 			return EXIT.ok;
 		}
 		if (first === "--version" || first === "-v") {
@@ -2367,7 +2532,7 @@ async function run(argv, io) {
 		if (first === "help" || first === "--help" || first === "-h") {
 			const topic = rest.find((a) => !a.startsWith("-"));
 			if (topic === void 0) {
-				io.stdout(welcome(out, io.version, COMMANDS));
+				stdout(welcome(out, io.version, COMMANDS));
 				return EXIT.ok;
 			}
 			stdout(commandHelp(out, findCommand(topic)));
@@ -2379,8 +2544,11 @@ async function run(argv, io) {
 			stdout(commandHelp(out, spec));
 			return EXIT.ok;
 		}
-		const args = parseCommandArgs(spec, rest);
-		checkPositionals(spec, args);
+		const args = spec.passThrough ? {
+			positionals: rest,
+			values: {}
+		} : parseCommandArgs(spec, rest);
+		if (!spec.passThrough) checkPositionals(spec, args);
 		const quiet = args.values["quiet"] === true;
 		const ctx = {
 			io,
@@ -2510,6 +2678,7 @@ function suggestCommand(error, first, rest, spec) {
 		const at = rest.findIndex((a, i) => a === path && rest[i - 1] !== "-o" && rest[i - 1] !== "--output");
 		if (at >= 0) return commandLine([spec.name, ...rest.map((a, i) => i === at ? suggestions[0] : a)]);
 	}
+	if (error.code === "XLV_E_NOT_INSTALLED" && typeof d["package"] === "string") return `npm install ${d["package"]}`;
 	return null;
 }
 /** Where the problem is, as one line; `null` when the message already says it all. */
@@ -2542,6 +2711,15 @@ function formatError(err, error, tryCommand, verbose = false) {
 		""
 	].join("\n");
 }
+/**
+* JSON text with DEL, the C1 controls (which include the 8-bit CSI U+009B), the bidirectional
+* formatting characters and U+2028/U+2029 written as `\uXXXX` escapes. JSON.stringify already
+* escapes C0 controls; these characters can occur only inside strings, so the escaped text is
+* valid JSON with the same value, and a terminal showing it does not act on them (D-H01).
+*/
+function jsonSafe(json) {
+	return json.replace(/[\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
 // src/cli/bin.ts
 function version() {
 	try {
@@ -2563,6 +2741,7 @@ run(process.argv.slice(2), {
 	stdoutIsTTY: process.stdout.isTTY === true,
 	stderrIsTTY: process.stderr.isTTY === true,
 	columns: process.stdout.columns,
+	importModule: (specifier) => import(specifier),
 	version: version()
 }).then((code) => {
 	process.exitCode = code;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as InspectOptions, $n as verifyPassword, $t as DataValidationOperator, A as toJSON, An as Hyperlink, At as Workbook, B as FormulaResult, Bn as PrintErrors, Bt as CfValue, C as TableRow, Cn as ImageAnchorInput, Ct as Sheet, D as fromJSON, Dn as SheetImage, Dt as SheetState, E as WriteTableOptions, En as ImagePositionInput, Et as SheetProperties, F as CellInput, Fn as PageOrder, Ft as TableDefinitionColumn, G as SheetPropertiesOptions, Gn as SheetProtectionOptions, Gt as ConditionalFormatRule, H as NewSheet, Hn as PrintTitles, Ht as CfValueType, I as ColumnOptions, In as PageOrientation, It as TableInput, J as WriteWorkbookOptions, Jn as HashPasswordOptions, Jt as DataBarAxisPosition, K as SheetViewOptions, Kn as WorkbookProtection, Kt as ConditionalFormatRuleInput, L as CreateWorkbookOptions, Ln as PageSetup, Lt as TableStyleOptions, M as StandardSchemaV1, Mn as HeaderFooter, Mt as WorkbookView, N as AddSheetOptions, Nn as PageBreaks, Nt as TableColumnInput, O as readTable, On as WorkbookImage, Ot as SheetView, P as CalculationOptions, Pn as PageMargins, Pt as TableDefinition, Q as InspectDefinedName, Qn as legacyPasswordHash, Qt as DataValidationImeMode, R as ERROR_VALUES, Rn as PageSetupOptions, Rt as TotalsRowFunction, S as TableResult, Sn as ImageAnchor, St as RowInfo, T as ToJSONOptions, Tn as ImageOptions, Tt as SheetLayout, U as NewWorkbook, Un as SheetProtection, Ut as ConditionalFormat, V as FreezeOptions, Vn as PrintOptions, Vt as CfValueInput, W as RowOptions, Wn as SheetProtectionFlags, Wt as ConditionalFormatOperator, X as writeWorkbook, Xn as PasswordVerifier, Xt as DataValidation, Y as createWorkbook, Yn as PasswordHash, Yt as DataBarDirection, Z as InspectColumn, Zn as hashPassword, Zt as DataValidationErrorStyle, _ as JsonTable, _n as ReadingOrder, _r as DefinedNameOptions, _t as DateSystem, a as WriteWorkbookStreamOptions, an as BorderEdge, ar as XlvDetails, at as ReadOptions, b as TableColumnSpec, bn as VerticalAlignment, bt as FrozenPanes, c as OpenWorkbookStreamOptions, cn as CellStyle, cr as XlvErrorInit, ct as NoteBox, d as StreamRow, dn as FontScheme, dr as XlvWarning, dt as NoteMargins, en as DataValidationRule, er as ShaAlgorithm, et as InspectReport, f as StreamSheetInfo, fn as FontStyle, fr as XlvWarningCode, ft as Cell, g as readTableStream, gn as ProtectionStyle, gr as DefinedName, gt as Conformance, h as openWorkbookStream, hn as PatternType, hr as ReadLimits, ht as ColumnInfo, i as WriteTableStreamOptions, in as AlignmentStyle, ir as XlvDetailValue, it as inspect, j as writeTable, jn as HyperlinkTarget, jt as WorkbookFormat, k as readTableAsync, kn as imageFormat, kt as SplitPanes, l as ReadTableStreamOptions, ln as Color, lr as XlvErrorJSON, lt as NoteBoxInput, m as WorkbookStream, mn as HorizontalAlignment, mr as DEFAULT_READ_LIMITS, mt as CellValue, n as StreamRowInput, nn as IconSetType, nr as ERROR_CODES, nt as InspectTypeCounts, o as writeTableStream, on as BorderLineStyle, or as XlvError, ot as readWorkbook, p as TableStreamItem, pn as GradientFill, pr as isXlvError, pt as CellType, q as WorkbookViewOptions, qn as WorkbookProtectionOptions, qt as ConditionalFormatType, r as StreamSheetSpec, rn as TimePeriod, rr as WARNING_CODES, rt as InspectValue, s as writeWorkbookStream, sn as BorderStyle, sr as XlvErrorCode, st as Note, t as StreamDefinedName, tn as DataValidationType, tr as WorkbookProperties, tt as InspectSheet, u as STREAM_LIMIT_DEFAULTS, un as FillStyle, ur as XlvLocation, ut as NoteInput, v as ReadTableOptions, vn as UnderlineStyle, vt as Formula, w as TableValue, wn as ImageFormat, wt as SheetKind, x as TableIssue, xn as AnchorMarker, xt as RichTextRun, y as TableColumn, yn as VerticalAlignRun, yt as FormulaKind, z as ErrorValue, zn as PrintCellComments, zt as CfIcon } from "./stream-write-GJXORYQ2.js";
+import { $ as InspectOptions, $n as verifyPassword, $t as DataValidationOperator, A as toJSON, An as Hyperlink, At as Workbook, B as FormulaResult, Bn as PrintErrors, Bt as CfValue, C as TableRow, Cn as ImageAnchorInput, Ct as Sheet, D as fromJSON, Dn as SheetImage, Dt as SheetState, E as WriteTableOptions, En as ImagePositionInput, Et as SheetProperties, F as CellInput, Fn as PageOrder, Ft as TableDefinitionColumn, G as SheetPropertiesOptions, Gn as SheetProtectionOptions, Gt as ConditionalFormatRule, H as NewSheet, Hn as PrintTitles, Ht as CfValueType, I as ColumnOptions, In as PageOrientation, It as TableInput, J as WriteWorkbookOptions, Jn as HashPasswordOptions, Jt as DataBarAxisPosition, K as SheetViewOptions, Kn as WorkbookProtection, Kt as ConditionalFormatRuleInput, L as CreateWorkbookOptions, Ln as PageSetup, Lt as TableStyleOptions, M as StandardSchemaV1, Mn as HeaderFooter, Mt as WorkbookView, N as AddSheetOptions, Nn as PageBreaks, Nt as TableColumnInput, O as readTable, On as WorkbookImage, Ot as SheetView, P as CalculationOptions, Pn as PageMargins, Pt as TableDefinition, Q as InspectDefinedName, Qn as legacyPasswordHash, Qt as DataValidationImeMode, R as ERROR_VALUES, Rn as PageSetupOptions, Rt as TotalsRowFunction, S as TableResult, Sn as ImageAnchor, St as RowInfo, T as ToJSONOptions, Tn as ImageOptions, Tt as SheetLayout, U as NewWorkbook, Un as SheetProtection, Ut as ConditionalFormat, V as FreezeOptions, Vn as PrintOptions, Vt as CfValueInput, W as RowOptions, Wn as SheetProtectionFlags, Wt as ConditionalFormatOperator, X as writeWorkbook, Xn as PasswordVerifier, Xt as DataValidation, Y as createWorkbook, Yn as PasswordHash, Yt as DataBarDirection, Z as InspectColumn, Zn as hashPassword, Zt as DataValidationErrorStyle, _ as JsonTable, _n as ReadingOrder, _r as DefinedNameOptions, _t as DateSystem, a as WriteWorkbookStreamOptions, an as BorderEdge, ar as XlvDetails, at as ReadOptions, b as TableColumnSpec, bn as VerticalAlignment, bt as FrozenPanes, c as OpenWorkbookStreamOptions, cn as CellStyle, cr as XlvErrorInit, ct as NoteBox, d as StreamRow, dn as FontScheme, dr as XlvWarning, dt as NoteMargins, en as DataValidationRule, er as ShaAlgorithm, et as InspectReport, f as StreamSheetInfo, fn as FontStyle, fr as XlvWarningCode, ft as Cell, g as readTableStream, gn as ProtectionStyle, gr as DefinedName, gt as Conformance, h as openWorkbookStream, hn as PatternType, hr as ReadLimits, ht as ColumnInfo, i as WriteTableStreamOptions, in as AlignmentStyle, ir as XlvDetailValue, it as inspect, j as writeTable, jn as HyperlinkTarget, jt as WorkbookFormat, k as readTableAsync, kn as imageFormat, kt as SplitPanes, l as ReadTableStreamOptions, ln as Color, lr as XlvErrorJSON, lt as NoteBoxInput, m as WorkbookStream, mn as HorizontalAlignment, mr as DEFAULT_READ_LIMITS, mt as CellValue, n as StreamRowInput, nn as IconSetType, nr as ERROR_CODES, nt as InspectTypeCounts, o as writeTableStream, on as BorderLineStyle, or as XlvError, ot as readWorkbook, p as TableStreamItem, pn as GradientFill, pr as isXlvError, pt as CellType, q as WorkbookViewOptions, qn as WorkbookProtectionOptions, qt as ConditionalFormatType, r as StreamSheetSpec, rn as TimePeriod, rr as WARNING_CODES, rt as InspectValue, s as writeWorkbookStream, sn as BorderStyle, sr as XlvErrorCode, st as Note, t as StreamDefinedName, tn as DataValidationType, tr as WorkbookProperties, tt as InspectSheet, u as STREAM_LIMIT_DEFAULTS, un as FillStyle, ur as XlvLocation, ut as NoteInput, v as ReadTableOptions, vn as UnderlineStyle, vt as Formula, w as TableValue, wn as ImageFormat, wt as SheetKind, x as TableIssue, xn as AnchorMarker, xt as RichTextRun, y as TableColumn, yn as VerticalAlignRun, yt as FormulaKind, z as ErrorValue, zn as PrintCellComments, zt as CfIcon } from "./stream-write-BVaFkgwO.js";
 /**
  * Options for {@link toCSV}.
  *
@@ -21,9 +21,10 @@ interface ToCSVOptions {
   /** Start with a UTF-8 byte order mark, which helps Excel detect UTF-8. Default `false`. */
   readonly bom?: boolean;
   /**
-   * `"escape"` (default): text cells that start with `=`, `+`, `-`, `@`, tab, CR, LF or their
-   * full-width forms get a leading `'` and quotes, so spreadsheet applications show them as
-   * text instead of running them as formulas (OWASP CSV Injection). `"off"`: write them as is.
+   * `"escape"` (default): text cells that start with `=`, `+`, `-`, `@`, their full-width or small
+   * forms, or a control character (tab, CR, LF, NUL, …) get a leading `'` and quotes, so
+   * spreadsheet applications show them as text instead of running them as formulas (OWASP CSV
+   * Injection). `"off"`: write them as is.
    */
   readonly formulaInjection?: "escape" | "off";
   /** Read limits for byte input; see `ReadLimits`. */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Dn as isXlvError, En as XlvError, Gt as legacyPasswordHash, Kt as verifyPassword, Rt as DEFAULT_READ_LIMITS, Tn as WARNING_CODES, Wt as hashPassword, Zt as imageFormat, b as readWorkbook, c as NewSheet, f as createWorkbook, g as inspect, l as NewWorkbook, m as writeWorkbook, s as ERROR_VALUES, wn as ERROR_CODES, z as shiftFormula } from "./options-CwSp2pA4.js";
-import { a as appendRows, c as fromCSV, d as fromJSON, g as writeTable, h as toJSON, i as adjustRange, m as readTableAsync, n as insertRows, o as editCells, p as readTable, r as adjustFormula, s as diff, t as deleteRows, u as toCSV } from "./rows-DKwlr0rg.js";
-import { a as readTableStream, i as openWorkbookStream, n as writeWorkbookStream, r as STREAM_LIMIT_DEFAULTS, t as writeTableStream } from "./stream-write-BKppyMz0.js";
+import { Dn as WARNING_CODES, En as ERROR_CODES, Gt as hashPassword, Kt as legacyPasswordHash, On as XlvError, Qt as imageFormat, Rt as DEFAULT_READ_LIMITS, b as readWorkbook, c as NewSheet, f as createWorkbook, g as inspect, kn as isXlvError, l as NewWorkbook, m as writeWorkbook, qt as verifyPassword, s as ERROR_VALUES, z as shiftFormula } from "./options-Ba1iWD-Z.js";
+import { a as appendRows, c as fromCSV, d as fromJSON, g as writeTable, h as toJSON, i as adjustRange, m as readTableAsync, n as insertRows, o as editCells, p as readTable, r as adjustFormula, s as diff, t as deleteRows, u as toCSV } from "./rows-IWKIxHt9.js";
+import { a as readTableStream, i as openWorkbookStream, n as writeWorkbookStream, r as STREAM_LIMIT_DEFAULTS, t as writeTableStream } from "./stream-write-BGuUjlXo.js";
 export { DEFAULT_READ_LIMITS, ERROR_CODES, ERROR_VALUES, NewSheet, NewWorkbook, STREAM_LIMIT_DEFAULTS, WARNING_CODES, XlvError, adjustFormula, adjustRange, appendRows, createWorkbook, deleteRows, diff, editCells, fromCSV, fromJSON, hashPassword, imageFormat, insertRows, inspect, isXlvError, legacyPasswordHash, openWorkbookStream, readTable, readTableAsync, readTableStream, readWorkbook, shiftFormula, toCSV, toJSON, verifyPassword, writeTable, writeTableStream, writeWorkbook, writeWorkbookStream };

package/dist/{node-files-B0iqSJIJ.js → node-files-CDb6TyZb.js}

@@ -1,4 +1,4 @@
-import { En as XlvError, zt as resolveLimits } from "./options-CwSp2pA4.js";
+import { Bt as resolveLimits, On as XlvError } from "./options-Ba1iWD-Z.js";
 import { readFile, stat } from "node:fs/promises";
 // src/util/node-files.ts
 /** The path as shown in messages. */

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { $ as InspectOptions, At as Workbook, J as WriteWorkbookOptions, U as NewWorkbook, a as WriteWorkbookStreamOptions, at as ReadOptions, c as OpenWorkbookStreamOptions, et as InspectReport, m as WorkbookStream } from "./stream-write-GJXORYQ2.js";
+import { $ as InspectOptions, At as Workbook, J as WriteWorkbookOptions, U as NewWorkbook, a as WriteWorkbookStreamOptions, at as ReadOptions, c as OpenWorkbookStreamOptions, et as InspectReport, m as WorkbookStream } from "./stream-write-BVaFkgwO.js";
 /**
  * Reads an XLSX file from disk. Node.js only; in other runtimes pass the bytes to
  * `readWorkbook` from `xlvane`. The file size is checked against `limits.maxInputBytes`

package/dist/node.js

@@ -1,6 +1,6 @@
-import { En as XlvError, b as readWorkbook, g as inspect, m as writeWorkbook, zt as resolveLimits } from "./options-CwSp2pA4.js";
-import { i as readInput, n as describePath, r as fileError, t as checkFile } from "./node-files-B0iqSJIJ.js";
-import { i as openWorkbookStream, n as writeWorkbookStream, r as STREAM_LIMIT_DEFAULTS } from "./stream-write-BKppyMz0.js";
+import { Bt as resolveLimits, On as XlvError, b as readWorkbook, g as inspect, m as writeWorkbook } from "./options-Ba1iWD-Z.js";
+import { i as readInput, n as describePath, r as fileError, t as checkFile } from "./node-files-CDb6TyZb.js";
+import { i as openWorkbookStream, n as writeWorkbookStream, r as STREAM_LIMIT_DEFAULTS } from "./stream-write-BGuUjlXo.js";
 import { openAsBlob } from "node:fs";
 import { open, unlink, writeFile } from "node:fs/promises";
 // src/node.ts