cool-workflow 0.1.98 → 0.2.1

package/dist/shell/execution-backend/container.js

@@ -0,0 +1,69 @@
+"use strict";
+// shell/execution-backend/container.ts — the container delegating driver.
+//
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
+// plugins/cool-workflow/src/execution-backend.ts's container handle builder
+// (:1068-1075) and `runContainer` (:720-792).
+//
+// Evidence: SPEC/execution-backend.md "container driver (runContainer)".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containerHandle = containerHandle;
+exports.runContainer = runContainer;
+const node_child_process_1 = require("node:child_process");
+const probes_1 = require("./probes");
+const envelopes_1 = require("./envelopes");
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function containerHandle(request, env = process.env) {
+    const delegation = request.delegation || {};
+    const image = delegation.image || (env.CW_CONTAINER_IMAGE || "").trim() || undefined;
+    if (!image)
+        return undefined;
+    const digest = delegation.digest || (env.CW_CONTAINER_DIGEST || "").trim() || undefined;
+    const ref = digest ? `${image}@${digest}` : image;
+    return { kind: "container", ref, image, digest };
+}
+/** container — real `docker`/`podman run` under the sandbox contract. Fails
+ *  closed when no runtime is on PATH, the daemon is unreachable, or the
+ *  runtime itself errors (exit 125) — distinct from the command's own
+ *  non-zero exit. Byte-exact port of src/execution-backend.ts:720-792. */
+function runContainer(descriptor, policy, request, label, handle, attestation) {
+    const runtime = (0, probes_1.hasExecutable)("docker") ? "docker" : (0, probes_1.hasExecutable)("podman") ? "podman" : undefined;
+    if (!runtime) {
+        return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "runtime-unavailable", "no container runtime (docker/podman) on PATH", attestation);
+    }
+    const ping = (0, node_child_process_1.spawnSync)(runtime, ["version", "--format", "{{.Server.Version}}"], { encoding: "utf8", timeout: 15000 });
+    const daemonUp = !ping.error && ping.status === 0 && String(ping.stdout || "").trim().length > 0;
+    if (!daemonUp) {
+        const why = (String(ping.stderr || "").split("\n").find((line) => line.trim()) || `${runtime} daemon not reachable`).trim();
+        return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "runtime-unavailable", `${runtime} daemon is not reachable: ${why}`, attestation);
+    }
+    const command = String(request.command);
+    const args = (request.args || []).map(String);
+    const cwd = request.cwd || process.cwd();
+    const runArgs = ["run", "--rm"];
+    if (policy.network.mode !== "any")
+        runArgs.push("--network", "none");
+    runArgs.push("-v", `${cwd}:${cwd}:ro`, "-w", cwd);
+    if (policy.env.inherit || (policy.env.expose && policy.env.expose.length)) {
+        for (const name of policy.env.inherit ? Object.keys(process.env) : policy.env.expose || []) {
+            if (name === "PATH" || name === "HOME")
+                continue;
+            const value = process.env[name];
+            if (value !== undefined)
+                runArgs.push("-e", `${name}=${value}`);
+        }
+    }
+    runArgs.push(handle.ref, command, ...args);
+    const result = (0, node_child_process_1.spawnSync)(runtime, runArgs, { cwd, encoding: "utf8", timeout: request.timeoutMs, maxBuffer: 32 * 1024 * 1024 });
+    if (result.error) {
+        return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "delegation-failed", `${runtime} run failed: ${messageOf(result.error)}`, attestation);
+    }
+    const exitCode = typeof result.status === "number" ? result.status : null;
+    if (exitCode === 125 || exitCode === null) {
+        const why = (String(result.stderr || "").split("\n").find((line) => line.trim()) || "container runtime error").trim();
+        return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "runtime-unavailable", `${runtime} could not run the container: ${why}`, attestation);
+    }
+    return (0, envelopes_1.delegatedEnvelope)(descriptor, label, handle, attestation, command, args, exitCode, String(result.stdout || ""));
+}

package/dist/shell/execution-backend/envelopes.js

