@lotics/cli 0.192.2 → 0.195.0

package/AGENTS.md

@@ -23,17 +23,17 @@ conventions are, and where the traps are.
 - **Tools** (`lotics tools`, `lotics run <tool>`) — the *agent tool registry*: what an agent, workflow,
   or automation may call. Workspace data, templates, knowledge, admin.
 - **Commands** (`lotics --help` § COMMANDS) — the CLI's *own verbs*. Auth and org/workspace scoping,
-  file upload/download/preview, local `.xlsx`/`.docx` authoring, and the whole custom-code app loop
-  (scaffold, pull, deploy, codegen, dev, and running a bound workflow or agent end to end).
+  file upload/download/preview, and the whole custom-code app loop (scaffold, pull, deploy, codegen,
+  dev, and running a bound workflow or agent end to end).
 
 Several capabilities exist **only** as commands and appear nowhere in `lotics tools` — downloading a
 file and running a bound app agent are the two that most often get mistaken for missing. Concluding
 "the platform can't do X" from the tool list alone is a mistake; check both.
 
 ⚠️ **`lotics <subcommand> --help` prints the generic top-level help**, except `lotics report --help`
-and a bare `lotics auth` / `xlsx` / `docx`, which print their own. It does not describe the
-subcommand, so an unhelpful response there is *not* evidence the subcommand is absent. To find out
-whether something exists, read `lotics --help` § COMMANDS — the whole section, not a narrow grep.
+and a bare `lotics auth`, which print their own. It does not describe the subcommand, so an unhelpful
+response there is *not* evidence the subcommand is absent. To find out whether something exists, read
+`lotics --help` § COMMANDS — the whole section, not a narrow grep.
 
 ## Conventions that hold across every command
 
@@ -108,5 +108,8 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   editing `tool_names` or `knowledge_doc_ids` still retypes `useAgentRun` — green locally, unchanged
   in production, and reverted by the next `app codegen`. An agent's PROSE is not in the manifest at
   all: it lives in `src/agents/<alias>.md` and is pushed by `app agent set`.
