@lotics/cli 0.57.0 → 0.60.1

package/dist/src/cli.js

@@ -29579,6 +29579,8 @@ var require_lib3 = __commonJS({
 });
 
 // src/cli.ts
+import dns from "node:dns";
+import net2 from "node:net";
 import fs7 from "node:fs";
 import path6 from "node:path";
 import readline from "node:readline";
@@ -29744,6 +29746,38 @@ var LoticsClient = class {
   async createApp(body) {
     return this.request("POST", "/v1/apps", body);
   }
+  /**
+   * Resolve the display name + fields (incl. select options) of the given tables
+   * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`
+   * alias maps. One `get_table` call per id (the tool surface has no batch
+   * variant); a missing/inaccessible table is dropped rather than throwing, so a
+   * stale id in the scope set never fails codegen.
+   */
+  async getWorkspaceSchema(tableIds) {
+    const tables = await Promise.all(
+      tableIds.map(async (table_id) => {
+        const res = await this.execute("get_table", { table_id });
+        if (res.error || res.result === null || typeof res.result !== "object") return null;
+        const table = res.result;
+        if (typeof table.id !== "string" || typeof table.name !== "string" || !Array.isArray(table.fields)) {
+          return null;
+        }
+        const fields = table.fields.flatMap((field) => {
+          if (field === null || typeof field !== "object") return [];
+          const f = field;
+          if (typeof f.key !== "string" || typeof f.name !== "string") return [];
+          const options = Array.isArray(f.options) ? f.options.flatMap((opt) => {
+            if (opt === null || typeof opt !== "object") return [];
+            const o = opt;
+            return typeof o.key === "string" && typeof o.name === "string" ? [{ id: o.key, label: o.name }] : [];
+          }) : void 0;
+          return [{ id: f.key, name: f.name, ...options && options.length > 0 ? { options } : {} }];
+        });
+        return { id: table.id, name: table.name, fields };
+      })
+    );
+    return tables.filter((t) => t !== null);
+  }
   /**
    * Rename an app's public subdomain — its `<slug>.lotics.app` address.
    * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
@@ -29818,6 +29852,52 @@ var LoticsClient = class {
     if (response.ok) return parsed ?? {};
     return { status: "error", message: transportErrorMessage(response.status, parsed) };
   }
+  /**
+   * Bind (create or replace) an app workflow by alias via the `set_app_workflow`
+   * tool — the SINGLE author of `apps.workflows` + the workflow row. `source` is
+   * the verbatim JS-subset body (no `on({...})` trigger). `inputs`/`outputs` are
+   * the typed schemas declared in `package.json#lotics.workflows.<alias>`. The
+   * server re-verifies the body and echoes the bound `outputs` (declared, else
+   * DERIVED from `return({ data })`), so the CLI can show the author what shape
+   * `result.data` will carry. Wraps the tool rather than a bespoke endpoint so
+   * the file flow stays a convenience over the existing single-author contract.
+   */
+  async setAppWorkflow(app_id, alias, body) {
+    return this.execute("set_app_workflow", {
+      app_id,
+      alias,
+      source: body.source,
+      ...body.inputs ? { inputs: body.inputs } : {},
+      ...body.outputs ? { outputs: body.outputs } : {},
+      ...body.name ? { name: body.name } : {},
+      ...body.description ? { description: body.description } : {}
+    });
+  }
+  /**
+   * Fetch one app workflow's faithful source + bound input/output schemas via
+   * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
+   * persisted step tree (incl. the `return({ data })` clause, opaque field/option
+   * keys) — the exact text `lotics app workflow set` would push back. Feeds
+   * `lotics app pull`, which writes it to `src/workflows/<alias>.ts`.
+   */
+  async getAppWorkflow(app_id, alias) {
+    return this.execute("get_app_workflow", { app_id, alias });
+  }
+  /**
+   * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
+   * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
+   * The server is the single source of the type model — the CLI never
+   * re-implements it. `envelope_prefix`/`envelope_suffix` are the exact
+   * `async function __workflow(): …` wrapper the server compiles inside, so the
+   * local typecheck mirrors the set-time verdict. Mirrors
+   * POST /v1/apps/{app_id}/workflows/{alias}/dts.
+   */
+  async getAppWorkflowDts(app_id, alias) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`
+    );
+  }
   /**
    * Open a streaming agent run and return the RAW streamed `Response` (the
    * caller reads `res.body`). Unlike `request`, this does not buffer/parse the
@@ -30366,6 +30446,45 @@ function buildStarterTemplate(args) {
           // fall to `unknown`. The explicit glob makes the dot-dir the non-wildcard
           // base, which IS read. (GAP-38.)
           include: ["src", ".lotics/**/*"],
+          // src/workflows/<alias>.ts bodies run on the server (workflow globals:
+          // trigger / runtime / tool calls). They ARE locally typecheckable —
+          // each is wrapped in the server's `__workflow` envelope and references
+          // its per-alias `.lotics/workflows/<alias>.globals.d.ts` — but under a
+          // DEDICATED config that mirrors the server's compile options (es2022
+          // lib, NO DOM). The main `npm run typecheck` excludes them so it stays
+          // green and DOM-lib-free for bodies; check a body with
+          // `tsc -p tsconfig.workflows.json`. The server is the single verifier
+          // on `lotics app workflow set`.
+          exclude: ["node_modules", "src/workflows"]
+        },
+        null,
+        2
+      ) + "\n"
+    },
+    {
+      // Dedicated config for the editable workflow bodies (GAP-59). Mirrors the
+      // SERVER's set-time typecheck options (strict, lib es2022 with NO DOM,
+      // target ES2022, skipLibCheck) so a local `tsc -p tsconfig.workflows.json`
+      // gives the same verdict the server would on `lotics app workflow set`.
+      // Each body file is a module (the CLI writes a bookkeeping `export {};`),
+      // so the per-file `__workflow` wrapper doesn't collide across bodies.
+      path: "tsconfig.workflows.json",
+      content: JSON.stringify(
+        {
+          compilerOptions: {
+            target: "ES2022",
+            lib: ["ES2022"],
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            strict: true,
+            skipLibCheck: true,
+            noEmit: true,
+            types: []
+          },
+          // The bodies + their per-alias ambient globals. `.lotics/workflows`
+          // uses the explicit `**/*` glob for the same dot-dir walk reason the
+          // main config does (TS's include walk skips bare dot-dirs).
+          include: ["src/workflows", ".lotics/workflows/**/*"],
           exclude: ["node_modules"]
         },
         null,
