@lotics/cli 0.114.0 → 0.116.0

package/dist/src/cli.js

@@ -71803,6 +71803,16 @@ var CliError = class extends Error {
 function fail2(message2) {
   throw new CliError(message2);
 }
+function rejectUnknownFlags(rest2, known, usage) {
+  const matches = (a) => known.some((k) => k.endsWith("=") ? a.startsWith(k) : a === k);
+  const unknown2 = rest2.filter((a) => a.startsWith("--") && !matches(a));
+  if (unknown2.length === 0) return;
+  fail2(`Unknown ${unknown2.length > 1 ? "flags" : "flag"} for ${usage}: ${unknown2.join(", ")}. Supported: ${known.join(", ")}.`);
+}
+function rejectExtraArgs(rest2, arity, usage) {
+  if (rest2.length <= arity) return;
+  fail2(`${usage} takes ${arity} argument${arity === 1 ? "" : "s"} after <file>, got ${rest2.length}. Unused: ${rest2.slice(arity).join(" ")}`);
+}
 function writeFileAtomic(filePath, bytes) {
   const dir = path6.dirname(path6.resolve(filePath));
   const tmp = path6.join(dir, `.${path6.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
@@ -92196,6 +92206,26 @@ function computeDisplay(value2, numFmtCode, date1904) {
   if (typeof value2 === "string") return value2;
   return formatNumFmt(value2, numFmtCode, date1904).text;
 }
+function recomputeAll(workbook) {
+  const engine = new FormulaEngine(workbook);
+  engine.buildGraph();
+  engine.evaluateAll();
+  return collectRecomputeReport(workbook);
+}
+function collectRecomputeReport(workbook) {
+  let total = 0;
+  const unevaluated = [];
+  for (const sheet of workbook.sheets) {
+    for (const [ref2, cell] of sheet.cells) {
+      if (!cell.formula) continue;
+      total++;
+      if (cell.value === null) {
+        unevaluated.push({ sheet: sheet.name, ref: ref2, formula: cell.formula, error: cell.error ?? "#ERROR!" });
+      }
+    }
+  }
+  return { total, unevaluated };
+}
 
 // ../xlsx/src/clipboard.ts
 function adjustFormulaRefsForRowShift(formula, atRow, delta) {
@@ -93163,6 +93193,7 @@ function splitOptionalSheetRef(spec) {
 }
 function xlsxRead(filePath, rest2) {
   if (!filePath) fail2("Usage: lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>] [--with-format]");
+  rejectUnknownFlags(rest2, ["--sheet", "--range", "--with-format"], "xlsx read");
   const rangeArg = readOptionFlag(rest2, "--range");
   const sheetArg = readOptionFlag(rest2, "--sheet");
   const withFormat = rest2.includes("--with-format");
@@ -93189,6 +93220,12 @@ function xlsxWrite(filePath, json2) {
     fail2(`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`);
   }
   const workbook = buildWorkbookFromJson(parsed);
+  const report = recomputeAll(workbook);
+  if (report.unevaluated.length > 0) {
+    const shown = report.unevaluated.slice(0, 5).map((u) => `${u.sheet}!${u.ref} (${u.formula}): ${u.error}`).join("; ");
+    const rest2 = report.unevaluated.length - Math.min(5, report.unevaluated.length);
+    console.error(`Warning: ${report.unevaluated.length} of ${report.total} formula(s) could not be evaluated \u2014 written without a cached value: ${shown}${rest2 > 0 ? `; +${rest2} more` : ""}`);
+  }
   const bytes = exportWorkbook(workbook);
   writeFileAtomic(filePath, bytes);
 }
@@ -93442,7 +93479,25 @@ Uses Lotics' own xlsx engine; round-trips faithfully with the Lotics editor and
 
 Edit ops mutate the file atomically (temp file + rename).`);
 }
+var FIXED_ARITY = /* @__PURE__ */ new Map([
+  ["write", 1],
+  ["set-cell", 2],
+  ["clear-range", 1],
+  ["merge", 1],
+  ["unmerge", 1],
+  ["add-sheet", 1],
+  ["delete-sheet", 1],
+  ["rename-sheet", 2],
+  ["insert-rows", 3],
+  ["delete-rows", 3],
+  ["insert-cols", 3],
+  ["delete-cols", 3],
+  ["set-style", 2],
+  ["batch", 1]
+]);
 async function runXlsxCommand(subcommand, toolArgs, restArgs) {
+  const arity = FIXED_ARITY.get(subcommand ?? "");
+  if (arity !== void 0) rejectExtraArgs(restArgs, arity, `lotics xlsx ${subcommand}`);
   switch (subcommand) {
     case "read":
       return xlsxRead(toolArgs, restArgs);
@@ -98783,6 +98838,7 @@ function buildDoc(input) {
 }
 async function docxRead(filePath, rest2) {
   if (!filePath) fail2("Usage: lotics docx read <file> [--include-opaque]");
+  rejectUnknownFlags(rest2, ["--include-opaque"], "docx read");
   const includeOpaque = rest2.includes("--include-opaque");
   const doc = await loadFile2(filePath);
   console.log(JSON.stringify(readToJson2(doc, includeOpaque), null, 2));
@@ -98817,6 +98873,7 @@ function firstPositional(rest2) {
   return rest2.find((a) => !a.startsWith("--"));
 }
 async function docxAppendParagraph(filePath, rest2) {
+  rejectUnknownFlags(rest2, ["--style="], "docx append-paragraph");
   const text = firstPositional(rest2);
   if (!filePath || text === void 0) fail2("Usage: lotics docx append-paragraph <file> '<text>' [--style=NAME]");
   const style = getStyleFlag(rest2);
@@ -98826,6 +98883,7 @@ async function docxAppendParagraph(filePath, rest2) {
   await writeDoc(filePath, replaceChildren(doc, newChildren));
 }
 async function docxInsertParagraph(filePath, rest2) {
+  rejectUnknownFlags(rest2, ["--style=", "--at="], "docx insert-paragraph");
   const text = firstPositional(rest2);
   const at2 = getAtFlag(rest2);
   if (!filePath || text === void 0 || at2 === void 0) {
@@ -98842,6 +98900,7 @@ async function docxInsertParagraph(filePath, rest2) {
   await writeDoc(filePath, replaceChildren(doc, newChildren));
 }
 async function docxDeleteBlock(filePath, rest2) {
+  rejectUnknownFlags(rest2, ["--at="], "docx delete-block");
   const at2 = getAtFlag(rest2);
   if (!filePath || at2 === void 0) fail2("Usage: lotics docx delete-block <file> --at=<index>");
   const doc = await loadFile2(filePath);
@@ -99119,7 +99178,14 @@ join across something that occupies space in the text (a line break, tab, symbol
 because the joined string does not represent it. The same rule applies inside a table cell as outside it. When a
 search fails but the words ARE on the page, the error names the block and the mark that split them.`);
 }
+var DOCX_FIXED_ARITY = /* @__PURE__ */ new Map([
+  ["write", 1],
+  ["replace-text", 2],
+  ["batch", 1]
+]);
 async function runDocxCommand(subcommand, toolArgs, restArgs) {
+  const arity = DOCX_FIXED_ARITY.get(subcommand ?? "");
+  if (arity !== void 0) rejectExtraArgs(restArgs, arity, `lotics docx ${subcommand}`);
   switch (subcommand) {
     case "read":
       return docxRead(toolArgs, restArgs);

package/docs/cli_reference.md

@@ -45,7 +45,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app rename "<new name>"` | Change the app's display name (launcher/title) via the `update_app` tool. app_id comes from the local `package.json` manifest; the public address (`subdomain`) and code (`deploy`) are unchanged. |
 | `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the installation's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. The dev-optimizer pre-bundle list (`optimizeDeps.include`, load-bearing for dev) is imported from `@lotics/ui/vite` (`loticsOptimizeDeps`) rather than hardcoded in the scaffold, so it tracks the installed `@lotics/ui` and can never go stale. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
 | `LOTICS_UI_SRC=<abs path to packages/ui/src>` (env, not a command) | Dev-link `@lotics/ui` to a monorepo checkout for the length of ONE command, **for every tool at once**. The app's `vite.config.ts` gets its whole `resolve` block from the kit (`resolve: loticsResolve()` — `@lotics/ui/vite`), which reads the variable at call time and adds the `@lotics/ui/*` → working-copy alias, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. In the same breath, every command that regenerates types (`create`/`pull`/`dev`/`deploy`/`codegen`, all via `writeAppDts`) writes **`.lotics/tsconfig.link.json`** — the matching `paths`, which the app's `tsconfig.json` `extends` — so `tsc`, vitest, eslint and your EDITOR resolve the same copy Vite does. Unset ⇒ every one of them goes back to `node_modules`, and the generated file is rewritten inert. **Why `paths` and not `npm link`:** the kit ships un-built `.tsx`, so a kit file outside `node_modules` resolves its OWN `react`/`react-native` from the monorepo — two copies in one program and every shared type stops matching ("Two different types with this name exist, but they are unrelated"). The generated file therefore also pins every peer @lotics/ui declares to the APP's copy, types-package first (`react` → `@types/react`; pinning the runtime package instead strands tsc on a `.js` with no declarations). The pin set is derived from the installed kit's `peerDependencies`, so it tracks the kit rather than rotting. **Nothing hand-written is touched** — the generated file lives in `.lotics/` (the CLI's own dir) and no config is edited by regex, which is what the deleted `lotics ui link` did when it twice destroyed the load-bearing `react-native` alias along with the array's closing bracket. Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app deploy` still warns whenever the variable is set — that the bundle carries kit code from your working copy, or that the app's config predates `loticsResolve()` and never reads it, so the PUBLISHED kit is going out. An app whose `tsconfig.json` already `extends` something else is told rather than rewritten: add `./.lotics/tsconfig.link.json` to the array yourself. |
-| `lotics xlsx <subcmd>` | Local .xlsx read/write/edit using the bundled `@lotics/xlsx` engine (no auth, no network). 14 named subcommands (read, write, set-cell, clear-range, merge, unmerge, add-sheet, delete-sheet, rename-sheet, insert-rows, delete-rows, insert-cols, delete-cols, set-style) + `batch` for applying multiple of the same 14 ops in a single parse/export cycle. `read` also takes `--sheet <name>` (limit output to one sheet — unknown name fails with the available list) and `--range <sheet>!<A1:G60>` (limit to a cell window; the `<sheet>!` prefix is optional when `--sheet` supplies the sheet, a single cell like `S1!B2` is a 1×1 window) to trim a large workbook's JSON — the output shape is unchanged, only the `sheets` array and each sheet's `cells` map are filtered. **`read` reports formatting back, so a generated file is verifiable through this path** rather than by unzipping OOXML: each cell carries `numFmt` when the file gave it one, and `--with-format` adds the resolved `style`. The asymmetry is deliberate — a parsed cell's style is *never* absent (every cell resolves to at least a font — size, name, colour), so emitting it by default would put three noise keys on every plain cell and make “is this styled?” unanswerable by presence; `numFmt` is genuinely absent on an unformatted cell, so it needs no flag. **`write` takes sheet-level `colWidths` (`{"A":34}`) and `rowHeights` (`{"1":44}`)** — without them every column is the default width and a human-facing workbook is unreadable no matter what the cells say. Both are written *pinned* (`customWidth`/`customHeight`), so Excel does not auto-fit them away, and both apply to a row/column that holds no cells (a spacer row's height survives). Keys are a bare column letter and a bare row number, bounded by Excel's grid (`A`…`XFD`, `1`…`1048576`): a key outside it, or a cell ref like `A1` where a column letter belongs, is **rejected** rather than resolved to something adjacent — past the grid the reference is written into the file verbatim, addressing a cell that cannot exist. Unknown **sheet** properties are rejected on the same terms as unknown cell properties — a silently-ignored `columnWidths` typo is a file that looks written and is not. Atomic in-place write (temp file + rename). |
+| `lotics xlsx <subcmd>` | Local .xlsx read/write/edit using the bundled `@lotics/xlsx` engine (no auth, no network). 14 named subcommands (read, write, set-cell, clear-range, merge, unmerge, add-sheet, delete-sheet, rename-sheet, insert-rows, delete-rows, insert-cols, delete-cols, set-style) + `batch` for applying multiple of the same 14 ops in a single parse/export cycle. `read` also takes `--sheet <name>` (limit output to one sheet — unknown name fails with the available list) and `--range <sheet>!<A1:G60>` (limit to a cell window; the `<sheet>!` prefix is optional when `--sheet` supplies the sheet, a single cell like `S1!B2` is a 1×1 window) to trim a large workbook's JSON — the output shape is unchanged, only the `sheets` array and each sheet's `cells` map are filtered. **`read` reports formatting back, so a generated file is verifiable through this path** rather than by unzipping OOXML: each cell carries `numFmt` when the file gave it one, and `--with-format` adds the resolved `style`. The asymmetry is deliberate — a parsed cell's style is *never* absent (every cell resolves to at least a font — size, name, colour), so emitting it by default would put three noise keys on every plain cell and make “is this styled?” unanswerable by presence; `numFmt` is genuinely absent on an unformatted cell, so it needs no flag. **`write` takes sheet-level `colWidths` (`{"A":34}`) and `rowHeights` (`{"1":44}`)** — without them every column is the default width and a human-facing workbook is unreadable no matter what the cells say. Both are written *pinned* (`customWidth`/`customHeight`), so Excel does not auto-fit them away, and both apply to a row/column that holds no cells (a spacer row's height survives). Keys are a bare column letter and a bare row number, bounded by Excel's grid (`A`…`XFD`, `1`…`1048576`): a key outside it, or a cell ref like `A1` where a column letter belongs, is **rejected** rather than resolved to something adjacent — past the grid the reference is written into the file verbatim, addressing a cell that cannot exist. Unknown **sheet** properties are rejected on the same terms as unknown cell properties — a silently-ignored `columnWidths` typo is a file that looks written and is not. A subcommand whose trailing args are ALL flags (`xlsx read`, `docx read`, `docx append-paragraph`/`insert-paragraph`/`delete-block`) **rejects a `--flag` it does not know** — `parseArgs` files an unrecognised token as a positional, so a mistyped flag would otherwise arrive as inert text and the command would report success without it (`--with-formats` then reads as proof the file carries no styles). Subcommands whose trailing arg is CONTENT (`xlsx set-cell`, `docx replace-text`) are deliberately exempt from the FLAG check: a value may legitimately begin with `--`, and there a typo is indistinguishable from data. They are covered instead by arity — **every fixed-shape subcommand refuses an argument past the last one it reads**, whatever it looks like, because the likeliest source is a flag the caller believes exists and these commands write in place (`xlsx delete-rows f.xlsx S1 5 3 --dry-run` deleted three rows and reported success). Arity rather than a leading `--` is the discriminator, since a sheet name may legitimately begin with one. Every subcommand that can introduce a formula (`write`, `set-cell`, `batch`) **evaluates it and writes the cached value**, so a generated formula does not read back blank: Excel and Sheets recalculate on open, but parsers — including this CLI's `read` and the rest of the platform — take the cached `<v>`. A formula the engine cannot evaluate still gets written, with a stderr warning naming the cells, rather than silently leaving a hole where a number belongs. Atomic in-place write (temp file + rename). |
 | `lotics docx <subcmd>` | Local .docx read/write/edit using the bundled `@lotics/docx` engine (OOXML round-trip surface only — no ProseMirror baggage). Subcommands: read, write, append-paragraph, insert-paragraph, delete-block, replace-text, batch. A legacy `.doc` (Word 97–2003 OLE2 binary) is detected in `loadFile` and routed through `@lotics/ooxml`'s `loadDocxFromBuffer` (which re-emits it as real OOXML) before reading — so `lotics docx read` works on a `.doc`, not just a `.docx`. Opaque blocks (tables, custom XML) preserved verbatim. Atomic in-place write. **`replace-text` matches across run boundaries** — Word splits a run at every formatting change, so a `{{marker}}` routinely lands split — and reads straight THROUGH marks that occupy no place in the sentence (`w:proofErr`, `w:footnoteReference`, endnote/comment refs + ranges, `w:bookmarkStart`/`End`, `w:lastRenderedPageBreak`). `w:proofErr` is the one that decides whether this works in practice — Word brackets every word its dictionary rejects, so on non-English text it lands between nearly every pair of runs. It still refuses to join across anything that occupies space in the text — `w:br`, `w:tab`, `w:sym`, a drawing, or any tag not on that allowlist — because the joined string does not represent the glyph and a match there would rewrite text the caller never saw. The SAME rule applies inside a table cell as outside it — both run one `replaceInParagraph` over paragraphs found at any depth, so a marker split by a line break is refused in both rather than rewritten in the cell and skipped in the body under a success message. Zero matches is always a hard error, never a silent no-op, and when the words ARE on the page the error names the block and the splitting mark (`The text IS present at block 1, split by w:br …`) rather than claiming the text is absent. |
 | `lotics file preview <file\|fil_id> [-o out.png]` | (also `lotics preview`) Render a .docx/.xlsx to a PNG using the SAME engines the frontend FilePreview uses (`@lotics/docx` `loadDocxIntoElement` / `@lotics/xlsx` `drawSpreadsheet`) — so what you see matches an operator. Accepts a **local path** OR a stored **`fil_…` id** (`isStoredFileId` — a bare id, no extension): an id is first downloaded to a temp dir via `downloadFileById` (the `signed_url` presign path — same authority as `lotics file download`), rendered, then the transient source is removed; with no `-o` the PNG lands in cwd under the stored file's base name (`defaultPreviewOutputPath`). Drives a headless Chrome over **CDP with only Node built-ins** (`WebSocket`/`fetch`/`http`/`child_process`) — zero npm deps, the CLI stays a single bundled binary. The browser render logic is a separate esbuild **browser** bundle shipped at `dist/render_page.js` (built by `build_cli.mjs`, excluded from the node `tsgo`), served over a throwaway localhost http server and screenshotted full-page. **Requires a Chrome/Chromium on the machine** — detected from `CHROME_PATH`/`LOTICS_CHROME`, then Playwright's installed chromium, then system paths — inherent to rendering these browser formats; a clear "install a browser" error otherwise. PDFs need no render (open them directly). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.114.0",
+  "version": "0.116.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {