@lotics/cli 0.113.0 → 0.116.0

package/dist/src/cli.js

@@ -64471,12 +64471,6 @@ var TIER_MODELS = {
 var RESOLVED_MODEL_IDS = MODEL_TIERS.map(
   (tier) => TIER_MODELS[tier]
 );
-function tierForModelId(modelId) {
-  for (const tier of MODEL_TIERS) {
-    if (modelId.startsWith(`claude-${tier}-`)) return tier;
-  }
-  return null;
-}
 var DEFAULT_MODEL_TIER = "sonnet";
 var UTILITY_MODEL_TIER = "haiku";
 var DEFAULT_MODEL_ID = TIER_MODELS[DEFAULT_MODEL_TIER];
@@ -64944,15 +64938,6 @@ var appAgentDeclarationSchema = zod_default.object({
   model_tier: zod_default.enum(MODEL_TIERS).optional().describe(
     "Model tier the agent runs on \u2014 `haiku`, `sonnet`, or `opus`. Omit to follow the platform default tier, resolved at run time: the preferred choice. A tier names capability, not a version, so the generation behind it moves with the platform and this declaration never needs a rewrite. Pin only a deliberate, tested choice."
   ),
-  /**
-   * LEGACY, read-only. A version pin written by a release from before tiers.
-   * Parsed so a declaration an older release wrote during the rollout window
-   * still resolves (via `tierForModelId`) instead of reading as unpinned
-   * and silently dropping to the default. Never written by this release, and
-   * rejected on the write surface. Deleted with the strip migration, once no
-   * deployed release writes it.
-   */
-  model_id: zod_default.string().min(1).optional(),
   effort_level: zod_default.enum(EFFORT_LEVELS).optional().describe(
     "Reasoning depth for adaptive-thinking tiers \u2014 one of the chosen tier's supported levels (validated against model_tier at declare time). Omit to use the model default; ignored on tiers without adaptive thinking."
   ),
@@ -65094,8 +65079,6 @@ var agentStepSchema = stepBaseSchema.extend({
   input: zod_default.record(zod_default.string(), toolInputValueSchema),
   tool_names: zod_default.array(zod_default.string().min(1)),
   model_tier: zod_default.enum(MODEL_TIERS).optional(),
-  /** LEGACY, read-only — see `appAgentDeclarationSchema.model_id`. */
-  model_id: zod_default.string().min(1).optional(),
   output: agentOutputSpecSchema
 });
 var breakStepSchema = stepBaseSchema.extend({
@@ -69719,7 +69702,7 @@ function walkAgentInvocation(call, scope, stepId, description) {
   let model_tier;
   if (modelNode) {
     const literal2 = readStaticString(modelNode, "agent `model`");
-    const tier = MODEL_TIERS.includes(literal2) ? literal2 : tierForModelId(literal2);
+    const tier = MODEL_TIERS.includes(literal2) ? literal2 : null;
     if (!tier) {
       fail(
         modelNode,
@@ -70275,7 +70258,7 @@ function agentFilePath2(projectDir, alias) {
 }
 var CLI_AGENT_NOTES = [
   "Pulled from the LIVE app row; edit here, then: lotics app agent set <alias>",
-  "The typed fields (inputs/outputs/tool_names/model_id) live in package.json#lotics.agents"
+  "The typed fields (inputs/outputs/tool_names/model_tier) live in package.json#lotics.agents"
 ];
 function writeAgentFile(projectDir, alias, instructions) {
   fs4.mkdirSync(path5.join(projectDir, AGENTS_DIR), { recursive: true });
@@ -71446,7 +71429,7 @@ async function appAgentSet(client, args) {
     process.exit(1);
   }
   console.error(
-    `Set agent "${args.alias}" (${instructions.length} chars of instructions` + (live.model_id ? `, ${live.model_id}` : "") + `). Typed fields left as they are.`
+    `Set agent "${args.alias}" (${instructions.length} chars of instructions` + (live.model_tier ? `, ${live.model_tier}` : "") + `). Typed fields left as they are.`
   );
 }
 async function appWorkflowSet(client, args) {
@@ -71820,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`);
@@ -92213,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) {
@@ -93180,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");
@@ -93206,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);
 }
@@ -93459,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);
@@ -98800,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));
@@ -98834,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);
@@ -98843,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) {
@@ -98859,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);
@@ -99136,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/dist/src/client.d.ts

@@ -233,7 +233,7 @@ export declare class LoticsClient {
         agents?: Record<string, {
             instructions?: string;
             tool_names?: string[];
-            model_id?: string;
+            model_tier?: string;
             inputs?: Record<string, unknown>;
             outputs?: Record<string, unknown>;
         }> | null;

package/docs/cli_reference.md

@@ -29,7 +29,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge update <id> [--from <file.md> \| --content <str>] [--name <n>] [--description <d>]` | Call `update_knowledge` with **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). At least one field required; --from and --content are mutually exclusive. |
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics app create <name> [path]` | Scaffold a Vite+React+TS custom-code app project; POST /v1/apps; npm install; vite build; upload as v1 |
-| `lotics app pull <app_id> [path]` | Download source archive from R2 (presigned), extract, npm install, stamp package.json's `lotics` field. With no `[path]`: refresh the cwd IN PLACE when it's already this app's own project (its manifest `app_id` matches — the documented `cd <app> && lotics app pull` flow), else clone into an `<name>/` subdir; this avoids the stray nested `./<name>/` subdir a pull-from-inside-the-app used to drop. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed, AND the runtime `.lotics/app_fields.ts` (the same linked-vs-bespoke branch `app codegen` runs, off the app row already fetched — see that row for the two forms). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. The write NAMES the form and the reason, because an in-place pull can FLIP a project between them (`opctl app publish` links an origin, `package eject` unlinks it) and that changes what the module does at load. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A binding/schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file, and pull always overwrites it from live, leaving no second copy to drift. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_id`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |
+| `lotics app pull <app_id> [path]` | Download source archive from R2 (presigned), extract, npm install, stamp package.json's `lotics` field. With no `[path]`: refresh the cwd IN PLACE when it's already this app's own project (its manifest `app_id` matches — the documented `cd <app> && lotics app pull` flow), else clone into an `<name>/` subdir; this avoids the stray nested `./<name>/` subdir a pull-from-inside-the-app used to drop. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed, AND the runtime `.lotics/app_fields.ts` (the same linked-vs-bespoke branch `app codegen` runs, off the app row already fetched — see that row for the two forms). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. The write NAMES the form and the reason, because an in-place pull can FLIP a project between them (`opctl app publish` links an origin, `package eject` unlinks it) and that changes what the module does at load. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A binding/schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file, and pull always overwrites it from live, leaving no second copy to drift. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_tier`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |
 | `lotics app deploy -m <message>` | **`-m` is REQUIRED** (CLI errors without a non-empty message) — each deploy is a version row read back by `lotics app versions`, so a blank message loses the audit trail. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. Carries code + capabilities only — **neither queries nor workflow/agent bindings are a deploy concern** (`set_app_workflow` / `remove_app_workflow` own `apps.workflows`; the manifest's `workflows` map is a pulled reflection, read by `useWorkflow` codegen and by `app workflow set`, never written by a deploy). Deploy DOES send the manifest's `lotics.workflows` alias KEYS (not the bindings) as `workflow_aliases`, recorded on the version row so `remove_app_workflow` can refuse to unbind an alias the served version still declares. It also reports any `lotics.queries` alias whose declaration DIFFERS from the app's, naming both recoveries (`app query set --all` to push yours, `app pull` to adopt the app's) — a deploy no longer writes them, so the two are allowed to drift. After a successful deploy it **warns loudly about any alias the source CALLS that is NOT bound on the server** (a `getApp` diff via `warnIfUnboundAliases`) — since deploy never binds them, that would otherwise throw only at the app's first `useWorkflow` / `useAgentRun` call; the warning points to `lotics app workflow set` / `set_app_agent`. Advisory only (never fails the deploy). |
 | `lotics app versions [app_id]` | `GET /v1/apps/{id}/versions` — print deploy history newest-first (version number, timestamp, deployer name, build status, the `-m` message; `*` marks the currently-served version). app_id from the local manifest, or pass one to inspect any app without pulling it. Admin-only server-side (mirrors deploy + source download). Answers "what shipped, when, by whom" — e.g. whether a fix was live at an incident's time. The deploy pipeline already persisted all of this in `app_versions`; this is the read surface. Title → stderr, table → stdout (pipeable). |
 | `lotics app codegen [path]` | Regenerate `.lotics/*` from the manifest + workspace schema **without a deploy**. The three `.d.ts` companions (`app_{workflows,queries,agents}.d.ts`) are always rewritten (synchronous, no network). When credentials resolve, also rewrites the **runtime** `.lotics/app_fields.ts` — **branched on whether the app is a package installation** (`getApp().package_id` set, from `generate_package_fields.ts`): a **linked/published** app emits the BINDING form (`F`/`OPT`/`ROLE` resolved from the installation's LIVE binding — via `appBinding` / the `binding` RPC — at module load through `getAppBinding()` + top-level await, so the source stays portable across every install); a **bespoke** app emits the BAKED form (`generate_app_fields.ts`) — a real `.ts` exporting `F` (table→field→`"fld_…"`) + `OPT` (table→select-field→option→`"opt_…"`) keyed by display-name aliases, for the tables the app's queries reference (+ optional `package.json#lotics.codegen.tables` allowlist). Both forms share the `F`/`OPT` shape (contract aliases derive from the same slugified display names), so a published origin's deployed source compiles unchanged. Writing the BINDING form also heals the project's vitest setup (`ensureAppVitestSetup`, folded into the same write boundary): the binding form awaits `getAppBinding()` (a network call) at module load, so without a stub `npm test` fails to collect any test that imports the app graph — the heal writes `vitest.setup.ts` (mocks only `getAppBinding`, returning an echo binding: any alias → a self-identifying `fld:test:…`/`opt:test:…`/`grp:test:…` id) if absent, and warns the one-liner to add to `vite.config.ts`'s `test.setupFiles` if the wiring is missing (TS source isn't safely munged, mirroring `ensureAppTsconfig`'s JSONC-tsconfig warn). New scaffolds ship both. Also refreshes each bound workflow's `.lotics/workflows/<alias>.globals.d.ts` + re-wraps its EXISTING `src/workflows/<alias>.ts` body in the current envelope (strips + re-wraps; never re-fetches the body, so local edits survive). **`.lotics/` is reconciled to the manifest, not merely added to** — a `<alias>.globals.d.ts` whose alias the manifest no longer declares is DELETED (that directory is read as the app's alias inventory, so a companion for a binding nobody can reach misreports what the app has). Only that exact filename shape is removed; anything else in the directory is left alone. The reconcile runs before the credential branch, so it happens offline too. The authored counterpart is never deleted — a `src/workflows/<alias>.ts` the manifest does not declare is NAMED instead (`check` and `set` both take their alias set from the manifest, so editing an undeclared body is a silent no-op). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). **Re-silvers `package.json#lotics.agents`** from the live app row whenever its `inputs`/`outputs` disagree, then rewrites the agent `.d.ts` from the refreshed block: that block is a mirror AND the offline seed for `useAgentRun` typings, so a stale copy types the app against an agent that does not exist. Refreshing here makes the divergence self-healing on a command already in the loop and keeps the remedy off `app pull` (which rewrites `src/workflows/*.ts` and would eat uncommitted body edits). The write is surgical and order-preserving (`orderedLike`), so it changes only the fields that actually differ. A hand edit to that block is therefore reverted — it never changed the agent anyway; to change one, `set_app_agent`. |
@@ -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.113.0",
+  "version": "0.116.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {