@lotics/cli 0.56.0 → 0.60.1

package/dist/app_commands.js

@@ -17,9 +17,12 @@ import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { buildStarterTemplate } from "./starter_template.js";
 import { startDevServer, openBrowser } from "./dev/server.js";
+import { ipv4ChildEnv } from "./child_env.js";
 import { generateAppWorkflowsDts } from "./generate_app_workflows_dts.js";
 import { generateAppAgentsDts } from "./generate_app_agents_dts.js";
 import { generateAppQueriesDts } from "./generate_app_queries_dts.js";
+import { collectQueryTableIds } from "@lotics/shared/app_query_ast";
+import { generateAppFields } from "./generate_app_fields.js";
 /**
  * Resolve the latest published version of a package from the npm registry.
  * Returns null on any failure (network error, 404, malformed payload) so
@@ -46,6 +49,190 @@ async function fetchLatestNpmVersion(packageName) {
         return null;
     }
 }
+/** The directory, relative to the project root, that holds editable workflow bodies. */
+const WORKFLOWS_DIR = path.join("src", "workflows");
+/** The dot-dir that holds the per-alias ambient globals `.d.ts` (server-generated). */
+const WORKFLOW_GLOBALS_DIR = path.join(".lotics", "workflows");
+/**
+ * The `async function __workflow(...)` wrapper a workflow body sits inside —
+ * the SAME envelope the server compiles the body within at `set_app_workflow`
+ * verify time (GAP-59). Carried so a body that uses top-level `await` and ends
+ * with `return({...})` typechecks locally exactly as the server checks it. The
+ * server returns the canonical strings (`getAppWorkflowDts`); these are the
+ * offline fallback when the dts fetch fails so the file is still wrapped — a
+ * test pins them equal to the server's, so they can't drift.
+ */
+export const FALLBACK_ENVELOPE_PREFIX = "async function __workflow(): Promise<__WorkflowReturn | void> {\n";
+export const FALLBACK_ENVELOPE_SUFFIX = "\n}";
+/**
+ * Header prepended to every pulled `src/workflows/<alias>.ts`. A triple-slash
+ * reference pulls in the per-alias ambient globals (`trigger` / `runtime` / tool
+ * calls — server-generated), and the body sits inside the SAME `__workflow`
+ * wrapper the server compiles within, so a local `tsc` now mirrors the set-time
+ * verdict (GAP-59). The wrapper + reference + comment lines are CLI bookkeeping,
+ * stripped on `set`; the filename IS the alias — renaming it orphans the body.
+ */
+function workflowFileHeader(alias) {
+    const refPath = path
+        .join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`)
+        .split(path.sep)
+        .join("/");
+    return (`/// <reference path="${refPath}" />\n` +
+        `// Auto-pulled workflow body for "${alias}". Edit the BODY between the wrapper\n` +
+        `// lines below, then push with:\n` +
+        `//   lotics app workflow set ${alias}\n` +
+        `// The push goes through set_app_workflow, where the SERVER verifies the body.\n` +
+        `// The __workflow wrapper + the reference above are CLI bookkeeping (stripped on\n` +
+        `// set) — they only make the body typecheck locally against the workspace types.\n` +
+        `// Do NOT rename this file — the filename is the alias the binding is keyed by.\n` +
+        // `export {};` makes the file a MODULE so the per-file `__workflow` wrapper
+        // doesn't collide across the bodies the dedicated tsconfig globs together.
+        // The server compiles each body in isolation (script mode), so this is a
+        // local-only adaptation with no effect on the body's type-checking; it is
+        // CLI bookkeeping, stripped on `set`.
+        `export {};\n`);
+}
+/** Absolute path of one workflow body file, given the project root + alias. */
+function workflowFilePath(projectDir, alias) {
+    return path.join(projectDir, WORKFLOWS_DIR, `${alias}.ts`);
+}
+/** Absolute path of one alias's ambient globals `.d.ts`. */
+function workflowGlobalsPath(projectDir, alias) {
+    return path.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`);
+}
+/**
+ * Write `.lotics/workflows/<alias>.globals.d.ts` = the server-generated ambient
+ * declarations the body typechecks against. Idempotent. Returns the path.
+ */
+export function writeWorkflowGlobals(projectDir, alias, dts) {
+    const dir = path.join(projectDir, WORKFLOW_GLOBALS_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = workflowGlobalsPath(projectDir, alias);
+    fs.writeFileSync(file, `${dts.replace(/\s+$/, "")}\n`);
+    return file;
+}
+/**
+ * Write `src/workflows/<alias>.ts` = header (triple-slash reference + comments)
+ * + the body wrapped in the `__workflow` envelope. Idempotent (a re-pull
+ * overwrites with the current server body). The raw `source` round-trips on
+ * `set` (the header + wrapper are stripped). Exported for direct unit testing —
+ * the surrounding pull shells out to `tar`/`npm`.
+ */
+export function writeWorkflowFile(projectDir, alias, source, envelope = { prefix: FALLBACK_ENVELOPE_PREFIX, suffix: FALLBACK_ENVELOPE_SUFFIX }) {
+    const dir = path.join(projectDir, WORKFLOWS_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = workflowFilePath(projectDir, alias);
+    // Body verbatim inside the wrapper so a later `set` round-trips byte-for-byte
+    // (modulo the header + wrapper, which are stripped). The prefix already ends
+    // with a newline and the suffix begins with one (server envelope shape).
+    const body = source.replace(/\s+$/, "");
+    fs.writeFileSync(file, `${workflowFileHeader(alias)}\n${envelope.prefix}${body}${envelope.suffix}\n`);
+    return file;
+}
+/** Matches the `__workflow` envelope opener (the wrapper `writeWorkflowFile`
+ *  prepends). Recognized structurally (not by exact return-type text) so a
+ *  future envelope-signature tweak doesn't silently leave the wrapper in the
+ *  pushed source. */
+const WORKFLOW_WRAPPER_OPENER = /^\s*async\s+function\s+__workflow\s*\(/;
+/**
+ * Strip the CLI bookkeeping back off a workflow body before pushing it: the
+ * triple-slash reference + the `//` header comments + the `export {};` marker +
+ * blank lines, then the `__workflow` envelope (the opening
+ * `async function __workflow(...) {` line and the matching trailing `}`). `set`
+ * sends ONLY the JS-subset body the author edited — the server stays the single
+ * verifier.
+ *
+ * The strip is anchored on the GENERATED bookkeeping, never on "the file happens
+ * to start with comments": the leading comment/marker/blank block is only peeled
+ * when it is immediately followed by the `__workflow` wrapper opener (the exact
+ * shape `writeWorkflowFile` produces). A hand-written, wrapper-LESS body whose
+ * first lines are comments therefore round-trips unchanged — its comments are
+ * real source, not bookkeeping, and must not be silently eaten.
+ */
+export function stripWorkflowHeader(content) {
+    const lines = content.split("\n");
+    // Probe how far a generated header would extend: `//`/`///` lines, then the
+    // `export {};` module marker, then the blank line(s) before the wrapper.
+    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++;
+    // Peel the header ONLY when the wrapper opener follows it — that's the proof
+    // the leading block was generated bookkeeping and not the author's own source.
+    // If the file opens with the wrapper directly (degraded pull with no header),
+    // peel from there. Otherwise leave the body verbatim.
+    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+$/, "");
+    }
+    // `start` is the wrapper opener line — drop it and the matching trailing `}`.
+    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+$/, "");
+    }
+    // Opener present but no closing `}` — a malformed wrapper; push the body after
+    // the opener verbatim rather than guessing where the envelope ends.
+    return lines.slice(start + 1).join("\n").replace(/\s+$/, "");
+}
+/**
+ * Pull every workflow body the server can render into `src/workflows/<alias>.ts`,
+ * plus the per-alias ambient globals `.lotics/workflows/<alias>.globals.d.ts` that
+ * make the body locally typecheckable. The alias set comes from the live
+ * `apps.workflows` map; each body comes from `get_app_workflow` (faithful source
+ * re-rendered from the persisted step tree) and each globals + envelope from
+ * `getAppWorkflowDts`. A legacy alias whose source can't be read is WARNED and
+ * SKIPPED — never a failure — so a partially-migrated app still pulls. A dts
+ * fetch failure is non-fatal too: the body is still written (with the fallback
+ * envelope), only the local typecheck is degraded — mirrors `app_fields`.
+ * Returns the aliases written.
+ */
+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(`⚠ Skipped src/workflows/${alias}.ts — 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;
+}
+/**
+ * Fetch + write one alias's ambient globals `.d.ts` and return the wrapper
+ * envelope to wrap the body in. Network failure is non-fatal (warn, keep the
+ * last-written globals if any) and the body is wrapped in the FALLBACK envelope
+ * so it still parses — mirrors `app_fields`'s offline tolerance.
+ */
+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 (err) {
+        console.error(`⚠ Could not fetch workflow types for "${alias}" (${err instanceof Error ? err.message : String(err)}). ` +
+            `Wrote the body with the fallback wrapper; its local typecheck may be degraded.`);
+        return { prefix: FALLBACK_ENVELOPE_PREFIX, suffix: FALLBACK_ENVELOPE_SUFFIX };
+    }
+}
 /** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
 function runTar(args, cwd) {
     return new Promise((resolve, reject) => {
@@ -66,7 +253,7 @@ function runTar(args, cwd) {
 /** Run `npm` (run/install/etc.) inheriting stdio so the user sees progress. */
 function runNpm(args, cwd) {
     return new Promise((resolve, reject) => {
-        const proc = spawn("npm", args, { cwd, stdio: "inherit" });
+        const proc = spawn("npm", args, { cwd, stdio: "inherit", env: ipv4ChildEnv(process.env) });
         proc.on("error", reject);
         proc.on("exit", (code) => {
             if (code === 0)
@@ -113,9 +300,121 @@ function writeAppMeta(projectDir, meta) {
 function writeAppDts(projectDir, manifest) {
     const dotLotics = path.join(projectDir, ".lotics");
     fs.mkdirSync(dotLotics, { recursive: true });
-    fs.writeFileSync(path.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows));
-    fs.writeFileSync(path.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries));
-    fs.writeFileSync(path.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents));
+    const written = [
+        [path.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows)],
+        [path.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries)],
+        [path.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)],
+    ];
+    for (const [file, content] of written)
+        fs.writeFileSync(file, content);
+    return written.map(([file]) => file);
+}
+/**
+ * The optional `package.json#lotics.codegen.tables` allowlist — extra table ids
+ * to include in `app_fields.ts` beyond those the named queries reference (e.g.
+ * tables an app only writes to via a workflow, never queries). Returns `[]` when
+ * absent or malformed (codegen falls back to the query-derived set).
+ */
+function readCodegenTablesAllowlist(projectDir) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf-8"));
+    const tables = pkg.lotics?.codegen?.tables;
+    return Array.isArray(tables) ? tables.filter((t) => typeof t === "string") : [];
+}
+/**
+ * The table ids `app_fields.ts` should cover: the union of every `from_table`
+ * referenced by a declared query AST plus the optional manifest allowlist. The
+ * query set is what the app can actually read; the allowlist widens it to tables
+ * only ever written (so their field/option aliases are still addressable).
+ */
+function resolveCodegenTableIds(projectDir, queries) {
+    const ids = new Set();
+    for (const decl of Object.values(queries)) {
+        // The manifest stores the AST untyped (`unknown`) — it's the server's
+        // deploy-time concern to verify. Cast at this single boundary so codegen
+        // reuses the canonical exhaustive walker (a new QueryNode kind is a
+        // compile error there, never a silently-dropped table).
+        for (const id of collectQueryTableIds(decl.ast))
+            ids.add(id);
+    }
+    for (const id of readCodegenTablesAllowlist(projectDir))
+        ids.add(id);
+    return [...ids];
+}
+/**
+ * Write the runtime `.lotics/app_fields.ts` from a resolved workspace schema.
+ * Separate from `writeAppDts` (the type-only companions) because this one needs
+ * the client to fetch the schema. Returns the written path.
+ */
+function writeAppFields(projectDir, tables) {
+    const dotLotics = path.join(projectDir, ".lotics");
+    fs.mkdirSync(dotLotics, { recursive: true });
+    const file = path.join(dotLotics, "app_fields.ts");
+    fs.writeFileSync(file, generateAppFields(tables));
+    return file;
+}
+/**
+ * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
+ * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are
+ * always written (synchronous, no network). When a `client` is available, the
+ * runtime `app_fields.ts` is also regenerated from the live schema of the tables
+ * the app's queries reference (+ the allowlist); a network failure is non-fatal
+ * (warn, keep the last-generated file) — so codegen still does useful work
+ * offline, mirroring `app create`'s tolerance of an offline npm registry.
+ */
+export async function appCodegen(args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    // readAppMeta throws the clear not-an-app error when there's no manifest.
+    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 — 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 (err) {
+        // Non-fatal: keep the last-generated app_fields.ts so an offline/transient
+        // failure doesn't strip the app's field aliases (same tolerance as the npm
+        // registry lookup on `app create`).
+        console.error(`⚠ Could not fetch the workspace schema (${err instanceof Error ? err.message : String(err)}). ` +
+            `Kept the existing .lotics/app_fields.ts.`);
+    }
+    // Refresh each bound workflow's ambient globals + re-wrap its EXISTING local
+    // body in the current envelope (GAP-59). Codegen never re-fetches the body
+    // (that would clobber local edits) — it strips the on-disk body and re-wraps
+    // it, so the local typecheck tracks the current workspace schema. Aliases
+    // never pulled (no body file yet) are skipped — codegen isn't a pull.
+    await refreshWorkflowGlobals(args.client, projectDir, meta.app_id, Object.keys(meta.workflows ?? {}));
+}
+/**
+ * For each bound alias that already has a local body file, fetch its current
+ * ambient globals `.d.ts` + envelope and re-wrap the on-disk body. Preserves the
+ * author's edits (strips + re-wraps, never re-fetches the body). A dts fetch
+ * failure is non-fatal per alias (warned inside `fetchWorkflowGlobals`).
+ */
+async function refreshWorkflowGlobals(client, projectDir, app_id, aliases) {
+    for (const alias of aliases) {
+        const file = workflowFilePath(projectDir, alias);
+        if (!fs.existsSync(file))
+            continue;
+        const body = stripWorkflowHeader(fs.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 ${path.relative(projectDir, file)} + its workflow types`);
+    }
 }
 /**
  * Stamp the post-extraction manifest with server-authoritative meta. Called
@@ -245,8 +544,10 @@ export async function appCreate(client, args) {
  *   4. Regenerate `.lotics/app_workflows.d.ts` from the live workflows so
  *      `useWorkflow<"alias">` is typed at pull time.
  *   5. Run `npm install`.
- *   6. (TODO) Generate `.lotics/types.ts` with workspace tables augmentation —
- *      pending a `client.getWorkspaceSchema()` endpoint.
+ *
+ * Runtime field/option id aliases (`.lotics/app_fields.ts`) are generated on
+ * demand by `lotics app codegen`, which fetches the workspace schema — pull
+ * leaves it to that command so a schema fetch never blocks the bootstrap.
  */
 /**
  * `lotics app subdomain <new>` — rename the current app's public address.
@@ -306,6 +607,18 @@ export async function appPull(client, args) {
         queries: app.queries ?? {},
         agents: app.agents ?? {},
     });
+    // Write each bound workflow's faithful body to src/workflows/<alias>.ts so the
+    // author edits a real file and pushes with `lotics app workflow set <alias>`
+    // — no more fetch/reconstruct/escape. Sourced from get_app_workflow (the live
+    // workflow row), like the manifest's `workflows` map, so agent-authored bodies
+    // survive the pull. A legacy alias with no rendered source warns and is skipped.
+    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(`\nReady. Next steps:`);
@@ -535,3 +848,297 @@ export async function appDev(client, args) {
     console.error("\nStopping…");
     await handle.stop();
 }
+/** Narrow the loose envelope's `created_records` into typed groups. */
+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;
+}
+/** Narrow `irreversible_tool_calls` into a list of tool names (deduped, ordered). */
+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;
+}
+/**
+ * Print the honest harvest of a run's side effects to stderr (GAP-58): created
+ * records grouped by table, a ready-to-paste `lotics run delete_records …` per
+ * table, then the MANDATORY caveat naming what cannot be auto-undone. Never
+ * deletes anything — this only reports.
+ */
+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}'`);
+        }
+    }
+    // The caveat is mandatory and unconditional — a clean run still owes the
+    // reader the explicit "this is not a rollback" framing so cleanup is never
+    // mistaken for complete.
+    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) — their effects are NOT in this list."
+        : "";
+    console.error(`\n${irreversiblePart}${subPart}`);
+}
+/**
+ * Run the harvested deletes for created records ONLY (never files / external /
+ * notifications — those are reported, never silently undone). Best-effort: a
+ * failed delete is logged and the rest continue. Returns `false` when ANY delete
+ * failed, so the command boundary can exit non-zero — a CI script branching on
+ * the exit code must not read partial cleanup as success.
+ */
+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 — 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(`  ✗ ${group.table_id}: ${res.error}`);
+            allDeleted = false;
+        }
+        else {
+            console.error(`  ✓ ${group.table_id}: deleted ${group.record_ids.length} record(s)`);
+        }
+    }
+    return allDeleted;
+}
+/**
+ * `lotics app workflow run <alias> '<json>'` — execute a bound app workflow
+ * end-to-end against the live workspace. `app_id` comes from the local manifest
+ * (like deploy/dev), the alias must be bound server-side via `set_app_workflow`.
+ *
+ * The full `{ status, message, data, files, side_effects }` JSON prints to
+ * stdout (pipeable / assertable); a one-line human summary goes to stderr. A
+ * `status: "error"` envelope exits non-zero so a script can branch on it — the
+ * transport already normalizes a gateway/timeout failure into the same
+ * `{ status: "error" }` shape, so a failed run is never a thrown HTML body.
+ *
+ * `--print-created` (alias `--report-effects`) renders the honest post-run
+ * harvest (GAP-58): created records grouped by table, a paste-ready
+ * `delete_records` per table, and the mandatory caveat about what cannot be
+ * auto-undone. `--cleanup` (DEFAULT OFF) additionally runs the deletes for the
+ * harvested records ONLY — never files, external integrations, or notifications.
+ * Neither is a rollback; a rollback is structurally impossible here.
+ */
+export 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}" → ${status}${message ? `: ${message}` : ""}`);
+    // --cleanup implies the report (you should always see what's being undone).
+    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)");
+    }
+    // Exit non-zero on an error run OR a partial cleanup — a script must not read
+    // either as success.
+    if (status === "error" || cleanupFailed)
+        process.exit(1);
+}
+/**
+ * `lotics app workflow set <alias>` — push the edited `src/workflows/<alias>.ts`
+ * body to the server through `set_app_workflow` (the single author of
+ * `apps.workflows`). The body is read from disk (header stripped); the typed
+ * `inputs`/`outputs` schemas come from `package.json#lotics.workflows.<alias>`,
+ * so a pulled-then-edited app keeps its declared contract. The server re-verifies
+ * the body and echoes the bound `outputs` (declared, else DERIVED from
+ * `return({ data })`) — the same guarantee as calling `set_app_workflow` by hand,
+ * with no fetch/reconstruct/escape. Errors (missing file, unbound alias, verify
+ * failure) print to stderr and exit non-zero.
+ *
+ * This is a CLI convenience over the existing tool — `lotics app deploy` is still
+ * NOT an author of workflows; the single-author invariant holds.
+ */
+export 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 (!fs.existsSync(file)) {
+        console.error(`No workflow body at ${path.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(fs.readFileSync(file, "utf-8"));
+    if (source.trim() === "") {
+        console.error(`Workflow body ${path.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);
+    }
+    // set_app_workflow echoes { app_id, alias, workflow_id, outputs? } — outputs is
+    // declared-wins-else-DERIVED from return({ data }), the shape result.data carries.
+    const result = (res.result ?? {});
+    const workflowId = typeof result.workflow_id === "string" ? result.workflow_id : "(unknown)";
+    console.error(`Set workflow "${args.alias}" → ${workflowId}`);
+    if (result.outputs && typeof result.outputs === "object") {
+        console.error(`  result.data schema: ${JSON.stringify(result.outputs)}`);
+    }
+}
+/**
+ * `lotics app workflow pull` — rewrite every `src/workflows/<alias>.ts` from the
+ * server without a full `lotics app pull` (no source archive, no npm install).
+ * The alias set + bodies come from the live App row (the same source `app pull`
+ * uses); a legacy alias with no rendered source warns and is skipped.
+ */
+export 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(", ")})` : ""));
+}
+/**
+ * Walk up from `start` to the monorepo's `packages/ui/src`. Returns null when
+ * not found — an external npm app author has no monorepo checkout, so `ui link`
+ * must fail loud rather than write a broken alias.
+ */
+function findUiSrcDir(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        const candidate = path.join(dir, "packages", "ui", "src");
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory())
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+// The dev-link alias entry — a package-wide `@lotics/ui/<subpath>` → local
+// `packages/ui/src/<subpath>` redirect. Matched/removed by the literal `find`
+// regex source so insert/remove is idempotent regardless of the replacement.
+const UI_ALIAS_FIND_SOURCE = String.raw `/^@lotics\/ui\/(.+)$/`;
+/**
+ * `lotics ui link <component> [--remove]` — add or remove the `@lotics/ui`
+ * dev-link alias in the app's `vite.config.ts`, so edits to the monorepo's
+ * `packages/ui/src` go live (HMR) without a publish round-trip. `component` is
+ * advisory only — the alias is package-wide (one subpath regex covers every
+ * import); it's validated to exist under `packages/ui/src` so a typo fails here.
+ *
+ * Idempotent: linking twice is a no-op; `--remove` strips the one inserted
+ * entry and leaves the rest of `resolve.alias` intact.
+ */
+export function appUiLink(args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const viteConfigPath = path.join(projectDir, "vite.config.ts");
+    if (!fs.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 — `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.");
+    }
+    // Validate the named component exists in src so a typo fails loud (the alias
+    // itself stays package-wide — this is the advisory check the spec calls for).
+    const hasComponent = fs.existsSync(path.join(uiSrc, `${args.component}.tsx`)) ||
+        fs.existsSync(path.join(uiSrc, `${args.component}.ts`)) ||
+        fs.existsSync(path.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 = fs.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 — nothing to remove.");
+            return;
+        }
+        // Drop the whole alias line (the entry + its own line), leaving the rest of
+        // resolve.alias untouched.
+        const stripped = source.replace(new RegExp(`^\\s*\\{ find: ${escapeRegExp(UI_ALIAS_FIND_SOURCE)}.*$\\n?`, "m"), "");
+        fs.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)}\n      ${aliasEntry}${source.slice(insertAt)}`;
+    fs.writeFileSync(viteConfigPath, updated);
+    console.error(`Dev-linked @lotics/ui → ${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 → publish → `lotics ui link <component> --remove` + bump the app's dep.");
+}
+/** Escape a string for literal use inside a RegExp. */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}