+- **Editing a local `.xlsx` / `.docx`.** A library call, not a verb: script `@lotics/xlsx` /
+  `@lotics/docx` (`lotics docs xlsx` / `lotics docs docx` prints the installed copy's API guide).
+  `lotics file preview` draws the result so it can be looked at.
 - **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.
 - **Anything needing a browser.** `app dev` and `file preview` shell out to a local Chrome.

package/README.md

@@ -110,8 +110,9 @@ irm https://lotics.ai/install.ps1 | iex           # Windows PowerShell — no No
 
 ## Update
 
-Re-run whichever installer you used; `npm install -g @lotics/cli@latest` updates an npm install.
-The CLI names the right one for the copy you are running when it sees a newer version.
+`lotics upgrade` updates this CLI in place, running whichever installer this copy came from. By
+hand: re-run whichever installer you used; `npm install -g @lotics/cli@latest` updates an npm
+install.
 
 The CLI checks for updates once per day and prints a note on stderr, naming the right installer, when a new version is available.
 
@@ -284,40 +285,20 @@ LOTICS_API_KEY=ltk_... lotics run query_tables '{}'
 LOTICS_ORG=acme LOTICS_WORKSPACE=wks_... lotics run query_tables '{}'
 ```
 
-## Local .xlsx and .docx authoring
+## Local .xlsx and .docx files
 
-The CLI bundles Lotics's own xlsx and docx engines so you can read, write, and edit files on your local filesystem without installing `xlsx` / `exceljs` / `docx` from npm. Prefer these over third-party libraries — they round-trip faithfully with the Lotics editor, template engine, and formula engine.
+Edit them by scripting Lotics's own engines, published as `@lotics/xlsx` and `@lotics/docx`. Prefer them over `xlsx` / `exceljs` / `docx` from npm: they round-trip faithfully with the Lotics editor, template engine, and formula engine. `npm i @lotics/xlsx @lotics/docx`, then read the API guide that ships inside the package: `lotics docs xlsx` / `lotics docs docx` prints the installed copy (`node_modules/@lotics/<pkg>/AGENTS.md` on a machine with no CLI). Both packages ship `.ts` sources as their entry, so run the script under a TypeScript-aware runner.
 
-```bash
-# .xlsx
-lotics xlsx read ./report.xlsx                                  # → JSON of sheets, cells, merges
-lotics xlsx read ./report.xlsx --with-format                    # …plus each cell's resolved style
-lotics xlsx write ./out.xlsx '{"sheets":[{"name":"S1","cells":{"A1":"Hi","B1":42}}]}'
-# A cell is a bare value, or an object with numFmt / style / formula:
-lotics xlsx write ./out.xlsx '{"sheets":[{"name":"S1",
-  "colWidths":{"A":34,"B":14}, "rowHeights":{"1":28},
-  "cells":{
-    "A1":{"value":"Tổng","style":{"fontBold":true}},
-    "B1":{"value":1234567,"numFmt":"#,##0"},
-    "B2":{"formula":"B1*0.1","numFmt":"#,##0"}}}]}'  # unknown keys are rejected, not ignored
-lotics xlsx set-cell ./report.xlsx 'Sheet1!A1' '=SUM(B:B)'
-lotics xlsx add-sheet ./report.xlsx 'Summary'
-lotics xlsx merge ./report.xlsx 'Sheet1!A1:C1'
-lotics xlsx insert-rows ./report.xlsx Sheet1 5 3
-lotics xlsx batch ./report.xlsx '[{"op":"set-cell","sheet":"Sheet1","ref":"A1","value":"Hi"}, {"op":"merge","sheet":"Sheet1","range":"A1:B1"}]'
-
-# .docx
-lotics docx read ./report.docx                                  # → JSON of blocks with text + style
-lotics docx write ./out.docx '{"blocks":[{"kind":"paragraph","text":"Title","style":"Heading1"}]}'
-lotics docx append-paragraph ./report.docx 'New paragraph' --style=Heading2
-lotics docx insert-paragraph ./report.docx 'Front matter' --at=0
-lotics docx replace-text ./report.docx '{{name}}' 'Acme Inc.'
-lotics docx batch ./report.docx '[{"op":"append-paragraph","text":"A","style":"Heading1"},{"op":"replace-text","search":"x","replace":"y"}]'
-```
+```ts
+import { readFile, writeFile } from "node:fs/promises";
+import { parseDocx, replaceText, serializeDocx } from "@lotics/docx";
 
-Edits mutate the file in place via an atomic temp-file + rename. Unknown OOXML constructs (tables, SmartArt, custom XML) round-trip verbatim — they show up in `read` as `opaque_block` entries.
+const { doc, count } = replaceText(await parseDocx(await readFile("in.docx")), "{{name}}", "Acme Ltd.");
+if (count === 0) throw new Error("{{name}} is not in this document — nothing written");
+await writeFile("out.docx", await serializeDocx(doc));
+```
 
-Run `lotics xlsx` or `lotics docx` with no subcommand for the full list.
+`lotics preview <file.xlsx|.docx>` draws one of those files to a PNG with the same engines, so a script's output can be looked at rather than guessed at.
 
 ## Knowledge docs
 

package/dist/render_page.js

@@ -50253,6 +50253,14 @@ ${e.toString()}`);
     return colon === -1 ? tag : tag.slice(colon + 1);
   }
 
+  // ../xlsx/src/invalid_model_error.ts
+  var InvalidModelError = class extends Error {
+    constructor(reason) {
+      super(reason);
+      this.name = "InvalidModelError";
+    }
+  };
+
   // ../xlsx/node_modules/fast-xml-parser/src/util.js
   var nameStartChar2 = ":A-Za-z_\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u02FF\\u0370-\\u037D\\u037F-\\u1FFF\\u200C-\\u200D\\u2070-\\u218F\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD";
   var nameChar2 = nameStartChar2 + "\\-.\\d\\u00B7\\u0300-\\u036F\\u203F-\\u2040";
