xlvane 1.2.2 → 1.3.0

package/README.md

@@ -26,7 +26,7 @@ From a shell: `npx xlvane inspect orders.xlsx`, then `npx xlvane read orders.xls
 ## Contents
 
 - [Command line in 5 minutes](#command-line-in-5-minutes)
-- [Reading a workbook](#reading-a-workbook) · [Writing a workbook](#writing-a-workbook) (rich text, hyperlinks, notes, images, printing, [data validation and conditional formatting](#data-validation-and-conditional-formatting), [tables](#tables))
+- [Reading a workbook](#reading-a-workbook) · [Writing a workbook](#writing-a-workbook) (rich text, hyperlinks, notes, images, [charts](#charts), printing, [data validation and conditional formatting](#data-validation-and-conditional-formatting), [tables](#tables))
 - [Tasks in one call](#tasks-in-one-call): tables of rows, CSV, JSON, editing files, diff · [inserting and deleting rows](#inserting-and-deleting-rows)
 - [Large files: streaming](#large-files-streaming)
 - [Inspecting a workbook](#inspecting-a-workbook) · [Errors and warnings](#errors-and-warnings) · [Untrusted input and limits](#untrusted-input-and-limits)
@@ -172,10 +172,41 @@ for (const picture of read.getSheet('Report').images) console.log(picture.anchor
 ```
 
 - **Adding:** `workbook.addImage(bytes)` takes PNG, JPEG or GIF bytes (recognised from the first bytes; other formats throw `XLV_E_INVALID_IMAGE`) and returns a number; the same image placed many times is stored once. `sheet.addImage(image, anchor, { name?, description?, hyperlink? })` places it over a range (`"E1:G4"`), between two corners (`{ from, to, editAs }`, each a cell or a 0-based `{ col, row }` with fractions) or at a corner with a size in pixels (`{ from, size }`). `sheet.background(image)` sets the sheet background. Pixels are converted at 96 per inch (9525 EMU); fractional positions use the sheet's column widths and row heights.
