@crewhaus/docker-images 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/docker-images",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Per-target-shape Docker images (multi-stage, non-root, healthchecked) + crewhaus build-image CLI wrapper (Section 32)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/docker-images"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/docker-images#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  type BuildRunner,
+  DockerImagesError,
+  TARGET_SHAPES,
+  buildImage,
+  dockerRoot,
+  dockerfilePath,
+  dockerfileSize,
+  fingerprintDockerfile,
+  isTargetShape,
+  listAvailableTargets,
+  loadDigests,
+  readDockerfile,
+  recordDigest,
+} from "./index";
+
+describe("TARGET_SHAPES", () => {
+  test("contains exactly the 12 shipped target shapes", () => {
+    expect(TARGET_SHAPES).toEqual([
+      "cli",
+      "workflow",
+      "channel",
+      "graph",
+      "managed",
+      "pipeline",
+      "crew",
+      "research",
+      "batch",
+      "voice",
+      "browser",
+      "eval",
+    ]);
+  });
+
+  test("isTargetShape accepts every shape and rejects unknowns", () => {
+    for (const t of TARGET_SHAPES) {
+      expect(isTargetShape(t)).toBe(true);
+    }
+    expect(isTargetShape("realtime")).toBe(false);
+    expect(isTargetShape("")).toBe(false);
+    expect(isTargetShape(42)).toBe(false);
+  });
+});
+
+describe("Dockerfiles on disk", () => {
+  test("every shape has a Dockerfile under docker/<target>/Dockerfile", () => {
+    for (const t of TARGET_SHAPES) {
+      expect(dockerfileSize(t)).toBeGreaterThan(100);
+    }
+  });
+
+  test("listAvailableTargets returns all 12 shapes", () => {
+    expect(listAvailableTargets()).toEqual(TARGET_SHAPES);
+  });
+
+  test("dockerRoot points inside the package", () => {
+    expect(dockerRoot()).toMatch(/packages\/docker-images\/docker$/);
+  });
+});
+
+describe("Dockerfile structural contract (T2)", () => {
+  for (const target of TARGET_SHAPES) {
+    test(`${target} → multi-stage, non-root, healthchecked, has bun runtime`, () => {
+      const text = readDockerfile(target);
+      const fp = fingerprintDockerfile(text);
+      expect(fp.stages.length).toBeGreaterThanOrEqual(2);
+      expect(fp.hasHealthcheck).toBe(true);
+      expect(fp.nonRootUser).toBe("crewhaus");
+      expect(fp.workdir).toBe("/app");
+      expect(fp.envs).toContain("CREWHAUS_TARGET");
+      expect(fp.entrypoint?.includes("bun")).toBe(true);
+      // multi-stage: at least one named stage (deps/build/runtime)
+      expect(fp.stages.some((s) => s.stage === "deps" || s.stage === "build")).toBe(true);
+    });
+  }
+
+  test("daemon shapes (channel/managed/crew/voice/browser) expose a port and curl healthcheck", () => {
+    const daemonShapes = ["channel", "managed", "crew", "voice", "browser"] as const;
+    for (const t of daemonShapes) {
+      const text = readDockerfile(t);
+      const fp = fingerprintDockerfile(text);
+      expect(fp.exposedPorts.length).toBeGreaterThan(0);
+      expect(text).toContain("curl");
+    }
+  });
+
+  test("voice image installs libopus", () => {
+    expect(readDockerfile("voice")).toContain("libopus");
+  });
+
+  test("browser image installs chromium and Playwright env vars", () => {
+    const text = readDockerfile("browser");
+    expect(text).toContain("chromium");
+    expect(text).toContain("PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH");
+  });
+});
+
+describe("buildImage()", () => {
+  test("rejects unknown targets", async () => {
+    await expect(buildImage({ target: "unknown" as never, tag: "smoke" })).rejects.toThrow(
+      DockerImagesError,
+    );
+  });
+
+  test("rejects empty/whitespace tags", async () => {
+    await expect(buildImage({ target: "cli", tag: "" })).rejects.toThrow(/invalid tag/);
+    await expect(buildImage({ target: "cli", tag: "bad tag" })).rejects.toThrow(/invalid tag/);
+  });
+
+  test("happy path emits the documented argv shape", async () => {
+    const captured: string[][] = [];
+    const runner: BuildRunner = async (argv) => {
+      captured.push([...argv]);
+      return { exitCode: 0, stdout: "", stderr: "" };
+    };
+    const result = await buildImage({
+      target: "cli",
+      tag: "smoke",
+      runner,
+    });
+    expect(result.tag).toBe("smoke");
+    expect(result.target).toBe("cli");
+    expect(captured.length).toBe(1);
+    const argv = captured[0] ?? [];
+    expect(argv[0]).toBe("docker");
+    expect(argv).toContain("buildx");
+    expect(argv).toContain("build");
+    expect(argv).toContain("--tag");
+    expect(argv).toContain("crewhaus/cli:smoke");
+    expect(argv).toContain("--load");
+    expect(argv.includes("--push")).toBe(false);
+    expect(argv).toContain(dockerfilePath("cli"));
+  });
+
+  test("--push instead of --load when push:true", async () => {
+    let argv: readonly string[] = [];
+    await buildImage({
+      target: "channel",
+      tag: "v1",
+      push: true,
+      runner: async (a) => {
+        argv = a;
+        return { exitCode: 0, stdout: "", stderr: "" };
+      },
+    });
+    expect(argv).toContain("--push");
+    expect(argv.includes("--load")).toBe(false);
+  });
+
+  test("non-zero exit propagates as DockerImagesError with stderr captured", async () => {
+    const runner: BuildRunner = async () => ({
+      exitCode: 1,
+      stdout: "",
+      stderr: "no docker daemon",
+    });
+    await expect(buildImage({ target: "cli", tag: "smoke", runner })).rejects.toThrow(
+      /no docker daemon/,
+    );
+  });
+
+  test("platform passes through to argv", async () => {
+    let argv: readonly string[] = [];
+    await buildImage({
+      target: "graph",
+      tag: "multi",
+      platform: "linux/amd64,linux/arm64",
+      runner: async (a) => {
+        argv = a;
+        return { exitCode: 0, stdout: "", stderr: "" };
+      },
+    });
+    expect(argv).toContain("--platform");
+    expect(argv).toContain("linux/amd64,linux/arm64");
+  });
+});
+
+describe("digests lockfile", () => {
+  test("loadDigests returns _format_version: 1 when file missing", () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-digests-"));
+    const path = join(dir, "missing.json");
+    expect(loadDigests(path)).toEqual({ _format_version: 1 });
+  });
+
+  test("recordDigest writes and round-trips", () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-digests-"));
+    const path = join(dir, "digests.json");
+    const sha = `sha256:${"a".repeat(64)}`;
+    recordDigest("cli", "smoke", sha, path);
+    const loaded = loadDigests(path) as { cli?: Record<string, { sha256: string }> };
+    expect(loaded.cli?.["smoke"]?.sha256).toBe(sha);
+  });
+
+  test("recordDigest rejects malformed digests", () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-digests-"));
+    const path = join(dir, "digests.json");
+    expect(() => recordDigest("cli", "tag", "not-a-digest", path)).toThrow(/invalid sha256/);
+    expect(() => recordDigest("cli", "tag", "sha256:short", path)).toThrow();
+  });
+
+  test("loadDigests propagates JSON parse errors as DockerImagesError", () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-digests-"));
+    const path = join(dir, "bad.json");
+    writeFileSync(path, "not json");
+    expect(() => loadDigests(path)).toThrow(DockerImagesError);
+  });
+
+  test("recordDigest preserves prior entries across multiple records", () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-digests-"));
+    const path = join(dir, "digests.json");
+    const shaA = `sha256:${"a".repeat(64)}`;
+    const shaB = `sha256:${"b".repeat(64)}`;
+    recordDigest("cli", "v1", shaA, path);
+    recordDigest("channel", "v1", shaB, path);
+    const final = JSON.parse(readFileSync(path, "utf8"));
+    expect(final.cli.v1.sha256).toBe(shaA);
+    expect(final.channel.v1.sha256).toBe(shaB);
+  });
+});
+
+describe("fingerprintDockerfile (T1 unit)", () => {
+  test("parses a minimal multi-stage Dockerfile", () => {
+    const text = `FROM alpine AS base
+FROM base AS runtime
+WORKDIR /work
+ENV FOO=bar BAZ=qux
+USER nobody
+EXPOSE 9000
+HEALTHCHECK CMD echo
+ENTRYPOINT ["bun", "x"]
+CMD ["--help"]
+`;
+    const fp = fingerprintDockerfile(text);
+    expect(fp.stages.map((s) => s.stage)).toEqual(["base", "runtime"]);
+    expect(fp.hasHealthcheck).toBe(true);
+    expect(fp.nonRootUser).toBe("nobody");
+    expect(fp.workdir).toBe("/work");
+    expect(fp.exposedPorts).toEqual([9000]);
+    expect([...fp.envs].sort()).toEqual(["BAZ", "FOO"]);
+    expect(fp.entrypoint).toContain("bun");
+    expect(fp.cmd).toContain("--help");
+  });
+
+  test("absent fields surface as undefined / empty", () => {
+    const fp = fingerprintDockerfile("FROM alpine\n");
+    expect(fp.hasHealthcheck).toBe(false);
+    expect(fp.nonRootUser).toBeUndefined();
+    expect(fp.exposedPorts).toEqual([]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,256 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Section 32 — `@crewhaus/docker-images`
+ *
+ * Per-target-shape Dockerfiles (one per target shape: cli, workflow, channel,
+ * graph, managed, pipeline, crew, research, batch, voice, browser, eval) plus
+ * a `buildImage()` wrapper around `docker buildx build` that the
+ * `crewhaus build-image <target>` CLI subcommand (apps/cli/src/index.ts) calls.
+ *
+ * v0 ships:
+ *   - 12 multi-stage Dockerfiles under `docker/<target>/Dockerfile`,
+ *     each with non-root user, read-only root, HEALTHCHECK, and
+ *     target-specific system deps baked in (chromium for browser,
+ *     libopus for voice, curl+ca-certs for daemon shapes).
+ *   - `buildImage()` shells to `docker buildx build` (gated on `docker
+ *     version` succeeding); injectable `runner` for tests.
+ *   - `loadDigests()` / `recordDigest()` over a `docker/digests.json`
+ *     lockfile so reproducible builds work offline.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export class DockerImagesError extends CrewhausError {
+  override readonly name = "DockerImagesError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+/**
+ * The 12 target shapes that ship a Dockerfile. Sourced from
+ * `packages/spec/src/index.ts` discriminator literals; we keep the
+ * canonical list locally because this package owns the "which shapes
+ * have a deployable image" question.
+ */
+export const TARGET_SHAPES = [
+  "cli",
+  "workflow",
+  "channel",
+  "graph",
+  "managed",
+  "pipeline",
+  "crew",
+  "research",
+  "batch",
+  "voice",
+  "browser",
+  "eval",
+] as const;
+
+export type TargetShape = (typeof TARGET_SHAPES)[number];
+
+export function isTargetShape(value: unknown): value is TargetShape {
+  return typeof value === "string" && (TARGET_SHAPES as readonly string[]).includes(value);
+}
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DOCKER_ROOT = join(PACKAGE_ROOT, "docker");
+const DIGESTS_PATH = join(DOCKER_ROOT, "digests.json");
+
+export function dockerRoot(): string {
+  return DOCKER_ROOT;
+}
+
+export function digestsPath(): string {
+  return DIGESTS_PATH;
+}
+
+export function dockerfilePath(target: TargetShape): string {
+  return join(DOCKER_ROOT, target, "Dockerfile");
+}
+
+export function readDockerfile(target: TargetShape): string {
+  const path = dockerfilePath(target);
+  if (!existsSync(path)) {
+    throw new DockerImagesError(`dockerfile missing for target ${target} (expected at ${path})`);
+  }
+  return readFileSync(path, "utf8");
+}
+
+export function dockerfileSize(target: TargetShape): number {
+  return statSync(dockerfilePath(target)).size;
+}
+
+export function listAvailableTargets(): readonly TargetShape[] {
+  return TARGET_SHAPES.filter((t) => existsSync(dockerfilePath(t)));
+}
+
+export type BuildRunner = (
+  argv: readonly string[],
+  cwd: string,
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>;
+
+export type BuildImageOptions = {
+  readonly target: TargetShape;
+  readonly tag: string;
+  /** Optional build context path; defaults to the workspace root. */
+  readonly contextPath?: string;
+  /** Optional buildx platform string, e.g. `linux/amd64,linux/arm64`. */
+  readonly platform?: string;
+  /** Whether to push to a registry after build. Defaults to false. */
+  readonly push?: boolean;
+  /** Test injection point — defaults to a node:child_process spawn of `docker`. */
+  readonly runner?: BuildRunner;
+};
+
+export type BuildImageResult = {
+  readonly tag: string;
+  readonly target: TargetShape;
+  readonly buildArgv: readonly string[];
+};
+
+export async function buildImage(opts: BuildImageOptions): Promise<BuildImageResult> {
+  if (!isTargetShape(opts.target)) {
+    throw new DockerImagesError(`unknown target shape: ${String(opts.target)}`);
+  }
+  if (!opts.tag || /[\s\n\r]/.test(opts.tag)) {
+    throw new DockerImagesError(
+      `invalid tag: ${JSON.stringify(opts.tag)} — must be non-empty and contain no whitespace`,
+    );
+  }
+  const dockerfile = dockerfilePath(opts.target);
+  if (!existsSync(dockerfile)) {
+    throw new DockerImagesError(
+      `dockerfile missing for target ${opts.target} (expected at ${dockerfile})`,
+    );
+  }
+  const contextPath = opts.contextPath ?? resolve(PACKAGE_ROOT, "..", "..");
+  const argv: string[] = [
+    "docker",
+    "buildx",
+    "build",
+    "--file",
+    dockerfile,
+    "--tag",
+    `crewhaus/${opts.target}:${opts.tag}`,
+  ];
+  if (opts.platform) {
+    argv.push("--platform", opts.platform);
+  }
+  argv.push(opts.push ? "--push" : "--load");
+  argv.push(contextPath);
+
+  const runner = opts.runner ?? defaultRunner;
+  const { exitCode, stderr } = await runner(argv, contextPath);
+  if (exitCode !== 0) {
+    throw new DockerImagesError(
+      `docker buildx build exited with code ${exitCode}: ${stderr.slice(0, 1024)}`,
+    );
+  }
+  return { tag: opts.tag, target: opts.target, buildArgv: argv };
+}
+
+const defaultRunner: BuildRunner = async (argv, cwd) => {
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve_) => {
+    const head = argv[0] ?? "docker";
+    const child = spawn(head, argv.slice(1), { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on("data", (b) => out.push(b));
+    child.stderr.on("data", (b) => err.push(b));
+    child.on("error", (e) =>
+      resolve_({ exitCode: 1, stdout: "", stderr: String((e as Error).message) }),
+    );
+    child.on("close", (code) =>
+      resolve_({
+        exitCode: code ?? 1,
+        stdout: Buffer.concat(out).toString("utf8"),
+        stderr: Buffer.concat(err).toString("utf8"),
+      }),
+    );
+  });
+};
+
+// ─── digests lockfile ────────────────────────────────────────────────────────
+
+export type DigestEntry = { readonly sha256: string; readonly builtAt: string };
+export type DigestsFile = {
+  _format_version: number;
+  [target: string]: unknown;
+};
+
+export function loadDigests(path: string = DIGESTS_PATH): DigestsFile {
+  if (!existsSync(path)) {
+    return { _format_version: 1 };
+  }
+  const raw = readFileSync(path, "utf8");
+  try {
+    return JSON.parse(raw) as DigestsFile;
+  } catch (cause) {
+    throw new DockerImagesError(`failed to parse digests.json at ${path}`, cause);
+  }
+}
+
+export function recordDigest(
+  target: TargetShape,
+  tag: string,
+  sha256: string,
+  path: string = DIGESTS_PATH,
+): void {
+  if (!/^sha256:[0-9a-f]{64}$/.test(sha256)) {
+    throw new DockerImagesError(`invalid sha256: ${sha256}`);
+  }
+  const current = loadDigests(path);
+  const targetEntry = (current[target] as Record<string, DigestEntry> | undefined) ?? {};
+  targetEntry[tag] = { sha256, builtAt: new Date().toISOString() };
+  current[target] = targetEntry;
+  current._format_version = 1;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(current, null, 2)}\n`, { mode: 0o644 });
+}
+
+// ─── Dockerfile structural fingerprint (consumed by tests) ───────────────────
+
+export type DockerfileFingerprint = {
+  readonly stages: ReadonlyArray<{ readonly image: string; readonly stage?: string }>;
+  readonly hasHealthcheck: boolean;
+  readonly nonRootUser?: string;
+  readonly workdir?: string;
+  readonly entrypoint?: string;
+  readonly cmd?: string;
+  readonly exposedPorts: readonly number[];
+  readonly envs: readonly string[];
+};
+
+export function fingerprintDockerfile(text: string): DockerfileFingerprint {
+  const lines = text.split(/\r?\n/);
+  const fromStages = lines
+    .map((l) => /^FROM\s+(\S+)(?:\s+AS\s+(\S+))?/i.exec(l.trim()))
+    .filter((m): m is RegExpExecArray => Boolean(m))
+    .map((m) => ({ image: m[1] ?? "", stage: (m[2] ?? "").toLowerCase() || undefined }));
+  const exposedPorts = lines
+    .filter((l) => /^EXPOSE\s+\d+/i.test(l.trim()))
+    .map((l) => Number(l.trim().split(/\s+/)[1]));
+  return {
+    stages: fromStages,
+    hasHealthcheck: /^HEALTHCHECK\s+/im.test(text),
+    nonRootUser: /^USER\s+(\S+)/im.exec(text)?.[1],
+    workdir: /^WORKDIR\s+(\S+)/im.exec(text)?.[1],
+    entrypoint: /^ENTRYPOINT\s+(.+)$/im.exec(text)?.[1]?.trim(),
+    cmd: /^CMD\s+(.+)$/im.exec(text)?.[1]?.trim(),
+    exposedPorts,
+    envs: lines
+      .filter((l) => /^ENV\s+/i.test(l.trim()))
+      .flatMap((l) =>
+        l
+          .trim()
+          .replace(/^ENV\s+/i, "")
+          .split(/\s+/)
+          .map((kv) => (kv.split("=")[0] ?? "").trim())
+          .filter((k) => k.length > 0 && /^[A-Z_][A-Z0-9_]*$/.test(k)),
+      ),
+  };
+}