rcf-lite 0.24.0 → 0.26.0

package/blueprints/platform-docker-compose-host/README.md

@@ -0,0 +1,76 @@
+# platform-docker-compose-host v1.0.0
+
+A container-orchestration facade over docker compose running on a Linux `cloudHost`. Provides `containerHost` for consumer blueprints that ship as containers.
+
+## What it commits
+
+Six REQs, nine USs, four TACs, four ADRs and five Node-only probes. Round-7 T-2 of the Hetzner spec at `projects/blueprint-library/specs/hetzner-round-7-spec-2026-09-07.md`.
+
+| REQ | Contract |
+|---|---|
+| REQ-001 | `compose.yaml` at repo root is the single-source runtime topology (service-per-container, named networks and volumes, `.env` for non-secret config) |
+| REQ-002 | Every secret injected via a docker compose secrets file mount; no plaintext literal in `compose.yaml` (grep-refuse); references `security-secrets-management` when applied |
+| REQ-003 | Healthcheck contract on every HTTP-terminating service; `docker compose config` refuses on missing |
+| REQ-004 | Restart discipline enforced at lint: `unless-stopped` on long-running, `on-failure` on jobs; unclassified value refuses |
+| REQ-005 | Zero-downtime reverse-proxy reload via bind-mounted config; verb per proxy; no non-2xx or dropped connection inside the elicited window (10 s default) |
+| REQ-006 | Log shipping to the elicited `observability-logging` sink: `journald` default matching Debian 12 / Ubuntu 24.04 baseline; `loki` opt-in when the project runs Grafana |
+
+## Capability
+
+- `containerHost` (extends `blueprint-authoring.md` section 6a).
+
+## Suggested companions
+
+- `logging`: every `composeStackReady`, `containerHealthy`, `containerCrashed` and `reverseProxyReloaded` event writes through the applied logger; a logging companion supplies the factory and the log-driver binding.
+- `errorHandling`: a healthcheck timeout, a compose lint refusal, a secret-file-mode mismatch, a reload window overshoot constructs an internal error record; an error-handling companion supplies the record factory and the boundary.
+
+## Elicits (via `elicits[]`)
+
+- `reverse-proxy`: `caddy` (default per Baz decision 19, matches dev-01 and ops-01) | `traefik` (alternative for docker-label auto-discovery) | `none` (alternative for projects fronted only by the round-7 tunnel).
+- `docker-engine-channel`: `stable` (default) | `test`.
+- `compose-file-location`: `repo-root` (default) | `compose/compose.yaml`.
+- `healthcheck-default-kind`: `http` (default) | `tcp` | `command`.
+- `log-driver`: `journald` (default per ADR-3904) | `loki` (opt-in).
+- `reload-window-seconds`: default `10`.
+
+## ADR shape
+
+- ADR-3901 container host contract: scope `global` on new topic `containerHostContract`; standards trace clause `Docker Compose file reference AND Docker Engine install-on-Ubuntu docs per hetzner-round-7-spec-2026-09-07.md`.
+- ADR-3902 reverse proxy: elicited, `caddy` default; standards trace clause `Caddy docs AND Traefik docs per hetzner-round-7-spec-2026-09-07.md`.
+- ADR-3903 reject Coolify: decision quoted verbatim from Baz ruling 20 ("reject; it shadows what the blueprints contract and adds its own DB and UI as a second source of state"); standards trace clause `generic enterprise practice`.
+- ADR-3904 log driver: elicited, `journald` default; standards trace clause `generic enterprise practice`.
+
+## Probes
+
+Five modules under `contributions/probes/`, each writes an envelope to `.rcf/reports/blueprints/platform-docker-compose-host/<probe>.json`:
+
+- `compose-config-lint` (accountBound: false; anchors AC-composeHost-healthcheckLint, AC-composeHost-restartClassification, AC-composeHost-logDriverClassification). Mutations: `SIMULATE_MISSING_HEALTHCHECK`, `SIMULATE_UNCLASSIFIED_RESTART`, `SIMULATE_UNCLASSIFIED_LOG_DRIVER`, `SIMULATE_EVENT_SECRECY_LEAK`.
+- `secrets-as-files-scan` (accountBound: false; anchors AC-composeHost-secretsAreFiles, AC-composeHost-secretShape). Mutation: `SIMULATE_PLAINTEXT_SECRET`.
+- `caddyfile-validate` (accountBound: false; anchors AC-composeHost-reverseProxyArtefactValid). Runs a local `caddy` binary when present, otherwise the `caddy:2` container via `docker run --rm`. Mutation: `SIMULATE_INVALID_CADDYFILE`. Skipped when `REVERSE_PROXY` is not `caddy`.
+- `real-account-minimal-stack-up` (accountBound: true; anchors AC-composeHost-upClean). Provisions the throwaway server, `scp`s the compose stack, runs `docker compose up -d --wait`, asserts every declared service reaches healthy inside the elicited timeout, tears down in `always()`. Records `accountBoundSkipped: true` without `CI_HAS_HETZNER_ACCOUNT`.
+- `real-account-reload-burst` (accountBound: true; anchors AC-composeHost-zeroDowntimeReload). Fires an `undici` burst against the caddy service while `docker compose exec caddy caddy reload` runs, asserts every request returns 2xx inside the elicited window with no dropped connection, tears down in `always()`. Records `accountBoundSkipped: true` without `CI_HAS_HETZNER_ACCOUNT`.
+
+## Running the probes
+
+From the shared throwaway-server fixture directory:
+
+```
+cd packages/rcf-lite/test/fixtures/hetzner-throwaway-server
+node ./run-compose-config-lint.mjs && node ./run-secrets-as-files-scan.mjs && node ./run-caddyfile-validate.mjs
+```
+
+Real-account probes gate on `CI_HAS_HETZNER_ACCOUNT`:
+
+```
+cd packages/rcf-lite/test/fixtures/hetzner-throwaway-server
+CI_HAS_HETZNER_ACCOUNT=true HCLOUD_TOKEN=$HETZNER_ACCOUNT_API_KEY node ./run-real-account-minimal-stack-up.mjs && node ./run-real-account-reload-burst.mjs
+```
+
+## Fixture extension path
+
+Round-7 T-1 (`deploy-hetzner-server`) minted the shared fixture at `packages/rcf-lite/test/fixtures/hetzner-throwaway-server/`. T-2 EXTENDS that fixture, never duplicates it: `compose.yaml`, `caddy/Caddyfile`, `secrets/web-token`, `src/serve.mjs` and five `run-<probe>.mjs` delegate shims land alongside T-1's `provision.mjs`/`destroy.mjs`/`sweep-orphans.mjs`. T-3 (`edge-cloudflare-tunnel`) extends the same fixture further; consumers of that fixture see one folder, one manifest, three tracks worth of runtime.
+
+## When to reach for this blueprint
+
+- Any project running a containerised stack on a `cloudHost` (T-1 `deploy-hetzner-server` provides the shipped v1.0.0 provider).
+- Any project that wants secrets as file mounts (not environment literals), healthchecks that gate boot, a checked-in reverse-proxy artefact, and a log driver on the elicited sink.