@@ -30705,6 +30824,60 @@ const routes = [
 export default function App() {
   return <AppRouter routes={routes} />;
 }
+`
+    },
+    {
+      // The home for editable workflow bodies. `lotics app pull` writes one
+      // `src/workflows/<alias>.ts` per bound workflow (faithful server source);
+      // edit it, then `lotics app workflow set <alias>` pushes it back through
+      // set_app_workflow (the server verifies). A new app has no bound workflows
+      // yet, so this is just the docked directory + the loop reference. It's a
+      // .md (not a .ts) so tsc's `include: ["src"]` never tries to compile it —
+      // a workflow body is a JS-subset expression over server globals
+      // (trigger / runtime / tool calls) that does NOT typecheck standalone.
+      path: "src/workflows/README.md",
+      content: `# Workflow bodies
+
+Editable JS-subset bodies of this app's workflows live here, one file per alias:
+\`src/workflows/<alias>.ts\`.
+
+## Loop
+
+\`\`\`bash
+lotics app workflow pull          # write/refresh every src/workflows/<alias>.ts from the server
+# edit src/workflows/<alias>.ts
+lotics app workflow set <alias>   # push it back through set_app_workflow (the server verifies)
+\`\`\`
+
+\`lotics app pull <app_id>\` also writes these files (alongside the rest of the project).
+
+## What a body is
+
+A workflow body is a **JS-subset expression** that runs server-side using workflow
+globals (\`trigger\`, \`runtime\`, tool calls) and ends with \`return({ data })\`. Each
+pulled file wraps the body in the server's \`__workflow\` envelope and references its
+per-alias ambient globals at \`.lotics/workflows/<alias>.globals.d.ts\`, so it **is**
+locally typecheckable \u2014 under the dedicated config that mirrors the server's compile
+options:
+
+\`\`\`bash
+tsc -p tsconfig.workflows.json   # same verdict the server gives on \`set\`
+\`\`\`
+
+The main \`npm run typecheck\` excludes \`src/workflows\` (it would apply the app's
+DOM lib, which the server doesn't), so the bodies have their own config. The
+verification that matters still runs on the **server** when you \`set\` \u2014 the same
+guarantee as authoring via \`set_app_workflow\` directly. Edit only the body BETWEEN
+the wrapper lines; the wrapper, the \`/// <reference>\`, and the \`export {};\` marker
+are CLI bookkeeping (stripped on \`set\`). Do not rename a file (the filename is the
+alias the binding is keyed by).
+
+## Authority
+
+\`lotics app deploy\` never authors workflows \u2014 it carries code, queries, and
+capabilities only. \`apps.workflows\` has exactly one author: \`set_app_workflow\`
+(which \`lotics app workflow set\` calls). The typed \`inputs\`/\`outputs\` schema for
+each alias lives in \`package.json#lotics.workflows.<alias>\`.
 `
     },
     {
@@ -30894,6 +31067,18 @@ import http from "node:http";
 import net from "node:net";
 import { spawn } from "node:child_process";
 
+// src/child_env.ts
+function ipv4ChildEnv(env) {
+  return {
+    ...env,
+    NODE_OPTIONS: [
+      env.NODE_OPTIONS,
+      "--dns-result-order=ipv4first",
+      "--network-family-autoselection-attempt-timeout=2000"
+    ].filter(Boolean).join(" ")
+  };
+}
+
 // src/dev/rpc_handler.ts
 var SUPPORTED_OPS = /* @__PURE__ */ new Set([
   "query",
@@ -31354,7 +31539,7 @@ async function startDevServer(args) {
     {
       cwd: args.projectDir,
       stdio: [process.stdin.isTTY ? "inherit" : "ignore", "inherit", "inherit"],
-      env: { ...process.env, FORCE_COLOR: "1" }
+      env: ipv4ChildEnv({ ...process.env, FORCE_COLOR: "1" })
     }
   );
   let stopped = false;
@@ -31778,6 +31963,162 @@ ${lines.join("\n")}
 `;
 }
 
+// ../shared/src/app_query_ast.ts
+function collectQueryTableIds(node) {
+  const result = /* @__PURE__ */ new Set();
+  walk(node, (n) => {
+    if (n.kind === "from_table") result.add(n.table_id);
+  });
+  return result;
+}
+function walk(node, visit) {
+  visit(node);
+  switch (node.kind) {
+    case "from_table":
+      return;
+    case "project":
+    case "filter":
+    case "group":
+    case "window":
+    case "sort":
+    case "limit":
+    case "unpivot":
+      walk(node.from, visit);
+      return;
+    case "join":
+      walk(node.left, visit);
+      walk(node.right, visit);
+      return;
+    case "union":
+      for (const child of node.sources) walk(child, visit);
+      return;
+    default: {
+      const _exhaustive = node;
+      void _exhaustive;
+      return;
+    }
+  }
+}
+
+// src/generate_app_fields.ts
+var HEADER4 = `// Auto-generated by 'lotics app codegen' (and app pull/dev/deploy).
+// DO NOT EDIT \u2014 regenerated from the workspace schema.
+//
+// Runtime field + option ids addressed by stable display-name aliases:
+//   record.data[F.<TABLE>.<field>]            \u2192 "fld_\u2026"
+//   value === OPT.<TABLE>.<field>.<option>    \u2192 "opt_\u2026"
+// A rename on the platform re-runs codegen and moves these in lockstep.
+`;
+function slugifyAlias(name, upper) {
+  const stripped = name.normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/đ/g, "d").replace(/Đ/g, "D");
+  const cased = upper ? stripped.toUpperCase() : stripped.toLowerCase();
+  const slug = cased.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  if (slug === "") return "_";
+  return /^[0-9]/.test(slug) ? `_${slug}` : slug;
+}
+function dedupeAliases(names, upper) {
+  const used = /* @__PURE__ */ new Map();
+  return names.map((name) => {
+    const base = slugifyAlias(name, upper);
+    const seen = used.get(base);
+    if (seen === void 0) {
+      used.set(base, 1);
+      return base;
+    }
+    let n = seen + 1;
+    while (used.has(`${base}_${n}`)) n++;
+    used.set(base, n);
+    used.set(`${base}_${n}`, 1);
+    return `${base}_${n}`;
+  });
+}
+function propKey(alias) {
+  return isValidIdentifier(alias) ? alias : JSON.stringify(alias);
+}
+function aliasTables(tables) {
+  const tableAliases = dedupeAliases(
+    tables.map((t) => t.name),
+    true
+  );
+  return tables.map((table, i2) => {
+    const fieldAliases = dedupeAliases(
+      table.fields.map((f) => f.name),
+      false
+    );
+    return {
+      alias: tableAliases[i2],
+      table,
+      fields: table.fields.map((field, j) => ({ alias: fieldAliases[j], field }))
+    };
+  });
+}
+function emitFieldMap(aliased) {
+  const tableBlocks = aliased.map(({ alias, fields }) => {
+    const fieldLines = fields.map(
+      ({ alias: fieldAlias, field }) => `    ${propKey(fieldAlias)}: ${JSON.stringify(field.id)},`
+    );
+    return `  ${propKey(alias)}: {
+${fieldLines.join("\n")}
+  },`;
+  });
+  return `export const F = {
+${tableBlocks.join("\n")}
+} as const;`;
+}
+function emitOptionMap(aliased) {
+  const tableBlocks = [];
+  for (const { alias, fields } of aliased) {
+    const fieldBlocks = [];
+    for (const { alias: fieldAlias, field } of fields) {
+      const options = field.options ?? [];
+      if (options.length === 0) continue;
+      const optionAliases = dedupeAliases(
+        options.map((o) => o.label),
+        false
+      );
+      const optionLines = options.map(
+        (option, i2) => `      ${propKey(optionAliases[i2])}: ${JSON.stringify(option.id)},`
+      );
+      fieldBlocks.push(`    ${propKey(fieldAlias)}: {
+${optionLines.join("\n")}
+    },`);
+    }
+    if (fieldBlocks.length === 0) continue;
+    tableBlocks.push(`  ${propKey(alias)}: {
+${fieldBlocks.join("\n")}
+  },`);
+  }
+  if (tableBlocks.length === 0) return `export const OPT = {} as const;`;
+  return `export const OPT = {
+${tableBlocks.join("\n")}
+} as const;`;
+}
+function generateAppFields(tables) {
+  if (tables.length === 0) {
+    return `${HEADER4}
+export const F = {} as const;
+
+export const OPT = {} as const;
+
+/** Field-id alias map (empty \u2014 no tables in scope). */
+export type AppFields = typeof F;
+/** Select-option alias map (empty \u2014 no tables in scope). */
+export type AppOptions = typeof OPT;
+`;
+  }
+  const aliased = aliasTables(tables);
+  return `${HEADER4}
+${emitFieldMap(aliased)}
+
+${emitOptionMap(aliased)}
+
+/** Field-id alias map: \`F[<TABLE>][<field>]\` is the \`fld_\u2026\` id (literal-typed). */
+export type AppFields = typeof F;
+/** Select-option alias map: \`OPT[<TABLE>][<field>][<option>]\` is the \`opt_\u2026\` id. */
+export type AppOptions = typeof OPT;
+`;
+}
+
 // src/app_commands.ts
 async function fetchLatestNpmVersion(packageName) {
   try {
@@ -31795,6 +32136,98 @@ async function fetchLatestNpmVersion(packageName) {
     return null;
   }
 }
+var WORKFLOWS_DIR = path4.join("src", "workflows");
+var WORKFLOW_GLOBALS_DIR = path4.join(".lotics", "workflows");
+var FALLBACK_ENVELOPE_PREFIX = "async function __workflow(): Promise<__WorkflowReturn | void> {\n";
+var FALLBACK_ENVELOPE_SUFFIX = "\n}";
+function workflowFileHeader(alias) {
+  const refPath = path4.join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`).split(path4.sep).join("/");
+  return `/// <reference path="${refPath}" />
+// Auto-pulled workflow body for "${alias}". Edit the BODY between the wrapper
+// lines below, then push with:
+//   lotics app workflow set ${alias}
+// The push goes through set_app_workflow, where the SERVER verifies the body.
+// The __workflow wrapper + the reference above are CLI bookkeeping (stripped on
+// set) \u2014 they only make the body typecheck locally against the workspace types.
+// Do NOT rename this file \u2014 the filename is the alias the binding is keyed by.
+export {};
+`;
+}
+function workflowFilePath(projectDir, alias) {
+  return path4.join(projectDir, WORKFLOWS_DIR, `${alias}.ts`);
+}
+function workflowGlobalsPath(projectDir, alias) {
+  return path4.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`);
+}
+function writeWorkflowGlobals(projectDir, alias, dts) {
+  const dir = path4.join(projectDir, WORKFLOW_GLOBALS_DIR);
+  fs3.mkdirSync(dir, { recursive: true });
+  const file = workflowGlobalsPath(projectDir, alias);
+  fs3.writeFileSync(file, `${dts.replace(/\s+$/, "")}
+`);
+  return file;
+}
+function writeWorkflowFile(projectDir, alias, source, envelope = { prefix: FALLBACK_ENVELOPE_PREFIX, suffix: FALLBACK_ENVELOPE_SUFFIX }) {
+  const dir = path4.join(projectDir, WORKFLOWS_DIR);
+  fs3.mkdirSync(dir, { recursive: true });
+  const file = workflowFilePath(projectDir, alias);
+  const body = source.replace(/\s+$/, "");
+  fs3.writeFileSync(file, `${workflowFileHeader(alias)}
+${envelope.prefix}${body}${envelope.suffix}
+`);
+  return file;
+}
+var WORKFLOW_WRAPPER_OPENER = /^\s*async\s+function\s+__workflow\s*\(/;
+function stripWorkflowHeader(content) {
+  const lines = content.split("\n");
+  let headerEnd = 0;
+  while (headerEnd < lines.length && /^\s*\/\//.test(lines[headerEnd])) headerEnd++;
+  while (headerEnd < lines.length && /^\s*export\s*\{\s*\}\s*;?\s*$/.test(lines[headerEnd])) headerEnd++;
+  while (headerEnd < lines.length && lines[headerEnd].trim() === "") headerEnd++;
+  let start;
+  if (headerEnd < lines.length && WORKFLOW_WRAPPER_OPENER.test(lines[headerEnd])) {
+    start = headerEnd;
+  } else if (lines.length > 0 && WORKFLOW_WRAPPER_OPENER.test(lines[0])) {
+    start = 0;
+  } else {
+    return content.replace(/\s+$/, "");
+  }
+  let end = lines.length - 1;
+  while (end > start && lines[end].trim() === "") end--;
+  if (lines[end]?.trim() === "}") {
+    return lines.slice(start + 1, end).join("\n").replace(/\s+$/, "");
+  }
+  return lines.slice(start + 1).join("\n").replace(/\s+$/, "");
+}
+async function writeWorkflowFiles(client, projectDir, app_id, aliases) {
+  const written = [];
+  for (const alias of aliases) {
+    const res = await client.getAppWorkflow(app_id, alias);
+    const source = res.error || res.result === null || typeof res.result !== "object" ? null : res.result.source;
+    if (typeof source !== "string" || source.trim() === "") {
+      console.error(
+        `\u26A0 Skipped src/workflows/${alias}.ts \u2014 the server returned no readable source (${res.error ?? "legacy workflow with no rendered body"}).`
+      );
+      continue;
+    }
+    const envelope = await fetchWorkflowGlobals(client, projectDir, app_id, alias);
+    writeWorkflowFile(projectDir, alias, source, envelope);
+    written.push(alias);
+  }
+  return written;
+}
+async function fetchWorkflowGlobals(client, projectDir, app_id, alias) {
+  try {
+    const { dts, envelope_prefix, envelope_suffix } = await client.getAppWorkflowDts(app_id, alias);
+    writeWorkflowGlobals(projectDir, alias, dts);
+    return { prefix: envelope_prefix, suffix: envelope_suffix };
+  } catch (err2) {
+    console.error(
+      `\u26A0 Could not fetch workflow types for "${alias}" (${err2 instanceof Error ? err2.message : String(err2)}). Wrote the body with the fallback wrapper; its local typecheck may be degraded.`
+    );
+    return { prefix: FALLBACK_ENVELOPE_PREFIX, suffix: FALLBACK_ENVELOPE_SUFFIX };
+  }
+}
 function runTar(args, cwd) {
   return new Promise((resolve, reject2) => {
     const proc = spawn2("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
@@ -31811,7 +32244,7 @@ function runTar(args, cwd) {
 }
 function runNpm(args, cwd) {
   return new Promise((resolve, reject2) => {
-    const proc = spawn2("npm", args, { cwd, stdio: "inherit" });
+    const proc = spawn2("npm", args, { cwd, stdio: "inherit", env: ipv4ChildEnv(process.env) });
     proc.on("error", reject2);
     proc.on("exit", (code) => {
       if (code === 0) resolve();
@@ -31850,18 +32283,71 @@ function writeAppMeta(projectDir, meta) {
 function writeAppDts(projectDir, manifest) {
   const dotLotics = path4.join(projectDir, ".lotics");
   fs3.mkdirSync(dotLotics, { recursive: true });
-  fs3.writeFileSync(
-    path4.join(dotLotics, "app_workflows.d.ts"),
-    generateAppWorkflowsDts(manifest.workflows)
-  );
-  fs3.writeFileSync(
-    path4.join(dotLotics, "app_queries.d.ts"),
-    generateAppQueriesDts(manifest.queries)
-  );
-  fs3.writeFileSync(
-    path4.join(dotLotics, "app_agents.d.ts"),
-    generateAppAgentsDts(manifest.agents)
-  );
+  const written = [
+    [path4.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows)],
+    [path4.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries)],
+    [path4.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
+  ];
+  for (const [file, content] of written) fs3.writeFileSync(file, content);
+  return written.map(([file]) => file);
+}
+function readCodegenTablesAllowlist(projectDir) {
+  const pkg2 = JSON.parse(fs3.readFileSync(path4.join(projectDir, "package.json"), "utf-8"));
+  const tables = pkg2.lotics?.codegen?.tables;
+  return Array.isArray(tables) ? tables.filter((t) => typeof t === "string") : [];
+}
+function resolveCodegenTableIds(projectDir, queries) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const decl of Object.values(queries)) {
+    for (const id of collectQueryTableIds(decl.ast)) ids.add(id);
+  }
+  for (const id of readCodegenTablesAllowlist(projectDir)) ids.add(id);
+  return [...ids];
+}
+function writeAppFields(projectDir, tables) {
+  const dotLotics = path4.join(projectDir, ".lotics");
+  fs3.mkdirSync(dotLotics, { recursive: true });
+  const file = path4.join(dotLotics, "app_fields.ts");
+  fs3.writeFileSync(file, generateAppFields(tables));
+  return file;
+}
+async function appCodegen(args) {
+  const projectDir = path4.resolve(args.projectDir ?? process.cwd());
+  const meta = readAppMeta(projectDir);
+  const dtsPaths = writeAppDts(projectDir, {
+    workflows: meta.workflows,
+    queries: meta.queries,
+    agents: meta.agents
+  });
+  for (const p of dtsPaths) console.error(`Regenerated ${p}`);
+  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."
+    );
+    return;
+  }
+  const tableIds = resolveCodegenTableIds(projectDir, meta.queries ?? {});
+  try {
+    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 fetch the workspace schema (${err2 instanceof Error ? err2.message : String(err2)}). Kept the existing .lotics/app_fields.ts.`
+    );
+  }
+  await refreshWorkflowGlobals(args.client, projectDir, meta.app_id, Object.keys(meta.workflows ?? {}));
+}
+async function refreshWorkflowGlobals(client, projectDir, app_id, aliases) {
+  for (const alias of aliases) {
+    const file = workflowFilePath(projectDir, alias);
+    if (!fs3.existsSync(file)) continue;
+    const body = stripWorkflowHeader(fs3.readFileSync(file, "utf-8"));
+    if (body.trim() === "") continue;
+    const envelope = await fetchWorkflowGlobals(client, projectDir, app_id, alias);
+    writeWorkflowFile(projectDir, alias, body, envelope);
+    console.error(`Refreshed ${path4.relative(projectDir, file)} + its workflow types`);
+  }
 }
 function stampPulledManifest(projectDir, args) {
   writeAppMeta(projectDir, {
@@ -31969,6 +32455,15 @@ async function appPull(client, args) {
     queries: app.queries ?? {},
     agents: app.agents ?? {}
   });
+  const aliases = Object.keys(app.workflows ?? {});
+  if (aliases.length > 0) {
+    const written = await writeWorkflowFiles(client, targetPath, app.id, aliases);
+    if (written.length > 0) {
+      console.error(
+        `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`
+      );
+    }
+  }
   console.error(`Installing npm dependencies...`);
   await runNpm(["install"], targetPath);
   console.error(`
@@ -31992,14 +32487,14 @@ function readAppSourceText(projectDir) {
   const srcDir = path4.join(projectDir, "src");
   if (!fs3.existsSync(srcDir)) return "";
   const parts = [];
-  const walk = (dir) => {
+  const walk2 = (dir) => {
     for (const entry of fs3.readdirSync(dir, { withFileTypes: true })) {
       const full = path4.join(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
+      if (entry.isDirectory()) walk2(full);
       else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) parts.push(fs3.readFileSync(full, "utf8"));
     }
   };
-  walk(srcDir);
+  walk2(srcDir);
   return parts.join("\n");
 }
 async function appDeploy(client, args) {
@@ -32146,6 +32641,209 @@ async function appDev(client, args) {
   console.error("\nStopping\u2026");
   await handle.stop();
 }
+function parseCreatedRecords(value) {
+  if (!Array.isArray(value)) return [];
+  const groups = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object") continue;
+    const tableId = entry.table_id;
+    const recordIds = entry.record_ids;
+    if (typeof tableId !== "string" || !Array.isArray(recordIds)) continue;
+    const ids = recordIds.filter((id) => typeof id === "string");
+    if (ids.length > 0) groups.push({ table_id: tableId, record_ids: ids });
+  }
+  return groups;
+}
+function parseIrreversibleToolNames(value) {
+  if (!Array.isArray(value)) return [];
+  const names = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object") continue;
+    const name = entry.tool_name;
+    if (typeof name === "string" && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+function printSideEffects(summary) {
+  const created = parseCreatedRecords(summary.created_records);
+  const irreversibleTools = parseIrreversibleToolNames(summary.irreversible_tool_calls);
+  const subWorkflows = summary.sub_workflows_possible === true;
+  console.error("\nCreated records:");
+  if (created.length === 0) {
+    console.error("  (none with ids to clean up)");
+  } else {
+    for (const group of created) {
+      console.error(`  ${group.table_id}: ${group.record_ids.length} record(s)`);
+      const payload = JSON.stringify({ table_id: group.table_id, record_ids: group.record_ids });
+      console.error(`    lotics run delete_records '${payload}'`);
+    }
+  }
+  const irreversiblePart = irreversibleTools.length > 0 ? `Could NOT auto-undo (clean up manually): ${irreversibleTools.join(", ")}.` : "Could NOT auto-undo: none.";
+  const subPart = subWorkflows ? " Sub-workflows may have run (after_* table workflows) \u2014 their effects are NOT in this list." : "";
+  console.error(`
+${irreversiblePart}${subPart}`);
+}
+async function cleanupCreatedRecords(client, created) {
+  if (created.length === 0) {
+    console.error("\nNo created records to clean up.");
+    return true;
+  }
+  console.error("\nCleaning up created records (delete_records \u2014 records only):");
+  let allDeleted = true;
+  for (const group of created) {
+    const res = await client.execute("delete_records", {
+      table_id: group.table_id,
+      record_ids: group.record_ids
+    });
+    if (res.error) {
+      console.error(`  \u2717 ${group.table_id}: ${res.error}`);
+      allDeleted = false;
+    } else {
+      console.error(`  \u2713 ${group.table_id}: deleted ${group.record_ids.length} record(s)`);
+    }
+  }
+  return allDeleted;
+}
+async function appExecuteWorkflow(client, args) {
+  const meta = readAppMeta(process.cwd());
+  const result = await client.appWorkflow(meta.app_id, args.alias, args.inputs);
+  console.log(JSON.stringify(result, null, 2));
+  const status = typeof result.status === "string" ? result.status : "unknown";
+  const message = typeof result.message === "string" ? result.message : "";
+  console.error(`Workflow "${args.alias}" \u2192 ${status}${message ? `: ${message}` : ""}`);
+  let cleanupFailed = false;
+  if ((args.printCreated || args.cleanup) && result.side_effects) {
+    printSideEffects(result.side_effects);
+    if (args.cleanup) {
+      const allDeleted = await cleanupCreatedRecords(
+        client,
+        parseCreatedRecords(result.side_effects.created_records)
+      );
+      cleanupFailed = !allDeleted;
+    }
+  } else if (args.printCreated || args.cleanup) {
+    console.error("\n(no side-effect summary returned by the server)");
+  }
+  if (status === "error" || cleanupFailed) process.exit(1);
+}
+async function appWorkflowSet(client, args) {
+  const projectDir = process.cwd();
+  const meta = readAppMeta(projectDir);
+  const declaration = meta.workflows?.[args.alias];
+  if (!declaration) {
+    console.error(
+      `No workflow "${args.alias}" in package.json#lotics.workflows. Bind it first (set_app_workflow), then 'lotics app pull' to write its body and manifest entry.`
+    );
+    process.exit(1);
+  }
+  const file = workflowFilePath(projectDir, args.alias);
+  if (!fs3.existsSync(file)) {
+    console.error(
+      `No workflow body at ${path4.relative(projectDir, file)}. Run 'lotics app pull ${meta.app_id}' to write src/workflows/${args.alias}.ts, then edit it.`
+    );
+    process.exit(1);
+  }
+  const source = stripWorkflowHeader(fs3.readFileSync(file, "utf-8"));
+  if (source.trim() === "") {
+    console.error(`Workflow body ${path4.relative(projectDir, file)} is empty after stripping the header.`);
+    process.exit(1);
+  }
+  const res = await client.setAppWorkflow(meta.app_id, args.alias, {
+    source,
+    inputs: declaration.inputs,
+    outputs: declaration.outputs
+  });
+  if (res.error) {
+    console.error(`Failed to set workflow "${args.alias}": ${res.error}`);
+    process.exit(1);
+  }
+  const result = res.result ?? {};
+  const workflowId = typeof result.workflow_id === "string" ? result.workflow_id : "(unknown)";
+  console.error(`Set workflow "${args.alias}" \u2192 ${workflowId}`);
+  if (result.outputs && typeof result.outputs === "object") {
+    console.error(`  result.data schema: ${JSON.stringify(result.outputs)}`);
+  }
+}
+async function appWorkflowPull(client) {
+  const projectDir = process.cwd();
+  const meta = readAppMeta(projectDir);
+  const app = await client.getApp(meta.app_id);
+  const aliases = Object.keys(app.workflows ?? {});
+  if (aliases.length === 0) {
+    console.error(`App ${meta.app_id} has no bound workflows.`);
+    return;
+  }
+  const written = await writeWorkflowFiles(client, projectDir, meta.app_id, aliases);
+  console.error(
+    `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
+  );
+}
+function findUiSrcDir(start) {
+  let dir = path4.resolve(start);
+  for (; ; ) {
+    const candidate = path4.join(dir, "packages", "ui", "src");
+    if (fs3.existsSync(candidate) && fs3.statSync(candidate).isDirectory()) return candidate;
+    const parent = path4.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+var UI_ALIAS_FIND_SOURCE = String.raw`/^@lotics\/ui\/(.+)$/`;
+function appUiLink(args) {
+  const projectDir = path4.resolve(args.projectDir ?? process.cwd());
+  const viteConfigPath = path4.join(projectDir, "vite.config.ts");
+  if (!fs3.existsSync(viteConfigPath)) {
+    throw new Error(
+      `No vite.config.ts at ${projectDir}. Run inside a 'lotics app' project directory.`
+    );
+  }
+  const uiSrc = findUiSrcDir(projectDir);
+  if (!uiSrc) {
+    throw new Error(
+      "Cannot find packages/ui/src by walking up from this directory \u2014 `lotics ui link` requires a monorepo checkout. External apps consume @lotics/ui from npm; bump the package version and widen the app's dependency range instead."
+    );
+  }
+  const hasComponent = fs3.existsSync(path4.join(uiSrc, `${args.component}.tsx`)) || fs3.existsSync(path4.join(uiSrc, `${args.component}.ts`)) || fs3.existsSync(path4.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 = fs3.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(`^\\s*\\{ find: ${escapeRegExp(UI_ALIAS_FIND_SOURCE)}.*$\\n?`, "m"), "");
+    fs3.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)}`;
+  fs3.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) {
@@ -32162,6 +32860,8 @@ function parseArgs(argv) {
     message: void 0,
     local: false,
     all: false,
+    printCreated: false,
+    cleanup: false,
     version: false,
     help: false
   };
@@ -32212,6 +32912,13 @@ function parseArgs(argv) {
       case "--all":
         flags.all = true;
         break;
+      case "--print-created":
+      case "--report-effects":
+        flags.printCreated = true;
+        break;
+      case "--cleanup":
+        flags.cleanup = true;
+        break;
       case "--version":
       case "-v":
         flags.version = true;
@@ -32237,6 +32944,34 @@ function parseArgs(argv) {
   return { command, subcommand, toolArgs, restArgs, flags };
 }
 
+// src/inputs.ts
+async function ingestJsonArgs(opts) {
+  let raw = opts.rawArg;
+  if (raw && raw.startsWith("@")) {
+    const argsPath = raw.slice(1);
+    try {
+      raw = opts.readFile(argsPath);
+    } catch (err2) {
+      return {
+        kind: "error",
+        message: `Cannot read args file "${argsPath}": ${err2 instanceof Error ? err2.message : String(err2)}`
+      };
+    }
+  } else if (!raw && !opts.stdinIsTTY) {
+    raw = await opts.readStdin();
+  }
+  if (!raw) return { kind: "ok", args: {} };
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { kind: "error", message: `JSON args must be an object, got: ${raw}` };
+    }
+    return { kind: "ok", args: parsed };
+  } catch {
+    return { kind: "error", message: `Invalid JSON: ${raw}` };
+  }
+}
+
 // src/xlsx.ts
 import fs5 from "node:fs";
 
@@ -48170,6 +48905,8 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
 }
 
 // src/cli.ts
+dns.setDefaultResultOrder("ipv4first");
+net2.setDefaultAutoSelectFamilyAttemptTimeout(2e3);
 function printHelp() {
   console.log(`Lotics CLI v${VERSION} \u2014 AI agent interface for Lotics
 
@@ -48226,9 +48963,21 @@ COMMANDS
   lotics app deploy [-m <message>]     Build + upload current dir as a new version
                                        (code + queries only \u2014 workflow bindings are
                                        managed by set_app_workflow / remove_app_workflow)
+  lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)
+                                       from the manifest + workspace schema \u2014 no deploy
+  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end
+                                       (inputs: inline JSON, @file, or stdin;
+                                        --print-created reports created records +
+                                        a paste-ready cleanup plan; --cleanup also
+                                        deletes those records \u2014 NOT a rollback)
+  lotics app workflow set <alias>      Push the edited src/workflows/<alias>.ts body
+                                       through set_app_workflow (server verifies)
+  lotics app workflow pull             Rewrite src/workflows/*.ts from the server
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
+  lotics ui link <component> [--remove] Dev-link @lotics/ui to the monorepo's
+                                       packages/ui/src for live HMR (monorepo only)
   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)
@@ -48588,6 +49337,34 @@ async function main() {
     await runDocxCommand(subcommand, toolArgs, restArgs);
     return;
   }
+  if (command === "ui") {
+    if (subcommand === "link") {
+      const component = toolArgs;
+      if (!component) {
+        console.error("Usage: lotics ui link <component> [--remove]");
+        console.error("Dev-links @lotics/ui to the monorepo's packages/ui/src for live HMR.");
+        process.exit(1);
+      }
+      appUiLink({ component, remove: restArgs.includes("--remove") });
+      return;
+    }
+    console.error(`Unknown ui subcommand: ${subcommand ?? "(none)"}`);
+    console.error("Usage: lotics ui link <component> [--remove]");
+    process.exit(1);
+  }
+  if (command === "app" && subcommand === "codegen") {
+    const projectDir = toolArgs;
+    const ctx2 = resolveContext(flags);
+    if (!ctx2) {
+      await appCodegen({ projectDir });
+      return;
+    }
+    const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
+    const client2 = new LoticsClient({ apiKey: ctx2.apiKey, workspaceId: ctx2.workspaceId, viewAsMemberId });
+    await resolveWorkspace(client2, ctx2);
+    await appCodegen({ projectDir, client: client2 });
+    return;
+  }
   if (command === "org") {
     const global2 = loadGlobalConfig() ?? {};
     const profiles = global2.profiles ?? {};
@@ -48655,6 +49432,10 @@ async function main() {
     console.error("  lotics app create <name> [path]      Scaffold a new app locally");
     console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
     console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
+    console.error("  lotics app codegen [path]            Regenerate .lotics/* (types + field ids) \u2014 no deploy");
+    console.error("  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end");
+    console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
+    console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
     console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
     console.error(`  lotics app rename "<new name>"        Rename the app's display name (launcher title)`);
     console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
@@ -48796,6 +49577,59 @@ Available workspaces:`);
       await appRename(client, { name: newName });
       return;
     }
+    if (subcommand === "workflow") {
+      const action = toolArgs;
+      const workflowUsage = () => {
+        console.error("Usage:");
+        console.error("  lotics app workflow run <alias> '<json>'   Execute a bound app workflow");
+        console.error("  lotics app workflow set <alias>            Push src/workflows/<alias>.ts");
+        console.error("  lotics app workflow pull                   Rewrite src/workflows/*.ts from the server");
+        process.exit(1);
+      };
+      if (action === "run") {
+        const alias = restArgs[0];
+        if (!alias) {
+          console.error("Usage: lotics app workflow run <alias> '<json>'");
+          console.error("       lotics app workflow run <alias> @inputs.json   (read inputs from a file)");
+          console.error("       cat inputs.json | lotics app workflow run <alias>   (read inputs from stdin)");
+          console.error("Flags: --print-created (report created records + cleanup plan + caveat)");
+          console.error("       --cleanup (also delete the created records \u2014 records only, NOT a rollback)");
+          process.exit(1);
+        }
+        const ingested = await ingestJsonArgs({
+          rawArg: restArgs[1],
+          stdinIsTTY: process.stdin.isTTY ?? false,
+          readFile: (p) => fs7.readFileSync(p, "utf-8"),
+          readStdin
+        });
+        if (ingested.kind === "error") {
+          console.error(ingested.message);
+          process.exit(1);
+        }
+        await appExecuteWorkflow(client, {
+          alias,
+          inputs: ingested.args,
+          printCreated: flags.printCreated,
+          cleanup: flags.cleanup
+        });
+        return;
+      }
+      if (action === "set") {
+        const alias = restArgs[0];
+        if (!alias) {
+          console.error("Usage: lotics app workflow set <alias>");
+          console.error("Pushes the edited src/workflows/<alias>.ts body via set_app_workflow.");
+          process.exit(1);
+        }
+        await appWorkflowSet(client, { alias });
+        return;
+      }
+      if (action === "pull") {
+        await appWorkflowPull(client);
+        return;
+      }
+      workflowUsage();
+    }
     if (subcommand === "dev") {
       const projectDir = toolArgs;
       let port;
@@ -48894,29 +49728,17 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
   }
   if (command === "run") {
     const toolName = subcommand;
-    let rawArgs = toolArgs;
-    if (rawArgs && rawArgs.startsWith("@")) {
-      const argsPath = rawArgs.slice(1);
-      try {
-        rawArgs = fs7.readFileSync(argsPath, "utf-8");
-      } catch (err2) {
-        console.error(
-          `Cannot read args file "${argsPath}": ${err2 instanceof Error ? err2.message : String(err2)}`
-        );
-        process.exit(1);
-      }
-    } else if (!rawArgs && !process.stdin.isTTY) {
-      rawArgs = await readStdin();
-    }
-    let args = {};
-    if (rawArgs) {
-      try {
-        args = JSON.parse(rawArgs);
-      } catch {
-        console.error(`Invalid JSON: ${rawArgs}`);
-        process.exit(1);
-      }
+    const ingested = await ingestJsonArgs({
+      rawArg: toolArgs,
+      stdinIsTTY: process.stdin.isTTY ?? false,
+      readFile: (p) => fs7.readFileSync(p, "utf-8"),
+      readStdin
+    });
+    if (ingested.kind === "error") {
+      console.error(ingested.message);
+      process.exit(1);
     }
+    const args = ingested.args;
     const timeoutMs = flags.timeout ?? 6e4;
     const result = await client.execute(toolName, args, { format: "text", timeoutMs });
     if (result.error) {