@north-light/crouter-env-docker 0.3.286

package/README.md

@@ -0,0 +1,91 @@
+# @north-light/crouter-env-docker
+
+A Docker `Environment` for the [crouter SDK](https://www.npmjs.com/package/@north-light/crouter-sdk) (`@north-light/crouter-sdk`'s `generate()`): run a [`crtrd`](https://github.com/vallum-security/crouter/tree/main/docker) container, wait for it to come up, and hand back the `{ baseUrl, headers }` shape the SDK needs to talk to it.
+
+Zero crouter imports — this package depends on nothing but Node built-ins. It shells out to the `docker` CLI via `child_process` and structurally satisfies the SDK's `Environment` interface (copied by hand into this package's own types, not imported).
+
+## Install
+
+```sh
+npm install @north-light/crouter-env-docker
+```
+
+## Usage
+
+```ts
+import { start } from '@north-light/crouter-env-docker';
+
+const env = await start(); // defaults to ghcr.io/vallum-security/crtrd:latest
+const { baseUrl, headers } = await env.daemon();
+// baseUrl:  http://127.0.0.1:<random free port>
+// headers:  { Authorization: 'Bearer <randomly generated CRTRD_TOKEN>' }
+
+await env.stop(); // stops and removes the container
+```
+
+Named + volume-backed = persistent, addressable by a later `attach()`:
+
+```ts
+import { start, attach } from '@north-light/crouter-env-docker';
+
+await start({ image: 'crtrd:local', name: 'my-agent', volume: 'my-agent-home' });
+// ... later, possibly from a different process ...
+const env = await attach('my-agent');
+const { baseUrl, headers } = await env.daemon();
+await env.stop(); // stops only — the container and its volume survive
+```
+
+### With the crouter SDK
+
+```ts
+import { start } from '@north-light/crouter-env-docker';
+import { generate } from '@north-light/crouter-sdk';
+import { z } from 'zod';
+
+const env = await start({ image: 'crtrd:local', env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! } });
+
+const result = await generate({
+  prompt: 'Read package.json and report the package name and version.',
+  schema: z.object({ name: z.string(), version: z.string() }),
+  env,
+});
+
+await env.stop();
+```
+
+## API
+
+```ts
+export interface Environment {
+  daemon(): Promise<{ baseUrl?: string; socketPath?: string; headers?: Record<string, string> }>;
+}
+
+export interface DockerEnvironment extends Environment {
+  containerId: string;
+  name: string;
+  stop(): Promise<void>; // stop + remove (start()'s container) or just stop (attach()'s)
+}
+
+export function start(opts?: {
+  image?: string;               // default: DEFAULT_IMAGE (ghcr.io/vallum-security/crtrd:<pin> — see below)
+  env?: Record<string, string>; // forwarded to the container as -e KEY=VALUE (model provider keys, etc)
+  name?: string;                // container name; default: a generated random name
+  volume?: string;              // named volume mounted at CRTR_HOME; default: none (ephemeral home)
+  port?: number;                // host port, always bound to 127.0.0.1; default: a random free port docker assigns
+}): Promise<DockerEnvironment>;
+
+export function attach(name: string): Promise<DockerEnvironment>;
+```
+
+- `start()` generates a random `CRTRD_TOKEN`, passes it into the container as `-e`, and resolves only once `/healthz` answers `200` with that bearer through the mapped host port.
+- `attach(name)` reads the mapped port and `CRTRD_TOKEN` off an already-running container via `docker inspect`. It throws a clear error if the container does not exist, is not running, or was not started with a `CRTRD_TOKEN` env var.
+- The token is never logged.
+- The container port is published to `127.0.0.1` only, never `0.0.0.0` — the daemon holds whatever provider keys you passed in `env`, and must not be reachable from the LAN.
+
+## Default image
+
+`DEFAULT_IMAGE` is `ghcr.io/vallum-security/crtrd:latest`, which the release workflow pushes alongside each version tag. Pass `image` to pin a version, or to run a locally built tag (`crtrd:local`, see [`docker/README.md`](../../docker/README.md)).
+
+## Requirements
+
+The `docker` CLI, reachable and authenticated for whatever registry `image` names, on `PATH`.

package/dist/docker-cli.d.ts

@@ -0,0 +1,10 @@
+/** A `docker` CLI invocation that exited non-zero. Carries stderr separately
+ *  so callers can fold it into a more specific message without re-parsing. */
+export declare class DockerCliError extends Error {
+    readonly stderr: string;
+    constructor(message: string, stderr: string);
+}
+/** Run `docker <args>` and return trimmed stdout, or throw `DockerCliError`
+ *  with stderr folded into the message. Never logs anything itself — a
+ *  caller passing `-e CRTRD_TOKEN=...` in `args` must not print `args`. */
+export declare function docker(args: string[]): Promise<string>;

