@vectojs/numera-cli 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.0
+
+### Minor Changes
+
+- d7e3400: Add safe local workbook inspect, get, and explicit-output set commands for
+  Numera JSON, CSV, and XLSX files.
+
+All notable changes to this project are documented in this file.
+
+## Unreleased
+
+### Added
+
+- Safe local `inspect`, `get`, and explicit-output `set` commands for Numera
+  JSON, CSV, and XLSX workbooks.
+- Atomic same-directory output replacement and stable command diagnostics.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xuepoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @vectojs/numera-cli
+
+> Safe, local-first workbook automation for Numera.
+
+`@vectojs/numera-cli` is the command-line boundary for inspecting and editing
+offline Numera workbooks. It uses the published Core document model and guarded
+XLSX adapter; it does not start a browser, render a UI, contact a service, or
+perform an implicit in-place write.
+
+## Install
+
+```bash
+npm install --global @vectojs/numera-cli
+```
+
+## Commands
+
+```bash
+numera inspect budget.xlsx --json
+numera get budget.xlsx "Sheet 1" A1:C3 --json
+numera set budget.xlsx "Sheet 1" B2 --number 42 --output budget-edited.xlsx
+```
+
+`set` always requires a distinct output path. A successful command writes an
+atomically replaced output file, leaving the input untouched.
+
+All command output is JSON so shell scripts and future agent tools can consume
+it without screen scraping. `get` accepts either one A1 address or a normalized
+range such as `A1:C3`.
+
+`set` accepts exactly one explicit value mode: `--text`, `--number`,
+`--boolean true|false`, or `--formula`. Formula source gets a leading `=` when
+needed; no input type is inferred from a text argument.
+
+## Formats
+
+- `.xlsx` reads and writes through `@vectojs/numera-xlsx`.
+- `.numera.json` uses Numera Core’s versioned snapshot codec.
+- `.csv` contains one selected worksheet and cannot represent workbook-wide
+  formatting or multiple sheets.
+
+## Verify
+
+```bash
+bun install
+bun run verify
+npm pack --dry-run
+```
+
+## License
+
+[MIT](./LICENSE) © 2026 Xuepoo

package/dist/CliError.d.ts

@@ -0,0 +1,7 @@
+export type CliErrorCode = "INVALID_ARGUMENT" | "INPUT_FORMAT_UNSUPPORTED" | "OUTPUT_FORMAT_UNSUPPORTED" | "SHEET_NOT_FOUND" | "RANGE_OUT_OF_BOUNDS" | "OUTPUT_EQUALS_INPUT";
+/** Stable command diagnostic that is safe to display to automation callers. */
+export declare class CliError extends Error {
+    readonly code: CliErrorCode;
+    constructor(code: CliErrorCode, message: string);
+}
+//# sourceMappingURL=CliError.d.ts.map

package/dist/CliError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CliError.d.ts","sourceRoot":"","sources":["../src/CliError.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,0BAA0B,GAC1B,2BAA2B,GAC3B,iBAAiB,GACjB,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,+EAA+E;AAC/E,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,IAAI,EAAE,YAAY;IAD7B,YACW,IAAI,EAAE,YAAY,EAC3B,OAAO,EAAE,MAAM,EAIhB;CACF"}

package/dist/a1.d.ts

@@ -0,0 +1,7 @@
+import { type Rect } from "@vectojs/numera-core";
+export declare function parseCellAddress(source: string): {
+    row: number;
+    col: number;
+};
+export declare function parseCellRange(source: string): Rect;
+//# sourceMappingURL=a1.d.ts.map

package/dist/a1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a1.d.ts","sourceRoot":"","sources":["../src/a1.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAItE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAK7E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAanD"}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+interface ParsedSetValue {
+    raw: string;
+    output: string;
+}
+declare function run(arguments_: string[]): Promise<string>;
+declare function parseSetValue(arguments_: string[]): ParsedSetValue;
+export { parseSetValue, run };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAMA,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iBAAe,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BxD;AAED,iBAAS,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,cAAc,CA2B3D;AAiBD,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC"}

