@capagents/forgeqe 1.3.2 → 2.0.1

package/src/containers/compose.ts

@@ -0,0 +1,173 @@
+import { readFileSync } from "node:fs"
+import path from "node:path"
+import YAML from "yaml"
+
+import { serviceSpec, type ServiceSpec } from "./config.ts"
+
+/**
+ * A docker-compose file as ForgeQE services (docs/CONTAINERS.md). Each service is translated to a forgeqe.yaml service
+ * and checked by the same rules, so a compose file can declare nothing a forgeqe.yaml service cannot: settings that
+ * widen what a container reaches on this machine (privileged, network_mode, cap_add, devices, a build) are refused,
+ * a bind mount is read-only, a named volume is left out (the container keeps no data between runs), and `${NAME}`
+ * becomes a secret passed by name. Compose itself never runs.
+ */
+
+/** Settings that make no difference to how ForgeQE runs the container, or that it sets itself. */
+const IGNORED = new Set(["container_name", "restart", "labels", "expose", "healthcheck", "networks", "hostname", "stop_grace_period", "logging", "init", "tty", "stdin_open", "platform", "pull_policy", "deploy", "profiles"])
+const SUPPORTED = new Set(["image", "ports", "environment", "volumes", "command", "depends_on", "x-forgeqe"])
+
+const VAR = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)(?::?-[^}]*)?\}?$/
+
+/** A compose command string as arguments: split on spaces, with quotes kept together (compose does not use a shell). */
+export function splitCommand(s: string): string[] {
+  const out: string[] = []
+  const re = /"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+)/g
+  for (let m = re.exec(s); m; m = re.exec(s)) out.push(m[1] !== undefined ? m[1].replace(/\\(.)/g, "$1") : m[2] !== undefined ? m[2] : m[3]!)
+  return out
+}
+
+function composePorts(raw: unknown, where: string): (string | number)[] | undefined {
+  if (raw === undefined || raw === null) return undefined
+  if (!Array.isArray(raw)) throw new Error(`${where}.ports must be a list.`)
+  return raw.map((p, i) => {
+    const at = `${where}.ports[${i}]`
+    if (p && typeof p === "object") {
+      const o = p as Record<string, unknown>
+      if (o.protocol && o.protocol !== "tcp") throw new Error(`${at}: only tcp ports are supported.`)
+      if (o.host_ip && o.host_ip !== "127.0.0.1") throw new Error(`${at}: host_ip ${o.host_ip}: services are reachable from this machine only (127.0.0.1).`)
+      return o.published !== undefined ? `${o.published}:${o.target}` : Number(o.target)
+    }
+    let s = String(p)
+    if (/\/(udp|sctp)$/.test(s)) throw new Error(`${at}: only tcp ports are supported.`)
+    s = s.replace(/\/tcp$/, "")
+    // 127.0.0.1:15432:5432 is what ForgeQE does anyway; any other address is refused by the forgeqe.yaml rules.
+    return s.startsWith("127.0.0.1:") ? s.slice("127.0.0.1:".length) : s
+  })
+}
+
+function composeEnv(raw: unknown, where: string): { env: Record<string, string>; secrets: string[] } {
+  const env: Record<string, string> = {}
+  const secrets: string[] = []
+  if (raw === undefined || raw === null) return { env, secrets }
+  const pairs: [string, unknown][] = Array.isArray(raw)
+    ? raw.map((e) => {
+        const s = String(e)
+        const eq = s.indexOf("=")
+        // A bare NAME passes the variable through: a secret by name.
+        return eq < 0 ? [s, `\${${s}}`] : [s.slice(0, eq), s.slice(eq + 1)]
+      })
+    : typeof raw === "object"
+      ? Object.entries(raw as Record<string, unknown>).map(([k, v]) => [k, v === null ? `\${${k}}` : v])
+      : (() => {
+          throw new Error(`${where}.environment must be a mapping or a list.`)
+        })()
+  for (const [k, v] of pairs) {
+    const s = String(v)
+    const m = VAR.exec(s)
+    if (m) {
+      // KEY: ${NAME}: the container's KEY is the value of NAME. ForgeQE passes variables by their own name only.
+      if (m[1] !== k) throw new Error(`${where}.environment.${k}: \${${m[1]}} under another name is not supported; name the variable ${k} in .env, or list it under secrets in forgeqe.yaml.`)
+      secrets.push(k)
+    } else if (s.includes("$")) {
+      throw new Error(`${where}.environment.${k}: a value that mixes text and \${…} is not supported; use a plain value, or \${${k}} alone.`)
+    } else env[k] = s
+  }
+  return { env, secrets }
+}
+
+function composeVolumes(raw: unknown, where: string, notes: string[]): string[] {
+  if (raw === undefined || raw === null) return []
+  if (!Array.isArray(raw)) throw new Error(`${where}.volumes must be a list.`)
+  const out: string[] = []
+  raw.forEach((v, i) => {
+    const at = `${where}.volumes[${i}]`
+    let source: string
+    let target: string
+    let mode = ""
+    if (v && typeof v === "object") {
+      const o = v as Record<string, unknown>
+      if (o.type && o.type !== "bind" && o.type !== "volume") throw new Error(`${at}: type ${o.type} is not supported.`)
+      if (o.type === "volume") {
+        notes.push(`${at}: the named volume ${o.source || ""} is left out; the container keeps no data between runs.`)
+        return
+      }
+      source = String(o.source || "")
+      target = String(o.target || "")
+      mode = o.read_only === false ? "rw" : ""
+    } else {
+      const parts = String(v).split(":")
+      // C:\path:/target on Windows: the drive letter is part of the source.
+      if (parts.length > 2 && /^[A-Za-z]$/.test(parts[0]!)) parts.splice(0, 2, `${parts[0]}:${parts[1]}`)
+      if (parts.length === 1) {
+        notes.push(`${at}: an anonymous volume (${parts[0]}) is left out.`)
+        return
+      }
+      ;[source = "", target = "", mode = ""] = parts
+    }
+    if (!/^(\.|\/|~|[A-Za-z]:)/.test(source)) {
+      notes.push(`${at}: the named volume ${source} is left out; the container keeps no data between runs.`)
+      return
+    }
+    if (source.startsWith("~")) throw new Error(`${at}: ${source} is outside the project; mounts are folders inside it.`)
+    if (mode.split(",").includes("rw")) notes.push(`${at}: mounted read-only (ForgeQE mounts nothing writable).`)
+    out.push(`${source}:${target}`)
+  })
+  return out
+}
+
+/** The services of a compose file, translated and checked; and what was left out. */
+export function readCompose(file: string, root: string): { services: Record<string, ServiceSpec>; notes: string[] } {
+  let doc: unknown
+  try {
+    doc = YAML.parse(readFileSync(file, "utf8"))
+  } catch (e) {
+    throw new Error(`${path.relative(root, file)}: not valid YAML (${e instanceof Error ? e.message : e}).`)
+  }
+  const rel = path.relative(root, file) || path.basename(file)
+  const services = doc && typeof doc === "object" ? (doc as Record<string, unknown>).services : undefined
+  if (!services || typeof services !== "object" || Array.isArray(services)) throw new Error(`${rel} has no services.`)
+  const out: Record<string, ServiceSpec> = {}
+  const notes: string[] = []
+  // Paths in a compose file are relative to the file's folder.
+  const dir = path.dirname(file)
+  for (const [raw, def] of Object.entries(services as Record<string, unknown>)) {
+    const name = raw.toLowerCase().replace(/_/g, "-")
+    const where = `${rel} services.${raw}`
+    if (!def || typeof def !== "object" || Array.isArray(def)) throw new Error(`${where} must be a mapping.`)
+    const d = def as Record<string, unknown>
+    const refused = Object.keys(d).filter((k) => !SUPPORTED.has(k) && !IGNORED.has(k))
+    if (refused.length) {
+      const why = refused.includes("build")
+        ? " A build runs the repository's Dockerfile: build and tag the image first, and name it under image."
+        : refused.includes("env_file")
+          ? " env_file reads a file into the container: list the variables under environment as ${NAME} instead."
+          : " ForgeQE never runs a container privileged, on the host network, with added capabilities or devices, or with the runtime's socket."
+      throw new Error(`${where}: ${refused.join(", ")} ${refused.length === 1 ? "is" : "are"} not supported.${why}`)
+    }
+    const x = d["x-forgeqe"] && typeof d["x-forgeqe"] === "object" ? (d["x-forgeqe"] as Record<string, unknown>) : {}
+    const { env, secrets } = composeEnv(d.environment, where)
+    const ports = composePorts(d.ports, where)
+    const command = d.command === undefined || d.command === null ? undefined : Array.isArray(d.command) ? d.command : splitCommand(String(d.command))
+    const spec = serviceSpec(
+      name,
+      {
+        image: d.image,
+        ...(ports ? { ports } : {}),
+        env,
+        secrets,
+        volumes: composeVolumes(d.volumes, where, notes),
+        ...(command ? { command } : {}),
+        ...(d.depends_on ? { depends_on: Array.isArray(d.depends_on) ? d.depends_on.map((n) => String(n).toLowerCase().replace(/_/g, "-")) : Object.keys(d.depends_on as object).map((n) => n.toLowerCase().replace(/_/g, "-")) } : {}),
+        ...(x.ready ? { ready: x.ready } : {}),
+        ...(x.timeout ? { timeout: x.timeout } : {}),
+        ...(x.description ? { description: x.description } : {}),
+      },
+      dir,
+      where,
+    )
+    // Without x-forgeqe.ready, a service with ports is ready when its first port takes connections.
+    if (!spec.ready && spec.ports.length) spec.ready = { tcp: spec.ports[0]!.container }
+    out[name] = { ...spec, from: rel }
+  }
+  return { services: out, notes }
+}

