blokctl 0.6.21 → 1.0.0

package/dist/commands/observability/descriptor.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { resolveObservabilitySelection } from "./apply.js";
+import { allObservabilityModules, resolveWithDependencies } from "./descriptor.js";
+describe("resolveWithDependencies", () => {
+    it("pulls in a transitive dependency (alerting → metrics)", () => {
+        const { resolved, added } = resolveWithDependencies(["alerting"]);
+        expect(resolved).toContain("metrics");
+        expect(resolved).toContain("alerting");
+        expect(added).toEqual(["metrics"]);
+    });
+    it("logging → trace-store", () => {
+        expect(resolveWithDependencies(["logging"]).resolved).toContain("trace-store");
+    });
+    it("no spurious deps for a leaf module, and no duplicates", () => {
+        const { resolved, added } = resolveWithDependencies(["tracing", "tracing"]);
+        expect(resolved).toEqual(["tracing"]);
+        expect(added).toEqual([]);
+    });
+    it("throws on an unknown module id", () => {
+        expect(() => resolveWithDependencies(["nope"])).toThrow(/Unknown observability module/);
+    });
+    it("every dependency id is itself a real module", () => {
+        const ids = new Set(allObservabilityModules().map((m) => m.id));
+        for (const m of allObservabilityModules())
+            for (const dep of m.dependencies)
+                expect(ids.has(dep)).toBe(true);
+    });
+});
+describe("resolveObservabilitySelection (create-time)", () => {
+    const opts = { addedAt: "2026-01-01T00:00:00.000Z", version: "0.6.0", projectDir: "/tmp/x" };
+    it("empty selection → empty everything", () => {
+        expect(resolveObservabilitySelection([], opts)).toEqual({ configMap: {}, envBlocks: [], added: [] });
+    });
+    it("builds a config map for the resolved set incl. deps", () => {
+        const { configMap, added } = resolveObservabilitySelection(["alerting"], opts);
+        expect(Object.keys(configMap).sort()).toEqual(["alerting", "metrics"]);
+        expect(configMap.metrics).toEqual({ enabled: true, addedAt: opts.addedAt, version: opts.version });
+        expect(added).toEqual(["metrics"]);
+    });
+});

package/dist/commands/observability/index.d.ts

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

package/dist/commands/observability/index.js

@@ -0,0 +1,53 @@
+import { Command } from "commander";
+import { program } from "../../services/commander.js";
+import { observabilityAdd } from "./add.js";
+import { OBSERVABILITY_MODULE_IDS } from "./descriptor.js";
+import { observabilityList } from "./list.js";
+import { observabilityRemove } from "./remove.js";
+import { observabilityStatus } from "./status.js";
+const MODULE_LIST = OBSERVABILITY_MODULE_IDS.join(", ");
+const observability = new Command("observability")
+    .alias("obs")
+    .description("Add, remove, list, or check observability modules (metrics, tracing, logging, …) in a project");
+observability.action(() => {
+    observability.help();
+});
+observability
+    .command("add")
+    .description(`Enable an observability module (${MODULE_LIST})`)
+    .argument("[module]", "Module to add (omit for an interactive picker)")
+    .option("-d, --directory <path>", "Project directory (default: current directory)")
+    .option("--force", "Re-apply even if the module is already enabled")
+    .option("--tier <tier>", "obs-stack only: none | lite | full (default: lite)")
+    .option("--local <path>", "obs-stack only: copy infra from a local blok repo instead of fetching")
+    .option("-y, --yes", "Skip prompts (non-interactive; auto-enables dependencies)")
+    .action(async (moduleArg, options) => {
+    await observabilityAdd(moduleArg, options);
+});
+observability
+    .command("remove")
+    .alias("rm")
+    .description("Disable an observability module")
+    .argument("<module>", "Module to remove")
+    .option("-d, --directory <path>", "Project directory (default: current directory)")
+    .option("-y, --yes", "Skip confirmation (non-interactive)")
+    .action(async (moduleArg, options) => {
+    await observabilityRemove(moduleArg, options);
+});
+observability
+    .command("list")
+    .alias("ls")
+    .description("List enabled modules and which are available to add")
+    .option("-d, --directory <path>", "Project directory (default: current directory)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    await observabilityList(options);
+});
+observability
+    .command("status")
+    .description("Report the health of each enabled observability module")
+    .option("-d, --directory <path>", "Project directory (default: current directory)")
+    .action(async (options) => {
+    await observabilityStatus(options);
+});
+program.addCommand(observability);

