blokctl 0.6.21 → 0.7.0

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>;

package/dist/commands/watch/sse.js

@@ -0,0 +1,82 @@
+function parseFrame(frame) {
+    let eventType = null;
+    const dataLines = [];
+    for (const raw of frame.split("\n")) {
+        const line = raw.replace(/\r$/, "");
+        if (line.length === 0 || line.startsWith(":"))
+            continue;
+        if (line.startsWith("event:"))
+            eventType = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            dataLines.push(line.slice(5).replace(/^ /, ""));
+    }
+    if (dataLines.length === 0)
+        return null;
+    if (eventType === "connected" || eventType === "stream-end")
+        return null;
+    try {
+        const parsed = JSON.parse(dataLines.join("\n"));
+        if (parsed && typeof parsed === "object" && "runId" in parsed && "type" in parsed) {
+            return parsed;
+        }
+    }
+    catch {
+    }
+    return null;
+}
+export function parseSseBuffer(buffer) {
+    const events = [];
+    let rest = buffer.replace(/\r\n/g, "\n");
+    let sep = rest.indexOf("\n\n");
+    while (sep !== -1) {
+        const frame = rest.slice(0, sep);
+        rest = rest.slice(sep + 2);
+        const event = parseFrame(frame);
+        if (event)
+            events.push(event);
+        sep = rest.indexOf("\n\n");
+    }
+    return { events, rest };
+}
+export async function connectEventStream(baseUrl, opts, handlers) {
+    const url = new URL("/__blok/stream", baseUrl);
+    if (opts.workflows && opts.workflows.length > 0) {
+        url.searchParams.set("workflows", opts.workflows.join(","));
+    }
+    const headers = { accept: "text/event-stream" };
+    if (opts.token)
+        headers.authorization = `Bearer ${opts.token}`;
+    let res;
+    try {
+        res = await fetch(url, { headers, signal: opts.signal });
+    }
+    catch (err) {
+        if (err?.name !== "AbortError")
+            handlers.onError?.(err);
+        return;
+    }
+    if (!res.ok || !res.body) {
+        handlers.onError?.(new Error(`stream connect failed: ${res.status} ${res.statusText || ""}`.trim()));
+        return;
+    }
+    handlers.onOpen?.();
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const { events, rest } = parseSseBuffer(buffer);
+            buffer = rest;
+            for (const event of events)
+                handlers.onEvent(event);
+        }
+    }
+    catch (err) {
+        if (err?.name !== "AbortError")
+            handlers.onError?.(err);
+    }
+}

package/dist/index.d.ts

@@ -13,8 +13,10 @@ import "./commands/nodes/index.js";
 import "./commands/config/index.js";
 import "./commands/migrate/index.js";
 import "./commands/runtime/index.js";
+import "./commands/observability/index.js";
 import "./commands/graph/index.js";
 import "./commands/profile/index.js";
 import "./commands/cost/index.js";
 import "./commands/trace/index.js";
+import "./commands/watch/index.js";
 export declare const CLI_NAME = "blokctl";

package/dist/index.js

@@ -28,10 +28,12 @@ import "./commands/nodes/index.js";
 import "./commands/config/index.js";
 import "./commands/migrate/index.js";
 import "./commands/runtime/index.js";
+import "./commands/observability/index.js";
 import "./commands/graph/index.js";
 import "./commands/profile/index.js";
 import "./commands/cost/index.js";
 import "./commands/trace/index.js";
+import "./commands/watch/index.js";
 import { Command } from "commander";
 const version = await getPackageVersion();
 const exec = util.promisify(child_process.exec);
