@lotics/cli 0.104.0 → 0.105.0

package/README.md

@@ -197,7 +197,7 @@ lotics knowledge rm kdc_...                                   # archive
 ```bash
 # Scaffold / pull / deploy a Vite+React+TS app project
 lotics app create "Sales Desk"            # scaffold + deploy v1
-lotics app pull app_...                    # bootstrap an existing app locally
+lotics app pull app_...                    # bootstrap an existing app locally (incl. .lotics/*)
 lotics app deploy -m "Add quote drawer"    # build + upload a new version
 lotics app versions                        # deploy history: version, when, who, -m message (* = live)
 lotics app versions app_...                # ...for any app, without pulling it first
@@ -205,6 +205,8 @@ lotics app versions app_...                # ...for any app, without pulling it
 # Regenerate .lotics/* WITHOUT a deploy: the .d.ts type companions (always) +
 # the runtime app_fields.ts (when authenticated) — F/OPT maps that address
 # fields + select options by stable display-name aliases instead of opaque ids.
+# `app pull` writes both too (a deploy archive can never carry app_fields.ts);
+# use this after a rename, or when a pull ran offline.
 lotics app codegen                         # import { F, OPT } from "../.lotics/app_fields"
 
 # Execute a bound app workflow end-to-end (inputs: inline / @file / stdin)

package/dist/src/cli.js

@@ -35953,7 +35953,7 @@ var require_stream_readable = __commonJS({
         increasedAwaitDrain = false;
         var ret = dest.write(chunk);
         if (false === ret && !increasedAwaitDrain) {
-          if ((state.pipesCount === 1 && state.pipes === dest || state.pipesCount > 1 && indexOf2(state.pipes, dest) !== -1) && !cleanedUp) {
+          if ((state.pipesCount === 1 && state.pipes === dest || state.pipesCount > 1 && indexOf3(state.pipes, dest) !== -1) && !cleanedUp) {
             debug("false write response, pause", state.awaitDrain);
             state.awaitDrain++;
             increasedAwaitDrain = true;
@@ -36025,7 +36025,7 @@ var require_stream_readable = __commonJS({
         }
         return this;
       }
-      var index = indexOf2(state.pipes, dest);
+      var index = indexOf3(state.pipes, dest);
       if (index === -1) return this;
       state.pipes.splice(index, 1);
       state.pipesCount -= 1;
@@ -36246,7 +36246,7 @@ var require_stream_readable = __commonJS({
         stream.emit("end");
       }
     }
-    function indexOf2(xs, x2) {
+    function indexOf3(xs, x2) {
       for (var i2 = 0, l = xs.length; i2 < l; i2++) {
         if (xs[i2] === x2) return i2;
       }
@@ -47367,7 +47367,7 @@ function walk(node, visit) {
 }
 
 // src/generate_app_fields.ts
-var HEADER = `// Auto-generated by 'lotics app codegen' (and app pull/dev/deploy).
+var HEADER = `// Auto-generated by 'lotics app codegen' and 'lotics app pull'.
 // DO NOT EDIT \u2014 regenerated from the workspace schema.
 //
 // Runtime field + option ids addressed by stable display-name aliases:
@@ -47486,7 +47486,7 @@ export type AppOptions = typeof OPT;
 }
 
 // src/generate_package_fields.ts
-var HEADER2 = `// Auto-generated by 'lotics app codegen' (linked/published app; also app pull/dev/deploy).
+var HEADER2 = `// Auto-generated by 'lotics app codegen' and 'lotics app pull' (linked/published app).
 // DO NOT EDIT \u2014 regenerated from the installation's live binding.
 //
 // A package installation resolves F/OPT/ROLE at MODULE LOAD from its binding
@@ -70527,6 +70527,43 @@ function writeBindingAppFields(projectDir, binding) {
   ensureAppVitestSetup(projectDir);
   return file2;
 }
+async function writeGeneratedAppFields(client, projectDir, app, queries) {
+  if (client.viewAsMemberId) {
+    console.error(
+      `\u26A0 Skipped .lotics/app_fields.ts \u2014 running with --view-as ${client.viewAsMemberId}. The schema is read as that member, so any table they cannot see would be silently missing from F/OPT. Re-run without --view-as to regenerate it.`
+    );
+    return;
+  }
+  try {
+    if (app.package_id) {
+      const binding = await client.appBinding(app.app_id);
+      const fieldsPath = writeBindingAppFields(projectDir, binding);
+      const count = Object.keys(binding.fields).length;
+      console.error(
+        `Wrote ${fieldsPath} (binding form \u2014 linked to package ${app.package_id}; ${count} field alias${count === 1 ? "" : "es"} resolved per-install)`
+      );
+    } else {
+      const tableIds = resolveCodegenTableIds(projectDir, queries);
+      const tables = await client.getWorkspaceSchema(tableIds);
+      const fieldsPath = writeAppFields(projectDir, tables);
+      console.error(
+        `Wrote ${fieldsPath} (baked form \u2014 bespoke; ${tables.length} table${tables.length === 1 ? "" : "s"})`
+      );
+    }
+  } catch (err2) {
+    warnAppFieldsUnwritten(projectDir, err2);
+  }
+}
+function warnAppFieldsUnwritten(projectDir, err2) {
+  const reason = err2 instanceof Error ? err2.message : String(err2);
+  if (fs4.existsSync(path5.join(projectDir, ".lotics", "app_fields.ts"))) {
+    console.error(`\u26A0 Could not regenerate .lotics/app_fields.ts (${reason}). Kept the existing file.`);
+    return;
+  }
+  console.error(
+    `\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;
@@ -70596,23 +70633,14 @@ async function appCodegen(args) {
   }
   try {
     const app = await args.client.getApp(meta3.app_id);
-    if (app.package_id) {
-      const binding = await args.client.appBinding(meta3.app_id);
-      const fieldsPath = writeBindingAppFields(projectDir, binding);
-      const count = Object.keys(binding.fields).length;
-      console.error(
-        `Regenerated ${fieldsPath} (binding form \u2014 ${count} field alias${count === 1 ? "" : "es"} resolved per-install)`
-      );
-    } else {
-      const tableIds = resolveCodegenTableIds(projectDir, meta3.queries ?? {});
-      const tables = await args.client.getWorkspaceSchema(tableIds);
-      const fieldsPath = writeAppFields(projectDir, tables);
-      console.error(`Regenerated ${fieldsPath} (${tables.length} table${tables.length === 1 ? "" : "s"})`);
-    }
-  } catch (err2) {
-    console.error(
-      `\u26A0 Could not regenerate .lotics/app_fields.ts (${err2 instanceof Error ? err2.message : String(err2)}). Kept the existing file.`
+    await writeGeneratedAppFields(
+      args.client,
+      projectDir,
+      { app_id: meta3.app_id, package_id: app.package_id },
+      meta3.queries ?? {}
     );
+  } catch (err2) {
+    warnAppFieldsUnwritten(projectDir, err2);
   }
   await refreshWorkflowGlobals(args.client, projectDir, meta3.app_id, meta3.workflows ?? {});
 }
@@ -70805,6 +70833,12 @@ async function appPull(client, args) {
     queries: app.queries ?? {},
     agents: app.agents ?? {}
   });
+  await writeGeneratedAppFields(
+    client,
+    targetPath,
+    { app_id: app.id, package_id: app.package_id },
+    app.queries ?? {}
+  );
   const workflows = app.workflows ?? {};
   if (Object.keys(workflows).length > 0) {
     const written = await writeWorkflowFiles(client, targetPath, app.id, app.name, workflows);
@@ -89700,6 +89734,93 @@ function getAttr2(el, attr) {
   return attrs?.[`@_${attr}`];
 }
 
+// ../ooxml/src/schema_order.ts
+var PPR_ORDER = [
+  "w:pStyle",
+  "w:keepNext",
+  "w:keepLines",
+  "w:pageBreakBefore",
+  "w:framePr",
+  "w:widowControl",
+  "w:numPr",
+  "w:suppressLineNumbers",
+  "w:pBdr",
+  "w:shd",
+  "w:tabs",
+  "w:suppressAutoHyphens",
+  "w:kinsoku",
+  "w:wordWrap",
+  "w:overflowPunct",
+  "w:topLinePunct",
+  "w:autoSpaceDE",
+  "w:autoSpaceDN",
+  "w:bidi",
+  "w:adjustRightInd",
+  "w:snapToGrid",
+  "w:spacing",
+  "w:ind",
+  "w:contextualSpacing",
+  "w:mirrorIndents",
+  "w:suppressOverlap",
+  "w:jc",
+  "w:textDirection",
+  "w:textAlignment",
+  "w:textboxTightWrap",
+  "w:outlineLvl",
+  "w:divId",
+  "w:cnfStyle",
+  "w:rPr",
+  "w:sectPr",
+  "w:pPrChange"
+];
+var RPR_ORDER = [
+  "w:rStyle",
+  "w:rFonts",
+  "w:b",
+  "w:bCs",
+  "w:i",
+  "w:iCs",
+  "w:caps",
+  "w:smallCaps",
+  "w:strike",
+  "w:dstrike",
+  "w:outline",
+  "w:shadow",
+  "w:emboss",
+  "w:imprint",
+  "w:noProof",
+  "w:snapToGrid",
+  "w:vanish",
+  "w:webHidden",
+  "w:color",
+  "w:spacing",
+  "w:w",
+  "w:kern",
+  "w:position",
+  "w:sz",
+  "w:szCs",
+  "w:highlight",
+  "w:u",
+  "w:effect",
+  "w:bdr",
+  "w:shd",
+  "w:fitText",
+  "w:vertAlign",
+  "w:rtl",
+  "w:cs",
+  "w:em",
+  "w:lang",
+  "w:eastAsianLayout",
+  "w:specVanish",
+  "w:oMath",
+  "w:rPrChange"
+];
+function indexOf2(order) {
+  return new Map(order.map((tag, i2) => [tag, i2]));
+}
+var PPR_INDEX = indexOf2(PPR_ORDER);
+var RPR_INDEX = indexOf2(RPR_ORDER);
+
 // ../ooxml/src/formatting.ts
 var formattingSchema = external_exports.object({
   bold: external_exports.boolean().optional(),
@@ -90564,23 +90685,25 @@ var DOCUMENT_RELS_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
   <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
 </Relationships>`;
-var SECT_PR = {
-  "w:sectPr": [
-    { "w:pgSz": [], ":@": { "@_w:w": "12240", "@_w:h": "15840" } },
-    {
-      "w:pgMar": [],
-      ":@": {
-        "@_w:top": "1440",
-        "@_w:right": "1440",
-        "@_w:bottom": "1440",
-        "@_w:left": "1440",
-        "@_w:header": "720",
-        "@_w:footer": "720",
-        "@_w:gutter": "0"
+function buildDefaultSectPr() {
+  return {
+    "w:sectPr": [
+      { "w:pgSz": [], ":@": { "@_w:w": "12240", "@_w:h": "15840" } },
+      {
+        "w:pgMar": [],
+        ":@": {
+          "@_w:top": "1440",
+          "@_w:right": "1440",
+          "@_w:bottom": "1440",
+          "@_w:left": "1440",
+          "@_w:header": "720",
+          "@_w:footer": "720",
+          "@_w:gutter": "0"
+        }
       }
-    }
-  ]
-};
+    ]
+  };
+}
 var DEFAULT_HEADING_SIZES = [32, 26, 24, 22, 20, 18];
 function escapeXmlAttr(value) {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -90676,7 +90799,7 @@ function createBlankDocx(opts) {
     default_font: opts?.default_font,
     default_font_size: opts?.default_font_size
   }));
-  const bodyElements = [{ ...SECT_PR }];
+  const bodyElements = [buildDefaultSectPr()];
   const documentAttrs = { ...DOCUMENT_ATTRS };
   if (opts?.page) setPageLayout(bodyElements, opts.page);
   return { zip, bodyElements, documentAttrs };

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. 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_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 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). |

package/package.json

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