@@ -0,0 +1,55 @@
+"use strict";
+// shell/execution-backend/envelopes.ts — shared envelope builders used by
+// every delegating driver (container/remote/ci/agent) plus the registry's
+// own refusal path.
+//
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of the
+// `delegatedEnvelope` (src/execution-backend.ts:680-713) and
+// `refusedEnvelope` (:1095-1126) helpers, factored into one shared module
+// since every delegating driver builds the identical shape (byte-stable
+// evidence triple across backends — see SPEC/execution-backend.md invariant
+// 2 "Same envelopes, any backend").
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delegatedEnvelope = delegatedEnvelope;
+exports.refusedEnvelope = refusedEnvelope;
+const hash_1 = require("../../core/hash");
+/** Build the canonical completed/failed envelope shared by every real
+ *  backend — identical to executeLocal's, so evidence is byte-stable across
+ *  backends. The handle is recorded in provenance only. */
+function delegatedEnvelope(descriptor, label, handle, attestation, command, args, exitCode, stdout) {
+    const digest = (0, hash_1.sha256)(stdout);
+    const status = exitCode === 0 ? "completed" : "failed";
+    const evidence = [`command:${[command, ...args].join(" ")}`, `exitCode:${exitCode === null ? "null" : exitCode}`, `stdoutSha256:${digest}`];
+    const summary = status === "completed" ? `${label}: completed (exit 0)` : `${label}: failed (exit ${exitCode === null ? "null" : exitCode})`;
+    return {
+        schemaVersion: 1,
+        status,
+        result: { summary, findings: [], evidence },
+        evidence,
+        provenance: {
+            schemaVersion: 1,
+            backendId: descriptor.id,
+            locality: descriptor.locality,
+            kind: descriptor.kind,
+            attestation,
+            handle,
+        },
+    };
+}
+function refusedEnvelope(descriptor, policy, label, code, reason, attestation) {
+    const evidence = [`refused:${code}`, `backend:${descriptor.id}`, `sandbox:${policy.id}`];
+    return {
+        schemaVersion: 1,
+        status: "refused",
+        result: { summary: `${label}: refused (${code}) — ${reason}`, findings: [], evidence },
+        evidence,
+        provenance: {
+            schemaVersion: 1,
+            backendId: descriptor.id,
+            locality: descriptor.locality,
+            kind: descriptor.kind,
+            attestation: { ...attestation, status: "refused", notes: [...(attestation.notes || []), `refused: ${code}`] },
+            handle: attestation.handle,
+        },
+    };
+}

package/dist/shell/execution-backend/local.js