@@ -52902,7 +52910,7 @@ ${e.toString()}`);
     const colCount = Math.max(parsedCols.length > 0 ? parsedCols[parsedCols.length - 1].max : 0, maxCol);
     const columns = buildColumns(parsedCols, colHidden, maxContentWidth, colCount, defaultColWidth);
     const mergedCells = parseMergedCells(worksheet);
-    const conditionalFormats = parseConditionalFormats(worksheet, theme, indexedColors);
+    const conditionalFormats = parseConditionalFormats(worksheet, theme, indexedColors, styles.dxfs);
     const images = parseImages(rels, zipEntries);
     const dataValidations = parseDataValidations(worksheet);
     const sparklineGroups = parseSparklineGroups(worksheet);
@@ -53233,7 +53241,7 @@ ${e.toString()}`);
     const cell = { column: cellRef.col, value: displayValue, content, style };
     cell.typedValue = typedValue;
     cell.rawValue = cellRawValue;
-    cell.originalXfIndex = styleIndex;
+    if (styles.hasXf(styleIndex)) cell.originalXfIndex = styleIndex;
     if (numFmt !== "General") cell.numFmtCode = numFmt;
     if (type === "e" && rawValue) cell.error = rawValue;
     if (formula) cell.formula = formula;
@@ -53383,7 +53391,7 @@ ${e.toString()}`);
     const dataUrl = `data:${mimeType};base64,${base64}`;
     return { dataUrl, tl, br, ext, anchorKind, extent, pos };
   }
-  function parseConditionalFormats(worksheet, theme, indexedColors) {
+  function parseConditionalFormats(worksheet, theme, indexedColors, dxfs) {
     const cfArr = worksheet["conditionalFormatting"];
     if (!cfArr) return [];
     const result = [];
@@ -53394,7 +53402,7 @@ ${e.toString()}`);
       if (!ruleArr) continue;
       const rules = [];
       for (const ruleEl of ruleArr) {
-        const parsed = parseCfRule(ruleEl, theme, indexedColors);
+        const parsed = parseCfRule(ruleEl, theme, indexedColors, dxfs);
         if (parsed) rules.push(parsed);
       }
       if (rules.length > 0) {
@@ -53403,7 +53411,7 @@ ${e.toString()}`);
     }
     return result;
   }
-  function parseCfRule(el, theme, indexedColors) {
+  function parseCfRule(el, theme, indexedColors, dxfs) {
     const type = el["@_type"];
     const priority = parseInt(el["@_priority"] ?? "1", 10);
     const stopIfTrue = el["@_stopIfTrue"] === "1";
@@ -53464,14 +53472,23 @@ ${e.toString()}`);
       case "aboveAverage":
       case "timePeriod":
       case "expression": {
-        return parseStyleCfRule(el, type, priority, stopIfTrue, theme, indexedColors);
+        return parseStyleCfRule(el, type, priority, stopIfTrue, dxfs);
       }
       default:
         return void 0;
     }
   }