package/dist/docker-cli.js

@@ -0,0 +1,30 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** A `docker` CLI invocation that exited non-zero. Carries stderr separately
+ *  so callers can fold it into a more specific message without re-parsing. */
+export class DockerCliError extends Error {
+    stderr;
+    constructor(message, stderr) {
+        super(message);
+        this.name = 'DockerCliError';
+        this.stderr = stderr;
+    }
+}
+/** Run `docker <args>` and return trimmed stdout, or throw `DockerCliError`
+ *  with stderr folded into the message. Never logs anything itself — a
+ *  caller passing `-e CRTRD_TOKEN=...` in `args` must not print `args`. */
+export async function docker(args) {
+    try {
+        const { stdout } = await execFileAsync('docker', args, { maxBuffer: 16 * 1024 * 1024 });
+        return stdout.trim();
+    }
+    catch (error) {
+        const stderr = isExecError(error) ? error.stderr.trim() : '';
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DockerCliError(`docker ${args[0] ?? ''} failed: ${stderr || message}`, stderr);
+    }
+}
+function isExecError(error) {
+    return typeof error === 'object' && error !== null && typeof error.stderr === 'string';
+}

package/dist/health.d.ts

@@ -0,0 +1,7 @@
+/** Poll `<baseUrl>/healthz` until it answers 200, `opts.timeoutMs` elapses,
+ *  or `opts.isAlive` reports the container already exited. */
+export declare function waitForHealthy(baseUrl: string, headers: Record<string, string>, opts: {
+    timeoutMs: number;
+    intervalMs: number;
+    isAlive?: () => Promise<boolean>;
+}): Promise<void>;

package/dist/health.js

