blokctl 1.0.0 → 1.2.0

package/dist/commands/nodes/index.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { program } from "../../services/commander.js";
 import { listNodes } from "./listNodes.js";
+import { syncNodes } from "./syncNodes.js";
 const nodes = new Command("nodes").description("Inspect the node catalog of a running Blok server");
 const list = new Command("list")
     .description("List every node across all runtimes (hits GET /__blok/nodes on a running server)")
@@ -9,5 +10,14 @@ const list = new Command("list")
     .action(async (options) => {
     await listNodes(options);
 });
+const sync = new Command("sync")
+    .description("Generate typed runtimeNode stubs (one file per runtime) from the catalog at GET /__blok/nodes")
+    .option("-u, --url <value>", "Base URL of the running Blok server", "http://localhost:4000")
+    .option("-o, --out <dir>", "Output directory for the generated stubs", "nodes-gen")
+    .option("--check", "CI mode: exit non-zero if checked-in stubs drift from freshly generated (writes nothing)")
+    .action(async (options) => {
+    await syncNodes(options);
+});
 nodes.addCommand(list);
+nodes.addCommand(sync);
 program.addCommand(nodes);

package/dist/commands/nodes/listNodes.d.ts

@@ -1,12 +1,14 @@
 import type { OptionValues } from "commander";
 export interface NodeEntry {
     name: string;
+    ref?: string;
     runtime: string;
     description?: string;
     inputSchema: unknown | null;
     outputSchema: unknown | null;
     tags?: string[];
 }
+export declare function fetchCatalog(url: string | undefined): Promise<NodeEntry[] | null>;
 export declare function schemaMark(node: NodeEntry): string;
 export declare function formatCatalog(nodes: readonly NodeEntry[]): string;
 export declare function listNodes(opts: OptionValues): Promise<void>;

package/dist/commands/nodes/listNodes.js

@@ -1,4 +1,22 @@
 import color from "picocolors";
+export async function fetchCatalog(url) {
+    const baseUrl = (url ?? "http://localhost:4000").replace(/\/+$/, "");
+    const endpoint = `${baseUrl}/__blok/nodes`;
+    try {
+        const res = await fetch(endpoint);
+        if (!res.ok) {
+            console.log(color.red(`❌ ${endpoint} returned HTTP ${res.status}.`));
+            return null;
+        }
+        const body = (await res.json());
+        return body.nodes ?? [];
+    }
+    catch (err) {
+        console.log(color.red(`❌ Could not reach ${color.cyan(endpoint)} — is the Blok server running? ` +
+            `Pass --url <baseUrl> to point elsewhere. (${err.message})`));
+        return null;
+    }
+}
 export function schemaMark(node) {
     const parts = [];
     if (node.inputSchema)
@@ -28,24 +46,11 @@ export function formatCatalog(nodes) {
 }
 export async function listNodes(opts) {
     const baseUrl = (opts.url ?? "http://localhost:4000").replace(/\/+$/, "");
-    const endpoint = `${baseUrl}/__blok/nodes`;
-    let body;
-    try {
-        const res = await fetch(endpoint);
-        if (!res.ok) {
-            console.log(color.red(`❌ ${endpoint} returned HTTP ${res.status}.`));
-            process.exit(1);
-            return;
-        }
-        body = (await res.json());
-    }
-    catch (err) {
-        console.log(color.red(`❌ Could not reach ${color.cyan(endpoint)} — is the Blok server running? ` +
-            `Pass --url <baseUrl> to point elsewhere. (${err.message})`));
+    const nodes = await fetchCatalog(opts.url);
+    if (nodes === null) {
         process.exit(1);
         return;
     }
-    const nodes = body.nodes ?? [];
     if (opts.json === true) {
         console.log(JSON.stringify(nodes, null, 2));
         return;

package/dist/commands/nodes/syncNodes.d.ts

@@ -0,0 +1,7 @@
+import type { OptionValues } from "commander";
+import { type NodeEntry } from "./listNodes.js";
+export declare function jsonSchemaToTs(schema: unknown): string;
+export declare function generateRuntimeStubs(nodes: readonly NodeEntry[]): Map<string, string>;
+export declare function regenRuntimeStubs(baseUrl: string | undefined, outDir: string): Promise<number>;
+export declare function diffStubs(files: Map<string, string>, outDir: string): Promise<string[]>;
+export declare function syncNodes(opts: OptionValues): Promise<void>;

package/dist/commands/nodes/syncNodes.js

@@ -0,0 +1,138 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import color from "picocolors";
+import { nameToIdentifier } from "../gen/appTypes.js";
+import { fetchCatalog } from "./listNodes.js";
+const BANNER = "// AUTO-GENERATED by `blokctl nodes sync` — do not edit by hand.";
+export function jsonSchemaToTs(schema) {
+    if (!schema || typeof schema !== "object")
+        return "unknown";
+    const s = schema;
+    if (Array.isArray(s.enum)) {
+        return s.enum.map((v) => JSON.stringify(v)).join(" | ") || "unknown";
+    }
+    switch (s.type) {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array":
+            return `Array<${jsonSchemaToTs(s.items)}>`;
+        case "object":
+        case undefined: {
+            const props = s.properties;
+            if (!props || typeof props !== "object")
+                return "Record<string, unknown>";
+            const required = new Set(Array.isArray(s.required) ? s.required : []);
+            const fields = Object.entries(props).map(([key, value]) => {
+                const k = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+                const opt = required.has(key) ? "" : "?";
+                return `${k}${opt}: ${jsonSchemaToTs(value)}`;
+            });
+            return fields.length === 0 ? "Record<string, unknown>" : `{ ${fields.join("; ")} }`;
+        }
+        default:
+            return "unknown";
+    }
+}
+export function generateRuntimeStubs(nodes) {
+    const byRuntime = new Map();
+    for (const n of nodes) {
+        if (n.runtime === "module")
+            continue;
+        const list = byRuntime.get(n.runtime) ?? [];
+        list.push(n);
+        byRuntime.set(n.runtime, list);
+    }
+    const files = new Map();
+    for (const [runtime, entries] of [...byRuntime].sort(([a], [b]) => a.localeCompare(b))) {
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        const used = new Map();
+        const lines = [BANNER, `// Runtime: ${runtime}.`, "", 'import { runtimeNode } from "@blokjs/core";', ""];
+        for (const n of entries) {
+            let ident = nameToIdentifier(n.name);
+            if (used.has(ident) && used.get(ident) !== n.name) {
+                let i = 2;
+                while (used.has(`${ident}${i}`))
+                    i++;
+                ident = `${ident}${i}`;
+            }
+            used.set(ident, n.name);
+            const inT = jsonSchemaToTs(n.inputSchema);
+            const outT = jsonSchemaToTs(n.outputSchema);
+            const ref = n.ref ?? `${runtime}:${n.name}`;
+            lines.push(`export const ${ident} = runtimeNode<${inT}, ${outT}>(${JSON.stringify(n.name)}, ${JSON.stringify(ref)});`);
+        }
+        files.set(`${runtime}.ts`, `${lines.join("\n")}\n`);
+    }
+    return files;
+}
+export async function regenRuntimeStubs(baseUrl, outDir) {
+    const nodes = await fetchCatalog(baseUrl);
+    if (nodes === null)
+        throw new Error("catalog fetch failed");
+    const files = generateRuntimeStubs(nodes);
+    if (files.size === 0)
+        return 0;
+    await fsp.mkdir(outDir, { recursive: true });
+    for (const [filename, source] of files) {
+        await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+    }
+    return files.size;
+}
+export async function diffStubs(files, outDir) {
+    const drifted = [];
+    for (const [filename, expected] of files) {
+        let actual = null;
+        try {
+            actual = await fsp.readFile(path.join(outDir, filename), "utf8");
+        }
+        catch {
+            actual = null;
+        }
+        if (actual !== expected)
+            drifted.push(filename);
+    }
+    return drifted.sort();
+}
+export async function syncNodes(opts) {
+    const cwd = process.cwd();
+    const outDir = path.isAbsolute(opts.out ?? "")
+        ? opts.out
+        : path.join(cwd, opts.out ?? "nodes-gen");
+    const nodes = await fetchCatalog(opts.url);
+    if (nodes === null) {
+        process.exit(1);
+        return;
+    }
+    const files = generateRuntimeStubs(nodes);
+    if (files.size === 0) {
+        console.log(color.yellow("No runtime nodes found — nothing to generate (module nodes are imported directly)."));
+        return;
+    }
+    if (opts.check) {
+        const drifted = await diffStubs(files, outDir);
+        if (drifted.length > 0) {
+            console.log(color.red("❌ Stub drift detected — checked-in stubs are stale:"));
+            for (const filename of drifted) {
+                console.log(color.red(`   • ${path.join(path.relative(cwd, outDir), filename)}`));
+            }
+            console.log(color.dim("\nRun `blokctl nodes sync` to regenerate.\n"));
+            process.exit(1);
+            return;
+        }
+        console.log(color.green(`✅ Stubs in sync (${files.size} file(s) checked).`));
+        return;
+    }
+    await fsp.mkdir(outDir, { recursive: true });
+    for (const [filename, source] of files) {
+        await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+        console.log(color.green(`✅ ${color.cyan(path.join(path.relative(cwd, outDir), filename))}`));
+    }
+    console.log(color.dim(`\nGenerated ${files.size} stub file(s). Import the named factories into your workflows.\n`));
+}

package/dist/commands/nodes/syncNodes.test.d.ts

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

package/dist/commands/nodes/syncNodes.test.js

@@ -0,0 +1,322 @@
+import { promises as fsp } from "node:fs";
+import os, { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { diffStubs, generateRuntimeStubs, jsonSchemaToTs, regenRuntimeStubs, syncNodes } from "./syncNodes.js";
+describe("jsonSchemaToTs", () => {
+    it("degrades null / empty / unknown schema to unknown", () => {
+        expect(jsonSchemaToTs(null)).toBe("unknown");
+        expect(jsonSchemaToTs(undefined)).toBe("unknown");
+        expect(jsonSchemaToTs({ type: "weird-future-type" })).toBe("unknown");
+    });
+    it("renders an object schema with required/optional fields", () => {
+        const schema = {
+            type: "object",
+            properties: { prompt: { type: "string" }, count: { type: "integer" } },
+            required: ["prompt"],
+        };
+        expect(jsonSchemaToTs(schema)).toBe("{ prompt: string; count?: number }");
+    });
+    it("renders arrays and enums", () => {
+        expect(jsonSchemaToTs({ type: "array", items: { type: "string" } })).toBe("Array<string>");
+        expect(jsonSchemaToTs({ enum: ["a", "b"] })).toBe('"a" | "b"');
+    });
+});
+describe("generateRuntimeStubs", () => {
+    const fixture = [
+        {
+            name: "ask",
+            ref: "runtime.python3:ask",
+            runtime: "runtime.python3",
+            inputSchema: { type: "object", properties: { prompt: { type: "string" } }, required: ["prompt"] },
+            outputSchema: { type: "object", properties: { answer: { type: "string" } }, required: ["answer"] },
+        },
+        { name: "embed", ref: "runtime.python3:embed", runtime: "runtime.python3", inputSchema: null, outputSchema: null },
+        { name: "@blokjs/respond", ref: "@blokjs/respond", runtime: "module", inputSchema: {}, outputSchema: null },
+        { name: "fast", ref: "runtime.rust:fast", runtime: "runtime.rust", inputSchema: null, outputSchema: null },
+    ];
+    it("emits one file per runtime kind, skipping module nodes", () => {
+        const files = generateRuntimeStubs(fixture);
+        expect([...files.keys()].sort()).toEqual(["runtime.python3.ts", "runtime.rust.ts"]);
+    });
+    it("emits the banner, the import, a typed factory, and an unknown fallback factory", () => {
+        const py = generateRuntimeStubs(fixture).get("runtime.python3.ts");
+        if (!py)
+            throw new Error("expected runtime.python3.ts");
+        expect(py).toContain("// AUTO-GENERATED by `blokctl nodes sync` — do not edit by hand.");
+        expect(py).toContain('import { runtimeNode } from "@blokjs/core";');
+        expect(py).toContain('export const ask = runtimeNode<{ prompt: string }, { answer: string }>("ask", "runtime.python3:ask");');
+        expect(py).toContain('export const embed = runtimeNode<unknown, unknown>("embed", "runtime.python3:embed");');
+    });
+    it("disambiguates identical identifiers across nodes", () => {
+        const files = generateRuntimeStubs([
+            { name: "do-thing", ref: "runtime.go:do-thing", runtime: "runtime.go", inputSchema: null, outputSchema: null },
+            { name: "do.thing", ref: "runtime.go:do.thing", runtime: "runtime.go", inputSchema: null, outputSchema: null },
+        ]);
+        const go = files.get("runtime.go.ts") ?? "";
+        expect(go).toContain('runtimeNode<unknown, unknown>("do-thing", "runtime.go:do-thing")');
+        expect(go).toMatch(/export const doThing2 = runtimeNode<unknown, unknown>\("do\.thing"/);
+    });
+});
+describe("regenRuntimeStubs (blokctl dev hook)", () => {
+    afterEach(() => vi.unstubAllGlobals());
+    const catalog = [
+        { name: "ask", ref: "runtime.python3:ask", runtime: "runtime.python3", inputSchema: null, outputSchema: null },
+        { name: "@blokjs/respond", ref: "@blokjs/respond", runtime: "module", inputSchema: null, outputSchema: null },
+    ];
+    function stubFetch(impl) {
+        vi.stubGlobal("fetch", vi.fn(impl));
+    }
+    it("fetches the live catalog and writes one stub file per runtime kind", async () => {
+        stubFetch(() => new Response(JSON.stringify({ nodes: catalog }), { status: 200 }));
+        const outDir = await fsp.mkdtemp(path.join(os.tmpdir(), "blok-regen-"));
+        const count = await regenRuntimeStubs("http://localhost:4000", outDir);
+        expect(count).toBe(1);
+        const written = (await fsp.readdir(outDir)).sort();
+        expect(written).toEqual(["runtime.python3.ts"]);
+        const src = await fsp.readFile(path.join(outDir, "runtime.python3.ts"), "utf8");
+        expect(src).toContain('runtimeNode<unknown, unknown>("ask", "runtime.python3:ask")');
+    });
+    it("returns 0 and writes nothing when the catalog has only module nodes", async () => {
+        stubFetch(() => new Response(JSON.stringify({ nodes: [catalog[1]] }), { status: 200 }));
+        const outDir = await fsp.mkdtemp(path.join(os.tmpdir(), "blok-regen-"));
+        const count = await regenRuntimeStubs("http://localhost:4000", outDir);
+        expect(count).toBe(0);
+        await expect(fsp.readdir(outDir)).resolves.toEqual([]);
+    });
+    it("throws when the server is unreachable (caller decides failure policy)", async () => {
+        stubFetch(() => {
+            throw new Error("ECONNREFUSED");
+        });
+        const outDir = await fsp.mkdtemp(path.join(os.tmpdir(), "blok-regen-"));
+        await expect(regenRuntimeStubs("http://localhost:4000", outDir)).rejects.toThrow("catalog fetch failed");
+    });
+});
+describe("diffStubs (--check)", () => {
+    const fixture = [
+        { name: "ask", ref: "runtime.python3:ask", runtime: "runtime.python3", inputSchema: null, outputSchema: null },
+        { name: "fast", ref: "runtime.rust:fast", runtime: "runtime.rust", inputSchema: null, outputSchema: null },
+    ];
+    let outDir;
+    beforeEach(async () => {
+        outDir = await fsp.mkdtemp(path.join(tmpdir(), "blok-sync-check-"));
+    });
+    afterEach(async () => {
+        await fsp.rm(outDir, { recursive: true, force: true });
+    });
+    it("(a) reports no drift when on-disk stubs match generated", async () => {
+        const files = generateRuntimeStubs(fixture);
+        for (const [filename, source] of files) {
+            await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+        }
+        expect(await diffStubs(files, outDir)).toEqual([]);
+    });
+    it("(b) reports drift for a stale on-disk stub", async () => {
+        const files = generateRuntimeStubs(fixture);
+        for (const [filename, source] of files) {
+            await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+        }
+        await fsp.writeFile(path.join(outDir, "runtime.python3.ts"), "// stale hand-edit\n", "utf8");
+        expect(await diffStubs(files, outDir)).toEqual(["runtime.python3.ts"]);
+    });
+    it("(c) reports drift for a missing on-disk file", async () => {
+        const files = generateRuntimeStubs(fixture);
+        await fsp.writeFile(path.join(outDir, "runtime.rust.ts"), files.get("runtime.rust.ts") ?? "", "utf8");
+        expect(await diffStubs(files, outDir)).toEqual(["runtime.python3.ts"]);
+    });
+});
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function isSafeTypeLiteral(ts) {
+    if (ts.length === 0)
+        return false;
+    const balanced = (open, close) => {
+        let depth = 0;
+        for (const ch of ts) {
+            if (ch === open)
+                depth++;
+            else if (ch === close && --depth < 0)
+                return false;
+        }
+        return depth === 0;
+    };
+    if (!balanced("{", "}") || !balanced("<", ">") || !balanced("[", "]"))
+        return false;
+    return !/\bany\b|\$ref|#\//.test(ts);
+}
+describe("#367 — bad node names produce safe identifiers", () => {
+    it("emits valid TS identifiers for names that are not valid identifiers, preserving the original name", () => {
+        const go = generateRuntimeStubs([
+            {
+                name: "weird name!",
+                ref: "runtime.go:weird name!",
+                runtime: "runtime.go",
+                inputSchema: null,
+                outputSchema: null,
+            },
+            { name: "123start", ref: "runtime.go:123start", runtime: "runtime.go", inputSchema: null, outputSchema: null },
+            { name: "a-b.c", ref: "runtime.go:a-b.c", runtime: "runtime.go", inputSchema: null, outputSchema: null },
+        ]).get("runtime.go.ts") ?? "";
+        const idents = [...go.matchAll(/export const (\S+) =/g)].map((m) => m[1]);
+        expect(idents.length).toBe(3);
+        for (const ident of idents)
+            expect(ident).toMatch(IDENT_RE);
+        expect(go).toContain('runtimeNode<unknown, unknown>("weird name!", "runtime.go:weird name!")');
+        expect(go).toContain('runtimeNode<unknown, unknown>("123start", "runtime.go:123start")');
+        expect(go).toContain('runtimeNode<unknown, unknown>("a-b.c", "runtime.go:a-b.c")');
+        expect(go).not.toMatch(/export const 1/);
+    });
+});
+describe("#367 — JSON-Schema dialect quirks degrade safely (grounded in #364 spike)", () => {
+    const dialectCases = [
+        {
+            label: "$ref + $defs (Rust/C#/Python nested model)",
+            schema: {
+                type: "object",
+                properties: { user: { $ref: "#/$defs/User" }, tags: { type: "array", items: { type: "string" } } },
+                required: ["user"],
+                $defs: { User: { type: "object", properties: { id: { type: "string" } } } },
+            },
+        },
+        {
+            label: "anyOf nullable (Pydantic Optional)",
+            schema: { type: "object", properties: { nickname: { anyOf: [{ type: "string" }, { type: "null" }] } } },
+        },
+        {
+            label: "oneOf union (Rust enum)",
+            schema: { oneOf: [{ type: "object", properties: { a: { type: "string" } } }, { type: "string" }] },
+        },
+        {
+            label: "format: date-time string",
+            schema: { type: "string", format: "date-time" },
+        },
+        {
+            label: "type-array nullable [string, null]",
+            schema: { type: ["string", "null"] },
+        },
+    ];
+    for (const { label, schema } of dialectCases) {
+        it(`degrades ${label} to a safe type without throwing`, () => {
+            let out = "";
+            expect(() => {
+                out = jsonSchemaToTs(schema);
+            }).not.toThrow();
+            expect(isSafeTypeLiteral(out)).toBe(true);
+        });
+    }
+    it("format: date-time preserves the base `string` type (lossless degrade)", () => {
+        expect(jsonSchemaToTs({ type: "string", format: "date-time" })).toBe("string");
+    });
+    it("type-array nullable degrades to `unknown` (most-conservative safe type)", () => {
+        expect(jsonSchemaToTs({ type: ["string", "null"] })).toBe("unknown");
+    });
+    it("a whole dialect catalog compiles to valid stub TS without throwing", () => {
+        const nodes = dialectCases.map((c, i) => ({
+            name: `n${i}`,
+            ref: `runtime.python3:n${i}`,
+            runtime: "runtime.python3",
+            inputSchema: c.schema,
+            outputSchema: null,
+        }));
+        const src = generateRuntimeStubs(nodes).get("runtime.python3.ts") ?? "";
+        const factoryLines = src.split("\n").filter((l) => l.startsWith("export const "));
+        expect(factoryLines.length).toBe(dialectCases.length);
+        for (const line of factoryLines)
+            expect(line).not.toMatch(/\bany\b|\$ref|#\//);
+        expect(isSafeTypeLiteral(src)).toBe(true);
+    });
+});
+describe("#371 — `--check` drift detection (CLI flow)", () => {
+    const catalog = [
+        { name: "ask", ref: "runtime.python3:ask", runtime: "runtime.python3", inputSchema: null, outputSchema: null },
+        { name: "fast", ref: "runtime.rust:fast", runtime: "runtime.rust", inputSchema: null, outputSchema: null },
+    ];
+    let outDir;
+    let exitSpy;
+    beforeEach(async () => {
+        outDir = await fsp.mkdtemp(path.join(tmpdir(), "blok-check-cli-"));
+        exitSpy = vi.spyOn(process, "exit").mockImplementation(((_code) => undefined));
+        vi.spyOn(console, "log").mockImplementation(() => undefined);
+    });
+    afterEach(async () => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+        await fsp.rm(outDir, { recursive: true, force: true });
+    });
+    function stubFetch(impl) {
+        vi.stubGlobal("fetch", vi.fn(impl));
+    }
+    const okCatalog = () => new Response(JSON.stringify({ nodes: catalog }), { status: 200 });
+    it("(a) in-sync stubs → no drift, never exits non-zero", async () => {
+        stubFetch(okCatalog);
+        for (const [filename, source] of generateRuntimeStubs(catalog)) {
+            await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+        }
+        await syncNodes({ url: "http://localhost:4000", out: outDir, check: true });
+        for (const call of exitSpy.mock.calls)
+            expect(call[0]).not.toBe(1);
+    });
+    it("(b) stale on-disk stub → exits non-zero", async () => {
+        stubFetch(okCatalog);
+        await fsp.writeFile(path.join(outDir, "runtime.python3.ts"), "// stale\n", "utf8");
+        for (const [filename, source] of generateRuntimeStubs(catalog)) {
+            if (filename === "runtime.python3.ts")
+                continue;
+            await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+        }
+        await syncNodes({ url: "http://localhost:4000", out: outDir, check: true });
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+    it("(c) UNREACHABLE runtime → exits 1, NEVER a false 'in sync' (key safety case)", async () => {
+        stubFetch(() => {
+            throw new Error("ECONNREFUSED");
+        });
+        for (const [filename, source] of generateRuntimeStubs(catalog)) {
+            await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+        }
+        await syncNodes({ url: "http://localhost:4000", out: outDir, check: true });
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        const logged = console.log.mock.calls.flat().join("\n");
+        expect(logged).not.toMatch(/in sync/i);
+    });
+    it("(c') non-ok HTTP (server up, endpoint errors) → exits 1, no false 'in sync'", async () => {
+        stubFetch(() => new Response("boom", { status: 500 }));
+        for (const [filename, source] of generateRuntimeStubs(catalog)) {
+            await fsp.writeFile(path.join(outDir, filename), source, "utf8");
+        }
+        await syncNodes({ url: "http://localhost:4000", out: outDir, check: true });
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        const logged = console.log.mock.calls.flat().join("\n");
+        expect(logged).not.toMatch(/in sync/i);
+    });
+});
+describe("#369 — regen does not clobber good stubs on an empty catalog", () => {
+    afterEach(() => vi.unstubAllGlobals());
+    function stubFetch(impl) {
+        vi.stubGlobal("fetch", vi.fn(impl));
+    }
+    it("module-only / empty catalog returns 0 and leaves pre-existing stub files untouched", async () => {
+        const outDir = await fsp.mkdtemp(path.join(tmpdir(), "blok-noclobber-"));
+        const goodStub = generateRuntimeStubs([
+            { name: "ask", ref: "runtime.python3:ask", runtime: "runtime.python3", inputSchema: null, outputSchema: null },
+        ]).get("runtime.python3.ts");
+        if (!goodStub)
+            throw new Error("expected a good stub fixture");
+        const goodPath = path.join(outDir, "runtime.python3.ts");
+        await fsp.writeFile(goodPath, goodStub, "utf8");
+        stubFetch(() => new Response(JSON.stringify({
+            nodes: [
+                {
+                    name: "@blokjs/respond",
+                    ref: "@blokjs/respond",
+                    runtime: "module",
+                    inputSchema: null,
+                    outputSchema: null,
+                },
+            ],
+        }), { status: 200 }));
+        const count = await regenRuntimeStubs("http://localhost:4000", outDir);
+        expect(count).toBe(0);
+        expect(await fsp.readFile(goodPath, "utf8")).toBe(goodStub);
+        await fsp.rm(outDir, { recursive: true, force: true });
+    });
+});

package/dist/commands/publish/workflow.d.ts

@@ -1,4 +1,5 @@
 import { Command, type OptionValues } from "../../services/commander.js";
+export declare function assertPublishableWorkflow(workflow: unknown, name: string): void;
 export declare function publish(opts: OptionValues): Promise<void>;
 declare const _default: Command;
 export default _default;

package/dist/commands/publish/workflow.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as p from "@clack/prompts";
+import { validateWorkflow } from "@blokjs/helper";
 import { Command, trackCommandExecution } from "../../services/commander.js";
 import { BLOK_URL } from "../../services/constants.js";
 import { tokenManager } from "../../services/local-token-manager.js";
@@ -52,7 +53,15 @@ async function loadWorkflowFiles(directory) {
         };
     });
 }
+export function assertPublishableWorkflow(workflow, name) {
+    const result = validateWorkflow(workflow);
+    if (result.ok)
+        return;
+    const details = result.errors.map((e) => `  • ${e.path ? `${e.path}: ` : ""}${e.message}`).join("\n");
+    throw new Error(`Workflow "${name}" failed validation — not published:\n${details}`);
+}
 async function publishWorkflow(token, workflow, name) {
+    assertPublishableWorkflow(workflow, name);
     const response = await fetch(`${BLOK_URL}/publish-workflow`, {
         method: "POST",
         headers: {

package/dist/commands/publish/workflow.test.d.ts

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

package/dist/commands/publish/workflow.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { assertPublishableWorkflow } from "./workflow";
+const validV2 = {
+    name: "auth-check",
+    version: "1.0.0",
+    trigger: { http: { method: "GET", path: "/x" } },
+    steps: [{ id: "check", use: "@blokjs/respond" }],
+};
+describe("assertPublishableWorkflow (#385) — IR admission gate before publish", () => {
+    it("passes a valid v2 workflow", () => {
+        expect(() => assertPublishableWorkflow(validV2, "auth-check")).not.toThrow();
+    });
+    it("rejects a non-object (malformed IR)", () => {
+        expect(() => assertPublishableWorkflow(null, "bad")).toThrow(/failed validation/);
+    });
+    it("rejects an object with no steps array (not a workflow)", () => {
+        expect(() => assertPublishableWorkflow({ name: "x", version: "1.0.0" }, "x")).toThrow(/failed validation/);
+    });
+    it("names the workflow in the error so the operator knows which file is bad", () => {
+        expect(() => assertPublishableWorkflow({}, "myflow")).toThrow(/"myflow"/);
+    });
+});

package/dist/services/observability-stack.real-prometheus.test.d.ts

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