package/src/containers/config.ts

@@ -0,0 +1,283 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+import { readCompose } from "./compose.ts"
+
+/**
+ * `containers:` in forgeqe.yaml (docs/CONTAINERS.md): the services ForgeQE may start in Docker or Podman for a test run
+ * (a database, a queue, the API under test), and the image mocks run on. The project declares every service; ForgeQE's
+ * agent can start, stop and read only these, and builds each command itself, so no image, flag or mount comes from a
+ * model.
+ */
+
+export type ContainerRuntime = "docker" | "podman"
+
+export type ServicePort = { host: number; container: number }
+
+export type ServiceVolume = { host: string; container: string }
+
+/** How ForgeQE knows a service is ready: a port that accepts connections, or an HTTP path that answers below 500. */
+export type ServiceReady = { tcp: number } | { http: string; port: number }
+
+export type ServiceSpec = {
+  name: string
+  image: string
+  ports: ServicePort[]
+  /** Plain values (no secrets). */
+  env: Record<string, string>
+  /** Names of environment variables passed through by name: the value never lands on a command line. */
+  secrets: string[]
+  /** Read-only mounts of folders or files inside the project. */
+  volumes: ServiceVolume[]
+  /** Arguments for the image's entrypoint. */
+  command: string[]
+  ready?: ServiceReady
+  /** Seconds to wait for `ready` (default 60). */
+  timeout: number
+  description?: string
+  /** Services that start before this one. */
+  dependsOn: string[]
+  /** Where it was declared: forgeqe.yaml, or a compose file. */
+  from?: string
+}
+
+/** containers.tests: the image the repository's tests run in, when run_tests runs them in a container. */
+export type TestsContainer = {
+  image: string
+  /** Declared services started first; the tests reach each by its name (db:5432). */
+  services: string[]
+  env: Record<string, string>
+  secrets: string[]
+}
+
+export type ContainersConfig = {
+  /** docker or podman; unset: whichever is on PATH (docker first). */
+  runtime?: ContainerRuntime
+  services: Record<string, ServiceSpec>
+  /** The WireMock image mocks run on. */
+  mockImage: string
+  /** The folder `volumes` must stay inside: the folder of forgeqe.yaml. */
+  root: string
+  /** Compose files the services were read from. */
+  compose: string[]
+  tests?: TestsContainer
+  /** What compose files had that ForgeQE left out (named volumes, rw mounts made read-only). */
+  notes: string[]
+}
+
+/** The WireMock release mocks run on, pinned. */
+export const WIREMOCK_IMAGE = "wiremock/wiremock:3.9.1"
+
+export const SERVICE_NAME = /^[a-z][a-z0-9-]{0,39}$/
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/
+/**
+ * An image with an exact tag or a digest: [registry[:port]/]name:tag or name@sha256:… Never untagged or `latest`, which change
+ * under the same name. Starts with a letter or digit, so it can never read as a flag.
+ */
+const IMAGE = /^[a-z0-9][a-z0-9.-]{0,100}(?::\d{1,5})?(?:\/[a-z0-9][a-z0-9._-]{0,100}){0,5}(?::[A-Za-z0-9_][A-Za-z0-9._-]{0,127})?(?:@sha256:[a-f0-9]{64})?$/
+/** A path inside the container: absolute, no `..`, none of the characters the runtimes split mounts on. */
+const CONTAINER_PATH = /^\/(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._@+/-]{0,200}$/
+
+export function checkImage(image: string, where: string): string {
+  if (!IMAGE.test(image)) throw new Error(`${where} must be an image name with an exact tag or a digest (postgres:16.4, or name@sha256:…).`)
+  const digest = image.includes("@sha256:")
+  const tag = image.split("@")[0]!.split("/").pop()!.split(":")[1]
+  if (!digest && !tag) throw new Error(`${where} (${image}) has no tag: name an exact version (postgres:16.4) or a digest, so the same image runs every time.`)
+  if (!digest && tag === "latest") throw new Error(`${where} (${image}) uses latest, which changes under the same name: name an exact version or a digest.`)
+  return image
+}
+
+function port(v: unknown, where: string): number {
+  const n = typeof v === "number" ? v : typeof v === "string" && /^\d+$/.test(v) ? Number(v) : NaN
+  if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error(`${where} must be a port number (1-65535).`)
+  return n
+}
+
+function ports(raw: unknown, where: string): ServicePort[] {
+  if (raw === undefined || raw === null) return []
+  if (!Array.isArray(raw)) throw new Error(`${where} must be a list of ports: 5432, or "15432:5432" (this machine:container).`)
+  return raw.map((p, i) => {
+    const at = `${where}[${i}]`
+    if (typeof p === "number") return { host: port(p, at), container: port(p, at) }
+    const s = String(p)
+    const m = /^(\d{1,5}):(\d{1,5})$/.exec(s)
+    if (m) return { host: port(m[1], at), container: port(m[2], at) }
+    // An address ("0.0.0.0:5432:5432") is refused: ports are always bound to this machine only.
+    if (/^\d{1,5}$/.test(s)) return { host: port(s, at), container: port(s, at) }
+    throw new Error(`${at} must be a port (5432) or "this machine:container" ("15432:5432"); services are reachable from this machine only.`)
+  })
+}
+
+function env(raw: unknown, where: string): Record<string, string> {
+  if (raw === undefined || raw === null) return {}
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${where} must map variable names to plain values.`)
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(raw)) {
+    if (!ENV_NAME.test(k)) throw new Error(`${where}.${k}: not a variable name (letters, digits and _).`)
+    if (v === null || typeof v === "object") throw new Error(`${where}.${k} must be a plain value; list secrets under secrets instead.`)
+    const s = String(v)
+    if (/[\0\r\n]/.test(s)) throw new Error(`${where}.${k} must be one line.`)
+    out[k] = s
+  }
+  return out
+}
+
+function names(raw: unknown, where: string): string[] {
+  if (raw === undefined || raw === null) return []
+  if (!Array.isArray(raw) || !raw.every((n) => typeof n === "string" && ENV_NAME.test(n))) {
+    throw new Error(`${where} must be a list of environment variable names (letters, digits and _); forgeqe.yaml holds no secret values.`)
+  }
+  return [...new Set(raw as string[])]
+}
+
+function volumes(raw: unknown, where: string, root: string): ServiceVolume[] {
+  if (raw === undefined || raw === null) return []
+  if (!Array.isArray(raw)) throw new Error(`${where} must be a list of "./folder:/path/in/container" mounts.`)
+  return raw.map((v, i) => {
+    const at = `${where}[${i}]`
+    const s = String(v)
+    const cut = s.lastIndexOf(":")
+    // ":ro" and other options are ForgeQE's to set: every mount is read-only.
+    if (cut <= 0 || /:(ro|rw|z|Z)$/.test(s)) throw new Error(`${at} must be "./folder:/path/in/container" (mounts are always read-only; leave the options out).`)
+    const host = s.slice(0, cut)
+    const container = s.slice(cut + 1)
+    if (!CONTAINER_PATH.test(container) || container === "/") throw new Error(`${at}: ${container} must be an absolute path in the container, not / and without ..`)
+    if (/[\0\r\n,]/.test(host)) throw new Error(`${at}: ${host} is not a usable path.`)
+    return { host: path.resolve(root, host), container }
+  })
+}
+
+function ready(raw: unknown, where: string, ps: ServicePort[]): ServiceReady | undefined {
+  if (raw === undefined || raw === null) return undefined
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${where} must be {tcp: PORT} or {http: /path, port: PORT}.`)
+  const r = raw as Record<string, unknown>
+  const own = (p: number) => {
+    if (!ps.some((x) => x.container === p)) throw new Error(`${where}: port ${p} is not one of the service's ports.`)
+    return p
+  }
+  if (r.tcp !== undefined) return { tcp: own(port(r.tcp, `${where}.tcp`)) }
+  if (r.http !== undefined) {
+    const p = String(r.http)
+    if (!/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]{0,200}$/.test(p)) throw new Error(`${where}.http must be a path such as /health.`)
+    const container = r.port === undefined && ps.length === 1 ? ps[0]!.container : port(r.port, `${where}.port`)
+    return { http: p, port: own(container) }
+  }
+  throw new Error(`${where} must be {tcp: PORT} or {http: /path, port: PORT}.`)
+}
+
+const SERVICE_KEYS = new Set(["image", "ports", "env", "secrets", "volumes", "command", "ready", "timeout", "description", "depends_on"])
+
+export function serviceSpec(name: string, raw: unknown, root: string, where = `containers.services.${name}`): ServiceSpec {
+  if (!SERVICE_NAME.test(name)) throw new Error(`${where}: a service name is lower-case letters, digits and -, starting with a letter.`)
+  if (name.startsWith("mock-")) throw new Error(`${where}: names starting with mock- are kept for mock_service's mocks.`)
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${where} must be a mapping with an image.`)
+  const r = raw as Record<string, unknown>
+  // Anything else (privileged, network, user, cap_add, devices…) would widen what the container can reach on this
+  // machine; ForgeQE runs every container the same restricted way, so such settings are refused, not ignored.
+  const unknown = Object.keys(r).filter((k) => !SERVICE_KEYS.has(k))
+  if (unknown.length) throw new Error(`${where}: ${unknown.join(", ")} ${unknown.length === 1 ? "is" : "are"} not supported. A service has ${[...SERVICE_KEYS].join(", ")}; ForgeQE never runs a container privileged, on the host network, or with the container runtime's socket.`)
+  if (typeof r.image !== "string") throw new Error(`${where}.image is required.`)
+  const ps = ports(r.ports, `${where}.ports`)
+  const hostPorts = ps.map((p) => p.host)
+  if (new Set(hostPorts).size !== hostPorts.length) throw new Error(`${where}.ports uses a port of this machine twice.`)
+  const command = r.command === undefined || r.command === null ? [] : r.command
+  if (!Array.isArray(command) || !command.every((c) => ["string", "number"].includes(typeof c) && !/[\0\r\n]/.test(String(c)))) {
+    throw new Error(`${where}.command must be a list of arguments, not one command string.`)
+  }
+  const timeout = r.timeout === undefined ? 60 : Number(r.timeout)
+  if (!Number.isFinite(timeout) || timeout < 1 || timeout > 600) throw new Error(`${where}.timeout must be 1 to 600 seconds.`)
+  return {
+    name,
+    image: checkImage(r.image, `${where}.image`),
+    ports: ps,
+    env: env(r.env, `${where}.env`),
+    secrets: names(r.secrets, `${where}.secrets`),
+    volumes: volumes(r.volumes, `${where}.volumes`, root),
+    command: (command as unknown[]).map(String),
+    ready: ready(r.ready, `${where}.ready`, ps),
+    timeout,
+    ...(r.description ? { description: String(r.description).trim() } : {}),
+    dependsOn: dependsOn(r.depends_on, where),
+  }
+}
+
+function dependsOn(raw: unknown, where: string): string[] {
+  if (raw === undefined || raw === null) return []
+  const list = Array.isArray(raw) ? raw : typeof raw === "object" ? Object.keys(raw) : null
+  if (!list || !list.every((n) => typeof n === "string" && SERVICE_NAME.test(n))) throw new Error(`${where}.depends_on must list service names.`)
+  return [...new Set(list as string[])]
+}
+
+/** The services to start for `picked` (default: all), each after the ones it depends on. */
+export function startOrder(services: Record<string, ServiceSpec>, picked?: string[]): ServiceSpec[] {
+  const out: ServiceSpec[] = []
+  const state = new Map<string, "visiting" | "done">()
+  const visit = (name: string, from?: string) => {
+    const s = services[name]
+    if (!s) throw new Error(`${from ? `${from} depends on ${name}, which` : name} is not a declared service.`)
+    if (state.get(name) === "done") return
+    if (state.get(name) === "visiting") throw new Error(`The services depend on each other in a circle (${name}).`)
+    state.set(name, "visiting")
+    for (const d of s.dependsOn) visit(d, name)
+    state.set(name, "done")
+    out.push(s)
+  }
+  for (const n of picked?.length ? picked : Object.keys(services)) visit(n)
+  return out
+}
+
+export function containersConfig(raw: Record<string, unknown>, base: string): ContainersConfig {
+  const runtime = raw.runtime === undefined || raw.runtime === null ? undefined : raw.runtime
+  if (runtime !== undefined && runtime !== "docker" && runtime !== "podman") throw new Error("containers.runtime in forgeqe.yaml must be docker or podman.")
+  const services: Record<string, ServiceSpec> = {}
+  const rawServices = raw.services === undefined || raw.services === null ? {} : raw.services
+  if (typeof rawServices !== "object" || Array.isArray(rawServices)) throw new Error("containers.services in forgeqe.yaml must map service names to their settings.")
+  for (const [name, s] of Object.entries(rawServices)) services[name] = serviceSpec(name, s, base)
+  const notes: string[] = []
+  const compose = composeFiles(raw.compose, base)
+  for (const file of compose) {
+    const read = readCompose(file, base)
+    notes.push(...read.notes)
+    // forgeqe.yaml's own declaration of a service wins over the compose file's.
+    for (const [name, spec] of Object.entries(read.services)) if (!services[name]) services[name] = spec
+  }
+  for (const s of Object.values(services)) for (const d of s.dependsOn) if (!services[d]) throw new Error(`containers: ${s.name} depends on ${d}, which is not a declared service.`)
+  const mock = raw.mock && typeof raw.mock === "object" ? (raw.mock as Record<string, unknown>) : {}
+  const mockImage = mock.image === undefined ? WIREMOCK_IMAGE : checkImage(String(mock.image), "containers.mock.image")
+  const tests = testsContainer(raw.tests, services)
+  return { ...(runtime ? { runtime } : {}), services, mockImage, root: base, compose, ...(tests ? { tests } : {}), notes }
+}
+
+function composeFiles(raw: unknown, base: string): string[] {
+  if (raw === undefined || raw === null) return []
+  const list = Array.isArray(raw) ? raw : [raw]
+  return list.map((f) => {
+    const file = path.resolve(base, String(f))
+    const rel = path.relative(base, file)
+    if (rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`containers.compose: ${f} is outside the project folder.`)
+    if (!/\.ya?ml$/i.test(file)) throw new Error(`containers.compose: ${f} is not a compose file (.yaml or .yml).`)
+    if (!existsSync(file)) throw new Error(`containers.compose: ${f} does not exist.`)
+    return file
+  })
+}
+
+const TESTS_KEYS = new Set(["image", "services", "env", "secrets"])
+
+function testsContainer(raw: unknown, services: Record<string, ServiceSpec>): TestsContainer | undefined {
+  if (raw === undefined || raw === null || raw === false) return undefined
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("containers.tests must be a mapping with an image.")
+  const r = raw as Record<string, unknown>
+  const unknown = Object.keys(r).filter((k) => !TESTS_KEYS.has(k))
+  if (unknown.length) throw new Error(`containers.tests: ${unknown.join(", ")} not supported (it has ${[...TESTS_KEYS].join(", ")}).`)
+  if (typeof r.image !== "string") throw new Error("containers.tests.image is required.")
+  const svc = dependsOn(r.services, "containers.tests").map((n) => {
+    if (!services[n]) throw new Error(`containers.tests.services: ${n} is not a declared service.`)
+    return n
+  })
+  return { image: checkImage(r.image, "containers.tests.image"), services: svc, env: env(r.env, "containers.tests.env"), secrets: names(r.secrets, "containers.tests.secrets") }
+}
+
+/** The config's containers: settings, or none declared (configs built in code, without forgeqe.yaml). */
+export function containersOf(cfg: { containers?: ContainersConfig }): ContainersConfig {
+  return cfg.containers || { services: {}, mockImage: WIREMOCK_IMAGE, root: process.cwd(), compose: [], notes: [] }
+}