-  function parseStyleCfRule(el, type, priority, stopIfTrue, _theme, _indexedColors) {
+  function parseStyleCfRule(el, type, priority, stopIfTrue, dxfs) {
     const rule = { ruleType: "style", priority, stopIfTrue, type };
+    const dxfIdAttr = el["@_dxfId"];
+    if (dxfIdAttr !== void 0) {
+      const dxfId = parseInt(dxfIdAttr, 10);
+      const dxf = dxfs[dxfId];
+      if (dxf !== void 0) {
+        rule.style = { ...dxf };
+        rule.originalDxfId = dxfId;
+      }
+    }
     if (type === "cellIs") {
       rule.operator = el["@_operator"];
       const formula = el["formula"];
@@ -54158,6 +54175,11 @@ ${e.toString()}`);
        * the styles part gets regenerated to include the new code.
        */
       this.knownNumFmts = /* @__PURE__ */ new Set(["General", ""]);
+      /**
+       * What each `cellXfs` index of the loaded file resolves to here — the
+       * baseline `originalXfExpresses` verifies an `originalXfIndex` against.
+       */
+      this.originalXfs = /* @__PURE__ */ new Map();
       this.keyMap.set(styleKey({}), 0);
     }
     /** Get style by index. Returns empty style for invalid indices. */
@@ -54191,6 +54213,44 @@ ${e.toString()}`);
       this.knownNumFmts.add(code2);
       this.dirty = true;
     }
+    /**
+     * Record what the loaded file's `cellXfs` table resolves to here. The whole
+     * table, because an entry no cell carries still governs the export: a cell
+     * written with no `s=` inherits entry 0. An entry whose style this registry
+     * never interned stays unrecorded, so a write claiming it fails
+     * `originalXfExpresses` and the claim is dropped.
+     */
+    recordOriginalXfs(cellXfs) {
+      for (let i3 = 0; i3 < cellXfs.length; i3++) {
+        const styleIndex = this.keyMap.get(styleKey(cellXfs[i3].style));
+        if (styleIndex !== void 0) {
+          this.originalXfs.set(i3, { styleIndex, numFmtCode: cellXfs[i3].numFmtCode });
+        }
+      }
+    }
+    /**
+     * Whether the loaded file's xf `index` resolves to exactly this style and
+     * number format here. The claim a caller makes by naming an `originalXfIndex`,
+     * checked at the write so no later scan has to re-ask it.
+     */
+    originalXfExpresses(index, styleIndex, numFmtCode) {
+      const original = this.originalXfs.get(index);
+      return original !== void 0 && original.styleIndex === styleIndex && original.numFmtCode === (numFmtCode === "" ? "General" : numFmtCode);
+    }
+    /**
+     * True when the xf index the writer emits for `cell` in styles-passthrough
+     * mode still expresses the cell's style. A cell CARRYING an index always
+     * does — every write path drops that index the moment the style or number
+     * format moves off it. The question left is the one no cell states: a cell
+     * the file never carried emits no `s=` and so inherits the file's xf 0,
+     * which is right only when that entry expresses the style the model gives
+     * it. Neither half reads cell protection or `quotePrefix`, which this model
+     * does not carry, so an xf differing only there compares equal.
+     */
+    keepsOriginalXf(cell) {
+      if (cell.originalXfIndex !== void 0) return true;
+      return this.originalXfExpresses(0, cell.styleIndex, cell.numFmtCode);
+    }
     /**
      * Reset the `dirty` flag and snapshot the current numFmt set as the
      * baseline. Called once after loading from a parsed workbook so that
@@ -54369,8 +54429,21 @@ ${e.toString()}`);
      *
      * Pass `originalXfIndex` to enable styles-passthrough mode for cells
      * copied from a parsed template.
+     *
+     * Both arguments are indexes into tables this sheet's registry owns and
+     * neither is interned here, so both are checked against it — differently.
+     * An unknown `styleIndex` throws: it would reach the writer and render as
+     * the empty style, and there is no style to fall back to. An
+     * `originalXfIndex` the file's xf table contradicts is instead dropped: the
+     * cell still knows its style, so the export rebuilds the styles part rather
+     * than shipping the cell with the one the file gave that index.
      */
     setWithStyleIndex(ref2, value2, styleIndex, numFmtCode = "General", formula, originalXfIndex) {
+      if (this.styles && !(Number.isInteger(styleIndex) && styleIndex >= 0 && styleIndex < this.styles.size)) {
+        throw new InvalidModelError(
+          `setWithStyleIndex: styleIndex ${styleIndex} is not in this sheet's registry (0..${this.styles.size - 1})`
+        );
+      }
       if (this.styles) this.styles.registerNumFmt(numFmtCode);
       const cell = {
         value: value2,
@@ -54380,7 +54453,23 @@ ${e.toString()}`);
         numFmtCode,
         content: { type: "plain", text: "" }
       };
-      if (originalXfIndex !== void 0) cell.originalXfIndex = originalXfIndex;
+      if (originalXfIndex !== void 0 && this.styles?.originalXfExpresses(originalXfIndex, styleIndex, numFmtCode)) {
+        cell.originalXfIndex = originalXfIndex;
+      }
+      this.cells.set(ref2, cell);
+      return cell;
+    }
+    /**
+     * Re-style an existing cell. Replaces it rather than editing it in place, so
+     * a style the cell's `originalXfIndex` no longer expresses drops that index
+     * exactly as `set()` does — keeping it would ship the cell with the style the
+     * FILE gave that index. Returns undefined for a ref holding no cell.
+     */
+    setStyleIndex(ref2, styleIndex) {
+      const existing = this.cells.get(ref2);
+      if (!existing) return void 0;
+      const cell = { ...existing, styleIndex };
+      if (styleIndex !== existing.styleIndex) delete cell.originalXfIndex;
       this.cells.set(ref2, cell);
       return cell;
     }
@@ -54449,6 +54538,30 @@ ${e.toString()}`);
       this.onChange?.(event);
       for (const sub of this.subscribers) sub(event);
     }
+    /**
+     * True while every reference the regenerated parts make into the styles part
+     * resolves against the loaded file's own — the precondition for exporting
+     * that part unrebuilt. Two kinds of reference exist: a cell's `s=` names a
+     * `cellXfs` entry, and a style conditional-format rule's `dxfId` names a
+     * `dxfs` entry. A rule read out of the file keeps the `dxfs` index it came
+     * in on; a rule painting a style that index cannot name is one only the
+     * rebuild can mint a dxf for, so a workbook holding one cannot skip it —
+     * that rule would ship with no `dxfId` and paint nothing.
+     */
+    regeneratedPartsReferenceOnlyLoadedStyles() {
+      for (const sheet of this.sheets) {
+        for (const cell of sheet.cells.values()) {
+          if (!this.styles.keepsOriginalXf(cell)) return false;
+        }
+        for (const cf of sheet.conditionalFormats) {
+          for (const rule of cf.rules) {
+            if (rule.ruleType !== "style") continue;
+            if (rule.style !== void 0 && rule.originalDxfId === void 0) return false;
+          }
+        }
+      }
+      return true;
+    }
     /** Produce an immutable ParsedSpreadsheet snapshot for read-only consumers. */
     toSnapshot() {
       return {
@@ -54550,7 +54663,7 @@ ${e.toString()}`);
     const styles = new StyleRegistry();
     const sheets = [];
     for (const ps of parsed.sheets) {
-      const sheet = loadSheetFromParsed(ps, styles);
+      const sheet = loadSheetFromParsed(ps, styles, parsed.cellXfs !== void 0);
       sheets.push(sheet);
     }
     const wb = new WorkbookModel({
@@ -54577,10 +54690,11 @@ ${e.toString()}`);
         }
       }
     }
