@lotics/cli 0.88.0 → 0.88.1

package/dist/app_commands.js

@@ -1,1520 +0,0 @@
-/**
- * `lotics app *` subcommands — create / pull / deploy.
- *
- * Apps are user-owned npm projects. Source-of-truth during editing is the
- * local filesystem; the server stores deployed bundles (source.tar.gz + dist)
- * in R2 keyed per version. These commands are the only sanctioned lifecycle
- * surface — everything else (validate, logs, watch) folds into a flag on
- * deploy or lives in the web UI.
- *
- * Tarball handling shells out to the system `tar` command. CLI users are
- * developers; macOS/Linux/WSL all ship a working tar. Avoids adding a
- * runtime dep to the published @lotics/cli package.
- */
-import fs from "node:fs";
-import path from "node:path";
-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 { generatePackageAppFields } from "./generate_package_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
- * callers can fall back to a static pin rather than crashing `app create`.
- *
- * 1.5s timeout — npm registry is fast when reachable; the fallback is fine
- * the rare times it isn't, and we don't want to block scaffold on a hang.
- */
-export async function fetchLatestNpmVersion(packageName) {
-    try {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 1500);
-        const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
-            signal: controller.signal,
-            headers: { accept: "application/json" },
-        });
-        clearTimeout(timeout);
-        if (!response.ok)
-            return null;
-        const body = (await response.json());
-        return typeof body.version === "string" ? body.version : null;
-    }
-    catch {
-        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 include glob that actually loads the generated `.lotics/*.d.ts` companions.
- * A BARE `.lotics` entry loads NONE of them: TypeScript's include-glob walk skips
- * dot-directories, so `useQuery` / `useWorkflow` / `useAgentRun` fall back to their
- * untyped string overloads and every param / input / result silently becomes
- * `unknown`. The current starter emits the glob (`starter_template.ts`); apps
- * scaffolded before that fix shipped the bare form and need healing.
- */
-const LOTICS_INCLUDE_GLOB = ".lotics/**/*";
-/** The bare `.lotics` forms an older starter emitted — all skipped by the glob walk. */
-const STALE_LOTICS_INCLUDES = new Set([".lotics", "./.lotics", ".lotics/"]);
-/**
- * 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. */
-export function runTar(args, cwd) {
-    return new Promise((resolve, reject) => {
-        const proc = spawn("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
-        let stderr = "";
-        proc.stderr.on("data", (chunk) => {
-            stderr += chunk.toString();
-        });
-        proc.on("error", reject);
-        proc.on("exit", (code) => {
-            if (code === 0)
-                resolve();
-            else
-                reject(new Error(`tar ${args.join(" ")} failed with exit ${code}: ${stderr}`));
-        });
-    });
-}
-/** Run `npm` (run/install/etc.) inheriting stdio so the user sees progress. */
-export function runNpm(args, cwd) {
-    return new Promise((resolve, reject) => {
-        const proc = spawn("npm", args, { cwd, stdio: "inherit", env: ipv4ChildEnv(process.env) });
-        proc.on("error", reject);
-        proc.on("exit", (code) => {
-            if (code === 0)
-                resolve();
-            else
-                reject(new Error(`npm ${args.join(" ")} exited with code ${code}`));
-        });
-    });
-}
-function readAppMeta(projectDir) {
-    const pkgPath = path.join(projectDir, "package.json");
-    if (!fs.existsSync(pkgPath)) {
-        throw new Error(`No package.json found at ${projectDir}. Run 'lotics app create' first.`);
-    }
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-    if (!pkg.lotics?.app_id || !pkg.lotics.workspace_id) {
-        throw new Error(`package.json is missing the 'lotics' field with app_id and workspace_id. ` +
-            `Was this folder created with 'lotics app create'?`);
-    }
-    return {
-        app_id: pkg.lotics.app_id,
-        workspace_id: pkg.lotics.workspace_id,
-        current_version_id: pkg.lotics.current_version_id ?? null,
-        version_number: pkg.lotics.version_number ?? null,
-        workflows: pkg.lotics.workflows ?? {},
-        queries: pkg.lotics.queries ?? {},
-        agents: pkg.lotics.agents ?? {},
-        capabilities: pkg.lotics.capabilities,
-    };
-}
-function writeAppMeta(projectDir, meta) {
-    const pkgPath = path.join(projectDir, "package.json");
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-    pkg.lotics = meta;
-    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-}
-/**
- * Heal a pre-existing app's `tsconfig.json` so its generated types load and its
- * `npm run typecheck` stays honest. Idempotent, run on every pull / codegen /
- * deploy. Two things the current starter ships but an app SCAFFOLDED before those
- * releases (or with a hand-written tsconfig) can lack:
- *
- *  1. `include`: a bare `.lotics` is rewritten to the recursive `LOTICS_INCLUDE_GLOB`.
- *     A bare dot-dir is skipped by TypeScript's include-glob walk, so the codegen'd
- *     `.d.ts` never enter the program — every `useQuery`/`useWorkflow`/`useAgentRun`
- *     param and result silently falls back to `unknown`.
- *  2. `exclude`: the workflow-body globs — the bodies use the app's DOM lib (the
- *     server doesn't) and the per-alias ambient globals collide on `trigger`,
- *     poisoning typecheck. Checked separately by `lotics app workflow check`.
- *
- * A missing / unparseable tsconfig is a non-fatal warn (the caller still succeeds);
- * the author fixes the config.
- */
-export function ensureAppTsconfig(projectDir) {
-    const tsconfigPath = path.join(projectDir, "tsconfig.json");
-    if (!fs.existsSync(tsconfigPath)) {
-        console.error(`⚠ No tsconfig.json at ${projectDir} — could not ensure "include" has "${LOTICS_INCLUDE_GLOB}" ` +
-            `(a bare .lotics loads none of the generated types) or "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")}.`);
-        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)}) — ` +
-            `ensure "include" has "${LOTICS_INCLUDE_GLOB}" and "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} manually.`);
-        return;
-    }
-    if (!parsed || typeof parsed !== "object")
-        return;
-    const changes = [];
-    // 1. Heal a stale bare `.lotics` include so the generated `.d.ts` actually load
-    //    (a bare dot-dir is invisible to TypeScript's include-glob walk).
-    if (Array.isArray(parsed.include)) {
-        const inc = parsed.include.filter((e) => typeof e === "string");
-        if (inc.some((e) => STALE_LOTICS_INCLUDES.has(e))) {
-            const healed = inc.map((e) => (STALE_LOTICS_INCLUDES.has(e) ? LOTICS_INCLUDE_GLOB : e));
-            parsed.include = healed.filter((e, i) => healed.indexOf(e) === i); // dedupe if the glob was already present
-            changes.push(`rewrote a bare ".lotics" to "${LOTICS_INCLUDE_GLOB}" in "include" (a dot-dir loads zero generated types)`);
-        }
-    }
-    // 2. Ensure the workflow-body excludes. `exclude` is a TOP-LEVEL tsconfig field —
-    //    tsc ignores `compilerOptions.exclude`, so they must land at the top level.
-    const currentEx = Array.isArray(parsed.exclude)
-        ? parsed.exclude.filter((e) => typeof e === "string")
-        : [];
-    const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentEx.includes(g));
-    if (toAdd.length > 0) {
-        parsed.exclude = [...currentEx, ...toAdd];
-        changes.push(`added ${toAdd.join(", ")} to "exclude"`);
-    }
-    if (changes.length === 0)
-        return;
-    fs.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
-    console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
-}
-/**
- * Write the three `.lotics/app_{workflows,queries,agents}.d.ts` companions from
- * the manifest's maps, then heal the app's tsconfig so they actually load. Called
- * from `app create / pull / dev / deploy / codegen`, so the augmented `AppWorkflows`
- * / `AppQueries` / `AppAgents` types stay in sync with the manifest.
- *
- * The heal is at the write boundary on purpose: a `.d.ts` written but not loaded is
- * useless (a bare `.lotics` include is skipped by TypeScript's include-glob walk and
- * loads zero of them), so `ensureAppTsconfig` couples "wrote the types" with "the
- * program can see them" — no caller can do one without the other.
- */
-export function writeAppDts(projectDir, manifest) {
-    const dotLotics = path.join(projectDir, ".lotics");
-    fs.mkdirSync(dotLotics, { recursive: true });
-    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);
-    ensureAppTsconfig(projectDir);
-    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;
-}
-/**
- * Write the BINDING-resolved `.lotics/app_fields.ts` for a package installation
- * — the portable twin of `writeAppFields`. Instead of baking this workspace's
- * concrete ids, the module resolves `F`/`OPT`/`ROLE` from the installation's
- * live binding at load (`getAppBinding()`), so a published origin's source runs
- * unchanged in every workspace that installs the package. Returns the path.
- */
-function writeBindingAppFields(projectDir, binding) {
-    const dotLotics = path.join(projectDir, ".lotics");
-    fs.mkdirSync(dotLotics, { recursive: true });
-    const file = path.join(dotLotics, "app_fields.ts");
-    fs.writeFileSync(file, generatePackageAppFields(binding));
-    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 — **branched on whether the app is
- * a package installation** (`getApp().package_id` set): a **linked/published**
- * app emits the BINDING-resolved form (`F`/`OPT`/`ROLE` resolved from the live
- * binding at module load via `getAppBinding()`, so the source stays portable
- * across every install), a **bespoke** app emits the baked form (this
- * workspace's concrete `fld_…`/`opt_…` ids, from the live schema of the tables
- * its 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;
-    }
-    try {
-        // Branch on linked-ness: a package installation (its own published origin OR
-        // an install of another org's package) must ship PORTABLE source, so
-        // app_fields resolves F/OPT/ROLE from the live binding at module load; a
-        // bespoke app bakes this workspace's concrete ids. getApp is the authority —
-        // `package_id` is set iff the app is a package installation.
-        const app = await args.client.getApp(meta.app_id);
-        if (app.package_id) {
-            const binding = await args.client.appBinding(meta.app_id);
-            const fieldsPath = writeBindingAppFields(projectDir, binding);
-            const count = Object.keys(binding.fields).length;
-            console.error(`Regenerated ${fieldsPath} (binding form — ${count} field alias${count === 1 ? "" : "es"} resolved per-install)`);
-        }
-        else {
-            const tableIds = resolveCodegenTableIds(projectDir, meta.queries ?? {});
-            const tables = await args.client.getWorkspaceSchema(tableIds);
-            const fieldsPath = writeAppFields(projectDir, tables);
-            console.error(`Regenerated ${fieldsPath} (${tables.length} table${tables.length === 1 ? "" : "s"})`);
-        }
-    }
-    catch (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 regenerate .lotics/app_fields.ts (${err instanceof Error ? err.message : String(err)}). ` +
-            `Kept the existing file.`);
-    }
-    // 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
- * by `appPull` after the source archive lands on disk.
- *
- * Crucially, `workflows` is sourced from `app.workflows` (live DB state),
- * NOT from whatever the extracted archive's package.json contains. The
- * archive's embedded `lotics.workflows` is a frozen snapshot from deploy
- * time and would silently overwrite any agent-authored bindings made via
- * `set_app_workflow` since the last deploy. Exported for direct unit
- * testing — the rest of `appPull` involves shelling out to `tar`/`npm`,
- * which doesn't reward integration coverage.
- */
-export function stampPulledManifest(projectDir, args) {
-    writeAppMeta(projectDir, {
-        app_id: args.app_id,
-        workspace_id: args.workspace_id,
-        current_version_id: args.current_version_id,
-        version_number: args.version_number,
-        workflows: args.workflows,
-        queries: args.queries,
-        agents: args.agents,
-    });
-    writeAppDts(projectDir, { workflows: args.workflows, queries: args.queries, agents: args.agents });
-}
-async function downloadToFile(url, destPath) {
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw new Error(`Failed to download ${url}: ${response.status}`);
-    }
-    const buffer = Buffer.from(await response.arrayBuffer());
-    fs.writeFileSync(destPath, buffer);
-}
-/**
- * A filesystem-safe SINGLE directory segment from an app's free-form display
- * name, for the default create/pull target. App names may contain "/" (and
- * other path-hostile characters); used verbatim as a directory, a name like
- * "Nhập/Xuất Cont" splits into NESTED folders ("Nhập" → "Xuất Cont") — and a
- * deploy then packages that nested copy into the source archive, so each later
- * pull re-extracts and compounds it. Neutralize path separators + reserved
- * characters to one segment, keeping spaces and unicode so the folder stays
- * recognizable. An explicit `targetPath` still overrides this entirely.
- */
-export function appDirName(name) {
-    const cleaned = name
-        .replace(/[/\\]+/g, "-") // path separators — the core bug
-        .replace(/[<>:"|?*]/g, "") // other filesystem-reserved characters
-        .replace(/\s+/g, " ") // collapse whitespace runs
-        .trim()
-        .replace(/^[.\s-]+|[.\s-]+$/g, ""); // no leading/trailing dot/space/dash → never "."/".."/hidden/blank
-    return cleaned || "app";
-}
-/**
- * `lotics app create <name> [path]`
- *
- * Creates the app server-side, scaffolds a Vite+React+TS project locally
- * from the embedded starter template, runs `npm install` + `npm run build`,
- * then deploys the result as v1. After this returns, `lotics app deploy`
- * works end-to-end on the same directory.
- *
- * Why scaffold + deploy rather than pull-from-server-starter: the deploy
- * pipeline requires a built dist tree, and v1 doesn't run builds server-side.
- * Doing the build locally on first create keeps the platform infrastructure
- * minimal — the starter template is embedded in the CLI binary and bumps
- * with CLI releases. (Server-side build is the v2 path.)
- */
-export async function appCreate(client, args) {
-    const targetPath = path.resolve(args.targetPath ?? appDirName(args.name));
-    if (fs.existsSync(targetPath)) {
-        const entries = fs.readdirSync(targetPath);
-        if (entries.length > 0) {
-            throw new Error(`Target directory ${targetPath} is not empty.`);
-        }
-    }
-    fs.mkdirSync(targetPath, { recursive: true });
-    // Server-side row first — if this fails, no local files have been touched.
-    const app = await client.createApp({ name: args.name });
-    console.error(`Created app: ${app.name} (${app.id})`);
-    // Resolve latest versions in parallel; null falls back to the static pin
-    // baked into the starter template. Lookups time out at 1.5s so an offline
-    // create still succeeds (with the fallback) instead of hanging.
-    const [uiLatest, sdkLatest] = await Promise.all([
-        fetchLatestNpmVersion("@lotics/ui"),
-        fetchLatestNpmVersion("@lotics/app-sdk"),
-    ]);
-    // Scaffold the starter into the target directory.
-    const files = buildStarterTemplate({
-        app_name: args.name,
-        app_id: app.id,
-        workspace_id: app.workspace_id,
-        ui_version: uiLatest ? `^${uiLatest}` : undefined,
-        sdk_version: sdkLatest ? `^${sdkLatest}` : undefined,
-    });
-    for (const file of files) {
-        const fullPath = path.join(targetPath, file.path);
-        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-        fs.writeFileSync(fullPath, file.content);
-    }
-    console.error(`Scaffolded ${files.length} files into ${targetPath}`);
-    // Codegen pass for AppWorkflows typing. Empty manifest on first create —
-    // emits a base augmentation file so future deploys produce idempotent diffs
-    // rather than introducing a new tracked file later.
-    writeAppDts(targetPath, {});
-    console.error("Installing npm dependencies...");
-    await runNpm(["install"], targetPath);
-    console.error("Building initial version...");
-    await appDeploy(client, {
-        projectDir: targetPath,
-        message: "Initial version",
-    });
-    console.error(`\nReady. Next steps:`);
-    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
-    console.error(`  # edit src/App.tsx, then:`);
-    console.error(`  lotics app deploy`);
-}
-/**
- * `lotics app pull <app_id> [path]`
- *
- * Bootstraps a full local dev environment for an existing app:
- *   1. Fetch the current version's source archive from R2 (presigned URL).
- *   2. Extract into the target directory.
- *   3. Stamp package.json's `lotics` field with app_id + version metadata,
- *      and the live `apps.workflows` map from the server (NOT the manifest
- *      embedded in the source archive — that's a frozen snapshot from deploy
- *      time and would silently overwrite any agent-authored bindings made via
- *      `set_app_workflow` since the last deploy).
- *   4. Regenerate `.lotics/app_workflows.d.ts` from the live workflows so
- *      `useWorkflow<"alias">` is typed at pull time.
- *   5. Run `npm install`.
- *
- * 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.
- * The app_id comes from the local `package.json` manifest. The old
- * `<slug>.lotics.app` stops resolving once the change lands.
- */
-export async function appSetSubdomain(client, args) {
-    const meta = readAppMeta(process.cwd());
-    const result = await client.setAppSubdomain(meta.app_id, args.subdomain);
-    console.error(`Public address set: https://${result.public_subdomain}.lotics.app`);
-}
-/**
- * `lotics app rename <name>` — change the current app's display name (the
- * launcher/title shown in the workspace). The app_id comes from the local
- * `package.json` manifest. Wraps the `update_app` tool — the public address
- * (`lotics app subdomain`) and the code (`lotics app deploy`) are unchanged.
- */
-export async function appRename(client, args) {
-    const meta = readAppMeta(process.cwd());
-    const res = await client.execute("update_app", { app_id: meta.app_id, name: args.name });
-    if (res.error)
-        throw new Error(res.error);
-    console.error(`App renamed: "${args.name}" (${meta.app_id})`);
-}
-/**
- * `lotics app versions [app_id]` — print the app's deploy history, newest
- * first: version number, when, deployer, build status, and the `-m` message.
- * With no `app_id`, reads it from the local `package.json` manifest (run inside
- * the app dir); pass an explicit `app_id` to inspect any app without pulling it.
- * The currently served version is marked with `*`. Admin-only server-side.
- */
-export async function appVersions(client, args) {
-    const appId = args.app_id ?? readAppMeta(process.cwd()).app_id;
-    const { current_version_id, versions } = await client.listAppVersions(appId, {
-        limit: args.limit,
-    });
-    if (versions.length === 0) {
-        console.error(`No versions found for ${appId}.`);
-        return;
-    }
-    const fmtWhen = (iso) => {
-        const d = new Date(iso);
-        if (Number.isNaN(d.getTime()))
-            return iso;
-        const p = (n) => String(n).padStart(2, "0");
-        return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
-    };
-    const rows = versions.map((v) => ({
-        mark: v.id === current_version_id ? "*" : " ",
-        ver: `v${v.version}`,
-        when: fmtWhen(v.created_at),
-        by: v.created_by_name ?? v.created_by ?? "—",
-        status: v.build_status,
-        message: v.message ?? "",
-    }));
-    const colWidth = (key, header) => Math.max(header.length, ...rows.map((r) => r[key].length));
-    const wVer = colWidth("ver", "VER");
-    const wWhen = colWidth("when", "WHEN");
-    const wBy = colWidth("by", "DEPLOYER");
-    const wStatus = colWidth("status", "STATUS");
-    const pad = (s, n) => s.padEnd(n);
-    // Title → stderr (status); the table → stdout (data), so it stays pipeable.
-    console.error(`Deploy history — ${appId} (${versions.length} version${versions.length === 1 ? "" : "s"}, newest first; * = currently served)`);
-    console.log(`  ${pad("VER", wVer)}  ${pad("WHEN", wWhen)}  ${pad("DEPLOYER", wBy)}  ${pad("STATUS", wStatus)}  MESSAGE`);
-    for (const r of rows) {
-        console.log(`${r.mark} ${pad(r.ver, wVer)}  ${pad(r.when, wWhen)}  ${pad(r.by, wBy)}  ${pad(r.status, wStatus)}  ${r.message}`.trimEnd());
-    }
-}
-/**
- * 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) {
-        throw new Error(`App ${app.id} has no published version yet. Deploy from another machine first, or use 'lotics app create' to scaffold a new app.`);
-    }
-    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 ?? 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`);
-    console.error(`Downloading source archive...`);
-    await downloadToFile(sourceUrl, tmpFile);
-    try {
-        console.error(`Extracting to ${targetPath}...`);
-        await runTar(["-xzf", tmpFile, "-C", targetPath], targetPath);
-    }
-    finally {
-        if (fs.existsSync(tmpFile))
-            fs.unlinkSync(tmpFile);
-    }
-    // Workflows live on the App row, not in the source archive. The R2 archive
-    // is for code; pull the workflows live from `apps.workflows` so agent-
-    // authored bindings (via set_app_workflow) land in the local manifest. The
-    // archive's embedded `lotics.workflows` is a deploy-time snapshot and would
-    // be stale relative to anything authored since.
-    stampPulledManifest(targetPath, {
-        app_id: app.id,
-        workspace_id: app.workspace_id,
-        current_version_id: app.current_version_id,
-        version_number: version.version,
-        workflows: app.workflows ?? {},
-        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:`);
-    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
-    console.error(`  # edit src/App.tsx`);
-    console.error(`  lotics app deploy`);
-}
-/**
- * SDK calls that only work when the matching capability is declared in
- * `package.json#lotics.capabilities`. Used by the deploy pre-flight (GAP-29):
- * code that calls one of these but omits the capability silently 403s at
- * runtime, with no build or deploy error. Extend this map when a new capability
- * gate ships in `@lotics/app-sdk`.
- */
-const CAPABILITY_GATED_CALLS = {
-    comments: ["useComments", "createComment", "updateComment", "deleteComment"],
-};
-/**
- * Capabilities the source CALLS but the manifest does not DECLARE — each one
- * silently 403s at runtime (GAP-29). Pure over the concatenated source text so
- * it's unit-testable; the deploy warns (non-blocking) on a non-empty result.
- */
-export function undeclaredCapabilities(sourceText, declared) {
-    const used = [];
-    for (const [capability, calls] of Object.entries(CAPABILITY_GATED_CALLS)) {
-        const isCalled = calls.some((call) => new RegExp(`\\b${call}\\b`).test(sourceText));
-        if (isCalled && declared?.[capability] !== true)
-            used.push(capability);
-    }
-    return used;
-}
-/** Concatenated text of the app's `src/` files — the input to the capability pre-flight. */
-function readAppSourceText(projectDir) {
-    const srcDir = path.join(projectDir, "src");
-    if (!fs.existsSync(srcDir))
-        return "";
-    const parts = [];
-    const walk = (dir) => {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory())
-                walk(full);
-            else if (/\.(ts|tsx|js|jsx)$/.test(entry.name))
-                parts.push(fs.readFileSync(full, "utf8"));
-        }
-    };
-    walk(srcDir);
-    return parts.join("\n");
-}
-/**
- * `lotics app deploy [-m <message>]`
- *
- * Builds the project locally with `npm run build`, tars source + dist, and
- * uploads to the deploy endpoint. The endpoint validates structure, stores
- * both archives in R2, creates an app_versions row, and atomically advances
- * the app's current_version pointer.
- */
-export async function appDeploy(client, 
-// `message` is required — each deploy is a version row read back by
-// `lotics app versions`; a blank message loses the audit trail. The CLI
-// enforces non-empty at the dispatch; the type enforces it for every caller.
-args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const meta = readAppMeta(projectDir);
-    // Pre-flight (GAP-29): a capability the code calls but the manifest doesn't
-    // declare silently 403s at runtime with no other signal — warn before shipping
-    // it. Non-blocking, like the unbranded nudge below.
-    const undeclared = undeclaredCapabilities(readAppSourceText(projectDir), meta.capabilities);
-    if (undeclared.length > 0) {
-        const block = JSON.stringify(Object.fromEntries(undeclared.map((c) => [c, true])));
-        console.error(`\n⚠ This app calls capability-gated SDK functions for ${undeclared.join(", ")} but the ` +
-            `manifest doesn't declare ${undeclared.length > 1 ? "them" : "it"} — those calls will 403 at runtime.\n` +
-            `  Add to package.json#lotics.capabilities:  ${block}`);
-    }
-    // Regenerate AppWorkflows typing before the build picks up source. Keeps
-    // .lotics/app_workflows.d.ts in sync with the manifest's workflows map
-    // every time the developer ships.
-    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries, agents: meta.agents });
-    // Build locally so the server doesn't need a build sandbox in v1.
-    console.error("Building...");
-    await runNpm(["run", "build"], projectDir);
-    const distDir = path.join(projectDir, "dist");
-    if (!fs.existsSync(distDir)) {
-        throw new Error(`Build did not produce a dist/ directory in ${projectDir}. ` +
-            `Check that 'npm run build' is configured correctly (Vite/etc. defaults to dist/).`);
-    }
-    const tmpSource = path.join(tmpdir(), `lotics-source-${Date.now()}.tar.gz`);
-    const tmpDist = path.join(tmpdir(), `lotics-dist-${Date.now()}.tar.gz`);
-    try {
-        console.error("Packaging source...");
-        await runTar([
-            "-czf",
-            tmpSource,
-            "--exclude=node_modules",
-            "--exclude=dist",
-            "--exclude=.lotics",
-            "--exclude=*.tsbuildinfo",
-            "--exclude=.git",
-            ".",
-        ], projectDir);
-        console.error("Packaging dist...");
-        await runTar(["-czf", tmpDist, "-C", distDir, "."], projectDir);
-        console.error("Uploading...");
-        try {
-            const result = await client.deployAppVersion({
-                app_id: meta.app_id,
-                source_archive: fs.readFileSync(tmpSource),
-                dist_archive: fs.readFileSync(tmpDist),
-                prev_version_id: meta.current_version_id,
-                message: args.message,
-                // Sync apps.queries from the manifest. Server validates each query
-                // template (parseQueryNode, table access, param coverage).
-                queries: meta.queries ?? {},
-                // Capabilities are manifest-authoritative (like queries): always send,
-                // defaulting to `{}` when the manifest declares none — so deleting the
-                // `capabilities` block turns every capability OFF on the next deploy
-                // (fail-safe; the declaration is the grant).
-                capabilities: meta.capabilities ?? {},
-                // Workflow BINDINGS are NOT a deploy concern — set_app_workflow /
-                // remove_app_workflow own apps.workflows. But the alias KEYS of the
-                // manifest's `workflows` map ARE sent (never the bindings): they record
-                // which aliases this bundle declares, so remove_app_workflow can refuse
-                // to unbind an alias the served version still calls. Drop an alias from
-                // the manifest + redeploy to lift that guard before removing its binding.
-                workflow_aliases: Object.keys(meta.workflows ?? {}),
-            });
-            writeAppMeta(projectDir, {
-                ...meta,
-                current_version_id: result.version_id,
-                version_number: result.version_number,
-            });
-            console.error(`Deployed v${result.version_number} (${result.version_id})`);
-            console.error(`Bundle size: ${(result.bundle_size_bytes / 1024).toFixed(1)} KB`);
-            // One post-deploy getApp feeds both advisory nudges (branding, unbound
-            // aliases). Deploy already succeeded — a failed check must not mask that.
-            try {
-                const app = await client.getApp(meta.app_id);
-                warnIfUnbranded(app);
-                warnIfUnboundAliases(app, meta.workflows ?? {}, meta.agents ?? {});
-            }
-            catch (err) {
-                console.error(`(skipped post-deploy checks: ${err.message})`);
-            }
-        }
-        catch (err) {
-            const e = err;
-            if (e.code === "VERSION_CONFLICT") {
-                throw new Error(`Deploy conflict: server is at version ${e.current_version_id ?? "unknown"} ` +
-                    `but local copy is based on ${meta.current_version_id ?? "no version"}. ` +
-                    `Pull the latest before redeploying:\n  lotics app pull ${meta.app_id}`);
-            }
-            throw err;
-        }
-    }
-    finally {
-        if (fs.existsSync(tmpSource))
-            fs.unlinkSync(tmpSource);
-        if (fs.existsSync(tmpDist))
-            fs.unlinkSync(tmpDist);
-    }
-}
-/**
- * Non-blocking nudge after a successful deploy: an app with no icon/color shows a
- * generic tile in the launcher. Branding is set via `update_app` (the single
- * setter) — this only reminds; it never fails the deploy.
- */
-function warnIfUnbranded(app) {
-    const missing = [];
-    if (!app.icon)
-        missing.push("icon");
-    if (!app.theme?.color)
-        missing.push("color");
-    if (missing.length === 0)
-        return;
-    console.error(`\n⚠ This app has no ${missing.join(" or ")} set — it shows a generic tile in the launcher.\n` +
-        `  Set it:  lotics run update_app '{"app_id":"${app.id}","icon":"<lucide-name>","theme":{"color":"blue"}}'\n` +
-        `  Find an icon:  lotics run search_app_icons '{"query":"<word>"}'`);
-}
-/**
- * Non-blocking nudge after a successful deploy: catch manifest workflow/agent aliases
- * that are NOT bound on the server. Deploy ships code + queries only — it never binds
- * workflows/agents (`set_app_workflow` / `set_app_agent` own `apps.workflows`/`apps.agents`;
- * the manifest maps are a pulled reflection). So an alias hand-added to `lotics.workflows`
- * / `lotics.agents` (or bound then removed) compiles + deploys clean and only throws when
- * the app first calls `useWorkflow` / `useAgentRun`. Surface that divergence HERE — at
- * deploy time — instead of at the user's first click. Advisory only; never fails the deploy.
- */
-function warnIfUnboundAliases(app, declaredWorkflows, declaredAgents) {
-    const boundWorkflows = new Set(Object.keys(app.workflows ?? {}));
-    const boundAgents = new Set(Object.keys(app.agents ?? {}));
-    const unboundWorkflows = Object.keys(declaredWorkflows).filter((a) => !boundWorkflows.has(a));
-    const unboundAgents = Object.keys(declaredAgents).filter((a) => !boundAgents.has(a));
-    if (unboundWorkflows.length === 0 && unboundAgents.length === 0)
-        return;
-    const lines = [
-        "\n⚠ The manifest declares aliases that are NOT bound on the server. Deploy ships code +",
-        "  queries only — it does NOT bind workflows/agents, so the app will throw \"has no … alias\"",
-        "  the first time it calls them. Bind each one:",
-    ];
-    for (const alias of unboundWorkflows)
-        lines.push(`  • workflow "${alias}"  →  lotics app workflow set ${alias}`);
-    for (const alias of unboundAgents)
-        lines.push(`  • agent "${alias}"  →  bind with set_app_agent (lotics run set_app_agent …)`);
-    console.error(lines.join("\n"));
-}
-/**
- * `lotics app dev [path] [--port=5174] [--vite-port=5173]`
- *
- * Local dev mode for iframe apps. Spawns Vite + a postMessage RPC forwarder
- * that bridges the iframe's hooks (useQuery, useWorkflow) to api.lotics.ai
- * using the CLI's stored API key. Wrapper
- * iframe matches the production sandbox attributes exactly — null origin,
- * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
- *
- * Lifecycle: Vite as a child process (HMR over WebSocket), HTTP server on a
- * sibling port serving the wrapper HTML + the /_rpc dispatcher. SIGINT kills
- * both cleanly.
- */
-export async function appDev(client, args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const meta = readAppMeta(projectDir);
-    // Regenerate AppWorkflows typing before Vite spins up so the dev typecheck
-    // sees the current shape. Doesn't watch for manifest changes mid-session —
-    // re-running `lotics app dev` after editing the manifest is the loop.
-    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries, agents: meta.agents });
-    // Sanity: confirm the app exists in the workspace the CLI is auth'd into.
-    // Surfaces a clear error if the project's app_id has been deleted or the
-    // CLI is pointed at the wrong workspace.
-    const app = await client.getApp(meta.app_id);
-    const handle = await startDevServer({
-        projectDir,
-        app_id: meta.app_id,
-        app_name: app.name,
-        workspace_id: meta.workspace_id,
-        api_url: client.baseUrl,
-        port: args.port,
-        vitePort: args.vitePort,
-        client,
-        commentsEnabled: meta.capabilities?.comments,
-    });
-    await handle.ready;
-    const url = `http://localhost:${handle.port}`;
-    console.error(`\n  lotics app dev`);
-    console.error(`  app:       ${app.name} (${meta.app_id})`);
-    console.error(`  workspace: ${meta.workspace_id}`);
-    if (client.viewAsMemberId) {
-        console.error(`  view as:   ${client.viewAsMemberId} (is_current_member resolves to this member)`);
-    }
-    console.error(`  vite:      http://localhost:${handle.vitePort}/`);
-    console.error(`  open:      ${url}`);
-    console.error(`  rpc:       ${client.baseUrl} (via Bearer API key)\n`);
-    console.error(`  Ctrl-C to stop.\n`);
-    openBrowser(url);
-    // Block until SIGINT.
-    await new Promise((resolve) => {
-        const onSig = () => {
-            process.off("SIGINT", onSig);
-            process.off("SIGTERM", onSig);
-            resolve();
-        };
-        process.on("SIGINT", onSig);
-        process.on("SIGTERM", onSig);
-    });
-    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 query set <alias>` — push `package.json#lotics.queries.<alias>` to
- * `apps.queries` through `set_app_query`, WITHOUT a deploy. The deploy-free inner
- * loop for named queries, parallel to `lotics app workflow set` for workflows.
- *
- * The declaration (`{ ast, params? }`) is read from the manifest — the same map
- * `useQuery` codegen reads and `lotics app deploy` syncs authoritatively. The
- * server validates it exactly as a deploy does (alias identifier, workspace-only
- * tables, resolvable fields, declared params). Because `apps.queries` is
- * manifest-authoritative, the next `lotics app deploy` overwrites this from the
- * manifest — so keep the manifest as the source of truth; this only skips the
- * build/upload round-trip while iterating. Errors (unbound alias, validation
- * failure) print to stderr and exit non-zero.
- */
-export async function appQuerySet(client, args) {
-    const projectDir = process.cwd();
-    const meta = readAppMeta(projectDir);
-    const declaration = meta.queries?.[args.alias];
-    if (!declaration) {
-        console.error(`No query "${args.alias}" in package.json#lotics.queries. ` +
-            `Declare it there (alias → { ast, params? }) first.`);
-        process.exit(1);
-    }
-    const res = await client.setAppQuery(meta.app_id, args.alias, declaration);
-    if (res.error) {
-        console.error(`Failed to set query "${args.alias}": ${res.error}`);
-        process.exit(1);
-    }
-    console.error(`Set query "${args.alias}" on ${meta.app_id}. ` +
-        `(apps.queries is manifest-authoritative — the next 'lotics app deploy' re-syncs it.)`);
-}
-/**
- * `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(", ")})` : ""));
-    // This command writes workflow BODIES, not the `.d.ts` — so it doesn't reach
-    // `writeAppDts`'s heal. Heal here so the bodies land excluded and a stale
-    // `.lotics` include doesn't leave the app's other generated types dead.
-    ensureAppTsconfig(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.`);
-    }
-    // Resolve packages/ui/src. An explicit --ui-src / LOTICS_UI_SRC wins — that's how
-    // an EXTERNAL app (one that consumes @lotics/ui from npm, with no monorepo above
-    // it) links the local kit; otherwise walk up for a monorepo checkout.
-    const explicit = args.uiSrc ?? process.env.LOTICS_UI_SRC;
-    const uiSrc = explicit ? path.resolve(explicit) : findUiSrcDir(projectDir);
-    if (!uiSrc || !fs.existsSync(uiSrc) || !fs.statSync(uiSrc).isDirectory()) {
-        throw new Error(explicit
-            ? `--ui-src / LOTICS_UI_SRC points at '${explicit}', which is not a directory. ` +
-                `Pass the absolute path to the monorepo's packages/ui/src.`
-            : "Cannot find packages/ui/src by walking up from this directory. For an EXTERNAL app " +
-                "(consuming @lotics/ui from npm), pass --ui-src=<abs path to packages/ui/src> or set " +
-                "LOTICS_UI_SRC; inside a monorepo checkout it is found automatically.");
-    }
-    // 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.");
-    // The app's tsc still resolves @lotics/ui from node_modules (the published .d.ts) —
-    // the kit `src` can't be typechecked in an app because it's RN-Web (uses
-    // react-native-web types the app resolves as base react-native). Typecheck the kit
-    // in packages/ui; the finalize publish restores the app's own typecheck.
-    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, "\\$&");
-}