@lotics/cli 0.109.0 → 0.110.0

package/dist/src/cli.js

@@ -45332,7 +45332,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 
 // src/starter_template.ts
-var STARTER_FALLBACK_UI_VERSION = "12.1.0";
+var STARTER_FALLBACK_UI_VERSION = "27.11.0";
 var STARTER_FALLBACK_SDK_VERSION = "0.52.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 var VITEST_SETUP_FILENAME = "vitest.setup.ts";
@@ -45486,7 +45486,7 @@ function buildStarterTemplate(args) {
 import { defineConfig } from "vite";
 import type { Plugin } from "vite";
 import react from "@vitejs/plugin-react";
-import { loticsOptimizeDeps } from "@lotics/ui/vite";
+import { loticsOptimizeDeps, loticsResolve } from "@lotics/ui/vite";
 
 // @lotics/ui/icon.tsx deep-imports \`lucide-react-native/dist/esm/icons/<name>\`.
 // lucide-react-native's \`exports\` map lists only "." and "./icons", so a strict
@@ -45515,11 +45515,6 @@ function lucideIconsWebAlias(): Plugin {
 // render endpoint rewrites those to /v1/apps/{id}/asset/... so the bundle
 // loads via the platform's asset proxy. Don't change \`base\` unless you
 // also adjust the rewrite logic in backend/api/apps.ts:rewriteAssetPaths.
-//
-// react-native \u2192 react-native-web alias lets @lotics/ui's RN primitives
-// (View, Text, Pressable, StyleSheet, etc.) render in a pure-web environment.
-// .web.tsx is prioritized in resolve.extensions so per-target variants
-// (avatar.web.tsx, wave_avatar.web.tsx) win over the native .tsx file.
 export default defineConfig({
   plugins: [lucideIconsWebAlias(), react()],
   // RN libraries reference globals Metro injects but Vite does not \u2014 undefined
@@ -45531,41 +45526,18 @@ export default defineConfig({
   // rn-web only reads \`global.x\` as a free var, so mapping it to \`globalThis\`
   // is safe. Define both so dev and the deployed build behave identically.
   define: { __DEV__: "false", global: "globalThis" },
-  resolve: {
-    // \`LOTICS_UI_SRC\` dev-links @lotics/ui to a monorepo checkout, so kit edits
-    // go live (HMR) and bundle on deploy without a publish round-trip:
-    //   LOTICS_UI_SRC=/abs/path/to/packages/ui/src lotics app dev
-    // Unset \u21D2 the kit resolves from node_modules as normal. It lives in the ENV,
-    // never in this file: the link used to be written here by \`lotics ui link\`
-    // and removed by \`--remove\`, which is a regex editing TypeScript \u2014 it twice
-    // took the react-native alias below with it and left the app unable to build.
-    // State that only exists for the length of one command belongs in the command.
-    // VITE ONLY: \`tsc\` still resolves @lotics/ui from node_modules (the kit's
-    // src is RN-Web and cannot typecheck inside an app), so typecheck the kit in
-    // packages/ui and let the publish restore this app's own typecheck.
-    alias: [
-      ...(process.env.LOTICS_UI_SRC
-        ? [{ find: /^@lotics\\/ui\\/(.+)$/, replacement: \`\${process.env.LOTICS_UI_SRC}/$1\` }]
-        : []),
-      { find: "react-native", replacement: "react-native-web" },
-    ],
-    // \`.web.js\` resolves the web build of RN packages that ship \`X.js\` (native)
-    // beside \`X.web.js\` (web) \u2014 e.g. @react-native-picker/picker, whose compiled
-    // \`Picker.web.js\` renders a real <select>. Without it the extensionless
-    // \`require("./Picker")\` picks native \`Picker.js\` and the standard Picker
-    // renders nothing on web.
-    // \`.mjs\`/\`.mts\` keep parity with Vite's DEFAULT resolver, which this override
-    // otherwise drops \u2014 a bare package subpath that ships ONLY as \`.mjs\` (e.g.
-    // \`lucide-react/dynamic\`, imported by @lotics/ui's DynamicIcon/AppIcon) would
-    // fail to resolve under \`lotics app dev\` while the prod rollup build resolves
-    // it, so the gap is dev-only and silent (build/typecheck/lint stay green).
-    extensions: [".web.tsx", ".web.ts", ".web.js", ".tsx", ".ts", ".jsx", ".js", ".mjs", ".mts"],
-    // @lotics/ui ships source and is consumed across many subpath entries
-    // (./card, ./metric, ./use_screen_size, \u2026). Without dedupe, Vite can
-    // pre-bundle a subpath into its own chunk with a second React copy \u2014 a
-    // hook called from there hits a null dispatcher ("Invalid hook call").
-    // Pin React (and RN-Web) to a single instance shared by every chunk.
-    dedupe: ["react", "react-dom", "react-native-web"],
+  // The kit owns its own resolution \u2014 the react-native \u2192 react-native-web alias,
+  // \`.web.tsx\`-first extensions, the React dedupe, and the \`LOTICS_UI_SRC\`
+  // dev-link \u2014 for the same reason it owns \`loticsOptimizeDeps\`: every entry is
+  // dictated by @lotics/ui's internals, so shipping it WITH the kit means it can
+  // never drift from the version installed here. It also stops being an app's job
+  // to hand-carry a load-bearing alias that a regex edit twice deleted (GAP-133/142).
+  // \`lotics app codegen\` writes the matching \`paths\` into
+  // .lotics/tsconfig.link.json, so tsc/vitest/eslint/your editor resolve the same
+  // @lotics/ui this does. To add your own alias, spread it:
+  //   const base = loticsResolve();
+  //   resolve: { ...base, alias: [...base.alias, { find: "x", replacement: "y" }] }
+  resolve: loticsResolve(),
   },
   optimizeDeps: {
     // The dev dep-optimizer must pre-bundle @lotics/ui's RN-ecosystem + markdown
@@ -45942,48 +45914,6 @@ declare module "lucide-react-native/dist/esm/icons/*" {
 
 // Plain side-effect CSS imports (@lotics/ui ships .tsx with import "./x.css").
 declare module "*.css";
-`
-    },
-    {
-      path: "src/react_native.d.ts",
-      content: `import "react-native";
-
-// Augments react-native's types with the web-only fields @lotics/ui consumes:
-// Pressable's \`hovered\` callback state, plus web-only ViewStyle / TextStyle
-// properties (cursor, outline, boxShadow, etc.) used by its primitives.
-// Each iframe app needs its own copy \u2014 TypeScript doesn't auto-pick-up
-// \`.d.ts\` files inside dependencies.
-declare module "react-native" {
-  interface PressableStateCallbackType {
-    hovered: boolean;
-  }
-
-  interface ViewStyle {
-    backdropFilter?: string;
-    backgroundImage?: string;
-    boxShadow?: string;
-    boxSizing?: string;
-    cursor?: string;
-    touchAction?: string;
-    transitionDuration?: string;
-    transitionProperty?: string;
-    appearance?: string;
-    outline?: string;
-    outlineColor?: string;
-    outlineStyle?: string;
-    outlineWidth?: number;
-    outlineOffset?: number;
-  }
-
-  interface TextStyle {
-    outline?: string;
-    outlineColor?: string;
-    outlineStyle?: string;
-    outlineWidth?: number;
-    outlineOffset?: number;
-    appearance?: string;
-  }
-}
 `
     },
     {
@@ -70530,10 +70460,75 @@ function ensureAppTsconfig(projectDir) {
     parsed.exclude = [...currentEx, ...toAdd];
     changes.push(`added ${toAdd.join(", ")} to "exclude"`);
   }
+  const existingExtends = parsed.extends;
+  if (existingExtends === void 0) {
+    parsed.extends = `./${LINK_TSCONFIG}`;
+    changes.push(`added "extends": "./${LINK_TSCONFIG}" (so tsc resolves the same @lotics/ui as Vite)`);
+  } else if (existingExtends !== `./${LINK_TSCONFIG}`) {
+    console.error(
+      `\u26A0 tsconfig.json already extends ${JSON.stringify(existingExtends)}, so the dev-link config was not added \u2014 \`tsc\` will keep resolving @lotics/ui from node_modules even under LOTICS_UI_SRC. Add "./${LINK_TSCONFIG}" to "extends" (it accepts an array) to fix it.`
+    );
+  }
   if (changes.length === 0) return;
   fs4.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
   console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
 }
+var LINK_TSCONFIG = ".lotics/tsconfig.link.json";
+function writeDevLinkTsconfig(projectDir) {
+  const uiSrc = process.env.LOTICS_UI_SRC;
+  const paths = {};
+  if (uiSrc) {
+    paths["@lotics/ui/*"] = [`${uiSrc}/*`];
+    for (const peer of readKitPeerNames(projectDir)) {
+      const typesDir = path5.join(projectDir, "node_modules", typesPackageFor(peer));
+      const runtimeDir = path5.join(projectDir, "node_modules", peer);
+      const target = fs4.existsSync(typesDir) ? `../node_modules/${typesPackageFor(peer)}` : fs4.existsSync(runtimeDir) ? `../node_modules/${peer}` : null;
+      if (!target) continue;
+      paths[peer] = [target];
+      paths[`${peer}/*`] = [`${target}/*`];
+    }
+  }
+  const file2 = path5.join(projectDir, ".lotics", "tsconfig.link.json");
+  const header = uiSrc ? `// GENERATED by \`lotics app codegen\` \u2014 do not edit.
+// LOTICS_UI_SRC is set, so @lotics/ui resolves to your working copy for tsc,
+// vitest, eslint and your editor \u2014 the same copy Vite is bundling. The peer
+// pins keep ONE react / react-native in the program; without them the kit's
+// source resolves its own copies and every shared type stops matching.
+// Unset LOTICS_UI_SRC and re-run to go back to the published kit.
+` : `// GENERATED by \`lotics app codegen\` \u2014 do not edit.
+// LOTICS_UI_SRC is not set, so this is inert and @lotics/ui resolves from
+// node_modules as normal.
+`;
+  fs4.writeFileSync(file2, `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
+`);
+  return file2;
+}
+function writeKitTypeAugmentation(projectDir) {
+  const uiSrc = process.env.LOTICS_UI_SRC;
+  const source = uiSrc ? path5.join(uiSrc, "react_native.d.ts") : path5.join(projectDir, "node_modules", "@lotics", "ui", "src", "react_native.d.ts");
+  const target = path5.join(projectDir, ".lotics", "react_native.d.ts");
+  if (!fs4.existsSync(source)) {
+    if (fs4.existsSync(target)) fs4.rmSync(target);
+    return;
+  }
+  fs4.writeFileSync(
+    target,
+    `// GENERATED by \`lotics app codegen\` from @lotics/ui \u2014 do not edit.
+// The kit's web-only ViewStyle/TextStyle properties, which react-native does
+// not model. Delete any hand-copied src/react_native.d.ts; this replaces it.
+` + fs4.readFileSync(source, "utf-8")
+  );
+}
+function typesPackageFor(peer) {
+  return peer.startsWith("@") ? `@types/${peer.slice(1).replace("/", "__")}` : `@types/${peer}`;
+}
+function readKitPeerNames(projectDir) {
+  const kitPkg = path5.join(projectDir, "node_modules", "@lotics", "ui", "package.json");
+  if (!fs4.existsSync(kitPkg)) return [];
+  const parsed = JSON.parse(fs4.readFileSync(kitPkg, "utf-8"));
+  const peers = parsed.peerDependencies;
+  return peers && typeof peers === "object" ? Object.keys(peers) : [];
+}
 function writeAppDts(projectDir, manifest) {
   const dotLotics = path5.join(projectDir, ".lotics");
   fs4.mkdirSync(dotLotics, { recursive: true });
@@ -70543,6 +70538,8 @@ function writeAppDts(projectDir, manifest) {
     [path5.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
   ];
   for (const [file2, content] of written) fs4.writeFileSync(file2, content);
+  writeDevLinkTsconfig(projectDir);
+  writeKitTypeAugmentation(projectDir);
   ensureAppTsconfig(projectDir);
   return written.map(([file2]) => file2);
 }
@@ -70611,28 +70608,26 @@ function warnAppFieldsUnwritten(projectDir, err2) {
     `\u26A0 Could not generate .lotics/app_fields.ts (${reason}), and this project has none. Any source importing F/OPT will fail to build with 'Could not resolve "../../.lotics/app_fields"'. Run 'lotics app codegen' once you can reach the workspace.`
   );
 }
-function warnIfDeployingLinkedKit(projectDir) {
-  const uiSrc = process.env.LOTICS_UI_SRC;
-  if (!uiSrc) return;
-  const viteConfigPath = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(viteConfigPath)) return;
-  if (!fs4.readFileSync(viteConfigPath, "utf-8").includes("LOTICS_UI_SRC")) return;
-  console.error(
-    `\u26A0 LOTICS_UI_SRC is set \u2014 this deploy bundles @lotics/ui from ${uiSrc}, NOT the published package. The deployed app will run kit code that exists only on this machine. Unset it and re-deploy once the kit change is published if that is not what you want.`
-  );
-}
-function warnIfDevLinkIgnored(projectDir) {
+function warnAboutDevLink(projectDir, command) {
   const uiSrc = process.env.LOTICS_UI_SRC;
   if (!uiSrc) return;
   const viteConfigPath = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(viteConfigPath)) return;
-  if (fs4.readFileSync(viteConfigPath, "utf-8").includes("LOTICS_UI_SRC")) return;
-  console.error(
-    `\u26A0 LOTICS_UI_SRC is set but vite.config.ts never reads it \u2014 @lotics/ui will still resolve from node_modules, so kit edits will NOT appear. Add the dev-link entry to \`resolve.alias\` (refresh vite.config.ts from the starter, or paste):
-    ...(process.env.LOTICS_UI_SRC
-      ? [{ find: /^@lotics\\/ui\\/(.+)$/, replacement: \`\${process.env.LOTICS_UI_SRC}/$1\` }]
-      : []),`
-  );
+  const config2 = fs4.existsSync(viteConfigPath) ? fs4.readFileSync(viteConfigPath, "utf-8") : "";
+  const linked = config2.includes("loticsResolve") || config2.includes("LOTICS_UI_SRC");
+  if (!linked) {
+    console.error(
+      `\u26A0 LOTICS_UI_SRC is set but vite.config.ts never reads it \u2014 @lotics/ui will still resolve from node_modules, so kit edits will NOT ${command === "deploy" ? "ship" : "appear"}. Hand the whole resolve block to the kit (it owns the dev-link, the react-native alias, the extensions and the dedupe):
+    import { loticsOptimizeDeps, loticsResolve } from "@lotics/ui/vite";
+    // \u2026
+    resolve: loticsResolve(),`
+    );
+    return;
+  }
+  if (command === "deploy") {
+    console.error(
+      `\u26A0 LOTICS_UI_SRC is set \u2014 this deploy bundles @lotics/ui from ${uiSrc}, NOT the published package. The deployed app will run kit code that exists only on this machine. Unset it and re-deploy once the kit change is published if that is not what you want.`
+    );
+  }
 }
 function ensureAppVitestSetup(projectDir) {
   const setupPath = path5.join(projectDir, VITEST_SETUP_FILENAME);
@@ -70944,7 +70939,7 @@ function readAppSourceText(projectDir) {
 async function appDeploy(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
-  warnIfDeployingLinkedKit(projectDir);
+  warnAboutDevLink(projectDir, "deploy");
   const liveApp = await client.getApp(meta3.app_id);
   const divergences = agentTypeDivergences(meta3.agents, liveApp.agents);
   if (divergences.length > 0) {
@@ -71100,7 +71095,7 @@ async function appCheck(client, args = {}) {
   Take the app's shape with 'lotics app pull ${meta3.app_id}', or change the agent with set_app_agent.`
     );
   }
-  warnIfDeployingLinkedKit(projectDir);
+  warnAboutDevLink(projectDir, "deploy");
   warnIfAgentProseDiffers(projectDir, app.agents);
   warnIfDynamicAliases(called);
   warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
@@ -71167,7 +71162,7 @@ function warnIfUnboundAliases(app, called) {
 async function appDev(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
-  warnIfDevLinkIgnored(projectDir);
+  warnAboutDevLink(projectDir, "dev");
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   const app = await client.getApp(meta3.app_id);
   const handle = await startDevServer({

package/docs/cli_reference.md

@@ -44,7 +44,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app subdomain <new-subdomain>` | Rename the app's public `<slug>.lotics.app` address via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
 | `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: the app's own `vite.config.ts` reads the variable and adds a `{ find: /^@lotics\/ui\/(.+)$/, replacement: "<LOTICS_UI_SRC>/$1" }` entry to `resolve.alias`, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. Unset ⇒ the kit resolves from `node_modules` as normal. **Nothing is written to disk** — there is no link/unlink step, nothing to leave switched on, and no config for the CLI to corrupt (the `lotics ui link` command this replaces edited `vite.config.ts` by regex and twice deleted the load-bearing `react-native` → `react-native-web` alias with the array's closing bracket, breaking the app's build entirely). Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app dev` **warns** when the variable is set but the app's `vite.config.ts` predates it (scaffolded earlier) and prints the lines to add; `app deploy` **warns** that the bundle carries kit code from your working copy rather than the published package. **Vite-only, by design:** the app's `tsc` still resolves `@lotics/ui` from `node_modules` (the published `.d.ts`) — the kit `src` can't be typechecked inside an app because it's RN-Web, so typecheck the kit in `packages/ui` and let the finalize publish restore the app's own typecheck. |
+| `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. 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.109.0",
+  "version": "0.110.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {