@lotics/cli 0.57.0 → 0.62.0

package/dist/app_workflow_check.js

@@ -0,0 +1,169 @@
+/**
+ * `lotics app workflow check [alias]` — local TypeScript type check of editable
+ * workflow bodies, ONE isolated program per bound alias (GAP-59 fix).
+ *
+ * The bug it replaces: a single tsc program over `src/workflows/*.ts` +
+ * `.lotics/workflows/**` compiles ALL aliases' ambient globals together. Each
+ * `.globals.d.ts` declares its OWN `declare const trigger: AppWorkflowTrigger`
+ * (where `app_workflow.inputs` is THAT alias's input shape) at top level — so N
+ * aliases means N colliding ambient `trigger` declarations. tsc resolves ONE, and
+ * every body then type-checks `trigger.app_workflow.inputs` against the WRONG
+ * alias's inputs (a 22-workflow app emitted ~237 false TS2339 errors).
+ *
+ * The fix mirrors the SERVER, which verifies one body at a time and never
+ * collides: build a SEPARATE `ts.Program` per alias from exactly that alias's
+ * `{body, globals}` pair, so its ambient `trigger` is unambiguous. All aliases
+ * run in ONE node process (N in-memory programs, not N `tsc` spawns).
+ *
+ * `typescript` is resolved from the APP's own `node_modules` (it ships `tsc` as a
+ * devDependency), not bundled into the CLI bin: the verdict then tracks the exact
+ * compiler version the app's own `npm run typecheck` / CI uses, and the bin stays
+ * lean (the compiler is ~9MB). This is the one place the CLI loads a project-local
+ * peer tool — the path is only knowable at runtime and the version must match the
+ * app's, so there is no static-import alternative.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+/**
+ * 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 function workflowCheckCompilerOptions(tsApi) {
+    return {
+        target: tsApi.ScriptTarget.ES2022,
+        module: tsApi.ModuleKind.ESNext,
+        lib: ["lib.es2022.d.ts"],
+        strict: true,
+        noImplicitAny: true,
+        strictNullChecks: true,
+        noImplicitReturns: false,
+        noEmit: true,
+        allowJs: false,
+        isolatedModules: false,
+        skipLibCheck: true,
+        moduleResolution: tsApi.ModuleResolutionKind.NodeNext,
+        types: [],
+        declaration: false,
+    };
+}
+/**
+ * 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 function bodyLineOffset(wrappedSource) {
+    const lines = wrappedSource.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*async\s+function\s+__workflow\s*\(/.test(lines[i]))
+            return i + 1;
+    }
+    return 0;
+}
+/**
+ * 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 async function loadProjectTypescript(projectDir) {
+    const requireFromProject = createRequire(path.join(projectDir, "package.json"));
+    let resolved;
+    try {
+        resolved = requireFromProject.resolve("typescript");
+    }
+    catch {
+        throw new Error(`Could not resolve 'typescript' from ${projectDir}. ` +
+            `'lotics app workflow check' type-checks bodies with the app's own compiler — ` +
+            `run 'npm install' (the scaffold ships typescript as a devDependency).`);
+    }
+    const mod = (await import(pathToImportUrl(resolved)));
+    // The CJS typescript module loads under an ESM `import()` as `{ default: ts }`;
+    // a future ESM build would expose the namespace directly. Accept both.
+    return mod.default ?? mod;
+}
+/** A filesystem path → a `file://` URL `import()` accepts on every platform. */
+function pathToImportUrl(p) {
+    const resolved = path.resolve(p);
+    const prefixed = resolved.startsWith("/") ? resolved : `/${resolved}`;
+    return `file://${prefixed.split(path.sep).join("/")}`;
+}
+/**
+ * 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 function checkOneWorkflowBody(tsApi, input) {
+    const wrapped = fs.readFileSync(input.bodyPath, "utf-8");
+    const offset = bodyLineOffset(wrapped);
+    const program = tsApi.createProgram({
+        rootNames: [input.globalsPath, input.bodyPath],
+        options: workflowCheckCompilerOptions(tsApi),
+    });
+    const bodyFile = program.getSourceFile(input.bodyPath);
+    if (!bodyFile) {
+        // The program failed to ingest the body file — surface loudly rather than
+        // returning a false "clean" result.
+        return [
+            {
+                line: 1,
+                col: 1,
+                code: "INTERNAL",
+                message: `workflow check: body file was not loaded (${input.bodyPath})`,
+            },
+        ];
+    }
+    const issues = [];
+    for (const d of tsApi.getPreEmitDiagnostics(program)) {
+        if (d.file !== bodyFile)
+            continue;
+        let line = 1;
+        let col = 1;
+        if (typeof d.start === "number") {
+            const lc = bodyFile.getLineAndCharacterOfPosition(d.start);
+            // Map the wrapped-source line back to the author's body line. A diagnostic
+            // that lands on a synthetic wrapper/header line (rare) clamps to line 1.
+            line = Math.max(1, lc.line + 1 - offset);
+            col = lc.character + 1;
+        }
+        issues.push({
+            line,
+            col,
+            code: `TS${d.code}`,
+            message: tsApi.flattenDiagnosticMessageText(d.messageText, "\n"),
+        });
+    }
+    return issues;
+}
+/**
+ * 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 function checkWorkflowBodies(tsApi, aliases) {
+    return aliases.map(({ alias, input }) => ({
+        alias,
+        bodyPath: input.bodyPath,
+        issues: checkOneWorkflowBody(tsApi, input),
+    }));
+}

package/dist/app_workflow_check.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/app_workflow_check.test.js

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import ts from "typescript";
+import { bodyLineOffset, checkOneWorkflowBody, checkWorkflowBodies, workflowCheckCompilerOptions, } from "./app_workflow_check.js";
+import { writeWorkflowFile, writeWorkflowGlobals, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } from "./app_commands.js";
+/**
+ * The collision regression (GAP-59 fix). The shipped GAP-59 attempt compiled
+ * every alias's body + per-alias ambient globals into ONE tsc program. Each
+ * `<alias>.globals.d.ts` declares its OWN top-level `declare const trigger:
+ * AppWorkflowTrigger` whose `app_workflow.inputs` is THAT alias's input shape —
+ * so N aliases collided on the ambient `trigger`, tsc resolved one, and every
+ * body checked `trigger.app_workflow.inputs` against the wrong alias's inputs.
+ *
+ * `checkWorkflowBodies` builds an ISOLATED program per alias, so each body's
+ * `trigger` is unambiguous. The decisive case: alias A's globals type
+ * `inputs.foo`, alias B's type `inputs.bar`; A's body reads `.foo` (clean), B's
+ * reads `.bar` (clean) — both pass ONLY because each program sees only its own
+ * globals. A body reading a field that isn't in its own inputs is an error for
+ * THAT alias only.
+ */
+/**
+ * A faithful per-alias ambient globals `.d.ts`, matching the shape
+ * `generateWorkspaceDts` emits for an `app_workflow` trigger: a top-level
+ * `interface AppWorkflowTrigger` whose `app_workflow.inputs` carries this alias's
+ * typed inputs, `declare const trigger`, and the `__WorkflowReturn` alias the
+ * envelope's return type references.
+ */
+function globalsDts(inputFields) {
+    const fields = Object.entries(inputFields)
+        .map(([k, t]) => `      readonly ${k}: ${t};`)
+        .join("\n");
+    return [
+        "interface AppWorkflowTrigger {",
+        '  readonly type: "app_workflow";',
+        "  readonly app_workflow: {",
+        "    readonly inputs: {",
+        fields,
+        "    };",
+        "  };",
+        "}",
+        "declare const trigger: AppWorkflowTrigger;",
+        "type __WorkflowReturn = { data?: unknown; message?: string; field_errors?: unknown };",
+    ].join("\n");
+}
+describe("checkWorkflowBodies — isolated program per alias (GAP-59 collision regression)", () => {
+    let workDir;
+    beforeEach(() => {
+        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-wf-check-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    });
+    /** Write one alias's body (wrapped via the real writer) + its globals; return the check input. */
+    function writeAlias(alias, body, inputs) {
+        const bodyPath = writeWorkflowFile(workDir, alias, body);
+        const globalsPath = writeWorkflowGlobals(workDir, alias, globalsDts(inputs));
+        return { alias, input: { bodyPath, globalsPath } };
+    }
+    it("each alias type-checks against its OWN inputs — A.foo clean, B.bar clean, no cross-talk", () => {
+        const a = writeAlias("aliasA", "const x: string = trigger.app_workflow.inputs.foo;\nreturn({ data: { x } });", { foo: "string" });
+        const b = writeAlias("aliasB", "const y: string = trigger.app_workflow.inputs.bar;\nreturn({ data: { y } });", { bar: "string" });
+        const results = checkWorkflowBodies(ts, [a, b]);
+        const byAlias = Object.fromEntries(results.map((r) => [r.alias, r]));
+        // Both clean — proving each program saw ONLY its own globals. Under the old
+        // all-in-one program, one of A/B would read a `.foo`/`.bar` that the OTHER
+        // alias's surviving ambient `trigger` doesn't declare → a false TS2339.
+        expect(byAlias.aliasA.issues).toEqual([]);
+        expect(byAlias.aliasB.issues).toEqual([]);
+    });
+    it("a body reading an input that isn't in its OWN schema is an error for THAT alias only", () => {
+        // aliasA's inputs = { foo }, but its body reads `.bar` (which only aliasB has).
+        // With isolated programs, aliasA must fail (it has no `bar`) while aliasB,
+        // reading its own `.bar`, stays clean.
+        const a = writeAlias("aliasA", "const x: string = trigger.app_workflow.inputs.bar;\nreturn({ data: { x } });", { foo: "string" });
+        const b = writeAlias("aliasB", "const y: string = trigger.app_workflow.inputs.bar;\nreturn({ data: { y } });", { bar: "string" });
+        const results = checkWorkflowBodies(ts, [a, b]);
+        const byAlias = Object.fromEntries(results.map((r) => [r.alias, r]));
+        expect(byAlias.aliasA.issues.length).toBeGreaterThan(0);
+        expect(byAlias.aliasA.issues[0].code).toBe("TS2339"); // Property 'bar' does not exist
+        expect(byAlias.aliasA.issues[0].message).toContain("bar");
+        // aliasB is unaffected — the error is scoped to the offending alias.
+        expect(byAlias.aliasB.issues).toEqual([]);
+    });
+    it("an isolated program proves a single combined program WOULD collide", () => {
+        // Build ONE program over BOTH aliases' bodies + globals (the OLD approach) and
+        // show it reports a false error that the per-alias programs do NOT — pinning
+        // exactly the bug the fix removes.
+        const a = writeAlias("aliasA", "const x: string = trigger.app_workflow.inputs.foo;\nreturn({ data: { x } });", { foo: "string" });
+        const b = writeAlias("aliasB", "const y: string = trigger.app_workflow.inputs.bar;\nreturn({ data: { y } });", { bar: "string" });
+        // Per-alias: both clean.
+        const perAlias = checkWorkflowBodies(ts, [a, b]);
+        expect(perAlias.every((r) => r.issues.length === 0)).toBe(true);
+        // All-in-one: one program over all four files. The two ambient `trigger`
+        // declarations + two `AppWorkflowTrigger`/`__WorkflowReturn` interfaces
+        // collide, so the combined program reports errors the isolated ones don't.
+        const combined = ts.createProgram({
+            rootNames: [a.input.globalsPath, a.input.bodyPath, b.input.globalsPath, b.input.bodyPath],
+            options: workflowCheckCompilerOptions(ts),
+        });
+        const combinedDiagnostics = ts.getPreEmitDiagnostics(combined);
+        // The collision is a TS2339 on a BODY file — the alias whose ambient `trigger`
+        // lost the merge reads a field that isn't on the surviving alias's inputs.
+        // Assert THAT specific diagnostic, not a bare count (an unrelated options-level
+        // TS5110, which has no `.file`, would also satisfy length > 0 — a false green).
+        const collisions = combinedDiagnostics.filter((d) => d.file !== undefined && d.code === 2339);
+        expect(collisions.length).toBeGreaterThan(0);
+        const text = collisions.map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n")).join("\n");
+        expect(text).toMatch(/\b(foo|bar)\b/);
+    });
+    it("maps a diagnostic line back to the author's body (envelope offset removed)", () => {
+        // Body line 2 has the error; the report must point at line 2, not the wrapped
+        // line (the envelope + header push it down several lines).
+        const a = writeAlias("aliasA", "const ok: string = trigger.app_workflow.inputs.foo;\nconst bad: number = trigger.app_workflow.inputs.foo;\nreturn({ data: { ok, bad } });", { foo: "string" });
+        const issues = checkOneWorkflowBody(ts, a.input);
+        expect(issues.length).toBeGreaterThan(0);
+        // The string→number assignment is on the author's line 2.
+        expect(issues[0].line).toBe(2);
+    });
+});
+describe("bodyLineOffset", () => {
+    it("counts the lines up to and including the __workflow opener", () => {
+        // Two header lines, then the opener on line 3 → offset 3 (author's line 1
+        // is the next line).
+        const wrapped = ["// header a", "// header b", FALLBACK_ENVELOPE_PREFIX.trimEnd(), "return({});", FALLBACK_ENVELOPE_SUFFIX.trim()].join("\n");
+        expect(bodyLineOffset(wrapped)).toBe(3);
+    });
+    it("returns 0 when there is no recognizable wrapper opener", () => {
+        expect(bodyLineOffset("return({});\n")).toBe(0);
+    });
+});
+/**
+ * Pin the local compiler options to the SERVER's set-time options
+ * (`COMPILER_OPTIONS` in typecheck_with_typescript.ts). The check command's
+ * verdict only matches set-time if these stay in lockstep — if the server
+ * changes a flag, this breaks and forces the local options to follow.
+ */
+describe("workflowCheckCompilerOptions pins the server's set-time options", () => {
+    it("matches the server's FULL pinned literal — every flag, so no flag can silently drift", () => {
+        expect(workflowCheckCompilerOptions(ts)).toEqual({
+            target: ts.ScriptTarget.ES2022,
+            module: ts.ModuleKind.ESNext,
+            lib: ["lib.es2022.d.ts"],
+            strict: true,
+            noImplicitAny: true,
+            strictNullChecks: true,
+            noImplicitReturns: false,
+            noEmit: true,
+            allowJs: false,
+            isolatedModules: false,
+            skipLibCheck: true,
+            moduleResolution: ts.ModuleResolutionKind.NodeNext,
+            types: [],
+            declaration: false,
+        });
+    });
+    it("uses the SAME __workflow envelope the server compiles bodies within", () => {
+        // The body writer wraps in this envelope; the server compiles within the
+        // identical one (pinned to the backend's SOURCE_PREFIX/SUFFIX by
+        // app_commands.test.ts + apps.test.ts). If they diverge, the local line
+        // mapping and the parse of top-level await / return({...}) break.
+        expect(FALLBACK_ENVELOPE_PREFIX).toBe("async function __workflow(): Promise<__WorkflowReturn | void> {\n");
+        expect(FALLBACK_ENVELOPE_SUFFIX).toBe("\n}");
+    });
+});

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(" "),
+    };
+}