package/dist/commands/observability/list.d.ts

@@ -0,0 +1,2 @@
+import type { OptionValues } from "../../services/commander.js";
+export declare function observabilityList(options: OptionValues): Promise<void>;

package/dist/commands/observability/list.js

@@ -0,0 +1,45 @@
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { allObservabilityModules } from "./descriptor.js";
+import { readConfigSafe, reportObservabilityError, resolveProjectRoot } from "./shared.js";
+export async function observabilityList(options) {
+    try {
+        const root = resolveProjectRoot(options.directory);
+        const enabled = readConfigSafe(root).observability ?? {};
+        const modules = allObservabilityModules();
+        if (options.json) {
+            console.log(JSON.stringify(modules.map((m) => ({
+                id: m.id,
+                label: m.label,
+                enabled: Boolean(enabled[m.id]?.enabled),
+                addedAt: enabled[m.id]?.addedAt,
+                dependencies: m.dependencies,
+            })), null, 2));
+            return;
+        }
+        p.intro(color.inverse(" Observability modules "));
+        const on = modules.filter((m) => enabled[m.id]?.enabled);
+        const off = modules.filter((m) => !enabled[m.id]?.enabled);
+        if (on.length > 0) {
+            p.note(on
+                .map((m) => {
+                const added = enabled[m.id]?.addedAt;
+                const when = added ? color.dim(`  added ${added.slice(0, 10)}`) : "";
+                return `${color.green("✓")} ${color.bold(m.label.padEnd(26))} ${color.dim(m.id.padEnd(13))}${when}`;
+            })
+                .join("\n"), `Enabled (${on.length})`);
+        }
+        else {
+            p.log.info(color.dim("No observability modules enabled yet."));
+        }
+        if (off.length > 0) {
+            p.note(off
+                .map((m) => `${color.bold(m.label.padEnd(26))} ${color.dim(m.description)}\n  ${color.dim(`blokctl observability add ${m.id}`)}`)
+                .join("\n"), `Available to add (${off.length})`);
+        }
+        p.outro(color.dim("Add with `blokctl observability add <id>`, remove with `… remove <id>`."));
+    }
+    catch (err) {
+        reportObservabilityError(err);
+    }
+}

package/dist/commands/observability/logging-module.test.d.ts

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

package/dist/commands/observability/logging-module.test.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getObservabilityModule } from "./descriptor.js";
+const logging = getObservabilityModule("logging");
+describe("logging module (MO-LOGGING)", () => {
+    it("depends on trace-store and declares loki + alloy compose services", () => {
+        expect(logging.dependencies).toEqual(["trace-store"]);
+        expect(logging.composeServices).toEqual(["loki", "alloy"]);
+    });
+    it("envBlock turns structured logging on", () => {
+        expect(logging.envBlock({ projectDir: "/tmp/x" })).toContain("CONSOLE_LOG_ACTIVE=true");
+    });
+    describe("verify()", () => {
+        let tmp;
+        beforeEach(() => {
+            tmp = fs.mkdtempSync(path.join(os.tmpdir(), "blok-logging-"));
+        });
+        afterEach(() => {
+            fs.rmSync(tmp, { recursive: true, force: true });
+        });
+        it("reports OFF when CONSOLE_LOG_ACTIVE isn't true", async () => {
+            fs.writeFileSync(path.join(tmp, ".env.local"), "PORT=4000\n# CONSOLE_LOG_ACTIVE=true\n");
+            const r = await logging.verify?.(tmp);
+            expect(r?.message).toMatch(/OFF/);
+        });
+        it("reports on-but-no-shipper when logging is active without the alloy config", async () => {
+            fs.writeFileSync(path.join(tmp, ".env.local"), "CONSOLE_LOG_ACTIVE=true\n");
+            const r = await logging.verify?.(tmp);
+            expect(r?.message).toMatch(/add obs-stack=full/);
+            expect(r?.dashboardUrl).toBeUndefined();
+        });
+        it("reports shipping when active AND the alloy config is present", async () => {
+            fs.writeFileSync(path.join(tmp, ".env.local"), "CONSOLE_LOG_ACTIVE=true\n");
+            fs.mkdirSync(path.join(tmp, "infra", "metrics"), { recursive: true });
+            fs.writeFileSync(path.join(tmp, "infra", "metrics", "alloy-config.alloy"), "// alloy\n");
+            const r = await logging.verify?.(tmp);
+            expect(r?.message).toMatch(/shipping JSON logs to Loki/);
+            expect(r?.dashboardUrl).toContain("/explore");
+        });
+    });
+});

package/dist/commands/observability/obs-stack-module.test.d.ts

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

package/dist/commands/observability/obs-stack-module.test.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getObservabilityModule } from "./descriptor.js";
+const obsStack = getObservabilityModule("obs-stack");
+describe("obs-stack module retrofit (MO-STACK T4)", () => {
+    let tmp;
+    beforeEach(() => {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), "blok-obsstack-"));
+    });
+    afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+    it("scaffold with tier=none is a no-op (writes nothing)", async () => {
+        const r = await obsStack.scaffold?.({ projectDir: tmp, nonInteractive: true, tier: "none" });
+        expect(r).toEqual({ filesCreated: [] });
+        expect(fs.existsSync(path.join(tmp, "infra"))).toBe(false);
+    });
+    it("verify reports tier-none when no stack is present", async () => {
+        expect((await obsStack.verify?.(tmp))?.message).toMatch(/tier none/);
+    });
+    it("verify reports the service count when a stack is present", async () => {
+        fs.mkdirSync(path.join(tmp, "infra", "metrics"), { recursive: true });
+        fs.writeFileSync(path.join(tmp, "infra", "metrics", "docker-compose.yml"), "services:\n  prometheus: {}\n  grafana: {}\n");
+        const r = await obsStack.verify?.(tmp);
+        expect(r?.message).toMatch(/2 service/);
+        expect(r?.dashboardUrl).toContain("3000");
+    });
+    it("cleanup removes the copied infra/metrics (the remove contract)", async () => {
+        fs.mkdirSync(path.join(tmp, "infra", "metrics"), { recursive: true });
+        await obsStack.cleanup?.({ projectDir: tmp, nonInteractive: true });
+        expect(fs.existsSync(path.join(tmp, "infra", "metrics"))).toBe(false);
+    });
+});

package/dist/commands/observability/remove.d.ts

@@ -0,0 +1,2 @@
+import type { OptionValues } from "../../services/commander.js";
+export declare function observabilityRemove(moduleArg: string, options: OptionValues): Promise<void>;

package/dist/commands/observability/remove.js

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { isNonInteractive } from "../../services/non-interactive.js";
+import { rewriteObservabilityEnvBlock, withoutObservabilityModule } from "../../services/observability-mutations.js";
+import { OBSERVABILITY_MODULE_IDS, getObservabilityModule } from "./descriptor.js";
+import { ObservabilityCommandError, readConfigSafe, reportObservabilityError, resolveProjectRoot } from "./shared.js";
+export async function observabilityRemove(moduleArg, options) {
+    try {
+        const id = moduleArg.trim().toLowerCase();
+        const mod = getObservabilityModule(id);
+        if (!mod) {
+            throw new ObservabilityCommandError(`Unknown observability module "${id}". Known: ${OBSERVABILITY_MODULE_IDS.join(", ")}.`);
+        }
+        const root = resolveProjectRoot(options.directory);
+        const config = readConfigSafe(root);
+        const enabled = config.observability ?? {};
+        const nonInteractive = isNonInteractive() || options.yes === true;
+        p.intro(color.inverse(` Remove ${mod.label} `));
+        if (!enabled[mod.id]) {
+            p.outro(color.dim(`${mod.label} isn't enabled in this project — nothing to remove.`));
+            return;
+        }
+        const dependents = Object.keys(enabled).filter((eid) => getObservabilityModule(eid)?.dependencies.includes(mod.id));
+        if (dependents.length > 0) {
+            const labels = dependents.map((d) => getObservabilityModule(d)?.label ?? d).join(", ");
+            p.log.warn(`${color.yellow(labels)} ${dependents.length > 1 ? "depend" : "depends"} on ${color.bold(mod.label)} — remove ${dependents.length > 1 ? "them" : "it"} too, or expect reduced function.`);
+        }
+        if (!nonInteractive) {
+            const ok = await p.confirm({ message: `Remove the ${mod.label} module?`, initialValue: false });
+            if (p.isCancel(ok) || !ok) {
+                p.outro(color.dim("Left unchanged."));
+                return;
+            }
+        }
+        if (mod.cleanup)
+            await mod.cleanup({ projectDir: root, nonInteractive });
+        const nextConfig = withoutObservabilityModule(config, mod.id);
+        fs.mkdirSync(path.join(root, ".blok"), { recursive: true });
+        fs.writeFileSync(path.join(root, ".blok", "config.json"), `${JSON.stringify(nextConfig, null, 2)}\n`);
+        const remainingIds = Object.keys(nextConfig.observability ?? {});
+        const envBlocks = remainingIds.map((eid) => getObservabilityModule(eid)?.envBlock({ projectDir: root }) ?? "");
+        const envPath = path.join(root, ".env.local");
+        if (fs.existsSync(envPath)) {
+            fs.writeFileSync(envPath, rewriteObservabilityEnvBlock(fs.readFileSync(envPath, "utf8"), envBlocks));
+        }
+        p.note([
+            `${color.red("−")} .blok/config.json   ${color.dim(`observability.${mod.id}`)}`,
+            `${color.red("−")} .env.local          ${color.dim(`${mod.label} env block`)}`,
+            mod.infraFiles.length > 0 && !mod.cleanup
+                ? `${color.yellow("•")} infra files left in place ${color.dim("(remove by hand if unused)")}`
+                : "",
+        ]
+            .filter(Boolean)
+            .join("\n"), `${mod.label} removed`);
+        p.outro(color.dim(`Re-add anytime: blokctl observability add ${mod.id}.`));
+    }
+    catch (err) {
+        reportObservabilityError(err);
+    }
+}

package/dist/commands/observability/shared.d.ts

@@ -0,0 +1,6 @@
+import { readConfigSafe, resolveProjectRoot } from "../runtime/shared.js";
+export { readConfigSafe, resolveProjectRoot };
+export declare class ObservabilityCommandError extends Error {
+}
+export declare function readFrameworkVersion(projectRoot: string): string | undefined;
+export declare function reportObservabilityError(err: unknown): void;

package/dist/commands/observability/shared.js

@@ -0,0 +1,23 @@
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { RuntimeCommandError, readConfigSafe, readFrameworkTag, resolveProjectRoot } from "../runtime/shared.js";
+export { readConfigSafe, resolveProjectRoot };
+export class ObservabilityCommandError extends Error {
+}
+export function readFrameworkVersion(projectRoot) {
+    try {
+        return readFrameworkTag(projectRoot)?.replace(/^v/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function reportObservabilityError(err) {
+    if (err instanceof ObservabilityCommandError || err instanceof RuntimeCommandError) {
+        p.cancel(err.message);
+    }
+    else {
+        p.cancel(color.red(`Unexpected error: ${err?.message ?? String(err)}`));
+    }
+    process.exitCode = 1;
+}

package/dist/commands/observability/status.d.ts

@@ -0,0 +1,2 @@
+import type { OptionValues } from "../../services/commander.js";
+export declare function observabilityStatus(options: OptionValues): Promise<void>;

package/dist/commands/observability/status.js

@@ -0,0 +1,36 @@
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { getObservabilityModule } from "./descriptor.js";
+import { readConfigSafe, reportObservabilityError, resolveProjectRoot } from "./shared.js";
+export async function observabilityStatus(options) {
+    try {
+        const root = resolveProjectRoot(options.directory);
+        const enabled = readConfigSafe(root).observability ?? {};
+        const enabledIds = Object.keys(enabled).filter((id) => enabled[id]?.enabled);
+        p.intro(color.inverse(" Observability status "));
+        if (enabledIds.length === 0) {
+            p.outro(color.dim("No observability modules enabled. Add one with `blokctl observability add <id>`."));
+            return;
+        }
+        const rows = [];
+        for (const id of enabledIds) {
+            const mod = getObservabilityModule(id);
+            if (!mod)
+                continue;
+            if (mod.verify) {
+                const res = await mod.verify(root);
+                const mark = res.ok ? color.green("✓") : color.yellow("!");
+                const link = res.dashboardUrl ? color.dim(`  ${res.dashboardUrl}`) : "";
+                rows.push(`${mark} ${color.bold(mod.label.padEnd(26))} ${res.message}${link}`);
+            }
+            else {
+                rows.push(`${color.dim("•")} ${color.bold(mod.label.padEnd(26))} ${color.dim("enabled (no health check yet)")}`);
+            }
+        }
+        p.note(rows.join("\n"), `Enabled (${enabledIds.length})`);
+        p.outro(color.dim("Health probes land with each module epic."));
+    }
+    catch (err) {
+        reportObservabilityError(err);
+    }
+}

package/dist/commands/observability/tracing-module.test.d.ts

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

package/dist/commands/observability/tracing-module.test.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getObservabilityModule } from "./descriptor.js";
+const tracing = getObservabilityModule("tracing");
+describe("tracing module (MO-TRACING)", () => {
+    it("ships inert — every OTEL_EXPORTER_OTLP_ENDPOINT line is commented out", () => {
+        const env = tracing.envBlock({ projectDir: "/tmp/x" });
+        expect(env).toContain("OTEL_EXPORTER_OTLP_ENDPOINT");
+        for (const line of env.split("\n")) {
+            if (/OTEL_EXPORTER_OTLP_ENDPOINT=/.test(line))
+                expect(line.trim().startsWith("#")).toBe(true);
+        }
+    });
+    it("declares tempo as its compose service, with no deps + no infra files", () => {
+        expect(tracing.composeServices).toEqual(["tempo"]);
+        expect(tracing.packageDeps).toEqual({});
+        expect(tracing.infraFiles).toEqual([]);
+        expect(tracing.dependencies).toEqual([]);
+    });
+    describe("verify()", () => {
+        let tmp;
+        beforeEach(() => {
+            tmp = fs.mkdtempSync(path.join(os.tmpdir(), "blok-tracing-"));
+        });
+        afterEach(() => {
+            fs.rmSync(tmp, { recursive: true, force: true });
+        });
+        it("reports inert when the endpoint is unset/commented", async () => {
+            fs.writeFileSync(path.join(tmp, ".env.local"), "PORT=4000\n# OTEL_EXPORTER_OTLP_ENDPOINT=http://x\n");
+            const r = await tracing.verify?.(tmp);
+            expect(r?.ok).toBe(true);
+            expect(r?.message).toMatch(/inert/);
+        });
+        it("reports active when the endpoint is uncommented", async () => {
+            fs.writeFileSync(path.join(tmp, ".env.local"), "OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4318\n");
+            const r = await tracing.verify?.(tmp);
+            expect(r?.message).toContain("exporting spans to http://tempo:4318");
+        });
+    });
+});

package/dist/commands/profile/index.js

@@ -43,19 +43,16 @@ program
             const host = options.host || "http://localhost:9090";
             const token = options.token;
             const topN = Number.parseInt(options.top, 10) || 10;
-            const [nodeTimeResults, _nodeCountResults, nodeMemResults, _nodeCpuResults, _nodeErrResults] = await Promise.all([
-                queryPrometheus("node_time", host, token),
-                queryPrometheus("node_total", host, token),
-                queryPrometheus("node_memory", host, token),
-                queryPrometheus("node_cpu", host, token),
-                queryPrometheus("node_errors_total", host, token),
+            const [nodeTimeResults, nodeMemResults] = await Promise.all([
+                queryPrometheus("(blok_node_duration_seconds_sum / blok_node_duration_seconds_count) * 1000", host, token),
+                queryPrometheus("blok_node_memory_bytes / 1000000", host, token),
             ]);
             const PerformanceProfiler = await getPerformanceProfiler();
             const profiler = new PerformanceProfiler({ topN });
             let hasData = false;
             for (const result of nodeTimeResults) {
-                const wf = result.metric.workflow || "unknown";
-                const node = result.metric.node || result.metric.name || "unknown";
+                const wf = result.metric.workflow_name || result.metric.workflow || "unknown";
+                const node = result.metric.node_name || result.metric.node || result.metric.name || "unknown";
                 if (workflowName && wf !== workflowName)
                     continue;
                 const timeMs = Number.parseFloat(result.value[1]) || 0;
@@ -65,8 +62,8 @@ program
                 }
             }
             for (const result of nodeMemResults) {
-                const wf = result.metric.workflow || "unknown";
-                const node = result.metric.node || result.metric.name || "unknown";
+                const wf = result.metric.workflow_name || result.metric.workflow || "unknown";
+                const node = result.metric.node_name || result.metric.node || result.metric.name || "unknown";
                 if (workflowName && wf !== workflowName)
                     continue;
                 const memMb = Number.parseFloat(result.value[1]) || 0;

package/dist/commands/watch/format.d.ts

@@ -0,0 +1,23 @@
+export interface WatchRunEvent {
+    id: string;
+    type: string;
+    runId: string;
+    workflowName: string;
+    timestamp: number;
+    nodeName?: string;
+    nodeId?: string;
+    payload?: {
+        durationMs?: number;
+        error?: {
+            message?: string;
+            code?: number | string;
+        } | unknown;
+        reason?: string;
+        [k: string]: unknown;
+    };
+}
+export interface FormatOptions {
+    color?: boolean;
+    verbose?: boolean;
+}
+export declare function formatEvent(ev: WatchRunEvent, opts?: FormatOptions): string | null;

package/dist/commands/watch/format.js

@@ -0,0 +1,60 @@
+import { createColors } from "picocolors";
+const NODE_INDENT = "  ";
+function shortRun(runId) {
+    return runId.length > 12 ? runId.slice(0, 12) : runId;
+}
+function durationMs(payload) {
+    const d = payload?.durationMs;
+    return typeof d === "number" && Number.isFinite(d) ? `${Math.round(d)}ms` : "";
+}
+function errorText(payload) {
+    const e = payload?.error;
+    if (!e || typeof e !== "object")
+        return "";
+    const code = e.code !== undefined && e.code !== null ? `${e.code} ` : "";
+    return `${code}${e.message ?? "error"}`.trim();
+}
+export function formatEvent(ev, opts = {}) {
+    const c = createColors(opts.color ?? true);
+    const verbose = opts.verbose ?? false;
+    const run = c.dim(shortRun(ev.runId));
+    const wf = c.bold(ev.workflowName || "(workflow)");
+    const node = ev.nodeName ?? "";
+    const ms = durationMs(ev.payload);
+    const err = errorText(ev.payload);
+    switch (ev.type) {
+        case "RUN_STARTED":
+            return `${c.cyan("▶")} ${wf}  ${run}  ${c.dim("started")}`;
+        case "NODE_STARTED":
+            return verbose ? `${NODE_INDENT}${c.dim("·")} ${node} ${c.dim("…")}` : null;
+        case "NODE_COMPLETED":
+            return `${NODE_INDENT}${c.green("✓")} ${node}${ms ? `  ${c.dim(ms)}` : ""}`;
+        case "NODE_CACHED":
+            return `${NODE_INDENT}${c.blue("◆")} ${node}  ${c.dim("cached")}`;
+        case "NODE_SKIPPED":
+            return verbose ? `${NODE_INDENT}${c.dim("→")} ${node}  ${c.dim("skipped")}` : null;
+        case "NODE_ATTEMPT_FAILED":
+            return `${NODE_INDENT}${c.yellow("↻")} ${node}  ${c.yellow("attempt failed")}${err ? `  ${c.dim(err)}` : ""}`;
+        case "NODE_FAILED":
+            return `${NODE_INDENT}${c.red("✗")} ${node}  ${c.red("FAILED")}${err ? `  ${c.dim(err)}` : ""}`;
+        case "RUN_COMPLETED":
+            return `${c.green("■")} ${wf}  ${run}  ${c.green("completed")}${ms ? ` ${c.dim(`(${ms})`)}` : ""}`;
+        case "RUN_FAILED":
+            return `${c.red("■")} ${wf}  ${run}  ${c.red("FAILED")}${ms ? ` ${c.dim(`(${ms})`)}` : ""}${err ? ` ${c.red(`· ${err}`)}` : ""}`;
+        case "RUN_CRASHED":
+            return `${c.red("■")} ${wf}  ${run}  ${c.red("CRASHED")}${err ? ` ${c.red(`· ${err}`)}` : ""}`;
+        case "RUN_TIMED_OUT":
+            return `${c.red("■")} ${wf}  ${run}  ${c.red("TIMED OUT")}${ms ? ` ${c.dim(`(${ms})`)}` : ""}`;
+        case "RUN_CANCELLED":
+            return `${c.yellow("■")} ${wf}  ${run}  ${c.yellow("cancelled")}`;
+        case "RUN_THROTTLED":
+            return `${c.yellow("■")} ${wf}  ${run}  ${c.yellow("throttled")}`;
+        case "RUN_QUEUED":
+        case "RUN_DELAYED":
+        case "RUN_DEBOUNCED":
+        case "RUN_EXPIRED":
+            return verbose ? `${c.dim("·")} ${wf}  ${run}  ${c.dim(ev.type.replace("RUN_", "").toLowerCase())}` : null;
+        default:
+            return null;
+    }
+}

package/dist/commands/watch/index.d.ts

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

package/dist/commands/watch/index.js

@@ -0,0 +1,53 @@
+import color from "picocolors";
+import { program, trackCommandExecution } from "../../services/commander.js";
+import { tokenManager } from "../../services/local-token-manager.js";
+import { formatEvent } from "./format.js";
+import { connectEventStream } from "./sse.js";
+program
+    .command("watch")
+    .description("Watch workflow executions live in the terminal (streams /__blok/stream)")
+    .option("-u, --url <url>", "Blok backend URL", "http://localhost:4000")
+    .option("--token <token>", "Auth token for the trace API (required in production)")
+    .option("-w, --workflow <names>", "Comma-separated workflow names to watch (default: all)")
+    .option("--verbose", "Also show node-started / skipped / scheduling events")
+    .option("--no-color", "Disable ANSI colors (pipe-friendly)")
+    .action(async (options) => {
+    await trackCommandExecution({
+        command: "watch",
+        args: options,
+        execution: async () => {
+            const url = options.url || "http://localhost:4000";
+            const token = options.token ?? tokenManager.getToken() ?? undefined;
+            const useColor = options.color !== false;
+            const verbose = Boolean(options.verbose);
+            const workflows = options.workflow
+                ? String(options.workflow)
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                : undefined;
+            const controller = new AbortController();
+            const stop = (code) => {
+                controller.abort();
+                process.stdout.write("\n");
+                process.exit(code);
+            };
+            process.once("SIGINT", () => stop(0));
+            process.once("SIGTERM", () => stop(0));
+            const where = workflows ? ` (workflows: ${workflows.join(", ")})` : "";
+            process.stdout.write(color.dim(`Watching ${url}/__blok/stream${where} — Ctrl-C to stop\n\n`));
+            await connectEventStream(url, { token, workflows, signal: controller.signal }, {
+                onEvent: (event) => {
+                    const line = formatEvent(event, { color: useColor, verbose });
+                    if (line)
+                        process.stdout.write(`${line}\n`);
+                },
+                onError: (err) => {
+                    process.stderr.write(color.red(`\nstream error: ${err.message}\n`));
+                    process.stderr.write(color.dim(`Is a Blok server running at ${url}? In production the trace API requires auth — pass --token.\n`));
+                    process.exit(1);
+                },
+            });
+        },
+    });
+});

package/dist/commands/watch/sse.d.ts

@@ -0,0 +1,16 @@
+import type { WatchRunEvent } from "./format.js";
+export interface ConnectOptions {
+    token?: string;
+    workflows?: string[];
+    signal?: AbortSignal;
+}
+export interface StreamHandlers {
+    onOpen?: () => void;
+    onEvent: (event: WatchRunEvent) => void;
+    onError?: (error: Error) => void;
+}
+export declare function parseSseBuffer(buffer: string): {
+    events: WatchRunEvent[];
+    rest: string;
+};
+export declare function connectEventStream(baseUrl: string, opts: ConnectOptions, handlers: StreamHandlers): Promise<void>;