@homeflare/alchemy 0.6.0 → 0.8.0

package/src/caddy/config-lifecycle.ts

@@ -0,0 +1,239 @@
+/**
+ * CaddyConfig's read / diff / reconcile as plain async functions over a CaddyAdmin, so the
+ * lifecycle runs against a fake admin server in tests.
+ *
+ * The comparison is always between DIGESTS OF ADAPTED JSON (digest.ts): what `POST /adapt` makes
+ * of the declared Caddyfile, what `GET /config/` reports, and what was stored after the last
+ * apply. Three digests, because they answer different questions:
+ *   · declared ≠ stored — the declaration changed.
+ *   · live ≠ stored — DRIFT: a hand `curl` to the API, or a restart that loaded a different file
+ *     (or an `autosave.json` holding someone else's change, under `--resume`).
+ *   · declared = live — nothing to load, whatever the state says.
+ * With NO state there is no stored digest, and the question is whose config is running: see
+ * `claimable` below, which both the adoption probe and the apply ask.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { type CaddyAdmin, CaddyUnreachableError } from './admin.ts';
+import {
+  CaddyAdminError,
+  adaptCaddyfile,
+  loadCaddyfile,
+  readRunningConfig,
+} from './admin-calls.ts';
+import { adminProblems } from './admin-guard.ts';
+import {
+  type CaddyConfigAttributes,
+  type CaddyConfigProps,
+  configProblems,
+} from './config-form.ts';
+import { configDigest } from './digest.ts';
+
+const refuse = (admin: CaddyAdmin, message: string): Error =>
+  new Error(`Caddy.Config at ${admin.endpoint}: ${message}`);
+
+const short = (digest: string): string => digest.slice(0, 12);
+
+type Desired = { readonly digest: string; readonly warnings: readonly string[] };
+
+/**
+ * ⛔ A CONFIG WITH NO APPS SERVES NOTHING. A Caddyfile of only comments or only global options
+ *   passes the empty-text check (config-form.ts) yet adapts to `{}` or `{"admin":…}` — MEASURED
+ *   2026-09-21 on a throwaway Caddy 2.11.4 — and loading it stops every server: the same outage,
+ *   from the same templating bug, that the empty check exists to prevent.
+ */
+const servesNothing = (config: unknown): boolean => {
+  const apps =
+    typeof config === 'object' && config !== null ? (config as { apps?: unknown }).apps : undefined;
+  return typeof apps !== 'object' || apps === null || Object.keys(apps).length === 0;
+};
+
+/**
+ * Validate the props, adapt the Caddyfile on the running Caddy, and check its `admin` block.
+ * ★ Every refusal happens HERE, before anything is loaded — and diff calls this at plan time, so a
+ *   Caddyfile that does not adapt, carries a literal secret, or would strand the admin API fails the
+ *   PLAN, before any resource (a HostFile holding the same text included) is applied.
+ */
+export const desiredConfig = async (
+  admin: CaddyAdmin,
+  props: CaddyConfigProps,
+): Promise<Desired> => {
+  const found = configProblems(props);
+  if (found.length > 0) throw refuse(admin, found.join('; '));
+  const adapted = await adaptCaddyfile(admin, props.caddyfile);
+  if (servesNothing(adapted.config)) {
+    throw refuse(admin, 'the Caddyfile adapts to no apps — loading it would stop every site');
+  }
+  const guard = adminProblems(adapted.config, admin.listener);
+  if (guard.length > 0) throw refuse(admin, guard.join('; '));
+  return { digest: configDigest(adapted.config), warnings: adapted.warnings };
+};
+
+const attributesOf = (
+  admin: CaddyAdmin,
+  running: unknown,
+  sourceFile?: string,
+): CaddyConfigAttributes => ({
+  configSha256: configDigest(running),
+  endpoint: admin.endpoint,
+  ...(sourceFile === undefined ? {} : { sourceFile }),
+});
+
+/** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
+export const readLive = async (
+  admin: CaddyAdmin,
+  sourceFile?: string,
+): Promise<CaddyConfigAttributes> =>
+  attributesOf(admin, await readRunningConfig(admin), sourceFile);
+
+/**
+ * ⛔ WITH NO STATE, A RUNNING CONFIG IS THIS STACK'S ONLY IF IT IS THE DECLARED ONE (decision,
+ *   2026-09-21: CaddyConfig must not adopt silently — the house rule HostFile and LaunchdJob keep).
+ *   Anything else was put there by a person, another tool or another stack, and loading over it
+ *   replaces every site it serves. ★ A config that serves nothing (`null`, or no apps) is claimable
+ *   too: there is nothing to take over, as an empty R2 lock rule set reads as no lock.
+ */
+export const claimable = (running: unknown, declaredDigest: string): boolean =>
+  servesNothing(running) || configDigest(running) === declaredDigest;
+
+export type Probe = {
+  readonly attributes: CaddyConfigAttributes;
+  /** The live config IS the declared one: adopting it changes nothing. */
+  readonly ours: boolean;
+  /** Why the declaration could not be compared, when it could not — the Caddy is then not ours. */
+  readonly unchecked?: string;
+};
+
+/**
+ * The adoption probe — `read` with no state: `undefined` when Caddy serves nothing (plan a create),
+ * else the live attributes and whether they are provably ours (the provider brands the rest
+ * `Unowned`, and the plan refuses them without `--adopt`).
+ * ⛔ IT NEVER THROWS OVER THE DECLARATION. The engine also runs this read to recover an interrupted
+ *   create, with THAT deploy's props (Plan.ts, `status: "creating"`) — so a Caddyfile that failed to
+ *   adapt then would fail every later plan, the one carrying the fix included. What cannot be
+ *   compared is "not proven ours", with the reason; the next diff or apply validates the Caddyfile.
+ */
+export const probeLive = async (
+  admin: CaddyAdmin,
+  caddyfile: string | undefined,
+  sourceFile?: string,
+): Promise<Probe | undefined> => {
+  const running = await readRunningConfig(admin);
+  if (servesNothing(running)) return undefined;
+  const attributes = attributesOf(admin, running, sourceFile);
+  if (caddyfile === undefined) {
+    return { attributes, ours: false, unchecked: 'the stored Caddyfile is not plain text' };
+  }
+  try {
+    const want = await desiredConfig(admin, { caddyfile });
+    return { attributes, ours: claimable(running, want.digest) };
+  } catch (cause) {
+    // ⚠️ Unreachable mid-probe is still "no Caddy" (config.ts plans without it), not "not ours".
+    if (cause instanceof CaddyUnreachableError) throw cause;
+    return {
+      attributes,
+      ours: false,
+      unchecked: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+};
+
+/**
+ * ★ NEVER `replace`. Nothing in the props names a different object: a new Caddyfile is a reload of
+ *   the same Caddy, and `sourceFile` is a header. (Which Caddy is the transport's business — see
+ *   the ⚠️ on `endpoint` in the diff.)
+ */
+export const diffConfig = async (
+  admin: CaddyAdmin,
+  news: CaddyConfigProps,
+  output: CaddyConfigAttributes,
+): Promise<Diff> => {
+  const want = await desiredConfig(admin, news);
+  const live = await readLive(admin);
+  const converged =
+    want.digest === live.configSha256 &&
+    live.configSha256 === output.configSha256 &&
+    news.sourceFile === output.sourceFile &&
+    // ⚠️ A stack whose transport now reaches ANOTHER Caddy (a new address) must load there; the
+    //   old one keeps what it has — the same as a delete, which never unloads (see config.ts).
+    //   Planned as an update, but the state does not vouch for that Caddy: see Authority.
+    admin.endpoint === output.endpoint;
+  return converged ? { action: 'noop' } : { action: 'update' };
+};
+
+export type Applied = {
+  readonly attributes: CaddyConfigAttributes;
+  /** The adapter's warnings (e.g. "Caddyfile input is not formatted") — log them, never refuse. */
+  readonly warnings: readonly string[];
+  /** Whether a `POST /load` was sent (false when Caddy already ran this config). */
+  readonly loaded: boolean;
+};
+
+/**
+ * What this apply may load over — config.ts decides from the state and the adopt setting:
+ *   · `takeOver` — any running config: the state was applied to THIS Caddy (an update, drift
+ *     correction, or a create the engine adopted), or adoption is on (`--adopt`, or the
+ *     resource's own `adopt(true)` — host-effect.ts adoptEnabled).
+ *   · otherwise only a claimable one — plus, as `stored`, the digest the state last recorded: a
+ *     Caddy reached at a NEW endpoint that runs exactly that is the same config under another name.
+ */
+export type Authority = { readonly takeOver: boolean; readonly stored?: string };
+
+/**
+ * Load the Caddyfile unless Caddy already runs it, then read it back and insist it matches.
+ * ⛔ WITHOUT `takeOver`, A CONFIG THE STACK CANNOT CLAIM IS NEVER LOADED OVER. The engine's adoption
+ *   probe cannot guard every create: it is skipped while `news` holds an Output — ALWAYS on
+ *   caddyWithFile's first deploy (`sourceFile` is its HostFile's path) — and a Caddy that was down at
+ *   plan time read as nothing. Nor does state vouch for a Caddy the transport NOW reaches at another
+ *   endpoint (diff plans that as an update). Refused here, before any `/load`, like HostFile's.
+ */
+export const reconcileConfig = async (
+  admin: CaddyAdmin,
+  props: CaddyConfigProps,
+  authority: Authority,
+): Promise<Applied> => {
+  const want = await desiredConfig(admin, props);
+  const running = await readRunningConfig(admin);
+  const before = configDigest(running);
+  const known = before === authority.stored || claimable(running, want.digest);
+  if (!authority.takeOver && !known) {
+    throw refuse(
+      admin,
+      `Caddy runs config ${short(before)}, which this stack did not load, and the Caddyfile adapts ` +
+        `to ${short(want.digest)} — loading it would replace every site that config serves. ` +
+        'Deploy with --adopt (or wrap the resource in adopt(true)) to take this Caddy over, or ' +
+        'point caddyProviders() at the Caddy you meant.',
+    );
+  }
+  let warnings = want.warnings;
+  const loaded = before !== want.digest;
+  if (loaded) {
+    try {
+      warnings = await loadCaddyfile(admin, props.caddyfile, props.sourceFile);
+    } catch (cause) {
+      if (!(cause instanceof CaddyAdminError)) throw cause;
+      // ★ SAY WHAT IS RUNNING NOW. Caddy restores the previous config on a failed load (caddy.go
+      //   changeConfig); confirm it rather than promise it, because the deploy log is where the
+      //   person decides whether sites are down.
+      const after = await readLive(admin).catch(() => undefined);
+      const state =
+        after === undefined
+          ? 'and the running config could not be read back'
+          : after.configSha256 === before
+            ? 'Caddy kept the previous config (still serving)'
+            : `and the running config is now ${short(after.configSha256)}, not the previous ${short(before)}`;
+      throw refuse(admin, `Caddy refused the Caddyfile — ${cause.message}; ${state}`);
+    }
+  }
+  // ⚠️ READ BACK, never echo the declaration: a concurrent writer, or a load Caddy answered 200 but
+  //   did not apply (admin-calls.ts), shows up here as a refusal instead of as stored state that is
+  //   already wrong.
+  const attributes = await readLive(admin, props.sourceFile);
+  if (attributes.configSha256 !== want.digest) {
+    throw refuse(
+      admin,
+      `after the load Caddy runs config ${short(attributes.configSha256)}, not the ` +
+        `${short(want.digest)} this Caddyfile adapts to — another writer changed it, or it was not applied`,
+    );
+  }
+  return { attributes, loaded, warnings };
+};

package/src/caddy/config.ts

@@ -0,0 +1,153 @@
+/**
+ * `Caddy.Config` — a running Caddy's whole config, declared as Caddyfile text and applied through
+ * Caddy's own admin API (decision 23).
+ *
+ * - create / update — `POST /adapt` (validate), `POST /load` with `text/caddyfile` (a graceful
+ *   reload; Caddy keeps the old config if it refuses the new one, and the error names why), then
+ *   `GET /config/` and insist it matches. Skipped when Caddy already runs this config.
+ * - read — the digest of `GET /config/`. With no state it is the adoption probe (below).
+ * - diff — declared, live and stored digests (config-lifecycle.ts). Never `replace`.
+ * - delete — ⛔ NOTHING. See below.
+ *
+ * ⛔ DELETE NEVER TOUCHES CADDY, UNDER EITHER REMOVAL POLICY. Removing this declaration must not take
+ *   every site down: there is no "less config" to fall back to, and an empty config stops all
+ *   servers. `retain` is the default (the engine never calls delete); with `destroy` the handler
+ *   still only forgets. It never calls `/stop` (which exits the process) or `DELETE /config/`.
+ *   To empty a Caddy, do it by hand at its admin API.
+ * ⛔ NOTHING IS ADOPTED SILENTLY (decision, 2026-09-21 — the house rule HostFile and LaunchdJob
+ *   keep). With no state, a running Caddy whose live config IS the declared one reads as ours (the
+ *   adoption changes nothing); any other config reads as `Unowned`, and the plan refuses it unless
+ *   the deploy runs with `--adopt`. A Caddy serving nothing reads as absent: a create. Where the
+ *   engine skips that probe, reconcile refuses the same takeover (config-lifecycle.ts).
+ * ⛔ `caddyfile` IS NEVER A SECRET — see config-form.ts; refused before anything is sent.
+ * ⚠️ WHICH CADDY is the transport's (providers.ts), not a prop: one CaddyAdmin per stack.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { adoptEnabled, lift, resolvedString } from '../launchd/host-effect.ts';
+import { CaddyAdminService, CaddyUnreachableError } from './admin.ts';
+import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
+import { diffConfig, probeLive, readLive, reconcileConfig } from './config-lifecycle.ts';
+
+export type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
+
+export interface CaddyConfig extends Resource<
+  'Caddy.Config',
+  CaddyConfigProps,
+  CaddyConfigAttributes
+> {}
+
+export const CaddyConfig = Resource<CaddyConfig>('Caddy.Config', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const unreachable = (error: Error): error is CaddyUnreachableError =>
+  error instanceof CaddyUnreachableError;
+
+/**
+ * ⚠️ A STOPPED CADDY MUST NOT FAIL THE PLAN THAT BRINGS IT BACK. Its launchd job usually sits in the
+ *   same stack; if every plan died on `ECONNREFUSED`, the fix to that job could never be deployed.
+ *   So at PLAN time only (read, diff) an unreachable Caddy plans an update — with a warning, because
+ *   the plan-time `/adapt` check did not run — and reconcile, which needs Caddy, still fails loudly.
+ */
+const planWithoutCaddy =
+  <A>(admin: { endpoint: string }, fallback: A) =>
+  (error: Error) =>
+    Effect.as(
+      Effect.logWarning(
+        `Caddy.Config: no Caddy at ${admin.endpoint} (${error.message}); planning without it — ` +
+          'the Caddyfile is validated when the deploy reaches Caddy',
+      ),
+      fallback,
+    );
+
+export const CaddyConfigProvider = () =>
+  Provider.effect(
+    CaddyConfig,
+    Effect.gen(function* () {
+      const admin = yield* CaddyAdminService;
+      /** The probe, branded for the engine: plain when ours, `Unowned` otherwise. */
+      const probe = (caddyfile: string | undefined, sourceFile: string | undefined) =>
+        Effect.flatMap(
+          lift(() => probeLive(admin, caddyfile, sourceFile)),
+          (found) => {
+            if (found === undefined) return Effect.succeed(undefined);
+            if (found.ours) return Effect.succeed(found.attributes);
+            const unowned = Unowned(found.attributes);
+            return found.unchecked === undefined
+              ? Effect.succeed(unowned)
+              : Effect.as(
+                  Effect.logWarning(
+                    `Caddy.Config at ${admin.endpoint}: the running config could not be compared ` +
+                      `with the declared Caddyfile (${found.unchecked}), so it is not treated as ours`,
+                  ),
+                  unowned,
+                );
+          },
+        );
+      return CaddyConfig.Provider.of({
+        /** ⛔ A Caddy has one config; there is nothing to enumerate, and nothing for nuke to delete. */
+        list: () => Effect.succeed([]),
+
+        /**
+         * With state: the live attributes, which diff compares. With none, the ADOPTION PROBE —
+         * `olds` is the declaration (Plan.ts passes `news`), and only a live config equal to it is
+         * ours. ⚠️ A running Caddy is still the one the stack means (the transport reaches only
+         * loopback), but WHOSE CONFIG it runs is not: a person, another tool or another stack.
+         */
+        read: ({ olds, output }) =>
+          (output === undefined
+            ? probe(resolvedString(olds, 'caddyfile'), resolvedString(olds, 'sourceFile'))
+            : lift(() => readLive(admin, resolvedString(olds, 'sourceFile')))
+          ).pipe(
+            // ★ Nothing to adopt from a Caddy that is down: plan a create, which is the same load.
+            Effect.catchIf(unreachable, planWithoutCaddy(admin, undefined)),
+          ),
+
+        diff: ({ news, output }) => {
+          if (output === undefined) return Effect.succeed(undefined);
+          const update = planWithoutCaddy(admin, { action: 'update' as const });
+          if (isResolved(news)) {
+            return lift(() => diffConfig(admin, news, output)).pipe(
+              Effect.catchIf(unreachable, update),
+            );
+          }
+          /**
+           * ⚠️ `sourceFile` is an Output while its HostFile changes in the same deploy
+           *   (caddyWithFile). The Caddyfile itself is usually plain text, so validate and compare
+           *   it now — a bad Caddyfile must fail the PLAN, before the HostFile writes it to disk —
+           *   and plan an update, which reloads only if the config really differs.
+           */
+          const caddyfile = resolvedString(news, 'caddyfile');
+          if (caddyfile === undefined) return Effect.succeed(undefined);
+          return lift(async () => {
+            await diffConfig(admin, { caddyfile }, output);
+            return { action: 'update' as const };
+          }).pipe(Effect.catchIf(unreachable, update));
+        },
+
+        reconcile: ({ fqn, news, output }) =>
+          Effect.gen(function* () {
+            // ⛔ State is authority over the Caddy it was applied to, and no other. With none (the
+            //   engine may not have probed: see reconcileConfig), or with the transport now at
+            //   another endpoint, only adoption — `--adopt`, or this resource's own `adopt(…)`,
+            //   as the planner resolves it — loads over a config the stack cannot claim.
+            const sameCaddy = output !== undefined && output.endpoint === admin.endpoint;
+            const takeOver = sameCaddy || (yield* adoptEnabled(fqn));
+            const stored = output === undefined ? {} : { stored: output.configSha256 };
+            const applied = yield* lift(() =>
+              reconcileConfig(admin, news, { takeOver, ...stored }),
+            );
+            for (const warning of applied.warnings) {
+              yield* Effect.logWarning(`Caddy.Config at ${admin.endpoint}: ${warning}`);
+            }
+            return applied.attributes;
+          }),
+
+        delete: () => Effect.void,
+      });
+    }),
+  );

package/src/caddy/digest.ts

@@ -0,0 +1,44 @@
+/**
+ * The one form an adapted Caddy config is hashed in — so what `POST /adapt` returns for the
+ * declared Caddyfile and what `GET /config/` reports after the load hash the same.
+ *
+ * ⛔ THE TWO ARE NOT THE SAME BYTES, AND COMPARING BYTES WOULD BE A FOREVER-`update`. Read in
+ *   caddyserver/caddy v2.11.4:
+ *   · `/adapt` returns the adapter's `json.Marshal(cfg)` of Go STRUCTS — keys in field order
+ *     (caddyconfig/caddyfile/adapter.go Adapt; load.go handleAdapt).
+ *   · `/load` decodes that JSON into a generic `any` and re-marshals it (caddy.go changeConfig):
+ *     Go sorts MAP keys, so the stored config has every object's keys sorted.
+ *   · `GET /config/` streams that stored value through `json.Encoder`, which appends a newline
+ *     (admin.go unsyncedConfigAccess), and escapes `<`, `>` and `&` as `\u003c`, `\u003e`, `\u0026`.
+ *   Parsing both and re-serialising with sorted keys erases all three differences. MEASURED
+ *   2026-09-21 on a throwaway Caddy 2.11.4: the digest of `GET /config/` after `POST /load` equals
+ *   the digest of `/adapt` for the same Caddyfile — and a Caddy started with `--config <file>`
+ *   hashes the same as `/adapt` of that file's text, so adopting it is a noop.
+ * ★ NUMBERS AGREE BY CONSTRUCTION. Go decodes every JSON number in that generic `any` as float64
+ *   (caddy.go indexConfigObjects says so), and JSON.parse does too — the same double on both sides
+ *   serialises the same way here.
+ */
+import { sha256Hex } from '../launchd/job-form.ts';
+
+type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };
+
+const sorted = (value: Json): Json => {
+  if (Array.isArray(value)) return (value as readonly Json[]).map(sorted);
+  if (typeof value === 'object' && value !== null) {
+    const object = value as { readonly [key: string]: Json };
+    const out: Record<string, Json> = {};
+    for (const key of Object.keys(object).sort()) out[key] = sorted(object[key] ?? null);
+    return out;
+  }
+  return value;
+};
+
+/** Parse a config body Caddy returned. ⚠️ An empty config is the JSON `null`, not an error. */
+export const parseConfig = (text: string): unknown => JSON.parse(text) as unknown;
+
+/** The canonical text of a parsed config: sorted keys, no whitespace. */
+export const canonicalConfig = (config: unknown): string =>
+  JSON.stringify(sorted((config ?? null) as Json));
+
+/** SHA-256 of the canonical form — what the resource stores and compares, never the config. */
+export const configDigest = (config: unknown): string => sha256Hex(canonicalConfig(config));

package/src/caddy/fake-caddy.ts

@@ -0,0 +1,179 @@
+/**
+ * A fake Caddy admin API for the tests beside it — `Bun.serve` on an ephemeral 127.0.0.1 port (or a
+ * unix socket), answering `/adapt`, `/load` and `/config/` the way caddyserver/caddy v2.11.4 does.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file, and it never forwards anywhere.
+ * ★ WHAT IS FAITHFUL, because the provider depends on it (see admin-calls.ts and digest.ts):
+ *   · `/adapt` answers the adapter's STRUCT key order (unsorted); `/config/` answers SORTED keys,
+ *     `<` escaped as `\u003c`, and a trailing newline — the differences the digest must erase.
+ *   · A refused `/load` keeps the old config. With adapter warnings, the refusal comes in a 200
+ *     whose body is the warnings followed by the error (load.go).
+ *   · The Host check (admin.go checkHost) and the Origin check when one is sent.
+ * ★ THE TOY ADAPTER. A Caddyfile here is lines; each becomes a route. Keywords steer the fake:
+ *   `SYNTAX_ERROR` fails the adapt; `PROVISION_ERROR` adapts but fails the load; a TAB anywhere is
+ *   "not formatted" (the warning real Caddy gives unformatted input); `admin <listen>`,
+ *   `admin off` and `origins <a> <b>` set the adapted `admin` block. With no site lines there are
+ *   no apps at all, as real Caddy adapts a Caddyfile of only comments or global options.
+ * ★ `listenPort` is the port Caddy BELIEVES it listens on — its Host check uses it — while the
+ *   fake really listens on an ephemeral one: a Caddy on its default :2019 behind a forward.
+ */
+import type { CaddyAdmin } from './admin.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+
+export type Seen = {
+  readonly method: string;
+  readonly path: string;
+  readonly headers: Headers;
+  readonly body: string;
+};
+
+export type FakeCaddy = {
+  /** An address localCaddyAdmin() takes. */
+  readonly address: string;
+  readonly port: number;
+  readonly seen: Seen[];
+  /** The running config as a parsed object (null when empty). */
+  running: unknown;
+  /** Adapt with the toy adapter — to stage a "restart with a different file". */
+  adapt(caddyfile: string): unknown;
+  stop(): void;
+};
+
+const json = (status: number, body: unknown) =>
+  new Response(`${JSON.stringify(body)}\n`, {
+    headers: { 'content-type': 'application/json' },
+    status,
+  });
+
+/** The toy adapter: struct key order on purpose (`routes` before `listen`, `apps` before `admin`). */
+const toyAdapt = (text: string): { config?: unknown; error?: string; warnings: unknown[] } => {
+  const lines = text.split('\n').filter((line) => line.trim() !== '' && !line.startsWith('#'));
+  const at = lines.findIndex((line) => line.includes('SYNTAX_ERROR'));
+  if (at !== -1)
+    return { error: `Caddyfile:${String(at + 1)} - Error during parsing`, warnings: [] };
+  const admin: Record<string, unknown> = {};
+  const routes: unknown[] = [];
+  for (const line of lines) {
+    const [word, ...rest] = line.trim().split(/\s+/);
+    if (word === 'admin' && rest[0] === 'off') admin['disabled'] = true;
+    else if (word === 'admin') admin['listen'] = rest[0];
+    else if (word === 'origins') admin['origins'] = rest;
+    else routes.push({ match: [{ host: [word] }], handle: [{ handler: 'static', body: line }] });
+  }
+  const warnings = text.includes('\t')
+    ? [{ file: 'Caddyfile', line: 1, message: 'Caddyfile input is not formatted' }]
+    : [];
+  const config = {
+    ...(routes.length === 0
+      ? {}
+      : { apps: { http: { servers: { srv0: { routes, listen: [':443'] } } } } }),
+    ...(Object.keys(admin).length === 0 ? {} : { admin }),
+  };
+  return { config, warnings };
+};
+
+/** Go's generic re-marshal: sorted keys, `<>&` escaped. */
+const goEncode = (value: unknown): string => {
+  const sort = (v: unknown): unknown =>
+    Array.isArray(v)
+      ? v.map(sort)
+      : typeof v === 'object' && v !== null
+        ? Object.fromEntries(
+            Object.keys(v)
+              .sort()
+              .map((k) => [k, sort((v as Record<string, unknown>)[k])]),
+          )
+        : v;
+  return JSON.stringify(sort(value))
+    .replaceAll('<', '\\u003c')
+    .replaceAll('>', '\\u003e')
+    .replaceAll('&', '\\u0026');
+};
+
+export const fakeCaddy = (
+  options: { unix?: string; running?: unknown; origins?: string[]; listenPort?: number } = {},
+): FakeCaddy => {
+  const seen: Seen[] = [];
+  let port = 0;
+  const state: { running: unknown } = { running: options.running ?? null };
+  const allowedHosts = () =>
+    options.origins ??
+    ['localhost', '[::1]', '127.0.0.1'].map(
+      (host) => `${host}:${String(options.listenPort ?? port)}`,
+    );
+
+  const handle = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const body = await request.text();
+    seen.push({ body, headers: request.headers, method: request.method, path: url.pathname });
+    if (options.unix === undefined) {
+      const host = request.headers.get('host') ?? '';
+      if (!allowedHosts().includes(host)) return json(403, { error: `host not allowed: ${host}` });
+      const origin = request.headers.get('origin');
+      if (origin !== null && !allowedHosts().includes(new URL(origin).host)) {
+        return json(403, { error: `client is not allowed to access from origin '${origin}'` });
+      }
+    }
+    if (url.pathname === '/config/' && request.method === 'GET') {
+      return new Response(`${goEncode(state.running)}\n`, { status: 200 });
+    }
+    const type = request.headers.get('content-type') ?? '';
+    if (request.method !== 'POST' || type !== 'text/caddyfile')
+      return json(400, { error: 'unexpected' });
+    const adapted = toyAdapt(body);
+    if (adapted.error !== undefined) return json(400, { error: adapted.error });
+    if (url.pathname === '/adapt') {
+      const out = adapted.warnings.length > 0 ? { warnings: adapted.warnings } : {};
+      return json(200, { ...out, result: adapted.config });
+    }
+    if (url.pathname !== '/load') return json(404, { error: 'not found' });
+    const prefix = adapted.warnings.length > 0 ? JSON.stringify(adapted.warnings) : '';
+    if (body.includes('PROVISION_ERROR')) {
+      const error = JSON.stringify({
+        error: 'loading config: provision http: listen tcp :443: address already in use',
+      });
+      // ⛔ load.go: warnings written first commit a 200; the error rides after them.
+      return prefix === ''
+        ? new Response(`${error}\n`, { status: 400 })
+        : new Response(`${prefix}${error}\n`, { status: 200 });
+    }
+    state.running = JSON.parse(goEncode(adapted.config));
+    return new Response(prefix, { status: 200 });
+  };
+
+  const server =
+    options.unix === undefined
+      ? Bun.serve({ fetch: handle, hostname: '127.0.0.1', port: 0 })
+      : Bun.serve({ fetch: handle, unix: options.unix });
+  port = server.port ?? 0;
+  return {
+    adapt: (caddyfile) => toyAdapt(caddyfile).config,
+    address:
+      options.unix === undefined ? `http://127.0.0.1:${String(port)}` : `unix://${options.unix}`,
+    get running() {
+      return state.running;
+    },
+    set running(value: unknown) {
+      state.running = value;
+    },
+    port,
+    seen,
+    stop: () => void server.stop(true),
+  };
+};
+
+/**
+ * A fake Caddy on its DEFAULT :2019 behind a forward (`hostHeader`), and the transport to it.
+ * ★ Addressed that way so a Caddyfile with no `admin` line — the common case — passes the guard.
+ *   A Caddy reached on any other port needs `admin <address>` declared, or the first load would
+ *   move it (admin-guard.ts).
+ */
+export const fakeDefaultCaddy = (running?: unknown): { admin: CaddyAdmin; caddy: FakeCaddy } => {
+  const caddy = fakeCaddy({ listenPort: 2019, ...(running === undefined ? {} : { running }) });
+  const admin = localCaddyAdmin({
+    address: caddy.address,
+    hostHeader: '127.0.0.1:2019',
+    retries: 0,
+  });
+  return { admin, caddy };
+};