@lotics/cli 0.102.0 → 0.104.0

package/README.md

@@ -239,9 +239,10 @@ lotics app agent run app_abc recognize --json                  # full run summar
 lotics app agent run app_abc recognize --session cli-123 '{}'  # continue an existing thread
 
 # Dev-link @lotics/ui to packages/ui/src for live HMR (Vite alias; deploy bundles it)
-lotics ui link card                        # monorepo: packages/ui/src found automatically
-lotics ui link card --ui-src /abs/monorepo/packages/ui/src   # external app (e.g. ~/lotics_apps)
-lotics ui link card --remove               # finalize: PR + publish, then drop the alias
+# Dev-link @lotics/ui to a monorepo checkout for ONE command — nothing is written to disk
+LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app dev
+LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app deploy -m "..."   # warns: bundles YOUR kit copy
+lotics app dev                             # unset ⇒ @lotics/ui resolves from node_modules again
 ```
 
 `app codegen` reads `package.json#lotics.queries` to decide which tables to put in `app_fields.ts`; widen the set with `package.json#lotics.codegen.tables` (an array of `tbl_…` ids) for tables the app only writes via workflows.

package/dist/render_page.js

@@ -25066,6 +25066,7 @@ ${e.toString()}`);
       this._byDepthAndTag = /* @__PURE__ */ new Map();
       this._wildcardByDepth = /* @__PURE__ */ new Map();
       this._deepWildcards = [];
+      this._deepByTerminalTag = /* @__PURE__ */ new Map();
       this._patterns = /* @__PURE__ */ new Set();
       this._sealed = false;
     }
@@ -25090,7 +25091,14 @@ ${e.toString()}`);
       if (this._patterns.has(expression.pattern)) return this;
       this._patterns.add(expression.pattern);
       if (expression.hasDeepWildcard()) {
-        this._deepWildcards.push(expression);
+        const lastSeg2 = expression.segments[expression.segments.length - 1];
+        if (lastSeg2 && lastSeg2.type !== "deep-wildcard" && lastSeg2.tag !== "*") {
+          const tag2 = lastSeg2.tag;
+          if (!this._deepByTerminalTag.has(tag2)) this._deepByTerminalTag.set(tag2, []);
+          this._deepByTerminalTag.get(tag2).push(expression);
+        } else {
+          this._deepWildcards.push(expression);
+        }
         return this;
       }
       const depth = expression.length;
@@ -25208,6 +25216,12 @@ ${e.toString()}`);
           if (matcher.matches(wildcardBucket[i3])) return wildcardBucket[i3];
         }
       }
+      const deepBucket = this._deepByTerminalTag.get(tag);
+      if (deepBucket) {
+        for (let i3 = 0; i3 < deepBucket.length; i3++) {
+          if (matcher.matches(deepBucket[i3])) return deepBucket[i3];
+        }
+      }
       for (let i3 = 0; i3 < this._deepWildcards.length; i3++) {
         if (matcher.matches(this._deepWildcards[i3])) return this._deepWildcards[i3];
       }
@@ -25267,6 +25281,24 @@ ${e.toString()}`);
       const current = path[path.length - 1];
       return current.values !== void 0 && attrName in current.values;
     }
+    /**
+     * Get the value of a "kept" attribute from the nearest ancestor (or
+     * current node) that declared it via `push(tag, attrs, ns, { keep: [...] })`.
+     * @param {string} attrName
+     * @returns {*}
+     */
+    getAnyParentAttr(attrName) {
+      return this._matcher.getAnyParentAttr(attrName);
+    }
+    /**
+     * Check whether any ancestor (or the current node) kept the given
+     * attribute via `push(tag, attrs, ns, { keep: [...] })`.
+     * @param {string} attrName
+     * @returns {boolean}
+     */
+    hasAnyParentAttr(attrName) {
+      return this._matcher.hasAnyParentAttr(attrName);
+    }
     /**
      * Get current node's sibling position (child index in parent).
      * @returns {number}
@@ -25345,30 +25377,32 @@ ${e.toString()}`);
       this.siblingStacks = [];
       this._pathStringCache = null;
       this._view = new MatcherView(this);
+      this._keptAttrs = [];
     }
     /**
      * Push a new tag onto the path.
      * @param {string} tagName
      * @param {Object|null} [attrValues=null]
      * @param {string|null} [namespace=null]
+     * @param {Object|null} [options=null]
+     * @param {string[]} [options.keep] - Names of attributes (from attrValues)
      */