package/dist/cli.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  parseSetValue: () => parseSetValue,
+  run: () => run
+});
+module.exports = __toCommonJS(cli_exports);
+
+// src/CliError.ts
+var CliError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CliError";
+  }
+  code;
+};
+
+// src/commands.ts
+var import_numera_core3 = require("@vectojs/numera-core");
+var import_node_path = require("path");
+
+// src/a1.ts
+var import_numera_core = require("@vectojs/numera-core");
+function parseCellAddress(source) {
+  const cell = (0, import_numera_core.parseA1)(source.toUpperCase());
+  if (!cell)
+    throw new CliError("INVALID_ARGUMENT", `Invalid cell address: ${source}`);
+  return cell;
+}
+function parseCellRange(source) {
+  const normalized = source.toUpperCase();
+  const range = normalized.includes(":") ? (0, import_numera_core.parseRange)(normalized) : (() => {
+    const cell = (0, import_numera_core.parseA1)(normalized);
+    return cell ? { r1: cell.row, c1: cell.col, r2: cell.row, c2: cell.col } : null;
+  })();
+  if (!range)
+    throw new CliError("INVALID_ARGUMENT", `Invalid cell range: ${source}`);
+  return range;
+}
+
+// src/workbookFiles.ts
+var import_numera_core2 = require("@vectojs/numera-core");
+var import_numera_xlsx = require("@vectojs/numera-xlsx");
+var import_promises = require("fs/promises");
+function detectWorkbookFormat(path) {
+  const normalized = path.toLowerCase();
+  if (normalized.endsWith(".xlsx")) return "xlsx";
+  if (normalized.endsWith(".csv")) return "csv";
+  if (normalized.endsWith(".numera.json") || normalized.endsWith(".json"))
+    return "json";
+  throw new CliError(
+    "INPUT_FORMAT_UNSUPPORTED",
+    `Unsupported input format: ${path}`
+  );
+}
+async function loadWorkbook(path) {
+  const format = detectWorkbookFormat(path);
+  const file = Bun.file(path);
+  if (!await file.exists())
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      `Input file does not exist: ${path}`
+    );
+  if (format === "xlsx")
+    return {
+      format,
+      workbook: await (0, import_numera_xlsx.decodeXlsx)(new Uint8Array(await file.arrayBuffer()))
+    };
+  const source = await file.text();
+  if (format === "json") return { format, workbook: (0, import_numera_core2.parseWorkbookJson)(source) };
+  const workbook = new import_numera_core2.Workbook();
+  const sheet = workbook.activeSheet.model;
+  for (const write of (0, import_numera_core2.fromCsv)(
+    source,
+    { row: 0, col: 0 },
+    { rows: sheet.rows, cols: sheet.cols }
+  ))
+    sheet.setCell(write.row, write.col, write.raw);
+  return { format, workbook };
+}
+async function serializeWorkbook(workbook, outputPath, sheetName) {
+  const format = detectOutputFormat(outputPath);
+  if (format === "xlsx") return (0, import_numera_xlsx.encodeXlsx)(workbook);
+  if (format === "json") return (0, import_numera_core2.toWorkbookJson)(workbook);
+  const sheet = sheetName ? findSheet(workbook, sheetName).model : workbook.activeSheet.model;
+  const used = sheet.getUsedRange();
+  const range = used ?? { r1: 0, c1: 0, r2: 0, c2: 0 };
+  return (0, import_numera_core2.toCsv)(sheet, range);
+}
+function findSheet(workbook, name) {
+  const sheet = workbook.sheets.find((candidate) => candidate.name === name);
+  if (!sheet) throw new CliError("SHEET_NOT_FOUND", `Sheet not found: ${name}`);
+  return sheet;
+}
+async function writeOutputAtomically(outputPath, content) {
+  const temporaryPath = `${outputPath}.numera-${crypto.randomUUID()}.tmp`;
+  try {
+    await Bun.write(temporaryPath, content);
+    await (0, import_promises.rename)(temporaryPath, outputPath);
+  } finally {
+    await (0, import_promises.rm)(temporaryPath, { force: true });
+  }
+}
+function detectOutputFormat(path) {
+  try {
+    return detectWorkbookFormat(path);
+  } catch {
+    throw new CliError(
+      "OUTPUT_FORMAT_UNSUPPORTED",
+      `Unsupported output format: ${path}`
+    );
+  }
+}
+
+// src/commands.ts
+function inspectWorkbook(workbook, format) {
+  return {
+    format,
+    activeSheet: workbook.activeSheet.name,
+    sheets: workbook.sheets.map((sheet) => ({
+      name: sheet.name,
+      populatedCells: sheet.model.cellCount,
+      rows: sheet.model.rows,
+      cols: sheet.model.cols
+    }))
+  };
+}
+function getRange(workbook, sheetName, sourceRange) {
+  const sheet = findSheet(workbook, sheetName).model;
+  const range = parseCellRange(sourceRange);
+  if (range.r2 >= sheet.rows || range.c2 >= sheet.cols)
+    throw new CliError(
+      "RANGE_OUT_OF_BOUNDS",
+      `Range is outside sheet bounds: ${sourceRange}`
+    );
+  const cells = [];
+  for (let row = range.r1; row <= range.r2; row++) {
+    for (let col = range.c1; col <= range.c2; col++) {
+      cells.push({
+        address: (0, import_numera_core3.toA1)({ row, col }),
+        raw: sheet.getRaw(row, col),
+        display: sheet.getDisplay(row, col)
+      });
+    }
+  }
+  return { sheet: sheetName, range: sourceRange.toUpperCase(), cells };
+}
+async function setCellAndWrite(workbook, sourcePath, sheetName, address, raw, outputPath) {
+  if (samePath(sourcePath, outputPath))
+    throw new CliError(
+      "OUTPUT_EQUALS_INPUT",
+      "--output must differ from the input path"
+    );
+  const cell = parseCellAddress(address);
+  const sheet = findSheet(workbook, sheetName).model;
+  expandSheetToCell(sheet, cell.row, cell.col);
+  sheet.setCell(cell.row, cell.col, raw);
+  await writeOutputAtomically(
+    outputPath,
+    await serializeWorkbook(workbook, outputPath, sheetName)
+  );
+}
+function expandSheetToCell(sheet, row, col) {
+  if (row < sheet.rows && col < sheet.cols) return;
+  const snapshot = sheet.toSnapshot();
+  sheet.restoreSnapshot({
+    ...snapshot,
+    rows: Math.max(sheet.rows, row + 1),
+    cols: Math.max(sheet.cols, col + 1)
+  });
+}
+function samePath(left, right) {
+  return (0, import_node_path.resolve)(left) === (0, import_node_path.resolve)(right);
+}
+
+// src/cli.ts
+async function run(arguments_) {
+  const [command, path, sheetName, target, ...rest] = arguments_;
+  if (command === "inspect" && path) {
+    const loaded = await loadWorkbook(path);
+    return JSON.stringify(inspectWorkbook(loaded.workbook, loaded.format));
+  }
+  if (command === "get" && path && sheetName && target) {
+    const loaded = await loadWorkbook(path);
+    return JSON.stringify(getRange(loaded.workbook, sheetName, target));
+  }
+  if (command === "set" && path && sheetName && target) {
+    const value = parseSetValue(rest);
+    const loaded = await loadWorkbook(path);
+    await setCellAndWrite(
+      loaded.workbook,
+      path,
+      sheetName,
+      target,
+      value.raw,
+      value.output
+    );
+    return JSON.stringify({
+      output: value.output,
+      sheet: sheetName,
+      address: target.toUpperCase()
+    });
+  }
+  throw new CliError("INVALID_ARGUMENT", usage());
+}
+function parseSetValue(arguments_) {
+  let raw;
+  let output;
+  for (let index = 0; index < arguments_.length; index += 2) {
+    const flag = arguments_[index];
+    const value = arguments_[index + 1];
+    if (!value)
+      throw new CliError("INVALID_ARGUMENT", `Missing value for ${flag}`);
+    if (flag === "--text") raw = value;
+    else if (flag === "--number") {
+      if (!Number.isFinite(Number(value)))
+        throw new CliError("INVALID_ARGUMENT", `Invalid number: ${value}`);
+      raw = value;
+    } else if (flag === "--boolean") {
+      if (value !== "true" && value !== "false")
+        throw new CliError("INVALID_ARGUMENT", `Invalid boolean: ${value}`);
+      raw = value.toUpperCase();
+    } else if (flag === "--formula")
+      raw = value.startsWith("=") ? value : `=${value}`;
+    else if (flag === "--output") output = value;
+    else throw new CliError("INVALID_ARGUMENT", `Unknown option: ${flag}`);
+  }
+  if (raw === void 0)
+    throw new CliError("INVALID_ARGUMENT", "set requires one value flag");
+  if (!output)
+    throw new CliError("INVALID_ARGUMENT", "set requires --output <path>");
+  return { raw, output };
+}
+function usage() {
+  return "Usage: numera inspect <file> | get <file> <sheet> <range> | set <file> <sheet> <cell> (--text|--number|--boolean|--formula) <value> --output <file>";
+}
+void run(Bun.argv.slice(2)).then((output) => process.stdout.write(`${output}
+`)).catch((error) => {
+  const diagnostic = error instanceof CliError ? `${error.code}: ${error.message}` : `UNEXPECTED: ${String(error)}`;
+  process.stderr.write(`${diagnostic}
+`);
+  process.exitCode = 1;
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseSetValue,
+  run
+});

