blokctl 0.6.19 → 0.6.20

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

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

package/dist/commands/runtime/add.js

@@ -0,0 +1,143 @@
+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 { detectRuntimes, getRuntimeDefinition } from "../../services/runtime-detector.js";
+import { ensureRuntimeGitignore, rewriteRuntimeEnvBlock, rewriteSupervisordRuntimes, runtimeEnvKey, withRuntime, } from "../../services/runtime-mutations.js";
+import { setupRuntime } from "../../services/runtime-setup.js";
+import { RuntimeCommandError, assertGrpcPortFree, assertSidecarKind, readConfigSafe, reportRuntimeError, resolveProjectRoot, resolveSdkSource, } from "./shared.js";
+export async function runtimeAdd(kindArg, options) {
+    try {
+        let grpcPortOverride;
+        if (options.grpcPort !== undefined) {
+            const parsed = Number(options.grpcPort);
+            if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+                throw new RuntimeCommandError(`--grpc-port must be an integer 1-65535 (got "${options.grpcPort}").`);
+            }
+            grpcPortOverride = parsed;
+        }
+        const root = resolveProjectRoot(options.directory);
+        const config = readConfigSafe(root);
+        const installedKinds = Object.keys(config.runtimes ?? {});
+        const nonInteractive = isNonInteractive() || options.yes === true;
+        let detected;
+        let kind = kindArg?.trim().toLowerCase();
+        if (!kind) {
+            if (nonInteractive) {
+                throw new RuntimeCommandError("Specify a runtime: blokctl runtime add <go|rust|java|csharp|php|ruby|python3>");
+            }
+            detected = await detectRuntimes();
+            const choices = detected
+                .filter((d) => !installedKinds.includes(d.kind))
+                .map((d) => ({
+                value: d.kind,
+                label: d.label,
+                hint: d.available ? `${d.toolchain} ready` : `needs ${d.toolchain}`,
+            }));
+            if (choices.length === 0) {
+                p.intro(color.inverse(" Add runtime "));
+                p.outro(color.dim("All supported runtimes are already installed."));
+                return;
+            }
+            const picked = await p.select({ message: "Which runtime do you want to add?", options: choices });
+            if (p.isCancel(picked)) {
+                p.cancel("Cancelled.");
+                return;
+            }
+            kind = picked;
+        }
+        assertSidecarKind(kind);
+        const def = getRuntimeDefinition(kind);
+        if (!def)
+            throw new RuntimeCommandError(`Unknown runtime "${kind}".`);
+        const sdkDir = path.join(root, ".blok", "runtimes", kind);
+        const alreadyInstalled = Boolean(config.runtimes?.[kind]) || fs.existsSync(sdkDir);
+        p.intro(color.inverse(` Add ${def.label} runtime `));
+        if (alreadyInstalled && options.force !== true) {
+            if (nonInteractive) {
+                p.outro(color.dim(`${def.label} is already installed. Re-run with --force to reinstall.`));
+                return;
+            }
+            const reinstall = await p.confirm({
+                message: `${def.label} is already installed. Reinstall it?`,
+                initialValue: false,
+            });
+            if (p.isCancel(reinstall) || !reinstall) {
+                p.outro(color.dim("Left unchanged."));
+                return;
+            }
+        }
+        const rt = (detected ?? (await detectRuntimes())).find((d) => d.kind === kind);
+        if (!rt)
+            throw new RuntimeCommandError(`Unknown runtime "${kind}".`);
+        if (!rt.available && options.skipToolchainCheck !== true) {
+            let missing = rt.toolchain;
+            let hint = rt.installHint;
+            if (rt.secondaryTool && rt.secondaryTool.available === false) {
+                missing = rt.secondaryTool.name;
+                hint = rt.secondaryTool.installHint;
+            }
+            throw new RuntimeCommandError(`${def.label} toolchain not detected (need ${color.bold(missing)}). ${hint}\n  Already have it? Re-run with --skip-toolchain-check.`);
+        }
+        const grpcPort = grpcPortOverride ?? rt.defaultGrpcPort;
+        const clash = Object.values(config.runtimes ?? {}).find((rc) => rc.kind !== kind && rc.grpcPort === grpcPort);
+        if (clash) {
+            throw new RuntimeCommandError(`gRPC port ${grpcPort} is already used by the ${clash.label} runtime. Pass --grpc-port <n> to pick another.`);
+        }
+        if (!alreadyInstalled)
+            await assertGrpcPortFree(grpcPort);
+        const s = p.spinner();
+        s.start("Resolving SDK source…");
+        const source = await resolveSdkSource(root, options.local, (msg) => s.message(msg));
+        if (alreadyInstalled)
+            fs.rmSync(sdkDir, { recursive: true, force: true });
+        let rc;
+        try {
+            rc = await setupRuntime(rt, source, root, s);
+        }
+        catch (err) {
+            fs.rmSync(sdkDir, { recursive: true, force: true });
+            s.stop(color.red(`${def.label} setup failed`));
+            throw new RuntimeCommandError(`${def.label} setup failed: ${err.message.split("\n")[0]}`);
+        }
+        if (grpcPortOverride !== undefined) {
+            rc.grpcPort = grpcPortOverride;
+            if (rc.grpcStartCmd)
+                rc.grpcStartCmd = rc.grpcStartCmd.split(String(rt.defaultGrpcPort)).join(String(grpcPortOverride));
+        }
+        s.stop(`${def.label} runtime ready`);
+        const nextConfig = withRuntime(config, rc);
+        const remaining = Object.values(nextConfig.runtimes ?? {});
+        fs.mkdirSync(path.join(root, ".blok"), { recursive: true });
+        fs.writeFileSync(path.join(root, ".blok", "config.json"), `${JSON.stringify(nextConfig, null, 2)}\n`);
+        const envPath = path.join(root, ".env.local");
+        const envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+        fs.writeFileSync(envPath, rewriteRuntimeEnvBlock(envContent, remaining));
+        const supervisordPath = path.join(root, "supervisord.conf");
+        if (fs.existsSync(supervisordPath)) {
+            fs.writeFileSync(supervisordPath, rewriteSupervisordRuntimes(fs.readFileSync(supervisordPath, "utf8"), remaining));
+        }
+        const gitignorePath = path.join(root, ".gitignore");
+        if (fs.existsSync(gitignorePath)) {
+            const before = fs.readFileSync(gitignorePath, "utf8");
+            const after = ensureRuntimeGitignore(before);
+            if (after !== before)
+                fs.writeFileSync(gitignorePath, after);
+        }
+        p.note([
+            `${color.green("✓")} .blok/config.json   ${color.dim(`runtimes.${kind}`)}`,
+            `${color.green("✓")} .env.local          ${color.dim(`RUNTIME_${runtimeEnvKey(kind)}_GRPC_PORT=${rc.grpcPort}`)}`,
+            fs.existsSync(supervisordPath)
+                ? `${color.green("✓")} supervisord.conf    ${color.dim(`[program:${kind}_runtime]`)}`
+                : "",
+            `${color.green("✓")} runtimes/${kind}/nodes/  ${color.dim("(your runtime nodes go here)")}`,
+        ]
+            .filter(Boolean)
+            .join("\n"), `${def.label} added`);
+        p.outro(`Run ${color.cyan("blokctl dev")} to start it, then add ${color.cyan(`type: "runtime.${kind}"`)} steps to your workflows.`);
+    }
+    catch (err) {
+        reportRuntimeError(err);
+    }
+}

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

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

package/dist/commands/runtime/index.js

@@ -0,0 +1,43 @@
+import { Command } from "commander";
+import { program } from "../../services/commander.js";
+import { runtimeAdd } from "./add.js";
+import { runtimeList } from "./list.js";
+import { runtimeRemove } from "./remove.js";
+const runtime = new Command("runtime").description("Add, remove, or list language runtimes in an existing project");
+runtime.action(() => {
+    runtime.help();
+});
+runtime
+    .command("add")
+    .description("Add a language runtime (go, rust, java, csharp, php, ruby, python3) to this project")
+    .argument("[runtime]", "Runtime to add (omit for an interactive picker)")
+    .option("-d, --directory <path>", "Project directory (default: current directory)")
+    .option("--local <path>", "Use a local blok repo for SDK source instead of fetching by version")
+    .option("--grpc-port <port>", "Override the gRPC port for this runtime")
+    .option("--force", "Reinstall if the runtime is already present")
+    .option("--skip-toolchain-check", "Add even if the language toolchain isn't detected")
+    .option("-y, --yes", "Skip prompts (non-interactive)")
+    .action(async (runtimeArg, options) => {
+    await runtimeAdd(runtimeArg, options);
+});
+runtime
+    .command("remove")
+    .alias("rm")
+    .description("Remove a language runtime from this project")
+    .argument("<runtime>", "Runtime to remove")
+    .option("-d, --directory <path>", "Project directory (default: current directory)")
+    .option("--purge-nodes", "Also delete your custom nodes in runtimes/<runtime>/nodes/")
+    .option("-y, --yes", "Skip prompts (keeps your custom nodes)")
+    .action(async (runtimeArg, options) => {
+    await runtimeRemove(runtimeArg.toLowerCase(), options);
+});
+runtime
+    .command("list")
+    .alias("ls")
+    .description("List installed runtimes and which are available to add")
+    .option("-d, --directory <path>", "Project directory (default: current directory)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+    await runtimeList(options);
+});
+program.addCommand(runtime);

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

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