@@ -0,0 +1,113 @@
+"use strict";
+// shell/execution-backend/local.ts — the local-execution driver body
+// (executeLocal) shared by the node/bun/shell built-in drivers.
+//
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
+// plugins/cool-workflow/src/execution-backend.ts's `executeLocal` (lines
+// 547-626) plus the leaf helpers it needs (sha256/hasExecutable/messageOf).
+//
+// Evidence: SPEC/execution-backend.md "Local execution (executeLocal)".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChildEnv = buildChildEnv;
+exports.checkShellGuard = checkShellGuard;
+exports.runtimeNoteFor = runtimeNoteFor;
+exports.executeLocal = executeLocal;
+const node_child_process_1 = require("node:child_process");
+const hash_1 = require("../../core/hash");
+const probes_1 = require("./probes");
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function buildChildEnv(policy, baseEnv = process.env) {
+    if (policy.env.inherit)
+        return { ...baseEnv };
+    const env = {};
+    if (baseEnv.PATH !== undefined)
+        env.PATH = baseEnv.PATH;
+    if (baseEnv.HOME !== undefined)
+        env.HOME = baseEnv.HOME;
+    for (const name of policy.env.expose || []) {
+        if (baseEnv[name] !== undefined)
+            env[name] = baseEnv[name];
+    }
+    for (const name of policy.env.deny || []) {
+        delete env[name];
+    }
+    return env;
+}
+/** Shell injection guard (SPEC/execution-backend.md "Local execution"): for
+ *  the `shell` driver, the joined string (with `{{token}}` placeholders
+ *  taken out first) must not match the control-character set. Throws a
+ *  plain Error with the byte-exact message on a hit. */
+function checkShellGuard(command, args) {
+    const shellArg = [command, ...args].join(" ").replace(/\{\{[a-zA-Z0-9_.-]+\}\}/g, "");
+    if (/[;&|`$(){}<>!\n\r#*?~]/.test(shellArg)) {
+        throw new Error(`Shell backend refused: args contain shell control characters. ` +
+            `Use the node, bun, or agent backend instead for untrusted inputs.`);
+    }
+}
+function runtimeNoteFor(backendId) {
+    if (backendId === "bun") {
+        return (0, probes_1.hasExecutable)("bun") ? "bun (node-compatible execution)" : "node-compatible (bun not installed)";
+    }
+    if (backendId === "shell")
+        return "posix-shell";
+    return "node";
+}
+/** executeLocal — spawn a thin child process and capture verifiable
+ *  evidence (exit code + output digest). Byte-exact port of
+ *  src/execution-backend.ts:547-626. */
+function executeLocal(descriptor, request, label, attestation, spawnStyle) {
+    const command = String(request.command);
+    const args = (request.args || []).map(String);
+    const env = buildChildEnv(request.sandboxPolicy);
+    const options = {
+        cwd: request.cwd,
+        env,
+        encoding: "utf8",
+        timeout: request.timeoutMs,
+        maxBuffer: 32 * 1024 * 1024,
+    };
+    if (spawnStyle === "shell") {
+        checkShellGuard(command, args);
+    }
+    const isTTY = Boolean(process.stderr.isTTY);
+    const shortLabel = command.split("/").pop() || command;
+    if (isTTY)
+        process.stderr.write(`● Running ${shortLabel}...\n`);
+    const startedAt = process.hrtime.bigint();
+    const result = spawnStyle === "shell"
+        ? (0, node_child_process_1.spawnSync)([command, ...args].join(" "), { ...options, shell: true })
+        : (0, node_child_process_1.spawnSync)(command, args, { ...options, shell: false });
+    const elapsedMs = Number((process.hrtime.bigint() - startedAt) / 1000000n);
+    if (isTTY)
+        process.stderr.write(`✓ Done (${elapsedMs}ms)\n`);
+    const exitCode = typeof result.status === "number" ? result.status : null;
+    const spawnError = result.error ? messageOf(result.error) : undefined;
+    const stdout = String(result.stdout || "");
+    const digest = (0, hash_1.sha256)(stdout);
+    const status = spawnError ? "failed" : exitCode === 0 ? "completed" : "failed";
+    const evidence = [`command:${[command, ...args].join(" ")}`, `exitCode:${exitCode === null ? "null" : exitCode}`, `stdoutSha256:${digest}`];
+    const summary = status === "completed"
+        ? `${label}: completed (exit 0)`
+        : spawnError
+            ? `${label}: failed (${spawnError})`
+            : `${label}: failed (exit ${exitCode})`;
+    const resultEnvelope = { summary, findings: [], evidence };
+    const notes = [`runtime: ${runtimeNoteFor(descriptor.id)}`];
+    if (spawnError)
+        notes.push(`spawn-error: ${spawnError}`);
+    return {
+        schemaVersion: 1,
+        status,
+        result: resultEnvelope,
+        evidence,
+        provenance: {
+            schemaVersion: 1,
+            backendId: descriptor.id,
+            locality: descriptor.locality,
+            kind: descriptor.kind,
+            attestation: { ...attestation, status: attestation.status, notes },
+        },
+    };
+}

package/dist/shell/execution-backend/probes.js

@@ -0,0 +1,175 @@
+"use strict";
+// shell/execution-backend/probes.ts — per-backend readiness probe bodies.
+//
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
+// plugins/cool-workflow/src/execution-backend/probes.ts. Each probe is a
+// pure free function of the host (PATH + configured env); the registry's
+// `probeBackend` wraps these with the descriptor-derived envelope.
+//
+// Evidence: SPEC/execution-backend.md "Probes".
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasExecutable = hasExecutable;
+exports.probeNodeBackend = probeNodeBackend;
+exports.probeShellBackend = probeShellBackend;
+exports.probeBunBackend = probeBunBackend;
+exports.probeContainerBackend = probeContainerBackend;
+exports.probeRemoteBackend = probeRemoteBackend;
+exports.probeCiBackend = probeCiBackend;
+exports.probeAgentBackend = probeAgentBackend;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+function hasExecutable(name, env = process.env) {
+    const dirs = (env.PATH || "").split(path.delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        const candidate = path.join(dir, name);
+        try {
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+                return true;
+        }
+        catch {
+            // ignore unreadable PATH entries
+        }
+    }
+    return false;
+}
+function probeNodeBackend() {
+    const ok = hasExecutable("node");
+    return {
+        checks: [{ name: "node-runtime", ok, detail: ok ? "node on PATH" : "node not found on PATH" }],
+        readiness: ok ? "ready" : "unavailable",
+        reason: ok ? undefined : "node runtime not found on PATH",
+    };
+}
+function probeShellBackend() {
+    const ok = hasExecutable("sh") || fs.existsSync("/bin/sh");
+    return {
+        checks: [{ name: "posix-shell", ok, detail: ok ? "sh available" : "no POSIX shell found" }],
+        readiness: ok ? "ready" : "unavailable",
+        reason: ok ? undefined : "POSIX shell not found",
+    };
+}
+function probeBunBackend() {
+    const bun = hasExecutable("bun");
+    const node = hasExecutable("node");
+    return {
+        checks: [
+            { name: "bun-runtime", ok: bun, detail: bun ? "bun on PATH" : "bun not found; node-compatible fallback" },
+            { name: "node-compatible-fallback", ok: node, detail: node ? "node on PATH" : "node not found on PATH" },
+        ],
+        readiness: bun || node ? "ready" : "unavailable",
+        reason: !bun && node
+            ? "bun not installed; executing via node-compatible runtime"
+            : !bun && !node
+                ? "neither bun nor node found on PATH"
+                : undefined,
+    };
+}
+function probeContainerBackend() {
+    const docker = hasExecutable("docker");
+    const podman = hasExecutable("podman");
+    return {
+        checks: [
+            { name: "docker", ok: docker, detail: docker ? "docker on PATH" : "docker not found" },
+            { name: "podman", ok: podman, detail: podman ? "podman on PATH" : "podman not found" },
+        ],
+        readiness: docker || podman ? "ready" : "unavailable",
+        reason: docker || podman ? undefined : "no container runtime (docker/podman) found; supply --image to delegate explicitly",
+    };
+}
+function delegateChildExists() {
+    // __dirname is dist/shell/execution-backend — three levels up reaches
+    // the package root (scripts/ is a sibling of dist/, not two levels up).
+    return fs.existsSync(path.resolve(__dirname, "..", "..", "..", "scripts", "children", "http-delegate-child.js"));
+}
+function probeRemoteBackend(env = process.env) {
+    const endpoint = (env.CW_REMOTE_ENDPOINT || "").trim();
+    const scriptOk = delegateChildExists();
+    const checks = [
+        { name: "endpoint", ok: Boolean(endpoint), detail: endpoint ? "CW_REMOTE_ENDPOINT configured" : "CW_REMOTE_ENDPOINT not set" },
+        {
+            name: "delegate-child-script",
+            ok: scriptOk,
+            detail: scriptOk ? "http-delegate-child.js found" : "http-delegate-child.js missing — reinstall cool-workflow",
+        },
+    ];
+    const readiness = !endpoint ? "unverified" : !scriptOk ? "unavailable" : "ready";
+    return {
+        checks,
+        readiness,
+        reason: readiness === "ready"
+            ? undefined
+            : !endpoint
+                ? "no remote endpoint configured (set CW_REMOTE_ENDPOINT or pass --endpoint)"
+                : "delegate child script is missing",
+    };
+}
+function probeCiBackend(env = process.env) {
+    const endpoint = (env.CW_CI_ENDPOINT || "").trim();
+    const scriptOk = delegateChildExists();
+    const checks = [
+        { name: "ci-endpoint", ok: Boolean(endpoint), detail: endpoint ? "CW_CI_ENDPOINT configured" : "CW_CI_ENDPOINT not set" },
+        {
+            name: "delegate-child-script",
+            ok: scriptOk,
+            detail: scriptOk ? "http-delegate-child.js found" : "http-delegate-child.js missing — reinstall cool-workflow",
+        },
+    ];
+    const readiness = !endpoint ? "unverified" : !scriptOk ? "unavailable" : "ready";
+    return {
+        checks,
+        readiness,
+        reason: readiness === "ready"
+            ? undefined
+            : !endpoint
+                ? "no CI job target configured (set CW_CI_ENDPOINT or pass --job)"
+                : "delegate child script is missing",
+    };
+}
+function probeAgentBackend(env = process.env) {
+    // Mirrors remote/ci EXACTLY: unconfigured ⇒ `unverified` (NOT a hard
+    // refusal), configured ⇒ `ready`.
+    const command = (env.CW_AGENT_COMMAND || "").trim();
+    const endpoint = (env.CW_AGENT_ENDPOINT || "").trim();
+    const configured = Boolean(command || endpoint);
+    return {
+        checks: [
+            { name: "agent-command", ok: Boolean(command), detail: command ? "CW_AGENT_COMMAND configured" : "CW_AGENT_COMMAND not set" },
+            { name: "agent-endpoint", ok: Boolean(endpoint), detail: endpoint ? "CW_AGENT_ENDPOINT configured" : "CW_AGENT_ENDPOINT not set" },
+        ],
+        readiness: configured ? "ready" : "unverified",
+        reason: configured ? undefined : "no agent configured (set CW_AGENT_COMMAND or CW_AGENT_ENDPOINT, or pass --agent-command/--agent-endpoint)",
+    };
+}