package/dist/cli.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+// src/CliError.ts
+var CliError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CliError";
+  }
+  code;
+};
+
+// src/commands.ts
+import { toA1 } from "@vectojs/numera-core";
+import { resolve } from "path";
+
+// src/a1.ts
+import { parseA1, parseRange } from "@vectojs/numera-core";
+function parseCellAddress(source) {
+  const cell = parseA1(source.toUpperCase());
+  if (!cell)
+    throw new CliError("INVALID_ARGUMENT", `Invalid cell address: ${source}`);
+  return cell;
+}
+function parseCellRange(source) {
+  const normalized = source.toUpperCase();
+  const range = normalized.includes(":") ? parseRange(normalized) : (() => {
+    const cell = parseA1(normalized);
+    return cell ? { r1: cell.row, c1: cell.col, r2: cell.row, c2: cell.col } : null;
+  })();
+  if (!range)
+    throw new CliError("INVALID_ARGUMENT", `Invalid cell range: ${source}`);
+  return range;
+}
+
+// src/workbookFiles.ts
+import {
+  fromCsv,
+  parseWorkbookJson,
+  toCsv,
+  toWorkbookJson,
+  Workbook
+} from "@vectojs/numera-core";
+import { decodeXlsx, encodeXlsx } from "@vectojs/numera-xlsx";
+import { rename, rm } from "fs/promises";
+function detectWorkbookFormat(path) {
+  const normalized = path.toLowerCase();
+  if (normalized.endsWith(".xlsx")) return "xlsx";
+  if (normalized.endsWith(".csv")) return "csv";
+  if (normalized.endsWith(".numera.json") || normalized.endsWith(".json"))
+    return "json";
+  throw new CliError(
+    "INPUT_FORMAT_UNSUPPORTED",
+    `Unsupported input format: ${path}`
+  );
+}
+async function loadWorkbook(path) {
+  const format = detectWorkbookFormat(path);
+  const file = Bun.file(path);
+  if (!await file.exists())
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      `Input file does not exist: ${path}`
+    );
+  if (format === "xlsx")
+    return {
+      format,
+      workbook: await decodeXlsx(new Uint8Array(await file.arrayBuffer()))
+    };
+  const source = await file.text();
+  if (format === "json") return { format, workbook: parseWorkbookJson(source) };
+  const workbook = new Workbook();
+  const sheet = workbook.activeSheet.model;
+  for (const write of fromCsv(
+    source,
+    { row: 0, col: 0 },
+    { rows: sheet.rows, cols: sheet.cols }
+  ))
+    sheet.setCell(write.row, write.col, write.raw);
+  return { format, workbook };
+}
+async function serializeWorkbook(workbook, outputPath, sheetName) {
+  const format = detectOutputFormat(outputPath);
+  if (format === "xlsx") return encodeXlsx(workbook);
+  if (format === "json") return toWorkbookJson(workbook);
+  const sheet = sheetName ? findSheet(workbook, sheetName).model : workbook.activeSheet.model;
+  const used = sheet.getUsedRange();
+  const range = used ?? { r1: 0, c1: 0, r2: 0, c2: 0 };
+  return toCsv(sheet, range);
+}
+function findSheet(workbook, name) {
+  const sheet = workbook.sheets.find((candidate) => candidate.name === name);
+  if (!sheet) throw new CliError("SHEET_NOT_FOUND", `Sheet not found: ${name}`);
+  return sheet;
+}
+async function writeOutputAtomically(outputPath, content) {
+  const temporaryPath = `${outputPath}.numera-${crypto.randomUUID()}.tmp`;
+  try {
+    await Bun.write(temporaryPath, content);
+    await rename(temporaryPath, outputPath);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+}
+function detectOutputFormat(path) {
+  try {
+    return detectWorkbookFormat(path);
+  } catch {
+    throw new CliError(
+      "OUTPUT_FORMAT_UNSUPPORTED",
+      `Unsupported output format: ${path}`
+    );
+  }
+}
+
+// src/commands.ts
+function inspectWorkbook(workbook, format) {
+  return {
+    format,
+    activeSheet: workbook.activeSheet.name,
+    sheets: workbook.sheets.map((sheet) => ({
+      name: sheet.name,
+      populatedCells: sheet.model.cellCount,
+      rows: sheet.model.rows,
+      cols: sheet.model.cols
+    }))
+  };
+}
+function getRange(workbook, sheetName, sourceRange) {
+  const sheet = findSheet(workbook, sheetName).model;
+  const range = parseCellRange(sourceRange);
+  if (range.r2 >= sheet.rows || range.c2 >= sheet.cols)
+    throw new CliError(
+      "RANGE_OUT_OF_BOUNDS",
+      `Range is outside sheet bounds: ${sourceRange}`
+    );
+  const cells = [];
+  for (let row = range.r1; row <= range.r2; row++) {
+    for (let col = range.c1; col <= range.c2; col++) {
+      cells.push({
+        address: toA1({ row, col }),
+        raw: sheet.getRaw(row, col),
+        display: sheet.getDisplay(row, col)
+      });
+    }
+  }
+  return { sheet: sheetName, range: sourceRange.toUpperCase(), cells };
+}
+async function setCellAndWrite(workbook, sourcePath, sheetName, address, raw, outputPath) {
+  if (samePath(sourcePath, outputPath))
+    throw new CliError(
+      "OUTPUT_EQUALS_INPUT",
+      "--output must differ from the input path"
+    );
+  const cell = parseCellAddress(address);
+  const sheet = findSheet(workbook, sheetName).model;
+  expandSheetToCell(sheet, cell.row, cell.col);
+  sheet.setCell(cell.row, cell.col, raw);
+  await writeOutputAtomically(
+    outputPath,
+    await serializeWorkbook(workbook, outputPath, sheetName)
+  );
+}
+function expandSheetToCell(sheet, row, col) {
+  if (row < sheet.rows && col < sheet.cols) return;
+  const snapshot = sheet.toSnapshot();
+  sheet.restoreSnapshot({
+    ...snapshot,
+    rows: Math.max(sheet.rows, row + 1),
+    cols: Math.max(sheet.cols, col + 1)
+  });
+}
+function samePath(left, right) {
+  return resolve(left) === resolve(right);
+}
+
+// src/cli.ts
+async function run(arguments_) {
+  const [command, path, sheetName, target, ...rest] = arguments_;
+  if (command === "inspect" && path) {
+    const loaded = await loadWorkbook(path);
+    return JSON.stringify(inspectWorkbook(loaded.workbook, loaded.format));
+  }
+  if (command === "get" && path && sheetName && target) {
+    const loaded = await loadWorkbook(path);
+    return JSON.stringify(getRange(loaded.workbook, sheetName, target));
+  }
+  if (command === "set" && path && sheetName && target) {
+    const value = parseSetValue(rest);
+    const loaded = await loadWorkbook(path);
+    await setCellAndWrite(
+      loaded.workbook,
+      path,
+      sheetName,
+      target,
+      value.raw,
+      value.output
+    );
+    return JSON.stringify({
+      output: value.output,
+      sheet: sheetName,
+      address: target.toUpperCase()
+    });
+  }
+  throw new CliError("INVALID_ARGUMENT", usage());
+}
+function parseSetValue(arguments_) {
+  let raw;
+  let output;
+  for (let index = 0; index < arguments_.length; index += 2) {
+    const flag = arguments_[index];
+    const value = arguments_[index + 1];
+    if (!value)
+      throw new CliError("INVALID_ARGUMENT", `Missing value for ${flag}`);
+    if (flag === "--text") raw = value;
+    else if (flag === "--number") {
+      if (!Number.isFinite(Number(value)))
+        throw new CliError("INVALID_ARGUMENT", `Invalid number: ${value}`);
+      raw = value;
+    } else if (flag === "--boolean") {
+      if (value !== "true" && value !== "false")
+        throw new CliError("INVALID_ARGUMENT", `Invalid boolean: ${value}`);
+      raw = value.toUpperCase();
+    } else if (flag === "--formula")
+      raw = value.startsWith("=") ? value : `=${value}`;
+    else if (flag === "--output") output = value;
+    else throw new CliError("INVALID_ARGUMENT", `Unknown option: ${flag}`);
+  }
+  if (raw === void 0)
+    throw new CliError("INVALID_ARGUMENT", "set requires one value flag");
+  if (!output)
+    throw new CliError("INVALID_ARGUMENT", "set requires --output <path>");
+  return { raw, output };
+}
+function usage() {
+  return "Usage: numera inspect <file> | get <file> <sheet> <range> | set <file> <sheet> <cell> (--text|--number|--boolean|--formula) <value> --output <file>";
+}
+void run(Bun.argv.slice(2)).then((output) => process.stdout.write(`${output}
+`)).catch((error) => {
+  const diagnostic = error instanceof CliError ? `${error.code}: ${error.message}` : `UNEXPECTED: ${String(error)}`;
+  process.stderr.write(`${diagnostic}
+`);
+  process.exitCode = 1;
+});
+export {
+  parseSetValue,
+  run
+};

package/dist/commands.d.ts

@@ -0,0 +1,23 @@
+import { type Workbook } from "@vectojs/numera-core";
+export interface InspectResult {
+    format: string;
+    activeSheet: string;
+    sheets: Array<{
+        name: string;
+        populatedCells: number;
+        rows: number;
+        cols: number;
+    }>;
+}
+export declare function inspectWorkbook(workbook: Workbook, format: string): InspectResult;
+export declare function getRange(workbook: Workbook, sheetName: string, sourceRange: string): {
+    sheet: string;
+    range: string;
+    cells: {
+        address: string;
+        raw: string;
+        display: string;
+    }[];
+};
+export declare function setCellAndWrite(workbook: Workbook, sourcePath: string, sheetName: string, address: string, raw: string, outputPath: string): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAW3D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,MAAM,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GACb,aAAa,CAWf;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;;;;;;;;EAoBpB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Programmatic exports are added only for stable CLI utilities. Workbook
+ * semantics remain owned by the published Numera Core and XLSX packages.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);