package/dist/commands/runtime/list.js

@@ -0,0 +1,60 @@
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { detectRuntimes } from "../../services/runtime-detector.js";
+import { readConfigSafe, reportRuntimeError, resolveProjectRoot } from "./shared.js";
+export async function runtimeList(options) {
+    try {
+        const root = resolveProjectRoot(options.directory);
+        const installed = readConfigSafe(root).runtimes ?? {};
+        const detected = await detectRuntimes();
+        const detectedByKind = new Map(detected.map((d) => [d.kind, d]));
+        const installedKinds = Object.keys(installed);
+        if (options.json) {
+            console.log(JSON.stringify({
+                installed: installedKinds.map((kind) => ({
+                    kind,
+                    label: installed[kind].label,
+                    grpcPort: installed[kind].grpcPort,
+                    version: installed[kind].version,
+                    requiredVersion: installed[kind].requiredVersion,
+                    toolchainAvailable: detectedByKind.get(kind)?.available ?? false,
+                })),
+                available: detected
+                    .filter((d) => !(d.kind in installed))
+                    .map((d) => ({ kind: d.kind, label: d.label, toolchainAvailable: d.available })),
+            }, null, 2));
+            return;
+        }
+        p.intro(color.inverse(" Blok runtimes "));
+        if (installedKinds.length === 0) {
+            p.log.info(color.dim("No sidecar runtimes installed yet."));
+        }
+        else {
+            const rows = installedKinds.map((kind) => {
+                const rc = installed[kind];
+                const d = detectedByKind.get(kind);
+                const ready = d?.available ?? false;
+                const mark = ready ? color.green("✓") : color.yellow("!");
+                const port = color.dim(`gRPC :${rc.grpcPort ?? "?"}`.padEnd(14));
+                const tool = ready
+                    ? color.dim(`${d?.toolchain} ${d?.version ?? ""}`.trim())
+                    : color.yellow("toolchain not detected");
+                return `${mark} ${color.bold(rc.label.padEnd(12))} ${port} ${tool}`;
+            });
+            p.note(rows.join("\n"), `Installed (${installedKinds.length})`);
+        }
+        const available = detected.filter((d) => !(d.kind in installed));
+        if (available.length > 0) {
+            const rows = available.map((d) => {
+                const statusText = (d.available ? `${d.toolchain} ready` : `needs ${d.toolchain}`).padEnd(20);
+                const status = d.available ? color.green(statusText) : color.dim(statusText);
+                return `${color.bold(d.label.padEnd(12))} ${status} ${color.dim(`blokctl runtime add ${d.kind}`)}`;
+            });
+            p.note(rows.join("\n"), `Available to add (${available.length})`);
+        }
+        p.outro(color.dim("Node / TypeScript runs in-process — always available, nothing to install."));
+    }
+    catch (err) {
+        reportRuntimeError(err);
+    }
+}

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

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

