blokctl 0.6.21 → 1.0.0

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/);
+    });
+});

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

@@ -23,13 +23,24 @@ export interface TriggerConfig {
     entryPoint: string;
     startCmd: string;
 }
+export interface ObservabilityModuleConfig {
+    enabled: boolean;
+    addedAt: string;
+    version?: string;
+    settings?: Record<string, unknown>;
+}
 export interface ProjectConfig {
     triggers?: Record<string, TriggerConfig>;
     runtimes?: Record<string, RuntimeConfig>;
+    observability?: Record<string, ObservabilityModuleConfig>;
 }
 export type ProjectRuntimeConfig = ProjectConfig;
 export declare function setupRuntime(runtime: RuntimeInfo, githubRepoLocal: string, projectDir: string, spinner: SpinnerHandler): Promise<RuntimeConfig>;
-export declare function writeProjectConfig(projectDir: string, runtimeConfigs: RuntimeConfig[], triggerConfigs?: TriggerConfig[]): void;
+export declare function generateGoNodeRegistry(projectDir: string): string;
+export declare function generateRustNodeRegistry(projectDir: string): string;
+export declare function generateJavaNodeRegistry(projectDir: string): string;
+export declare function generateCSharpNodeRegistry(projectDir: string): string;
+export declare function writeProjectConfig(projectDir: string, runtimeConfigs: RuntimeConfig[], triggerConfigs?: TriggerConfig[], observabilityConfigs?: Record<string, ObservabilityModuleConfig>): void;
 export declare function readProjectConfig(projectDir: string): ProjectConfig | null;
 export declare function generateRuntimeEnvVars(runtimeConfigs: RuntimeConfig[]): string;
 export declare function generateSupervisordConfig(runtimeConfigs: RuntimeConfig[]): string;