package/dist/workbookFiles.d.ts

@@ -0,0 +1,12 @@
+import { Workbook } from "@vectojs/numera-core";
+export type WorkbookFileFormat = "csv" | "json" | "xlsx";
+export interface LoadedWorkbook {
+    format: WorkbookFileFormat;
+    workbook: Workbook;
+}
+export declare function detectWorkbookFormat(path: string): WorkbookFileFormat;
+export declare function loadWorkbook(path: string): Promise<LoadedWorkbook>;
+export declare function serializeWorkbook(workbook: Workbook, outputPath: string, sheetName?: string): Promise<Uint8Array | string>;
+export declare function findSheet(workbook: Workbook, name: string): import("@vectojs/numera-core").WorkbookSheet;
+export declare function writeOutputAtomically(outputPath: string, content: Uint8Array | string): Promise<void>;
+//# sourceMappingURL=workbookFiles.d.ts.map

package/dist/workbookFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbookFiles.d.ts","sourceRoot":"","sources":["../src/workbookFiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAM9B,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAUrE;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAwBxE;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,CAU9B;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,gDAIzD;AAED,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,UAAU,GAAG,MAAM,GAC3B,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@vectojs/numera-cli",
+  "version": "0.2.0",
+  "description": "Safe local-first workbook automation CLI for the Numera family.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vectojs/numera-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vectojs/numera-cli/issues"
+  },
+  "homepage": "https://github.com/vectojs/numera-cli#readme",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "numera": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --clean && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "test": "bun test",
+    "format:check": "prettier --check .",
+    "lint": "oxlint --deny-warnings src test",
+    "verify": "bun run format:check && bun run lint && bun test && bun run build"
+  },
+  "dependencies": {
+    "@vectojs/numera-core": "0.3.1",
+    "@vectojs/numera-xlsx": "0.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.3.0",
+    "oxlint": "^1.71.0",
+    "prettier": "^3.9.1",
+    "tsup": "^8.3.5",
+    "typescript": "^7.0.2"
+  }
+}