package/dist/commands/runtime/remove.js

@@ -0,0 +1,114 @@
+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 { getRuntimeDefinition } from "../../services/runtime-detector.js";
+import { rewriteRuntimeEnvBlock, rewriteSupervisordRuntimes, runtimeEnvKey, withoutRuntime, } from "../../services/runtime-mutations.js";
+import { assertSidecarKind, listUserNodes, readConfigSafe, reportRuntimeError, resolveProjectRoot, scanWorkflowsForRuntime, } from "./shared.js";
+export async function runtimeRemove(kind, options) {
+    try {
+        assertSidecarKind(kind);
+        const root = resolveProjectRoot(options.directory);
+        const nonInteractive = isNonInteractive() || options.yes === true;
+        const label = getRuntimeDefinition(kind)?.label ?? kind;
+        const config = readConfigSafe(root);
+        const sdkDir = path.join(root, ".blok", "runtimes", kind);
+        const inConfig = Boolean(config.runtimes?.[kind]);
+        const onDisk = fs.existsSync(sdkDir);
+        if (!inConfig && !onDisk) {
+            p.intro(color.inverse(` Remove ${label} runtime `));
+            p.outro(color.dim(`${label} isn't installed in this project — nothing to remove.`));
+            return;
+        }
+        p.intro(color.inverse(` Remove ${label} runtime `));
+        const hits = scanWorkflowsForRuntime(root, kind);
+        if (hits.length > 0) {
+            const list = hits
+                .slice(0, 10)
+                .map((h) => `  ${color.yellow("•")} ${h.file}${h.count > 1 ? color.dim(` (${h.count} refs)`) : ""}`)
+                .join("\n");
+            const more = hits.length > 10 ? `\n  ${color.dim(`…and ${hits.length - 10} more`)}` : "";
+            p.log.warn(`${color.yellow(`${hits.length} workflow file(s)`)} reference ${color.bold(`runtime.${kind}`)} — those steps will fail at run time after removal:\n${list}${more}`);
+        }
+        const userNodes = listUserNodes(root, kind);
+        let deleteNodes = false;
+        if (!userNodes.isSymlink && userNodes.files.length > 0) {
+            if (options.purgeNodes === true) {
+                deleteNodes = true;
+            }
+            else if (nonInteractive) {
+                deleteNodes = false;
+                p.log.info(color.dim(`Keeping your ${userNodes.files.length} node file(s) in runtimes/${kind}/nodes/ (use --purge-nodes to delete).`));
+            }
+            else {
+                const answer = await p.confirm({
+                    message: `Also delete your ${color.bold(`${userNodes.files.length} custom node file(s)`)} in runtimes/${kind}/nodes/?`,
+                    initialValue: false,
+                });
+                deleteNodes = !p.isCancel(answer) && answer === true;
+            }
+        }
+        if (!nonInteractive) {
+            const ok = await p.confirm({ message: `Remove the ${label} runtime?`, initialValue: false });
+            if (p.isCancel(ok) || !ok) {
+                p.outro(color.dim("Left unchanged."));
+                return;
+            }
+        }
+        const s = p.spinner();
+        s.start(`Removing ${label} runtime…`);
+        const nextConfig = withoutRuntime(config, kind);
+        fs.mkdirSync(path.join(root, ".blok"), { recursive: true });
+        fs.writeFileSync(path.join(root, ".blok", "config.json"), `${JSON.stringify(nextConfig, null, 2)}\n`);
+        const remaining = Object.values(nextConfig.runtimes ?? {});
+        const envPath = path.join(root, ".env.local");
+        if (fs.existsSync(envPath)) {
+            fs.writeFileSync(envPath, rewriteRuntimeEnvBlock(fs.readFileSync(envPath, "utf8"), remaining));
+        }
+        const supervisordPath = path.join(root, "supervisord.conf");
+        if (fs.existsSync(supervisordPath)) {
+            fs.writeFileSync(supervisordPath, rewriteSupervisordRuntimes(fs.readFileSync(supervisordPath, "utf8"), remaining));
+        }
+        fs.rmSync(sdkDir, { recursive: true, force: true });
+        const projRuntimeDir = path.join(root, "runtimes", kind);
+        const tryLstat = (target) => {
+            try {
+                return fs.lstatSync(target);
+            }
+            catch {
+                return null;
+            }
+        };
+        for (const name of ["nodes", "core"]) {
+            const link = path.join(projRuntimeDir, name);
+            if (tryLstat(link)?.isSymbolicLink())
+                fs.unlinkSync(link);
+        }
+        if (deleteNodes)
+            fs.rmSync(path.join(projRuntimeDir, "nodes"), { recursive: true, force: true });
+        if (fs.existsSync(projRuntimeDir) && fs.readdirSync(projRuntimeDir).length === 0)
+            fs.rmdirSync(projRuntimeDir);
+        s.stop(`${label} runtime removed`);
+        const keptNodes = !deleteNodes && !userNodes.isSymlink && userNodes.files.length > 0;
+        p.note([
+            `${color.red("−")} .blok/config.json   ${color.dim(`runtimes.${kind}`)}`,
+            `${color.red("−")} .env.local          ${color.dim(`RUNTIME_${runtimeEnvKey(kind)}_*`)}`,
+            fs.existsSync(supervisordPath)
+                ? `${color.red("−")} supervisord.conf    ${color.dim(`[program:${kind}_runtime]`)}`
+                : "",
+            `${color.red("−")} .blok/runtimes/${kind}/  ${color.dim("(SDK source + build output)")}`,
+            keptNodes
+                ? `${color.green("✓")} runtimes/${kind}/nodes/  ${color.dim(`kept your ${userNodes.files.length} node file(s)`)}`
+                : "",
+        ]
+            .filter(Boolean)
+            .join("\n"), `${label} removed`);
+        p.outro(hits.length > 0
+            ? color.yellow(`Update the ${hits.length} workflow(s) that referenced runtime.${kind}. Re-add anytime: blokctl runtime add ${kind}.`)
+            : color.dim(`Done. Re-add anytime: blokctl runtime add ${kind}.`));
+    }
+    catch (err) {
+        reportRuntimeError(err);
+    }
+}

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