@@ -89,6 +91,8 @@ async function main() {
             .option("-m, --package-manager <value>", "Package manager: npm, yarn, pnpm, bun")
             .option("--pubsub-provider <value>", "Pub/Sub provider: gcp, aws, azure (default: gcp)")
             .option("--queue-provider <value>", "Queue provider: kafka, rabbitmq, sqs, redis (default: kafka)")
+            .option("--obs-stack <tier>", "Observability dev stack: none, lite, full (default: none)")
+            .option("--observability <list>", "Comma-separated observability modules: metrics,tracing,trace-store,logging,alerting,error-sink")
             .option("--examples", "Install example workflows and nodes")
             .action(async (options) => {
             await analytics.trackCommandExecution({

package/dist/services/obs-setup.d.ts

@@ -0,0 +1,5 @@
+import { type ObsStackTier } from "./obs-tiers.js";
+export declare function setupObservabilityStack(repoSource: string, projectDir: string, tier: ObsStackTier): {
+    copied: string[];
+};
+export declare function trimComposeServices(composePath: string, keep: string[]): void;

package/dist/services/obs-setup.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import fsExtra from "fs-extra";
+import { parse, stringify } from "yaml";
+import { TIER_DEFINITIONS } from "./obs-tiers.js";
+export function setupObservabilityStack(repoSource, projectDir, tier) {
+    const def = TIER_DEFINITIONS[tier];
+    if (tier === "none")
+        return { copied: [] };
+    const src = path.join(repoSource, "infra", "metrics");
+    const dest = path.join(projectDir, "infra", "metrics");
+    fsExtra.ensureDirSync(dest);
+    const copied = [];
+    if (def.files === "*") {
+        fsExtra.copySync(src, dest);
+        copied.push(...fsExtra.readdirSync(dest));
+    }
+    else {
+        for (const entry of def.files) {
+            const from = path.join(src, entry);
+            if (fsExtra.existsSync(from)) {
+                fsExtra.copySync(from, path.join(dest, entry));
+                copied.push(entry);
+            }
+        }
+    }
+    trimComposeServices(path.join(dest, "docker-compose.yml"), def.services);
+    return { copied };
+}
+export function trimComposeServices(composePath, keep) {
+    if (!fsExtra.existsSync(composePath))
+        return;
+    const doc = parse(fsExtra.readFileSync(composePath, "utf8"));
+    if (!doc.services)
+        return;
+    const keepSet = new Set(keep);
+    let changed = false;
+    for (const name of Object.keys(doc.services)) {
+        if (!keepSet.has(name)) {
+            delete doc.services[name];
+            changed = true;
+        }
+    }
+    for (const svc of Object.values(doc.services)) {
+        const dep = svc.depends_on;
+        if (Array.isArray(dep)) {
+            const next = dep.filter((d) => keepSet.has(d));
+            if (next.length !== dep.length) {
+                changed = true;
+                if (next.length > 0)
+                    svc.depends_on = next;
+                else
+                    svc.depends_on = undefined;
+            }
+        }
+        else if (dep && typeof dep === "object") {
+            for (const d of Object.keys(dep)) {
+                if (!keepSet.has(d)) {
+                    delete dep[d];
+                    changed = true;
+                }
+            }
+            if (Object.keys(dep).length === 0)
+                svc.depends_on = undefined;
+        }
+    }
+    if (changed)
+        fsExtra.writeFileSync(composePath, stringify(doc));
+}

package/dist/services/obs-setup.test.d.ts

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

package/dist/services/obs-setup.test.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import { setupObservabilityStack } from "./obs-setup.js";
+import { ALL_OBS_SERVICES } from "./obs-tiers.js";
+function findRepoRoot() {
+    let dir = import.meta.dirname;
+    for (let i = 0; i < 8; i++) {
+        if (fs.existsSync(path.join(dir, "infra", "metrics", "docker-compose.yml")))
+            return dir;
+        const up = path.dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    return null;
+}
+const REPO = findRepoRoot();
+const composeServices = (dir) => {
+    const doc = parse(fs.readFileSync(path.join(dir, "infra", "metrics", "docker-compose.yml"), "utf8"));
+    return Object.keys(doc.services ?? {});
+};
+describe.skipIf(!REPO)("setupObservabilityStack — tiers (MO-STACK)", () => {
+    const repo = REPO;
+    let tmp;
+    beforeEach(() => {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), "blok-obs-tier-"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    });
+    it("none: writes nothing — no infra/metrics dir", () => {
+        const res = setupObservabilityStack(repo, tmp, "none");
+        expect(res.copied).toEqual([]);
+        expect(fs.existsSync(path.join(tmp, "infra", "metrics"))).toBe(false);
+    });
+    it("lite: exactly prometheus + grafana, and no loki/tempo/alloy", () => {
+        setupObservabilityStack(repo, tmp, "lite");
+        expect(composeServices(tmp).sort()).toEqual(["grafana", "prometheus"]);
+        const m = path.join(tmp, "infra", "metrics");
+        expect(fs.existsSync(path.join(m, "prometheus.yml"))).toBe(true);
+        expect(fs.existsSync(path.join(m, "loki-config.yaml"))).toBe(false);
+        expect(fs.existsSync(path.join(m, "tempo.yaml"))).toBe(false);
+    });
+    it("lite: no kept service depends_on a trimmed-away service", () => {
+        setupObservabilityStack(repo, tmp, "lite");
+        const doc = parse(fs.readFileSync(path.join(tmp, "infra", "metrics", "docker-compose.yml"), "utf8"));
+        for (const svc of Object.values(doc.services ?? {})) {
+            const dep = svc.depends_on;
+            const deps = Array.isArray(dep) ? dep : dep ? Object.keys(dep) : [];
+            for (const d of deps)
+                expect(["prometheus", "grafana"]).toContain(d);
+        }
+    });
+    it("full: all services + the whole file set", () => {
+        setupObservabilityStack(repo, tmp, "full");
+        expect(composeServices(tmp).sort()).toEqual([...ALL_OBS_SERVICES].sort());
+        const m = path.join(tmp, "infra", "metrics");
+        expect(fs.existsSync(path.join(m, "loki-config.yaml"))).toBe(true);
+        expect(fs.existsSync(path.join(m, "tempo.yaml"))).toBe(true);
+    });
+    it("is idempotent — re-running lite yields an identical compose file", () => {
+        setupObservabilityStack(repo, tmp, "lite");
+        const composePath = path.join(tmp, "infra", "metrics", "docker-compose.yml");
+        const first = fs.readFileSync(composePath, "utf8");
+        setupObservabilityStack(repo, tmp, "lite");
+        expect(fs.readFileSync(composePath, "utf8")).toBe(first);
+    });
+});

package/dist/services/obs-tiers.d.ts

@@ -0,0 +1,9 @@
+export type ObsStackTier = "none" | "lite" | "full";
+export declare const OBS_STACK_TIERS: readonly ObsStackTier[];
+export declare const ALL_OBS_SERVICES: readonly ["prometheus", "alertmanager", "grafana", "tempo", "loki", "nginx", "alloy"];
+export interface TierDefinition {
+    services: string[];
+    files: string[] | "*";
+}
+export declare const TIER_DEFINITIONS: Record<ObsStackTier, TierDefinition>;
+export declare function parseObsTier(value: string): ObsStackTier;

package/dist/services/obs-tiers.js

@@ -0,0 +1,16 @@
+export const OBS_STACK_TIERS = ["none", "lite", "full"];
+export const ALL_OBS_SERVICES = ["prometheus", "alertmanager", "grafana", "tempo", "loki", "nginx", "alloy"];
+export const TIER_DEFINITIONS = {
+    none: { services: [], files: [] },
+    lite: {
+        services: ["prometheus", "grafana"],
+        files: ["docker-compose.yml", "prometheus.yml", "rules", "datasources.yml", "dashboards", "dashboard.json"],
+    },
+    full: { services: [...ALL_OBS_SERVICES], files: "*" },
+};
+export function parseObsTier(value) {
+    const v = value.trim().toLowerCase();
+    if (OBS_STACK_TIERS.includes(v))
+        return v;
+    throw new Error(`Invalid --obs-stack "${value}". Choose one of: ${OBS_STACK_TIERS.join(", ")}.`);
+}

package/dist/services/observability-mutations.d.ts

@@ -0,0 +1,4 @@
+import type { ObservabilityModuleConfig, ProjectConfig } from "./runtime-setup.js";
+export declare function withObservabilityModule(config: ProjectConfig, id: string, moduleConfig: ObservabilityModuleConfig): ProjectConfig;
+export declare function withoutObservabilityModule(config: ProjectConfig, id: string): ProjectConfig;
+export declare function rewriteObservabilityEnvBlock(envContent: string, moduleBlocks: string[]): string;

package/dist/services/observability-mutations.js

@@ -0,0 +1,46 @@
+const OBS_START = "# >>> Blok observability (managed by blokctl) >>>";
+const OBS_END = "# <<< Blok observability (managed by blokctl) <<<";
+export function withObservabilityModule(config, id, moduleConfig) {
+    return { ...config, observability: { ...(config.observability ?? {}), [id]: moduleConfig } };
+}
+export function withoutObservabilityModule(config, id) {
+    if (!config.observability || !(id in config.observability))
+        return config;
+    const rest = Object.fromEntries(Object.entries(config.observability).filter(([k]) => k !== id));
+    return { ...config, observability: Object.keys(rest).length === 0 ? undefined : rest };
+}
+function stripManagedBlock(envContent) {
+    const out = [];
+    let inside = false;
+    for (const line of envContent.split("\n")) {
+        if (line.trim() === OBS_START) {
+            inside = true;
+            continue;
+        }
+        if (inside) {
+            if (line.trim() === OBS_END)
+                inside = false;
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}
+export function rewriteObservabilityEnvBlock(envContent, moduleBlocks) {
+    for (const block of moduleBlocks) {
+        if (/\bBLOK_METRICS_ENABLED\b/.test(block)) {
+            throw new Error("BLOK_METRICS_ENABLED is not a supported flag — metrics are ON by default; disable with BLOK_METRICS_DISABLED=1.");
+        }
+    }
+    const cleaned = stripManagedBlock(envContent)
+        .replace(/\n{3,}/g, "\n\n")
+        .replace(/\n+$/, "");
+    const body = moduleBlocks
+        .map((b) => b.trim())
+        .filter(Boolean)
+        .join("\n\n");
+    if (!body)
+        return cleaned.length > 0 ? `${cleaned}\n` : "";
+    const block = `${OBS_START}\n${body}\n${OBS_END}`;
+    return cleaned.length > 0 ? `${cleaned}\n\n${block}\n` : `${block}\n`;
+}

package/dist/services/observability-mutations.test.d.ts

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

package/dist/services/observability-mutations.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { rewriteObservabilityEnvBlock, withObservabilityModule, withoutObservabilityModule, } from "./observability-mutations.js";
+const mod = (addedAt = "2026-01-01T00:00:00.000Z") => ({ enabled: true, addedAt });
+describe("withObservabilityModule / withoutObservabilityModule", () => {
+    it("adds a module while preserving runtimes + triggers", () => {
+        const base = { runtimes: { go: { port: 0, startCmd: "", cwd: "", kind: "go", label: "Go" } } };
+        const next = withObservabilityModule(base, "metrics", mod());
+        expect(next.observability).toEqual({ metrics: mod() });
+        expect(next.runtimes).toBe(base.runtimes);
+    });
+    it("re-adding the same module is a no-op (identical output)", () => {
+        const a = withObservabilityModule({}, "tracing", mod());
+        const b = withObservabilityModule(a, "tracing", mod());
+        expect(b).toEqual(a);
+    });
+    it("removing the last module drops the observability key entirely", () => {
+        const one = withObservabilityModule({}, "metrics", mod());
+        const gone = withoutObservabilityModule(one, "metrics");
+        expect(gone.observability).toBeUndefined();
+    });
+    it("removing an absent module is a no-op", () => {
+        const cfg = { observability: { metrics: mod() } };
+        expect(withoutObservabilityModule(cfg, "tracing")).toBe(cfg);
+    });
+    it("removing one of several keeps the rest", () => {
+        const cfg = withObservabilityModule(withObservabilityModule({}, "metrics", mod()), "tracing", mod());
+        const next = withoutObservabilityModule(cfg, "metrics");
+        expect(Object.keys(next.observability ?? {})).toEqual(["tracing"]);
+    });
+});
+describe("rewriteObservabilityEnvBlock", () => {
+    it("appends a fenced block and is idempotent (run twice = identical)", () => {
+        const blocks = ["BLOK_TRACE_STORE=sqlite", "# BLOK_METRICS_DISABLED=1"];
+        const once = rewriteObservabilityEnvBlock("PORT=4000\n", blocks);
+        const twice = rewriteObservabilityEnvBlock(once, blocks);
+        expect(twice).toBe(once);
+        expect(once).toContain("PORT=4000");
+        expect(once).toContain("BLOK_TRACE_STORE=sqlite");
+        expect(once.match(/managed by blokctl/g)?.length).toBe(2);
+    });
+    it("preserves unrelated env vars when the module set changes", () => {
+        const first = rewriteObservabilityEnvBlock("SECRET=abc\n", ["BLOK_TRACE_STORE=sqlite"]);
+        const second = rewriteObservabilityEnvBlock(first, ["CONSOLE_LOG_ACTIVE=true"]);
+        expect(second).toContain("SECRET=abc");
+        expect(second).toContain("CONSOLE_LOG_ACTIVE=true");
+        expect(second).not.toContain("BLOK_TRACE_STORE");
+    });
+    it("removes the block when no modules remain", () => {
+        const withBlock = rewriteObservabilityEnvBlock("SECRET=abc\n", ["BLOK_TRACE_STORE=sqlite"]);
+        const cleared = rewriteObservabilityEnvBlock(withBlock, []);
+        expect(cleared).toBe("SECRET=abc\n");
+        expect(cleared).not.toContain("managed by blokctl");
+    });
+    it("rejects BLOK_METRICS_ENABLED (only the DISABLED kill-switch is supported)", () => {
+        expect(() => rewriteObservabilityEnvBlock("", ["BLOK_METRICS_ENABLED=false"])).toThrow(/BLOK_METRICS_ENABLED/);
+    });
+});