@lotics/cli 0.260.1 → 0.261.0

package/dist/probe_page.js

@@ -1835,7 +1835,7 @@ var __loticsProbe = (() => {
     partial_count: {
       law: "reviewing.md",
       section: "8o",
-      fix: "State the server's count of the set, never the rows a page loaded: count the read (`useCount`) and step or badge against that total."
+      fix: "State the server's count of the set, never the rows a page loaded: count the read (`useQuery`'s `total`) and step or badge against that total."
     },
     record_primary: {
       law: "hierarchy.md",

package/dist/src/cli.js

@@ -52,7 +52,7 @@ var __toESM = (mod2, isNodeMode, target) => (target = mod2 != null ? __create(__
 var define_LOTICS_KIT_VERSIONS_default;
 var init_define_LOTICS_KIT_VERSIONS = __esm({
   "<define:__LOTICS_KIT_VERSIONS__>"() {
-    define_LOTICS_KIT_VERSIONS_default = { runtime: "0.42.2" };
+    define_LOTICS_KIT_VERSIONS_default = { runtime: "0.43.0" };
   }
 });
 
@@ -30137,6 +30137,14 @@ var LoticsClient = class {
   async appFieldOptions(app_id, alias2) {
     return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/field-options`, { alias: alias2 });
   }
+  /**
+   * What the app's writes will change — each bound workflow's record-write subset, each query's column
+   * sources, the fields they name. Mirrors GET /v1/apps/{app_id}/write_model; the dev server hands it to
+   * the app's SDK whole, so its parts stay opaque here.
+   */
+  async appWriteModel(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/write_model`);
+  }
   /**
    * Execute a workflow by alias declared in package.json#lotics.workflows.
    * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
@@ -64296,7 +64304,7 @@ function resultSideEffects(result) {
 
 // src/version.ts
 init_define_LOTICS_KIT_VERSIONS();
-var VERSION = "0.260.1";
+var VERSION = "0.261.0";
 
 // src/timezone.ts
 init_define_LOTICS_KIT_VERSIONS();
@@ -69642,6 +69650,47 @@ function matchesTimeOfDay(recordValue, startTime, endTime) {
 
 // ../shared/src/app_query_ast.ts
 init_define_LOTICS_KIT_VERSIONS();
+
+// ../shared/src/interpolate.ts
+init_define_LOTICS_KIT_VERSIONS();
+function interpolateObject(obj, context) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (typeof obj === "string") {
+    const expressionMatches = obj.match(/\{\{.*?\}\}/g);
+    if (expressionMatches && expressionMatches.length > 0) {
+      if (expressionMatches.length === 1 && obj === expressionMatches[0]) {
+        const expression = obj.slice(2, -2).trim();
+        return evaluateJsExpression(expression, context);
+      }
+      const parts = obj.split(/(\{\{.*?\}\})/g);
+      const evaluatedParts = parts.map((part) => {
+        if (part.startsWith("{{") && part.endsWith("}}")) {
+          const expression = part.slice(2, -2).trim();
+          const result = evaluateJsExpression(expression, context);
+          return result != null ? String(result) : "";
+        }
+        return part;
+      });
+      return evaluatedParts.join("");
+    }
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => interpolateObject(item, context));
+  }
+  if (typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = interpolateObject(value, context);
+    }
+    return result;
+  }
+  return obj;
+}
+
+// ../shared/src/app_query_ast.ts
 function collectQueryTableIds(node) {
   const result = /* @__PURE__ */ new Set();
   walk(node, (n) => {
@@ -71452,7 +71501,8 @@ function codeWithoutComments(sourceText) {
   return out.join("");
 }
 var ALIAS_CALL_HOOKS = {
-  queries: ["useQuery", "usePaginatedQuery", "useInfiniteQuery", "useCount", "useFieldOptions", "useQueries", "queryAll"],
+  // `usePaginatedQuery` through `useCounts`: gone from the SDK, still called by bundles on runtime 0.42 or earlier.
+  queries: ["useQuery", "useFieldOptions", "useQueries", "queryAll", "usePaginatedQuery", "useInfiniteQuery", "useCount", "useCounts"],
   workflows: ["useWorkflow", "useWorkflows", "useRecording"],
   agents: ["useAgentRun"]
 };
@@ -76264,7 +76314,7 @@ init_define_LOTICS_KIT_VERSIONS();
 var TOOL_INPUT_SEMANTICS = {
   // ─── Bulk record mutations ─────────────────────────────────────────────
   update_records: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "change" },
     record_ids: { kind: "record_refs" },
     filters: { kind: "filter_tree", table_from: "table_id" },
     set: { kind: "record_data", table_from: "table_id", writes: true },
@@ -76296,7 +76346,7 @@ var TOOL_INPUT_SEMANTICS = {
     field_edits: { kind: "dynamic" }
   },
   create_records: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "change" },
     records: { kind: "record_data_array", table_from: "table_id", writes: true },
     field_keys: { kind: "field_key_refs", table_from: "table_id", writes: true },
     // Per-record cells — semantic depends on field_keys[i]; tool resolves.
@@ -76307,7 +76357,7 @@ var TOOL_INPUT_SEMANTICS = {
     // `rec_*` identifiers) which is all this kind asserts: normalization passes it
     // through raw and nothing resolves it against stored rows.
     ids: { kind: "record_refs" },
-    source_table_id: { kind: "table_ref", removes: false },
+    source_table_id: { kind: "table_ref", rows: "none" },
     record_ids: { kind: "record_refs" },
     filters: { kind: "filter_tree", table_from: "table_id" },
     // Cross-table mapping — {source_field_key: target_field_key}. Not
@@ -76326,28 +76376,28 @@ var TOOL_INPUT_SEMANTICS = {
     // rows of whatever tables a single-valued link points here from, and those
     // are the link graph's answer rather than the source's, so a scan can no
     // more resolve them than it can a field key computed at runtime.
-    table_id: { kind: "table_ref", removes: true },
+    table_id: { kind: "table_ref", rows: "remove" },
     record_ids: { kind: "record_refs" },
     filters: { kind: "filter_tree", table_from: "table_id" },
     cascade: { kind: "scalar" }
   },
   restore_records: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "change" },
     record_ids: { kind: "record_refs" },
     filters: { kind: "filter_tree", table_from: "table_id" }
   },
   lock_records: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "change" },
     record_ids: { kind: "record_refs" },
     filters: { kind: "filter_tree", table_from: "table_id" }
   },
   unlock_records: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "change" },
     record_ids: { kind: "record_refs" },
     filters: { kind: "filter_tree", table_from: "table_id" }
   },
   request_locked_record_change: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "none" },
     record_id: { kind: "record_ref" },
     // Map of field_key → new value; key validation and per-field value
     // resolution depend on the table schema, resolved at execute time.
