@lotics/cli 0.56.0 → 0.60.1

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, 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,502 @@ 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);
+    });
+});

package/dist/args.d.ts

@@ -28,6 +28,10 @@ export declare function parseArgs(argv: string[]): {
         message?: string;
         local: boolean;
         all: boolean;
+        /** `--print-created` (alias `--report-effects`): print the honest post-run side-effect harvest. */
+        printCreated: boolean;
+        /** `--cleanup`: also delete the harvested created records (records only). */
+        cleanup: boolean;
         version: boolean;
         help: boolean;
     };

package/dist/args.js

@@ -24,6 +24,8 @@ export function parseArgs(argv) {
         message: undefined,
         local: false,
         all: false,
+        printCreated: false,
+        cleanup: false,
         version: false,
         help: false,
     };
@@ -74,6 +76,13 @@ export function parseArgs(argv) {
             case "--all":
                 flags.all = true;
                 break;
+            case "--print-created":
+            case "--report-effects":
+                flags.printCreated = true;
+                break;
+            case "--cleanup":
+                flags.cleanup = true;
+                break;
             case "--version":
             case "-v":
                 flags.version = true;

package/dist/args.test.js

@@ -51,6 +51,18 @@ describe("parseArgs", () => {
         expect(r.flags.workspace).toBeUndefined();
         expect(r.flags.all).toBe(false);
     });
+    it("parses --print-created and --report-effects to the same boolean flag", () => {
+        expect(parseArgs(["app", "workflow", "run", "wf", "--print-created"]).flags.printCreated).toBe(true);
+        expect(parseArgs(["app", "workflow", "run", "wf", "--report-effects"]).flags.printCreated).toBe(true);
+        // The alias does not consume the next token (it's a boolean flag).
+        const r = parseArgs(["app", "workflow", "run", "wf", "--print-created"]);
+        expect(r.restArgs).toEqual(["wf"]);
+    });
+    it("parses --cleanup as a boolean flag (default false)", () => {
+        expect(parseArgs(["app", "workflow", "run", "wf", "--cleanup"]).flags.cleanup).toBe(true);
+        expect(parseArgs(["app", "workflow", "run", "wf"]).flags.cleanup).toBe(false);
+        expect(parseArgs(["app", "workflow", "run", "wf"]).flags.printCreated).toBe(false);
+    });
     it("treats `org use <name>` as command / subcommand / positional", () => {
         const r = parseArgs(["org", "use", "Acme Corp"]);
         expect(r.command).toBe("org");

package/dist/child_env.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `NODE_OPTIONS` for a spawned Node child (npm, vite), forcing IPv4-first DNS +
+ * a fast Happy-Eyeballs family timeout. The CLI bin applies the equivalent as
+ * runtime API calls (cli.ts top-of-module), but a child Node process is a fresh
+ * runtime that won't inherit them — so they must travel via the env. Preserves
+ * any existing `NODE_OPTIONS`.
+ *
+ * Why: WSL2 + Node 24's Happy-Eyeballs races IPv4/IPv6 and intermittently stalls
+ * on a dead IPv6 route to api.lotics.ai. IPv4-first + a 2s per-family cap fails a
+ * bad IPv6 path fast to IPv4. Its own module so `app_commands` and `dev/server`
+ * share it without a circular import.
+ */
+export declare function ipv4ChildEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/child_env.js

@@ -0,0 +1,24 @@
+/**
+ * `NODE_OPTIONS` for a spawned Node child (npm, vite), forcing IPv4-first DNS +
+ * a fast Happy-Eyeballs family timeout. The CLI bin applies the equivalent as
+ * runtime API calls (cli.ts top-of-module), but a child Node process is a fresh
+ * runtime that won't inherit them — so they must travel via the env. Preserves
+ * any existing `NODE_OPTIONS`.
+ *
+ * Why: WSL2 + Node 24's Happy-Eyeballs races IPv4/IPv6 and intermittently stalls
+ * on a dead IPv6 route to api.lotics.ai. IPv4-first + a 2s per-family cap fails a
+ * bad IPv6 path fast to IPv4. Its own module so `app_commands` and `dev/server`
+ * share it without a circular import.
+ */
+export function ipv4ChildEnv(env) {
+    return {
+        ...env,
+        NODE_OPTIONS: [
+            env.NODE_OPTIONS,
+            "--dns-result-order=ipv4first",
+            "--network-family-autoselection-attempt-timeout=2000",
+        ]
+            .filter(Boolean)
+            .join(" "),
+    };
+}