+    if (parsed.cellXfs) styles.recordOriginalXfs(parsed.cellXfs);
     styles.markClean();
     return wb;
   }
-  function loadSheetFromParsed(ps, styles) {
+  function loadSheetFromParsed(ps, styles, hasCellXfs) {
     const sheet = new SheetModel(ps.name, styles);
     sheet.sheetState = ps.sheetState;
     sheet.defaultRowHeight = ps.defaultRowHeight;
@@ -54627,20 +54741,28 @@ ${e.toString()}`);
       for (const cell of row.cells) {
         const ref2 = rowColToRef(row.index, cell.column);
         const styleIndex = styles.intern(cell.style);
+        const numFmtCode = cell.numFmtCode ?? "General";
         styles.registerNumFmt(cell.numFmtCode);
         const rawValue = cell.typedValue !== void 0 ? cell.typedValue : inferRawValue(cell.value, cell.content);
         const model = {
           value: rawValue,
           displayValue: cell.value,
           styleIndex,
-          numFmtCode: cell.numFmtCode ?? "General",
+          numFmtCode,
           content: cell.content
         };
         if (cell.error) model.error = cell.error;
         if (cell.formula) model.formula = cell.formula;
         if (cell.isArrayFormula) model.isArrayFormula = true;
         if (cell.arrayRange) model.arrayRange = cell.arrayRange;
-        if (cell.originalXfIndex !== void 0) model.originalXfIndex = cell.originalXfIndex;
+        if (cell.originalXfIndex !== void 0) {
+          if (!hasCellXfs) {
+            throw new InvalidModelError(
+              `${ps.name}!${ref2} carries originalXfIndex ${cell.originalXfIndex} but the snapshot has no cellXfs table`
+            );
+          }
+          model.originalXfIndex = cell.originalXfIndex;
+        }
         if (cell.content.type === "rich_text") {
           model.richText = cell.content.parts;
         }
@@ -64979,7 +65101,7 @@ ${e.toString()}`);
     // dropped before anything looks a tag up — see `stripNsPrefix`.
     transformTagName: stripNsPrefix,
     processEntities: false,
-    isArray: (tagName) => tagName === "numFmt" || tagName === "font" || tagName === "fill" || tagName === "border" || tagName === "xf" || tagName === "rgbColor" || tagName === "stop"
+    isArray: (tagName) => tagName === "numFmt" || tagName === "font" || tagName === "fill" || tagName === "border" || tagName === "xf" || tagName === "dxf" || tagName === "rgbColor" || tagName === "stop"
   });
   function parseStyles(stylesXml, theme) {
     const doc3 = xmlParser3.parse(stylesXml);
@@ -65078,7 +65200,18 @@ ${e.toString()}`);
       if (!cellXfs[xfIndex].applyNumFmt && fmtId === 0) return "General";
       return customFmts.get(fmtId) ?? BUILTIN_NUM_FMTS[fmtId] ?? "General";
     }
-    return { resolveStyle, getNumFmt, indexedColors };
+    let resolvedXfs;
+    return {
+      resolveStyle,
+      getNumFmt,
+      hasXf: (xfIndex) => xfIndex >= 0 && xfIndex < cellXfs.length,
+      indexedColors,
+      dxfs: parseDxfs(root, theme, indexedColors),
+      get cellXfs() {
+        resolvedXfs ?? (resolvedXfs = cellXfs.map((_, i3) => ({ style: resolveStyle(i3), numFmtCode: getNumFmt(i3) })));
+        return resolvedXfs;
+      }
+    };
   }
   function parseIndexedColors(root) {
     const result = [...DEFAULT_INDEXED_COLORS];
@@ -65218,6 +65351,29 @@ ${e.toString()}`);
       color: colorEl ? parseColorElement(colorEl) : void 0
     };
   }