@@ -0,0 +1,22 @@
+import { type ProjectConfig } from "../../services/runtime-setup.js";
+export declare const NON_SIDECAR_KINDS: Set<string>;
+export declare class RuntimeCommandError extends Error {
+}
+export declare function readConfigSafe(projectRoot: string): ProjectConfig;
+export declare function assertGrpcPortFree(grpcPort: number): Promise<void>;
+export declare function resolveProjectRoot(directory?: string): string;
+export declare function readFrameworkTag(projectRoot: string): string | null;
+export declare function resolveSdkSource(projectRoot: string, localOverride: string | undefined, onProgress?: (msg: string) => void): Promise<string>;
+export interface WorkflowRuntimeHit {
+    file: string;
+    count: number;
+}
+export declare function scanWorkflowsForRuntime(projectRoot: string, kind: string): WorkflowRuntimeHit[];
+export interface UserNodesInfo {
+    dir: string;
+    isSymlink: boolean;
+    files: string[];
+}
+export declare function listUserNodes(projectRoot: string, kind: string): UserNodesInfo;
+export declare function reportRuntimeError(err: unknown): void;
+export declare function assertSidecarKind(kind: string): void;

package/dist/commands/runtime/shared.js

@@ -0,0 +1,164 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import simpleGit from "simple-git";
+import { tryConnect } from "../../services/health-probe.js";
+import { getRuntimeDefinition } from "../../services/runtime-detector.js";
+import { readProjectConfig } from "../../services/runtime-setup.js";
+const HOME_DIR = `${os.homedir()}/.blok`;
+const GITHUB_REPO_REMOTE = "https://github.com/well-prado/blok.git";
+export const NON_SIDECAR_KINDS = new Set(["node", "nodejs", "typescript", "ts", "bun", "docker", "wasm"]);
+export class RuntimeCommandError extends Error {
+}
+export function readConfigSafe(projectRoot) {
+    try {
+        return readProjectConfig(projectRoot) ?? {};
+    }
+    catch {
+        throw new RuntimeCommandError(`Could not parse ${path.join(projectRoot, ".blok", "config.json")} — fix or delete it and retry.`);
+    }
+}
+export async function assertGrpcPortFree(grpcPort) {
+    if (await tryConnect("127.0.0.1", grpcPort, 400)) {
+        throw new RuntimeCommandError(`gRPC port ${grpcPort} is already in use by a live process. Stop it, or pass --grpc-port <n> to use another port.`);
+    }
+}
+export function resolveProjectRoot(directory) {
+    const root = path.resolve(directory ?? process.cwd());
+    const pkgPath = path.join(root, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+        throw new RuntimeCommandError(`No package.json found at ${root}. Run this inside a Blok project, or pass --directory <path>.`);
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    }
+    catch {
+        throw new RuntimeCommandError(`Could not parse ${pkgPath}.`);
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const looksLikeBlok = Object.keys(deps).some((d) => d.startsWith("@blokjs/")) || fs.existsSync(path.join(root, ".blok"));
+    if (!looksLikeBlok) {
+        throw new RuntimeCommandError(`${root} doesn't look like a Blok project (no @blokjs/* dependency, no .blok/). Pass --directory <path> to the project root.`);
+    }
+    return root;
+}
+export function readFrameworkTag(projectRoot) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const range = deps["@blokjs/runner"] ?? deps["@blokjs/shared"] ?? deps.blokctl;
+    if (!range)
+        return null;
+    const m = range.match(/(\d+\.\d+\.\d+)/);
+    return m ? `v${m[1]}` : null;
+}
+export async function resolveSdkSource(projectRoot, localOverride, onProgress) {
+    if (localOverride) {
+        const resolved = path.resolve(localOverride);
+        if (!fs.existsSync(path.join(resolved, "sdks"))) {
+            throw new RuntimeCommandError(`--local path ${resolved} has no sdks/ directory.`);
+        }
+        return resolved;
+    }
+    const tag = readFrameworkTag(projectRoot);
+    if (!tag) {
+        throw new RuntimeCommandError("Couldn't determine the project's Blok version from package.json. Pass --local <path-to-blok-repo> to point at a matching SDK source.");
+    }
+    const cacheDir = path.join(HOME_DIR, "sdk-src", tag);
+    if (fs.existsSync(path.join(cacheDir, "sdks")))
+        return cacheDir;
+    onProgress?.(`Fetching SDK source (blok ${tag})…`);
+    fs.mkdirSync(path.join(HOME_DIR, "sdk-src"), { recursive: true });
+    const git = simpleGit({ baseDir: path.join(HOME_DIR, "sdk-src") });
+    try {
+        await git.clone(GITHUB_REPO_REMOTE, cacheDir, ["--branch", tag, "--depth", "1"]);
+    }
+    catch (err) {
+        fs.rmSync(cacheDir, { recursive: true, force: true });
+        throw new RuntimeCommandError(`Couldn't fetch the SDK source for ${tag} (${err.message.split("\n")[0]}). If this version isn't on GitHub, pass --local <path-to-blok-repo>.`);
+    }
+    if (!fs.existsSync(path.join(cacheDir, "sdks"))) {
+        throw new RuntimeCommandError(`Fetched ${tag} but it has no sdks/ directory.`);
+    }
+    return cacheDir;
+}
+const SCAN_SKIP_DIRS = new Set(["node_modules", ".blok", "dist", ".git", "coverage", "runtimes", ".nx"]);
+export function scanWorkflowsForRuntime(projectRoot, kind) {
+    const ref = new RegExp(`runtime\\.${kind}\\b`, "g");
+    const hits = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SCAN_SKIP_DIRS.has(entry.name))
+                    walk(full);
+                continue;
+            }
+            if (!/\.(ts|tsx|js|mjs|json)$/.test(entry.name))
+                continue;
+            let content;
+            try {
+                content = fs.readFileSync(full, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const matches = content.match(ref);
+            if (matches && matches.length > 0) {
+                hits.push({ file: path.relative(projectRoot, full), count: matches.length });
+            }
+        }
+    };
+    walk(projectRoot);
+    return hits.sort((a, b) => a.file.localeCompare(b.file));
+}
+export function listUserNodes(projectRoot, kind) {
+    const dir = path.join(projectRoot, "runtimes", kind, "nodes");
+    if (!fs.existsSync(dir))
+        return { dir, isSymlink: false, files: [] };
+    const stat = fs.lstatSync(dir);
+    if (stat.isSymbolicLink())
+        return { dir, isSymlink: true, files: [] };
+    const files = [];
+    const walk = (d) => {
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+            if (entry.isSymbolicLink())
+                continue;
+            const full = path.join(d, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else
+                files.push(path.relative(dir, full));
+        }
+    };
+    walk(dir);
+    return { dir, isSymlink: false, files: files.sort() };
+}
+export function reportRuntimeError(err) {
+    if (err instanceof RuntimeCommandError) {
+        p.cancel(err.message);
+    }
+    else {
+        p.cancel(color.red(`Unexpected error: ${err?.message ?? String(err)}`));
+    }
+    process.exitCode = 1;
+}
+export function assertSidecarKind(kind) {
+    if (NON_SIDECAR_KINDS.has(kind)) {
+        throw new RuntimeCommandError(`"${kind}" runs in-process and is always available — there's no sidecar to add or remove. Sidecar runtimes: go, rust, java, csharp, php, ruby, python3.`);
+    }
+    if (!getRuntimeDefinition(kind)) {
+        throw new RuntimeCommandError(`Unknown runtime "${kind}". Supported: go, rust, java, csharp, php, ruby, python3.`);
+    }
+}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ import "./commands/gen/index.js";
 import "./commands/nodes/index.js";
 import "./commands/config/index.js";
 import "./commands/migrate/index.js";
