blokctl 0.6.21 → 0.7.0

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

@@ -0,0 +1,37 @@
+export type ObservabilityModuleId = "obs-stack" | "tracing" | "trace-store" | "metrics" | "logging" | "alerting" | "error-sink";
+export declare const OBSERVABILITY_MODULE_IDS: readonly ObservabilityModuleId[];
+export interface ObservabilityScaffoldOpts {
+    projectDir: string;
+    nonInteractive: boolean;
+    tier?: string;
+    localRepo?: string;
+}
+export interface ObservabilityModuleDescriptor {
+    id: ObservabilityModuleId;
+    label: string;
+    description: string;
+    dependencies: ObservabilityModuleId[];
+    envBlock: (opts: {
+        projectDir: string;
+    }) => string;
+    infraFiles: string[];
+    composeServices: string[];
+    packageDeps: Record<string, string>;
+    scaffold?: (opts: ObservabilityScaffoldOpts) => Promise<{
+        filesCreated: string[];
+    }>;
+    setup?: (opts: ObservabilityScaffoldOpts) => Promise<void>;
+    verify?: (projectDir: string) => Promise<{
+        ok: boolean;
+        message: string;
+        dashboardUrl?: string;
+    }>;
+    validate?: (projectDir: string) => Promise<void>;
+    cleanup?: (opts: ObservabilityScaffoldOpts) => Promise<void>;
+}
+export declare function getObservabilityModule(id: string): ObservabilityModuleDescriptor | undefined;
+export declare function allObservabilityModules(): ObservabilityModuleDescriptor[];
+export declare function resolveWithDependencies(ids: string[]): {
+    resolved: ObservabilityModuleId[];
+    added: ObservabilityModuleId[];
+};

