blokctl 0.6.21 → 1.0.0

package/dist/commands/generate/validators/WorkflowValidator.js

@@ -29,15 +29,21 @@ export function validateWorkflow(jsonString) {
             warnings: [],
         };
     }
-    validateTopLevel(workflow, errors, warnings);
+    const v2 = isV2Workflow(workflow.steps);
+    validateTopLevel(workflow, v2, errors, warnings);
     if (workflow.trigger && typeof workflow.trigger === "object") {
         validateTrigger(workflow.trigger, errors, warnings);
     }
     const stepNames = new Set();
     if (Array.isArray(workflow.steps)) {
-        validateSteps(workflow.steps, stepNames, errors, warnings);
+        if (v2) {
+            validateV2Steps(workflow.steps, stepNames, errors, warnings);
+        }
+        else {
+            validateSteps(workflow.steps, stepNames, errors, warnings);
+        }
     }
-    if (workflow.nodes && typeof workflow.nodes === "object") {
+    if (!v2 && workflow.nodes && typeof workflow.nodes === "object") {
         validateNodes(workflow.nodes, stepNames, errors, warnings);
     }
     return {
@@ -46,7 +52,17 @@ export function validateWorkflow(jsonString) {
         warnings,
     };
 }
-function validateTopLevel(workflow, errors, warnings) {
+function isV2Workflow(steps) {
+    if (!Array.isArray(steps))
+        return false;
+    return steps.some((s) => {
+        if (!s || typeof s !== "object")
+            return false;
+        const step = s;
+        return step.use !== undefined || step.branch !== undefined || (step.id !== undefined && step.name === undefined);
+    });
+}
+function validateTopLevel(workflow, v2, errors, warnings) {
     if (!workflow.name || typeof workflow.name !== "string") {
         errors.push('Missing or invalid "name" field (must be a non-empty string)');
     }
@@ -71,7 +87,7 @@ function validateTopLevel(workflow, errors, warnings) {
     else if (workflow.steps.length === 0) {
         errors.push('"steps" array must not be empty');
     }
-    if (!workflow.nodes || typeof workflow.nodes !== "object") {
+    if (!v2 && (!workflow.nodes || typeof workflow.nodes !== "object")) {
         errors.push('Missing or invalid "nodes" field (must be an object)');
     }
 }
@@ -205,6 +221,65 @@ function validateSteps(steps, stepNames, errors, warnings) {
         stepNames.add(step.name);
     }
 }
+function validateV2Steps(steps, ids, errors, warnings) {
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        if (!step || typeof step !== "object") {
+            errors.push(`Step at index ${i} must be an object`);
+            continue;
+        }
+        if (!step.id || typeof step.id !== "string") {
+            errors.push(`Step at index ${i} is missing required "id" field`);
+            continue;
+        }
+        if (ids.has(step.id)) {
+            errors.push(`Duplicate step id "${step.id}" — step ids are flat per workflow (including branch arms)`);
+        }
+        ids.add(step.id);
+        if (step.branch !== undefined) {
+            const branch = step.branch;
+            if (!branch || typeof branch !== "object") {
+                errors.push(`Step "${step.id}" has an invalid "branch" (must be an object)`);
+                continue;
+            }
+            if (!branch.when || typeof branch.when !== "string") {
+                errors.push(`Branch step "${step.id}" is missing a "when" condition string`);
+            }
+            else if (branch.when.startsWith("js/") || branch.when.startsWith("$.")) {
+                errors.push(`Branch step "${step.id}" "when" must be a raw \`ctx.*\` expression (e.g. "ctx.state.x > 10") — never "js/..." or "$...", which throw at runtime`);
+            }
+            if (!Array.isArray(branch.then) || branch.then.length === 0) {
+                errors.push(`Branch step "${step.id}" must have a non-empty "then" array`);
+            }
+            else {
+                validateV2Steps(branch.then, ids, errors, warnings);
+            }
+            if (branch.else !== undefined) {
+                if (!Array.isArray(branch.else)) {
+                    errors.push(`Branch step "${step.id}" "else" must be an array when present`);
+                }
+                else {
+                    validateV2Steps(branch.else, ids, errors, warnings);
+                }
+            }
+            continue;
+        }
+        if ((!step.use || typeof step.use !== "string") && typeof step.subworkflow !== "string") {
+            errors.push(`Step "${step.id}" is missing required "use" field (the node to run)`);
+        }
+        if (step.type !== undefined) {
+            if (typeof step.type !== "string") {
+                errors.push(`Step "${step.id}" "type" must be a string`);
+            }
+            else if (!VALID_STEP_TYPES.includes(step.type) && !step.type.startsWith("runtime.")) {
+                warnings.push(`Step "${step.id}" has unusual type "${step.type}". Common types: ${VALID_STEP_TYPES.join(", ")}`);
+            }
+        }
+        if (step.as !== undefined && step.spread !== undefined) {
+            errors.push(`Step "${step.id}" sets both "as" and "spread" — they are mutually exclusive`);
+        }
+    }
+}
 function validateNodes(nodes, stepNames, errors, warnings) {
     const allReferencedStepNames = new Set(stepNames);
     for (const [nodeName, nodeConfig] of Object.entries(nodes)) {

package/dist/commands/generate/validators/WorkflowValidator.test.js

@@ -644,4 +644,70 @@ describe("WorkflowValidator", () => {
             expect(result.valid).toBe(true);
         });
     });
+    describe("v2 workflows (inline inputs, no nodes map)", () => {
+        const base = {
+            name: "V2 Flow",
+            description: "A v2 workflow",
+            version: "1.0.0",
+            trigger: { http: { method: "GET", path: "/v2" } },
+        };
+        it("accepts a v2 workflow with id/use/inputs and no nodes map", () => {
+            const result = validateWorkflow(JSON.stringify({
+                ...base,
+                steps: [
+                    { id: "fetch", use: "@blokjs/api-call", inputs: { url: "https://x" } },
+                    { id: "respond", use: "@blokjs/respond", inputs: { body: "$.state.fetch" }, ephemeral: true },
+                ],
+            }));
+            expect(result.valid).toBe(true);
+        });
+        it("accepts a v2 branch step and validates its arm ids", () => {
+            const result = validateWorkflow(JSON.stringify({
+                ...base,
+                steps: [
+                    {
+                        id: "route",
+                        branch: {
+                            when: "ctx.req.method === 'POST'",
+                            then: [{ id: "create", use: "@blokjs/api-call", inputs: {} }],
+                            else: [{ id: "read", use: "@blokjs/api-call", inputs: {} }],
+                        },
+                    },
+                ],
+            }));
+            expect(result.valid).toBe(true);
+        });
+        it("errors on a v2 step missing use", () => {
+            const result = validateWorkflow(JSON.stringify({ ...base, steps: [{ id: "x", inputs: {} }] }));
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes('missing required "use"'))).toBe(true);
+        });
+        it("errors on a duplicate id across a branch arm", () => {
+            const result = validateWorkflow(JSON.stringify({
+                ...base,
+                steps: [
+                    { id: "dup", use: "@blokjs/api-call", inputs: {} },
+                    {
+                        id: "b",
+                        branch: { when: "ctx.state.dup.ok", then: [{ id: "dup", use: "@blokjs/respond", inputs: {} }] },
+                    },
+                ],
+            }));
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes("Duplicate step id"))).toBe(true);
+        });
+        it("errors on a branch when prefixed with js/ or $.", () => {
+            const result = validateWorkflow(JSON.stringify({
+                ...base,
+                steps: [{ id: "b", branch: { when: "js/ctx.state.x", then: [{ id: "t", use: "n", inputs: {} }] } }],
+            }));
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes("raw"))).toBe(true);
+        });
+        it("errors when a v2 step sets both as and spread", () => {
+            const result = validateWorkflow(JSON.stringify({ ...base, steps: [{ id: "x", use: "n", as: "y", spread: true, inputs: {} }] }));
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes("mutually exclusive"))).toBe(true);
+        });
+    });
 });