+  function parseDxfs(root, theme, indexedColors) {
+    const dxfsEl = root["dxfs"];
+    const dxfArr = dxfsEl?.["dxf"];
+    if (!dxfArr) return [];
+    return dxfArr.map((el) => {
+      const style = {};
+      const fontEl = el["font"]?.[0];
+      if (fontEl) {
+        const font = parseFont(fontEl);
+        if (font.bold) style.fontBold = true;
+        if (font.italic) style.fontItalic = true;
+        const fontColor = resolveColor(font.color, theme, indexedColors, "font");
+        if (fontColor) style.fontColor = prefixHex(fontColor);
+      }
+      const fillEl = el["fill"]?.[0];
+      if (fillEl) {
+        const fill = parseFill(fillEl);
+        const bgHex = resolveColor(fill.bgColor ?? fill.fgColor, theme, indexedColors, "fill");
+        if (bgHex) style.backgroundColor = prefixHex(bgHex);
+      }
+      return style;
+    });
+  }
   function parseCellXfs(root) {
     const xfsEl = root["cellXfs"];
     if (!xfsEl) return [];
@@ -65303,7 +65459,10 @@ ${e.toString()}`);
     return {
       resolveStyle: () => ({}),
       getNumFmt: () => "General",
-      indexedColors: [...DEFAULT_INDEXED_COLORS]
+      hasXf: () => false,
+      indexedColors: [...DEFAULT_INDEXED_COLORS],
+      dxfs: [],
+      cellXfs: []
     };
   }
 
@@ -67074,7 +67233,13 @@ ${e.toString()}`);
       return { sheets: [emptySheet("Sheet1")], activeSheetIndex: 0 };
     }
     if (activeSheetIndex >= sheets.length) activeSheetIndex = 0;
-    const result = { sheets, activeSheetIndex };
+    const result = {
+      sheets,
+      activeSheetIndex,
+      get cellXfs() {
+        return styles.cellXfs;
+      }
+    };
     if (workbookInfo.namedRanges.size > 0) {
       result.namedRanges = workbookInfo.namedRanges;
     }