@lotics/cli 0.57.0 → 0.62.0

package/dist/app_commands.js

@@ -17,9 +17,13 @@ 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";
+import { loadProjectTypescript, checkWorkflowBodies, } from "./app_workflow_check.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 +50,202 @@ 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 two globs the MAIN tsconfig must `exclude`: the editable workflow bodies AND
+ * their per-alias ambient globals. The bodies use the app's DOM lib (the server
+ * doesn't) and each globals file declares its own ambient `trigger` — loading 22
+ * of them into the app's program collides those declarations and poisons
+ * `npm run typecheck`. Bodies are type-checked separately by
+ * `lotics app workflow check` (one isolated program per alias). Always written
+ * with `/` separators — tsconfig globs are POSIX even on Windows.
+ */
+const WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".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 `lotics app workflow check`
+ * 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 check + push with:\n` +
+        `//   lotics app workflow check ${alias}\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. `lotics app workflow check` compiles
+        // each body in its OWN isolated program (just this body + its globals), so the
+        // `__workflow` function never collides across bodies; the marker is retained as
+        // stable CLI bookkeeping (stripWorkflowHeader anchors on it) and is stripped on
+        // `set`, so it has no effect on what the server verifies.
+        `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 +266,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)
@@ -103,6 +303,47 @@ function writeAppMeta(projectDir, meta) {
     pkg.lotics = meta;
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
+/**
+ * Add the workflow-body globs to the main `tsconfig.json`'s `exclude` if missing,
+ * preserving every other exclude. The starter ships these excludes already, but
+ * an app SCAFFOLDED before this CLI release (or one with a hand-written tsconfig)
+ * doesn't — and pulling bodies into it would otherwise break its
+ * `npm run typecheck`: the bodies pull the app's DOM lib (the server doesn't) and
+ * the per-alias ambient globals collide on `trigger`. Idempotent — a second pull
+ * is a no-op. Warns exactly what it added. A missing/unparseable tsconfig is a
+ * non-fatal warn (the pull itself still succeeds); the author fixes the config.
+ */
+export function ensureWorkflowTsconfigExcludes(projectDir) {
+    const tsconfigPath = path.join(projectDir, "tsconfig.json");
+    if (!fs.existsSync(tsconfigPath)) {
+        console.error(`⚠ No tsconfig.json at ${projectDir} — could not ensure ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} are excluded. ` +
+            `Add them to your tsconfig's "exclude" so npm run typecheck skips the workflow bodies.`);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(tsconfigPath, "utf-8"));
+    }
+    catch (err) {
+        console.error(`⚠ Could not parse tsconfig.json (${err instanceof Error ? err.message : String(err)}) — ` +
+            `add ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} to its "exclude" manually so npm run typecheck skips the workflow bodies.`);
+        return;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return;
+    // `exclude` is a TOP-LEVEL tsconfig field — tsc ignores `compilerOptions.exclude`,
+    // so the workflow globs must land at the top level or `npm run typecheck` still
+    // loads the bodies + their colliding per-alias globals.
+    const current = Array.isArray(parsed.exclude) ? parsed.exclude : [];
+    const currentStrings = current.filter((e) => typeof e === "string");
+    const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentStrings.includes(g));
+    if (toAdd.length === 0)
+        return;
+    parsed.exclude = [...currentStrings, ...toAdd];
+    fs.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
+    console.error(`Patched tsconfig.json: added ${toAdd.join(", ")} to "exclude" so npm run typecheck skips the workflow bodies ` +
+        `(check them with: lotics app workflow check).`);
+}
 /**
  * Write `.lotics/app_workflows.d.ts` + `.lotics/app_queries.d.ts` from the
  * manifest's `workflows` / `queries` maps. Called from `app create / pull /
@@ -113,9 +354,125 @@ 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 ?? {}));
+    // Keep the main tsconfig excluding the workflow-body globs (idempotent) so
+    // npm run typecheck never loads the bodies or their colliding per-alias globals.
+    if (Object.keys(meta.workflows ?? {}).length > 0)
+        ensureWorkflowTsconfigExcludes(projectDir);
+}
+/**
+ * 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 +602,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.
@@ -271,6 +630,31 @@ export async function appRename(client, args) {
         throw new Error(res.error);
     console.error(`App renamed: "${args.name}" (${meta.app_id})`);
 }
+/**
+ * Where `lotics app pull <app_id>` lands when given NO explicit path. If the cwd
+ * IS already this app's own project (its manifest `app_id` matches), refresh in
+ * place — the documented `cd <app> && lotics app pull` flow. Otherwise a fresh
+ * clone goes to an `appDirName(name)` subdir. Without this, pulling from inside
+ * the app dropped a stray `./<name>/` subdir instead of refreshing the project.
+ */
+export function defaultPullTarget(appId, appName) {
+    const cwdPkgPath = path.join(process.cwd(), "package.json");
+    if (fs.existsSync(cwdPkgPath)) {
+        let pkg = null;
+        try {
+            pkg = JSON.parse(fs.readFileSync(cwdPkgPath, "utf-8"));
+        }
+        catch (err) {
+            // An unparseable cwd package.json means we can't confirm this is the app's
+            // own project — warn and fall through to a fresh clone rather than crash.
+            console.error(`⚠ Could not parse ${cwdPkgPath} (${err instanceof Error ? err.message : String(err)}) — ` +
+                `pulling into a fresh ${appDirName(appName)}/ subdir.`);
+        }
+        if (pkg?.lotics?.app_id === appId)
+            return process.cwd();
+    }
+    return appDirName(appName);
+}
 export async function appPull(client, args) {
     const app = await client.getApp(args.app_id);
     if (!app.current_version_id) {
@@ -278,7 +662,7 @@ export async function appPull(client, args) {
     }
     const version = await client.getAppVersion(app.id, app.current_version_id);
     const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
-    const targetPath = path.resolve(args.targetPath ?? appDirName(app.name));
+    const targetPath = path.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
     fs.mkdirSync(targetPath, { recursive: true });
     // Download to a temp file because `tar -xz` reads from a real path.
     const tmpFile = path.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
@@ -306,6 +690,21 @@ 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(", ")})`);
+        }
+        // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
+        // bodies into it would break its npm run typecheck. Patch it idempotently.
+        ensureWorkflowTsconfigExcludes(targetPath);
+    }
     console.error(`Installing npm dependencies...`);
     await runNpm(["install"], targetPath);
     console.error(`\nReady. Next steps:`);
@@ -535,3 +934,400 @@ 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(", ")})` : ""));
+    // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
+    // bodies into it would break its npm run typecheck. Patch it idempotently.
+    ensureWorkflowTsconfigExcludes(projectDir);
+}
+/**
+ * `lotics app workflow check [alias]` — local TypeScript type check of the
+ * editable workflow bodies, ONE isolated program per bound alias (GAP-59 fix).
+ *
+ * The dedicated `tsconfig.workflows.json` that GAP-59 first shipped compiled ALL
+ * aliases' bodies + per-alias ambient globals into a SINGLE program, so the N
+ * `declare const trigger: AppWorkflowTrigger` declarations (each with THAT
+ * alias's `app_workflow.inputs`) collided — tsc resolved one and every body
+ * checked `trigger.app_workflow.inputs` against the wrong alias. This command
+ * replaces that config: it builds a separate `ts.Program` per alias from exactly
+ * that alias's `{body, globals}` pair (mirroring the SERVER, which verifies one
+ * body at a time), so the ambient `trigger` is unambiguous and the verdict
+ * matches set-time. All aliases run in ONE process.
+ *
+ * `[alias]` checks one alias; omitted, checks every bound alias that has a body
+ * file. Exits non-zero if ANY alias has a type error. A bound alias with no body
+ * file yet (never pulled) is warned and skipped; an alias missing its globals
+ * file is an error (the body can't be checked without its types).
+ */
+export async function appWorkflowCheck(args) {
+    const projectDir = process.cwd();
+    const meta = readAppMeta(projectDir);
+    const bound = Object.keys(meta.workflows ?? {});
+    let aliases;
+    if (args.alias) {
+        if (!bound.includes(args.alias)) {
+            console.error(`No workflow "${args.alias}" in package.json#lotics.workflows. ` +
+                `Bound aliases: ${bound.length > 0 ? bound.join(", ") : "(none)"}.`);
+            process.exit(1);
+        }
+        aliases = [args.alias];
+    }
+    else {
+        aliases = bound;
+    }
+    if (aliases.length === 0) {
+        console.error(`App ${meta.app_id} has no bound workflows to check.`);
+        return;
+    }
+    // Each alias contributes its OWN body + globals. A bound alias never pulled has
+    // no body file — warn + skip (not an error; the author hasn't pulled it). A
+    // body with no globals can't be checked — that IS an error (run a pull).
+    const toCheck = [];
+    for (const alias of aliases) {
+        const bodyPath = workflowFilePath(projectDir, alias);
+        const globalsPath = workflowGlobalsPath(projectDir, alias);
+        if (!fs.existsSync(bodyPath)) {
+            console.error(`⚠ Skipped "${alias}" — no body at ${path.relative(projectDir, bodyPath)}. ` +
+                `Run 'lotics app workflow pull' to write it.`);
+            continue;
+        }
+        if (!fs.existsSync(globalsPath)) {
+            console.error(`Cannot check "${alias}" — missing types at ${path.relative(projectDir, globalsPath)}. ` +
+                `Run 'lotics app workflow pull' (or 'lotics app codegen') to fetch them.`);
+            process.exit(1);
+        }
+        toCheck.push({ alias, input: { bodyPath, globalsPath } });
+    }
+    if (toCheck.length === 0) {
+        console.error("No workflow bodies to check (every bound alias was skipped).");
+        return;
+    }
+    const tsApi = await loadProjectTypescript(projectDir);
+    const results = checkWorkflowBodies(tsApi, toCheck);
+    printWorkflowCheckResults(projectDir, results);
+    const failed = results.filter((r) => r.issues.length > 0);
+    if (failed.length > 0)
+        process.exit(1);
+}
+/**
+ * Render the per-alias verdict to stderr (status) — a clean line per passing
+ * alias, then `<file>:<line>:<col> - TS####: message` per error, grouped by
+ * alias, with a final tally. Lines point at the author's body (the envelope
+ * offset already removed in `checkOneWorkflowBody`).
+ */
+function printWorkflowCheckResults(projectDir, results) {
+    let totalErrors = 0;
+    for (const r of results) {
+        const rel = path.relative(projectDir, r.bodyPath);
+        if (r.issues.length === 0) {
+            console.error(`✓ ${r.alias} (${rel}) — no type errors`);
+            continue;
+        }
+        totalErrors += r.issues.length;
+        console.error(`✗ ${r.alias} (${rel}) — ${r.issues.length} error${r.issues.length === 1 ? "" : "s"}:`);
+        for (const issue of r.issues) {
+            // TS multi-line messages indent every continuation under the location line.
+            const [first, ...rest] = issue.message.split("\n");
+            console.error(`    ${rel}:${issue.line}:${issue.col} - ${issue.code}: ${first}`);
+            for (const line of rest)
+                console.error(`      ${line}`);
+        }
+    }
+    const passed = results.length - results.filter((r) => r.issues.length > 0).length;
+    console.error(totalErrors === 0
+        ? results.length === 1
+            ? `\nThe workflow body type-checks clean.`
+            : `\nAll ${results.length} workflow bodies type-check clean.`
+        : `\n${totalErrors} error${totalErrors === 1 ? "" : "s"} across ${results.length - passed} of ${results.length} ${results.length === 1 ? "body" : "bodies"}.`);
+}
+/**
+ * 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, "\\$&");
+}