package/dist/commands/monitor/monitor-component.js

@@ -120,11 +120,11 @@ const fetchPrometheusMetrics = async (host, token) => {
     mapWorkflow(wfErrors, "errors", (v) => Math.round(+v));
     mapWorkflow(wfReqs, "requests", (v) => Math.round(+v));
     const nodeMetricsRaw = await Promise.all([
-        queryPrometheus("(sum(increase(node_total[1m])) by (node_name, workflow_path)) > 0", host, token),
-        queryPrometheus("sum(increase(node_time[1m])) by (node_name, workflow_path)", host, token),
-        queryPrometheus("(sum(increase(node_errors_total[1m])) by (node_name, workflow_path)) > 0", host, token),
-        queryPrometheus("sum(increase(node_cpu[1m])) by (node_name, workflow_path)", host, token),
-        queryPrometheus("sum(increase(node_memory[1m])) by (node_name, workflow_path)", host, token),
+        queryPrometheus("(sum(increase(blok_node_executions_total[1m])) by (node_name, workflow_path)) > 0", host, token),
+        queryPrometheus("sum(increase(blok_node_duration_seconds_sum[1m])) by (node_name, workflow_path)", host, token),
+        queryPrometheus("(sum(increase(blok_node_errors_total[1m])) by (node_name, workflow_path)) > 0", host, token),
+        queryPrometheus("sum(increase(blok_node_cpu_usage[1m])) by (node_name, workflow_path)", host, token),
+        queryPrometheus("sum(increase(blok_node_memory_bytes[1m])) by (node_name, workflow_path)", host, token),
     ]);
     const nodeMap = {};
     const setNodeMetric = (list, key, convert) => {

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

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

package/dist/commands/observability/add.js

@@ -0,0 +1,113 @@
+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, withObservabilityModule } from "../../services/observability-mutations.js";
+import { OBSERVABILITY_MODULE_IDS, allObservabilityModules, getObservabilityModule, resolveWithDependencies, } from "./descriptor.js";
+import { ObservabilityCommandError, readConfigSafe, readFrameworkVersion, reportObservabilityError, resolveProjectRoot, } from "./shared.js";
+export async function observabilityAdd(moduleArg, options) {
+    try {
+        const root = resolveProjectRoot(options.directory);
+        const config = readConfigSafe(root);
+        const enabled = config.observability ?? {};
+        const nonInteractive = isNonInteractive() || options.yes === true;
+        let id = moduleArg?.trim().toLowerCase();
+        if (!id) {
+            if (nonInteractive) {
+                throw new ObservabilityCommandError(`Specify a module: blokctl observability add <${OBSERVABILITY_MODULE_IDS.join("|")}>`);
+            }
+            const choices = allObservabilityModules()
+                .filter((m) => !enabled[m.id])
+                .map((m) => ({ value: m.id, label: m.label, hint: m.description }));
+            if (choices.length === 0) {
+                p.intro(color.inverse(" Add observability module "));
+                p.outro(color.dim("All observability modules are already enabled."));
+                return;
+            }
+            const picked = await p.select({ message: "Which observability module do you want to add?", options: choices });
+            if (p.isCancel(picked)) {
+                p.cancel("Cancelled.");
+                return;
+            }
+            id = picked;
+        }
+        const mod = getObservabilityModule(id);
+        if (!mod) {
+            throw new ObservabilityCommandError(`Unknown observability module "${id}". Known: ${OBSERVABILITY_MODULE_IDS.join(", ")}.`);
+        }
+        p.intro(color.inverse(` Add ${mod.label} `));
+        if (enabled[mod.id] && options.force !== true) {
+            p.outro(color.dim(`${mod.label} is already enabled. Re-run with --force to re-apply its scaffold.`));
+            return;
+        }
+        const { resolved, added } = resolveWithDependencies([mod.id]);
+        const newDeps = added.filter((d) => !enabled[d]);
+        if (newDeps.length > 0) {
+            const labels = newDeps.map((d) => getObservabilityModule(d)?.label ?? d).join(", ");
+            if (nonInteractive) {
+                p.log.info(color.dim(`Also enabling required dependencies: ${labels}`));
+            }
+            else {
+                const ok = await p.confirm({
+                    message: `${mod.label} requires ${labels}. Enable ${newDeps.length > 1 ? "them" : "it"} too?`,
+                    initialValue: true,
+                });
+                if (p.isCancel(ok) || !ok) {
+                    p.outro(color.dim("Left unchanged."));
+                    return;
+                }
+            }
+        }
+        const toApply = resolved.filter((rid) => rid === mod.id || !enabled[rid]);
+        const addedAt = new Date().toISOString();
+        const version = readFrameworkVersion(root);
+        const s = p.spinner();
+        let nextConfig = config;
+        const scaffoldOpts = {
+            projectDir: root,
+            nonInteractive,
+            tier: options.tier,
+            localRepo: options.local,
+        };
+        for (const rid of toApply) {
+            const d = getObservabilityModule(rid);
+            if (!d)
+                continue;
+            if (d.validate)
+                await d.validate(root);
+            if (d.scaffold) {
+                s.start(`Scaffolding ${d.label}…`);
+                await d.scaffold(scaffoldOpts);
+                s.stop(`${d.label} ready`);
+            }
+            if (d.setup)
+                await d.setup(scaffoldOpts);
+            const extra = rid === "obs-stack" ? { settings: { tier: options.tier ?? "lite" } } : {};
+            nextConfig = withObservabilityModule(nextConfig, rid, { enabled: true, addedAt, version, ...extra });
+        }
+        fs.mkdirSync(path.join(root, ".blok"), { recursive: true });
+        fs.writeFileSync(path.join(root, ".blok", "config.json"), `${JSON.stringify(nextConfig, null, 2)}\n`);
+        const enabledIds = Object.keys(nextConfig.observability ?? {});
+        const envBlocks = enabledIds.map((eid) => getObservabilityModule(eid)?.envBlock({ projectDir: root }) ?? "");
+        const envPath = path.join(root, ".env.local");
+        const envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+        fs.writeFileSync(envPath, rewriteObservabilityEnvBlock(envContent, envBlocks));
+        const deps = {};
+        for (const rid of toApply)
+            Object.assign(deps, getObservabilityModule(rid)?.packageDeps ?? {});
+        if (Object.keys(deps).length > 0)
+            mergePackageDeps(root, deps);
+        p.note(toApply.map((rid) => `${color.green("✓")} ${getObservabilityModule(rid)?.label ?? rid}`).join("\n"), `${mod.label} added`);
+        p.outro(color.dim(`Enabled modules: ${enabledIds.join(", ")}.`));
+    }
+    catch (err) {
+        reportObservabilityError(err);
+    }
+}
+function mergePackageDeps(root, deps) {
+    const pkgPath = path.join(root, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    pkg.dependencies = { ...(pkg.dependencies ?? {}), ...deps };
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}

package/dist/commands/observability/alerting-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 alerting = getObservabilityModule("alerting");
+const errorSink = getObservabilityModule("error-sink");
+describe("alerting + error-sink modules (MO-ALERTS)", () => {
+    it("alerting depends on metrics, declares alertmanager, and enables alerting", () => {
+        expect(alerting.dependencies).toEqual(["metrics"]);
+        expect(alerting.composeServices).toEqual(["alertmanager"]);
+        expect(alerting.envBlock({ projectDir: "/x" })).toContain("BLOK_ALERTING_ENABLED=true");
+    });
+    it("error-sink ships inert — SENTRY_DSN is commented out", () => {
+        for (const line of errorSink.envBlock({ projectDir: "/x" }).split("\n")) {
+            if (/SENTRY_DSN=/.test(line))
+                expect(line.trim().startsWith("#")).toBe(true);
+        }
+    });
+    describe("verify()", () => {
+        let tmp;
+        beforeEach(() => {
+            tmp = fs.mkdtempSync(path.join(os.tmpdir(), "blok-alerts-"));
+        });
+        afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+        it("error-sink: inert when no SENTRY_DSN", async () => {
+            fs.writeFileSync(path.join(tmp, ".env.local"), "# SENTRY_DSN=\n");
+            expect((await errorSink.verify?.(tmp))?.message).toMatch(/inert/);
+        });
+        it("error-sink: flags the missing dep when DSN is set but @sentry/node is absent", async () => {
+            fs.writeFileSync(path.join(tmp, ".env.local"), "SENTRY_DSN=https://k@e.test/1\n");
+            expect((await errorSink.verify?.(tmp))?.message).toMatch(/@sentry\/node missing/);
+        });
+        it("alerting: points at obs-stack when the rules file isn't in the project", async () => {
+            expect((await alerting.verify?.(tmp))?.message).toMatch(/obs-stack=full/);
+        });
+        it("alerting: reports rules present when they exist", async () => {
+            fs.mkdirSync(path.join(tmp, "infra", "metrics", "rules"), { recursive: true });
+            fs.writeFileSync(path.join(tmp, "infra", "metrics", "rules", "blok-alerts.yml"), "groups: []\n");
+            expect((await alerting.verify?.(tmp))?.message).toMatch(/alert rules present/);
+        });
+    });
+});

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

@@ -0,0 +1,10 @@
+import type { ObservabilityModuleConfig } from "../../services/runtime-setup.js";
+export declare function resolveObservabilitySelection(moduleIds: string[], opts: {
+    addedAt: string;
+    version?: string;
+    projectDir: string;
+}): {
+    configMap: Record<string, ObservabilityModuleConfig>;
+    envBlocks: string[];
+    added: string[];
+};

package/dist/commands/observability/apply.js

@@ -0,0 +1,11 @@
+import { getObservabilityModule, resolveWithDependencies } from "./descriptor.js";
+export function resolveObservabilitySelection(moduleIds, opts) {
+    if (moduleIds.length === 0)
+        return { configMap: {}, envBlocks: [], added: [] };
+    const { resolved, added } = resolveWithDependencies(moduleIds);
+    const configMap = {};
+    for (const id of resolved)
+        configMap[id] = { enabled: true, addedAt: opts.addedAt, version: opts.version };
+    const envBlocks = resolved.map((id) => getObservabilityModule(id)?.envBlock({ projectDir: opts.projectDir }) ?? "");
+    return { configMap, envBlocks, added };
+}

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