@lotics/cli 0.88.0 → 0.88.1

package/dist/app_commands.test.js

@@ -1,898 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import fs from "node:fs";
-import path from "node:path";
-import { tmpdir } from "node:os";
-import { stampPulledManifest, undeclaredCapabilities, appDirName, defaultPullTarget, ensureAppTsconfig, appCodegen, appUiLink, appVersions, appWorkflowSet, appWorkflowPull, appExecuteWorkflow, writeWorkflowFile, writeWorkflowGlobals, stripWorkflowHeader, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } from "./app_commands.js";
-/**
- * `appPull` reads workflows from the live App row (server response), NOT from
- * the manifest embedded in the extracted source archive. The frozen archive
- * snapshot would silently overwrite any agent-authored bindings (via
- * `set_app_workflow`) that landed on the App row after the last deploy.
- *
- * Tests `stampPulledManifest` directly — the part of `appPull` that decides
- * which workflows source wins. The rest of `appPull` shells out to
- * `tar`/`npm`, which is integration territory.
- */
-describe("stampPulledManifest", () => {
-    let workDir;
-    beforeEach(() => {
-        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-sdk-test-"));
-    });
-    afterEach(() => {
-        fs.rmSync(workDir, { recursive: true, force: true });
-    });
-    function writeExtractedPackageJson(workflows) {
-        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({
-            name: "sample-app",
-            lotics: {
-                // Stale archived map — must NOT survive the stamp.
-                app_id: "app_old",
-                workspace_id: "wks_old",
-                current_version_id: "apv_old",
-                version_number: 1,
-                workflows,
-            },
-        }, null, 2));
-    }
-    function readStampedManifest() {
-        const pkg = JSON.parse(fs.readFileSync(path.join(workDir, "package.json"), "utf-8"));
-        return pkg.lotics;
-    }
-    it("writes workflows from the live argument, overriding the archive-embedded manifest", () => {
-        // Simulate the source archive's embedded manifest containing a stale
-        // alias — the kind of thing that ships when an agent-authored workflow
-        // hasn't yet been propagated to a developer's local checkout.
-        writeExtractedPackageJson({
-            stale_archive_alias: { workflow_id: "wfl_archived_at_deploy_time" },
-        });
-        // Live state from the server — what `client.getApp()` returns. This
-        // includes the agent-authored alias added since the last deploy.
-        stampPulledManifest(workDir, {
-            app_id: "app_live",
-            workspace_id: "wks_live",
-            current_version_id: "apv_live",
-            version_number: 7,
-            workflows: {
-                agent_authored: { workflow_id: "wfl_authored_by_agent" },
-                renamed: { workflow_id: "wfl_renamed_on_server" },
-            },
-            queries: {},
-            agents: {},
-        });
-        const stamped = readStampedManifest();
-        expect(stamped.app_id).toBe("app_live");
-        expect(stamped.workspace_id).toBe("wks_live");
-        expect(stamped.current_version_id).toBe("apv_live");
-        expect(stamped.version_number).toBe(7);
-        // Only the live workflows are present. The archive's stale_archive_alias
-        // does not survive — proving we're not reading from the extracted manifest.
-        expect(stamped.workflows).toEqual({
-            agent_authored: { workflow_id: "wfl_authored_by_agent" },
-            renamed: { workflow_id: "wfl_renamed_on_server" },
-        });
-        expect(stamped.workflows).not.toHaveProperty("stale_archive_alias");
-    });
-    it("clears the local workflows when the server has none", () => {
-        writeExtractedPackageJson({
-            stale_archive_alias: { workflow_id: "wfl_should_disappear" },
-        });
-        stampPulledManifest(workDir, {
-            app_id: "app_x",
-            workspace_id: "wks_x",
-            current_version_id: "apv_x",
-            version_number: 2,
-            workflows: {},
-            queries: {},
-            agents: {},
-        });
-        const stamped = readStampedManifest();
-        expect(stamped.workflows).toEqual({});
-    });
-    it("emits .lotics/app_workflows.d.ts from the live workflows", () => {
-        writeExtractedPackageJson({});
-        stampPulledManifest(workDir, {
-            app_id: "app_y",
-            workspace_id: "wks_y",
-            current_version_id: "apv_y",
-            version_number: 3,
-            workflows: {
-                only_live: { workflow_id: "wfl_only_live" },
-            },
-            queries: {},
-            agents: {},
-        });
-        const dtsPath = path.join(workDir, ".lotics", "app_workflows.d.ts");
-        expect(fs.existsSync(dtsPath)).toBe(true);
-        const dts = fs.readFileSync(dtsPath, "utf-8");
-        expect(dts).toContain("only_live");
-    });
-});
-/**
- * The deploy pre-flight that catches GAP-29: source that CALLS a capability-gated
- * SDK function while the manifest omits that capability would silently 403 at
- * runtime. `undeclaredCapabilities` is the pure decision the warning is built on.
- */
-describe("undeclaredCapabilities", () => {
-    const commentsSource = `import { useComments } from "@lotics/app-sdk";\nconst { available } = useComments({ record_id });`;
-    it("flags a capability that's called but not declared", () => {
-        expect(undeclaredCapabilities(commentsSource, undefined)).toEqual(["comments"]);
-        expect(undeclaredCapabilities(commentsSource, {})).toEqual(["comments"]);
-        expect(undeclaredCapabilities(commentsSource, { comments: false })).toEqual(["comments"]);
-    });
-    it("stays quiet when the called capability is declared", () => {
-        expect(undeclaredCapabilities(commentsSource, { comments: true })).toEqual([]);
-    });
-    it("stays quiet when the capability isn't used at all", () => {
-        expect(undeclaredCapabilities(`const x = createInvoice();`, undefined)).toEqual([]);
-        expect(undeclaredCapabilities("", { comments: true })).toEqual([]);
-    });
-    it("matches on whole identifiers, not substrings", () => {
-        // `myUseCommentsHelper` is not a call to the gated `useComments`.
-        expect(undeclaredCapabilities(`const x = myUseCommentsHelper();`, undefined)).toEqual([]);
-    });
-    it("detects any of a capability's gated calls", () => {
-        expect(undeclaredCapabilities(`await createComment({ body });`, {})).toEqual(["comments"]);
-        expect(undeclaredCapabilities(`await deleteComment(id);`, {})).toEqual(["comments"]);
-    });
-});
-describe("appDirName", () => {
-    it("collapses a slash in the name to a single segment (the create/pull nesting bug)", () => {
-        // A "/" in the name used to split the create/pull target into nested folders
-        // ("Nhập" → "Xuất Cont") and compound on each pull.
-        expect(appDirName("Nhập/Xuất Cont")).toBe("Nhập-Xuất Cont");
-        expect(appDirName("a/b/c")).toBe("a-b-c");
-        expect(appDirName("a\\b")).toBe("a-b");
-    });
-    it("leaves an ordinary name untouched (no regression for the common case)", () => {
-        expect(appDirName("Sales Tracker")).toBe("Sales Tracker");
-        expect(appDirName("crm")).toBe("crm");
-    });
-    it("strips reserved characters and collapses whitespace", () => {
-        expect(appDirName('Report: "Q1" <draft>')).toBe("Report Q1 draft");
-    });
-    it("never yields a traversal, hidden, or empty directory", () => {
-        expect(appDirName("../etc")).toBe("etc"); // "/"→"-", then leading dot/dash run stripped
-        expect(appDirName(".hidden")).toBe("hidden");
-        expect(appDirName("   ")).toBe("app");
-        expect(appDirName("///")).toBe("app"); // separators → "-", a dir of only "-" falls back
-    });
-});
-/**
- * `appCodegen` (no client) always regenerates the `.lotics/*.d.ts` companions
- * from the manifest. It throws the clear not-an-app error when there's no
- * manifest, and produces byte-identical output across runs (idempotent).
- */
-describe("appCodegen (.d.ts-only path)", () => {
-    let workDir;
-    beforeEach(() => {
-        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-codegen-test-"));
-        vi.spyOn(console, "error").mockImplementation(() => undefined);
-    });
-    afterEach(() => {
-        fs.rmSync(workDir, { recursive: true, force: true });
-        vi.restoreAllMocks();
-    });
-    function writeManifest() {
-        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({
-            name: "sample-app",
-            lotics: {
-                app_id: "app_1",
-                workspace_id: "wks_1",
-                current_version_id: "apv_1",
-                version_number: 1,
-                workflows: { issue: { workflow_id: "wfl_x" } },
-                queries: { all: { ast: { kind: "from_table", table_id: "tbl_1" } } },
-            },
-        }, null, 2));
-    }
-    it("writes the three .d.ts companions from the manifest", async () => {
-        writeManifest();
-        await appCodegen({ projectDir: workDir });
-        const dir = path.join(workDir, ".lotics");
-        expect(fs.existsSync(path.join(dir, "app_workflows.d.ts"))).toBe(true);
-        expect(fs.existsSync(path.join(dir, "app_queries.d.ts"))).toBe(true);
-        expect(fs.existsSync(path.join(dir, "app_agents.d.ts"))).toBe(true);
-        expect(fs.readFileSync(path.join(dir, "app_workflows.d.ts"), "utf-8")).toContain("issue");
-    });
-    it("throws the not-an-app error when there's no manifest", async () => {
-        await expect(appCodegen({ projectDir: workDir })).rejects.toThrow(/package\.json/);
-    });
-    it("produces byte-identical output across runs (idempotent)", async () => {
-        writeManifest();
-        await appCodegen({ projectDir: workDir });
-        const first = fs.readFileSync(path.join(workDir, ".lotics", "app_queries.d.ts"));
-        await appCodegen({ projectDir: workDir });
-        const second = fs.readFileSync(path.join(workDir, ".lotics", "app_queries.d.ts"));
-        expect(second.equals(first)).toBe(true);
-    });
-});
-/**
- * `appCodegen` (with a client) branches the runtime `app_fields.ts` on whether
- * the app is a package installation: a LINKED app (`getApp().package_id` set)
- * emits the binding-resolved form (portable — resolves through `getAppBinding()`
- * at load); a BESPOKE app bakes this workspace's concrete ids from the schema.
- */
-describe("appCodegen app_fields branch (linked vs bespoke)", () => {
-    let workDir;
-    beforeEach(() => {
-        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-codegen-branch-"));
-        vi.spyOn(console, "error").mockImplementation(() => undefined);
-    });
-    afterEach(() => {
-        fs.rmSync(workDir, { recursive: true, force: true });
-        vi.restoreAllMocks();
-    });
-    function writeManifest() {
-        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({
-            name: "sample-app",
-            lotics: {
-                app_id: "app_1",
-                workspace_id: "wks_1",
-                current_version_id: "apv_1",
-                version_number: 1,
-                queries: { all: { ast: { kind: "from_table", table_id: "tbl_1" } } },
-            },
-        }, null, 2));
-    }
-    const readFields = () => fs.readFileSync(path.join(workDir, ".lotics", "app_fields.ts"), "utf-8");
-    it("emits the BAKED form for a bespoke app (no package_id)", async () => {
-        writeManifest();
-        const client = {
-            getApp: async () => ({ package_id: null }),
-            getWorkspaceSchema: async () => [
-                { id: "tbl_1", name: "Tasks", fields: [{ id: "fld_title", name: "Title" }] },
-            ],
-        };
-        await appCodegen({ projectDir: workDir, client });
-        const src = readFields();
-        expect(src).not.toContain("getAppBinding");
-        // Concrete id baked into the value position.
-        expect(src).toContain('"fld_title"');
-        expect(src).toMatch(/TASKS: \{/);
-    });
-    it("emits the BINDING form for a linked/published app (package_id set)", async () => {
-        writeManifest();
-        const client = {
-            getApp: async () => ({ package_id: "apg_1" }),
-            appBinding: async () => ({
-                fields: { "tasks.title": "fld_title" },
-                options: {},
-                roles: { approver: "grp_x" },
-            }),
-            // Must NOT be consulted on the linked branch — a call would fail the type
-            // shape it returns, and the assertions below prove the baked path is dead.
-            getWorkspaceSchema: async () => {
-                throw new Error("getWorkspaceSchema must not run for a linked app");
-            },
-        };
-        await appCodegen({ projectDir: workDir, client });
-        const src = readFields();
-        expect(src).toContain('import { getAppBinding } from "@lotics/app-sdk";');
-        expect(src).toContain("const binding = await getAppBinding();");
-        expect(src).toContain('title: bound(binding.fields, "tasks.title", "field")');
-        expect(src).toContain('approver: bound(binding.roles, "approver", "role")');
-        // No concrete id baked into any value position.
-        expect(src).not.toMatch(/"(fld|opt|tbl|grp)_/);
-    });
-});
-/**
- * `appUiLink` edits the app's vite.config.ts resolve.alias to dev-link
- * @lotics/ui at packages/ui/src — auto-found in a monorepo checkout, or given
- * explicitly via --ui-src for an external app. It validates the src + component,
- * fails loud when neither resolves, and insert/remove is idempotent.
- */
-describe("appUiLink", () => {
-    let root;
-    let appDir;
-    let uiSrc;
-    beforeEach(() => {
-        vi.spyOn(console, "error").mockImplementation(() => undefined);
-        // A fake monorepo: <root>/packages/ui/src/<component>, <root>/apps/myapp.
-        root = fs.mkdtempSync(path.join(tmpdir(), "lotics-uilink-test-"));
-        uiSrc = path.join(root, "packages", "ui", "src");
-        fs.mkdirSync(uiSrc, { recursive: true });
-        fs.writeFileSync(path.join(uiSrc, "card.tsx"), "export const Card = () => null;");
-        appDir = path.join(root, "apps", "myapp");
-        fs.mkdirSync(appDir, { recursive: true });
-        fs.writeFileSync(path.join(appDir, "vite.config.ts"), [
-            "export default {",
-            "  resolve: {",
-            "    alias: [",
-            '      { find: "react-native", replacement: "react-native-web" },',
-            "    ],",
-            "  },",
-            "};",
-            "",
-        ].join("\n"));
-    });
-    afterEach(() => {
-        fs.rmSync(root, { recursive: true, force: true });
-        vi.restoreAllMocks();
-    });
-    const config = () => fs.readFileSync(path.join(appDir, "vite.config.ts"), "utf-8");
-    it("inserts the dev-link alias pointing at packages/ui/src", () => {
-        appUiLink({ projectDir: appDir, component: "card" });
-        const out = config();
-        expect(out).toContain(String.raw `/^@lotics\/ui\/(.+)$/`);
-        expect(out).toContain(uiSrc);
-        // The pre-existing alias is preserved.
-        expect(out).toContain("react-native-web");
-    });
-    it("is idempotent — linking twice does not duplicate the alias", () => {
-        appUiLink({ projectDir: appDir, component: "card" });
-        const once = config();
-        appUiLink({ projectDir: appDir, component: "card" });
-        expect(config()).toBe(once);
-    });
-    it("removes the alias and leaves the rest of resolve.alias intact", () => {
-        appUiLink({ projectDir: appDir, component: "card" });
-        appUiLink({ projectDir: appDir, component: "card", remove: true });
-        const out = config();
-        expect(out).not.toContain(String.raw `@lotics\/ui`);
-        expect(out).toContain("react-native-web");
-    });
-    it("fails loud when the named component does not exist in packages/ui/src", () => {
-        expect(() => appUiLink({ projectDir: appDir, component: "nonexistent" })).toThrow(/nonexistent/);
-    });
-    it("fails loud when there is no packages/ui/src and no --ui-src override", () => {
-        const lonely = fs.mkdtempSync(path.join(tmpdir(), "lotics-lonely-app-"));
-        fs.writeFileSync(path.join(lonely, "vite.config.ts"), "export default { resolve: { alias: [] } };");
-        try {
-            expect(() => appUiLink({ projectDir: lonely, component: "card" })).toThrow(/--ui-src/);
-        }
-        finally {
-            fs.rmSync(lonely, { recursive: true, force: true });
-        }
-    });
-    it("links an EXTERNAL app (no monorepo above) via an explicit --ui-src", () => {
-        const ext = fs.mkdtempSync(path.join(tmpdir(), "lotics-external-app-"));
-        fs.writeFileSync(path.join(ext, "vite.config.ts"), "export default { resolve: { alias: [] } };");
-        try {
-            appUiLink({ projectDir: ext, component: "card", uiSrc });
-            expect(fs.readFileSync(path.join(ext, "vite.config.ts"), "utf-8")).toContain(uiSrc);
-        }
-        finally {
-            fs.rmSync(ext, { recursive: true, force: true });
-        }
-    });
-    it("fails loud when --ui-src is not a directory", () => {
-        expect(() => appUiLink({ projectDir: appDir, component: "card", uiSrc: path.join(root, "nope") })).toThrow(/not a directory/);
-    });
-});
-/**
- * The workflow body files are how AA-1 Option B becomes "open a file → edit →
- * push". `writeWorkflowFile` writes the verbatim server source under an
- * auto-pulled header; `stripWorkflowHeader` undoes the header so `set` round-
- * trips only the body. The two must compose so a pull-then-set is a no-op on the
- * source itself.
- */
-describe("workflow body files (writeWorkflowFile / stripWorkflowHeader)", () => {
-    let workDir;
-    beforeEach(() => {
-        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-wf-file-test-"));
-    });
-    afterEach(() => {
-        fs.rmSync(workDir, { recursive: true, force: true });
-    });
-    const body = `return({ data: { ok: tool_create_records({ table_id: "tbl_1" }) } })`;
-    it("writes src/workflows/<alias>.ts with a header + reference + wrapped body", () => {
-        const file = writeWorkflowFile(workDir, "issueInvoice", body);
-        expect(file).toBe(path.join(workDir, "src", "workflows", "issueInvoice.ts"));
-        const content = fs.readFileSync(file, "utf-8");
-        // Header: the loop command + the do-not-rename warning, all in // comments.
-        expect(content).toContain("lotics app workflow set issueInvoice");
-        expect(content).toContain("Do NOT rename");
-        // The triple-slash reference points at the per-alias ambient globals.
-        expect(content).toContain(`/// <reference path="../../.lotics/workflows/issueInvoice.globals.d.ts" />`);
-        // The body sits inside the server's __workflow envelope.
-        expect(content).toContain("async function __workflow()");
-        expect(content).toContain(body);
-    });
-    it("round-trips: stripping the header + wrapper recovers exactly the written body", () => {
-        const file = writeWorkflowFile(workDir, "wf", body);
-        const recovered = stripWorkflowHeader(fs.readFileSync(file, "utf-8"));
-        expect(recovered).toBe(body);
-    });
-    it("round-trips a multi-line body (wrapper peel is structural, not line-counted)", () => {
-        const multi = ["let_total = 0;", "return({ data: { total: let_total } })"].join("\n");
-        const file = writeWorkflowFile(workDir, "multi", multi);
-        expect(stripWorkflowHeader(fs.readFileSync(file, "utf-8"))).toBe(multi);
-    });
-    it("uses the server-returned envelope verbatim when provided", () => {
-        const file = writeWorkflowFile(workDir, "srv", body, {
-            prefix: "async function __workflow(): Promise<__WorkflowReturn | void> {\n",
-            suffix: "\n}",
-        });
-        const content = fs.readFileSync(file, "utf-8");
-        expect(content).toContain("async function __workflow(): Promise<__WorkflowReturn | void> {");
-        expect(stripWorkflowHeader(content)).toBe(body);
-    });
-    it("writes the per-alias ambient globals under .lotics/workflows", () => {
-        const file = writeWorkflowGlobals(workDir, "issueInvoice", "declare const trigger: never;");
-        expect(file).toBe(path.join(workDir, ".lotics", "workflows", "issueInvoice.globals.d.ts"));
-        expect(fs.readFileSync(file, "utf-8")).toContain("declare const trigger: never;");
-    });
-    it("passes a header-less hand-written body through unchanged", () => {
-        expect(stripWorkflowHeader(body)).toBe(body);
-    });
-    // GAP-59 pin: the CLI's fallback envelope must equal the SERVER's compile
-    // envelope (the canonical SOURCE_PREFIX/SOURCE_SUFFIX, pinned on the backend
-    // by `apps.test.ts`). If either side changes the wrapper, this literal breaks
-    // here and the backend pin breaks there — they can't silently diverge.
-    it("the CLI fallback envelope matches the server's __workflow wrapper byte-for-byte", () => {
-        expect(FALLBACK_ENVELOPE_PREFIX).toBe("async function __workflow(): Promise<__WorkflowReturn | void> {\n");
-        expect(FALLBACK_ENVELOPE_SUFFIX).toBe("\n}");
-    });
-    it("keeps an in-body leading comment when stripping a real generated file (header + wrapper)", () => {
-        // A body whose own first line is a comment: written through the real writer
-        // (header + __workflow wrapper), stripping recovers the body verbatim — the
-        // header peel is anchored on the wrapper opener that follows it, so the
-        // body's own comment is never mistaken for bookkeeping.
-        const commentBody = ["// real body comment", body].join("\n");
-        const file = writeWorkflowFile(workDir, "withcomment", commentBody);
-        expect(stripWorkflowHeader(fs.readFileSync(file, "utf-8"))).toBe(commentBody);
-    });
-    it("passes a wrapper-LESS hand-written body through unchanged even when it opens with comments", () => {
-        // No __workflow wrapper present (an author removed it, or hand-created the
-        // file before any pull): the leading comments are real source, not the
-        // generated header, so nothing is stripped. The earlier bug ate them.
-        const handWritten = [
-            "// a deliberate leading comment",
-            "// and a second one",
-            "",
-            body,
-        ].join("\n");
-        expect(stripWorkflowHeader(handWritten)).toBe(handWritten);
-    });
-});
-/**
- * `appWorkflowSet` is the push half of the file flow: resolve app_id from the
- * manifest, read src/workflows/<alias>.ts (header stripped), attach the typed
- * inputs/outputs from the manifest, and call client.setAppWorkflow. Tested as a
- * pure assembly against a captured mock client — no HTTP. process.cwd() is the
- * resolution base (like deploy/dev), so each test runs chdir'd into its workDir.
- */
-describe("appWorkflowSet", () => {
-    let workDir;
-    let prevCwd;
-    let exitErr;
-    beforeEach(() => {
-        prevCwd = process.cwd();
-        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-wf-set-test-"));
-        process.chdir(workDir);
-        vi.spyOn(console, "error").mockImplementation(() => undefined);
-        // appWorkflowSet calls process.exit(1) on the error paths; turn that into a
-        // throwable so a test can assert "it bailed" without killing the runner.
-        exitErr = undefined;
-        vi.spyOn(process, "exit").mockImplementation(((code) => {
-            exitErr = new Error(`process.exit(${code})`);
-            throw exitErr;
-        }));
-    });
-    afterEach(() => {
-        process.chdir(prevCwd);
-        fs.rmSync(workDir, { recursive: true, force: true });
-        vi.restoreAllMocks();
-    });
-    function writeManifest(workflows) {
-        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({
-            name: "sample-app",
-            lotics: {
-                app_id: "app_set",
-                workspace_id: "wks_set",
-                current_version_id: "apv_1",
-                version_number: 1,
-                workflows,
-            },
-        }, null, 2));
-    }
-    /** A mock client that captures the setAppWorkflow call and echoes a result. */
-    function mockClient(echo) {
-        const calls = [];
-        const client = {
-            setAppWorkflow: async (app_id, alias, body) => {
-                calls.push({ app_id, alias, body });
-                return { result: echo ?? { app_id, alias, workflow_id: "wfl_new" } };
-            },
-        };
-        return { client, calls };
-    }
-    it("reads app_id from the manifest, strips the file header, and forwards inputs/outputs", async () => {
-        writeManifest({
-            issueInvoice: {
-                workflow_id: "wfl_x",
-                inputs: { record_id: { type: "text", required: true } },
-                outputs: { invoice_id: { type: "text" } },
-            },
-        });
-        const source = `return({ data: { invoice_id: "x" } })`;
-        writeWorkflowFile(workDir, "issueInvoice", source);
-        const { client, calls } = mockClient({ workflow_id: "wfl_x", outputs: { invoice_id: { type: "text" } } });
-        await appWorkflowSet(client, { alias: "issueInvoice" });
-        expect(calls).toHaveLength(1);
-        expect(calls[0].app_id).toBe("app_set");
-        expect(calls[0].alias).toBe("issueInvoice");
-        // The body is the stripped source — no header comment crosses the boundary.
-        expect(calls[0].body.source).toBe(source);
-        expect(calls[0].body.source).not.toContain("Auto-pulled");
-        // The typed schemas ride along from the manifest declaration.
-        expect(calls[0].body.inputs).toEqual({ record_id: { type: "text", required: true } });
-        expect(calls[0].body.outputs).toEqual({ invoice_id: { type: "text" } });
-    });
-    it("forwards no inputs/outputs when the manifest declares none", async () => {
-        writeManifest({ ping: { workflow_id: "wfl_ping" } });
-        writeWorkflowFile(workDir, "ping", `return({ data: {} })`);
-        const { client, calls } = mockClient();
-        await appWorkflowSet(client, { alias: "ping" });
-        expect(calls[0].body.inputs).toBeUndefined();
-        expect(calls[0].body.outputs).toBeUndefined();
-    });
-    it("bails when the alias is absent from the manifest", async () => {
-        writeManifest({ other: { workflow_id: "wfl_o" } });
-        writeWorkflowFile(workDir, "missing", `return({})`);
-        const { client, calls } = mockClient();
-        await expect(appWorkflowSet(client, { alias: "missing" })).rejects.toThrow(/process\.exit/);
-        expect(calls).toHaveLength(0);
-    });
-    it("bails when the body file does not exist", async () => {
-        writeManifest({ declared: { workflow_id: "wfl_d" } });
-        // No src/workflows/declared.ts written.
-        const { client, calls } = mockClient();
-        await expect(appWorkflowSet(client, { alias: "declared" })).rejects.toThrow(/process\.exit/);
-        expect(calls).toHaveLength(0);
-    });
-    it("bails on a server verify error (non-zero exit, no swallowed failure)", async () => {
-        writeManifest({ bad: { workflow_id: "wfl_b" } });
-        writeWorkflowFile(workDir, "bad", `return(nope)`);
-        const calls = [];
-        const client = {
-            setAppWorkflow: async () => {
-                calls.push(1);
-                return { result: null, error: "source failed verification: unknown identifier 'nope'" };
-            },
-        };
-        await expect(appWorkflowSet(client, { alias: "bad" })).rejects.toThrow(/process\.exit/);
-        expect(calls).toHaveLength(1); // it DID attempt the push, then surfaced the error
-    });
-});
-/**
- * `appWorkflowPull` is the pull half: write one src/workflows/<alias>.ts per
- * bound alias from the live App row, using get_app_workflow for each faithful
- * body. A legacy alias whose source can't be rendered is warned and SKIPPED, not
- * a failure — so a partially-migrated app still pulls its readable bodies. (This
- * is the same writer appPull uses; appPull itself shells out to tar/npm.)
- */
-describe("appWorkflowPull", () => {
-    let workDir;
-    let prevCwd;
-    beforeEach(() => {
-        prevCwd = process.cwd();
-        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-wf-pull-test-"));
-        process.chdir(workDir);
-        vi.spyOn(console, "error").mockImplementation(() => undefined);
-    });
-    afterEach(() => {
-        process.chdir(prevCwd);
-        fs.rmSync(workDir, { recursive: true, force: true });
-        vi.restoreAllMocks();
-    });
-    function writeManifest() {
-        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({ name: "sample-app", lotics: { app_id: "app_p", workspace_id: "wks_p", current_version_id: "apv_1", version_number: 1 } }, null, 2));
-    }
-    /**
-     * Mock client: getApp returns the bound alias set; getAppWorkflow returns a
-     * body per alias; getAppWorkflowDts returns the per-alias globals + envelope.
-     */
-    function mockClient(aliases, sources) {
-        return {
-            getApp: async () => ({ workflows: Object.fromEntries(aliases.map((a) => [a, { workflow_id: `wfl_${a}` }])) }),
-            getAppWorkflow: async (_app_id, alias) => {
-                const source = sources[alias];
-                return source === null || source === undefined
-                    ? { result: { app_id: "app_p", alias, workflow_id: `wfl_${alias}` }, error: undefined }
-                    : { result: { app_id: "app_p", alias, workflow_id: `wfl_${alias}`, source } };
-            },
-            getAppWorkflowDts: async (_app_id, alias) => ({
-                dts: `// globals for ${alias}\ndeclare const trigger: { type: "app_workflow" };`,
-                envelope_prefix: "async function __workflow(): Promise<__WorkflowReturn | void> {\n",
-                envelope_suffix: "\n}",
-            }),
-        };
-    }
-    it("writes one src/workflows/<alias>.ts per bound alias, wrapped + referencing its globals", async () => {
-        writeManifest();
-        const client = mockClient(["a", "b"], {
-            a: `return({ data: { x: 1 } })`,
-            b: `return({ data: { y: 2 } })`,
-        });
-        await appWorkflowPull(client);
-        const a = fs.readFileSync(path.join(workDir, "src", "workflows", "a.ts"), "utf-8");
-        const b = fs.readFileSync(path.join(workDir, "src", "workflows", "b.ts"), "utf-8");
-        expect(a).toContain("lotics app workflow set a");
-        expect(a).toContain(`return({ data: { x: 1 } })`);
-        // Wrapped in the server's __workflow envelope and references its globals.
-        expect(a).toContain("async function __workflow()");
-        expect(a).toContain(`/// <reference path="../../.lotics/workflows/a.globals.d.ts" />`);
-        expect(b).toContain(`return({ data: { y: 2 } })`);
-        // The per-alias ambient globals landed under .lotics/workflows/.
-        const globalsA = fs.readFileSync(path.join(workDir, ".lotics", "workflows", "a.globals.d.ts"), "utf-8");
-        expect(globalsA).toContain("globals for a");
-        // The body still round-trips: stripping recovers exactly what set will push.
-        expect(stripWorkflowHeader(a)).toBe(`return({ data: { x: 1 } })`);
-    });
-    it("skips (does not fail) a legacy alias with no readable source", async () => {
-        writeManifest();
-        const client = mockClient(["good", "legacy"], {
-            good: `return({ data: {} })`,
-            legacy: null, // no source field → skipped with a warning
-        });
-        await appWorkflowPull(client);
-        expect(fs.existsSync(path.join(workDir, "src", "workflows", "good.ts"))).toBe(true);
-        expect(fs.existsSync(path.join(workDir, "src", "workflows", "legacy.ts"))).toBe(false);
-    });
-    it("writes the body with a fallback wrapper when the dts fetch fails (non-fatal)", async () => {
-        writeManifest();
-        const client = {
-            getApp: async () => ({ workflows: { c: { workflow_id: "wfl_c" } } }),
-            getAppWorkflow: async (_a, alias) => ({
-                result: { app_id: "app_p", alias, workflow_id: "wfl_c", source: `return({ data: {} })` },
-            }),
-            getAppWorkflowDts: async () => {
-                throw new Error("network down");
-            },
-        };
-        await appWorkflowPull(client);
-        const c = fs.readFileSync(path.join(workDir, "src", "workflows", "c.ts"), "utf-8");
-        // Body still written, still wrapped, still round-trips — only the globals
-        // file is absent (typecheck degraded, not the file).
-        expect(c).toContain("async function __workflow()");
-        expect(stripWorkflowHeader(c)).toBe(`return({ data: {} })`);
-        expect(fs.existsSync(path.join(workDir, ".lotics", "workflows", "c.globals.d.ts"))).toBe(false);
-    });
-});
-/**
- * `appExecuteWorkflow` runs a bound workflow and, with `--print-created` /
- * `--cleanup`, harvests the run's side effects (GAP-58). The harvest is an
- * honest report, never a rollback: it prints created records + a paste-ready
- * delete command + the mandatory caveat, and `--cleanup` deletes ONLY the
- * harvested records (never files/external/notifications).
- */
-describe("appExecuteWorkflow (--print-created / --cleanup harvest)", () => {
-    let workDir;
-    let prevCwd;
-    let stderr;
-    let exitCode;
-    beforeEach(() => {
-        prevCwd = process.cwd();
-        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-wf-run-test-"));
-        process.chdir(workDir);
-        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({ name: "a", lotics: { app_id: "app_r", workspace_id: "wks_r" } }));
-        stderr = [];
-        exitCode = undefined;
-        vi.spyOn(console, "error").mockImplementation((...args) => {
-            stderr.push(args.map(String).join(" "));
-        });
-        vi.spyOn(console, "log").mockImplementation(() => undefined);
-        vi.spyOn(process, "exit").mockImplementation(((code) => {
-            exitCode = code;
-            throw new Error(`exit(${code})`);
-        }));
-    });
-    afterEach(() => {
-        process.chdir(prevCwd);
-        fs.rmSync(workDir, { recursive: true, force: true });
-        vi.restoreAllMocks();
-    });
-    const summary = {
-        created_records: [{ table_id: "tbl_x", record_ids: ["rec_1", "rec_2"] }],
-        created_files: ["fil_1"],
-        irreversible_tool_calls: [{ tool_name: "misa_save_sales_voucher", step_id: "s1" }],
-        sub_workflows_possible: true,
-    };
-    function mockClient(deleteCalls) {
-        return {
-            appWorkflow: async () => ({ status: "success", message: "ok", side_effects: summary }),
-            execute: async (_tool, args) => {
-                deleteCalls.push(args);
-                return { result: { deleted: 2 } };
-            },
-        };
-    }
-    it("--print-created reports created records + a paste-ready delete + the caveat; deletes nothing", async () => {
-        const deleteCalls = [];
-        await appExecuteWorkflow(mockClient(deleteCalls), { alias: "run", inputs: {}, printCreated: true });
-        const out = stderr.join("\n");
-        expect(out).toContain("tbl_x: 2 record(s)");
-        expect(out).toContain(`lotics run delete_records '{"table_id":"tbl_x","record_ids":["rec_1","rec_2"]}'`);
-        // The mandatory caveat names the irreversible call + the sub-workflow risk.
-        expect(out).toContain("Could NOT auto-undo (clean up manually): misa_save_sales_voucher.");
-        expect(out).toContain("Sub-workflows may have run");
-        // Report-only: no delete executed.
-        expect(deleteCalls).toHaveLength(0);
-    });
-    it("--cleanup deletes ONLY the harvested records (never files/external)", async () => {
-        const deleteCalls = [];
-        await appExecuteWorkflow(mockClient(deleteCalls), { alias: "run", inputs: {}, cleanup: true });
-        expect(deleteCalls).toEqual([{ table_id: "tbl_x", record_ids: ["rec_1", "rec_2"] }]);
-    });
-    it("--cleanup exits non-zero when a delete fails (a CI script must not read partial cleanup as success)", async () => {
-        const client = {
-            appWorkflow: async () => ({ status: "success", message: "ok", side_effects: summary }),
-            execute: async () => ({ result: null, error: "permission denied" }),
-        };
-        await expect(appExecuteWorkflow(client, { alias: "run", inputs: {}, cleanup: true })).rejects.toThrow(/exit\(1\)/);
-        expect(exitCode).toBe(1);
-        expect(stderr.join("\n")).toContain("✗ tbl_x: permission denied");
-    });
-    it("exits non-zero on an error status even with --print-created", async () => {
-        const client = {
-            appWorkflow: async () => ({ status: "error", message: "boom", side_effects: summary }),
-            execute: async () => ({ result: {} }),
-        };
-        await expect(appExecuteWorkflow(client, { alias: "run", inputs: {}, printCreated: true })).rejects.toThrow(/exit\(1\)/);
-        expect(exitCode).toBe(1);
-    });
-    it("without the flags, prints no harvest and performs no delete", async () => {
-        const deleteCalls = [];
-        await appExecuteWorkflow(mockClient(deleteCalls), { alias: "run", inputs: {} });
-        const out = stderr.join("\n");
-        expect(out).not.toContain("Could NOT auto-undo");
-        expect(deleteCalls).toHaveLength(0);
-    });
-});
-describe("defaultPullTarget", () => {
-    let dir;
-    let prevCwd;
-    beforeEach(() => {
-        prevCwd = process.cwd();
-        dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-pull-target-"));
-        process.chdir(dir);
-    });
-    afterEach(() => {
-        process.chdir(prevCwd);
-        fs.rmSync(dir, { recursive: true, force: true });
-    });
-    it("refreshes in place when the cwd IS this app's own project (no stray subdir)", () => {
-        fs.writeFileSync("package.json", JSON.stringify({ lotics: { app_id: "app_X" } }));
-        expect(defaultPullTarget("app_X", "Sales Tracker")).toBe(process.cwd());
-    });
-    it("clones into a name subdir when the cwd is a DIFFERENT app", () => {
-        fs.writeFileSync("package.json", JSON.stringify({ lotics: { app_id: "app_OTHER" } }));
-        expect(defaultPullTarget("app_X", "Sales Tracker")).toBe("Sales Tracker");
-    });
-    it("clones into a name subdir when the cwd is not an app at all", () => {
-        expect(defaultPullTarget("app_X", "Sales Tracker")).toBe("Sales Tracker");
-    });
-});
-describe("ensureAppTsconfig", () => {
-    let dir;
-    beforeEach(() => {
-        dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-tsconfig-"));
-    });
-    afterEach(() => {
-        fs.rmSync(dir, { recursive: true, force: true });
-    });
-    const tsconfigPath = () => path.join(dir, "tsconfig.json");
-    const read = () => JSON.parse(fs.readFileSync(tsconfigPath(), "utf-8"));
-    it("adds both workflow globs to the TOP-LEVEL exclude", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ compilerOptions: {}, exclude: ["node_modules"] }));
-        ensureAppTsconfig(dir);
-        expect(read().exclude).toEqual(["node_modules", "src/workflows", ".lotics/workflows"]);
-    });
-    it("writes TOP-LEVEL even when a compilerOptions.exclude exists (tsc ignores the nested key)", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ compilerOptions: { exclude: ["x"] } }));
-        ensureAppTsconfig(dir);
-        const cfg = read();
-        expect(cfg.exclude).toEqual(["src/workflows", ".lotics/workflows"]);
-        expect(cfg.compilerOptions.exclude).toEqual(["x"]); // left untouched (and tsc-ignored)
-    });
-    it("preserves pre-existing top-level excludes", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ exclude: ["node_modules", "dist"] }));
-        ensureAppTsconfig(dir);
-        expect(read().exclude).toEqual(["node_modules", "dist", "src/workflows", ".lotics/workflows"]);
-    });
-    it("is idempotent — a second call writes nothing new", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ exclude: ["node_modules"] }));
-        ensureAppTsconfig(dir);
-        const afterFirst = fs.readFileSync(tsconfigPath(), "utf-8");
-        ensureAppTsconfig(dir);
-        expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe(afterFirst);
-    });
-    it("warns + does not throw or create a file when there is no tsconfig", () => {
-        expect(() => ensureAppTsconfig(dir)).not.toThrow();
-        expect(fs.existsSync(tsconfigPath())).toBe(false);
-    });
-    it("warns + does not throw on an unparseable tsconfig (left as-is)", () => {
-        fs.writeFileSync(tsconfigPath(), "{ not json,, }");
-        expect(() => ensureAppTsconfig(dir)).not.toThrow();
-        expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe("{ not json,, }");
-    });
-    it("rewrites a bare .lotics include to the glob (a dot-dir loads zero generated types)", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics"], exclude: ["node_modules"] }));
-        ensureAppTsconfig(dir);
-        expect(read().include).toEqual(["src", ".lotics/**/*"]);
-    });
-    it("leaves an already-correct .lotics/**/* include untouched (idempotent)", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics/**/*"], exclude: ["node_modules", "src/workflows", ".lotics/workflows"] }));
-        const before = fs.readFileSync(tsconfigPath(), "utf-8");
-        ensureAppTsconfig(dir);
-        expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe(before);
-    });
-    it("dedupes when both a bare .lotics and the glob are present", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: [".lotics", ".lotics/**/*", "src"] }));
-        ensureAppTsconfig(dir);
-        expect(read().include).toEqual([".lotics/**/*", "src"]);
-    });
-    it("heals the include AND adds the excludes in a single write", () => {
-        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics"], exclude: ["node_modules"] }));
-        ensureAppTsconfig(dir);
-        const cfg = read();
-        expect(cfg.include).toEqual(["src", ".lotics/**/*"]);
-        expect(cfg.exclude).toEqual(["node_modules", "src/workflows", ".lotics/workflows"]);
-    });
-});
-describe("appVersions", () => {
-    let logLines;
-    let errLines;
-    beforeEach(() => {
-        logLines = [];
-        errLines = [];
-        vi.spyOn(console, "log").mockImplementation((...args) => {
-            logLines.push(String(args[0]));
-        });
-        vi.spyOn(console, "error").mockImplementation((...args) => {
-            errLines.push(String(args[0]));
-        });
-    });
-    afterEach(() => {
-        vi.restoreAllMocks();
-    });
-    const clientWith = (payload) => ({ listAppVersions: vi.fn().mockResolvedValue(payload) });
-    it("renders history newest-first, marks the current version, and prefers the deployer name", async () => {
-        const client = clientWith({
-            current_version_id: "apv_2",
-            versions: [
-                {
-                    id: "apv_2",
-                    version: 2,
-                    message: "add receipt gate",
-                    build_status: "success",
-                    bundle_size_bytes: 1234,
-                    created_at: "2026-06-24T03:04:41Z",
-                    created_by: "mem_a",
-                    created_by_name: "Minh Vu",
-                },
-                {
-                    id: "apv_1",
-                    version: 1,
-                    message: "initial deploy",
-                    build_status: "success",
-                    bundle_size_bytes: 1000,
-                    created_at: "2026-06-23T08:00:00Z",
-                    created_by: "mem_b",
-                    created_by_name: null,
-                },
-            ],
-        });
-        // Explicit app_id → no manifest/package.json in cwd required.
-        await appVersions(client, { app_id: "app_x" });
-        // One header row + one row per version, all on stdout.
-        expect(logLines.length).toBe(3);
-        const v2Row = logLines.find((l) => l.includes("v2"));
-        const v1Row = logLines.find((l) => l.includes("v1"));
-        // Currently-served version is marked with `*`; the other is not.
-        expect(v2Row.startsWith("*")).toBe(true);
-        expect(v1Row.startsWith("*")).toBe(false);
-        // Messages render; the deployer name is preferred, falling back to the id.
-        expect(v2Row).toContain("add receipt gate");
-        expect(v2Row).toContain("Minh Vu");
-        expect(v1Row).toContain("initial deploy");
-        expect(v1Row).toContain("mem_b");
-    });
-    it("reports an empty history to stderr without printing a table", async () => {
-        const client = clientWith({ current_version_id: null, versions: [] });
-        await appVersions(client, { app_id: "app_empty" });
-        expect(logLines).toEqual([]);
-        expect(errLines.join("\n")).toContain("No versions found");
-    });
-});