@cat-factory/local-server 0.7.2 → 0.7.4

package/dist/LocalContainerRunnerTransport.d.ts

@@ -0,0 +1,83 @@
+import type { RunnerDispatchKind, RunnerDispatchOptions, RunnerJobRef, RunnerJobView, RunnerTransport } from '@cat-factory/kernel';
+import { type ContainerExec, type ContainerRuntimeAdapter } from './runtimes/index.js';
+/** Injectable CLI runner — overridable in tests. Re-exported for callers/tests. */
+export type { ContainerExec } from './runtimes/index.js';
+export interface LocalContainerRunnerTransportOptions {
+    /** The executor-harness image ref (a GHCR pull or a locally built tag). */
+    image: string;
+    /**
+     * The container runtime adapter (Docker-family or Apple). Defaults to the Docker-CLI
+     * adapter (`docker` binary) so existing callers/tests keep working.
+     */
+    adapter?: ContainerRuntimeAdapter;
+    /**
+     * Shared secret injected as `HARNESS_SHARED_SECRET` and sent as the
+     * `x-harness-secret` header on every call. Defaults to a random per-process value.
+     */
+    sharedSecret?: string;
+    /** Optional `--network` for the container (docker family only). */
+    network?: string;
+    /** Extra `-e KEY=VALUE` env passed into the container (rarely needed). */
+    env?: Record<string, string>;
+    /** Injectable CLI exec — defaults to running the adapter's binary via execFile. */
+    exec?: ContainerExec;
+    /** Injectable fetch — defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** How long to wait for the container's endpoint + `/health` after start. Default 60s. */
+    readyTimeoutMs?: number;
+    /** Per-HTTP-call timeout. Default 30s. */
+    requestTimeoutMs?: number;
+    /**
+     * Run the Tester (`test`) job container privileged so its in-container
+     * Docker-in-Docker daemon can start and the Tester can `docker compose up` the
+     * service's local infra. Only honoured by a runtime that supports DinD (the Apple
+     * adapter ignores it — it has no nested-container path; the engine refuses local-infra
+     * Tester runs there). Default true; set false to fall back to the harness's
+     * best-effort rootless daemon (e.g. under rootless Podman).
+     */
+    privilegedTestJobs?: boolean;
+}
+export declare class LocalContainerRunnerTransport implements RunnerTransport {
+    private readonly adapter;
+    private readonly image;
+    private readonly sharedSecret;
+    private readonly network?;
+    private readonly extraEnv;
+    private readonly exec;
+    private readonly fetchImpl;
+    private readonly readyTimeoutMs;
+    private readonly requestTimeoutMs;
+    private readonly privilegedTestJobs;
+    /** runId → resolved container handle, to spare a CLI lookup on the hot poll path. */
+    private readonly cache;
+    constructor(options: LocalContainerRunnerTransportOptions);
+    /** The runtime's capabilities (e.g. whether local Docker-in-Docker testing is possible). */
+    get capabilities(): import("./runtimes/containerRuntime.js").RuntimeCapabilities;
+    dispatch(ref: RunnerJobRef, spec: Record<string, unknown>, kind?: RunnerDispatchKind, options?: RunnerDispatchOptions): Promise<void>;
+    poll(ref: RunnerJobRef): Promise<RunnerJobView>;
+    /**
+     * Reclaim the per-RUN container now rather than leaving it idle — this tears down the
+     * whole run's container (and with it any step still running in it). Best-effort and
+     * idempotent: removing an already-gone container is a no-op.
+     */
+    release(ref: RunnerJobRef): Promise<void>;
+    /**
+     * Reap exited per-run containers this transport manages — orphans a crash or hard
+     * kill left behind (release() never ran for them). Best-effort; returns the count
+     * removed. Call once at boot, before any job is in flight.
+     */
+    reapExited(): Promise<number>;
+    private url;
+    /** The container handle for a run from the cache, else rediscovered via the runtime. */
+    private resolve;
+    private waitForEndpoint;
+    private waitForHealth;
+}
+/**
+ * Build a {@link LocalContainerRunnerTransport} from the process environment. The image
+ * ref (`LOCAL_HARNESS_IMAGE`) is required; the runtime adapter is selected by
+ * `LOCAL_CONTAINER_RUNTIME` (docker | podman | orbstack | colima | apple); everything
+ * else has sane local defaults.
+ */
+export declare function createLocalContainerTransportFromEnv(env: NodeJS.ProcessEnv): LocalContainerRunnerTransport;
+//# sourceMappingURL=LocalContainerRunnerTransport.d.ts.map

