@lotics/cli 0.60.1 → 0.62.0

package/README.md

@@ -173,9 +173,10 @@ lotics app workflow run issueInvoice '{...}' --cleanup   # also deletes created
 # Edit workflow bodies as files. `app pull` writes src/workflows/<alias>.ts (the
 # faithful server source, wrapped + referencing its .lotics/workflows/<alias>.globals.d.ts);
 # edit the body, then push it back through set_app_workflow — the server verifies it
-# (deploy still never authors workflows). Bodies are locally typecheckable:
-#   tsc -p tsconfig.workflows.json
+# (deploy still never authors workflows). Bodies are locally typecheckable with
+# `app workflow check` (one isolated program per alias = the same verdict as `set`):
 lotics app workflow pull                    # rewrite src/workflows/*.ts + globals from the server
+lotics app workflow check                   # typecheck every body locally ([alias] for one)
 lotics app workflow set issueInvoice        # push the edited src/workflows/issueInvoice.ts
 
 # Dev-link @lotics/ui to the monorepo's packages/ui/src for live HMR (monorepo only)

package/dist/app_commands.d.ts

@@ -86,6 +86,17 @@ export declare function writeWorkflowFile(projectDir: string, alias: string, sou
  * real source, not bookkeeping, and must not be silently eaten.
  */
 export declare function stripWorkflowHeader(content: string): string;
+/**
+ * Add the workflow-body globs to the main `tsconfig.json`'s `exclude` if missing,
+ * preserving every other exclude. The starter ships these excludes already, but
+ * an app SCAFFOLDED before this CLI release (or one with a hand-written tsconfig)
+ * doesn't — and pulling bodies into it would otherwise break its
+ * `npm run typecheck`: the bodies pull the app's DOM lib (the server doesn't) and
+ * the per-alias ambient globals collide on `trigger`. Idempotent — a second pull
+ * is a no-op. Warns exactly what it added. A missing/unparseable tsconfig is a
+ * non-fatal warn (the pull itself still succeeds); the author fixes the config.
+ */
+export declare function ensureWorkflowTsconfigExcludes(projectDir: string): void;
 /**
  * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
  * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are
@@ -185,6 +196,14 @@ export declare function appSetSubdomain(client: LoticsClient, args: {
 export declare function appRename(client: LoticsClient, args: {
     name: string;
 }): Promise<void>;
+/**
+ * Where `lotics app pull <app_id>` lands when given NO explicit path. If the cwd
+ * IS already this app's own project (its manifest `app_id` matches), refresh in
+ * place — the documented `cd <app> && lotics app pull` flow. Otherwise a fresh
+ * clone goes to an `appDirName(name)` subdir. Without this, pulling from inside
+ * the app dropped a stray `./<name>/` subdir instead of refreshing the project.
+ */
+export declare function defaultPullTarget(appId: string, appName: string): string;
 export declare function appPull(client: LoticsClient, args: {
     app_id: string;
     targetPath?: string;
@@ -273,6 +292,28 @@ export declare function appWorkflowSet(client: LoticsClient, args: {
  * uses); a legacy alias with no rendered source warns and is skipped.
  */
 export declare function appWorkflowPull(client: LoticsClient): Promise<void>;
+/**
+ * `lotics app workflow check [alias]` — local TypeScript type check of the
+ * editable workflow bodies, ONE isolated program per bound alias (GAP-59 fix).
+ *
+ * The dedicated `tsconfig.workflows.json` that GAP-59 first shipped compiled ALL
+ * aliases' bodies + per-alias ambient globals into a SINGLE program, so the N
+ * `declare const trigger: AppWorkflowTrigger` declarations (each with THAT
+ * alias's `app_workflow.inputs`) collided — tsc resolved one and every body
+ * checked `trigger.app_workflow.inputs` against the wrong alias. This command
+ * replaces that config: it builds a separate `ts.Program` per alias from exactly
+ * that alias's `{body, globals}` pair (mirroring the SERVER, which verifies one
+ * body at a time), so the ambient `trigger` is unambiguous and the verdict
+ * matches set-time. All aliases run in ONE process.
+ *
+ * `[alias]` checks one alias; omitted, checks every bound alias that has a body
+ * file. Exits non-zero if ANY alias has a type error. A bound alias with no body
+ * file yet (never pulled) is warned and skipped; an alias missing its globals
+ * file is an error (the body can't be checked without its types).
+ */
+export declare function appWorkflowCheck(args: {
+    alias?: string;
+}): Promise<void>;
 /**
  * `lotics ui link <component> [--remove]` — add or remove the `@lotics/ui`
  * dev-link alias in the app's `vite.config.ts`, so edits to the monorepo's

package/dist/app_commands.js

@@ -23,6 +23,7 @@ import { generateAppAgentsDts } from "./generate_app_agents_dts.js";
 import { generateAppQueriesDts } from "./generate_app_queries_dts.js";
 import { collectQueryTableIds } from "@lotics/shared/app_query_ast";
 import { generateAppFields } from "./generate_app_fields.js";
+import { loadProjectTypescript, checkWorkflowBodies, } from "./app_workflow_check.js";
 /**
  * Resolve the latest published version of a package from the npm registry.
  * Returns null on any failure (network error, 404, malformed payload) so
@@ -53,6 +54,16 @@ async function fetchLatestNpmVersion(packageName) {
 const WORKFLOWS_DIR = path.join("src", "workflows");
 /** The dot-dir that holds the per-alias ambient globals `.d.ts` (server-generated). */
 const WORKFLOW_GLOBALS_DIR = path.join(".lotics", "workflows");
+/**
+ * The two globs the MAIN tsconfig must `exclude`: the editable workflow bodies AND
+ * their per-alias ambient globals. The bodies use the app's DOM lib (the server
+ * doesn't) and each globals file declares its own ambient `trigger` — loading 22
+ * of them into the app's program collides those declarations and poisons
+ * `npm run typecheck`. Bodies are type-checked separately by
+ * `lotics app workflow check` (one isolated program per alias). Always written
+ * with `/` separators — tsconfig globs are POSIX even on Windows.
+ */
+const WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".lotics/workflows"];
 /**
  * The `async function __workflow(...)` wrapper a workflow body sits inside —
  * the SAME envelope the server compiles the body within at `set_app_workflow`
@@ -68,9 +79,10 @@ export const FALLBACK_ENVELOPE_SUFFIX = "\n}";
  * Header prepended to every pulled `src/workflows/<alias>.ts`. A triple-slash
  * reference pulls in the per-alias ambient globals (`trigger` / `runtime` / tool
  * calls — server-generated), and the body sits inside the SAME `__workflow`
- * wrapper the server compiles within, so a local `tsc` now mirrors the set-time
- * verdict (GAP-59). The wrapper + reference + comment lines are CLI bookkeeping,
- * stripped on `set`; the filename IS the alias — renaming it orphans the body.
+ * wrapper the server compiles within, so a local `lotics app workflow check`
+ * mirrors the set-time verdict (GAP-59). The wrapper + reference + comment lines
+ * are CLI bookkeeping, stripped on `set`; the filename IS the alias — renaming it
+ * orphans the body.
  */
 function workflowFileHeader(alias) {
     const refPath = path
@@ -79,17 +91,18 @@ function workflowFileHeader(alias) {
         .join("/");
     return (`/// <reference path="${refPath}" />\n` +
         `// Auto-pulled workflow body for "${alias}". Edit the BODY between the wrapper\n` +
-        `// lines below, then push with:\n` +
+        `// lines below, then check + push with:\n` +
+        `//   lotics app workflow check ${alias}\n` +
         `//   lotics app workflow set ${alias}\n` +
         `// The push goes through set_app_workflow, where the SERVER verifies the body.\n` +
         `// The __workflow wrapper + the reference above are CLI bookkeeping (stripped on\n` +
         `// set) — they only make the body typecheck locally against the workspace types.\n` +
         `// Do NOT rename this file — the filename is the alias the binding is keyed by.\n` +
-        // `export {};` makes the file a MODULE so the per-file `__workflow` wrapper
-        // doesn't collide across the bodies the dedicated tsconfig globs together.
-        // The server compiles each body in isolation (script mode), so this is a
-        // local-only adaptation with no effect on the body's type-checking; it is
-        // CLI bookkeeping, stripped on `set`.
+        // `export {};` makes the file a MODULE. `lotics app workflow check` compiles
+        // each body in its OWN isolated program (just this body + its globals), so the
+        // `__workflow` function never collides across bodies; the marker is retained as
+        // stable CLI bookkeeping (stripWorkflowHeader anchors on it) and is stripped on
+        // `set`, so it has no effect on what the server verifies.
         `export {};\n`);
 }
 /** Absolute path of one workflow body file, given the project root + alias. */
@@ -290,6 +303,47 @@ function writeAppMeta(projectDir, meta) {
     pkg.lotics = meta;
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
+/**
+ * Add the workflow-body globs to the main `tsconfig.json`'s `exclude` if missing,
+ * preserving every other exclude. The starter ships these excludes already, but
+ * an app SCAFFOLDED before this CLI release (or one with a hand-written tsconfig)
+ * doesn't — and pulling bodies into it would otherwise break its
+ * `npm run typecheck`: the bodies pull the app's DOM lib (the server doesn't) and
+ * the per-alias ambient globals collide on `trigger`. Idempotent — a second pull
+ * is a no-op. Warns exactly what it added. A missing/unparseable tsconfig is a
+ * non-fatal warn (the pull itself still succeeds); the author fixes the config.
+ */
+export function ensureWorkflowTsconfigExcludes(projectDir) {
+    const tsconfigPath = path.join(projectDir, "tsconfig.json");
+    if (!fs.existsSync(tsconfigPath)) {
+        console.error(`⚠ No tsconfig.json at ${projectDir} — could not ensure ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} are excluded. ` +
+            `Add them to your tsconfig's "exclude" so npm run typecheck skips the workflow bodies.`);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(tsconfigPath, "utf-8"));
+    }
+    catch (err) {
+        console.error(`⚠ Could not parse tsconfig.json (${err instanceof Error ? err.message : String(err)}) — ` +
+            `add ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} to its "exclude" manually so npm run typecheck skips the workflow bodies.`);
+        return;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return;
+    // `exclude` is a TOP-LEVEL tsconfig field — tsc ignores `compilerOptions.exclude`,
+    // so the workflow globs must land at the top level or `npm run typecheck` still
+    // loads the bodies + their colliding per-alias globals.
+    const current = Array.isArray(parsed.exclude) ? parsed.exclude : [];
+    const currentStrings = current.filter((e) => typeof e === "string");
+    const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentStrings.includes(g));
+    if (toAdd.length === 0)
+        return;
+    parsed.exclude = [...currentStrings, ...toAdd];
+    fs.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
+    console.error(`Patched tsconfig.json: added ${toAdd.join(", ")} to "exclude" so npm run typecheck skips the workflow bodies ` +
+        `(check them with: lotics app workflow check).`);
+}
 /**
  * Write `.lotics/app_workflows.d.ts` + `.lotics/app_queries.d.ts` from the
  * manifest's `workflows` / `queries` maps. Called from `app create / pull /
@@ -396,6 +450,10 @@ export async function appCodegen(args) {
     // it, so the local typecheck tracks the current workspace schema. Aliases
     // never pulled (no body file yet) are skipped — codegen isn't a pull.
     await refreshWorkflowGlobals(args.client, projectDir, meta.app_id, Object.keys(meta.workflows ?? {}));
+    // Keep the main tsconfig excluding the workflow-body globs (idempotent) so
+    // npm run typecheck never loads the bodies or their colliding per-alias globals.
+    if (Object.keys(meta.workflows ?? {}).length > 0)
+        ensureWorkflowTsconfigExcludes(projectDir);
 }
 /**
  * For each bound alias that already has a local body file, fetch its current
@@ -572,6 +630,31 @@ export async function appRename(client, args) {
         throw new Error(res.error);
     console.error(`App renamed: "${args.name}" (${meta.app_id})`);
 }
+/**
+ * Where `lotics app pull <app_id>` lands when given NO explicit path. If the cwd
+ * IS already this app's own project (its manifest `app_id` matches), refresh in
+ * place — the documented `cd <app> && lotics app pull` flow. Otherwise a fresh
+ * clone goes to an `appDirName(name)` subdir. Without this, pulling from inside
+ * the app dropped a stray `./<name>/` subdir instead of refreshing the project.
+ */
+export function defaultPullTarget(appId, appName) {
+    const cwdPkgPath = path.join(process.cwd(), "package.json");
+    if (fs.existsSync(cwdPkgPath)) {
+        let pkg = null;
+        try {
+            pkg = JSON.parse(fs.readFileSync(cwdPkgPath, "utf-8"));
+        }
+        catch (err) {
+            // An unparseable cwd package.json means we can't confirm this is the app's
+            // own project — warn and fall through to a fresh clone rather than crash.
+            console.error(`⚠ Could not parse ${cwdPkgPath} (${err instanceof Error ? err.message : String(err)}) — ` +
+                `pulling into a fresh ${appDirName(appName)}/ subdir.`);
+        }
+        if (pkg?.lotics?.app_id === appId)
+            return process.cwd();
+    }
+    return appDirName(appName);
+}
 export async function appPull(client, args) {
     const app = await client.getApp(args.app_id);
     if (!app.current_version_id) {
@@ -579,7 +662,7 @@ export async function appPull(client, args) {
     }
     const version = await client.getAppVersion(app.id, app.current_version_id);
     const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
-    const targetPath = path.resolve(args.targetPath ?? appDirName(app.name));
+    const targetPath = path.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
     fs.mkdirSync(targetPath, { recursive: true });
     // Download to a temp file because `tar -xz` reads from a real path.
     const tmpFile = path.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
@@ -618,6 +701,9 @@ export async function appPull(client, args) {
         if (written.length > 0) {
             console.error(`Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`);
         }
+        // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
+        // bodies into it would break its npm run typecheck. Patch it idempotently.
+        ensureWorkflowTsconfigExcludes(targetPath);
     }
     console.error(`Installing npm dependencies...`);
     await runNpm(["install"], targetPath);
@@ -1053,6 +1139,109 @@ export async function appWorkflowPull(client) {
     const written = await writeWorkflowFiles(client, projectDir, meta.app_id, aliases);
     console.error(`Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` +
         (written.length > 0 ? ` (${written.join(", ")})` : ""));
+    // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
+    // bodies into it would break its npm run typecheck. Patch it idempotently.
+    ensureWorkflowTsconfigExcludes(projectDir);
+}
+/**
+ * `lotics app workflow check [alias]` — local TypeScript type check of the
+ * editable workflow bodies, ONE isolated program per bound alias (GAP-59 fix).
+ *
+ * The dedicated `tsconfig.workflows.json` that GAP-59 first shipped compiled ALL
+ * aliases' bodies + per-alias ambient globals into a SINGLE program, so the N
+ * `declare const trigger: AppWorkflowTrigger` declarations (each with THAT
+ * alias's `app_workflow.inputs`) collided — tsc resolved one and every body
+ * checked `trigger.app_workflow.inputs` against the wrong alias. This command
+ * replaces that config: it builds a separate `ts.Program` per alias from exactly
+ * that alias's `{body, globals}` pair (mirroring the SERVER, which verifies one
+ * body at a time), so the ambient `trigger` is unambiguous and the verdict
+ * matches set-time. All aliases run in ONE process.
+ *
+ * `[alias]` checks one alias; omitted, checks every bound alias that has a body
+ * file. Exits non-zero if ANY alias has a type error. A bound alias with no body
+ * file yet (never pulled) is warned and skipped; an alias missing its globals
+ * file is an error (the body can't be checked without its types).
+ */
+export async function appWorkflowCheck(args) {
+    const projectDir = process.cwd();
+    const meta = readAppMeta(projectDir);
+    const bound = Object.keys(meta.workflows ?? {});
+    let aliases;
+    if (args.alias) {
+        if (!bound.includes(args.alias)) {
+            console.error(`No workflow "${args.alias}" in package.json#lotics.workflows. ` +
+                `Bound aliases: ${bound.length > 0 ? bound.join(", ") : "(none)"}.`);
+            process.exit(1);
+        }
+        aliases = [args.alias];
+    }
+    else {
+        aliases = bound;
+    }
+    if (aliases.length === 0) {
+        console.error(`App ${meta.app_id} has no bound workflows to check.`);
+        return;
+    }
+    // Each alias contributes its OWN body + globals. A bound alias never pulled has
+    // no body file — warn + skip (not an error; the author hasn't pulled it). A
+    // body with no globals can't be checked — that IS an error (run a pull).
+    const toCheck = [];
+    for (const alias of aliases) {
+        const bodyPath = workflowFilePath(projectDir, alias);
+        const globalsPath = workflowGlobalsPath(projectDir, alias);
+        if (!fs.existsSync(bodyPath)) {
+            console.error(`⚠ Skipped "${alias}" — no body at ${path.relative(projectDir, bodyPath)}. ` +
+                `Run 'lotics app workflow pull' to write it.`);
+            continue;
+        }
+        if (!fs.existsSync(globalsPath)) {
+            console.error(`Cannot check "${alias}" — missing types at ${path.relative(projectDir, globalsPath)}. ` +
+                `Run 'lotics app workflow pull' (or 'lotics app codegen') to fetch them.`);
+            process.exit(1);
+        }
+        toCheck.push({ alias, input: { bodyPath, globalsPath } });
+    }
+    if (toCheck.length === 0) {
+        console.error("No workflow bodies to check (every bound alias was skipped).");
+        return;
+    }
+    const tsApi = await loadProjectTypescript(projectDir);
+    const results = checkWorkflowBodies(tsApi, toCheck);
+    printWorkflowCheckResults(projectDir, results);
+    const failed = results.filter((r) => r.issues.length > 0);
+    if (failed.length > 0)
+        process.exit(1);
+}
+/**
+ * Render the per-alias verdict to stderr (status) — a clean line per passing
+ * alias, then `<file>:<line>:<col> - TS####: message` per error, grouped by
+ * alias, with a final tally. Lines point at the author's body (the envelope
+ * offset already removed in `checkOneWorkflowBody`).
+ */
+function printWorkflowCheckResults(projectDir, results) {
+    let totalErrors = 0;
+    for (const r of results) {
+        const rel = path.relative(projectDir, r.bodyPath);
+        if (r.issues.length === 0) {
+            console.error(`✓ ${r.alias} (${rel}) — no type errors`);
+            continue;
+        }
+        totalErrors += r.issues.length;
+        console.error(`✗ ${r.alias} (${rel}) — ${r.issues.length} error${r.issues.length === 1 ? "" : "s"}:`);
+        for (const issue of r.issues) {
+            // TS multi-line messages indent every continuation under the location line.
+            const [first, ...rest] = issue.message.split("\n");
+            console.error(`    ${rel}:${issue.line}:${issue.col} - ${issue.code}: ${first}`);
+            for (const line of rest)
+                console.error(`      ${line}`);
+        }
+    }
+    const passed = results.length - results.filter((r) => r.issues.length > 0).length;
+    console.error(totalErrors === 0
+        ? results.length === 1
+            ? `\nThe workflow body type-checks clean.`
+            : `\nAll ${results.length} workflow bodies type-check clean.`
+        : `\n${totalErrors} error${totalErrors === 1 ? "" : "s"} across ${results.length - passed} of ${results.length} ${results.length === 1 ? "body" : "bodies"}.`);
 }
 /**
  * Walk up from `start` to the monorepo's `packages/ui/src`. Returns null when

package/dist/app_commands.test.js

@@ -2,7 +2,7 @@ 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, appCodegen, appUiLink, appWorkflowSet, appWorkflowPull, appExecuteWorkflow, writeWorkflowFile, writeWorkflowGlobals, stripWorkflowHeader, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } 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
@@ -656,3 +656,71 @@ describe("appExecuteWorkflow (--print-created / --cleanup harvest)", () => {
         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[];