package/dist/commands/observability/descriptor.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+export const OBSERVABILITY_MODULE_IDS = [
+    "obs-stack",
+    "tracing",
+    "trace-store",
+    "metrics",
+    "logging",
+    "alerting",
+    "error-sink",
+];
+const REGISTRY = {
+    "obs-stack": {
+        id: "obs-stack",
+        label: "Observability stack",
+        description: "Local Prometheus/Grafana/Loki/Tempo dev stack (tiered: none|lite|full)",
+        dependencies: [],
+        envBlock: () => "",
+        infraFiles: [],
+        composeServices: [],
+        packageDeps: {},
+        scaffold: async ({ projectDir, tier, localRepo }) => {
+            const { parseObsTier } = await import("../../services/obs-tiers.js");
+            const t = parseObsTier(tier ?? "lite");
+            if (t === "none")
+                return { filesCreated: [] };
+            const { resolveSdkSource } = await import("../runtime/shared.js");
+            const { setupObservabilityStack } = await import("../../services/obs-setup.js");
+            const source = await resolveSdkSource(projectDir, localRepo);
+            return { filesCreated: setupObservabilityStack(source, projectDir, t).copied };
+        },
+        verify: async (projectDir) => {
+            const compose = path.join(projectDir, "infra", "metrics", "docker-compose.yml");
+            if (!fs.existsSync(compose))
+                return { ok: true, message: "no dev stack copied (tier none)" };
+            const { parse } = await import("yaml");
+            const doc = parse(fs.readFileSync(compose, "utf8"));
+            const n = Object.keys(doc.services ?? {}).length;
+            return { ok: true, message: `dev stack present — ${n} service(s)`, dashboardUrl: "http://localhost:3000" };
+        },
+        cleanup: async ({ projectDir }) => {
+            fs.rmSync(path.join(projectDir, "infra", "metrics"), { recursive: true, force: true });
+        },
+    },
+    tracing: {
+        id: "tracing",
+        label: "Distributed tracing",
+        description: "OTLP spans + W3C propagation → Tempo/Jaeger (already wired in all triggers)",
+        dependencies: [],
+        envBlock: () => [
+            "# Tracing (tracing module). UNCOMMENT the endpoint to start exporting spans.",
+            "# Until then tracing is inert (the trigger no-ops without an endpoint).",
+            "# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318",
+            "# BLOK_TRACING_DISABLED=1  # force-disable even when an endpoint is set",
+        ].join("\n"),
+        infraFiles: [],
+        composeServices: ["tempo"],
+        packageDeps: {},
+        verify: async (projectDir) => {
+            const envPath = path.join(projectDir, ".env.local");
+            const content = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+            const active = content
+                .split("\n")
+                .map((l) => l.trim())
+                .find((l) => !l.startsWith("#") && /^OTEL_EXPORTER_OTLP_(TRACES_)?ENDPOINT=\S/.test(l));
+            if (active)
+                return { ok: true, message: `exporting spans to ${active.split("=").slice(1).join("=")}` };
+            return { ok: true, message: "added (inert) — uncomment OTEL_EXPORTER_OTLP_ENDPOINT to start exporting" };
+        },
+    },
+    "trace-store": {
+        id: "trace-store",
+        label: "Run trace store",
+        description: "Durable run history + Studio API (sqlite | postgres | memory)",
+        dependencies: [],
+        envBlock: () => [
+            "# Trace store (trace-store module). sqlite is durable + the default outside tests.",
+            "BLOK_TRACE_STORE=sqlite",
+            "BLOK_TRACE_SQLITE_PATH=.blok/trace.db",
+        ].join("\n"),
+        infraFiles: [],
+        composeServices: [],
+        packageDeps: {},
+    },
+    metrics: {
+        id: "metrics",
+        label: "Prometheus metrics",
+        description: "~33 blok_* metrics + the /metrics exporter (ON by default)",
+        dependencies: [],
+        envBlock: () => [
+            "# Metrics (metrics module). The /metrics exporter is ON by default.",
+            "# BLOK_METRICS_DISABLED=1  # uncomment to turn the exporter OFF",
+            "# BLOK_METRICS_PORT=9464   # override the default exporter port",
+        ].join("\n"),
+        infraFiles: [],
+        composeServices: [],
+        packageDeps: {},
+    },
+    logging: {
+        id: "logging",
+        label: "Structured logging → Loki",
+        description: "JSON logs (run_id/trace_id) shipped to Loki via Grafana Alloy",
+        dependencies: ["trace-store"],
+        envBlock: () => [
+            "# Logging (logging module). Structured JSON to stdout; ship to Loki via Alloy.",
+            "CONSOLE_LOG_ACTIVE=true",
+            "# BLOK_LOG_LEVEL=info",
+        ].join("\n"),
+        infraFiles: [],
+        composeServices: ["loki", "alloy"],
+        packageDeps: {},
+        verify: async (projectDir) => {
+            const envPath = path.join(projectDir, ".env.local");
+            const env = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+            const active = env
+                .split("\n")
+                .map((l) => l.trim())
+                .some((l) => !l.startsWith("#") && /^CONSOLE_LOG_ACTIVE\s*=\s*true$/i.test(l));
+            const shipper = fs.existsSync(path.join(projectDir, "infra", "metrics", "alloy-config.alloy"));
+            if (!active)
+                return { ok: true, message: "structured logging is OFF — set CONSOLE_LOG_ACTIVE=true" };
+            if (!shipper)
+                return { ok: true, message: "structured JSON logging on; add obs-stack=full to ship to Loki" };
+            return {
+                ok: true,
+                message: "shipping JSON logs to Loki via Alloy",
+                dashboardUrl: "http://localhost:3000/explore",
+            };
+        },
+    },
+    alerting: {
+        id: "alerting",
+        label: "Alerting rules",
+        description: "Prometheus alert rules + Helm PrometheusRule",
+        dependencies: ["metrics"],
+        envBlock: () => [
+            "# Alerting (alerting module). Rules live in infra/metrics/rules + the Helm PrometheusRule.",
+            "BLOK_ALERTING_ENABLED=true",
+        ].join("\n"),
+        infraFiles: [],
+        composeServices: ["alertmanager"],
+        packageDeps: {},
+        verify: async (projectDir) => {
+            const rules = path.join(projectDir, "infra", "metrics", "rules", "blok-alerts.yml");
+            if (fs.existsSync(rules))
+                return { ok: true, message: "alert rules present (validate: promtool check rules)" };
+            return { ok: true, message: "enabled; rules ship with obs-stack=full (infra/metrics/rules)" };
+        },
+    },
+    "error-sink": {
+        id: "error-sink",
+        label: "Error sink (Sentry)",
+        description: "Forward unhandled errors to a Sentry-compatible error sink (set SENTRY_DSN)",
+        dependencies: [],
+        envBlock: () => [
+            "# Error sink (error-sink module). Set a DSN to forward unhandled errors;",
+            "# unset = inert. Needs the @sentry/node peer dep installed.",
+            "# SENTRY_DSN=",
+        ].join("\n"),
+        infraFiles: [],
+        composeServices: [],
+        packageDeps: {},
+        verify: async (projectDir) => {
+            const envPath = path.join(projectDir, ".env.local");
+            const env = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+            const dsnSet = env
+                .split("\n")
+                .map((l) => l.trim())
+                .some((l) => !l.startsWith("#") && /^SENTRY_DSN=\S/.test(l));
+            const installed = fs.existsSync(path.join(projectDir, "node_modules", "@sentry", "node"));
+            if (!dsnSet)
+                return { ok: true, message: "added (inert) — set SENTRY_DSN to start forwarding errors" };
+            if (!installed)
+                return { ok: true, message: "SENTRY_DSN set but @sentry/node missing — run npm i @sentry/node" };
+            return { ok: true, message: "forwarding unhandled errors to Sentry" };
+        },
+    },
+};
+export function getObservabilityModule(id) {
+    return REGISTRY[id];
+}
+export function allObservabilityModules() {
+    return OBSERVABILITY_MODULE_IDS.map((id) => REGISTRY[id]);
+}
+export function resolveWithDependencies(ids) {
+    const out = new Set();
+    const visit = (id) => {
+        const mod = getObservabilityModule(id);
+        if (!mod)
+            throw new Error(`Unknown observability module "${id}". Known: ${OBSERVABILITY_MODULE_IDS.join(", ")}.`);
+        if (out.has(mod.id))
+            return;
+        for (const dep of mod.dependencies)
+            visit(dep);
+        out.add(mod.id);
+    };
+    for (const id of ids)
+        visit(id);
+    const resolved = OBSERVABILITY_MODULE_IDS.filter((id) => out.has(id));
+    const requested = new Set(ids);
+    const added = resolved.filter((id) => !requested.has(id));
+    return { resolved, added };
+}

package/dist/commands/observability/descriptor.test.d.ts

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

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