package/dist/LocalContainerRunnerTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalContainerRunnerTransport.d.ts","sourceRoot":"","sources":["../src/LocalContainerRunnerTransport.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAG7B,MAAM,qBAAqB,CAAA;AA4B5B,mFAAmF;AACnF,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,MAAM,WAAW,oCAAoC;IACnD,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAA;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,mFAAmF;IACnF,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAID,qBAAa,6BAA8B,YAAW,eAAe;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAE5C,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiE;IAEvF,YAAY,OAAO,EAAE,oCAAoC,EAqBxD;IAED,4FAA4F;IAC5F,IAAI,YAAY,iEAEf;IAEK,QAAQ,CACZ,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,GAAE,kBAA0B,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Cf;IAEK,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAgCpD;IAED;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9C;IAED;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAElC;IAID,OAAO,CAAC,GAAG;IAIX,wFAAwF;YAC1E,OAAO;YAcP,eAAe;YAYf,aAAa;CAoB5B;AAUD;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,6BAA6B,CAkB/B"}

package/dist/LocalContainerRunnerTransport.js

@@ -0,0 +1,247 @@
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { promisify } from 'node:util';
+import { resolveDockerResources } from '@cat-factory/contracts';
+import { createRuntimeAdapter, DockerRuntimeAdapter, } from './runtimes/index.js';
+const execFileAsync = promisify(execFile);
+// The local-mode runner backend: each RUN gets its OWN local container — the SAME
+// executor-harness image the Cloudflare Worker runs per-run Containers from — which
+// hosts that run's whole sequence of step jobs. It is the local analogue of
+// `CloudflareContainerTransport` (a per-run Cloudflare Container) and of
+// `RunnerPoolTransport` (an org's self-hosted pool): the ContainerAgentExecutor drives
+// all three identically through the `RunnerTransport` port, addressed by a
+// {@link RunnerJobRef} — the run id (which container) plus the per-step job id.
+//
+// HOW it talks to the runtime is delegated to a {@link ContainerRuntimeAdapter}, so this
+// transport supports Docker, Podman, OrbStack, Colima (the Docker-CLI adapter) and
+// Apple's `container` (its own adapter, VM-per-container, connect-by-IP) without forking.
+// This class owns only the runtime-agnostic lifecycle: start a container per RUN, cache
+// its endpoint, re-attach the run's later steps to it, poll the harness over HTTP, and
+// reap it. The harness reaches this service's LLM proxy at the runtime's host alias and
+// clones/pushes to github.com directly with the per-job token in the request body.
+// The failed-poll error the engine classifies as a container eviction (matched by
+// orchestration `isContainerEvictionError`, also used by the bootstrap flow). A
+// vanished/exited local container maps to it so the run stops and the stale-run
+// sweeper can re-drive it — mirroring the Worker transport's 404 mapping.
+const EVICTION_ERROR = 'Job not found (container evicted or crashed)';
+const SECRET_HEADER = 'x-harness-secret';
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class LocalContainerRunnerTransport {
+    adapter;
+    image;
+    sharedSecret;
+    network;
+    extraEnv;
+    exec;
+    fetchImpl;
+    readyTimeoutMs;
+    requestTimeoutMs;
+    privilegedTestJobs;
+    /** runId → resolved container handle, to spare a CLI lookup on the hot poll path. */
+    cache = new Map();
+    constructor(options) {
+        this.adapter =
+            options.adapter ??
+                new DockerRuntimeAdapter({
+                    id: 'docker',
+                    binary: 'docker',
+                    hostAlias: 'host.docker.internal',
+                    addHostGateway: true,
+                    localDind: true,
+                });
+        this.image = options.image;
+        this.sharedSecret = options.sharedSecret ?? randomBytes(24).toString('hex');
+        this.network = options.network;
+        this.extraEnv = options.env ?? {};
+        this.exec =
+            options.exec ??
+                ((args) => execFileAsync(this.adapter.binary, args, { maxBuffer: 16 * 1024 * 1024 }));
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.readyTimeoutMs = options.readyTimeoutMs ?? 60_000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.privilegedTestJobs = options.privilegedTestJobs ?? true;
+    }
+    /** The runtime's capabilities (e.g. whether local Docker-in-Docker testing is possible). */
+    get capabilities() {
+        return this.adapter.capabilities;
+    }
+    async dispatch(ref, spec, kind = 'run', options) {
+        // The container is per-RUN: a run's first step starts it, later steps re-attach to
+        // it (resolved by the run id), and the harness keys each step's job by the per-step
+        // `ref.jobId` carried in the spec body.
+        const runId = ref.runId;
+        let resolved = await this.resolve(runId);
+        if (!resolved) {
+            // A prior attempt may have left an exited/dead container under this run (resolve()
+            // returns undefined for one whose endpoint is gone). Remove any such container
+            // first so it can't shadow the fresh one in later lookups.
+            await this.adapter.removeRun(this.exec, runId);
+            const containerId = await this.adapter.run(this.exec, {
+                runId,
+                image: this.image,
+                sharedSecret: this.sharedSecret,
+                // The Tester stands its infra up with `docker compose` INSIDE the job container
+                // (Docker-in-Docker), so run that one kind privileged. Runtimes without DinD
+                // ignore it (and the engine never asks them to run local-infra Tester jobs).
+                privileged: kind === 'test' && this.privilegedTestJobs,
+                network: this.network,
+                env: this.extraEnv,
+                instanceSize: options?.instanceSize
+                    ? resolveDockerResources(options.instanceSize)
+                    : undefined,
+            });
+            const endpoint = await this.waitForEndpoint(containerId);
+            resolved = { containerId, ...endpoint };
+            this.cache.set(runId, resolved);
+            await this.waitForHealth(endpoint);
+        }
+        // POST the job to the single harness endpoint, with the kind in the body. Idempotent:
+        // re-attaching to an already-running container re-POSTs, which the harness's per-id
+        // registry treats as a re-attach.
+        const res = await this.fetchImpl(this.url(resolved, '/jobs'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', [SECRET_HEADER]: this.sharedSecret },
+            body: JSON.stringify({ ...spec, kind }),
+            signal: AbortSignal.timeout(this.requestTimeoutMs),
+        });
+        if (!res.ok) {
+            throw new Error(`Local container dispatch failed (HTTP ${res.status}): ${await safeText(res)}`);
+        }
+    }
+    async poll(ref) {
+        const resolved = await this.resolve(ref.runId);
+        // No container for this run at all → it was evicted/reaped (or never started).
+        if (!resolved)
+            return { state: 'failed', error: EVICTION_ERROR };
+        let res;
+        try {
+            // Address the per-RUN container, but read the per-step job by its own id.
+            res = await this.fetchImpl(this.url(resolved, `/jobs/${encodeURIComponent(ref.jobId)}`), {
+                method: 'GET',
+                headers: { [SECRET_HEADER]: this.sharedSecret },
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
+            });
+        }
+        catch (err) {
+            // Connection refused / DNS gone: the container most likely exited. Confirm via
+            // the runtime — if it is no longer running, report an eviction so the run stops;
+            // otherwise surface the transient error so the caller can retry.
+            if (!(await this.adapter.isRunning(this.exec, resolved.containerId))) {
+                this.cache.delete(ref.runId);
+                return { state: 'failed', error: EVICTION_ERROR };
+            }
+            throw err;
+        }
+        // The container is up but the harness no longer knows this job id (it was reaped
+        // after completion, or the container was recreated): treat as an eviction.
+        if (res.status === 404)
+            return { state: 'failed', error: EVICTION_ERROR };
+        if (!res.ok) {
+            throw new Error(`Local container job poll failed (HTTP ${res.status}): ${await safeText(res)}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Reclaim the per-RUN container now rather than leaving it idle — this tears down the
+     * whole run's container (and with it any step still running in it). Best-effort and
+     * idempotent: removing an already-gone container is a no-op.
+     */
+    async release(ref) {
+        const containerId = this.cache.get(ref.runId)?.containerId ?? (await this.adapter.find(this.exec, ref.runId));
+        this.cache.delete(ref.runId);
+        if (!containerId)
+            return;
+        await this.adapter.remove(this.exec, containerId);
+    }
+    /**
+     * Reap exited per-run containers this transport manages — orphans a crash or hard
+     * kill left behind (release() never ran for them). Best-effort; returns the count
+     * removed. Call once at boot, before any job is in flight.
+     */
+    async reapExited() {
+        return this.adapter.reapExited(this.exec);
+    }
+    // --- internals ----------------------------------------------------------
+    url(endpoint, path) {
+        return `http://${endpoint.host}:${endpoint.port}${path}`;
+    }
+    /** The container handle for a run from the cache, else rediscovered via the runtime. */
+    async resolve(runId) {
+        const cached = this.cache.get(runId);
+        if (cached)
+            return cached;
+        const containerId = await this.adapter.find(this.exec, runId);
+        if (!containerId)
+            return undefined;
+        const endpoint = await this.adapter.endpoint(this.exec, containerId);
+        if (!endpoint)
+            return undefined;
+        const resolved = { containerId, ...endpoint };
+        this.cache.set(runId, resolved);
+        return resolved;
+    }
+    async waitForEndpoint(containerId) {
+        const deadline = Date.now() + this.readyTimeoutMs;
+        for (;;) {
+            const endpoint = await this.adapter.endpoint(this.exec, containerId).catch(() => undefined);
+            if (endpoint)
+                return endpoint;
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for container ${containerId} to expose its endpoint`);
+            }
+            await delay(250);
+        }
+    }
+    async waitForHealth(endpoint) {
+        const deadline = Date.now() + this.readyTimeoutMs;
+        for (;;) {
+            try {
+                const res = await this.fetchImpl(this.url(endpoint, '/health'), {
+                    method: 'GET',
+                    signal: AbortSignal.timeout(Math.min(this.requestTimeoutMs, 5_000)),
+                });
+                if (res.ok)
+                    return;
+            }
+            catch {
+                // not up yet
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for the harness at ${endpoint.host}:${endpoint.port} to become healthy`);
+            }
+            await delay(300);
+        }
+    }
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 500);
+    }
+    catch {
+        return '(no body)';
+    }
+}
+/**
+ * Build a {@link LocalContainerRunnerTransport} from the process environment. The image
+ * ref (`LOCAL_HARNESS_IMAGE`) is required; the runtime adapter is selected by
+ * `LOCAL_CONTAINER_RUNTIME` (docker | podman | orbstack | colima | apple); everything
+ * else has sane local defaults.
+ */
+export function createLocalContainerTransportFromEnv(env) {
+    const image = env.LOCAL_HARNESS_IMAGE?.trim();
+    if (!image) {
+        throw new Error('LOCAL_HARNESS_IMAGE is required for local mode: set it to the executor-harness image ref ' +
+            '(a GHCR pull or a tag built from backend/internal/executor-harness/Dockerfile).');
+    }
+    return new LocalContainerRunnerTransport({
+        image,
+        adapter: createRuntimeAdapter(env),
+        sharedSecret: env.HARNESS_SHARED_SECRET?.trim() || undefined,
+        network: env.LOCAL_DOCKER_NETWORK?.trim() || undefined,
+        // Default on: the Tester stands its docker-compose infra up via Docker-in-Docker,
+        // which needs a privileged job container. Set to `false` for runtimes that run
+        // nested containers without it (e.g. rootless Podman).
+        privilegedTestJobs: env.LOCAL_DOCKER_PRIVILEGED_TEST_JOBS?.trim() !== 'false',
+    });
+}
+//# sourceMappingURL=LocalContainerRunnerTransport.js.map