@@ -76356,7 +76406,7 @@ var TOOL_INPUT_SEMANTICS = {
   },
   // ─── Query surfaces ────────────────────────────────────────────────────
   query_records: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "none" },
     view_id: { kind: "scalar" },
     field_keys: { kind: "field_key_refs", table_from: "table_id", writes: false },
     filters: { kind: "filter_tree", table_from: "table_id" },
@@ -76397,7 +76447,7 @@ var TOOL_INPUT_SEMANTICS = {
     limit: { kind: "scalar" }
   },
   aggregate_records: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "none" },
     filters: { kind: "filter_tree", table_from: "table_id" },
     // Nested {field_key, operation} shape — current vocabulary has no
     // nested-field-key kind, so the tool resolves at execute time.
@@ -76408,14 +76458,14 @@ var TOOL_INPUT_SEMANTICS = {
   get_record: {
     // Schema only takes `record_id`; table_id is optional/derived.
     record_id: { kind: "record_ref" },
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "none" },
     // Keys on the record's own table, which `table_id` names when supplied and
     // the record resolves otherwise — the same position it holds on a query.
     field_keys: { kind: "field_key_refs", table_from: "table_id", writes: false }
   },
   // ─── View management ──────────────────────────────────────────────────
   create_view: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "none" },
     name: { kind: "text" },
     frozen_columns: { kind: "scalar" },
     // summary keys are field_keys on `table_id`, values are view-summary