+import "./commands/runtime/index.js";
 import "./commands/graph/index.js";
 import "./commands/profile/index.js";
 import "./commands/cost/index.js";

package/dist/index.js

@@ -27,6 +27,7 @@ import "./commands/gen/index.js";
 import "./commands/nodes/index.js";
 import "./commands/config/index.js";
 import "./commands/migrate/index.js";
+import "./commands/runtime/index.js";
 import "./commands/graph/index.js";
 import "./commands/profile/index.js";
 import "./commands/cost/index.js";

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

@@ -0,0 +1,7 @@
+import { type ProjectConfig, type RuntimeConfig } from "./runtime-setup.js";
+export declare function runtimeEnvKey(kind: string): string;
+export declare function withRuntime(config: ProjectConfig, rc: RuntimeConfig): ProjectConfig;
+export declare function withoutRuntime(config: ProjectConfig, kind: string): ProjectConfig;
+export declare function rewriteRuntimeEnvBlock(envContent: string, runtimes: RuntimeConfig[]): string;
+export declare function rewriteSupervisordRuntimes(supervisordContent: string, runtimes: RuntimeConfig[]): string;
+export declare function ensureRuntimeGitignore(gitignoreContent: string): string;

package/dist/services/runtime-mutations.js

@@ -0,0 +1,67 @@
+import { generateRuntimeEnvVars, generateSupervisordConfig, } from "./runtime-setup.js";
+const RUNTIME_ENV_HEADER = "# Runtimes (auto-configured by blokctl)";
+export function runtimeEnvKey(kind) {
+    return kind === "csharp" ? "CSHARP" : kind.toUpperCase();
+}
+export function withRuntime(config, rc) {
+    return { ...config, runtimes: { ...(config.runtimes ?? {}), [rc.kind]: rc } };
+}
+export function withoutRuntime(config, kind) {
+    if (!config.runtimes || !(kind in config.runtimes))
+        return config;
+    const runtimes = Object.fromEntries(Object.entries(config.runtimes).filter(([k]) => k !== kind));
+    return { ...config, runtimes: Object.keys(runtimes).length === 0 ? undefined : runtimes };
+}
+export function rewriteRuntimeEnvBlock(envContent, runtimes) {
+    const isManaged = (line) => {
+        const t = line.trimStart();
+        return (line.trim() === RUNTIME_ENV_HEADER ||
+            /^RUNTIME_[A-Z0-9]+_(HOST|PORT|GRPC_PORT)=/.test(t) ||
+            /^BLOK_TRANSPORT=/.test(t));
+    };
+    const kept = envContent
+        .split("\n")
+        .filter((line) => !isManaged(line))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .replace(/\n+$/, "");
+    const block = generateRuntimeEnvVars(runtimes);
+    if (!block)
+        return kept.length > 0 ? `${kept}\n` : "";
+    return `${kept}\n${block}\n`;
+}
+export function rewriteSupervisordRuntimes(supervisordContent, runtimes) {
+    const out = [];
+    let skipping = false;
+    for (const line of supervisordContent.split("\n")) {
+        const t = line.trimStart();
+        if (/^\[program:[\w-]+_runtime\]/.test(t)) {
+            skipping = true;
+            continue;
+        }
+        if (/^\[/.test(t))
+            skipping = false;
+        if (!skipping)
+            out.push(line);
+    }
+    const kept = out.join("\n").replace(/\n+$/, "");
+    const block = generateSupervisordConfig(runtimes);
+    return block ? `${kept}\n${block}\n` : `${kept}\n`;
+}
+const RUNTIME_GITIGNORE_GLOBS = [
+    ".blok/runtimes/**/bin/",
+    ".blok/runtimes/**/obj/",
+    ".blok/runtimes/**/target/",
+    ".blok/runtimes/**/__pycache__/",
+    ".blok/runtimes/**/python3_runtime/",
+    ".blok/runtimes/**/vendor/",
+];
+export function ensureRuntimeGitignore(gitignoreContent) {
+    if (/^\.blok\/\s*$/m.test(gitignoreContent))
+        return gitignoreContent;
+    const missing = RUNTIME_GITIGNORE_GLOBS.filter((glob) => !gitignoreContent.includes(glob));
+    if (missing.length === 0)
+        return gitignoreContent;
+    const base = gitignoreContent.replace(/\n+$/, "");
+    return `${base}\n\n# Blok runtime build artifacts (managed by blokctl)\n${missing.join("\n")}\n`;
+}