-- **Reading:** `sheet.images` lists the pictures (`anchor` in EMU with the cell of each corner, `image` with `format`, `contentType` and `bytes`, `description`, `hyperlink`), `sheet.backgroundImage` the background, and `workbook.images` every image once. Charts, shapes and other drawing objects are not read; `XLV_W_DRAWING_CONTENT_NOT_READ` reports them, and `editCells` keeps them unchanged.
+- **Reading:** `sheet.images` lists the pictures (`anchor` in EMU with the cell of each corner, `image` with `format`, `contentType` and `bytes`, `description`, `hyperlink`), `sheet.backgroundImage` the background, and `workbook.images` every image once. Charts are read into `sheet.charts` (see [Charts](#charts)); shapes and other drawing objects are not read: `XLV_W_DRAWING_CONTENT_NOT_READ` reports them, and `editCells` keeps them unchanged.
 - **Rows:** `insertRows` and `deleteRows` move pictures with their rows. A deletion that would cut a picture, and a drawing with charts or shapes, are refused with `XLV_E_NOT_SUPPORTED`.
 - **Streaming:** `writeWorkbookStream({ images: [png], sheets: [{ images: [{ image: 0, anchor: 'B2:D6' }], background: 0, rows }] })`.
 
+### Charts
+
+```ts
+import { createWorkbook, readWorkbook, writeWorkbook } from 'xlvane';
+
+const workbook = createWorkbook();
+const sales = workbook.addSheet('Sales').set('A1', 'Month').set('B1', 'North').set('C1', 'South');
+['Jan', 'Feb', 'Mar'].forEach((month, i) => sales.set(`A${String(i + 2)}`, month).set(`B${String(i + 2)}`, 10 + i).set(`C${String(i + 2)}`, 20 - i));
+sales.addChart({
+  type: 'column',
+  anchor: 'E2:L18',
+  title: 'Sales by month',
+  series: [
+    { name: 'Sales!B1', categories: 'Sales!A2:A4', values: 'Sales!B2:B4' },
+    { name: 'Sales!C1', categories: 'Sales!A2:A4', values: 'Sales!C2:C4', color: 'C00000' },
+  ],
+  legend: 'bottom',
+  axes: { y: { title: 'Units', min: 0 } },
+});
+
+const chart = readWorkbook(writeWorkbook(workbook)).getSheet('Sales').charts[0];
+console.log(chart?.types, chart?.title, chart?.series.map((s) => s.values)); // ['column'] { text: 'Sales by month' } ['Sales!$B$2:$B$4', 'Sales!$C$2:$C$4']
+```
+
+- **Adding:** `sheet.addChart({ type, anchor, series, title?, legend?, stacked?, axes?, name?, description? })` with `type` `column`, `bar`, `line`, `pie`, `scatter` or `area`; `anchor` as for pictures. Each series has `values` and optional `categories` (for scatter: the y and x values), each a sheet-qualified range of one row or one column such as `'Sales Data'!B2:B13`, an optional `name` (literal text, or a one-cell reference such as `Sales!B1`) and an optional `color` (`RRGGBB`). `stacked` is `true` or `'percent'` (not for pie and scatter); `legend` is `'right'` (default), `'bottom'`, `'top'`, `'left'` or `false`; `axes.x.title`, `axes.y.title`, `axes.y.min`, `axes.y.max`. A chart has 1 to 255 series; a pie exactly one, with at most 1 000 values. The sheets named in the ranges must exist when the workbook is written. Errors: `XLV_E_INVALID_CHART`.
+- **What is written:** a chart part per chart with the series colours from a fixed palette (the accent colours of Excel's Office theme), since xlvane writes no theme part, and with the current cell values as caches, as Excel writes them. Combination charts, secondary axes, trendlines, data labels and chart sheets are not written.
+- **Reading:** `sheet.charts` lists each chart's `name`, `description`, `anchor`, `types` (the chart groups in order, for example `['column', 'line']` for a combination chart; other chart types as `other:` and the element name), `stacked`, `title` (`{ text }`, `{ ref }` or `null`), `legend`, `axes` (`title`, `min`, `max`) and `series` (`type`, `name`, `categories`, `values` as reference text). References are never evaluated and cached values are not read. Charts on chart sheets are not read. `openWorkbookStream` does not report pictures or charts.
+- **Streaming:** `writeWorkbookStream({ sheets: [{ name: 'Sales', rows, charts: [{ type: 'line', anchor: 'E2:L18', series: [...] }] }] })`. The streaming writer keeps no cell values, so its charts have no caches. LibreOffice draws such charts from the cells; whether Excel does is not verified.
+- **Rows:** `insertRows` and `deleteRows` refuse sheets with charts, and workbooks whose charts may refer to the sheet, with `XLV_E_NOT_SUPPORTED`.
+- **Checked with:** a copy of the ECMA-376 chart schema and LibreOffice 24.2.7.2, not with Excel. In the repository, `node scripts/chart-samples.mjs <directory>` (after `npm run build`) writes one sample file per type and variant.
+
 ### Sheet rules and printing
 
 ```ts
@@ -330,7 +361,7 @@ const stream = writeWorkbookStream({ sheets: [{ name: 'Data', rows: rows() }] })
 - Memory stays constant: the test suite reads and writes 50 000 and 400 000 rows and checks that the retained heap does not grow. It measured under 1 MB in both cases.
 - Streamed text is stored in the cells (inline strings) by default. Pass `sharedStrings: true` for a shared string table, which is smaller when values repeat but kept in memory until the end.
 - Rows come in file order. A shared formula whose master cell comes later in the file cannot be translated while streaming.
-- `maxCells` does not apply when streaming; single parts may decompress to 4 GiB (`STREAM_LIMIT_DEFAULTS`). All other limits apply.
+- `maxCells` does not apply when streaming, except that one `<row>` element may hold at most 16 384 cells; single parts may decompress to 4 GiB (`STREAM_LIMIT_DEFAULTS`). All other limits apply.
 - `readTableStream` differs from `readTable` in what it can see in advance: it detects the header row among the first rows it reads and fixes the columns there (the columns of the header row, or of the first rows without one), so a column that first appears further down is not part of the objects. `readTable` takes the columns of the whole sheet. For files that fit in memory, `readTable` gives the complete table.
 
 ## Benchmark
@@ -387,8 +418,8 @@ Limits can be changed per call, for example `readWorkbook(bytes, { limits: { max
 | `maxXmlNameLength` | 1 024 | huge element or attribute names |
 | `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); 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 |
+| `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, and of `fromCSV`, `fromJSON` and `writeTable` to `max(maxCells, 16 × cells written)`; for `editCells` and `appendRows`, the cells of the workbook plus the new cells, and at most 1 000 000 cells written per call unless `maxCells` is given; for `insertRows` with `style`, the copied cell formats plus the cells of the workbook |
+| `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 and for header names repeated in every row object of `readTable` and `toJSON` |
 
 ## Package size
 
@@ -398,7 +429,7 @@ Limits can be changed per call, for example `readWorkbook(bytes, { limits: { max
 
 - xlvane does not calculate formulas. It reads and writes formula text and the cached results stored in the file; edited files ask spreadsheet applications to recalculate when they are opened.
 - Password-protected (encrypted) workbooks and legacy `.xls` files are rejected with `XLV_E_UNSUPPORTED_CONTAINER`. A sheet protection password is not encryption and is supported.
-- Charts, shapes, pivot tables, slicers and form controls are not modelled: reading skips them (with a warning for drawings), `editCells` keeps them unchanged, and row operations refuse sheets where they would have to move.
+- Shapes, pivot tables, slicers and form controls are not modelled: reading skips them (with a warning for drawings), `editCells` keeps them unchanged, and row operations refuse sheets where they would have to move. Charts are read and written for six types (see [Charts](#charts)); row operations refuse them too.
 - The command line reads files, not standard input.
 
 ## Links

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-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 { Vt as suggest, _ as inspect, v as isoDate, x as readWorkbook, yn as parseRange, zn as XlvError } from "./options-Cxt-LJE4.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-DltZ-hiW.js";
+import { i as readInput } from "./node-files-SVg17pky.js";
 import { existsSync, readFileSync } from "node:fs";
-import { chmod, lstat, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, open, 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";
@@ -523,14 +523,15 @@ function oneLine(text) {
 }
 /**
 * Control characters that a terminal would act on (C0 except tab and line feed, DEL, and C1,
-* 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
+* which includes the 8-bit CSI U+009B) written as `\x1b`, bidirectional formatting characters
+* written as `\u202e`, and line feeds written as `⏎` (so a name from a file cannot add lines of its
+* own to the output, D-K04), 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` 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")}`);
+	return text.replace(/\n/g, "⏎").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")}`);
 }
 /**
 * The characters with the Unicode property Bidi_Control (checked against `/\p{Bidi_Control}/u` in
@@ -649,6 +650,18 @@ function quoteArg(arg) {
 	if (/^[\w@%+=:,./-]+$/.test(arg)) return arg;
 	return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
+/**
+* `args` with `options` added before the first "--", after which every argument is positional
+* (or at the end when there is none).
+*/
+function withOptions(args, ...options) {
+	const at = args.indexOf("--");
+	return at === -1 ? [...args, ...options] : [
+		...args.slice(0, at),
+		...options,
+		...args.slice(at)
+	];
+}
 /** A command line as text. */
 function commandLine(args) {
 	return ["xlvane", ...args].map(quoteArg).join(" ");
@@ -805,8 +818,8 @@ function withPath(error, path) {
 }
 /**
 * For a missing file, suggests a file with a similar name in the same directory: only a name the
-* command can read (`accept`), and never a file that another argument of the command already
-* names, such as the other side of a diff (D-R08).
+* command can read (`accept`), and never the path itself or a file that another argument of the
+* command already names, such as the other side of a diff (D-R08, D-K04).
 */
 async function withFileHint(ctx, path, error, accept) {
 	if (!(error instanceof XlvError) || error.details["code"] !== "ENOENT") return error;
@@ -817,6 +830,7 @@ async function withFileHint(ctx, path, error, accept) {
 		return error;
 	}
 	const others = new Set(ctx.argv.filter((a) => a !== path && !a.startsWith("-")).map((a) => resolvePath(ctx, a)));
+	others.add(resolvePath(ctx, path));
 	const candidates = names.filter((n) => accept(n) && !others.has(resolvePath(ctx, join(dirname(path), n))));
 	const close = suggest(basename(path), candidates, 1);
 	if (close.length === 0) return error;
@@ -844,16 +858,26 @@ async function writeOutput(ctx, path, data, options) {
 	let exists = false;
 	let mode = null;
 	try {
-		const info = await stat(target);
+		const link = await lstat(target);
 		exists = true;
-		mode = info.mode & 4095;
-		if (!info.isFile()) throw new XlvError("XLV_E_FILE_WRITE", `"${path}" is a directory.`, {
-			hint: "Give a file name for the output.",
-			details: {
-				path,
-				code: "EISDIR"
-			}
-		});
+		const info = link.isSymbolicLink() ? await stat(target).catch(() => null) : link;
+		if (info !== null) {
+			mode = info.mode & 511;
+			if (info.isDirectory()) throw new XlvError("XLV_E_FILE_WRITE", `"${path}" is a directory.`, {
+				hint: "Give a file name for the output.",
+				details: {
+					path,
+					code: "EISDIR"
+				}
+			});
+			if (!info.isFile()) throw new XlvError("XLV_E_FILE_WRITE", `"${path}" is not a regular file.`, {
+				hint: "Give the name of a regular file for the output.",
+				details: {
+					path,
+					code: "ENOTREG"
+				}
+			});
+		}
 	} catch (error) {
 		if (error instanceof XlvError) throw error;
 	}
@@ -869,13 +893,21 @@ async function writeOutput(ctx, path, data, options) {
 	};
 	try {
 		if (exists) {
-			const temp = join(dirname(target), `.${basename(target)}.xlvane-${String(Date.now())}.tmp`);
+			const random = Array.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8)), (b) => b.toString(16).padStart(2, "0")).join("");
+			const temp = join(dirname(target), `.${shortName(basename(target))}.xlvane-${random}.tmp`);
+			let created = false;
 			try {
-				await writeFile(temp, bytes, { flag: "wx" });
-				if (mode !== null) await chmod(temp, mode);
+				const handle = await open(temp, "wx", mode === null ? void 0 : 384);
+				created = true;
+				try {
+					await handle.writeFile(bytes);
+					if (mode !== null) await handle.chmod(mode);
+				} finally {
+					await handle.close();
+				}
 				await rename(temp, target);
 			} catch (error) {
-				await rm(temp, { force: true });
+				if (created) await rm(temp, { force: true });
 				throw error;
 			}
 		} else await writeFile(target, bytes, { flag: "wx" });
@@ -902,6 +934,21 @@ async function writeOutput(ctx, path, data, options) {
 		replaced: exists
 	};
 }
+/**
+* The start of a file name, at most 100 bytes of UTF-8 and never cut inside a character, for the
+* name of a temporary file next to it (file systems limit names in bytes, D-K03).
+*/
+function shortName(name) {
+	let bytes = 0;
+	let end = 0;
+	for (const ch of name) {
+		const size = new TextEncoder().encode(ch).length;
+		if (bytes + size > 100) break;
+		bytes += size;
+		end += ch.length;
+	}
+	return name.slice(0, end);
+}
 /** The line every writing command ends with; green when something was written. */
 function wroteLine(w, out) {
 	if (!w.written) {
@@ -1068,6 +1115,23 @@ function formatOf(command, path, role) {
 		[role]: path
 	});
 }
+/**
+* The rows as indented JSON text. Every row repeats the header names, so a small file can ask for
+* more text than a JavaScript string can hold; that ends as a limit error, not an internal one
+* (D-J01).
+*/
+function jsonText(rows) {
+	try {
+		return `${JSON.stringify(rows, null, 2)}\n`;
+	} catch (error) {
+		if (!(error instanceof RangeError)) throw error;
+		throw new XlvError("XLV_E_LIMIT_EXCEEDED", "The JSON text would be longer than a JavaScript string can be.", {
+			hint: "Convert part of the sheet with --range, or convert to CSV, which does not repeat the header in every row.",
+			details: { limit: "maxSharedStringChars" },
+			cause: error
+		});
+	}
+}
 /** The delimiter option: one character, or "tab". */
 function delimiterOf(ctx, command, format) {
 	const d = str(ctx.args, "delimiter");
@@ -1091,12 +1155,7 @@ function delimiterNote(ctx, command, text, input) {
 	const other = first.includes(";") ? ";" : first.includes("	") ? "tab" : null;
 	if (other === null) return;
 	const args = ctx.argv.filter((a) => a !== "--json");
-	ctx.note(`note: the first line of ${input} has no "," but has ${other === "tab" ? "tabs" : "\";\""}; every line became one column. Try: ${commandLine([
-		command,
-		...args,
-		"--delimiter",
-		other
-	])}`);
+	ctx.note(`note: the first line of ${input} has no "," but has ${other === "tab" ? "tabs" : "\";\""}; every line became one column. Try: ${commandLine(withOptions([command, ...args], "--delimiter", other))}`);
 }
 /** What to do with a JSON file that holds something other than an array of rows. */
 /**
@@ -1253,10 +1312,10 @@ const convertCommand = {
 				...sheet !== void 0 ? { sheet } : {},
 				...range !== void 0 ? { range } : {}
 			};
-			if (to === "json") data = `${JSON.stringify(toJSON(workbook, {
+			if (to === "json") data = jsonText(toJSON(workbook, {
 				...where,
 				header: headerOption(ctx.args, "convert")
-			}).rows, null, 2)}\n`;
+			}).rows);
 			else data = toCSV(workbook, {
 				...where,
 				delimiter: delimiterOf(ctx, "convert", to),
@@ -1682,10 +1741,10 @@ const editCommand = {
 				render: (out) => {
 					if (ctx.quiet && w.written) return "";
 					const done = [
-						insert !== null ? `inserted ${plural(insert.count, "row")} before row ${String(insert.at)} of "${sheetOption ?? ""}"` : "",
-						remove !== null ? `deleted ${remove.count === 1 ? `row ${String(remove.at)}` : `rows ${String(remove.at)}–${String(remove.at + remove.count - 1)}`} of "${sheetOption ?? ""}"` : "",
+						insert !== null ? `inserted ${plural(insert.count, "row")} before row ${String(insert.at)} of "${escapeControls(sheetOption ?? "")}"` : "",
+						remove !== null ? `deleted ${remove.count === 1 ? `row ${String(remove.at)}` : `rows ${String(remove.at)}–${String(remove.at + remove.count - 1)}`} of "${escapeControls(sheetOption ?? "")}"` : "",
 						parsed.length > 0 ? `set ${plural(parsed.length, "cell")}` : "",
-						rows.length > 0 ? `appended ${plural(rows.length, "row")} to "${appendSheet ?? ""}"` : ""
+						rows.length > 0 ? `appended ${plural(rows.length, "row")} to "${escapeControls(appendSheet ?? "")}"` : ""
 					].filter((p) => p !== "").join(", ");
 					return [
 						`${done.charAt(0).toUpperCase()}${done.slice(1)}.`,
@@ -1829,6 +1888,10 @@ function renderReport(out, file, r, verbose) {
 			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.chartCount > 0) {
+			const shown = s.charts.slice(0, 5).map((c) => `${c.cell ?? "absolute"} ${escapeControls(c.types.join("+") || "empty")}${c.typesTruncated ? "+…" : ""}${c.title === null ? "" : "text" in c.title ? ` "${escapeControls(c.title.text)}"` : ` =${escapeControls(c.title.ref)}`}`);
+			lines.push(`  Charts: ${plural(s.chartCount, "chart")} (${shown.join(", ")}${s.chartCount > 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((table) => `${escapeControls(table.name)} ${escapeControls(table.ref)}`).join(", ")}${s.tables.length > 5 ? ", …" : ""}`);
 		if (s.dataValidationCount > 0 || s.conditionalFormatCount > 0) {
@@ -1865,7 +1928,7 @@ const OWN_OPTIONS = /* @__PURE__ */ new Set([
 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.",
+	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>, --max-response-chars <n> and --max-cells <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,
@@ -2066,9 +2129,23 @@ function jsonError(path, cause) {
 		cause
 	});
 }
+async function isLink(path) {
+	try {
+		return (await lstat(path)).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
 async function run$1(ctx) {
 	const dir = ctx.args.positionals[0] ?? ".";
 	const pkgPath = join(dir, "package.json");
+	if (await isLink(resolvePath(ctx, pkgPath))) throw new XlvError("XLV_E_FILE_READ", `"${pkgPath}" is a symbolic link; migrate does not follow links.`, {
+		hint: "Run migrate in the directory that holds the real package.json.",
+		details: {
+			path: pkgPath,
+			code: "ELOOP"
+		}
+	});
 	const text = await readText(ctx, pkgPath);
 	let pkg;
 	try {
@@ -2138,17 +2215,22 @@ async function run$1(ctx) {
 			else if (alreadyMigrated) lines.push(`${pkgPath} already uses ${ALIAS} for "exceljs".`);
 			else {
 				lines.push(`${out.bold("Change in")} ${pkgPath}:`);
-				for (const c of changes) lines.push(`  ${c.section}: ${out.red(`- "exceljs": "${c.from}"`)}`, `  ${" ".repeat(c.section.length)}  ${out.green(`+ "exceljs": "${c.to}"`)}`);
+				for (const c of changes) lines.push(`  ${c.section}: ${out.red(`- "exceljs": "${escapeControls(c.from)}"`)}`, `  ${" ".repeat(c.section.length)}  ${out.green(`+ "exceljs": "${escapeControls(c.to)}"`)}`);
 			}
-			lines.push(`Node.js: require('exceljs') of @xlvane/compat needs Node.js 22.12 or later (package.json engines.node: ${typeof engines === "string" ? `"${engines}"` : "not set"}).`);
+			lines.push(`Node.js: require('exceljs') of @xlvane/compat needs Node.js 22.12 or later (package.json engines.node: ${typeof engines === "string" ? `"${escapeControls(engines)}"` : "not set"}).`);
 			lines.push("", `Scanned ${plural(files.length, "source file")}${limited ? ` (stopped at ${String(MAX_FILES)})` : ""} for exceljs API that @xlvane/compat does not fully support:`);
 			if (findings.length === 0) lines.push("  none found.");
-			for (const f of findings.slice(0, 200)) lines.push(`  ${f.status === "partly" ? out.yellow("partly       ") : out.red("not supported")} ${f.file}:${String(f.line)}:${String(f.column)}  ${f.api}`);
+			for (const f of findings.slice(0, 200)) lines.push(`  ${f.status === "partly" ? out.yellow("partly       ") : out.red("not supported")} ${escapeControls(f.file)}:${String(f.line)}:${String(f.column)}  ${escapeControls(f.api)}`);
 			if (findings.length > 200) lines.push(out.dim(`  … ${String(findings.length - 200)} more; use --json for all`));
 			lines.push("  Details: docs/exceljs-compat.md. Unsupported calls throw XLV_E_NOT_SUPPORTED at run time.");
 			lines.push("");
 			if (write) lines.push(wroteLine(write));
-			else if (changes.length > 0) lines.push(`Nothing was written. Run "${commandLine([
+			else if (changes.length > 0) lines.push(`Nothing was written. Run "${commandLine(dir.startsWith("-") ? [
+				"migrate",
+				"--force",
+				"--",
+				dir
+			] : [
 				"migrate",
 				...dir === "." ? [] : [dir],
 				"--force"
@@ -2300,7 +2382,7 @@ const readCommand = {
 			result,
 			exitCode: 0,
 			render: (out) => {
-				if (table.columns.length === 0) return `Sheet "${table.sheet}" has no data${table.range ? ` in ${table.range}` : ""}.`;
+				if (table.columns.length === 0) return `Sheet "${escapeControls(table.sheet)}" has no data${table.range ? ` in ${table.range}` : ""}.`;
 				const numeric = table.columns.map((c) => shown.length > 0 && shown.every((row) => row[c.key] === null || typeof row[c.key] === "number") ? "right" : "left");
 				return out.table(table.columns.map((c) => c.header ?? c.key), shown.map((row) => table.columns.map((c) => showValue(row[c.key]))), "", numeric);
 			}
@@ -2410,6 +2492,8 @@ const COMMANDS = [
 			const problems = [];
 			let sheetName = null;
 			let rowsChecked = 0;
+			const named = str(ctx.args, "sheet");
+			if (named !== void 0) workbook.getSheet(named);
 			if (rules.length > 0) {
 				const sheet = str(ctx.args, "sheet");
 				const table = readTable(workbook, {
@@ -2481,7 +2565,7 @@ const COMMANDS = [
 						lines.push("");
 					}
 					if (warnings.length > 0) lines.push(...warningsBlock(out, warnings), "");
-					const checked = sheetName !== null ? `, ${plural(rowsChecked, "row")} of sheet "${sheetName}" checked against ${plural(rules.length, "column rule")}` : "";
+					const checked = sheetName !== null ? `, ${plural(rowsChecked, "row")} of sheet "${escapeControls(sheetName)}" checked against ${plural(rules.length, "column rule")}` : "";
 					if (ok && warnings.length > 0) lines.push(`${out.yellow(`OK with ${plural(warnings.length, "warning")}`)}: ${file}${checked}. Use --strict to fail on warnings.`);
 					else if (ok) lines.push(`${out.green("OK")}: ${file}${checked}.`);
 					else lines.push(`${out.red("Failed")}: ${file}${checked}${strict && problems.length === 0 ? " (warnings count with --strict)" : ""}.`);
@@ -2658,11 +2742,7 @@ function suggestCommand(error, first, rest, spec) {
 		}
 	}
 	if (spec === void 0) return null;
-	if (error.code === "XLV_E_FILE_EXISTS") return commandLine([
-		spec.name,
-		...rest,
-		"--force"
-	]);
+	if (error.code === "XLV_E_FILE_EXISTS") return commandLine(withOptions([spec.name, ...rest], "--force"));
 	if (error.code === "XLV_E_SHEET_NOT_FOUND" && Array.isArray(d["available"]) && typeof error.location.sheet === "string") {
 		const close = suggest(error.location.sheet, d["available"], 1);
 		const fixed = close.length > 0 ? withSheetName(rest, error.location.sheet, close[0]) : null;

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-BVaFkgwO.js";
+import { $ as InspectOptions, $n as SheetProtection, $t as DataValidationOperator, A as toJSON, An as SheetChart, At as Workbook, B as FormulaResult, Bn as Hyperlink, Bt as CfValue, C as TableRow, Cn as ChartInput, Cr as isXlvError, Ct as Sheet, D as fromJSON, Dn as ChartSeriesInput, Dr as DefinedNameOptions, Dt as SheetState, E as WriteTableOptions, En as ChartSeries, Er as DefinedName, Et as SheetProperties, F as CellInput, Fn as ImageOptions, Ft as TableDefinitionColumn, G as SheetPropertiesOptions, Gn as PageOrder, Gt as ConditionalFormatRule, H as NewSheet, Hn as HeaderFooter, Ht as CfValueType, I as ColumnOptions, In as ImagePositionInput, It as TableInput, J as WriteWorkbookOptions, Jn as PageSetupOptions, Jt as DataBarAxisPosition, K as SheetViewOptions, Kn as PageOrientation, Kt as ConditionalFormatRuleInput, L as CreateWorkbookOptions, Ln as SheetImage, Lt as TableStyleOptions, M as StandardSchemaV1, Mn as ImageAnchor, Mt as WorkbookView, N as AddSheetOptions, Nn as ImageAnchorInput, Nt as TableColumnInput, O as readTable, On as ChartText, Ot as SheetView, P as CalculationOptions, Pn as ImageFormat, Pt as TableDefinition, Q as InspectDefinedName, Qn as PrintTitles, Qt as DataValidationImeMode, R as ERROR_VALUES, Rn as WorkbookImage, Rt as TotalsRowFunction, S as TableResult, Sn as ChartAxisInput, Sr as XlvWarningCode, St as RowInfo, T as ToJSONOptions, Tn as ChartLegendPosition, Tr as ReadLimits, Tt as SheetLayout, U as NewWorkbook, Un as PageBreaks, Ut as ConditionalFormat, V as FreezeOptions, Vn as HyperlinkTarget, Vt as CfValueInput, W as RowOptions, Wn as PageMargins, Wt as ConditionalFormatOperator, X as writeWorkbook, Xn as PrintErrors, Xt as DataValidation, Y as createWorkbook, Yn as PrintCellComments, Yt as DataBarDirection, Z as InspectColumn, Zn as PrintOptions, Zt as DataValidationErrorStyle, _ as JsonTable, _n as ReadingOrder, _r as XlvErrorCode, _t as DateSystem, a as WriteWorkbookStreamOptions, an as BorderEdge, ar as PasswordHash, at as ReadOptions, b as TableColumnSpec, bn as VerticalAlignment, br as XlvLocation, bt as FrozenPanes, c as OpenWorkbookStreamOptions, cn as CellStyle, cr as legacyPasswordHash, ct as NoteBox, d as StreamRow, dn as FontScheme, dr as WorkbookProperties, dt as NoteMargins, en as DataValidationRule, er as SheetProtectionFlags, et as InspectReport, f as StreamSheetInfo, fn as FontStyle, fr as ERROR_CODES, ft as Cell, g as readTableStream, gn as ProtectionStyle, gr as XlvError, gt as Conformance, h as openWorkbookStream, hn as PatternType, hr as XlvDetails, ht as ColumnInfo, i as WriteTableStreamOptions, in as AlignmentStyle, ir as HashPasswordOptions, it as inspect, j as writeTable, jn as AnchorMarker, jt as WorkbookFormat, k as readTableAsync, kn as ChartType, kt as SplitPanes, l as ReadTableStreamOptions, ln as Color, lr as verifyPassword, lt as NoteBoxInput, m as WorkbookStream, mn as HorizontalAlignment, mr as XlvDetailValue, mt as CellValue, n as StreamRowInput, nn as IconSetType, nr as WorkbookProtection, nt as InspectTypeCounts, o as writeTableStream, on as BorderLineStyle, or as PasswordVerifier, ot as readWorkbook, p as TableStreamItem, pn as GradientFill, pr as WARNING_CODES, pt as CellType, q as WorkbookViewOptions, qn as PageSetup, qt as ConditionalFormatType, r as StreamSheetSpec, rn as TimePeriod, rr as WorkbookProtectionOptions, rt as InspectValue, s as writeWorkbookStream, sn as BorderStyle, sr as hashPassword, st as Note, t as StreamDefinedName, tn as DataValidationType, tr as SheetProtectionOptions, tt as InspectSheet, u as STREAM_LIMIT_DEFAULTS, un as FillStyle, ur as ShaAlgorithm, ut as NoteInput, v as ReadTableOptions, vn as UnderlineStyle, vr as XlvErrorInit, vt as Formula, w as TableValue, wn as ChartKind, wr as DEFAULT_READ_LIMITS, wt as SheetKind, x as TableIssue, xn as ChartAxis, xr as XlvWarning, xt as RichTextRun, y as TableColumn, yn as VerticalAlignRun, yr as XlvErrorJSON, yt as FormulaKind, z as ErrorValue, zn as imageFormat, zt as CfIcon } from "./stream-write-XnCyLdOy.js";
 /**
  * Options for {@link toCSV}.
  *
@@ -14,7 +14,11 @@ interface ToCSVOptions {
   readonly sheet?: string;
   /** Only this range, for example `"A1:D100"`. Default: from A1 to the last used row and column. */
   readonly range?: string;
-  /** Field separator: one character other than `"`, CR or LF. Default `","`. */
+  /**
+   * Field separator: one character other than `"`, CR or LF. Default `","`. While formulas are
+   * escaped (`formulaInjection: "escape"`), `=`, `+`, `-`, `@` and their full-width and small forms
+   * are refused, because a line whose first field is empty would start with them.
+   */
   readonly delimiter?: string;
   /** Line ending. Default `"\r\n"` (RFC 4180). */
   readonly newline?: "\r\n" | "\n";
@@ -22,7 +26,8 @@ interface ToCSVOptions {
   readonly bom?: boolean;
   /**
    * `"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
+   * forms, a control character (tab, CR, LF, NUL, …) or a byte order mark (U+FEFF, U+FFFE, which
+   * spreadsheet applications drop at the start of a file) 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.
    */
@@ -33,8 +38,9 @@ interface ToCSVOptions {
   readonly onWarning?: (warning: XlvWarning) => void;
 }
 /**
- * Converts a sheet to CSV text. Fields that contain the delimiter, a quote, CR or LF are
- * enclosed in quotes, and quotes are doubled (RFC 4180). Numbers are written in JavaScript's
+ * Converts a sheet to CSV text. Fields that contain the delimiter, a quote, CR, LF, or one of
+ * the common separators `,`, `;`, tab and `|` (whatever the delimiter, CSV-14) are enclosed in
+ * quotes, and quotes are doubled (RFC 4180). Numbers are written in JavaScript's
  * shortest form, booleans as `TRUE`/`FALSE`, dates as ISO 8601, error cells as their code and
  * formula cells as their cached value. By default, text that a spreadsheet would run as a
  * formula is escaped (`formulaInjection: "escape"`).
@@ -266,7 +272,12 @@ interface CellEdit {
  * ```
  */
 interface EditOptions {
-  /** Read limits for the input file; see `ReadLimits`. */
+  /**
+   * Read limits for the input file; see `ReadLimits`. For `editCells` and `appendRows`,
+   * `maxCells` also bounds the edit: the cells of the edited sheets plus the new cells must not
+   * exceed it, and one call writes at most 1 000 000 cells unless `maxCells` is given, in which
+   * case it writes at most `maxCells` (`XLV_E_LIMIT_EXCEEDED`, `details.limit` `"maxCells"`).
+   */
   readonly limits?: Partial<ReadLimits>;
 }
 /**
@@ -329,10 +340,14 @@ export declare function editCells(input: Uint8Array | ArrayBuffer, edits: readon
  * Appends rows below the last used row of a sheet (the rows of merged ranges count as used) in
  * an existing XLSX file, editing the file surgically like {@link editCells}. Object rows are
  * placed under the matching header columns (unknown keys throw `XLV_E_INVALID_ROWS` with
- * suggestions); array rows start at the first used column. A table whose last row is the sheet's last used row grows to include the new
- * rows (its range and filter); if that table has a totals row the call is refused with
+ * suggestions). Array rows start at the first used column, or, when the new rows extend a table
+ * (one that reaches the last used row), at that table's first column; when several such tables
+ * start in different columns the call is refused with `XLV_E_INVALID_ARGUMENT` (pass object rows
+ * instead). A table whose last row is the sheet's last used row grows to include the new rows
+ * (its range and filter); if that table has a totals row the call is refused with
  * `XLV_E_NOT_SUPPORTED` and a hint to insert the rows above the totals row with `insertRows`.
- * Calculated columns are not filled in the new rows.
+ * Calculated columns are not filled in the new rows. One call writes at most 1 000 000 cells
+ * unless `limits.maxCells` is given (see `EditOptions`).
  *
  * @example
  * ```ts
@@ -343,6 +358,9 @@ export declare function editCells(input: Uint8Array | ArrayBuffer, edits: readon
  *   { Customer: 'Alice', Total: 120.5 },
  *   { Customer: 'Bob', Total: 80 },
  * ]);
+ * // Array rows that extend a table start at the table's first column.
+ * const { bytes: more } = appendRows(updated, 'Orders', [['Carol', 64]]);
+ * console.log(more.length);
  * ```
  */
 export declare function appendRows(input: Uint8Array | ArrayBuffer, sheet: string, rows: readonly (readonly CellInput[])[] | readonly Readonly<Record<string, CellInput>>[], options?: AppendRowsOptions): EditResult;
@@ -367,6 +385,8 @@ interface InsertRowsOptions extends EditOptions {
   /**
    * Formatting of the new rows: `'above'` copies the row format, height and cell formats of the row
    * above, `'below'` those of the row that is pushed down, `'none'` (default) leaves them empty.
+   * The copied cell formats are cells that count against `limits.maxCells` with the cells of the
+   * workbook (`XLV_E_LIMIT_EXCEEDED` above it).
    */
   readonly style?: "above" | "below" | "none";
 }
@@ -403,7 +423,9 @@ interface DeleteRowsOptions extends EditOptions {
  * custom sheet views, other extended content that refers to cells (sparklines, slicers) and
  * other related parts xlvane does not know; charts or pivot tables anywhere in the workbook that
  * may refer to the sheet; data tables; an array formula the change would split; and formulas it
- * cannot rewrite safely (docs/facts/ref-adjust.md).
+ * cannot rewrite safely (docs/facts/ref-adjust.md). Rows formatted with `style` add a formatted
+ * cell for each formatted cell of the row they copy; when the workbook would then hold more cells
+ * than `limits.maxCells`, the call throws `XLV_E_LIMIT_EXCEEDED` before building them.
  *
  * @example
  * ```ts
@@ -517,4 +539,4 @@ export declare function adjustRange(sqref: string, change: ReferenceChange): str
  * ```
  */
 export declare function shiftFormula(text: string, dRow: number, dCol: number): string | null;
-export { type AddSheetOptions, type AlignmentStyle, type AnchorMarker, type AppendRowsOptions, type BorderEdge, type BorderLineStyle, type BorderStyle, type CalculationOptions, type Cell, type CellChange, type CellEdit, type CellInput, type CellStyle, type CellType, type CellValue, type CfIcon, type CfValue, type CfValueInput, type CfValueType, type Color, type ColumnInfo, type ColumnOptions, type ConditionalFormat, type ConditionalFormatOperator, type ConditionalFormatRule, type ConditionalFormatRuleInput, type ConditionalFormatType, type Conformance, type CreateWorkbookOptions, DEFAULT_READ_LIMITS, type DataBarAxisPosition, type DataBarDirection, type DataValidation, type DataValidationErrorStyle, type DataValidationImeMode, type DataValidationOperator, type DataValidationRule, type DataValidationType, type DateSystem, type DefinedName, type DefinedNameOptions, type DeleteRowsOptions, type DiffCell, type DiffOptions, ERROR_CODES, ERROR_VALUES, type EditOptions, type EditResult, type ErrorValue, type FillStyle, type FontScheme, type FontStyle, type Formula, type FormulaKind, type FormulaResult, type FreezeOptions, type FromCSVOptions, type FrozenPanes, type GradientFill, type HashPasswordOptions, type HeaderFooter, type HorizontalAlignment, type Hyperlink, type HyperlinkTarget, type IconSetType, type ImageAnchor, type ImageAnchorInput, type ImageFormat, type ImageOptions, type ImagePositionInput, type InsertRowsOptions, type InspectColumn, type InspectDefinedName, type InspectOptions, type InspectReport, type InspectSheet, type InspectTypeCounts, type InspectValue, type JsonTable, NewSheet, NewWorkbook, type Note, type NoteBox, type NoteBoxInput, type NoteInput, type NoteMargins, type OpenWorkbookStreamOptions, type PageBreaks, type PageMargins, type PageOrder, type PageOrientation, type PageSetup, type PageSetupOptions, type PasswordHash, type PasswordVerifier, type PatternType, type PrintCellComments, type PrintErrors, type PrintOptions, type PrintTitles, type ProtectionStyle, type ReadLimits, type ReadOptions, type ReadTableOptions, type ReadTableStreamOptions, type ReadingOrder, type ReferenceChange, type RichTextRun, type RowInfo, type RowOptions, STREAM_LIMIT_DEFAULTS, type ShaAlgorithm, type Sheet, type SheetDiff, type SheetImage, type SheetKind, type SheetLayout, type SheetProperties, type SheetPropertiesOptions, type SheetProtection, type SheetProtectionFlags, type SheetProtectionOptions, type SheetState, type SheetView, type SheetViewOptions, type SplitPanes, type StandardSchemaV1, type StreamDefinedName, type StreamRow, type StreamRowInput, type StreamSheetInfo, type StreamSheetSpec, type TableColumn, type TableColumnInput, type TableColumnSpec, type TableDefinition, type TableDefinitionColumn, type TableInput, type TableIssue, type TableResult, type TableRow, type TableStreamItem, type TableStyleOptions, type TableValue, type TimePeriod, type ToCSVOptions, type ToJSONOptions, type TotalsRowFunction, type UnderlineStyle, type VerticalAlignRun, type VerticalAlignment, WARNING_CODES, type Workbook, type WorkbookDiff, type WorkbookFormat, type WorkbookImage, type WorkbookProperties, type WorkbookProtection, type WorkbookProtectionOptions, type WorkbookStream, type WorkbookView, type WorkbookViewOptions, type WriteTableOptions, type WriteTableStreamOptions, type WriteWorkbookOptions, type WriteWorkbookStreamOptions, type XlvDetailValue, type XlvDetails, XlvError, type XlvErrorCode, type XlvErrorInit, type XlvErrorJSON, type XlvLocation, type XlvWarning, type XlvWarningCode, createWorkbook, fromJSON, hashPassword, imageFormat, inspect, isXlvError, legacyPasswordHash, openWorkbookStream, readTable, readTableAsync, readTableStream, readWorkbook, toJSON, verifyPassword, writeTable, writeTableStream, writeWorkbook, writeWorkbookStream };
+export { type AddSheetOptions, type AlignmentStyle, type AnchorMarker, type AppendRowsOptions, type BorderEdge, type BorderLineStyle, type BorderStyle, type CalculationOptions, type Cell, type CellChange, type CellEdit, type CellInput, type CellStyle, type CellType, type CellValue, type CfIcon, type CfValue, type CfValueInput, type CfValueType, type ChartAxis, type ChartAxisInput, type ChartInput, type ChartKind, type ChartLegendPosition, type ChartSeries, type ChartSeriesInput, type ChartText, type ChartType, type Color, type ColumnInfo, type ColumnOptions, type ConditionalFormat, type ConditionalFormatOperator, type ConditionalFormatRule, type ConditionalFormatRuleInput, type ConditionalFormatType, type Conformance, type CreateWorkbookOptions, DEFAULT_READ_LIMITS, type DataBarAxisPosition, type DataBarDirection, type DataValidation, type DataValidationErrorStyle, type DataValidationImeMode, type DataValidationOperator, type DataValidationRule, type DataValidationType, type DateSystem, type DefinedName, type DefinedNameOptions, type DeleteRowsOptions, type DiffCell, type DiffOptions, ERROR_CODES, ERROR_VALUES, type EditOptions, type EditResult, type ErrorValue, type FillStyle, type FontScheme, type FontStyle, type Formula, type FormulaKind, type FormulaResult, type FreezeOptions, type FromCSVOptions, type FrozenPanes, type GradientFill, type HashPasswordOptions, type HeaderFooter, type HorizontalAlignment, type Hyperlink, type HyperlinkTarget, type IconSetType, type ImageAnchor, type ImageAnchorInput, type ImageFormat, type ImageOptions, type ImagePositionInput, type InsertRowsOptions, type InspectColumn, type InspectDefinedName, type InspectOptions, type InspectReport, type InspectSheet, type InspectTypeCounts, type InspectValue, type JsonTable, NewSheet, NewWorkbook, type Note, type NoteBox, type NoteBoxInput, type NoteInput, type NoteMargins, type OpenWorkbookStreamOptions, type PageBreaks, type PageMargins, type PageOrder, type PageOrientation, type PageSetup, type PageSetupOptions, type PasswordHash, type PasswordVerifier, type PatternType, type PrintCellComments, type PrintErrors, type PrintOptions, type PrintTitles, type ProtectionStyle, type ReadLimits, type ReadOptions, type ReadTableOptions, type ReadTableStreamOptions, type ReadingOrder, type ReferenceChange, type RichTextRun, type RowInfo, type RowOptions, STREAM_LIMIT_DEFAULTS, type ShaAlgorithm, type Sheet, type SheetChart, type SheetDiff, type SheetImage, type SheetKind, type SheetLayout, type SheetProperties, type SheetPropertiesOptions, type SheetProtection, type SheetProtectionFlags, type SheetProtectionOptions, type SheetState, type SheetView, type SheetViewOptions, type SplitPanes, type StandardSchemaV1, type StreamDefinedName, type StreamRow, type StreamRowInput, type StreamSheetInfo, type StreamSheetSpec, type TableColumn, type TableColumnInput, type TableColumnSpec, type TableDefinition, type TableDefinitionColumn, type TableInput, type TableIssue, type TableResult, type TableRow, type TableStreamItem, type TableStyleOptions, type TableValue, type TimePeriod, type ToCSVOptions, type ToJSONOptions, type TotalsRowFunction, type UnderlineStyle, type VerticalAlignRun, type VerticalAlignment, WARNING_CODES, type Workbook, type WorkbookDiff, type WorkbookFormat, type WorkbookImage, type WorkbookProperties, type WorkbookProtection, type WorkbookProtectionOptions, type WorkbookStream, type WorkbookView, type WorkbookViewOptions, type WriteTableOptions, type WriteTableStreamOptions, type WriteWorkbookOptions, type WriteWorkbookStreamOptions, type XlvDetailValue, type XlvDetails, XlvError, type XlvErrorCode, type XlvErrorInit, type XlvErrorJSON, type XlvLocation, type XlvWarning, type XlvWarningCode, createWorkbook, fromJSON, hashPassword, imageFormat, inspect, isXlvError, legacyPasswordHash, openWorkbookStream, readTable, readTableAsync, readTableStream, readWorkbook, toJSON, verifyPassword, writeTable, writeTableStream, writeWorkbook, writeWorkbookStream };

package/dist/index.js

@@ -1,4 +1,4 @@
-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";
+import { Bn as isXlvError, Gt as hashPassword, Kt as legacyPasswordHash, Ln as ERROR_CODES, Lt as DEFAULT_READ_LIMITS, Qt as imageFormat, Rn as WARNING_CODES, _ as inspect, c as NewSheet, dn as shiftFormula, f as createWorkbook, l as NewWorkbook, m as writeWorkbook, qt as verifyPassword, s as ERROR_VALUES, x as readWorkbook, zn as XlvError } from "./options-Cxt-LJE4.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-DltZ-hiW.js";
+import { a as readTableStream, i as openWorkbookStream, n as writeWorkbookStream, r as STREAM_LIMIT_DEFAULTS, t as writeTableStream } from "./stream-write-D573ewpr.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-CDb6TyZb.js → node-files-SVg17pky.js}

@@ -1,4 +1,4 @@
-import { Bt as resolveLimits, On as XlvError } from "./options-Ba1iWD-Z.js";
+import { Bt as resolveLimits, zn as XlvError } from "./options-Cxt-LJE4.js";
 import { readFile, stat } from "node:fs/promises";
 // src/util/node-files.ts
 /** The path as shown in messages. */
@@ -12,7 +12,7 @@ async function checkFile(path, limits) {
 		const info = await stat(path);
 		if (!info.isFile()) throw new XlvError("XLV_E_FILE_READ", `"${shown}" is not a file.`, {
 			location: {},
-			hint: "Pass the path of an .xlsx file, not a directory.",
+			hint: info.isDirectory() ? "Pass the path of an .xlsx file, not a directory." : "Pass the path of an .xlsx file, not a pipe, device or other special file.",
 			details: { path: shown }
 		});
 		size = info.size;

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-BVaFkgwO.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-XnCyLdOy.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 { 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 { Bt as resolveLimits, _ as inspect, m as writeWorkbook, x as readWorkbook, zn as XlvError } from "./options-Cxt-LJE4.js";
+import { i as readInput, n as describePath, r as fileError, t as checkFile } from "./node-files-SVg17pky.js";
+import { i as openWorkbookStream, n as writeWorkbookStream, r as STREAM_LIMIT_DEFAULTS } from "./stream-write-D573ewpr.js";
 import { openAsBlob } from "node:fs";
 import { open, unlink, writeFile } from "node:fs/promises";
 // src/node.ts