-    push(tagName, attrValues = null, namespace = null) {
+    push(tagName, attrValues = null, namespace = null, options = null) {
       this._pathStringCache = null;
       if (this.path.length > 0) {
         this.path[this.path.length - 1].values = void 0;
       }
       const currentLevel = this.path.length;
-      if (!this.siblingStacks[currentLevel]) {
-        this.siblingStacks[currentLevel] = /* @__PURE__ */ new Map();
+      let level2 = this.siblingStacks[currentLevel];
+      if (!level2) {
+        level2 = { counts: /* @__PURE__ */ new Map(), total: 0 };
+        this.siblingStacks[currentLevel] = level2;
       }
-      const siblings = this.siblingStacks[currentLevel];
       const siblingKey = namespace ? `${namespace}:${tagName}` : tagName;
-      const counter = siblings.get(siblingKey) || 0;
-      let position = 0;
-      for (const count of siblings.values()) {
-        position += count;
-      }
-      siblings.set(siblingKey, counter + 1);
+      const counter = level2.counts.get(siblingKey) || 0;
+      const position = level2.total;
+      level2.counts.set(siblingKey, counter + 1);
+      level2.total++;
       const node = {
         tag: tagName,
         position,
@@ -25381,6 +25415,16 @@ ${e.toString()}`);
         node.values = attrValues;
       }
       this.path.push(node);
+      const depth = this.path.length;
+      const keep = options !== null ? options.keep : null;
+      if (keep !== null && keep !== void 0 && keep.length > 0 && attrValues) {
+        for (let i3 = 0; i3 < keep.length; i3++) {
+          const name = keep[i3];
+          if (attrValues[name] !== void 0) {
+            this._keptAttrs.push({ depth, name, value: attrValues[name] });
+          }
+        }
+      }
     }
     /**
      * Pop the last tag from the path.
@@ -25393,6 +25437,10 @@ ${e.toString()}`);
       if (this.siblingStacks.length > this.path.length + 1) {
         this.siblingStacks.length = this.path.length + 1;
       }
+      const poppedDepth = this.path.length + 1;
+      while (this._keptAttrs.length > 0 && this._keptAttrs[this._keptAttrs.length - 1].depth >= poppedDepth) {
+        this._keptAttrs.pop();
+      }
       return node;
     }
     /**
@@ -25441,6 +25489,36 @@ ${e.toString()}`);
       const current = this.path[this.path.length - 1];
       return current.values !== void 0 && attrName in current.values;
     }
+    /**
+     * Get the value of a "kept" attribute from the nearest ancestor (or
+     * current node) that declared it via `push(tag, attrs, ns, { keep: [...] })`.
+     * Unlike getAttrValue(), this works regardless of how deep the path has
+     * gone since the attribute was pushed — but only for attribute names that
+     * were explicitly marked with `keep` at push time. Cost is proportional to
+     * the number of currently-kept attributes (typically 0-3), not path depth.
+     * @param {string} attrName
+     * @returns {*} the value, or undefined if no ancestor kept this attribute
+     */
+    getAnyParentAttr(attrName) {
+      const kept = this._keptAttrs;
+      for (let i3 = kept.length - 1; i3 >= 0; i3--) {
+        if (kept[i3].name === attrName) return kept[i3].value;
+      }
+      return void 0;
+    }
+    /**
+     * Check whether any ancestor (or the current node) kept the given
+     * attribute via `push(tag, attrs, ns, { keep: [...] })`.
+     * @param {string} attrName
+     * @returns {boolean}
+     */
+    hasAnyParentAttr(attrName) {
+      const kept = this._keptAttrs;
+      for (let i3 = kept.length - 1; i3 >= 0; i3--) {
+        if (kept[i3].name === attrName) return true;
+      }
+      return false;
+    }
     /**
      * Get current node's sibling position (child index in parent).
      * @returns {number}
@@ -25509,6 +25587,7 @@ ${e.toString()}`);
       this._pathStringCache = null;
       this.path = [];
       this.siblingStacks = [];
+      this._keptAttrs = [];
     }
     /**
      * Match current path against an Expression.
@@ -25632,7 +25711,8 @@ ${e.toString()}`);
     snapshot() {
       return {
         path: this.path.map((node) => ({ ...node })),
-        siblingStacks: this.siblingStacks.map((map3) => new Map(map3))
+        siblingStacks: this.siblingStacks.map((level2) => level2 ? { counts: new Map(level2.counts), total: level2.total } : level2),
+        keptAttrs: this._keptAttrs.map((entry) => ({ ...entry }))
       };
     }
     /**
@@ -25642,7 +25722,8 @@ ${e.toString()}`);
     restore(snapshot) {
       this._pathStringCache = null;
       this.path = snapshot.path.map((node) => ({ ...node }));
-      this.siblingStacks = snapshot.siblingStacks.map((map3) => new Map(map3));
+      this.siblingStacks = snapshot.siblingStacks.map((level2) => level2 ? { counts: new Map(level2.counts), total: level2.total } : level2);
+      this._keptAttrs = (snapshot.keptAttrs || []).map((entry) => ({ ...entry }));
     }
     /**
      * Return the read-only {@link MatcherView} for this matcher.

package/dist/src/cli.js

@@ -45532,7 +45532,23 @@ export default defineConfig({
   // is safe. Define both so dev and the deployed build behave identically.
   define: { __DEV__: "false", global: "globalThis" },
   resolve: {
-    alias: [{ find: "react-native", replacement: "react-native-web" }],
+    // \`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
@@ -70201,8 +70217,27 @@ export {};
 function workflowFilePath(projectDir, alias) {
   return path5.join(projectDir, WORKFLOWS_DIR, `${alias}.ts`);
 }
+var GLOBALS_SUFFIX = ".globals.d.ts";
 function workflowGlobalsPath(projectDir, alias) {
-  return path5.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`);
+  return path5.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}${GLOBALS_SUFFIX}`);
+}
+function pruneOrphanWorkflowGlobals(projectDir, declared) {
+  const dir = path5.join(projectDir, WORKFLOW_GLOBALS_DIR);
+  if (!fs4.existsSync(dir)) return [];
+  const removed = [];
+  for (const entry of fs4.readdirSync(dir)) {
+    if (!entry.endsWith(GLOBALS_SUFFIX)) continue;
+    const alias = entry.slice(0, -GLOBALS_SUFFIX.length);
+    if (declared.has(alias)) continue;
+    fs4.unlinkSync(path5.join(dir, entry));
+    removed.push(alias);
+  }
+  return removed.sort();
+}
+function orphanWorkflowBodies(projectDir, declared) {
+  const dir = path5.join(projectDir, WORKFLOWS_DIR);
+  if (!fs4.existsSync(dir)) return [];
+  return fs4.readdirSync(dir).filter((e) => e.endsWith(".ts") && !e.endsWith(".d.ts") && !e.endsWith(".test.ts")).map((e) => e.slice(0, -".ts".length)).filter((alias) => !declared.has(alias)).sort();
 }
 function writeWorkflowGlobals(projectDir, alias, dts) {
   const dir = path5.join(projectDir, WORKFLOW_GLOBALS_DIR);
@@ -70492,6 +70527,29 @@ function writeBindingAppFields(projectDir, binding) {
   ensureAppVitestSetup(projectDir);
   return file2;
 }
+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) {
+  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\` }]
+      : []),`
+  );
+}
 function ensureAppVitestSetup(projectDir) {
   const setupPath = path5.join(projectDir, VITEST_SETUP_FILENAME);
   if (!fs4.existsSync(setupPath)) {
@@ -70521,6 +70579,15 @@ async function appCodegen(args) {
     agents: meta3.agents
   });
   for (const p of dtsPaths) console.error(`Regenerated ${p}`);
+  const declared = new Set(Object.keys(meta3.workflows ?? {}));
+  for (const alias of pruneOrphanWorkflowGlobals(projectDir, declared)) {
+    console.error(`Removed stale workflow types for ${alias} \u2014 no longer in package.json#lotics.workflows`);
+  }
+  for (const alias of orphanWorkflowBodies(projectDir, declared)) {
+    console.error(
+      `\u26A0 ${path5.join(WORKFLOWS_DIR, `${alias}.ts`)} is not declared in package.json#lotics.workflows \u2014 'workflow check' and 'workflow set' both skip it. Declare the alias or delete the file.`
+    );
+  }
   if (!args.client) {
     console.error(
       "Skipped .lotics/app_fields.ts \u2014 no workspace credentials resolved. Run authenticated (or set LOTICS_API_KEY) to regenerate field/option ids."
@@ -70781,6 +70848,7 @@ function readAppSourceText(projectDir) {
 async function appDeploy(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
+  warnIfDeployingLinkedKit(projectDir);
   const sourceText = readAppSourceText(projectDir);
   const called = calledAppAliases(sourceText);
   if (called.dynamic.length > 0) {
@@ -70943,6 +71011,7 @@ function warnIfUnboundAliases(app, called) {
 async function appDev(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
+  warnIfDevLinkIgnored(projectDir);
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   const app = await client.getApp(meta3.app_id);
   const handle = await startDevServer({
@@ -71370,80 +71439,6 @@ All ${results.length} workflow bodies parse and type-check clean.`) + `
 ${totalErrors} error${totalErrors === 1 ? "" : "s"} across ${results.length - passed} of ${results.length} ${results.length === 1 ? "body" : "bodies"}.`
   );
 }
-function findUiSrcDir(start) {
-  let dir = path5.resolve(start);
-  for (; ; ) {
-    const candidate = path5.join(dir, "packages", "ui", "src");
-    if (fs4.existsSync(candidate) && fs4.statSync(candidate).isDirectory()) return candidate;
-    const parent = path5.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-var UI_ALIAS_FIND_SOURCE = String.raw`/^@lotics\/ui\/(.+)$/`;
-function appUiLink(args) {
-  const projectDir = path5.resolve(args.projectDir ?? process.cwd());
-  const viteConfigPath = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(viteConfigPath)) {
-    throw new Error(
-      `No vite.config.ts at ${projectDir}. Run inside a 'lotics app' project directory.`
-    );
-  }
-  const explicit = args.uiSrc ?? process.env.LOTICS_UI_SRC;
-  const uiSrc = explicit ? path5.resolve(explicit) : findUiSrcDir(projectDir);
-  if (!uiSrc || !fs4.existsSync(uiSrc) || !fs4.statSync(uiSrc).isDirectory()) {
-    throw new Error(
-      explicit ? `--ui-src / LOTICS_UI_SRC points at '${explicit}', which is not a directory. Pass the absolute path to the monorepo's packages/ui/src.` : "Cannot find packages/ui/src by walking up from this directory. For an EXTERNAL app (consuming @lotics/ui from npm), pass --ui-src=<abs path to packages/ui/src> or set LOTICS_UI_SRC; inside a monorepo checkout it is found automatically."
-    );
-  }
-  const hasComponent = fs4.existsSync(path5.join(uiSrc, `${args.component}.tsx`)) || fs4.existsSync(path5.join(uiSrc, `${args.component}.ts`)) || fs4.existsSync(path5.join(uiSrc, args.component));
-  if (!hasComponent) {
-    throw new Error(
-      `No '@lotics/ui/${args.component}' under ${uiSrc} (expected ${args.component}.tsx/.ts). Check the component name.`
-    );
-  }
-  const source = fs4.readFileSync(viteConfigPath, "utf-8");
-  const aliasEntry = `{ find: ${UI_ALIAS_FIND_SOURCE}, replacement: ${JSON.stringify(`${uiSrc}/$1`)} },`;
-  const alreadyLinked = source.includes(UI_ALIAS_FIND_SOURCE);
-  if (args.remove) {
-    if (!alreadyLinked) {
-      console.error("No @lotics/ui dev-link alias present \u2014 nothing to remove.");
-      return;
-    }
-    const stripped = source.replace(
-      new RegExp(
-        `\\n?[ \\t]*\\{ find: ${escapeRegExp(UI_ALIAS_FIND_SOURCE)}, ` + // The replacement is a JSON-encoded path, so it cannot contain an
-        // unescaped quote — bounded, rather than greedy to end of line.
-        String.raw`replacement: "(?:[^"\\]|\\.)*" \},`
-      ),
-      ""
-    );
-    fs4.writeFileSync(viteConfigPath, stripped);
-    console.error(`Removed the @lotics/ui dev-link alias from ${viteConfigPath}.`);
-    console.error("Restart `lotics app dev` and rm -rf node_modules/.vite to clear cached modules.");
-    return;
-  }
-  if (alreadyLinked) {
-    console.error(`@lotics/ui is already dev-linked in ${viteConfigPath}.`);
-    return;
-  }
-  const aliasMatch = /resolve\s*:\s*\{[\s\S]*?alias\s*:\s*\[/.exec(source);
-  if (!aliasMatch) {
-    throw new Error(
-      `Could not find a resolve.alias array literal in ${viteConfigPath}. Refresh vite.config.ts from the starter (packages/sdk/src/starter_template.ts) and retry.`
-    );
-  }
-  const insertAt = aliasMatch.index + aliasMatch[0].length;
-  const updated = `${source.slice(0, insertAt)}
-      ${aliasEntry}${source.slice(insertAt)}`;
-  fs4.writeFileSync(viteConfigPath, updated);
-  console.error(`Dev-linked @lotics/ui \u2192 ${uiSrc} in ${viteConfigPath}.`);
-  console.error("Restart `lotics app dev` and rm -rf node_modules/.vite to clear cached modules.");
-  console.error("Finalize: PR the packages/ui change \u2192 publish \u2192 `lotics ui link <component> --remove` + bump the app's dep.");
-}
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 
 // src/args.ts
 function parseArgs(argv) {
@@ -71455,7 +71450,6 @@ function parseArgs(argv) {
     apiKey: void 0,
     workspace: void 0,
     viewAs: void 0,
-    uiSrc: void 0,
     name: void 0,
     description: void 0,
     from: void 0,
@@ -71502,9 +71496,6 @@ function parseArgs(argv) {
       case "--view-as":
         flags.viewAs = argv[++i2];
         break;
-      case "--ui-src":
-        flags.uiSrc = argv[++i2];
-        break;
       case "--name":
         flags.name = argv[++i2];
         break;
@@ -74264,6 +74255,7 @@ var ExpressionSet = class {
     this._byDepthAndTag = /* @__PURE__ */ new Map();
     this._wildcardByDepth = /* @__PURE__ */ new Map();
     this._deepWildcards = [];
+    this._deepByTerminalTag = /* @__PURE__ */ new Map();
     this._patterns = /* @__PURE__ */ new Set();
     this._sealed = false;
   }
@@ -74288,7 +74280,14 @@ var ExpressionSet = class {
     if (this._patterns.has(expression.pattern)) return this;
     this._patterns.add(expression.pattern);
     if (expression.hasDeepWildcard()) {
-      this._deepWildcards.push(expression);
+      const lastSeg2 = expression.segments[expression.segments.length - 1];
+      if (lastSeg2 && lastSeg2.type !== "deep-wildcard" && lastSeg2.tag !== "*") {
+        const tag2 = lastSeg2.tag;
+        if (!this._deepByTerminalTag.has(tag2)) this._deepByTerminalTag.set(tag2, []);
+        this._deepByTerminalTag.get(tag2).push(expression);
+      } else {
+        this._deepWildcards.push(expression);
+      }
       return this;
     }
     const depth = expression.length;
@@ -74406,6 +74405,12 @@ var ExpressionSet = class {
         if (matcher.matches(wildcardBucket[i2])) return wildcardBucket[i2];
       }
     }
+    const deepBucket = this._deepByTerminalTag.get(tag);
+    if (deepBucket) {
+      for (let i2 = 0; i2 < deepBucket.length; i2++) {
+        if (matcher.matches(deepBucket[i2])) return deepBucket[i2];
+      }
+    }
     for (let i2 = 0; i2 < this._deepWildcards.length; i2++) {
       if (matcher.matches(this._deepWildcards[i2])) return this._deepWildcards[i2];
     }
@@ -74465,6 +74470,24 @@ var MatcherView = class {
     const current = path8[path8.length - 1];
     return current.values !== void 0 && attrName in current.values;
   }
+  /**
+   * Get the value of a "kept" attribute from the nearest ancestor (or
+   * current node) that declared it via `push(tag, attrs, ns, { keep: [...] })`.
+   * @param {string} attrName
+   * @returns {*}
+   */
+  getAnyParentAttr(attrName) {
+    return this._matcher.getAnyParentAttr(attrName);
+  }
+  /**
+   * Check whether any ancestor (or the current node) kept the given
+   * attribute via `push(tag, attrs, ns, { keep: [...] })`.
+   * @param {string} attrName
+   * @returns {boolean}
+   */
+  hasAnyParentAttr(attrName) {
+    return this._matcher.hasAnyParentAttr(attrName);
+  }
   /**
    * Get current node's sibling position (child index in parent).
    * @returns {number}
@@ -74543,30 +74566,32 @@ var Matcher = class {
     this.siblingStacks = [];
     this._pathStringCache = null;
     this._view = new MatcherView(this);
+    this._keptAttrs = [];
   }
   /**
    * Push a new tag onto the path.
    * @param {string} tagName
    * @param {Object|null} [attrValues=null]
    * @param {string|null} [namespace=null]
+   * @param {Object|null} [options=null]
+   * @param {string[]} [options.keep] - Names of attributes (from attrValues)
    */
-  push(tagName, attrValues = null, namespace = null) {
+  push(tagName, attrValues = null, namespace = null, options = null) {
     this._pathStringCache = null;
     if (this.path.length > 0) {
       this.path[this.path.length - 1].values = void 0;
     }
     const currentLevel = this.path.length;
-    if (!this.siblingStacks[currentLevel]) {
-      this.siblingStacks[currentLevel] = /* @__PURE__ */ new Map();
+    let level = this.siblingStacks[currentLevel];
+    if (!level) {
+      level = { counts: /* @__PURE__ */ new Map(), total: 0 };
+      this.siblingStacks[currentLevel] = level;
     }
-    const siblings = this.siblingStacks[currentLevel];
     const siblingKey = namespace ? `${namespace}:${tagName}` : tagName;
-    const counter = siblings.get(siblingKey) || 0;
-    let position = 0;
-    for (const count of siblings.values()) {
-      position += count;
-    }
-    siblings.set(siblingKey, counter + 1);
+    const counter = level.counts.get(siblingKey) || 0;
+    const position = level.total;
+    level.counts.set(siblingKey, counter + 1);
+    level.total++;
     const node = {
       tag: tagName,
       position,
@@ -74579,6 +74604,16 @@ var Matcher = class {
       node.values = attrValues;
     }
     this.path.push(node);
+    const depth = this.path.length;
+    const keep = options !== null ? options.keep : null;
+    if (keep !== null && keep !== void 0 && keep.length > 0 && attrValues) {
+      for (let i2 = 0; i2 < keep.length; i2++) {
+        const name = keep[i2];
+        if (attrValues[name] !== void 0) {
+          this._keptAttrs.push({ depth, name, value: attrValues[name] });
+        }
+      }
+    }
   }
   /**
    * Pop the last tag from the path.
@@ -74591,6 +74626,10 @@ var Matcher = class {
     if (this.siblingStacks.length > this.path.length + 1) {
       this.siblingStacks.length = this.path.length + 1;
     }
+    const poppedDepth = this.path.length + 1;
+    while (this._keptAttrs.length > 0 && this._keptAttrs[this._keptAttrs.length - 1].depth >= poppedDepth) {
+      this._keptAttrs.pop();
+    }
     return node;
   }
   /**
@@ -74639,6 +74678,36 @@ var Matcher = class {
     const current = this.path[this.path.length - 1];
     return current.values !== void 0 && attrName in current.values;
   }
+  /**
+   * Get the value of a "kept" attribute from the nearest ancestor (or
+   * current node) that declared it via `push(tag, attrs, ns, { keep: [...] })`.
+   * Unlike getAttrValue(), this works regardless of how deep the path has
+   * gone since the attribute was pushed — but only for attribute names that
+   * were explicitly marked with `keep` at push time. Cost is proportional to
+   * the number of currently-kept attributes (typically 0-3), not path depth.
+   * @param {string} attrName
+   * @returns {*} the value, or undefined if no ancestor kept this attribute
+   */
+  getAnyParentAttr(attrName) {
+    const kept = this._keptAttrs;
+    for (let i2 = kept.length - 1; i2 >= 0; i2--) {
+      if (kept[i2].name === attrName) return kept[i2].value;
+    }
+    return void 0;
+  }
+  /**
+   * Check whether any ancestor (or the current node) kept the given
+   * attribute via `push(tag, attrs, ns, { keep: [...] })`.
+   * @param {string} attrName
+   * @returns {boolean}
+   */
+  hasAnyParentAttr(attrName) {
+    const kept = this._keptAttrs;
+    for (let i2 = kept.length - 1; i2 >= 0; i2--) {
+      if (kept[i2].name === attrName) return true;
+    }
+    return false;
+  }
   /**
    * Get current node's sibling position (child index in parent).
    * @returns {number}
@@ -74707,6 +74776,7 @@ var Matcher = class {
     this._pathStringCache = null;
     this.path = [];
     this.siblingStacks = [];
+    this._keptAttrs = [];
   }
   /**
    * Match current path against an Expression.
@@ -74830,7 +74900,8 @@ var Matcher = class {
   snapshot() {
     return {
       path: this.path.map((node) => ({ ...node })),
-      siblingStacks: this.siblingStacks.map((map3) => new Map(map3))
+      siblingStacks: this.siblingStacks.map((level) => level ? { counts: new Map(level.counts), total: level.total } : level),
+      keptAttrs: this._keptAttrs.map((entry) => ({ ...entry }))
     };
   }
   /**
@@ -74840,7 +74911,8 @@ var Matcher = class {
   restore(snapshot) {
     this._pathStringCache = null;
     this.path = snapshot.path.map((node) => ({ ...node }));
-    this.siblingStacks = snapshot.siblingStacks.map((map3) => new Map(map3));
+    this.siblingStacks = snapshot.siblingStacks.map((level) => level ? { counts: new Map(level.counts), total: level.total } : level);
+    this._keptAttrs = (snapshot.keptAttrs || []).map((entry) => ({ ...entry }));
   }
   /**
    * Return the read-only {@link MatcherView} for this matcher.
@@ -89659,180 +89731,6 @@ var runSchema = external_exports.object({
   formatting: formattingSchema.optional()
 });
 
-// ../ooxml/src/queries.ts
-function getBodyElementType(el) {
-  const tag = getTagName(el);
-  if (tag === "w:p") return "paragraph";
-  if (tag === "w:tbl") return "table";
-  return "other";
-}
-function extractParagraphText(el) {
-  const tag = getTagName(el);
-  if (tag !== "w:p") return "";
-  const parts = [];
-  for (const child of getChildren(el)) {
-    const childTag = getTagName(child);
-    if (childTag === "w:r") {
-      for (const runChild of getChildren(child)) {
-        if (getTagName(runChild) === "w:t") {
-          parts.push(getTextContent(runChild));
-        }
-      }
-    } else if (childTag === "w:hyperlink") {
-      for (const hlChild of getChildren(child)) {
-        if (getTagName(hlChild) === "w:r") {
-          for (const runChild of getChildren(hlChild)) {
-            if (getTagName(runChild) === "w:t") {
-              parts.push(getTextContent(runChild));
-            }
-          }
-        }
-      }
-    }
-  }
-  return parts.join("");
-}
-function getParagraphTextSegments(el) {
-  const segments = [];
-  for (const child of getChildren(el)) {
-    if (getTagName(child) !== "w:r") continue;
-    let pending = [];
-    const flush = () => {
-      if (pending.length === 0) return;
-      const text = pending.map(
-        (node) => getChildren(node).reduce(
-          (acc, tn) => typeof tn["#text"] === "string" ? acc + tn["#text"] : acc,
-          ""
-        )
-      ).join("");
-      segments.push({ element: child, textNodes: pending, text });
-      pending = [];
-    };
-    for (const grandchild of getChildren(child)) {
-      if (getTagName(grandchild) === "w:t") {
-        pending.push(grandchild);
-        continue;
-      }
-      flush();
-    }
-    flush();
-  }
-  return segments;
-}
-function setSegmentText(segment, newText) {
-  const children = getChildren(segment.element);
-  const textNode = {
-    "w:t": [{ "#text": newText }],
-    ":@": { "@_xml:space": "preserve" }
-  };
-  const head = children.indexOf(segment.textNodes[0]);
-  children[head] = textNode;
-  for (let i2 = segment.textNodes.length - 1; i2 >= 1; i2--) {
-    const at2 = children.indexOf(segment.textNodes[i2]);
-    if (at2 >= 0) children.splice(at2, 1);
-  }
-  segment.textNodes = [textNode];
-  segment.text = newText;
-}
-function computeReplacementRanges(text, query, replacement, matchType, maxReplacements, startCount) {
-  const ranges = [];
-  let count = startCount;
-  if (matchType === "exact") {
-    if (text === query && count < maxReplacements) {
-      ranges.push({ start: 0, end: text.length, replacement });
-      count++;
-    }
-    return { ranges, count };
-  }
-  if (matchType === "regex") {
-    const re2 = new RegExp(query, "gi");
-    let match2;
-    while (count < maxReplacements && (match2 = re2.exec(text)) !== null) {
-      ranges.push({ start: match2.index, end: match2.index + match2[0].length, replacement });
-      count++;
-      if (match2[0].length === 0) re2.lastIndex++;
-    }
-    return { ranges, count };
-  }
-  if (query.length === 0) return { ranges, count };
-  const lower2 = text.toLowerCase();
-  const lowerQuery = query.toLowerCase();
-  let searchFrom = 0;
-  while (count < maxReplacements) {
-    const idx = lower2.indexOf(lowerQuery, searchFrom);
-    if (idx === -1) break;
-    ranges.push({ start: idx, end: idx + query.length, replacement });
-    searchFrom = idx + query.length;
-    count++;
-  }
-  return { ranges, count };
-}
-function applyRangeReplacements(segments, ranges) {
-  if (ranges.length === 0) return;
-  const bounds = [];
-  let offset = 0;
-  for (const segment of segments) {
-    bounds.push({ segment, start: offset, end: offset + segment.text.length });
-    offset += segment.text.length;
-  }
-  const joined = segments.map((s) => s.text).join("");
-  const sorted = [...ranges].sort((a, b) => a.start - b.start);
-  for (const { segment, start: segStart, end: segEnd } of bounds) {
-    let next = "";
-    let cursor = segStart;
-    for (const range2 of sorted) {
-      if (range2.end <= segStart || range2.start >= segEnd) continue;
-      const keepUntil = Math.min(range2.start, segEnd);
-      const from = Math.max(cursor, segStart);
-      if (keepUntil > from) next += joined.slice(from, keepUntil);
-      if (segStart <= range2.start && range2.start < segEnd) next += range2.replacement;
-      cursor = Math.max(cursor, range2.end);
-    }
-    const tail = Math.max(cursor, segStart);
-    if (segEnd > tail) next += joined.slice(tail, segEnd);
-    if (next !== segment.text) setSegmentText(segment, next);
-  }
-}
-function replaceInParagraph(el, query, replacement, matchType, maxReplacements, replacementsMade) {
-  if (!extractParagraphText(el)) return replacementsMade;
-  const segments = getParagraphTextSegments(el);
-  if (segments.length === 0) return replacementsMade;
-  const text = segments.length === 1 ? segments[0].text : segments.map((s) => s.text).join("");
-  const { ranges, count } = computeReplacementRanges(text, query, replacement, matchType, maxReplacements, replacementsMade);
-  applyRangeReplacements(segments, ranges);
-  return count;
-}
-function replaceText(bodyElements, query, replacement, matchType = "contains", maxReplacements = Infinity) {
-  if (matchType === "regex") {
-    try {
-      new RegExp(query);
-    } catch {
-      throw new Error(`Invalid regex pattern: ${query}`);
-    }
-  }
-  let replacementsMade = 0;
-  for (let i2 = 0; i2 < bodyElements.length && replacementsMade < maxReplacements; i2++) {
-    const el = bodyElements[i2];
-    const type = getBodyElementType(el);
-    if (type === "paragraph") {
-      replacementsMade = replaceInParagraph(el, query, replacement, matchType, maxReplacements, replacementsMade);
-    } else if (type === "table") {
-      for (const child of getChildren(el)) {
-        if (getTagName(child) !== "w:tr") continue;
-        for (const cell of getChildren(child)) {
-          if (getTagName(cell) !== "w:tc") continue;
-          for (const p of getChildren(cell)) {
-            if (getTagName(p) === "w:p" && replacementsMade < maxReplacements) {
-              replacementsMade = replaceInParagraph(p, query, replacement, matchType, maxReplacements, replacementsMade);
-            }
-          }
-        }
-      }
-    }
-  }
-  return replacementsMade;
-}
-
 // ../ooxml/src/sections.ts
 var PAGE_SIZES = {
   letter: { w: 12240, h: 15840 },
@@ -90885,6 +90783,9 @@ function parseBlock(el) {
   if (tag === "w:sectPr") return parseBodySectPr(el);
   return parseOpaqueBlock(el);
 }
+function parseBlockXml(el) {
+  return parseBlock(el);
+}
 function parseParagraph(el) {
   const properties = [];
   const content = [];
@@ -91102,11 +91003,11 @@ function serializeDocumentXml(doc) {
 function serializeBody(body) {
   const out = [];
   for (const block of body.children) {
-    out.push(serializeBlock(block));
+    out.push(serializeBlockXml(block));
   }
   return out;
 }
-function serializeBlock(block) {
+function serializeBlockXml(block) {
   switch (block.kind) {
     case "paragraph":
       return serializeParagraph(block);
@@ -91356,7 +91257,8 @@ async function docxReplaceText(filePath, rest) {
   const doc = await loadFile2(filePath);
   const { children, count } = replaceEverywhere(doc.body.children, search, replace2);
   if (count === 0) {
-    fail2(`No occurrence of ${JSON.stringify(search)} in ${filePath} \u2014 nothing written.`);
+    const why = explainNoMatch(doc.body.children, search);
+    fail2(`No occurrence of ${JSON.stringify(search)} in ${filePath} \u2014 nothing written.${why ? ` ${why}` : ""}`);
   }
   await writeDoc(filePath, replaceChildren(doc, children));
   console.error(`Wrote ${filePath} (${count} replacement${count === 1 ? "" : "s"})`);
@@ -91365,13 +91267,12 @@ function replaceEverywhere(blocks, search, replace2) {
   let count = 0;
   const children = blocks.map((b) => {
     if (b.kind === "paragraph") {
-      const [paragraph, n] = replaceInParagraph2(b, search, replace2);
+      const [paragraph, n] = replaceInParagraph(b, search, replace2);
       count += n;
       return paragraph;
     }
     if (b.kind === "opaque_block") {
-      const xml = structuredClone(b.xml);
-      const n = replaceText([xml], search, replace2, "contains");
+      const [xml, n] = replaceInOpaque(b.xml, search, replace2);
       if (n === 0) return b;
       count += n;
       return { kind: "opaque_block", xml };
@@ -91380,7 +91281,27 @@ function replaceEverywhere(blocks, search, replace2) {
   });
   return { children, count };
 }
-function replaceInParagraph2(p, search, replace2) {
+function replaceInOpaque(el, search, replace2) {
+  const tag = getTagName(el);
+  if (tag === void 0) return [el, 0];
+  if (tag === "w:p") {
+    const block = parseBlockXml(el);
+    if (block.kind !== "paragraph") return [el, 0];
+    const [paragraph, n] = replaceInParagraph(block, search, replace2);
+    return n === 0 ? [el, 0] : [serializeBlockXml(paragraph), n];
+  }
+  let count = 0;
+  const children = getChildren(el).map((child) => {
+    if (isTextNode(child)) return child;
+    const [next, n] = replaceInOpaque(child, search, replace2);
+    count += n;
+    return next;
+  });
+  if (count === 0) return [el, 0];
+  const attrs = el[":@"];
+  return [{ [tag]: children, ...attrs === void 0 ? {} : { ":@": attrs } }, count];
+}
+function replaceInParagraph(p, search, replace2) {
   if (search === "") return [p, 0];
   const rewritten = /* @__PURE__ */ new Map();
   let count = 0;
@@ -91419,6 +91340,71 @@ function replaceInParagraph2(p, search, replace2) {
   });
   return [{ kind: "paragraph", properties: p.properties, content }, count];
 }
+var ZERO_WIDTH_MARKS = /* @__PURE__ */ new Set([
+  "w:proofErr",
+  "w:footnoteReference",
+  "w:endnoteReference",
+  "w:commentReference",
+  "w:commentRangeStart",
+  "w:commentRangeEnd",
+  "w:annotationRef",
+  "w:bookmarkStart",
+  "w:bookmarkEnd",
+  "w:lastRenderedPageBreak"
+]);
+function interruptsText(node) {
+  const tag = getTagName(node.xml);
+  return tag === void 0 || !ZERO_WIDTH_MARKS.has(tag);
+}
+function paragraphText(p) {
+  let out = "";
+  for (const inline of p.content) {
+    if (inline.kind !== "run") continue;
+    for (const child of inline.content) if (child.kind === "text") out += child.value;
+  }
+  return out;
+}
+function interruptingTags(p) {
+  const tags = [];
+  for (const inline of p.content) {
+    if (inline.kind !== "run") {
+      if (interruptsText(inline)) tags.push(getTagName(inline.xml) ?? "?");
+      continue;
+    }
+    for (const child of inline.content) {
+      if (child.kind !== "text" && interruptsText(child)) tags.push(getTagName(child.xml) ?? "?");
+    }
+  }
+  return [...new Set(tags)];
+}
+function explainNoMatch(blocks, search) {
+  for (const { index, paragraph, nested } of everyParagraph(blocks)) {
+    if (!paragraphText(paragraph).includes(search)) continue;
+    const tags = interruptingTags(paragraph);
+    if (tags.length === 0) continue;
+    const where = nested ? `inside block ${index}` : `at block ${index}`;
+    return `The text IS present ${where}, split by ${tags.join(", ")} \u2014 replace-text will not join across those, because the joined string does not represent them. Search a shorter phrase that does not cross one.`;
+  }
+  return void 0;
+}
+function everyParagraph(blocks) {
+  const out = [];
+  const walk2 = (el, index) => {
+    const tag = getTagName(el);
+    if (tag === void 0) return;
+    if (tag === "w:p") {
+      const block = parseBlockXml(el);
+      if (block.kind === "paragraph") out.push({ index, paragraph: block, nested: true });
+      return;
+    }
+    for (const child of getChildren(el)) if (!isTextNode(child)) walk2(child, index);
+  };
+  for (const [index, block] of blocks.entries()) {
+    if (block.kind === "paragraph") out.push({ index, paragraph: block, nested: false });
+    else if (block.kind === "opaque_block") walk2(block.xml, index);
+  }
+  return out;
+}
 function collectTextSegments(p) {
   const segments = [];
   let current = [];
@@ -91430,12 +91416,12 @@ function collectTextSegments(p) {
   };
   p.content.forEach((inline, inlineIndex) => {
     if (inline.kind !== "run") {
-      breakSegment();
+      if (interruptsText(inline)) breakSegment();
       return;
     }
     inline.content.forEach((child, childIndex) => {
       if (child.kind !== "text") {
-        breakSegment();
+        if (interruptsText(child)) breakSegment();
         return;
       }
       current.push({
@@ -91494,7 +91480,10 @@ function applyBatchOp(doc, op, index) {
     }
     case "replace-text": {
       const { children, count } = replaceEverywhere(doc.body.children, op.search, op.replace);
-      if (count === 0) fail2(`[op ${index}] No occurrence of ${JSON.stringify(op.search)} \u2014 batch aborted.`);
+      if (count === 0) {
+        const why = explainNoMatch(doc.body.children, op.search);
+        fail2(`[op ${index}] No occurrence of ${JSON.stringify(op.search)} \u2014 batch aborted.${why ? ` ${why}` : ""}`);
+      }
       return replaceChildren(doc, children);
     }
     default: {
@@ -91520,7 +91509,13 @@ Uses Lotics' own OOXML engine; round-trips faithfully with the Lotics editor and
   lotics docx batch <file> '<json-array-of-ops>'           Apply many ops in one parse/serialize cycle
 
 Edit ops mutate the file atomically (temp file + rename). Structure inside opaque blocks (tables, custom XML) is
-preserved verbatim; replace-text rewrites the text within them.`);
+preserved verbatim; replace-text rewrites the text within them.
+
+replace-text matches across run boundaries (Word splits a run at every formatting change) and reads through marks
+that take no place in the sentence \u2014 spell-check markers, footnote/endnote/comment refs, bookmarks. It will NOT
+join across something that occupies space in the text (a line break, tab, symbol, drawing, or any other tag),
+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.`);
 }
 async function runDocxCommand(subcommand, toolArgs, restArgs) {
   switch (subcommand) {
@@ -91984,10 +91979,6 @@ COMMANDS
   lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>]
                                        Update a doc \u2014 sends only the fields you pass
   lotics knowledge rm <id>             Archive a doc
-  lotics ui link <component> [--ui-src <path>] [--remove]
-                                       Dev-link @lotics/ui to packages/ui/src (Vite alias
-                                       + tsc paths) for live HMR + typecheck. Monorepo apps
-                                       auto-find it; external apps pass --ui-src / LOTICS_UI_SRC
   lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem
                                        (uses the bundled Lotics xlsx engine; prefer over
                                        npm xlsx/exceljs for round-trip fidelity)
@@ -92406,22 +92397,6 @@ async function main() {
     await runPreviewCommand(subcommand, flags);
     return;
   }
-  if (command === "ui") {
-    if (subcommand === "link") {
-      const component = toolArgs;
-      if (!component) {
-        console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
-        console.error("Dev-links @lotics/ui to packages/ui/src (Vite + tsc) for live HMR + typecheck.");
-        console.error("Monorepo apps find packages/ui/src automatically; external apps pass --ui-src / LOTICS_UI_SRC.");
-        process.exit(1);
-      }
-      appUiLink({ component, uiSrc: flags.uiSrc, remove: restArgs.includes("--remove") });
-      return;
-    }
-    console.error(`Unknown ui subcommand: ${subcommand ?? "(none)"}`);
-    console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
-    process.exit(1);
-  }
   if (command === "app" && subcommand === "workflow" && toolArgs === "check") {
     await appWorkflowCheck({ alias: restArgs[0] });
     return;

package/docs/cli_reference.md

@@ -32,7 +32,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `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 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). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). |
+| `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). |
 | `lotics app workflow run <alias> '<json>'` | Execute a bound app workflow end-to-end via `appWorkflow`. `app_id` comes from the local manifest; the alias must be bound (`set_app_workflow`). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin — bulk inputs bypass `ARG_MAX`). Prints the full `{status,message,data,files,side_effects}` JSON to stdout + a one-line summary to stderr; exits non-zero on `status:"error"` (assertable). `--print-created` (alias `--report-effects`) renders the honest post-run harvest (GAP-58): created records grouped by table, a paste-ready `lotics run delete_records …` per table, then the **mandatory caveat** naming what cannot be auto-undone (external integrations + notifications) and that sub-workflows may have run. `--cleanup` (DEFAULT OFF, implies the report) additionally runs the deletes for harvested records ONLY — never files / external / notifications. Neither is a rollback — a rollback is structurally impossible here. |
 | `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` **and the `description`** from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). The `description` is the one line an agent reads when choosing between the app's aliases (the workflow counterpart to a query's) — authored in the manifest so it lives beside the body in version control and rides every push; omit it and the workflow keeps whatever description it already has, so a push can never blank one set elsewhere. When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
 | `lotics app agent set <alias>` | Push the edited `src/agents/<alias>.md` instructions back through `set_app_agent` — the agent mirror of `app workflow set`, and the deploy-free authoring path for `apps.agents`. Reads the prose from disk (the `<!-- lotics: … -->` header stripped) and the typed fields (`inputs`/`outputs`/`tool_names`/`model_id`/`effort_level`/`knowledge_doc_ids`/`query_aliases`/`workflow_aliases`) from `package.json#lotics.agents.<alias>`, then sends them as ONE declaration. That assembly is the point: **`set_app_agent` REPLACES the declaration rather than patching it**, so a hand-built payload that sets one field silently drops the instructions, the output schema and the model pin — a silent, unrecoverable edit against a live prompt. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a file that is empty once the header is stripped (refusing to push an empty prompt). `app pull` writes the file; edit, then `set`. |
@@ -43,8 +43,8 @@ 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 (the former GAP-44): 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 link <component> [--ui-src <path>] [--remove]` | Dev-link `@lotics/ui` to `packages/ui/src` by inserting (or removing) a package-wide `{ find: /^@lotics\/ui\/(.+)$/, replacement: "<absUiSrc>/$1" }` alias in the app's `vite.config.ts` resolve.alias — so edits to `packages/ui/src` go live (HMR) and bundle on deploy, without a publish round-trip. **`packages/ui/src` resolution:** walk up for a monorepo checkout, else the explicit `--ui-src <abs path>` / `LOTICS_UI_SRC` env — that's how an **EXTERNAL app** (one that consumes `@lotics/ui` from npm, e.g. under `~/lotics_apps`) links the local kit; fails loud when neither resolves, or when `--ui-src` isn't a directory. No auth (local file edit). Idempotent. `component` is advisory/validation only (the alias covers every subpath). **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 (uses `react-native-web` types the app resolves as base `react-native`), so typecheck the kit in `packages/ui` and let the finalize publish restore the app's own typecheck. Reminds to restart dev + `rm node_modules/.vite`, and to finalize (`--remove` + publish-chain bump). |
+| `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 — GAP-133/142). 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 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. |
+| `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.102.0",
+  "version": "0.104.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {