@homeflare/alchemy 0.5.0 → 0.7.0

package/src/caddy/config-lifecycle.test.ts

@@ -0,0 +1,218 @@
+/**
+ * CaddyConfig's lifecycle against the fake admin API (fake-caddy.ts): apply, a refused config
+ * rolled back, drift, and the refusals that must happen before anything is sent.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import type { CaddyAdmin } from './admin.ts';
+import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
+import { configDigest } from './digest.ts';
+import { diffConfig, readLive, reconcileConfig } from './config-lifecycle.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+const OTHER = 'www.example.com respond <hello> & bye';
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+/**
+ * ★ Addressed as a Caddy on its DEFAULT :2019 behind a forward (`hostHeader`), 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).
+ */
+const setup = (running?: unknown) => {
+  fake = fakeCaddy({ listenPort: 2019, ...(running === undefined ? {} : { running }) });
+  const admin = localCaddyAdmin({
+    address: fake.address,
+    hostHeader: '127.0.0.1:2019',
+    retries: 0,
+  });
+  return { admin, caddy: fake };
+};
+
+const loads = (caddy: FakeCaddy) => caddy.seen.filter((call) => call.path === '/load');
+
+describe('apply', () => {
+  test('loads the Caddyfile, reads it back, and stores the digest Caddy reports', async () => {
+    const { admin, caddy } = setup();
+    const applied = await reconcileConfig(admin, { caddyfile: OTHER });
+    expect(applied.loaded).toBe(true);
+    // ★ The fake's /config/ is sorted and escaped differently from /adapt; the digests still agree.
+    expect(applied.attributes.configSha256).toBe(configDigest(caddy.adapt(OTHER)));
+    expect(applied.attributes.endpoint).toBe(caddy.address);
+    const [load] = loads(caddy);
+    expect(load?.headers.get('content-type')).toBe('text/caddyfile');
+    expect(load?.body).toBe(OTHER);
+  });
+
+  test('a Caddy already running this config is not reloaded', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE });
+    const again = await reconcileConfig(admin, { caddyfile: SITE });
+    expect(again.loaded).toBe(false);
+    expect(loads(caddy)).toHaveLength(1);
+  });
+
+  test('sourceFile rides as the headers `caddy reload` sends, and lands in the attributes', async () => {
+    const { admin, caddy } = setup();
+    const path = '/usr/local/etc/Caddyfile';
+    const applied = await reconcileConfig(admin, { caddyfile: SITE, sourceFile: path });
+    expect(loads(caddy)[0]?.headers.get('caddy-config-source-file')).toBe(path);
+    expect(loads(caddy)[0]?.headers.get('caddy-config-source-adapter')).toBe('caddyfile');
+    expect(applied.attributes.sourceFile).toBe(path);
+  });
+
+  test('adapter warnings are returned, not refused', async () => {
+    const { admin } = setup();
+    const applied = await reconcileConfig(admin, { caddyfile: `${SITE}\t` });
+    expect(applied.warnings).toEqual(['Caddyfile:1: Caddyfile input is not formatted']);
+  });
+});
+
+describe('a config Caddy refuses', () => {
+  test('surfaces Caddy’s reason and confirms the previous config is still running', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE });
+    const before = caddy.running;
+    await expect(reconcileConfig(admin, { caddyfile: `${SITE}\nPROVISION_ERROR` })).rejects.toThrow(
+      /address already in use.*kept the previous config/,
+    );
+    expect(caddy.running).toEqual(before);
+  });
+
+  test('a refusal that came back as a 200 (warnings first) is still a refusal', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE });
+    await expect(
+      reconcileConfig(admin, { caddyfile: `${SITE}\t\nPROVISION_ERROR` }),
+    ).rejects.toThrow(/→ 200: loading config.*error in a 200 body.*kept the previous/);
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+
+  test('a load answered 200 that Caddy did not apply fails the deploy (the read-back)', async () => {
+    const { admin, caddy } = setup();
+    await reconcileConfig(admin, { caddyfile: SITE });
+    // ⚠️ A concurrent writer, or a 200 that carried no change: state must not record OTHER.
+    const swallowing: CaddyAdmin = {
+      ...admin,
+      request: (call) =>
+        call.path === '/load' ? Promise.resolve({ body: '', status: 200 }) : admin.request(call),
+    };
+    await expect(reconcileConfig(swallowing, { caddyfile: OTHER })).rejects.toThrow(
+      /after the load Caddy runs config \w+, not the \w+ this Caddyfile adapts to/,
+    );
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+
+  test('a Caddyfile that does not adapt is refused before any load', async () => {
+    const { admin, caddy } = setup();
+    await expect(reconcileConfig(admin, { caddyfile: 'SYNTAX_ERROR' })).rejects.toThrow(
+      /\/adapt → 400: Caddyfile:1 - Error during parsing/,
+    );
+    expect(loads(caddy)).toHaveLength(0);
+  });
+});
+
+describe('refused before anything is sent', () => {
+  test.each([
+    ['a literal token', 'example.com {\n  dns cloudflare abcdef0123456789\n}'],
+    ['an empty Caddyfile', '  \n'],
+  ])('%s', async (_, caddyfile) => {
+    const { admin, caddy } = setup();
+    await expect(reconcileConfig(admin, { caddyfile })).rejects.toThrow(/Caddy\.Config at http/);
+    expect(caddy.seen).toHaveLength(0);
+  });
+
+  test.each([
+    ['only a comment', '# the template rendered nothing'],
+    ['only global options', 'admin localhost:2019'],
+  ])('a Caddyfile of %s adapts to no apps, and is never loaded', async (_, caddyfile) => {
+    const { admin, caddy } = setup();
+    await expect(reconcileConfig(admin, { caddyfile })).rejects.toThrow(/adapts to no apps/);
+    expect(loads(caddy)).toHaveLength(0);
+  });
+
+  test('a Caddyfile that would turn the admin API off is never loaded', async () => {
+    const { admin, caddy } = setup();
+    await expect(reconcileConfig(admin, { caddyfile: `admin off\n${SITE}` })).rejects.toThrow(
+      /admin off/,
+    );
+    expect(loads(caddy)).toHaveLength(0);
+  });
+});
+
+describe('drift', () => {
+  const applied = async () => {
+    const { admin, caddy } = setup();
+    const { attributes } = await reconcileConfig(admin, { caddyfile: SITE });
+    return { admin, attributes, caddy };
+  };
+
+  test('converged: declared, live and stored agree → noop', async () => {
+    const { admin, attributes } = await applied();
+    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'noop' });
+  });
+
+  test('a changed declaration → update', async () => {
+    const { admin, attributes } = await applied();
+    expect(await diffConfig(admin, { caddyfile: OTHER }, attributes)).toEqual({ action: 'update' });
+  });
+
+  test('a hand edit through the API → update, and the apply puts the declaration back', async () => {
+    const { admin, attributes, caddy } = await applied();
+    caddy.running = { apps: { http: { servers: {} } } };
+    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'update' });
+    const again = await reconcileConfig(admin, { caddyfile: SITE });
+    expect(again.attributes.configSha256).toBe(attributes.configSha256);
+  });
+
+  test('a restart with a different file → update', async () => {
+    const { admin, attributes, caddy } = await applied();
+    caddy.running = JSON.parse(JSON.stringify(caddy.adapt(OTHER))) as unknown;
+    expect((await readLive(admin)).configSha256).not.toBe(attributes.configSha256);
+    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'update' });
+  });
+
+  test('state that lags the live config → update, so the stored digest is refreshed', async () => {
+    const { admin, attributes } = await applied();
+    const stale = { ...attributes, configSha256: configDigest({ apps: { before: true } }) };
+    expect(await diffConfig(admin, { caddyfile: SITE }, stale)).toEqual({ action: 'update' });
+  });
+
+  test('the transport now reaches Caddy at another endpoint → update (load there)', async () => {
+    const { admin, attributes } = await applied();
+    const moved = { ...attributes, endpoint: 'unix:///run/caddy/admin.sock' };
+    expect(await diffConfig(admin, { caddyfile: SITE }, moved)).toEqual({ action: 'update' });
+  });
+
+  test('a new sourceFile → update, so state records the file this config mirrors', async () => {
+    const { admin, attributes } = await applied();
+    const diff = await diffConfig(
+      admin,
+      { caddyfile: SITE, sourceFile: '/etc/Caddyfile' },
+      attributes,
+    );
+    expect(diff).toEqual({ action: 'update' });
+  });
+});
+
+describe('adopt', () => {
+  test('a running Caddy reads as its live config; the first apply replaces it', async () => {
+    const { admin, caddy } = setup({
+      apps: { http: { servers: { legacy: { listen: [':80'] } } } },
+    });
+    const adopted = await readLive(admin);
+    expect(adopted.configSha256).toBe(configDigest(caddy.running));
+    expect(await diffConfig(admin, { caddyfile: SITE }, adopted)).toEqual({ action: 'update' });
+    await reconcileConfig(admin, { caddyfile: SITE });
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+
+  test('an empty Caddy (config null) is adoptable too', async () => {
+    const { admin } = setup();
+    expect((await readLive(admin)).configSha256).toBe(configDigest(null));
+  });
+});

package/src/caddy/config-lifecycle.ts

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { CaddyAdmin } 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 };
+};
+
+/** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
+export const readLive = async (
+  admin: CaddyAdmin,
+  sourceFile?: string,
+): Promise<CaddyConfigAttributes> => ({
+  configSha256: configDigest(await readRunningConfig(admin)),
+  endpoint: admin.endpoint,
+  ...(sourceFile === undefined ? {} : { sourceFile }),
+});
+
+/**
+ * ★ 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).
+    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;
+};
+
+/** Load the Caddyfile unless Caddy already runs it, then read it back and insist it matches. */
+export const reconcileConfig = async (
+  admin: CaddyAdmin,
+  props: CaddyConfigProps,
+): Promise<Applied> => {
+  const want = await desiredConfig(admin, props);
+  const before = configDigest(await readRunningConfig(admin));
+  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,116 @@
+/**
+ * `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, A RUNNING CADDY IS ADOPTED: its live
+ *   config becomes the starting point, and the deploy's forced update loads the declared one.
+ * - 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.
+ * ⛔ `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 { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { lift, resolvedString } from '../launchd/host-effect.ts';
+import { CaddyAdminService, CaddyUnreachableError } from './admin.ts';
+import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
+import { diffConfig, 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;
+      return CaddyConfig.Provider.of({
+        /** ⛔ A Caddy has one config; there is nothing to enumerate, and nothing for nuke to delete. */
+        list: () => Effect.succeed([]),
+
+        /**
+         * ★ Plain attributes, never `Unowned`: a Caddy on this host's loopback admin API is the one
+         *   the stack means (the transport refuses anything else), and adopting reads — it changes
+         *   nothing until reconcile loads the declared Caddyfile.
+         */
+        read: ({ olds }) =>
+          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: ({ news }) =>
+          Effect.gen(function* () {
+            const applied = yield* lift(() => reconcileConfig(admin, news));
+            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));