package/blueprints/platform-docker-compose-host/blueprint.json

@@ -0,0 +1,209 @@
+{
+  "slug": "platform-docker-compose-host",
+  "version": "1.0.0",
+  "category": "platform",
+  "capabilities": [
+    "containerHost"
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every composeStackReady, containerHealthy, containerCrashed and reverseProxyReloaded event writes through the applied logger; a logging companion supplies the factory and the log-driver binding."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A healthcheck timeout, a compose lint refusal, a secret-file-mode mismatch, a reload window overshoot constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "elicits": [
+    {
+      "id": "reverse-proxy",
+      "prompt": "Reverse proxy in front of the compose services. caddy is the shipped default per Baz decision 19 (matches dev-01 and ops-01); traefik is the alternative for docker-label auto-discovery; none is the alternative for projects fronted only by the round-7 tunnel.",
+      "kind": "enum",
+      "options": [
+        "caddy",
+        "traefik",
+        "none"
+      ],
+      "default": "caddy"
+    },
+    {
+      "id": "docker-engine-channel",
+      "prompt": "Docker Engine apt channel per the Docker Engine install-on-Ubuntu docs. stable is the shipped default; test is for pre-release verification; the vendor also documents nightly builds available separately.",
+      "kind": "enum",
+      "options": [
+        "stable",
+        "test"
+      ],
+      "default": "stable"
+    },
+    {
+      "id": "compose-file-location",
+      "prompt": "Where the compose.yaml lives in the applying repo. repo-root is the shipped default; the alternative name is used when a project already owns compose.yaml for another purpose.",
+      "kind": "enum",
+      "options": [
+        "repo-root",
+        "compose/compose.yaml"
+      ],
+      "default": "repo-root"
+    },
+    {
+      "id": "healthcheck-default-kind",
+      "prompt": "Default healthcheck kind per service. http covers the common web service (curl or wget to a /health path); tcp covers a database or plain socket service; command lets the operator supply a bespoke test string.",
+      "kind": "enum",
+      "options": [
+        "http",
+        "tcp",
+        "command"
+      ],
+      "default": "http"
+    },
+    {
+      "id": "log-driver",
+      "prompt": "Container log driver per ADR-3904. journald is the shipped default matching the Debian 12 and Ubuntu 24.04 baseline T-1 sets up; loki is the opt-in alternative when the project runs Grafana.",
+      "kind": "enum",
+      "options": [
+        "journald",
+        "loki"
+      ],
+      "default": "journald"
+    },
+    {
+      "id": "reload-window-seconds",
+      "prompt": "Zero-downtime reverse-proxy reload window in seconds (the maximum time a client burst may see any non-2xx or dropped connection during a reload). 10 is the shipped default per REQ-005.",
+      "kind": "string",
+      "default": "10"
+    }
+  ],
+  "contributions": [
+    {
+      "id": "platform-docker-compose-host-REQ-001",
+      "kind": "req",
+      "path": "requirements/platform-docker-compose-host-req-001.json"
+    },
+    {
+      "id": "platform-docker-compose-host-REQ-002",
+      "kind": "req",
+      "path": "requirements/platform-docker-compose-host-req-002.json"
+    },
+    {
+      "id": "platform-docker-compose-host-REQ-003",
+      "kind": "req",
+      "path": "requirements/platform-docker-compose-host-req-003.json"
+    },
+    {
+      "id": "platform-docker-compose-host-REQ-004",
+      "kind": "req",
+      "path": "requirements/platform-docker-compose-host-req-004.json"
+    },
+    {
+      "id": "platform-docker-compose-host-REQ-005",
+      "kind": "req",
+      "path": "requirements/platform-docker-compose-host-req-005.json"
+    },
+    {
+      "id": "platform-docker-compose-host-REQ-006",
+      "kind": "req",
+      "path": "requirements/platform-docker-compose-host-req-006.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38101",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38101.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38102",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38102.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38103",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38103.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38104",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38104.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38105",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38105.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38106",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38106.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38107",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38107.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38108",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38108.json"
+    },
+    {
+      "id": "platform-docker-compose-host-US-38109",
+      "kind": "us",
+      "path": "user-stories/platform-docker-compose-host-us-38109.json"
+    },
+    {
+      "id": "TAC-3901-platform-docker-compose-host-compose-layout",
+      "kind": "tac",
+      "path": "tacs/tac-3901-platform-docker-compose-host-compose-layout.json"
+    },
+    {
+      "id": "TAC-3902-platform-docker-compose-host-secrets-mount",
+      "kind": "tac",
+      "path": "tacs/tac-3902-platform-docker-compose-host-secrets-mount.json"
+    },
+    {
+      "id": "TAC-3903-platform-docker-compose-host-healthcheck-lint",
+      "kind": "tac",
+      "path": "tacs/tac-3903-platform-docker-compose-host-healthcheck-lint.json"
+    },
+    {
+      "id": "TAC-3904-platform-docker-compose-host-reverse-proxy-artefact",
+      "kind": "tac",
+      "path": "tacs/tac-3904-platform-docker-compose-host-reverse-proxy-artefact.json"
+    },
+    {
+      "id": "ADR-3901-platform-docker-compose-host-contract",
+      "kind": "adr",
+      "path": "adrs/adr-3901-platform-docker-compose-host-contract.json",
+      "scope": "global",
+      "topic": "containerHostContract",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "Docker Compose file reference AND Docker Engine install-on-Ubuntu docs per hetzner-round-7-spec-2026-09-07.md"
+    },
+    {
+      "id": "ADR-3902-platform-docker-compose-host-reverse-proxy",
+      "kind": "adr",
+      "path": "adrs/adr-3902-platform-docker-compose-host-reverse-proxy.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "Caddy docs AND Traefik docs per hetzner-round-7-spec-2026-09-07.md"
+    },
+    {
+      "id": "ADR-3903-platform-docker-compose-host-reject-coolify",
+      "kind": "adr",
+      "path": "adrs/adr-3903-platform-docker-compose-host-reject-coolify.json",
+      "recommendedDefault": false,
+      "elicited": false,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-3904-platform-docker-compose-host-log-driver",
+      "kind": "adr",
+      "path": "adrs/adr-3904-platform-docker-compose-host-log-driver.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    }
+  ]
+}

package/blueprints/platform-docker-compose-host/contributions/adrs/adr-3901-platform-docker-compose-host-contract.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3901-platform-docker-compose-host-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Container host contract: docker compose as source of truth on a cloudHost (scope global, new topic containerHostContract)",
+  "context": "An applying project running its stack on a Linux cloudHost needs one shipped contract for how services are declared, wired and brought up on a container-orchestration surface. Round-7 T-2 mints the containerHostContract topic on this ADR. Docker Compose is the shipped v1.0.0 surface (compose.yaml as source of truth, healthchecks required, secrets as files, restart discipline, reverse-proxy as artefact). Every applied container host needs one project-wide answer to the containerHostContract topic; a future non-compose sibling (Docker Swarm, Nomad) would contribute the same topic string with a different mechanism, forcing a DELIBERATE conflict the operator resolves per the round-2 conflict pattern. Standards trace clause: Docker Compose file reference AND Docker Engine install-on-Ubuntu docs per hetzner-round-7-spec-2026-09-07.md.",
+  "decision": "The shipped v1.0.0 default is docker compose on a cloudHost as the containerHostContract provider. A canonical compose.yaml at the repo root drives docker compose up on the applied cloudHost (T-1 deploy-hetzner-server); healthchecks refuse at docker compose config on missing; secrets are file mounts; restart policies are unless-stopped or on-failure; the reverse-proxy config is a first-class versioned artefact per TAC-3904. The containerHostContract topic scope is global on this blueprint; the topic string is containerHostContract (lower camelCase, one concept per topic, no version suffix, per the round-2 rules-for-new-topics clause on the shelf registry). Standards trace clause: Docker Compose file reference AND Docker Engine install-on-Ubuntu docs per hetzner-round-7-spec-2026-09-07.md.",
+  "consequences": "Consumer blueprints that ship as containers declare capabilities: [containerHost] on their applied contract; the round-7 T-3 edge-cloudflare-tunnel reads this capability at apply-time to choose the compose-service runtime. Rebuild-from-manifest is always possible: the compose file is the source of truth, the running stack is derivative. Compose is famously many right ways; over-specifying alienates a project with a defensible different shape, so v1.0.0 pins the small load-bearing set (healthchecks, secrets-as-files, restart discipline, reverse-proxy-as-artefact) and leaves everything else to project-owned ADRs.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/adrs/adr-3902-platform-docker-compose-host-reverse-proxy.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3902-platform-docker-compose-host-reverse-proxy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Reverse proxy choice: caddy default (matches dev-01 and ops-01), traefik alternative for docker-label auto-discovery, none for tunnel-fronted projects (elicited)",
+  "context": "Compose stacks need a reverse-proxy for HTTPS termination and hostname-to-service routing. Caddy is the estate baseline (dev-01 and ops-01 already run it per Baz decision 19 on 2026-09-07 09:50Z). Traefik has a docker-label auto-discovery model some projects prefer. Some projects front their stack only with the round-7 tunnel and skip a reverse proxy inside compose.",
+  "decision": "The reverse-proxy choice is elicited via the reverseProxy parameter. The shipped default is caddy per Baz decision 19. The alternatives are traefik (for projects that want docker-label auto-discovery) and none (for projects fronted only by the round-7 tunnel). Standards trace clause: Caddy docs AND Traefik docs per hetzner-round-7-spec-2026-09-07.md.",
+  "consequences": "A project applying reverseProxy=caddy gets the caddy/Caddyfile artefact and the caddy reload verb. A project applying reverseProxy=traefik gets the traefik/traefik.yaml artefact and the Traefik equivalent reload verb; docker-label auto-discovery is a project-side pattern the guide names. A project applying reverseProxy=none omits the reverse-proxy service and must apply edge-cloudflare-tunnel (T-3) so ingress terminates at the CF edge.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/adrs/adr-3903-platform-docker-compose-host-reject-coolify.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3903-platform-docker-compose-host-reject-coolify",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Coolify rejected per Baz decision 20 (it shadows what the blueprints contract and adds its own DB and UI as a second source of state)",
+  "context": "Coolify was proposed as a candidate platform-* sibling in the round-7 proposal. It is a self-hosted PaaS with its own database and UI. Baz decision 20 on 2026-09-07 09:50Z ruled Coolify out for round 7.",
+  "decision": "reject; it shadows what the blueprints contract and adds its own DB and UI as a second source of state.",
+  "consequences": "No platform-coolify-host blueprint is scoped in round 7 and no reserved slot is allocated. A future platform-coolify-host sibling mints on operator demand under a fresh scope PR. The standards trace clause on the contribution entry is generic enterprise practice; no vendor-doc URL is claimed for the reject decision.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/adrs/adr-3904-platform-docker-compose-host-log-driver.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3904-platform-docker-compose-host-log-driver",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Log driver: journald default matching Debian 12 and Ubuntu 24.04 baseline; loki opt-in when the project runs Grafana (elicited)",
+  "context": "Containers write stdout and stderr to a log driver. Debian 12 and Ubuntu 24.04 (the T-1 cloud-init baseline) ship journald. Grafana users on the estate reach for loki as a native sink. A one-choice hard-code loses either journald parity with the OS or loki when the operator runs Grafana.",
+  "decision": "The log driver is elicited via the log-driver parameter. The shipped default is journald matching the Debian 12 and Ubuntu 24.04 baselines T-1 sets up. The alternative is loki, opted into when the applying project runs Grafana. When observability-logging is applied, the compose file wires the elicited driver to that companion. Standards trace clause: generic enterprise practice.",
+  "consequences": "A project applying log-driver=journald gets the systemd-native path; the journald sink is queried via journalctl. A project applying log-driver=loki targets the Grafana loki endpoint; the observability-logging companion supplies the endpoint address. Neither choice adds a runtime npm dependency. The compose-config-lint refuses on any driver value outside the allowed set.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/platform-docker-compose-host/contributions/probes/caddyfile-validate.mjs

@@ -0,0 +1,108 @@
+// Probe: caddyfile-validate.
+//
+// anchorAcId: AC-composeHost-reverseProxyArtefactValid.
+// accountBound: false.
+//
+// Runs caddy validate against the applied fixture caddy/Caddyfile. When
+// a local caddy binary is not on PATH the probe uses the caddy:2
+// container image via docker run --rm (pinned tag), so review machines
+// without a local caddy still get a real validation. When neither is
+// available the probe records skipped with a warn note.
+//
+// The applying project may set reverseProxy to a value other than caddy
+// (traefik or none per ADR-3902); when that happens the probe returns
+// skipped with note.
+//
+// Mutation:
+// - SIMULATE_INVALID_CADDYFILE=true writes an obviously-invalid
+//   directive (\"not-a-directive-at-all\") into a scratch copy of the
+//   Caddyfile; the probe FAILS naming the offending line.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { runShim, CADDYFILE_PATH, whichCaddy, whichDocker } from './probe-utils.mjs';
+
+export const anchorAcId = 'AC-composeHost-reverseProxyArtefactValid';
+export const accountBound = false;
+
+function isCaddyReverseProxy() {
+  // Applying project passes reverseProxy via env for the probe run; the
+  // shipped default per ADR-3902 is caddy.
+  const v = process.env.REVERSE_PROXY;
+  if (v === undefined || v === 'caddy') return true;
+  return false;
+}
+
+export default async function runProbe() {
+  const results = [];
+  const extra = {};
+  extra.mutations = { invalidCaddyfile: process.env.SIMULATE_INVALID_CADDYFILE === 'true' };
+  extra.reverseProxy = process.env.REVERSE_PROXY ?? 'caddy';
+  if (!isCaddyReverseProxy()) {
+    results.push({
+      anchorAcId,
+      verdict: 'skipped',
+      detail: `reverseProxy=${extra.reverseProxy}: caddyfile-validate skipped (applies only when reverseProxy=caddy)`,
+    });
+    return { results, extra };
+  }
+  const scratchDir = join(tmpdir(), `rcf-lite-t2-caddyfile-validate-${Date.now()}`);
+  await mkdir(scratchDir, { recursive: true });
+  const scratchPath = join(scratchDir, 'Caddyfile');
+  try {
+    let text = await readFile(CADDYFILE_PATH, 'utf8');
+    if (process.env.SIMULATE_INVALID_CADDYFILE === 'true') {
+      text = text + "\n{ unclosed_block_that_never_ends_and_is_a_syntax_error_caddy_will_reject\n";
+    }
+    await writeFile(scratchPath, text, 'utf8');
+    const localCaddy = whichCaddy();
+    const localDocker = whichDocker();
+    extra.caddyLocal = localCaddy;
+    extra.dockerLocal = localDocker;
+    let cmd, args, engineLabel;
+    if (localCaddy !== null) {
+      cmd = 'caddy';
+      args = ['validate', '--config', scratchPath, '--adapter', 'caddyfile'];
+      engineLabel = `local caddy ${localCaddy}`;
+    } else if (localDocker !== null) {
+      cmd = 'docker';
+      args = ['run', '--rm', '-v', `${scratchDir}:/etc/caddy:ro`, 'caddy:2',
+        'caddy', 'validate', '--config', '/etc/caddy/Caddyfile', '--adapter', 'caddyfile'];
+      engineLabel = 'caddy:2 container (docker run --rm)';
+    } else {
+      results.push({
+        anchorAcId,
+        verdict: 'warn',
+        detail: 'neither caddy binary nor docker on PATH; caddy validate could not be exercised',
+      });
+      return { results, extra };
+    }
+    const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 60_000 });
+    extra.exitStatus = r.status;
+    extra.engineLabel = engineLabel;
+    const tail = ((r.stderr || '') + (r.stdout || '')).split('\n').slice(-10).join('\n');
+    if (r.status === 0) {
+      results.push({
+        anchorAcId,
+        verdict: 'pass',
+        detail: `caddy validate exit 0 (${engineLabel}); tail: ${tail.slice(-200)}`,
+      });
+    } else {
+      results.push({
+        anchorAcId,
+        verdict: 'fail',
+        detail: `caddy validate exit ${r.status} (${engineLabel}); tail: ${tail.slice(-400)}`,
+      });
+    }
+  } finally {
+    await rm(scratchDir, { recursive: true, force: true });
+  }
+  return { results, extra };
+}
+
+const engine = { kind: 'caddy-validate', image: 'caddy:2 (or local caddy binary)', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('caddyfile-validate', engine, runProbe);
+}