package/dist/LocalContainerRunnerTransport.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import type { AppConfig } from '@cat-factory/server';
+/**
+ * Apply local-mode env defaults onto a copy of {@link env}. Idempotent: an explicitly
+ * set value is always preserved, so calling it twice (loader + container) is safe.
+ */
+export declare function applyLocalDefaults(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The shared {@link AppConfig} with local-mode defaults applied. */
+export declare function loadLocalConfig(env: NodeJS.ProcessEnv): AppConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAgBpD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAuB5E;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAEjE"}

package/dist/config.js

@@ -0,0 +1,47 @@
+import { randomBytes } from 'node:crypto';
+import { loadNodeConfig } from '@cat-factory/node-server';
+import { resolveHostAlias } from './runtimes/index.js';
+// Local mode is a single developer running the whole product on their own machine.
+// It reuses the Node facade's config loader verbatim and only changes the defaults
+// that would otherwise force cloud-style setup:
+//   - the auth gate defaults OPEN (no GitHub OAuth app to register) — never in a
+//     production ENVIRONMENT (`loadNodeConfig` enforces that);
+//   - a session secret is generated if absent (it only signs the short-lived LLM-proxy
+//     tokens the local container uses; a per-process value is fine for dev);
+//   - PUBLIC_URL defaults to `host.docker.internal:<PORT>` so a job's container can
+//     reach this service's LLM proxy from inside Docker.
+// Every default is overridable: setting the corresponding env var wins.
+const DEFAULT_PORT = '8787';
+/**
+ * Apply local-mode env defaults onto a copy of {@link env}. Idempotent: an explicitly
+ * set value is always preserved, so calling it twice (loader + container) is safe.
+ */
+export function applyLocalDefaults(env) {
+    const port = env.PORT?.trim() || DEFAULT_PORT;
+    // The host alias the harness uses to reach this service depends on the runtime:
+    // `host.docker.internal` (Docker/Podman/OrbStack), `host.lima.internal` (Colima), or
+    // the vmnet gateway (Apple). An explicit LOCAL_HARNESS_HOST_ALIAS / PUBLIC_URL wins.
+    const hostAlias = resolveHostAlias(env);
+    return {
+        ...env,
+        // `|| 'true'` (not `??`) so an explicit empty `AUTH_DEV_OPEN=` still defaults open,
+        // consistent with the other fields here; set `AUTH_DEV_OPEN=false` to close the gate.
+        AUTH_DEV_OPEN: env.AUTH_DEV_OPEN?.trim() || 'true',
+        // Stable within a process; only signs short-lived proxy tokens for local jobs.
+        AUTH_SESSION_SECRET: env.AUTH_SESSION_SECRET?.trim() || randomBytes(32).toString('hex'),
+        // The shared key backing credential encryption at rest (document/task/runner/slack
+        // integrations, personal subscriptions). `loadNodeConfig` requires it, so generate a
+        // per-process key when absent — enough to boot and run a pipeline. Set ENCRYPTION_KEY
+        // explicitly to keep encrypted-at-rest credentials decryptable across restarts.
+        ENCRYPTION_KEY: env.ENCRYPTION_KEY?.trim() || randomBytes(32).toString('base64'),
+        // The harness (inside the container) posts to `${PUBLIC_URL}/v1`; the runtime's host
+        // alias routes back to this service on the host. The docker-family transport
+        // publishes that alias on Linux via `--add-host=<alias>:host-gateway`.
+        PUBLIC_URL: env.PUBLIC_URL?.trim() || `http://${hostAlias}:${port}`,
+    };
+}
+/** The shared {@link AppConfig} with local-mode defaults applied. */
+export function loadLocalConfig(env) {
+    return loadNodeConfig(applyLocalDefaults(env));
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEtD,mFAAmF;AACnF,mFAAmF;AACnF,gDAAgD;AAChD,iFAAiF;AACjF,+DAA+D;AAC/D,uFAAuF;AACvF,6EAA6E;AAC7E,oFAAoF;AACpF,yDAAyD;AACzD,wEAAwE;AAExE,MAAM,YAAY,GAAG,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,YAAY,CAAA;IAC7C,gFAAgF;IAChF,qFAAqF;IACrF,qFAAqF;IACrF,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;IACvC,OAAO;QACL,GAAG,GAAG;QACN,oFAAoF;QACpF,sFAAsF;QACtF,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,MAAM;QAClD,+EAA+E;QAC/E,mBAAmB,EAAE,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QACvF,mFAAmF;QACnF,qFAAqF;QACrF,sFAAsF;QACtF,gFAAgF;QAChF,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAChF,qFAAqF;QACrF,6EAA6E;QAC7E,uEAAuE;QACvE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,UAAU,SAAS,IAAI,IAAI,EAAE;KACpE,CAAA;AACH,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,GAAsB;IACpD,OAAO,cAAc,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAA;AAChD,CAAC"}

package/dist/container.d.ts

@@ -0,0 +1,4 @@
+import type { NodeContainerOptions } from '@cat-factory/node-server';
+import type { ServerContainer } from '@cat-factory/server';
+export declare function buildLocalContainer(options: NodeContainerOptions): ServerContainer;
+//# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAyB7F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,eAAe,CAiFlF"}

package/dist/container.js

@@ -0,0 +1,94 @@
+import { DrizzleGitHubInstallationRepository, buildNodeContainer, loadNodeConfig, } from '@cat-factory/node-server';
+import { applyLocalDefaults } from './config.js';
+import { createLocalGitHubClient, fetchPatAccount, githubPatCreationUrl } from './github.js';
+import { AutoProvisioningInstallationRepository } from './installations.js';
+import { createLocalContainerTransportFromEnv, } from './LocalContainerRunnerTransport.js';
+import { createRuntimeAdapter } from './runtimes/index.js';
+// The local-mode composition root. It is intentionally thin: the ENTIRE Drizzle/
+// Postgres persistence, pg-boss durable execution, gateways and model provisioning
+// come from `buildNodeContainer` unchanged. Local mode only swaps the two
+// differentiators behind the seams `buildNodeContainer` exposes:
+//   - the runner backend → a per-run local container (LocalContainerRunnerTransport,
+//     Docker/Podman/OrbStack/Colima/Apple `container`) instead of a self-hosted pool;
+//   - the push/clone token → a static GitHub PAT (`GITHUB_PAT`) instead of a GitHub
+//     App installation token.
+// Repo resolution is unchanged: the executor still resolves a block's repo from the
+// `github_repos` / `github_installations` projection (seed those rows for a target
+// repo with the link helper). So a developer can run coder/mocker/playwright/
+// blueprints/ci-fixer/merger jobs entirely locally, pushing real branches and opening
+// real PRs on github.com via the PAT.
+export function buildLocalContainer(options) {
+    const env = applyLocalDefaults(options.env ?? process.env);
+    const pat = env.GITHUB_PAT?.trim();
+    const base = options.config ?? loadNodeConfig(env);
+    // Tag the config as local mode and, when no PAT is set, carry the (scopes-preselected)
+    // creation URL so the SPA can surface it as a dismissible banner — the server-side warn
+    // log alone is easy to miss in a dev terminal. With a PAT, force the GitHub integration
+    // ON: the Node loader only enables it for a configured GitHub App, but local mode reaches
+    // GitHub through the PAT-backed client, so the read/link endpoints (connection, available
+    // repos, "add from existing repo") should be served the same way.
+    const config = {
+        ...base,
+        ...(pat ? { github: { ...base.github, enabled: true } } : {}),
+        localMode: {
+            enabled: true,
+            ...(pat ? {} : { githubPatSetupUrl: githubPatCreationUrl() }),
+        },
+    };
+    // Local mode has no GitHub-App connect flow, so a workspace's installation is conjured
+    // from the PAT on first read (see AutoProvisioningInstallationRepository): the synthetic
+    // row makes `getConnection` report connected and gives the sync service an installation
+    // id to list/link repos under. The PAT account is fetched once and shared across
+    // workspaces (a single developer's token).
+    let accountPromise;
+    const resolveAccount = () => (accountPromise ??= fetchPatAccount(env));
+    const githubInstallationRepository = pat && options.db
+        ? new AutoProvisioningInstallationRepository(new DrizzleGitHubInstallationRepository(options.db), resolveAccount)
+        : undefined;
+    // The Docker transport is constructed LAZILY on first container-job dispatch, so the
+    // service still boots to serve the board (and inline kinds) when LOCAL_HARNESS_IMAGE
+    // is unset — only repo-operating kinds then fail, loudly and with a clear message,
+    // mirroring how the Node facade treats a missing runner backend.
+    let transport;
+    const resolveTransport = () => {
+        transport ??= createLocalContainerTransportFromEnv(env);
+        return Promise.resolve(transport);
+    };
+    // The selected runtime decides whether the Tester's LOCAL docker-compose infra (run
+    // via Docker-in-Docker) is possible: Docker/Podman/OrbStack/Colima can nest a daemon,
+    // Apple `container` (one VM per container) cannot. Surface that capability to the
+    // engine so it refuses a local-infra Tester run on an incapable runtime ("limited
+    // mode") instead of dispatching a job that can't stand its dependencies up. Building
+    // the adapter is pure (no IO), so this is cheap even though the transport stays lazy.
+    const localTestInfraSupported = createRuntimeAdapter(env).capabilities.localDind;
+    return buildNodeContainer({
+        ...options,
+        env,
+        config,
+        // Always dispatch container jobs to the local Docker transport (a constant
+        // resolver, ignoring workspace — local mode has no per-workspace runner pools).
+        resolveTransport,
+        // Authenticate git with the developer's PAT when present. Absent → the executor
+        // falls back to the GitHub App path (and is null without it), so container kinds
+        // fail loudly rather than silently mis-running.
+        ...(pat ? { mintInstallationToken: async () => pat } : {}),
+        // The PAT-backed GitHub client wires the CI gate + merge / mergeability providers,
+        // so a local pipeline gates on real GitHub Actions CI and merges the PR for real, AND
+        // serves the read/link endpoints (it lists repos via /user/repos, the PAT analogue of
+        // the App-only /installation/repositories).
+        ...(pat ? { githubClient: createLocalGitHubClient(env) } : {}),
+        // Auto-provision the synthetic per-workspace installation so the integration reports
+        // connected with no manual connect step.
+        ...(githubInstallationRepository ? { githubInstallationRepository } : {}),
+        overrides: {
+            ...options.overrides,
+            // The local PAT carries `workflow` scope (the creation URL pre-selects it), so the
+            // connection isn't missing workflows: write — report it granted to suppress the
+            // advisory banner. (The App-permissions probe this normally uses needs an app JWT.)
+            ...(pat ? { workflowsGranted: async () => true } : {}),
+            // Gate the Tester's local-infra mode on the runtime's Docker-in-Docker support.
+            localTestInfraSupported,
+        },
+    });
+}
+//# sourceMappingURL=container.js.map

package/dist/container.js.map

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

package/dist/github.d.ts

@@ -0,0 +1,36 @@
+import type { GitHubClient } from '@cat-factory/kernel';
+import { type AppTokenSource } from '@cat-factory/server';
+import type { PatAccount } from './installations.js';
+/**
+ * A GitHub "new personal access token (classic)" URL with the scopes local mode needs
+ * pre-selected, so a developer without a PAT can click straight through to create one.
+ * Classic tokens are used (not fine-grained) because only the classic form accepts the
+ * `scopes` query param for pre-selection.
+ */
+export declare function githubPatCreationUrl(): string;
+/** An {@link AppTokenSource} that returns a fixed PAT for every installation call. */
+export declare class StaticTokenAppRegistry implements AppTokenSource {
+    private readonly token;
+    readonly defaultAppId = "";
+    constructor(token: string);
+    apps(): readonly {
+        appId: string;
+    }[];
+    authForApp(): {
+        appJwt(): Promise<string>;
+    };
+    installationToken(): Promise<string>;
+}
+/**
+ * Read the PAT's own account (`GET /user`) so a synthetic installation can be attributed
+ * to it in the connect UI. Best-effort: a failed/forbidden call falls back to an empty
+ * login (the link flow only needs the installation row to exist, not its account label).
+ */
+export declare function fetchPatAccount(env: NodeJS.ProcessEnv): Promise<PatAccount>;
+/**
+ * Build a {@link GitHubClient} that authenticates with the PAT, for the CI / merge /
+ * mergeability gates AND the repo-link / board "add from repo" flows. Returns undefined
+ * when no PAT is configured (the gates then pass through, like the Node default).
+ */
+export declare function createLocalGitHubClient(env: NodeJS.ProcessEnv): GitHubClient | undefined;
+//# sourceMappingURL=github.d.ts.map

package/dist/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,YAAY,EAMb,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,KAAK,cAAc,EAAqB,MAAM,qBAAqB,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAgBpD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED,sFAAsF;AACtF,qBAAa,sBAAuB,YAAW,cAAc;IAE/C,OAAO,CAAC,QAAQ,CAAC,KAAK;IADlC,QAAQ,CAAC,YAAY,MAAK;IAC1B,YAA6B,KAAK,EAAE,MAAM,EAAI;IAE9C,IAAI,IAAI,SAAS;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAEnC;IAED,UAAU,IAAI;QAAE,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAK1C;IAED,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEnC;CACF;AAoGD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBjF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,YAAY,GAAG,SAAS,CAgBxF"}