@zenalexa/unicli 0.211.2 → 0.212.1

package/dist/transport/adapters/subprocess.js

@@ -0,0 +1,254 @@
+/**
+ * SubprocessTransport — wraps `child_process.spawn` behind the
+ * TransportAdapter interface.
+ *
+ * Mirrors the contract of the existing yaml-runner `exec` step
+ * (command + args + stdin + env + cwd + timeout) and adds a lightweight
+ * event stream (`stream()`) for callers that want to observe stdout/stderr
+ * chunks as they arrive.
+ */
+import { spawn } from "node:child_process";
+import { err, exitCodeFor, ok } from "../../core/envelope.js";
+const SUBPROCESS_STEPS = [
+    "exec",
+    "write_temp",
+    "download",
+    "wait",
+    "launch_app",
+];
+const SUBPROCESS_CAPABILITY = {
+    steps: SUBPROCESS_STEPS,
+    snapshotFormats: ["text", "json"],
+    mutatesHost: true,
+};
+/** Minimal async queue fed by stdout/stderr chunks, drained by `stream()`. */
+class EventQueue {
+    buffer = [];
+    waiters = [];
+    closed = false;
+    push(e) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value: e, done: false });
+        else
+            this.buffer.push(e);
+    }
+    close() {
+        this.closed = true;
+        while (this.waiters.length) {
+            const w = this.waiters.shift();
+            if (w)
+                w({ value: undefined, done: true });
+        }
+    }
+    async next() {
+        const buffered = this.buffer.shift();
+        if (buffered)
+            return { value: buffered, done: false };
+        if (this.closed)
+            return { value: undefined, done: true };
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+}
+export class SubprocessTransport {
+    kind = "subprocess";
+    capability = SUBPROCESS_CAPABILITY;
+    ctx;
+    queue = new EventQueue();
+    lastOutcome;
+    async open(ctx) {
+        this.ctx = ctx;
+    }
+    async snapshot(opts) {
+        const format = opts?.format ?? "text";
+        if (format === "json") {
+            return {
+                format: "json",
+                data: JSON.stringify(this.lastOutcome ?? {}),
+            };
+        }
+        return { format: "text", data: this.lastOutcome?.stdout ?? "" };
+    }
+    async action(req) {
+        const start = Date.now();
+        try {
+            let envelope;
+            switch (req.kind) {
+                case "exec":
+                    envelope = await this.doExec(req.params);
+                    break;
+                case "wait": {
+                    const p = req.params;
+                    const ms = typeof p.ms === "number"
+                        ? p.ms
+                        : typeof p.seconds === "number"
+                            ? p.seconds * 1000
+                            : 0;
+                    if (ms > 0)
+                        await new Promise((r) => setTimeout(r, ms));
+                    envelope = ok(undefined);
+                    break;
+                }
+                default:
+                    envelope = err({
+                        transport: "subprocess",
+                        step: 0,
+                        action: req.kind,
+                        reason: `unsupported action "${req.kind}" for subprocess transport`,
+                        suggestion: `subprocess transport supports: ${SUBPROCESS_STEPS.join(", ")}`,
+                        minimum_capability: `subprocess.${req.kind}`,
+                        exit_code: exitCodeFor("usage_error"),
+                    });
+            }
+            envelope.elapsedMs = Date.now() - start;
+            return envelope;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return err({
+                transport: "subprocess",
+                step: 0,
+                action: req.kind,
+                reason: msg,
+                suggestion: "inspect the command, args, and environment",
+                retryable: false,
+            });
+        }
+    }
+    /** Optional event stream — drains stdout/stderr pushed by `doExec`. */
+    stream() {
+        const queue = this.queue;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        return queue.next();
+                    },
+                    async return() {
+                        return {
+                            value: undefined,
+                            done: true,
+                        };
+                    },
+                };
+            },
+        };
+    }
+    async close() {
+        this.ctx = undefined;
+        this.queue.close();
+    }
+    // ── internals ────────────────────────────────────────────────────
+    async doExec(p) {
+        const command = typeof p.command === "string" ? p.command : undefined;
+        if (!command) {
+            return err({
+                transport: "subprocess",
+                step: 0,
+                action: "exec",
+                reason: "missing required param `command`",
+                suggestion: "pass params.command (binary name or absolute path)",
+                retryable: false,
+                exit_code: exitCodeFor("usage_error"),
+            });
+        }
+        const args = Array.isArray(p.args) ? p.args.map((a) => String(a)) : [];
+        const cwd = typeof p.cwd === "string" ? p.cwd : this.ctx?.cwd;
+        const envExtra = p.env && typeof p.env === "object" && !Array.isArray(p.env)
+            ? p.env
+            : undefined;
+        const env = envExtra
+            ? { ...process.env, ...envExtra }
+            : undefined;
+        const stdin = typeof p.stdin === "string" ? p.stdin : undefined;
+        const timeout = typeof p.timeoutMs === "number"
+            ? p.timeoutMs
+            : typeof p.timeoutMs === "string"
+                ? Number(p.timeoutMs)
+                : undefined;
+        return new Promise((resolve) => {
+            let settled = false;
+            let child;
+            try {
+                child = spawn(command, args, {
+                    cwd,
+                    env,
+                    timeout,
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                resolve(err({
+                    transport: "subprocess",
+                    step: 0,
+                    action: "exec",
+                    reason: msg,
+                    suggestion: `check that \`${command}\` is installed and on PATH`,
+                    retryable: false,
+                }));
+                return;
+            }
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            child.stdout?.on("data", (chunk) => {
+                stdoutChunks.push(chunk);
+                this.queue.push({
+                    ts: Date.now(),
+                    kind: "stdout",
+                    payload: chunk.toString("utf8"),
+                });
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderrChunks.push(chunk);
+                this.queue.push({
+                    ts: Date.now(),
+                    kind: "stderr",
+                    payload: chunk.toString("utf8"),
+                });
+            });
+            child.on("error", (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(err({
+                    transport: "subprocess",
+                    step: 0,
+                    action: "exec",
+                    reason: error.message,
+                    suggestion: `check that \`${command}\` is installed and on PATH`,
+                    retryable: false,
+                }));
+            });
+            child.on("close", (code, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+                const stderr = Buffer.concat(stderrChunks).toString("utf8");
+                const exitCode = code ?? (signal ? 1 : 0);
+                const outcome = { stdout, stderr, exitCode };
+                this.lastOutcome = outcome;
+                if (exitCode !== 0) {
+                    resolve(err({
+                        transport: "subprocess",
+                        step: 0,
+                        action: "exec",
+                        reason: `process \`${command}\` exited with code ${exitCode}${stderr ? `: ${stderr.slice(0, 200)}` : ""}`,
+                        suggestion: "inspect stderr for the failure cause",
+                        retryable: false,
+                    }));
+                    return;
+                }
+                resolve(ok(outcome));
+            });
+            if (stdin !== undefined) {
+                child.stdin?.write(stdin);
+                child.stdin?.end();
+            }
+        });
+    }
+}
+//# sourceMappingURL=subprocess.js.map

package/dist/transport/adapters/subprocess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.js","sourceRoot":"","sources":["../../../src/transport/adapters/subprocess.ts"],"names":[],"mappings":"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"}

package/dist/transport/bus.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TransportBus — composition layer that routes a pipeline step to the
+ * transport that can execute it on the current host.
+ *
+ * The bus consults {@link CAPABILITY_MATRIX} at parse time so the YAML
+ * runner can refuse a pipeline before any I/O happens. When no transport
+ * satisfies the step (either unregistered or platform-gated), the bus
+ * throws a {@link NoTransportForStepError} carrying an envelope with the
+ * repair hint `minimum_capability: "<kind>.<step>"` so agents know which
+ * transport to add or fix.
+ */
+import { type EnvelopeErr } from "../core/envelope.js";
+import { stepPlatform, stepSupportedBy } from "./capability.js";
+import type { TransportBus } from "./types.js";
+/**
+ * Typed error thrown by {@link TransportBus.require} when no registered
+ * transport can execute the requested step on the given platform. The
+ * `envelope` field is the machine-readable payload callers should emit
+ * to stderr.
+ */
+export declare class NoTransportForStepError extends Error {
+    readonly envelope: EnvelopeErr;
+    constructor(envelope: EnvelopeErr);
+}
+/** Factory — callers create one bus per pipeline run. */
+export declare function createTransportBus(): TransportBus;
+export { stepPlatform, stepSupportedBy };
+//# sourceMappingURL=bus.d.ts.map

package/dist/transport/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../../src/transport/bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAO,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAEL,YAAY,EACZ,eAAe,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAoB,YAAY,EAAiB,MAAM,YAAY,CAAC;AAEhF;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;gBACnB,QAAQ,EAAE,WAAW;CAKlC;AAqGD,yDAAyD;AACzD,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAGD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/transport/bus.js

@@ -0,0 +1,112 @@
+/**
+ * TransportBus — composition layer that routes a pipeline step to the
+ * transport that can execute it on the current host.
+ *
+ * The bus consults {@link CAPABILITY_MATRIX} at parse time so the YAML
+ * runner can refuse a pipeline before any I/O happens. When no transport
+ * satisfies the step (either unregistered or platform-gated), the bus
+ * throws a {@link NoTransportForStepError} carrying an envelope with the
+ * repair hint `minimum_capability: "<kind>.<step>"` so agents know which
+ * transport to add or fix.
+ */
+import { err } from "../core/envelope.js";
+import { CAPABILITY_MATRIX, stepPlatform, stepSupportedBy, } from "./capability.js";
+/**
+ * Typed error thrown by {@link TransportBus.require} when no registered
+ * transport can execute the requested step on the given platform. The
+ * `envelope` field is the machine-readable payload callers should emit
+ * to stderr.
+ */
+export class NoTransportForStepError extends Error {
+    envelope;
+    constructor(envelope) {
+        super(envelope.error.reason);
+        this.name = "NoTransportForStepError";
+        this.envelope = envelope;
+    }
+}
+/** Implementation of the {@link TransportBus} interface. */
+class TransportBusImpl {
+    adapters = new Map();
+    register(adapter) {
+        this.adapters.set(adapter.kind, adapter);
+    }
+    get(kind) {
+        const a = this.adapters.get(kind);
+        if (!a) {
+            throw new NoTransportForStepError(err({
+                transport: kind,
+                step: 0,
+                action: "<bus.get>",
+                reason: `no transport registered for kind ${kind}`,
+                suggestion: `register a ${kind} adapter on the bus before requesting it`,
+                minimum_capability: `${kind}.register`,
+            }));
+        }
+        return a;
+    }
+    list() {
+        return Array.from(this.adapters.values());
+    }
+    require(step, platform) {
+        const row = CAPABILITY_MATRIX[step];
+        const hostPlatform = platform ?? process.platform;
+        if (!row) {
+            throw new NoTransportForStepError(err({
+                transport: "http",
+                step: 0,
+                action: step,
+                reason: `unknown step "${step}" — not present in capability matrix`,
+                suggestion: `check the 49-step matrix in src/transport/capability.ts or rename the step`,
+                minimum_capability: `unknown.${step}`,
+            }));
+        }
+        // Platform gate — a step marked ◐darwin must run on darwin.
+        if (row.platforms &&
+            !row.platforms.includes(hostPlatform)) {
+            const requiredTransport = row.transports[0] ?? "http";
+            throw new NoTransportForStepError(err({
+                transport: requiredTransport,
+                step: 0,
+                action: step,
+                reason: `no transport for step ${step} on platform ${hostPlatform}`,
+                suggestion: `step requires ${row.platforms.join(" | ")}; run on that host or use a fallback transport`,
+                minimum_capability: `${requiredTransport}.${step}`,
+                exit_code: 69, // SERVICE_UNAVAILABLE — OS-gated
+            }));
+        }
+        // Walk the matrix in declaration order; pick the first registered
+        // transport that declares support for the step.
+        for (const kind of row.transports) {
+            const adapter = this.adapters.get(kind);
+            if (adapter && adapter.capability.steps.includes(step))
+                return adapter;
+        }
+        // Fallback: maybe a registered transport declares this step even if the
+        // matrix is tighter. Walk every registered transport and match.
+        for (const adapter of this.adapters.values()) {
+            if (adapter.capability.steps.includes(step)) {
+                if (!row.platforms ||
+                    row.platforms.includes(hostPlatform)) {
+                    return adapter;
+                }
+            }
+        }
+        const requiredTransport = row.transports[0] ?? "http";
+        throw new NoTransportForStepError(err({
+            transport: requiredTransport,
+            step: 0,
+            action: step,
+            reason: `no transport for step ${step} on platform ${hostPlatform}`,
+            suggestion: `register one of [${row.transports.join(", ")}] on the bus`,
+            minimum_capability: `${requiredTransport}.${step}`,
+        }));
+    }
+}
+/** Factory — callers create one bus per pipeline run. */
+export function createTransportBus() {
+    return new TransportBusImpl();
+}
+// Re-export for downstream callers that want a single import point.
+export { stepPlatform, stepSupportedBy };
+//# sourceMappingURL=bus.js.map

package/dist/transport/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../../src/transport/bus.ts"],"names":[],"mappings":"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"}

package/dist/transport/capability.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Step → transport capability matrix.
+ *
+ * Single source of truth for which transports can execute each pipeline
+ * step, per `.claude/plans/sessions/2026-04-14-v212-rethink/round4/02-operate-anything-arch.md`
+ * §3 (46 steps × 7 transports).
+ *
+ * Legend from round4/02:
+ *   ●  native
+ *   ○  emulated via delegate (still legal — appears in `transports`)
+ *   –  unsupported (absent from `transports`)
+ *   ◐  OS-gated (appears in `transports` AND `platforms`)
+ *
+ * The YAML runner uses {@link stepSupportedBy} at parse time to route a
+ * step to the right transport; {@link stepPlatform} is consulted when the
+ * step is platform-exclusive.
+ */
+import type { TransportKind } from "./types.js";
+/** Canonical ordering for the 7 transports; stable across releases. */
+export declare const TRANSPORT_KINDS: readonly TransportKind[];
+/** One row in the matrix. */
+export interface CapabilityRow {
+    readonly transports: readonly TransportKind[];
+    /** Platform gate, if any. Undefined = any host OS. */
+    readonly platforms?: readonly ("darwin" | "win32" | "linux")[];
+}
+/**
+ * The 46-step matrix. Keep row ordering loose; tests assert membership
+ * semantically.
+ */
+export declare const CAPABILITY_MATRIX: Readonly<Record<string, CapabilityRow>>;
+/** Step names this transport can execute on the given host platform. */
+export declare function stepSupportedBy(step: string): readonly TransportKind[];
+/** Platform gate for a step; undefined means any OS. */
+export declare function stepPlatform(step: string): readonly ("darwin" | "win32" | "linux")[] | undefined;
+/** Count of distinct steps in the matrix. */
+export declare function stepCount(): number;
+//# sourceMappingURL=capability.d.ts.map

package/dist/transport/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/transport/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAQ1C,CAAC;AAEX,6BAA6B;AAC7B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,EAAE,CAAC;CAChE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAsNrE,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE,CAGtE;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,EAAE,GAAG,SAAS,CAGvD;AAED,6CAA6C;AAC7C,wBAAgB,SAAS,IAAI,MAAM,CAElC"}