@lotics/cli 0.32.0 → 0.34.0

package/dist/{src/starter_template.d.ts → starter_template.d.ts}

@@ -40,7 +40,7 @@ export interface StarterFile {
  * fall back here when the lookup fails.
  */
 export declare const STARTER_FALLBACK_UI_VERSION = "1.8.0";
-export declare const STARTER_FALLBACK_SDK_VERSION = "0.8.0";
+export declare const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
 export declare function buildStarterTemplate(args: {
     app_name: string;
     app_id: string;

package/dist/{src/starter_template.js → starter_template.js}

@@ -36,7 +36,7 @@
  * fall back here when the lookup fails.
  */
 export const STARTER_FALLBACK_UI_VERSION = "1.8.0";
-export const STARTER_FALLBACK_SDK_VERSION = "0.8.0";
+export const STARTER_FALLBACK_SDK_VERSION = "0.11.0";
 export function buildStarterTemplate(args) {
     const uiVersion = args.ui_version ?? `^${STARTER_FALLBACK_UI_VERSION}`;
     const sdkVersion = args.sdk_version ?? `^${STARTER_FALLBACK_SDK_VERSION}`;

package/dist/starter_template.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/xlsx.d.ts

@@ -0,0 +1,2 @@
+export declare function printXlsxHelp(): void;
+export declare function runXlsxCommand(subcommand: string | undefined, toolArgs: string | undefined, restArgs: string[]): Promise<void>;

package/dist/xlsx.js

@@ -0,0 +1,489 @@
+import fs from "node:fs";
+import { fail, writeFileAtomic } from "./file_command_io.js";
+import { parseExcelBuffer } from "@lotics/xlsx/excel_parser";
+import { unzipXlsx } from "@lotics/xlsx/ooxml_zip";
+import { exportWorkbook } from "@lotics/xlsx/xlsx_writer";
+import { loadWorkbookFromSnapshot, WorkbookModel, SheetModel, StyleRegistry } from "@lotics/xlsx/workbook_model";
+import { FormulaEngine } from "@lotics/xlsx/formula_engine";
+import { refToRowCol, rowColToRef } from "@lotics/xlsx/excel_utils";
+import { setCellValueCommand, clearRangeCommand, mergeCellsCommand, unmergeCellsCommand, addSheetCommand, deleteSheetCommand, renameSheetCommand, insertRowsCommand, deleteRowsCommand, insertColsCommand, deleteColsCommand, setRangeStyleCommand, } from "@lotics/xlsx/spreadsheet_commands";
+function loadFile(filePath) {
+    if (!fs.existsSync(filePath))
+        fail(`File not found: ${filePath}`);
+    const buffer = fs.readFileSync(filePath);
+    const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    const originalZip = unzipXlsx(arrayBuffer);
+    const parsed = parseExcelBuffer(arrayBuffer);
+    const workbook = loadWorkbookFromSnapshot(parsed);
+    return { workbook, originalZip };
+}
+function exportAndWrite(loaded, filePath) {
+    const bytes = exportWorkbook(loaded.workbook, loaded.originalZip);
+    writeFileAtomic(filePath, bytes);
+}
+function resolveSheetIndex(workbook, sheetName) {
+    const index = workbook.sheets.findIndex((s) => s.name === sheetName);
+    if (index < 0) {
+        const names = workbook.sheets.map((s) => `"${s.name}"`).join(", ");
+        fail(`Sheet not found: "${sheetName}". Available: ${names}`);
+    }
+    return index;
+}
+function parseRange(range) {
+    const [start, end] = range.includes(":") ? range.split(":") : [range, range];
+    const s = refToRowCol(start.toUpperCase());
+    const e = refToRowCol(end.toUpperCase());
+    if (!s || !e)
+        fail(`Invalid range: ${range}`);
+    return {
+        startRow: Math.min(s.row, e.row),
+        startCol: Math.min(s.col, e.col),
+        endRow: Math.max(s.row, e.row),
+        endCol: Math.max(s.col, e.col),
+    };
+}
+function parseInt10(s, name) {
+    if (s === undefined)
+        fail(`Missing ${name}`);
+    const n = parseInt(s, 10);
+    if (!Number.isFinite(n))
+        fail(`Invalid ${name}: ${s}`);
+    return n;
+}
+function lazyEngine(workbook) {
+    let engine;
+    return {
+        get() {
+            if (!engine) {
+                engine = new FormulaEngine(workbook);
+                engine.buildGraph();
+            }
+            return engine;
+        },
+    };
+}
+// =============================================================================
+// JSON shape: ParsedSpreadsheet (read) and SimpleWorkbook (write)
+// =============================================================================
+function readToJson(filePath) {
+    const buffer = fs.readFileSync(filePath);
+    const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    const parsed = parseExcelBuffer(arrayBuffer);
+    return {
+        activeSheetIndex: parsed.activeSheetIndex,
+        sheets: parsed.sheets.map((s) => ({
+            name: s.name,
+            totalRowCount: s.totalRowCount,
+            truncated: s.truncated,
+            cells: cellsFromParsedRows(s.rows),
+            merges: s.mergedCells.map((m) => `${rowColToRef(m.startRow, m.startCol)}:${rowColToRef(m.endRow, m.endCol)}`),
+            freeze: s.freezePane ? { row: s.freezePane.frozenRows, col: s.freezePane.frozenCols } : undefined,
+        })),
+    };
+}
+function cellsFromParsedRows(rows) {
+    const out = {};
+    for (const row of rows) {
+        for (const cell of row.cells) {
+            const ref = rowColToRef(row.index, cell.column);
+            const value = cell.typedValue ?? cell.value;
+            const entry = { value };
+            if (cell.formula)
+                entry.formula = cell.formula;
+            out[ref] = entry;
+        }
+    }
+    return out;
+}
+function buildWorkbookFromJson(input) {
+    if (!input || !Array.isArray(input.sheets) || input.sheets.length === 0) {
+        fail("Workbook JSON must include a non-empty `sheets` array");
+    }
+    for (let i = 0; i < input.sheets.length; i++)
+        validateSimpleSheet(input.sheets[i], i);
+    const styles = new StyleRegistry();
+    const sheets = input.sheets.map((s) => new SheetModel(s.name, styles));
+    const workbook = new WorkbookModel({ sheets, activeSheetIndex: 0, styles });
+    for (let i = 0; i < input.sheets.length; i++) {
+        applySheetCells(workbook, i, input.sheets[i]);
+    }
+    return workbook;
+}
+function validateSimpleSheet(s, index) {
+    if (!s || typeof s !== "object")
+        fail(`sheets[${index}] must be an object`);
+    if (typeof s.name !== "string" || s.name === "")
+        fail(`sheets[${index}].name must be a non-empty string`);
+    if (s.cells !== undefined && (typeof s.cells !== "object" || s.cells === null || Array.isArray(s.cells))) {
+        fail(`sheets[${index}].cells must be an object keyed by cell ref (e.g. {"A1": "value"})`);
+    }
+    if (s.merges !== undefined && !Array.isArray(s.merges)) {
+        fail(`sheets[${index}].merges must be an array of ranges (e.g. ["A1:B2"])`);
+    }
+    if (s.freeze !== undefined) {
+        if (typeof s.freeze !== "object" || s.freeze === null)
+            fail(`sheets[${index}].freeze must be {row, col}`);
+        if (typeof s.freeze.row !== "number" || typeof s.freeze.col !== "number") {
+            fail(`sheets[${index}].freeze.row and .col must be numbers`);
+        }
+    }
+}
+function applySheetCells(workbook, sheetIndex, def) {
+    const sheet = workbook.sheets[sheetIndex];
+    if (def.cells) {
+        for (const [ref, raw] of Object.entries(def.cells)) {
+            const cell = normalizeSimpleCell(raw);
+            const coord = refToRowCol(ref.toUpperCase());
+            if (!coord)
+                fail(`Invalid cell ref in sheet "${def.name}": ${ref}`);
+            const stringValue = cell.formula ? `=${cell.formula}` : valueToInput(cell.value);
+            const cmd = setCellValueCommand(workbook, undefined, sheetIndex, coord.row, coord.col, stringValue);
+            cmd.execute();
+        }
+    }
+    if (def.merges) {
+        for (const range of def.merges) {
+            const r = parseRange(range);
+            const cmd = mergeCellsCommand(workbook, sheetIndex, r.startRow, r.startCol, r.endRow, r.endCol);
+            cmd.execute();
+        }
+    }
+    if (def.freeze) {
+        sheet.freeze = { row: def.freeze.row, col: def.freeze.col };
+    }
+}
+function normalizeSimpleCell(raw) {
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        return raw;
+    }
+    return { value: raw };
+}
+function valueToInput(value) {
+    if (value === null || value === undefined)
+        return "";
+    return String(value);
+}
+// =============================================================================
+// Subcommand handlers
+// =============================================================================
+function xlsxRead(filePath) {
+    if (!filePath)
+        fail("Usage: lotics xlsx read <file>");
+    const data = readToJson(filePath);
+    console.log(JSON.stringify(data, null, 2));
+}
+function xlsxWrite(filePath, json) {
+    if (!filePath || !json)
+        fail("Usage: lotics xlsx write <file> '<json>'");
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        fail(`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const workbook = buildWorkbookFromJson(parsed);
+    const bytes = exportWorkbook(workbook);
+    writeFileAtomic(filePath, bytes);
+}
+function parseSheetRef(spec) {
+    const idx = spec.indexOf("!");
+    if (idx < 0)
+        fail(`Expected <sheet>!<ref>, got: ${spec}`);
+    return { sheet: spec.slice(0, idx), ref: spec.slice(idx + 1) };
+}
+function xlsxSetCell(filePath, rest) {
+    const [sheetRef, value] = rest;
+    if (!filePath || !sheetRef || value === undefined) {
+        fail("Usage: lotics xlsx set-cell <file> <sheet>!<ref> '<value>'");
+    }
+    const { sheet, ref } = parseSheetRef(sheetRef);
+    const coord = refToRowCol(ref.toUpperCase());
+    if (!coord)
+        fail(`Invalid cell ref: ${ref}`);
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheet);
+    const engine = lazyEngine(loaded.workbook);
+    const cmd = setCellValueCommand(loaded.workbook, engine.get(), sheetIndex, coord.row, coord.col, value);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxClearRange(filePath, rest) {
+    const [sheetRef] = rest;
+    if (!filePath || !sheetRef)
+        fail("Usage: lotics xlsx clear-range <file> <sheet>!<range>");
+    const { sheet, ref } = parseSheetRef(sheetRef);
+    const r = parseRange(ref);
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheet);
+    const engine = lazyEngine(loaded.workbook);
+    const cmd = clearRangeCommand(loaded.workbook, engine.get(), sheetIndex, r.startRow, r.startCol, r.endRow, r.endCol);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxMerge(filePath, rest) {
+    const [sheetRef] = rest;
+    if (!filePath || !sheetRef)
+        fail("Usage: lotics xlsx merge <file> <sheet>!<range>");
+    const { sheet, ref } = parseSheetRef(sheetRef);
+    const r = parseRange(ref);
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheet);
+    const cmd = mergeCellsCommand(loaded.workbook, sheetIndex, r.startRow, r.startCol, r.endRow, r.endCol);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxUnmerge(filePath, rest) {
+    const [sheetRef] = rest;
+    if (!filePath || !sheetRef)
+        fail("Usage: lotics xlsx unmerge <file> <sheet>!<range>");
+    const { sheet, ref } = parseSheetRef(sheetRef);
+    const r = parseRange(ref);
+    const mergeRef = `${rowColToRef(r.startRow, r.startCol)}:${rowColToRef(r.endRow, r.endCol)}`;
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheet);
+    const cmd = unmergeCellsCommand(loaded.workbook, sheetIndex, mergeRef);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxAddSheet(filePath, rest) {
+    const [name] = rest;
+    if (!filePath || !name)
+        fail("Usage: lotics xlsx add-sheet <file> <name>");
+    const loaded = loadFile(filePath);
+    const cmd = addSheetCommand(loaded.workbook, name);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxDeleteSheet(filePath, rest) {
+    const [name] = rest;
+    if (!filePath || !name)
+        fail("Usage: lotics xlsx delete-sheet <file> <name>");
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, name);
+    const cmd = deleteSheetCommand(loaded.workbook, sheetIndex);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxRenameSheet(filePath, rest) {
+    const [oldName, newName] = rest;
+    if (!filePath || !oldName || !newName)
+        fail("Usage: lotics xlsx rename-sheet <file> <old> <new>");
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, oldName);
+    const cmd = renameSheetCommand(loaded.workbook, sheetIndex, newName);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxInsertRows(filePath, rest) {
+    const [sheetName, atStr, countStr] = rest;
+    if (!filePath || !sheetName)
+        fail("Usage: lotics xlsx insert-rows <file> <sheet> <at> <count>");
+    const at = parseInt10(atStr, "at");
+    const count = parseInt10(countStr, "count");
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheetName);
+    const cmd = insertRowsCommand(loaded.workbook, sheetIndex, at, count);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxDeleteRows(filePath, rest) {
+    const [sheetName, atStr, countStr] = rest;
+    if (!filePath || !sheetName)
+        fail("Usage: lotics xlsx delete-rows <file> <sheet> <at> <count>");
+    const at = parseInt10(atStr, "at");
+    const count = parseInt10(countStr, "count");
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheetName);
+    const cmd = deleteRowsCommand(loaded.workbook, sheetIndex, at, count);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxInsertCols(filePath, rest) {
+    const [sheetName, atStr, countStr] = rest;
+    if (!filePath || !sheetName)
+        fail("Usage: lotics xlsx insert-cols <file> <sheet> <at> <count>");
+    const at = parseInt10(atStr, "at");
+    const count = parseInt10(countStr, "count");
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheetName);
+    const cmd = insertColsCommand(loaded.workbook, sheetIndex, at, count);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxDeleteCols(filePath, rest) {
+    const [sheetName, atStr, countStr] = rest;
+    if (!filePath || !sheetName)
+        fail("Usage: lotics xlsx delete-cols <file> <sheet> <at> <count>");
+    const at = parseInt10(atStr, "at");
+    const count = parseInt10(countStr, "count");
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheetName);
+    const cmd = deleteColsCommand(loaded.workbook, sheetIndex, at, count);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxSetStyle(filePath, rest) {
+    const [sheetRef, styleJson] = rest;
+    if (!filePath || !sheetRef || !styleJson) {
+        fail("Usage: lotics xlsx set-style <file> <sheet>!<range> '<style-json>'");
+    }
+    const { sheet, ref } = parseSheetRef(sheetRef);
+    const r = parseRange(ref);
+    let style;
+    try {
+        style = JSON.parse(styleJson);
+    }
+    catch (e) {
+        fail(`Invalid style JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const loaded = loadFile(filePath);
+    const sheetIndex = resolveSheetIndex(loaded.workbook, sheet);
+    const cmd = setRangeStyleCommand(loaded.workbook, sheetIndex, r.startRow, r.startCol, r.endRow, r.endCol, style);
+    cmd.execute();
+    exportAndWrite(loaded, filePath);
+}
+function xlsxBatch(filePath, json) {
+    if (!filePath || !json)
+        fail("Usage: lotics xlsx batch <file> '<json-array-of-ops>'");
+    let ops;
+    try {
+        ops = JSON.parse(json);
+    }
+    catch (e) {
+        fail(`Invalid batch JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!Array.isArray(ops))
+        fail("Batch must be a JSON array of ops");
+    for (let i = 0; i < ops.length; i++) {
+        const op = ops[i];
+        if (!op || typeof op !== "object" || typeof op.op !== "string") {
+            fail(`[op ${i}] each op must be an object with an "op" string field`);
+        }
+    }
+    const loaded = loadFile(filePath);
+    const engine = lazyEngine(loaded.workbook);
+    for (let i = 0; i < ops.length; i++) {
+        const op = ops[i];
+        const cmd = buildBatchCommand(loaded.workbook, engine, op, i);
+        cmd.execute();
+    }
+    exportAndWrite(loaded, filePath);
+}
+function buildBatchCommand(workbook, engine, op, index) {
+    switch (op.op) {
+        case "set-cell": {
+            const sheetIndex = resolveSheetIndex(workbook, op.sheet);
+            const coord = refToRowCol(op.ref.toUpperCase());
+            if (!coord)
+                fail(`[op ${index}] Invalid cell ref: ${op.ref}`);
+            return setCellValueCommand(workbook, engine.get(), sheetIndex, coord.row, coord.col, op.value);
+        }
+        case "clear-range": {
+            const sheetIndex = resolveSheetIndex(workbook, op.sheet);
+            const r = parseRange(op.range);
+            return clearRangeCommand(workbook, engine.get(), sheetIndex, r.startRow, r.startCol, r.endRow, r.endCol);
+        }
+        case "merge": {
+            const sheetIndex = resolveSheetIndex(workbook, op.sheet);
+            const r = parseRange(op.range);
+            return mergeCellsCommand(workbook, sheetIndex, r.startRow, r.startCol, r.endRow, r.endCol);
+        }
+        case "unmerge": {
+            const sheetIndex = resolveSheetIndex(workbook, op.sheet);
+            const r = parseRange(op.range);
+            const mergeRef = `${rowColToRef(r.startRow, r.startCol)}:${rowColToRef(r.endRow, r.endCol)}`;
+            return unmergeCellsCommand(workbook, sheetIndex, mergeRef);
+        }
+        case "add-sheet":
+            return addSheetCommand(workbook, op.name);
+        case "delete-sheet":
+            return deleteSheetCommand(workbook, resolveSheetIndex(workbook, op.name));
+        case "rename-sheet":
+            return renameSheetCommand(workbook, resolveSheetIndex(workbook, op.old), op.new);
+        case "insert-rows":
+            return insertRowsCommand(workbook, resolveSheetIndex(workbook, op.sheet), op.at, op.count);
+        case "delete-rows":
+            return deleteRowsCommand(workbook, resolveSheetIndex(workbook, op.sheet), op.at, op.count);
+        case "insert-cols":
+            return insertColsCommand(workbook, resolveSheetIndex(workbook, op.sheet), op.at, op.count);
+        case "delete-cols":
+            return deleteColsCommand(workbook, resolveSheetIndex(workbook, op.sheet), op.at, op.count);
+        case "set-style": {
+            const sheetIndex = resolveSheetIndex(workbook, op.sheet);
+            const r = parseRange(op.range);
+            return setRangeStyleCommand(workbook, sheetIndex, r.startRow, r.startCol, r.endRow, r.endCol, op.style);
+        }
+        default: {
+            const exhaustive = op;
+            void exhaustive;
+            fail(`[op ${index}] Unknown op: ${JSON.stringify(op)}`);
+        }
+    }
+}
+// =============================================================================
+// Dispatch + help
+// =============================================================================
+export function printXlsxHelp() {
+    console.error(`Lotics xlsx commands — manipulate .xlsx files in place.
+Uses Lotics' own xlsx engine; round-trips faithfully with the Lotics editor and templates.
+
+  lotics xlsx read <file>                          Dump file as JSON (sheets, cells, merges, freeze)
+  lotics xlsx write <file> '<json>'                Create .xlsx from {"sheets":[{"name","cells":{"A1":...}}]}
+  lotics xlsx set-cell <file> <sheet>!<ref> '<v>'  Set cell value (prefix '=' for formula)
+  lotics xlsx clear-range <file> <sheet>!<range>   Clear all cells in a range
+  lotics xlsx merge <file> <sheet>!<range>         Merge a range into one cell
+  lotics xlsx unmerge <file> <sheet>!<range>       Unmerge a previously merged range
+  lotics xlsx add-sheet <file> <name>              Append a new sheet
+  lotics xlsx delete-sheet <file> <name>           Remove a sheet
+  lotics xlsx rename-sheet <file> <old> <new>      Rename a sheet
+  lotics xlsx insert-rows <file> <sheet> <at> <n>  Insert <n> rows at 1-based position
+  lotics xlsx delete-rows <file> <sheet> <at> <n>  Delete <n> rows starting at <at>
+  lotics xlsx insert-cols <file> <sheet> <at> <n>  Insert <n> columns at 1-based position
+  lotics xlsx delete-cols <file> <sheet> <at> <n>  Delete <n> columns starting at <at>
+  lotics xlsx set-style <file> <sheet>!<range> '<style-json>'
+                                                   Apply partial CellStyle to range (fontBold, backgroundColor, ...)
+  lotics xlsx batch <file> '<json-array-of-ops>'   Apply many ops in one parse/export cycle
+
+Edit ops mutate the file atomically (temp file + rename).`);
+}
+export async function runXlsxCommand(subcommand, toolArgs, restArgs) {
+    switch (subcommand) {
+        case "read":
+            return xlsxRead(toolArgs);
+        case "write":
+            return xlsxWrite(toolArgs, restArgs[0]);
+        case "set-cell":
+            return xlsxSetCell(toolArgs, restArgs);
+        case "clear-range":
+            return xlsxClearRange(toolArgs, restArgs);
+        case "merge":
+            return xlsxMerge(toolArgs, restArgs);
+        case "unmerge":
+            return xlsxUnmerge(toolArgs, restArgs);
+        case "add-sheet":
+            return xlsxAddSheet(toolArgs, restArgs);
+        case "delete-sheet":
+            return xlsxDeleteSheet(toolArgs, restArgs);
+        case "rename-sheet":
+            return xlsxRenameSheet(toolArgs, restArgs);
+        case "insert-rows":
+            return xlsxInsertRows(toolArgs, restArgs);
+        case "delete-rows":
+            return xlsxDeleteRows(toolArgs, restArgs);
+        case "insert-cols":
+            return xlsxInsertCols(toolArgs, restArgs);
+        case "delete-cols":
+            return xlsxDeleteCols(toolArgs, restArgs);
+        case "set-style":
+            return xlsxSetStyle(toolArgs, restArgs);
+        case "batch":
+            return xlsxBatch(toolArgs, restArgs[0]);
+        default: {
+            if (subcommand)
+                console.error(`Unknown xlsx subcommand: ${subcommand}\n`);
+            printXlsxHelp();
+            process.exit(subcommand ? 1 : 0);
+        }
+    }
+}

package/dist/xlsx.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/xlsx.test.js

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { parseExcelBuffer } from "@lotics/xlsx/excel_parser";
+import { runXlsxCommand } from "./xlsx.js";
+import { CliError } from "./file_command_io.js";
+let tmpDir;
+let file;
+beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "xlsx-test-"));
+    file = path.join(tmpDir, "test.xlsx");
+    // Silence the "Wrote <path>" status line that handlers emit on writes.
+    vi.spyOn(console, "error").mockImplementation(() => { });
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+function parseFile(p) {
+    const bytes = fs.readFileSync(p);
+    const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    return parseExcelBuffer(ab);
+}
+async function writeFresh(json) {
+    await runXlsxCommand("write", file, [json]);
+}
+describe("xlsx write + read", () => {
+    it("round-trips cells, merges, and freeze", async () => {
+        await writeFresh(JSON.stringify({
+            sheets: [{
+                    name: "S1",
+                    cells: { A1: "hi", B1: 42, C1: true, D1: { formula: "A1" } },
+                    merges: ["A1:B1"],
+                    freeze: { row: 1, col: 1 },
+                }],
+        }));
+        const parsed = parseFile(file);
+        expect(parsed.sheets[0].name).toBe("S1");
+        expect(parsed.sheets[0].rows[0].cells.map((c) => c.value)).toEqual(["hi", "42", "TRUE", ""]);
+        expect(parsed.sheets[0].rows[0].cells[3].formula).toBe("A1");
+        expect(parsed.sheets[0].mergedCells).toHaveLength(1);
+        expect(parsed.sheets[0].freezePane).toEqual({ frozenRows: 1, frozenCols: 1 });
+    });
+    it("read dumps the file as JSON to stdout", async () => {
+        await writeFresh(JSON.stringify({ sheets: [{ name: "S1", cells: { A1: "hi" } }] }));
+        const stdout = vi.spyOn(console, "log").mockImplementation(() => { });
+        await runXlsxCommand("read", file, []);
+        const printed = JSON.parse(stdout.mock.calls[0][0]);
+        expect(printed.sheets[0].name).toBe("S1");
+        expect(printed.sheets[0].cells.A1.value).toBe("hi");
+    });
+});
+describe("xlsx single-op mutations", () => {
+    beforeEach(async () => {
+        await writeFresh(JSON.stringify({ sheets: [{ name: "S1", cells: { A1: "hi" } }] }));
+    });
+    it("set-cell writes a literal", async () => {
+        await runXlsxCommand("set-cell", file, ["S1!B2", "world"]);
+        expect(parseFile(file).sheets[0].rows[1].cells[0].value).toBe("world");
+    });
+    it("set-cell writes a formula", async () => {
+        await runXlsxCommand("set-cell", file, ["S1!B1", "=A1"]);
+        expect(parseFile(file).sheets[0].rows[0].cells[1].formula).toBe("A1");
+    });
+    it("clear-range removes cells in the range", async () => {
+        await runXlsxCommand("set-cell", file, ["S1!B1", "x"]);
+        await runXlsxCommand("clear-range", file, ["S1!A1:B1"]);
+        expect(parseFile(file).sheets[0].rows).toEqual([]);
+    });
+    it("merge + unmerge round-trip", async () => {
+        await runXlsxCommand("merge", file, ["S1!A1:B1"]);
+        expect(parseFile(file).sheets[0].mergedCells).toHaveLength(1);
+        await runXlsxCommand("unmerge", file, ["S1!A1:B1"]);
+        expect(parseFile(file).sheets[0].mergedCells).toHaveLength(0);
+    });
+    it("add-sheet, rename-sheet, delete-sheet", async () => {
+        await runXlsxCommand("add-sheet", file, ["S2"]);
+        expect(parseFile(file).sheets.map((s) => s.name)).toEqual(["S1", "S2"]);
+        await runXlsxCommand("rename-sheet", file, ["S2", "Renamed"]);
+        expect(parseFile(file).sheets.map((s) => s.name)).toEqual(["S1", "Renamed"]);
+        await runXlsxCommand("delete-sheet", file, ["Renamed"]);
+        expect(parseFile(file).sheets.map((s) => s.name)).toEqual(["S1"]);
+    });
+    it("insert-rows shifts existing cells", async () => {
+        await runXlsxCommand("set-cell", file, ["S1!A2", "below"]);
+        await runXlsxCommand("insert-rows", file, ["S1", "1", "1"]);
+        // Original A1 ("hi") shifts to A2; original A2 ("below") shifts to A3.
+        const rows = parseFile(file).sheets[0].rows;
+        expect(rows.find((r) => r.index === 2)?.cells[0].value).toBe("hi");
+        expect(rows.find((r) => r.index === 3)?.cells[0].value).toBe("below");
+    });
+});
+describe("xlsx batch", () => {
+    it("applies multiple ops in one parse/export cycle", async () => {
+        await writeFresh(JSON.stringify({ sheets: [{ name: "S1", cells: { A1: "x" } }] }));
+        const ops = [
+            { op: "set-cell", sheet: "S1", ref: "A2", value: "y" },
+            { op: "merge", sheet: "S1", range: "A1:B1" },
+            { op: "add-sheet", name: "S2" },
+        ];
+        await runXlsxCommand("batch", file, [JSON.stringify(ops)]);
+        const parsed = parseFile(file);
+        expect(parsed.sheets.map((s) => s.name)).toEqual(["S1", "S2"]);
+        expect(parsed.sheets[0].mergedCells).toHaveLength(1);
+        expect(parsed.sheets[0].rows.find((r) => r.index === 2)?.cells[0].value).toBe("y");
+    });
+});
+describe("xlsx error paths", () => {
+    it("fails on unknown sheet name", async () => {
+        await writeFresh(JSON.stringify({ sheets: [{ name: "S1" }] }));
+        await expect(runXlsxCommand("set-cell", file, ["Nope!A1", "x"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("fails on invalid cell ref", async () => {
+        await writeFresh(JSON.stringify({ sheets: [{ name: "S1" }] }));
+        await expect(runXlsxCommand("set-cell", file, ["S1!ZZZ", "x"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("fails on missing file", async () => {
+        await expect(runXlsxCommand("set-cell", path.join(tmpDir, "no.xlsx"), ["S1!A1", "x"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("fails on invalid write JSON", async () => {
+        await expect(runXlsxCommand("write", file, ["{not json"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("rejects write with non-object cells", async () => {
+        await expect(runXlsxCommand("write", file, [JSON.stringify({ sheets: [{ name: "S", cells: "bad" }] })])).rejects.toBeInstanceOf(CliError);
+    });
+    it("rejects batch op without an 'op' string", async () => {
+        await writeFresh(JSON.stringify({ sheets: [{ name: "S1" }] }));
+        await expect(runXlsxCommand("batch", file, [JSON.stringify([{ sheet: "S1" }])])).rejects.toBeInstanceOf(CliError);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -14,12 +14,16 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsgo",
+    "build": "tsgo && node scripts/build_cli.mjs",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@lotics/docx": "*",
+    "@lotics/xlsx": "*",
+    "@types/node": "^22.15.21",
+    "esbuild": "^0.25.0",
     "vitest": "^4.0.15"
   },
   "keywords": [