@cat-factory/local-server 0.6.0 → 0.7.3

package/dist/runtimes/appleContainerRuntime.js

@@ -0,0 +1,191 @@
+import { HARNESS_PORT, } from './containerRuntime.js';
+// The Apple `container` adapter (macOS Containerization framework). It diverges from the
+// Docker CLI in three ways that the seam absorbs:
+//   1. Verbs: `container run | list | inspect | delete` (no `ps`/`rm`, no `--filter`,
+//      no `inspect -f` template) — so we list-all + filter client-side and parse JSON.
+//   2. Identity: `--name` IS the container id, so a run is addressed by a deterministic
+//      name (`cf-<runId>`); a managed label marks ours for reaping.
+//   3. Networking: each container runs in its own VM with its own IP — there is no
+//      published-port-on-loopback, so the orchestrator connects to `<containerIP>:8080`
+//      directly (read from `container inspect`). There is no Docker-in-Docker, so
+//      `capabilities.localDind` is false (the engine refuses the Tester's local infra
+//      mode on this runtime — see ExecutionService limited-mode gating).
+//
+// CLI flags verified against apple/container's command reference (run -d/-e/-l/--name/
+// -c/-m, list --all --format json, inspect, delete --force). The inspect JSON shape for
+// the assigned IP is not contractually documented, so the IP/state extraction is
+// deliberately tolerant (and unit-tested against the observed shape).
+const NAME_PREFIX = 'cf-';
+const LABEL_MANAGED = 'cat-factory.managed=apple';
+/**
+ * Statuses we treat as terminal — i.e. safe to reap. A container whose status we can't
+ * recognise (empty/unknown — the `container list` JSON shape is not contractual) is left
+ * ALONE rather than risk force-deleting one that is still running.
+ */
+const TERMINAL_STATUSES = new Set(['stopped', 'exited', 'dead']);
+/** The deterministic container name (== id) for a run. */
+function runName(runId) {
+    // Container names allow [a-zA-Z0-9][a-zA-Z0-9_.-]*; run ids are already in that set,
+    // but sanitise defensively so an unusual id can't produce an invalid name.
+    return `${NAME_PREFIX}${runId.replace(/[^a-zA-Z0-9_.-]/g, '-')}`;
+}
+/** Whether a listed container is one we manage (matched on either the id or the name). */
+function isManaged(row) {
+    return row.id.startsWith(NAME_PREFIX) || (row.name?.startsWith(NAME_PREFIX) ?? false);
+}
+/** Parse `container list --format json` into a normalised {id,name,status} list, tolerantly. */
+function parseList(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    const rows = Array.isArray(parsed) ? parsed : [parsed];
+    const out = [];
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const obj = row;
+        const config = (obj.configuration ?? obj.config);
+        const name = asString(obj.name) ?? asString(config?.name);
+        const id = asString(obj.id) ?? asString(config?.id) ?? name;
+        const status = (asString(obj.status) ?? asString(obj.state) ?? '').toLowerCase();
+        if (id)
+            out.push({ id, name, status });
+    }
+    return out;
+}
+function asString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** First plausible non-gateway IPv4 found anywhere in the inspect JSON, CIDR-stripped. */
+function extractIp(node, keyHint = '') {
+    if (typeof node === 'string') {
+        if (/gateway/i.test(keyHint))
+            return undefined;
+        const m = node.match(/\b(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(?:\/\d+)?\b/);
+        return m?.[1];
+    }
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            const found = extractIp(item, keyHint);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (typeof node === 'object' && node !== null) {
+        // Prefer explicit address-bearing fields over a blind scan.
+        for (const key of ['address', 'ipAddress', 'ip', 'ipv4']) {
+            const v = node[key];
+            const found = extractIp(v, key);
+            if (found)
+                return found;
+        }
+        for (const [key, v] of Object.entries(node)) {
+            const found = extractIp(v, key);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** Parse `container inspect` output (array or object) into {ip?, running}. */
+function parseInspect(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return { running: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { running: false };
+    }
+    const node = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (typeof node !== 'object' || node === null)
+        return { running: false };
+    const obj = node;
+    const status = (asString(obj.status) ?? asString(obj.state) ?? '').toLowerCase();
+    return { ip: extractIp(obj), running: status === 'running' };
+}
+export class AppleContainerRuntimeAdapter {
+    id = 'apple';
+    binary;
+    hostAlias;
+    capabilities = { localDind: false };
+    constructor(options) {
+        this.binary = options.binary ?? 'container';
+        this.hostAlias = options.hostAlias;
+    }
+    async run(exec, spec) {
+        const name = runName(spec.runId);
+        const args = [
+            'run',
+            '-d',
+            '--name',
+            name,
+            '-l',
+            LABEL_MANAGED,
+            '-e',
+            `HARNESS_SHARED_SECRET=${spec.sharedSecret}`,
+        ];
+        // No published port (connect by the container's own IP) and no --privileged
+        // (one-VM-per-container has no Docker-in-Docker; the engine never asks the Tester to
+        // run local infra here — see capabilities.localDind=false).
+        if (spec.instanceSize)
+            args.push('-m', spec.instanceSize.memory, '-c', spec.instanceSize.cpus);
+        for (const [k, v] of Object.entries(spec.env))
+            args.push('-e', `${k}=${v}`);
+        args.push(spec.image);
+        await exec(args);
+        // The name IS the container id; the transport addresses everything by it.
+        return name;
+    }
+    async find(exec, runId) {
+        const name = runName(runId);
+        const rows = parseList((await exec(['list', '--all', '--format', 'json'])).stdout);
+        // The deterministic name is the addressable handle (inspect/delete accept it). Match it
+        // against either the `id` or the `name` field, since `container list`'s `id` may be a
+        // content hash rather than the assigned name depending on the CLI version.
+        const hit = rows.find((r) => r.id === name || r.name === name);
+        return hit ? name : undefined;
+    }
+    async endpoint(exec, containerId) {
+        const { ip } = parseInspect((await exec(['inspect', containerId])).stdout);
+        if (!ip)
+            return undefined;
+        return { host: ip, port: HARNESS_PORT };
+    }
+    async isRunning(exec, containerId) {
+        try {
+            return parseInspect((await exec(['inspect', containerId])).stdout).running;
+        }
+        catch {
+            return false;
+        }
+    }
+    async remove(exec, containerId) {
+        await exec(['delete', '--force', containerId]).catch(() => undefined);
+    }
+    async removeRun(exec, runId) {
+        await this.remove(exec, runName(runId));
+    }
+    async reapExited(exec) {
+        // Reap only managed containers in a recognised TERMINAL state — never one whose status
+        // we can't parse, which could still be running (mirrors the Docker adapter's precise
+        // `status=exited` filter). Address by the assigned name when present (always a valid
+        // handle), else the id.
+        const rows = parseList((await exec(['list', '--all', '--format', 'json'])).stdout).filter((r) => isManaged(r) && TERMINAL_STATUSES.has(r.status));
+        if (rows.length) {
+            await exec(['delete', '--force', ...rows.map((r) => r.name ?? r.id)]).catch(() => undefined);
+        }
+        return rows.length;
+    }
+}
+//# sourceMappingURL=appleContainerRuntime.js.map

package/dist/runtimes/appleContainerRuntime.js.map

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

package/dist/runtimes/containerRuntime.d.ts

@@ -0,0 +1,96 @@
+/** The in-container port the executor-harness listens on. */
+export declare const HARNESS_PORT = 8080;
+/** Injectable CLI runner (docker/podman/container) — overridable in tests. */
+export type ContainerExec = (args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/** Where the orchestrator connects to reach a run's harness. */
+export interface ContainerEndpoint {
+    host: string;
+    port: number;
+}
+/** What a runtime can and cannot do, consumed by the engine's Tester gate. */
+export interface RuntimeCapabilities {
+    /**
+     * Whether the runtime can stand the Tester's local docker-compose infra up via
+     * Docker-in-Docker (a privileged / nested-container daemon inside the job
+     * container). False for one-VM-per-container runtimes (Apple `container`), which
+     * drives the engine's Tester "limited mode".
+     */
+    localDind: boolean;
+}
+/** A per-run container to start. */
+export interface RunContainerSpec {
+    runId: string;
+    image: string;
+    sharedSecret: string;
+    /** Run privileged (only the Tester `test` kind, only when the runtime supports DinD). */
+    privileged: boolean;
+    /** Optional `--network` (docker family only). */
+    network?: string;
+    /** Extra `-e KEY=VALUE` env passed into the container. */
+    env: Record<string, string>;
+    /** Host resource limits derived from the service's abstract instance size. */
+    instanceSize?: {
+        memory: string;
+        cpus: string;
+    };
+}
+/**
+ * A container runtime as the transport sees it. Each method takes the injected
+ * {@link ContainerExec} so the transport stays runtime-agnostic and tests can drive a
+ * fake CLI. Implementations own their own container-identity scheme (labels vs names)
+ * and their own networking model (published host port vs per-container IP).
+ */
+export interface ContainerRuntimeAdapter {
+    readonly id: RuntimeId;
+    readonly binary: string;
+    readonly capabilities: RuntimeCapabilities;
+    /** The hostname the harness uses to reach the orchestrator's LLM proxy (for PUBLIC_URL). */
+    readonly hostAlias: string;
+    /** Start a per-run container detached; resolves to its container id/name. */
+    run(exec: ContainerExec, spec: RunContainerSpec): Promise<string>;
+    /** The (running-or-exited) container for a run, if any. */
+    find(exec: ContainerExec, runId: string): Promise<string | undefined>;
+    /** The host+port the orchestrator should connect to, or undefined if not ready. */
+    endpoint(exec: ContainerExec, containerId: string): Promise<ContainerEndpoint | undefined>;
+    /** Whether the container is currently running. */
+    isRunning(exec: ContainerExec, containerId: string): Promise<boolean>;
+    /** Force-remove a single container (idempotent). */
+    remove(exec: ContainerExec, containerId: string): Promise<void>;
+    /** Force-remove every container for a run (idempotent). */
+    removeRun(exec: ContainerExec, runId: string): Promise<void>;
+    /** Reap exited managed containers left by crashes; resolves to the count removed. */
+    reapExited(exec: ContainerExec): Promise<number>;
+}
+export type RuntimeId = 'docker' | 'podman' | 'orbstack' | 'colima' | 'apple';
+/** Per-runtime defaults — the single source of truth for binary + networking + capability. */
+export interface RuntimeProfile {
+    id: RuntimeId;
+    /** Default CLI binary (overridable via LOCAL_DOCKER_BINARY). */
+    binary: string;
+    /** Default host alias used for PUBLIC_URL + the docker `--add-host` line. */
+    hostAlias: string;
+    /** Whether the docker-family adapter adds `--add-host=<alias>:host-gateway`. */
+    addHostGateway: boolean;
+    /** Whether the Tester's local Docker-in-Docker infra can run on this runtime. */
+    localDind: boolean;
+    /** Which adapter implementation backs this runtime. */
+    family: 'docker' | 'apple';
+}
+/** Resolve the runtime profile for an id (defaults to docker for an unknown value). */
+export declare function runtimeProfile(id: RuntimeId): RuntimeProfile;
+/**
+ * The runtime selected by `LOCAL_CONTAINER_RUNTIME` (docker | podman | orbstack |
+ * colima | apple). Defaults to `docker`; an unrecognised value also falls back to
+ * docker (logged by the preflight). Explicit selection is the supported path.
+ */
+export declare function resolveRuntimeId(env: NodeJS.ProcessEnv): RuntimeId;
+/**
+ * The effective host alias for the chosen runtime: an explicit `LOCAL_HARNESS_HOST_ALIAS`
+ * wins, else the runtime profile's default. Used to derive the PUBLIC_URL default so a
+ * job container can reach this service's LLM proxy on the host.
+ */
+export declare function resolveHostAlias(env: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=containerRuntime.d.ts.map

package/dist/runtimes/containerRuntime.d.ts.map

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

package/dist/runtimes/containerRuntime.js

@@ -0,0 +1,99 @@
+// The local-mode container-runtime seam. `LocalContainerRunnerTransport` orchestrates
+// the per-run container lifecycle (cache, health polling, HTTP) but delegates every
+// CLI call and the "how do I reach this container / how does it reach the host"
+// decision to a `ContainerRuntimeAdapter`, so a runtime that diverges from the Docker
+// CLI (today: Apple's `container`, which runs each container in its own VM with its own
+// IP and speaks a different CLI) is a new adapter rather than a fork of the transport.
+//
+// Docker, Podman, OrbStack and Colima all speak the Docker CLI, so they share ONE
+// adapter (`DockerRuntimeAdapter`) parameterised by binary + networking. Apple
+// `container` gets its own (`AppleContainerRuntimeAdapter`).
+/** The in-container port the executor-harness listens on. */
+export const HARNESS_PORT = 8080;
+const PROFILES = {
+    // Docker Desktop / Engine — the baseline. Desktop resolves host.docker.internal
+    // natively; Linux Engine needs the host-gateway add-host (harmless on Desktop).
+    docker: {
+        id: 'docker',
+        binary: 'docker',
+        hostAlias: 'host.docker.internal',
+        addHostGateway: true,
+        localDind: true,
+        family: 'docker',
+    },
+    // Podman speaks the same CLI; host.docker.internal:host-gateway works on v4+. Rootless
+    // Podman nests containers without --privileged (set LOCAL_DOCKER_PRIVILEGED_TEST_JOBS=false).
+    // NOTE: Podman needs fully-qualified image refs (ghcr.io/…, localhost/…).
+    podman: {
+        id: 'podman',
+        binary: 'podman',
+        hostAlias: 'host.docker.internal',
+        addHostGateway: true,
+        localDind: true,
+        family: 'docker',
+    },
+    // OrbStack ships a drop-in `docker` CLI and resolves host.docker.internal natively;
+    // published ports forward to the host loopback. Works like Docker Desktop.
+    orbstack: {
+        id: 'orbstack',
+        binary: 'docker',
+        hostAlias: 'host.docker.internal',
+        addHostGateway: true,
+        localDind: true,
+        family: 'docker',
+    },
+    // Colima runs dockerd in a Lima VM. Ports forward to the host loopback, but
+    // host.docker.internal/host-gateway resolves to the VM, not the Mac host where the
+    // orchestrator runs — so the harness often can't reach the LLM proxy with the default
+    // alias. host.lima.internal is the Lima-provided host alias; if it still doesn't
+    // resolve, set PUBLIC_URL to the Mac's LAN IP (see deploy/local/README.md).
+    colima: {
+        id: 'colima',
+        binary: 'docker',
+        hostAlias: 'host.lima.internal',
+        addHostGateway: false,
+        localDind: true,
+        family: 'docker',
+    },
+    // Apple `container` (macOS): one lightweight VM per container, each with its own IP.
+    // No published-port model (reach the container by IP), no host.docker.internal, and
+    // no Docker-in-Docker — so the Tester's local infra mode is unavailable (limited mode).
+    // The default host alias is the macOS Virtualization-framework vmnet gateway; override
+    // via PUBLIC_URL / LOCAL_HARNESS_HOST_ALIAS if your subnet differs.
+    apple: {
+        id: 'apple',
+        binary: 'container',
+        hostAlias: '192.168.64.1',
+        addHostGateway: false,
+        localDind: false,
+        family: 'apple',
+    },
+};
+const RUNTIME_IDS = Object.keys(PROFILES);
+/** Resolve the runtime profile for an id (defaults to docker for an unknown value). */
+export function runtimeProfile(id) {
+    return PROFILES[id] ?? PROFILES.docker;
+}
+/**
+ * The runtime selected by `LOCAL_CONTAINER_RUNTIME` (docker | podman | orbstack |
+ * colima | apple). Defaults to `docker`; an unrecognised value also falls back to
+ * docker (logged by the preflight). Explicit selection is the supported path.
+ */
+export function resolveRuntimeId(env) {
+    const raw = env.LOCAL_CONTAINER_RUNTIME?.trim().toLowerCase();
+    if (raw && RUNTIME_IDS.includes(raw))
+        return raw;
+    return 'docker';
+}
+/**
+ * The effective host alias for the chosen runtime: an explicit `LOCAL_HARNESS_HOST_ALIAS`
+ * wins, else the runtime profile's default. Used to derive the PUBLIC_URL default so a
+ * job container can reach this service's LLM proxy on the host.
+ */
+export function resolveHostAlias(env) {
+    const explicit = env.LOCAL_HARNESS_HOST_ALIAS?.trim();
+    if (explicit)
+        return explicit;
+    return runtimeProfile(resolveRuntimeId(env)).hostAlias;
+}
+//# sourceMappingURL=containerRuntime.js.map

package/dist/runtimes/containerRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerRuntime.js","sourceRoot":"","sources":["../../src/runtimes/containerRuntime.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,oFAAoF;AACpF,gFAAgF;AAChF,sFAAsF;AACtF,wFAAwF;AACxF,uFAAuF;AACvF,EAAE;AACF,kFAAkF;AAClF,+EAA+E;AAC/E,6DAA6D;AAE7D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAA;AAmFhC,MAAM,QAAQ,GAAsC;IAClD,gFAAgF;IAChF,gFAAgF;IAChF,MAAM,EAAE;QACN,EAAE,EAAE,QAAQ;QACZ,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,sBAAsB;QACjC,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,QAAQ;KACjB;IACD,uFAAuF;IACvF,8FAA8F;IAC9F,0EAA0E;IAC1E,MAAM,EAAE;QACN,EAAE,EAAE,QAAQ;QACZ,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,sBAAsB;QACjC,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,QAAQ;KACjB;IACD,oFAAoF;IACpF,2EAA2E;IAC3E,QAAQ,EAAE;QACR,EAAE,EAAE,UAAU;QACd,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,sBAAsB;QACjC,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,QAAQ;KACjB;IACD,4EAA4E;IAC5E,mFAAmF;IACnF,sFAAsF;IACtF,iFAAiF;IACjF,4EAA4E;IAC5E,MAAM,EAAE;QACN,EAAE,EAAE,QAAQ;QACZ,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,oBAAoB;QAC/B,cAAc,EAAE,KAAK;QACrB,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,QAAQ;KACjB;IACD,qFAAqF;IACrF,oFAAoF;IACpF,wFAAwF;IACxF,uFAAuF;IACvF,oEAAoE;IACpE,KAAK,EAAE;QACL,EAAE,EAAE,OAAO;QACX,MAAM,EAAE,WAAW;QACnB,SAAS,EAAE,cAAc;QACzB,cAAc,EAAE,KAAK;QACrB,SAAS,EAAE,KAAK;QAChB,MAAM,EAAE,OAAO;KAChB;CACF,CAAA;AAED,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAgB,CAAA;AAExD,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,EAAa;IAC1C,OAAO,QAAQ,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAA;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAsB;IACrD,MAAM,GAAG,GAAG,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAC7D,IAAI,GAAG,IAAK,WAAwB,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,GAAgB,CAAA;IAC3E,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAsB;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,CAAA;IACrD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAC7B,OAAO,cAAc,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAA;AACxD,CAAC"}

package/dist/runtimes/dockerRuntime.d.ts

@@ -0,0 +1,27 @@
+import { type ContainerEndpoint, type ContainerExec, type ContainerRuntimeAdapter, type RunContainerSpec, type RuntimeId } from './containerRuntime.js';
+export interface DockerRuntimeAdapterOptions {
+    id: RuntimeId;
+    binary: string;
+    hostAlias: string;
+    /** Add `--add-host=<hostAlias>:host-gateway` so the harness can reach the host. */
+    addHostGateway: boolean;
+    localDind: boolean;
+}
+export declare class DockerRuntimeAdapter implements ContainerRuntimeAdapter {
+    readonly id: RuntimeId;
+    readonly binary: string;
+    readonly hostAlias: string;
+    readonly capabilities: {
+        localDind: boolean;
+    };
+    private readonly addHostGateway;
+    constructor(options: DockerRuntimeAdapterOptions);
+    run(exec: ContainerExec, spec: RunContainerSpec): Promise<string>;
+    find(exec: ContainerExec, runId: string): Promise<string | undefined>;
+    endpoint(exec: ContainerExec, containerId: string): Promise<ContainerEndpoint | undefined>;
+    isRunning(exec: ContainerExec, containerId: string): Promise<boolean>;
+    remove(exec: ContainerExec, containerId: string): Promise<void>;
+    removeRun(exec: ContainerExec, runId: string): Promise<void>;
+    reapExited(exec: ContainerExec): Promise<number>;
+}
+//# sourceMappingURL=dockerRuntime.d.ts.map

package/dist/runtimes/dockerRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dockerRuntime.d.ts","sourceRoot":"","sources":["../../src/runtimes/dockerRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAE5B,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACf,MAAM,uBAAuB,CAAA;AAY9B,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,SAAS,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,cAAc,EAAE,OAAO,CAAA;IACvB,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,qBAAa,oBAAqB,YAAW,uBAAuB;IAClE,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,YAAY,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAA;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,YAAY,OAAO,EAAE,2BAA2B,EAM/C;IAEK,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBtE;IAEK,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU1E;IAEK,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAS/F;IAEK,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO1E;IAEK,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpE;IAEK,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAejE;IAEK,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrD;CACF"}

package/dist/runtimes/dockerRuntime.js

@@ -0,0 +1,124 @@
+import { HARNESS_PORT, } from './containerRuntime.js';
+// The Docker-CLI adapter — covers Docker, Podman, OrbStack and Colima, which all speak
+// the same `run/ps/port/inspect/rm` surface. It is the behaviour the transport had
+// inline before the seam was extracted, parameterised by binary + networking. A run's
+// container is labelled with the run id (the container key) and a managed marker; the
+// harness `:8080` is published to an ephemeral host port read back with `docker port`.
+/** Labels the per-run container by its run id (a run's steps share one container). */
+const LABEL_RUN = 'cat-factory.runId';
+const LABEL_MANAGED = 'cat-factory.managed=local-docker';
+export class DockerRuntimeAdapter {
+    id;
+    binary;
+    hostAlias;
+    capabilities;
+    addHostGateway;
+    constructor(options) {
+        this.id = options.id;
+        this.binary = options.binary;
+        this.hostAlias = options.hostAlias;
+        this.addHostGateway = options.addHostGateway;
+        this.capabilities = { localDind: options.localDind };
+    }
+    async run(exec, spec) {
+        const args = [
+            'run',
+            '-d',
+            '--label',
+            `${LABEL_RUN}=${spec.runId}`,
+            '--label',
+            LABEL_MANAGED,
+            '-p',
+            `127.0.0.1:0:${HARNESS_PORT}`,
+            '-e',
+            `HARNESS_SHARED_SECRET=${spec.sharedSecret}`,
+        ];
+        if (spec.instanceSize)
+            args.push('--memory', spec.instanceSize.memory, '--cpus', spec.instanceSize.cpus);
+        if (spec.privileged)
+            args.push('--privileged');
+        if (this.addHostGateway)
+            args.push(`--add-host=${this.hostAlias}:host-gateway`);
+        if (spec.network)
+            args.push('--network', spec.network);
+        for (const [k, v] of Object.entries(spec.env))
+            args.push('-e', `${k}=${v}`);
+        args.push(spec.image);
+        const { stdout } = await exec(args);
+        const containerId = stdout.trim().split(/\s+/).pop();
+        if (!containerId)
+            throw new Error(`${this.binary} run returned no container id`);
+        return containerId;
+    }
+    async find(exec, runId) {
+        const { stdout } = await exec([
+            'ps',
+            '-aq',
+            '--filter',
+            `label=${LABEL_RUN}=${runId}`,
+            '--filter',
+            `label=${LABEL_MANAGED}`,
+        ]);
+        return stdout.trim().split('\n')[0]?.trim() || undefined;
+    }
+    async endpoint(exec, containerId) {
+        const { stdout } = await exec(['port', containerId, `${HARNESS_PORT}/tcp`]);
+        // e.g. "127.0.0.1:49153" (possibly several lines for IPv4/IPv6); take the last
+        // numeric segment of the first line.
+        const line = stdout.trim().split('\n')[0]?.trim();
+        if (!line)
+            return undefined;
+        const port = Number(line.slice(line.lastIndexOf(':') + 1));
+        if (!Number.isFinite(port) || port <= 0)
+            return undefined;
+        return { host: '127.0.0.1', port };
+    }
+    async isRunning(exec, containerId) {
+        try {
+            const { stdout } = await exec(['inspect', '-f', '{{.State.Running}}', containerId]);
+            return stdout.trim() === 'true';
+        }
+        catch {
+            return false;
+        }
+    }
+    async remove(exec, containerId) {
+        await exec(['rm', '-f', containerId]).catch(() => undefined);
+    }
+    async removeRun(exec, runId) {
+        const { stdout } = await exec([
+            'ps',
+            '-aq',
+            '--filter',
+            `label=${LABEL_RUN}=${runId}`,
+            '--filter',
+            `label=${LABEL_MANAGED}`,
+        ]);
+        const ids = stdout
+            .trim()
+            .split('\n')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (ids.length)
+            await exec(['rm', '-f', ...ids]).catch(() => undefined);
+    }
+    async reapExited(exec) {
+        const { stdout } = await exec([
+            'ps',
+            '-aq',
+            '--filter',
+            `label=${LABEL_MANAGED}`,
+            '--filter',
+            'status=exited',
+        ]);
+        const ids = stdout
+            .trim()
+            .split('\n')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (ids.length)
+            await exec(['rm', '-f', ...ids]).catch(() => undefined);
+        return ids.length;
+    }
+}
+//# sourceMappingURL=dockerRuntime.js.map

package/dist/runtimes/dockerRuntime.js.map

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

package/dist/runtimes/index.d.ts

@@ -0,0 +1,13 @@
+import { type ContainerRuntimeAdapter } from './containerRuntime.js';
+export * from './containerRuntime.js';
+export { DockerRuntimeAdapter } from './dockerRuntime.js';
+export { AppleContainerRuntimeAdapter } from './appleContainerRuntime.js';
+/**
+ * Build the container-runtime adapter selected by `LOCAL_CONTAINER_RUNTIME`
+ * (docker | podman | orbstack | colima | apple), applying the env overrides
+ * (`LOCAL_DOCKER_BINARY`, `LOCAL_DOCKER_ADD_HOST_GATEWAY`, `LOCAL_HARNESS_HOST_ALIAS`)
+ * on top of the runtime's profile defaults. Docker/Podman/OrbStack/Colima share the
+ * Docker-CLI adapter; Apple `container` gets its own.
+ */
+export declare function createRuntimeAdapter(env: NodeJS.ProcessEnv): ContainerRuntimeAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtimes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtimes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,uBAAuB,CAAA;AAI9B,cAAc,uBAAuB,CAAA;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAA;AAEzE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,uBAAuB,CAqBpF"}

package/dist/runtimes/index.js

@@ -0,0 +1,33 @@
+import { resolveHostAlias, resolveRuntimeId, runtimeProfile, } from './containerRuntime.js';
+import { DockerRuntimeAdapter } from './dockerRuntime.js';
+import { AppleContainerRuntimeAdapter } from './appleContainerRuntime.js';
+export * from './containerRuntime.js';
+export { DockerRuntimeAdapter } from './dockerRuntime.js';
+export { AppleContainerRuntimeAdapter } from './appleContainerRuntime.js';
+/**
+ * Build the container-runtime adapter selected by `LOCAL_CONTAINER_RUNTIME`
+ * (docker | podman | orbstack | colima | apple), applying the env overrides
+ * (`LOCAL_DOCKER_BINARY`, `LOCAL_DOCKER_ADD_HOST_GATEWAY`, `LOCAL_HARNESS_HOST_ALIAS`)
+ * on top of the runtime's profile defaults. Docker/Podman/OrbStack/Colima share the
+ * Docker-CLI adapter; Apple `container` gets its own.
+ */
+export function createRuntimeAdapter(env) {
+    const profile = runtimeProfile(resolveRuntimeId(env));
+    const binary = env.LOCAL_DOCKER_BINARY?.trim() || profile.binary;
+    const hostAlias = resolveHostAlias(env);
+    if (profile.family === 'apple') {
+        return new AppleContainerRuntimeAdapter({ binary, hostAlias });
+    }
+    // An explicit LOCAL_DOCKER_ADD_HOST_GATEWAY wins; otherwise the profile default
+    // (Colima defaults off — host-gateway resolves to the Lima VM, not the Mac host).
+    const explicit = env.LOCAL_DOCKER_ADD_HOST_GATEWAY?.trim();
+    const addHostGateway = explicit ? explicit !== 'false' : profile.addHostGateway;
+    return new DockerRuntimeAdapter({
+        id: profile.id,
+        binary,
+        hostAlias,
+        addHostGateway,
+        localDind: profile.localDind,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/runtimes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtimes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAA;AAEzE,cAAc,uBAAuB,CAAA;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAA;AAEzE;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAsB;IACzD,MAAM,OAAO,GAAG,cAAc,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAA;IACrD,MAAM,MAAM,GAAG,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,MAAM,CAAA;IAChE,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;IAEvC,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC/B,OAAO,IAAI,4BAA4B,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;IAChE,CAAC;IAED,gFAAgF;IAChF,kFAAkF;IAClF,MAAM,QAAQ,GAAG,GAAG,CAAC,6BAA6B,EAAE,IAAI,EAAE,CAAA;IAC1D,MAAM,cAAc,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,CAAA;IAE/E,OAAO,IAAI,oBAAoB,CAAC;QAC9B,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,MAAM;QACN,SAAS;QACT,cAAc;QACd,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAA;AACJ,CAAC"}

package/dist/server.d.ts

@@ -1,5 +1,8 @@
 import { start } from '@cat-factory/node-server';
+import type { EnvironmentProvider } from '@cat-factory/kernel';
 export declare function startLocal(options?: {
     env?: NodeJS.ProcessEnv;
+    environmentProvider?: EnvironmentProvider;
+    host?: string;
 }): Promise<Awaited<ReturnType<typeof start>>>;
 //# sourceMappingURL=server.d.ts.map