package/src/containers/mock.ts

@@ -0,0 +1,156 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { NetworkCall } from "../api/traffic.ts"
+import type { ContractSet, JsonSchema } from "../api/types.ts"
+import { SERVICE_NAME, type ServiceSpec } from "./config.ts"
+
+/**
+ * Mock services (docs/CONTAINERS.md): WireMock stubs from the API calls a browser run recorded (the answers the app
+ * really got) or from an API description (answers made from its examples and schemas). The stubs are JSON files in
+ * the mock's folder, mounted read-only into a WireMock container on 127.0.0.1.
+ */
+
+export type Stub = {
+  request: { method: string; urlPath?: string; urlPathPattern?: string; queryParameters?: Record<string, { equalTo: string }> }
+  response: { status: number; headers?: Record<string, string>; body?: string }
+  metadata: { forgeqe: { from: "run" | "spec"; id: string } }
+}
+
+export type MockBuild = { stubs: Stub[]; skipped: string[] }
+
+const MAX_STUBS = 500
+const MAX_BODY = 1_000_000
+
+/** Stubs from a run's calls: one per method, path and query, the last answer seen; the app's own API only. */
+export function stubsFromCalls(calls: NetworkCall[], opts: { thirdParty?: boolean } = {}): MockBuild {
+  const skipped: string[] = []
+  const byKey = new Map<string, Stub>()
+  for (const c of calls) {
+    let u: URL
+    try {
+      u = new URL(c.url)
+    } catch {
+      continue
+    }
+    const label = `${c.method} ${u.pathname}`
+    if (c.third_party && !opts.thirdParty) {
+      skipped.push(`${label} on ${u.host}: another site's call`)
+      continue
+    }
+    if (c.failed || !c.response?.status) {
+      skipped.push(`${label}: the call failed (${c.failed || "no answer"})`)
+      continue
+    }
+    if (c.response.truncated) skipped.push(`${label}: the recorded answer was cut, so the mock answers with the part recorded`)
+    const query: Record<string, { equalTo: string }> = {}
+    for (const [k, v] of u.searchParams) query[k] = { equalTo: v }
+    const key = `${c.method.toUpperCase()} ${u.pathname}?${[...u.searchParams].map(([k, v]) => `${k}=${v}`).sort().join("&")}`
+    const mime = c.response.mime || c.response.headers?.["content-type"] || c.response.headers?.["Content-Type"]
+    byKey.set(key, {
+      request: { method: c.method.toUpperCase(), urlPath: u.pathname, ...(Object.keys(query).length ? { queryParameters: query } : {}) },
+      response: { status: c.response.status, ...(mime ? { headers: { "Content-Type": mime } } : {}), ...(c.response.body !== undefined ? { body: c.response.body.slice(0, MAX_BODY) } : {}) },
+      metadata: { forgeqe: { from: "run", id: label } },
+    })
+  }
+  const stubs = [...byKey.values()]
+  if (stubs.length > MAX_STUBS) skipped.push(`${stubs.length - MAX_STUBS} more operations: a mock keeps at most ${MAX_STUBS}`)
+  return { stubs: stubs.slice(0, MAX_STUBS), skipped: [...new Set(skipped)] }
+}
+
+/** A value that fits a JSON schema: its example, else one made from its type (for answers from a description). */
+export function sampleOf(schema: JsonSchema | undefined, depth = 0): unknown {
+  if (!schema || depth > 6) return null
+  if (schema.example !== undefined) return schema.example
+  if (schema.enum?.length) return schema.enum[0]
+  const alt = schema.oneOf?.[0] || schema.anyOf?.[0]
+  if (alt) return sampleOf(alt, depth + 1)
+  if (schema.allOf?.length) {
+    const parts = schema.allOf.map((s) => sampleOf(s, depth + 1))
+    return parts.every((p) => p && typeof p === "object" && !Array.isArray(p)) ? Object.assign({}, ...parts) : parts[0]
+  }
+  const type = Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") : schema.type
+  switch (type || (schema.properties ? "object" : schema.items ? "array" : undefined)) {
+    case "object": {
+      const out: Record<string, unknown> = {}
+      for (const [k, v] of Object.entries(schema.properties || {}).slice(0, 30)) out[k] = sampleOf(v, depth + 1)
+      return out
+    }
+    case "array":
+      return schema.items ? [sampleOf(schema.items, depth + 1)] : []
+    case "integer":
+      return 1
+    case "number":
+      return 1.5
+    case "boolean":
+      return true
+    case "string":
+      return schema.format === "date-time" ? "2026-01-01T00:00:00Z" : schema.format === "date" ? "2026-01-01" : schema.format === "uuid" ? "00000000-0000-4000-8000-000000000000" : schema.format === "email" ? "user@example.com" : schema.format === "uri" ? "https://example.com/" : "string"
+    default:
+      return null
+  }
+}
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/** A REST path template as a WireMock path pattern: each {param} matches one path segment. */
+export function pathPattern(template: string): string {
+  return `^${template.split(/\{[^}/]+\}/).map(escapeRe).join("[^/]+")}$`
+}
+
+/** Stubs from a contract set made from a description: REST operations answer with their example or schema. */
+export function stubsFromContracts(set: ContractSet): MockBuild {
+  const skipped: string[] = []
+  const stubs: Stub[] = []
+  for (const c of set.contracts) {
+    if (c.protocol !== "rest") {
+      skipped.push(`${c.id}: ${c.protocol} is not mocked (REST only)`)
+      continue
+    }
+    const basePath = set.baseUrl ? new URL(set.baseUrl, "http://x").pathname.replace(/\/$/, "") : ""
+    const template = `${basePath}${c.path.startsWith("/") ? "" : "/"}${c.path}`
+    const templated = /\{[^}]+\}/.test(template)
+    const body = c.expect.schema ? JSON.stringify(sampleOf(c.expect.schema)) : undefined
+    stubs.push({
+      request: { method: c.method.toUpperCase(), ...(templated ? { urlPathPattern: pathPattern(template) } : { urlPath: template }) },
+      response: { status: c.expect.status || 200, ...(body !== undefined ? { headers: { "Content-Type": c.expect.contentType || "application/json" }, body } : {}) },
+      metadata: { forgeqe: { from: "spec", id: c.id } },
+    })
+  }
+  return { stubs: stubs.slice(0, MAX_STUBS), skipped }
+}
+
+export function checkMockName(name: string): string {
+  const n = name.trim().toLowerCase()
+  if (!SERVICE_NAME.test(n) || n.length > 30) throw new Error(`A mock's name is lower-case letters, digits and -, starting with a letter (at most 30): got "${name}".`)
+  return n
+}
+
+/** Write the stubs as WireMock mapping files in `<dir>/mappings`, replacing what an earlier build wrote. */
+export function writeStubs(dir: string, stubs: Stub[]): string {
+  const mappings = path.join(dir, "mappings")
+  rmSync(mappings, { recursive: true, force: true })
+  mkdirSync(mappings, { recursive: true })
+  stubs.forEach((s, i) => writeFileSync(path.join(mappings, `${String(i + 1).padStart(3, "0")}.json`), `${JSON.stringify(s, null, 2)}\n`))
+  return mappings
+}
+
+/** The WireMock service for a mock: its stubs mounted read-only, on a port of this machine. */
+export function mockSpec(name: string, image: string, hostPort: number): ServiceSpec {
+  return {
+    name: `mock-${name}`,
+    image,
+    ports: [{ host: hostPort, container: 8080 }],
+    env: {},
+    secrets: [],
+    volumes: [],
+    // Cross-origin answers, so a web app on another local port can call the mock.
+    command: ["--enable-stub-cors"],
+    ready: { http: "/__admin/mappings", port: 8080 },
+    timeout: 90,
+    description: `Mock ${name} (WireMock)`,
+    dependsOn: [],
+  }
+}
+
+export const WIREMOCK_MAPPINGS = "/home/wiremock/mappings"