@@ -0,0 +1,38 @@
+import { request } from 'node:http';
+/** Poll `<baseUrl>/healthz` until it answers 200, `opts.timeoutMs` elapses,
+ *  or `opts.isAlive` reports the container already exited. */
+export async function waitForHealthy(baseUrl, headers, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        if (opts.isAlive && !(await opts.isAlive())) {
+            throw new Error(`container exited before /healthz answered${lastError ? ` (last probe: ${lastError})` : ''}`);
+        }
+        try {
+            const status = await probe(baseUrl, headers);
+            if (status === 200)
+                return;
+            lastError = `HTTP ${status}`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await sleep(opts.intervalMs);
+    }
+    throw new Error(`/healthz did not return 200 within ${opts.timeoutMs}ms (last: ${lastError ?? 'no response'})`);
+}
+function probe(baseUrl, headers) {
+    return new Promise((resolve, reject) => {
+        const url = new URL('/healthz', baseUrl);
+        const req = request(url, { method: 'GET', headers, timeout: 2000 }, (res) => {
+            res.resume();
+            resolve(res.statusCode ?? 0);
+        });
+        req.on('timeout', () => req.destroy(new Error('healthz probe timed out')));
+        req.on('error', reject);
+        req.end();
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { DockerEnvironment, Environment, StartOptions } from './types.js';
+export type { DockerEnvironment, Environment, StartOptions };
+/**
+ * Default image tag — the `latest` the release workflow's `publish-image` job
+ * pushes alongside the version tag. Pass `image` to pin a version or to run a
+ * locally built tag (e.g. `crtrd:local`).
+ */
+export declare const DEFAULT_IMAGE = "ghcr.io/vallum-security/crtrd:latest";
+/** Run the crtrd image, wait until `/healthz` answers 200 through the mapped
+ *  port, and return an `Environment` pointed at it. `stop()` stops and
+ *  removes the container. */
+export declare function start(opts?: StartOptions): Promise<DockerEnvironment>;
+/** Wrap an already-running container by name. Reads its mapped host port and
+ *  `CRTRD_TOKEN` via `docker inspect`. `stop()` only stops the container —
+ *  it does not remove it. */
+export declare function attach(name: string): Promise<DockerEnvironment>;

package/dist/index.js

@@ -0,0 +1,86 @@
+import { randomBytes } from 'node:crypto';
+import { docker } from './docker-cli.js';
+import { waitForHealthy } from './health.js';
+import { CONTAINER_PORT, inspectContainer, isContainerRunning, readHostPortFromInspect, readTokenFromInspect, resolveHostPort, tryReadLogs, } from './inspect.js';
+/**
+ * Default image tag — the `latest` the release workflow's `publish-image` job
+ * pushes alongside the version tag. Pass `image` to pin a version or to run a
+ * locally built tag (e.g. `crtrd:local`).
+ */
+export const DEFAULT_IMAGE = 'ghcr.io/vallum-security/crtrd:latest';
+const HEALTH_TIMEOUT_MS = 60_000;
+const HEALTH_INTERVAL_MS = 300;
+function generateToken() {
+    return randomBytes(24).toString('hex');
+}
+function generateName() {
+    return `crtrd-env-${randomBytes(6).toString('hex')}`;
+}
+/** Run the crtrd image, wait until `/healthz` answers 200 through the mapped
+ *  port, and return an `Environment` pointed at it. `stop()` stops and
+ *  removes the container. */
+export async function start(opts = {}) {
+    const image = opts.image ?? DEFAULT_IMAGE;
+    const name = opts.name ?? generateName();
+    const token = generateToken();
+    const args = ['run', '-d', '--name', name, '-e', `CRTRD_TOKEN=${token}`];
+    for (const [key, value] of Object.entries(opts.env ?? {})) {
+        args.push('-e', `${key}=${value}`);
+    }
+    if (opts.volume) {
+        args.push('-v', `${opts.volume}:/home/agent/.crouter`);
+    }
+    // Bind loopback explicitly: docker's default publishes to 0.0.0.0, which
+    // would put a daemon holding the caller's provider keys on the LAN behind
+    // nothing but its bearer token.
+    args.push('-p', `127.0.0.1:${opts.port ?? 0}:${CONTAINER_PORT}`);
+    args.push(image);
+    const containerId = await docker(args);
+    const headers = { Authorization: `Bearer ${token}` };
+    let baseUrl;
+    try {
+        const port = await resolveHostPort(containerId);
+        baseUrl = `http://127.0.0.1:${port}`;
+        await waitForHealthy(baseUrl, headers, {
+            timeoutMs: HEALTH_TIMEOUT_MS,
+            intervalMs: HEALTH_INTERVAL_MS,
+            isAlive: () => isContainerRunning(containerId),
+        });
+    }
+    catch (error) {
+        const logs = await tryReadLogs(containerId);
+        await docker(['rm', '-f', containerId]).catch(() => { });
+        throw new Error(`crouter-env-docker: start() container '${name}' (${containerId.slice(0, 12)}) never became healthy: ${error instanceof Error ? error.message : String(error)}${logs ? `\n--- docker logs ---\n${logs}` : ''}`);
+    }
+    return {
+        containerId,
+        name,
+        async daemon() {
+            return { baseUrl, headers };
+        },
+        async stop() {
+            await docker(['rm', '-f', containerId]);
+        },
+    };
+}
+/** Wrap an already-running container by name. Reads its mapped host port and
+ *  `CRTRD_TOKEN` via `docker inspect`. `stop()` only stops the container —
+ *  it does not remove it. */
+export async function attach(name) {
+    const inspection = await inspectContainer(name);
+    const containerId = inspection.Id;
+    const token = readTokenFromInspect(inspection, name);
+    const port = readHostPortFromInspect(inspection, name);
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const headers = { Authorization: `Bearer ${token}` };
+    return {
+        containerId,
+        name,
+        async daemon() {
+            return { baseUrl, headers };
+        },
+        async stop() {
+            await docker(['stop', containerId]);
+        },
+    };
+}

package/dist/inspect.d.ts

@@ -0,0 +1,30 @@
+export declare const CONTAINER_PORT = 7777;
+interface DockerInspectOutput {
+    Id: string;
+    State?: {
+        Running?: boolean;
+    };
+    Config?: {
+        Env?: string[];
+    };
+    NetworkSettings?: {
+        Ports?: Record<string, {
+            HostIp?: string;
+            HostPort?: string;
+        }[] | null>;
+    };
+}
+/** `docker inspect <name>` for one container. Throws a message naming `name`
+ *  when the container does not exist — the caller (`attach()`) surfaces this
+ *  as-is, which is the "attach fails clearly because the container is gone"
+ *  contract. */
+export declare function inspectContainer(name: string): Promise<DockerInspectOutput>;
+export declare function readTokenFromInspect(inspection: DockerInspectOutput, name: string): string;
+export declare function readHostPortFromInspect(inspection: DockerInspectOutput, name: string): number;
+export declare function isContainerRunning(containerId: string): Promise<boolean>;
+export declare function tryReadLogs(containerId: string): Promise<string | undefined>;
+/** `docker port <id> <containerPort>/tcp` prints one host binding per line —
+ *  e.g. `0.0.0.0:54321` and `[::]:54321` for a dual-stack mapping. Take the
+ *  first line's port. */
+export declare function resolveHostPort(containerId: string): Promise<number>;
+export {};

package/dist/inspect.js

@@ -0,0 +1,66 @@
+import { docker } from './docker-cli.js';
+export const CONTAINER_PORT = 7777;
+/** `docker inspect <name>` for one container. Throws a message naming `name`
+ *  when the container does not exist — the caller (`attach()`) surfaces this
+ *  as-is, which is the "attach fails clearly because the container is gone"
+ *  contract. */
+export async function inspectContainer(name) {
+    let stdout;
+    try {
+        stdout = await docker(['inspect', name]);
+    }
+    catch (error) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — no such container (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const parsed = JSON.parse(stdout);
+    const entry = parsed[0];
+    if (!entry) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — docker inspect returned no data`);
+    }
+    return entry;
+}
+export function readTokenFromInspect(inspection, name) {
+    const env = inspection.Config?.Env ?? [];
+    const entry = env.find((line) => line.startsWith('CRTRD_TOKEN='));
+    if (!entry) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — container has no CRTRD_TOKEN env var (was it started by this package's start()?)`);
+    }
+    return entry.slice('CRTRD_TOKEN='.length);
+}
+export function readHostPortFromInspect(inspection, name) {
+    const bindings = inspection.NetworkSettings?.Ports?.[`${CONTAINER_PORT}/tcp`];
+    const hostPort = bindings?.[0]?.HostPort;
+    if (!hostPort) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — no host port mapped for ${CONTAINER_PORT}/tcp (is the container running?)`);
+    }
+    return Number(hostPort);
+}
+export async function isContainerRunning(containerId) {
+    try {
+        const state = await docker(['inspect', '-f', '{{.State.Running}}', containerId]);
+        return state === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+export async function tryReadLogs(containerId) {
+    try {
+        return await docker(['logs', '--tail', '50', containerId]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `docker port <id> <containerPort>/tcp` prints one host binding per line —
+ *  e.g. `0.0.0.0:54321` and `[::]:54321` for a dual-stack mapping. Take the
+ *  first line's port. */
+export async function resolveHostPort(containerId) {
+    const output = await docker(['port', containerId, `${CONTAINER_PORT}/tcp`]);
+    const firstLine = output.split('\n')[0]?.trim() ?? '';
+    const match = firstLine.match(/:(\d+)$/);
+    if (!match) {
+        throw new Error(`crouter-env-docker: could not determine the host port docker mapped for container ${containerId} (docker port output: ${JSON.stringify(output)})`);
+    }
+    return Number(match[1]);
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Structural mirror of the crouter SDK's `Environment` interface
+ * (`packages/crouter-sdk`, `crouter-sdk-design.md` unit B). Copied by hand,
+ * not imported — this package carries zero crouter/SDK dependencies, so a
+ * `DockerEnvironment` satisfies the SDK's `Environment` purely by shape. Keep
+ * this in sync with the SDK's definition if it changes.
+ */
+export interface Environment {
+    /** Where the crtrd for this run is. Called once per `generate()`. */
+    daemon(): Promise<{
+        baseUrl?: string;
+        socketPath?: string;
+        headers?: Record<string, string>;
+    }>;
+}
+export interface DockerEnvironment extends Environment {
+    /** The container's full id. */
+    containerId: string;
+    /** The container's name — as passed to `start({ name })` or generated, or the name passed to `attach()`. */
+    name: string;
+    /** `start()`'s container: stop and remove. `attach()`'s container: stop only. */
+    stop(): Promise<void>;
+}
+export interface StartOptions {
+    /**
+     * Image to run. Default: `DEFAULT_IMAGE` (`ghcr.io/vallum-security/crtrd:latest`).
+     * Pass a version tag to pin, or a locally built tag (e.g. `crtrd:local`).
+     */
+    image?: string;
+    /** Extra env vars forwarded into the container — model provider keys, etc. Never logged. */
+    env?: Record<string, string>;
+    /** Container name. A named container is later addressable via `attach()`. Default: a generated random name. */
+    name?: string;
+    /** Named volume mounted at `CRTR_HOME` (`/home/agent/.crouter`). Default: none — an ephemeral, unnamed home. */
+    volume?: string;
+    /** Host port to bind, always on `127.0.0.1`. Default: a random free port docker assigns. */
+    port?: number;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@north-light/crouter-env-docker",
+  "version": "0.3.286",
+  "description": "Docker Environment for the crouter SDK — start, attach to, and stop a crtrd container over the docker CLI. Zero crouter imports.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vallum-security/crouter.git",
+    "directory": "packages/crouter-env-docker"
+  },
+  "license": "UNLICENSED"
+}