@lotics/cli 0.57.0 → 0.62.0

package/dist/app_commands.test.js

@@ -1,8 +1,8 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+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 } from "./app_commands.js";
+import { stampPulledManifest, undeclaredCapabilities, appDirName, defaultPullTarget, ensureWorkflowTsconfigExcludes, appCodegen, appUiLink, 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
@@ -157,3 +157,570 @@ describe("appDirName", () => {
         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);
+    });
+});
+/**
+ * `appUiLink` edits the app's vite.config.ts resolve.alias to dev-link
+ * @lotics/ui at the monorepo's packages/ui/src. It fails loud outside a
+ * monorepo, validates the component exists, 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 monorepo packages/ui/src above the project", () => {
+        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(/monorepo checkout/);
+        }
+        finally {
+            fs.rmSync(lonely, { recursive: true, force: true });
+        }
+    });
+});
+/**
+ * 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("ensureWorkflowTsconfigExcludes", () => {
+    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"] }));
+        ensureWorkflowTsconfigExcludes(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"] } }));
+        ensureWorkflowTsconfigExcludes(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"] }));
+        ensureWorkflowTsconfigExcludes(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"] }));
+        ensureWorkflowTsconfigExcludes(dir);
+        const afterFirst = fs.readFileSync(tsconfigPath(), "utf-8");
+        ensureWorkflowTsconfigExcludes(dir);
+        expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe(afterFirst);
+    });
+    it("warns + does not throw or create a file when there is no tsconfig", () => {
+        expect(() => ensureWorkflowTsconfigExcludes(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(() => ensureWorkflowTsconfigExcludes(dir)).not.toThrow();
+        expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe("{ not json,, }");
+    });
+});

package/dist/app_workflow_check.d.ts

@@ -0,0 +1,77 @@
+import type ts from "typescript";
+/**
+ * The compiler options the SERVER uses at set-time verify — a copy of
+ * `backend/features/workflows/typecheck_with_typescript.ts:COMPILER_OPTIONS`,
+ * expressed against the project-resolved `ts` namespace so the local verdict
+ * matches the server's. The CLI can't import backend code, so this is duplicated
+ * and pinned to the same literal by tests on BOTH sides (this package's
+ * `app_workflow_check.test.ts` + the backend's `typecheck_with_typescript.test.ts`
+ * — same pattern as the `__workflow` envelope). If the server changes a flag, both
+ * pins break and force this to follow. lib `es2022` with NO DOM (a body runs on
+ * the server, not a browser); `types: []` so no `@types/*` ambient leaks in;
+ * `skipLibCheck` keeps lib-typecheck off the hot path.
+ */
+export declare function workflowCheckCompilerOptions(tsApi: typeof ts): ts.CompilerOptions;
+/** One type error, mapped back to the author's body coordinates. */
+export interface WorkflowCheckIssue {
+    /** 1-indexed line in the author's body (the envelope-prefix offset removed). */
+    line: number;
+    /** 1-indexed column in the author's body. */
+    col: number;
+    /** TS-prefixed diagnostic code, e.g. "TS2339". */
+    code: string;
+    /** Human-readable message; multi-line TS messages joined with `\n`. */
+    message: string;
+}
+/** The verdict for one alias's body. `issues: []` ⇒ clean. */
+export interface WorkflowCheckAliasResult {
+    alias: string;
+    bodyPath: string;
+    issues: WorkflowCheckIssue[];
+}
+export interface WorkflowCheckInput {
+    /** Absolute path to the wrapped body file (`src/workflows/<alias>.ts`). */
+    bodyPath: string;
+    /** Absolute path to the per-alias ambient globals (`.lotics/workflows/<alias>.globals.d.ts`). */
+    globalsPath: string;
+}
+/**
+ * Count the lines the envelope prefix adds ABOVE the author's body, so a
+ * diagnostic on body line K reports as the author's line K, not K+offset. The
+ * wrapper opener (`async function __workflow(...) {`) and the header above it
+ * (the `/// <reference>`, the `//` comments, the `export {};` marker, blank
+ * lines) all sit before the first author line. The author's body is everything
+ * between the wrapper opener line and the trailing `}` — so the offset is the
+ * count of lines up to and including the opener.
+ *
+ * Mirrors the body shape `writeWorkflowFile` produces; recognized structurally
+ * (the `__workflow` opener) so a future header tweak can't silently desync the
+ * line mapping. A file with no recognizable opener (degraded) maps with a zero
+ * offset rather than guessing.
+ */
+export declare function bodyLineOffset(wrappedSource: string): number;
+/**
+ * Resolve the app's own `typescript` from `projectDir`. Loud, actionable error
+ * when the app has no compiler installed (never a silent skip — a skipped check
+ * reads as a clean check). The dynamic import is the boundary adapter the file
+ * header explains: the only place we load a project-local peer tool.
+ */
+export declare function loadProjectTypescript(projectDir: string): Promise<typeof ts>;
+/**
+ * Type-check one alias's body in an ISOLATED program built from exactly that
+ * alias's `{body, globals}` pair — so the ambient `trigger` is unambiguous and
+ * `trigger.app_workflow.inputs` is checked against THIS alias's inputs. Returns
+ * every diagnostic that lands in the body file, mapped back to the author's
+ * coordinates.
+ */
+export declare function checkOneWorkflowBody(tsApi: typeof ts, input: WorkflowCheckInput): WorkflowCheckIssue[];
+/**
+ * Type-check every requested alias in ONE process (one isolated program each).
+ * Pure over its inputs (the resolved `ts` + the `{body, globals}` paths) so it's
+ * unit-testable without the CLI/manifest plumbing. Aliases are returned in the
+ * order given.
+ */
+export declare function checkWorkflowBodies(tsApi: typeof ts, aliases: {
+    alias: string;
+    input: WorkflowCheckInput;
+}[]): WorkflowCheckAliasResult[];