@@ -76452,13 +76502,13 @@ var TOOL_INPUT_SEMANTICS = {
   },
   // ─── Buttons (table-scoped field with action) ─────────────────────────
   press_button: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "unnamed" },
     record_id: { kind: "record_ref" },
     field_key: { kind: "field_key_ref", table_from: "table_id", writes: false }
   },
   // ─── Table management ─────────────────────────────────────────────────
   update_table: {
-    table_id: { kind: "table_ref", removes: false },
+    table_id: { kind: "table_ref", rows: "change" },
     name: { kind: "text" },
     description: { kind: "text" },
     // add_fields carries NEW field definitions (not refs to existing ones).
@@ -76898,7 +76948,7 @@ function bodyWrites(source) {
       const semantic = semantics[kwarg];
       if (semantic === void 0) continue;
       if (semantic.kind === "table_ref") {
-        if (semantic.removes) deletes.push(resolveTableFrom(semantics, step.input, kwarg));
+        if (semantic.rows === "remove") deletes.push(resolveTableFrom(semantics, step.input, kwarg));
         continue;
       }
       if (!("writes" in semantic) || !semantic.writes) continue;
@@ -78268,45 +78318,6 @@ async function assertFilterTraversalsResolve(loadTable, filter2, fields, subject
   }
 }
 
-// ../shared/src/interpolate.ts
-init_define_LOTICS_KIT_VERSIONS();
-function interpolateObject(obj, context) {
-  if (obj === null || obj === void 0) {
-    return obj;
-  }
-  if (typeof obj === "string") {
-    const expressionMatches = obj.match(/\{\{.*?\}\}/g);
-    if (expressionMatches && expressionMatches.length > 0) {
-      if (expressionMatches.length === 1 && obj === expressionMatches[0]) {
-        const expression = obj.slice(2, -2).trim();
-        return evaluateJsExpression(expression, context);
-      }
-      const parts = obj.split(/(\{\{.*?\}\})/g);
-      const evaluatedParts = parts.map((part) => {
-        if (part.startsWith("{{") && part.endsWith("}}")) {
-          const expression = part.slice(2, -2).trim();
-          const result = evaluateJsExpression(expression, context);
-          return result != null ? String(result) : "";
-        }
-        return part;
-      });
-      return evaluatedParts.join("");
-    }
-    return obj;
-  }
-  if (Array.isArray(obj)) {
-    return obj.map((item) => interpolateObject(item, context));
-  }
-  if (typeof obj === "object") {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = interpolateObject(value, context);
-    }
-    return result;
-  }
-  return obj;
-}
-
 // ../shared/src/app_query_gate.ts
 function refused(refusal) {
   return { ok: false, refusal };
@@ -81346,6 +81357,7 @@ function createSource(plan) {
   const opening = [
     `const made = await create_records({`,
     `  table_id: ${str(plan.table.id)},`,
+    `  ids: isNull(i.${RECORD_INPUT}) ? null : [i.${RECORD_INPUT}],`,
     `  records: [`,
     `    {`,
     ...cells.map((cell) => `      ${cell}`),
@@ -82456,7 +82468,7 @@ function fieldInput(ctx, bf, required2) {
   }
 }
 function createInputs(ctx, alias2, writes) {
-  const inputs = {};
+  const inputs = { [RECORD_INPUT]: { type: "text", required: false } };
   if (writes.parent !== void 0) {
     const via = fieldOf2(ctx, alias2, writes.parent);
     if (via.field.type !== "select_record_link") fail(`"${alias2}.${via.alias}" files a row under its record, so it must be a link`);
@@ -86705,6 +86717,7 @@ var READ_OPS = /* @__PURE__ */ new Set([
   "context",
   "query",
   "field_options",
+  "write_model",
   "members",
   "agentRuns",
   "agentRun.get",
@@ -86737,6 +86750,7 @@ function refusalMessage(refused2, by) {
 var SUPPORTED_OPS = /* @__PURE__ */ new Set([
   "query",
   "field_options",
+  "write_model",
   "workflow",
   "members",
   "context",
@@ -86792,6 +86806,8 @@ async function dispatchRpc(client, body, opts) {
       }
       return client.appFieldOptions(body.app_id, p.alias);
     }
+    case "write_model":
+      return client.appWriteModel(body.app_id);
     case "workflow": {
       const p = body.payload;
       if (!p || typeof p.alias !== "string") {
@@ -88233,7 +88249,7 @@ var PROBES = {
   partial_count: {
     law: "reviewing.md",
     section: "8o",
-    fix: "State the server's count of the set, never the rows a page loaded: count the read (`useCount`) and step or badge against that total."
+    fix: "State the server's count of the set, never the rows a page loaded: count the read (`useQuery`'s `total`) and step or badge against that total."
   },
   record_primary: {
     law: "hierarchy.md",
@@ -89242,6 +89258,8 @@ function modelAnswer(data) {
         return { members: [{ ...PREVIEW_MEMBER }] };
       case "field_options":
         return typeof alias2 === "string" ? { fields: data.field_options[alias2] ?? {}, units: data.field_units[alias2] ?? {} } : { fields: {}, units: {} };
+      case "write_model":
+        return { workflows: {}, queries: {}, tables: [] };
       case "query": {
         if (typeof alias2 !== "string") throw new Error("a query names its alias; this call named none");
         const params = stated2(payload, "params");

package/dist/src/client.d.ts

@@ -1426,6 +1426,12 @@ export declare class LoticsClient {
             }>;
         }>;
     }>;
+    /**
+     * What the app's writes will change — each bound workflow's record-write subset, each query's column
+     * sources, the fields they name. Mirrors GET /v1/apps/{app_id}/write_model; the dev server hands it to
+     * the app's SDK whole, so its parts stay opaque here.
+     */
+    appWriteModel(app_id: string): Promise<unknown>;
     /**
      * Execute a workflow by alias declared in package.json#lotics.workflows.
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.

package/dist/src/client.js

@@ -883,6 +883,14 @@ var LoticsClient = class {
   async appFieldOptions(app_id, alias) {
     return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/field-options`, { alias });
   }
+  /**
+   * What the app's writes will change — each bound workflow's record-write subset, each query's column
+   * sources, the fields they name. Mirrors GET /v1/apps/{app_id}/write_model; the dev server hands it to
+   * the app's SDK whole, so its parts stay opaque here.
+   */
+  async appWriteModel(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/write_model`);
+  }
   /**
    * Execute a workflow by alias declared in package.json#lotics.workflows.
    * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.

package/docs/cli_reference.md

@@ -81,7 +81,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app workflow check [alias...]` | Check the editable workflow bodies locally — **every alias you name**, or all of them when you name none; an alias that is not bound is refused BEFORE any body is checked, so a green ✓ never sits under an exit 1 — locally first, in the **server's own order** — parse, then type-check — then on the server. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias. All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there, and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. **Then every body the local passes found clean goes to the server**: `set_app_workflow` with `verify_only: true`, sent exactly what `set` sends (the manifest's `inputs`/`outputs`/`description` and the synced `expected_body_sha`), which runs every check a save runs — names, lint, structural validation, table reach, the published-API guard — and writes nothing. Its issues print in the same `<file>:<line>:<col> - <source>/<code>` form at the physical line; one tied to a step rather than a position prints against the file, naming the step; a refusal (a stale baseline, a draft, a break) prints as `server/<code>`. All of them exit 1. A server it cannot reach — no credentials, the network, a server that predates `verify_only` — is a warning naming each alias and why, and the exit is then the local verdict's, so a green run says which of the two it is. A bound alias with no body file yet warns + skips; a body with no globals errors (naming `lotics app codegen`, which refreshes types WITHOUT touching the body — a pull would overwrite it). **It also keeps the types honest.** Each alias's `.lotics/workflows/<alias>.globals.d.ts` carries a `// lotics:declaration <hash>` stamp of the manifest declaration it was rendered from; `check` compares it to `package.json#lotics.workflows.<alias>` and, when they differ, re-renders that alias's dts from the LOCAL declaration before compiling. Without it the verdict was confidently wrong in the exact case an author needs it — declare an input, run `check`, and get `TS2339: Property 'x' does not exist` pointing at your body for a schema the types have never been told about. The server renders a dts from a SUPPLIED declaration, so this works before the manifest has ever been deployed, which is when it matters (the order is edit → check → set). That refresh is skipped when the stamps match, and with no credentials or a failed fetch it WARNS and checks against the older types rather than blocking. A file written before the stamp existed reads as unknown, never as matching, so a pre-existing checkout heals on its first run. |
 | `lotics app subdomain <new-subdomain>` | Rename the app's public address under the instance's apps domain 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>" [--description <d>] [--icon <lucide-name>] [--theme <color>]` | **The app's display metadata, live and on disk, in one verb** — via the `update_app` tool (the single setter for name/description/icon/theme). app_id comes from the local `package.json` manifest; the public address (`subdomain`) and the code (`deploy`) are unchanged. **It also writes `package.json#name`**, folded from the new display name by the scaffold's own rule (`starter_template.ts` — diacritics are FOLDED, never dropped, so `Điều xe` is `dieu-xe` and not `i-u`). Nothing else folds it, so a rename that skipped it left every `npm` line, every CI log and every reader of the project calling the app by its old name. Written only after the server took the rename, and surgically: no other manifest key moves. The three flags set the branding `app check` warns about — a missing icon or colour draws a generic tile, a missing description gives the app's chat agent a roster of aliases and no brief — through the same call, so setting them is never a second `lotics run update_app` that forgets the manifest write. `--theme` takes the COLOUR (`theme.color` is the whole of what the launcher reads), not a JSON object. A flag you omit changes nothing: `update_app` merges, and absent means unchanged. CLEARING one is still `lotics run update_app` with an explicit `null` — a CLI flag has no spelling for that a shell cannot produce by accident. |
-| `lotics app dev [path] [--port <n>] [--vite-port <n>] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. **Refused in one sentence on a project with no `vite.config.*`** — an app created with `--api` serves no bundle, and without the config Vite fails on a missing entry document in a bundler's words about a file the author never expected to have. `app check --screens` is refused on the same project for the same reason, rather than reporting "nothing blocking" for a pass it never ran; plain `app check` runs everything else. **`--port` is the wrapper you open and `--vite-port` is the module server, each as `--port <n>` or `--port=<n>`; pin both to run several apps at once.** A value that is not a port number is refused. With no `--vite-port`, `vite.config`'s own `server.port` is used when it states a literal one — the CLI passes `--port … --strictPort` to Vite, and a CLI flag beats the config in Vite's precedence, so the config's value could otherwise never win. `--vite-port` still outranks it and says so. **The wrapper serves every path that is not one of its own `/_…` routes**, so `http://localhost:PORT/lo/rec_…` opens that screen directly; `?_loc=<url-encoded path>` still works and wins. With `LOTICS_UI_SRC` set, Vite is started with `--force`: its optimizer cache survives a restart, so a NEW file added to the linked kit tree otherwise left the browser running the previous build of the module that imported it, silently. 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>`** 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>`** (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-runtime/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 app'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. **Every forwarded op logs one line naming its ALIAS** — `[rpc] query applicants 231ms` — and `query applicants (count)` for a count request, which is a SECOND full execution of the same query rather than a cheap lookup. When requests overlap the line carries `· N in flight`. That number is the one to watch: the server bounds how many app queries run at once, so requests past the bound wait and the wait lands inside each request's own duration — a burst reads as "every query got slower", which looks like a slow database and is not one. A screen firing its list plus three facet counts on one keystroke shows up here as eight lines over one or two aliases; see `@lotics/app-runtime` `docs/data_fetching.md` (`useCount`, and handing `usePaginatedQuery` a `total`) and `docs/queries.md` §10 for collapsing them. **Holds no realtime connection** — push belongs to the product frontend, so an app previewed here never updates on an external write (a CLI run, another tab, an agent): reload to see it. Deliberate rather than missing, since the alternative is a second implementation of the channel in the wrapper page, and a blanket poll here would hide an app whose queries do not declare their tables — the one mistake the real host punishes. The startup banner says `realtime: off` so this is visible without reading this table. The scaffold's `vite.config.ts` states `optimizeDeps: loticsOptimizeDeps()` — every published kit subpath, DERIVED from the kit's own `exports` rather than copied, and empty under `LOTICS_UI_SRC`. Vite's scanner reaches a subpath the moment something imports it, and meeting one mid-session re-optimizes, reloads, and inside this sandboxed iframe leaves two Reacts ("Invalid hook call") until a cold restart. `dev` and `codegen` heal that line, and the `server.fs.allow` one beside it, into a config scaffolded before them. 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 app dev [path] [--port <n>] [--vite-port <n>] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. **Refused in one sentence on a project with no `vite.config.*`** — an app created with `--api` serves no bundle, and without the config Vite fails on a missing entry document in a bundler's words about a file the author never expected to have. `app check --screens` is refused on the same project for the same reason, rather than reporting "nothing blocking" for a pass it never ran; plain `app check` runs everything else. **`--port` is the wrapper you open and `--vite-port` is the module server, each as `--port <n>` or `--port=<n>`; pin both to run several apps at once.** A value that is not a port number is refused. With no `--vite-port`, `vite.config`'s own `server.port` is used when it states a literal one — the CLI passes `--port … --strictPort` to Vite, and a CLI flag beats the config in Vite's precedence, so the config's value could otherwise never win. `--vite-port` still outranks it and says so. **The wrapper serves every path that is not one of its own `/_…` routes**, so `http://localhost:PORT/lo/rec_…` opens that screen directly; `?_loc=<url-encoded path>` still works and wins. With `LOTICS_UI_SRC` set, Vite is started with `--force`: its optimizer cache survives a restart, so a NEW file added to the linked kit tree otherwise left the browser running the previous build of the module that imported it, silently. 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>`** 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>`** (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-runtime/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 app'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. **Every forwarded op logs one line naming its ALIAS** — `[rpc] query applicants 231ms` — and `query applicants (count)` for a count request, which is a SECOND full execution of the same query rather than a cheap lookup. When requests overlap the line carries `· N in flight`. That number is the one to watch: the server bounds how many app queries run at once, so requests past the bound wait and the wait lands inside each request's own duration — a burst reads as "every query got slower", which looks like a slow database and is not one. A screen firing its list plus three facet counts on one keystroke shows up here as eight lines over one or two aliases; see `@lotics/app-runtime` `docs/data_fetching.md` (`total`, and `useQueries` for several counts at once) and `docs/queries.md` §10 for collapsing them. **Holds no realtime connection** — push belongs to the product frontend, so an app previewed here never updates on an external write (a CLI run, another tab, an agent): reload to see it. Deliberate rather than missing, since the alternative is a second implementation of the channel in the wrapper page, and a blanket poll here would hide an app whose queries do not declare their tables — the one mistake the real host punishes. The startup banner says `realtime: off` so this is visible without reading this table. The scaffold's `vite.config.ts` states `optimizeDeps: loticsOptimizeDeps()` — every published kit subpath, DERIVED from the kit's own `exports` rather than copied, and empty under `LOTICS_UI_SRC`. Vite's scanner reaches a subpath the moment something imports it, and meeting one mid-session re-optimizes, reloads, and inside this sandboxed iframe leaves two Reacts ("Invalid hook call") until a cold restart. `dev` and `codegen` heal that line, and the `server.fs.allow` one beside it, into a config scaffolded before them. 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`:** under the dev-link a kit file sits OUTSIDE the app's `node_modules` and resolves its OWN `react` 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. **The one hand-written file edited is `vite.config.ts`**, by `dev` and `codegen`, and only for the two blocks that are CALLS into `@lotics/ui/vite` (`optimizeDeps: loticsOptimizeDeps()`, `loticsFsAllow()` in `server.fs.allow`), spliced at the scaffold's own anchors in a config that already imports the subpath; a key the author answers themselves is left as typed and named back instead. Everything else generated lives in `.lotics/` (the CLI's own dir). 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 file preview <file\|fil_id> [-o out.png]` | (also `lotics preview`) A PDF is refused and the refusal names the route: `lotics file download <fil_id>`, then `pdftoppm -png -r 150` (poppler-utils) for one PNG per page — "open it" is an instruction for a person at a screen, and the caller here is usually an agent. A `.html` renders as the page it is — served from its own directory so what it refers to beside it resolves, read once its images have loaded, captured at its content size — which is how a demo's paper props (an official letter, a stamped minute, a supplier's bill) are looked at before they go into an `html` template. Otherwise 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** (a bare id, no extension): an id is first downloaded to a temp dir (the same presign path 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. Drives a headless Chrome over **CDP with only Node built-ins** — zero npm deps, the CLI stays a single bundled binary. The browser render logic is a separate browser bundle shipped at `dist/render_page.js`, 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.260.1",
+  "version": "0.261.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {