@homeflare/alchemy 0.6.0 → 0.7.0

package/README.md

@@ -4,7 +4,8 @@ Custom [Alchemy](https://alchemy.run) providers for gaps the vendor SDK leaves.
 
 ```sh
 bun add @homeflare/alchemy alchemy@2.0.0-beta.79 effect@4.0.0-rc.115 \
-        @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0
+        @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0 \
+        @distilled.cloud/cloudflare@1.0.0-rc.12
 ```
 
 ⛔ **Every one of those is required, and you also need an `overrides` block** — see
@@ -23,8 +24,7 @@ An R2 bucket's lock rules, declared rather than applied by hand. A lock rule is
 credential can delete it.
 
 ```ts
-import { R2BucketLock } from '@homeflare/alchemy';
-import { providers } from '@homeflare/alchemy/cloudflare';
+import { R2BucketLock } from '@homeflare/alchemy/cloudflare';
 
 export class BackupLock extends R2BucketLock('backup-lock', {
   bucketName: 'my-backups',
@@ -40,6 +40,41 @@ import { providers } from '@homeflare/alchemy/cloudflare';
 // …then provide `providers()` alongside Cloudflare.providers()
 ```
 
+⚠️ **The rule set is REPLACE, not merge.** The API `PUT`s the whole set, so a rule omitted
+from `rules` is a rule deleted. That is the same shape as the Cloudflare API itself.
+
+⛔ **It retains on destroy.** Removing a lock is removing a retention floor, which is the one
+operation this resource exists to make hard: dropping the declaration leaves the lock in place,
+and only an explicit `RemovalPolicy.destroy()` reaches the unlocking `delete`.
+
+## MeshNode
+
+A Cloudflare Mesh node (a `warp_connector`), declared **without its token in state**. Alchemy's
+`Cloudflare.Tunnel.WarpConnector` stores the node token in plaintext state on every read and has
+no `ha`; this one never reads the token, and `ha` is a create-only prop.
+
+```ts
+import { MeshNode, providers } from '@homeflare/alchemy/cloudflare';
+
+const door = yield * MeshNode('vault-door', { name: 'door-a', ha: false });
+// door.id → the node id for the Gateway rules and for fetchMeshNodeToken
+```
+
+- **`name`** renames in place (`PATCH`); **`ha`** is required and replaces the node (delete-first
+  while the name stays). Existing nodes are adopted by exact name, `Unowned` until `adopt(true)`.
+- ⛔ **It retains on destroy** (deleting a node cuts every replica off the Mesh), so a same-name
+  `ha` change refuses, writing nothing, until that deploy pipes `RemovalPolicy.destroy()`.
+- ★ **A door (a node with no routes) is `ha: false`.** HA fails over routes, and each replica has
+  its own Mesh IP; a second door is a second `MeshNode`.
+- The account and credentials come from Alchemy's own Cloudflare environment, the same as
+  `Cloudflare.providers()`.
+- **`fetchMeshNodeToken({ accountId, id })`** returns the token `Redacted`, on demand, for a
+  one-off enrolment step. ⛔ Write it to a root-owned `0600` file on the node and nowhere else.
+  It refuses the Global API Key, an empty API token, and a set `DISTILLED_DEBUG_HTTP` (distilled
+  would print the token).
+
+Guide, the enrolment step and every replace case: [docs/mesh-node.md](./docs/mesh-node.md).
+
 ## Website.Astro / Website.Vite
 
 House flags on Alchemy's own stacks — the two this estate actually ships.
@@ -58,12 +93,6 @@ const app = yield * viteWebsite('aimto', { rootDir: webRoot });
 ⛔ Not Nextjs. `Website.Nextjs` hashes source and plans as **create** against a live
 Worker. Adopt that shape with `Worker`, not a helper here.
 
-⚠️ **The rule set is REPLACE, not merge.** The API `PUT`s the whole set, so a rule omitted
-from `rules` is a rule deleted. That is the same shape as the Cloudflare API itself.
-
-⛔ **Deletion is refused by design.** Removing a lock is removing a retention floor, which
-is the one operation this resource exists to make hard. It retains on destroy.
-
 ## OpenBao — `@homeflare/alchemy/openbao`
 
 Vault objects as resources — mounts (with `remountFrom` moves), auth methods, policies, AppRole,
@@ -90,9 +119,23 @@ delete-first.
 - ⛔ **No silent sudo:** the system domain needs a deploy started as root, or a `privileged` runner.
 - ⚠️ `org.nixos.*` jobs are never adopted. Guide and nix-darwin cutover: [docs/launchd.md](./docs/launchd.md).
 
+## Caddy — `@homeflare/alchemy/caddy`
+
+`CaddyConfig` declares a running Caddy's config as Caddyfile text, applied through Caddy's own admin
+API: `POST /load` (graceful reload; Caddy keeps the old config if it refuses the new one, and the
+deploy says why), `GET /config/` for drift. A running Caddy is adopted on first read.
+`caddyWithFile()` also writes the file Caddy starts from, with `HostFile`; `caddyProviders()` provides
+the transport, `http://127.0.0.1:2019` by default.
+
+- ⛔ **No secrets in the Caddyfile** (state is unencrypted): `{env.NAME}` / `{file./path}` placeholders.
+- ⛔ **The admin API stays on loopback or a unix socket**, and a Caddyfile that would move it is refused.
+- ⛔ **Delete never unloads or stops Caddy.** Order of file and load, `--resume`: [docs/caddy.md](./docs/caddy.md).
+
 ## Credentials
 
 `CLOUDFLARE_API_TOKEN` is read from the environment at call time, never at module scope.
+`MeshNode` instead resolves credentials and the account the way `Cloudflare.providers()` does
+(an Alchemy profile, or `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` in CI).
 
 ⛔ **Mint a short-lived, scoped token** — do not reuse a long-lived one, and never a Global
 API Key. An empty value fails closed with a message saying so, because an empty render is
@@ -103,7 +146,8 @@ like a bad credential.
 
 ```sh
 bun add @homeflare/alchemy alchemy@2.0.0-beta.79 effect@4.0.0-rc.115 \
-        @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0
+        @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0 \
+        @distilled.cloud/cloudflare@1.0.0-rc.12
 ```
 
 ⚠️ Peers, not dependencies: Alchemy's resource registry and Effect's context both break if

package/dist/caddy/admin-calls.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The three admin API calls the provider makes, each classified into a value or a readable Error
+ * that carries Caddy's own message.
+ *
+ * Read in caddyserver/caddy v2.11.4 (and the API docs, caddyserver.com/docs/api):
+ *   · `POST /adapt` — adapts without running (load.go handleAdapt): 200 `{warnings?, result}`,
+ *     or 400 `{"error": …}`. Side-effect free, so it is what plan-time validation uses.
+ *   · `POST /load` — Content-Type `text/caddyfile` picks the adapter (load.go adaptByContentType);
+ *     "if the new config fails for any reason, the old config is rolled back into place without
+ *     downtime" (docs; caddy.go changeConfig restores the previous raw config). An identical
+ *     config is a no-op without `Cache-Control: must-revalidate`.
+ *   · `GET /config/` — the running config as JSON, `null` when empty (admin.go handleConfig).
+ * ⛔ A FAILED LOAD CAN ANSWER 200. load.go writes the adapter's WARNINGS to the body before it
+ *   runs the config; if the run then fails, the error JSON is appended to a response whose status
+ *   is already 200 (Go's first Write sends 200; the later WriteHeader(400) is ignored). The
+ *   Caddyfile adapter warns on every unformatted input (adapter.go FormattingDifference), so this
+ *   is the COMMON failure shape, not an edge. Hence: look for the error in the body whatever the
+ *   status — and the lifecycle reads the config back after every load anyway.
+ *   MEASURED 2026-09-21 on a throwaway Caddy 2.11.4 (loopback ports, isolated XDG dirs): an
+ *   unformatted Caddyfile whose port was taken answered `200` with body
+ *   `[{"file":"Caddyfile","line":8,"message":"Caddyfile input is not formatted; …"}]{"error":"loading
+ *   config: … bind: address already in use"}`, and Caddy kept serving the previous config.
+ */
+import type { CaddyAdmin } from './admin.ts';
+export declare class CaddyAdminError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(status: number, method: string, path: string, reason: string);
+}
+export type Adapted = {
+    readonly config: unknown;
+    readonly warnings: readonly string[];
+};
+/** Adapt a Caddyfile to JSON on the running Caddy, without loading it. */
+export declare const adaptCaddyfile: (admin: CaddyAdmin, caddyfile: string) => Promise<Adapted>;
+/** The running config, parsed; `null` when Caddy runs with none. */
+export declare const readRunningConfig: (admin: CaddyAdmin) => Promise<unknown>;
+/**
+ * Apply a Caddyfile with `POST /load`; resolves with the adapter's warnings.
+ *
+ * ★ `sourceFile` RIDES AS `Caddy-Config-Source-File` (+ `-Adapter: caddyfile`), the headers
+ *   `caddy reload` sends (cmd/commandfuncs.go). A load WITHOUT them makes Caddy forget the file it
+ *   was started with (caddy.go ClearLastConfigIfDifferent), and SIGUSR1 then no longer reloads
+ *   from that file. With them, and the same path, it keeps it.
+ */
+export declare const loadCaddyfile: (admin: CaddyAdmin, caddyfile: string, sourceFile?: string) => Promise<readonly string[]>;
+//# sourceMappingURL=admin-calls.d.ts.map

package/dist/caddy/admin-calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-calls.d.ts","sourceRoot":"","sources":["../../src/caddy/admin-calls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,YAAY,CAAC;AAGjE,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAHvB,YACW,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EAIf;CACF;AAwCD,MAAM,MAAM,OAAO,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEzF,0EAA0E;AAC1E,eAAO,MAAM,cAAc,UAAiB,UAAU,aAAa,MAAM,KAAG,OAAO,CAAC,OAAO,CAY1F,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,UAAiB,UAAU,KAAG,OAAO,CAAC,OAAO,CAI1E,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,UACjB,UAAU,aACN,MAAM,eACJ,MAAM,KAClB,OAAO,CAAC,SAAS,MAAM,EAAE,CAe3B,CAAC"}

package/dist/caddy/admin-guard.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Refuse a config whose `admin` block would cut the provider off from Caddy, or expose the admin
+ * API — checked on the ADAPTED JSON (`POST /adapt`), before anything is loaded.
+ *
+ * ⛔ A Caddyfile can move its own admin endpoint. After `POST /load`, Caddy swaps the admin server
+ *   to the new config's (admin.go replaceLocalAdminServer), so each of these would succeed ONCE and
+ *   then strand the resource — no read-back, no drift check, no next deploy — or worse:
+ *   · `admin off` (`disabled`): nothing can manage this Caddy through its API again.
+ *   · a `listen` off loopback (`:2019`, `0.0.0.0:2019`, a LAN address): the unauthenticated API is
+ *     on the network. Decision 23: never expose :2019.
+ *   · a `listen` on another port, socket or loopback ADDRESS than the transport's: the provider
+ *     loses Caddy. Go binds exactly the literal address given (`[::1]:2019` is not reachable at
+ *     `127.0.0.1:2019`), and a hostname binds its first IPv4 address (net ListenConfig.Listen,
+ *     `addrs.first(isIPv4)`), so `localhost:2019` is `127.0.0.1:2019`. MEASURED 2026-09-21 on a
+ *     throwaway Caddy 2.11.4: after loading `admin [::1]:<p>`, `127.0.0.1:<p>` refused the
+ *     connection; after `admin localhost:<p>`, `[::1]:<p>` did.
+ *   · NO `admin` address at all: Caddy falls back to DefaultAdminListen — `localhost:2019`, or
+ *     `$CADDY_ADMIN` in ITS environment (admin.go replaceLocalAdminServer), which this side cannot
+ *     see. A Caddy reached any other way (a socket, another port) moves there on the first load.
+ *     Refused unless the transport is at that default; declaring `admin <address>` is the fix.
+ *   · a Host the new config does not allow: `origins` without it, or — with no `origins` — a Host
+ *     outside Caddy's loopback defaults (`localhost`, `[::1]`, `127.0.0.1` at the listen port).
+ *     Every later call answers 403 (admin.go allowedOrigins / checkHost; MEASURED on the mini's
+ *     Caddy 2.11.4 — `host not allowed`). The transport also sends `Origin: http://<Host>`, which
+ *     Caddy checks against the same list (originAllowed), so one check covers both.
+ *   · `enforce_origin` over a unix socket: this transport, like Caddy's CLI (cmd/commandfuncs.go
+ *     AdminAPIRequest), sends no Origin there, and a unix listener has no default origins — so
+ *     checkOrigin answers 403 to every call. MEASURED 2026-09-21 on a throwaway Caddy 2.11.4:
+ *     `client is not allowed to access from origin ''`, and that Caddy could not be managed again.
+ *   · `remote`: a second, network-facing admin listener (mTLS on :2021) — declare that deliberately,
+ *     not through this resource.
+ *   · `config.load`: Caddy pulls its config from elsewhere, replacing this one on a timer.
+ * ★ Read in caddyserver/caddy v2.11.4: admin.go AdminConfig / allowedOrigins / originAllowed, and
+ *   httpcaddyfile/options.go parseOptAdmin (an `admin { … }` block with no address still emits
+ *   `listen` as the default, so a present `listen` is the norm, not a change).
+ */
+import type { CaddyAdminListener } from './admin.ts';
+/** Refusals for the adapted config's `admin` block, given where the transport reaches Caddy. */
+export declare const adminProblems: (adapted: unknown, transport: CaddyAdminListener) => string[];
+//# sourceMappingURL=admin-guard.d.ts.map

package/dist/caddy/admin-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-guard.d.ts","sourceRoot":"","sources":["../../src/caddy/admin-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgGrD,gGAAgG;AAChG,eAAO,MAAM,aAAa,YAAa,OAAO,aAAa,kBAAkB,KAAG,MAAM,EAoCrF,CAAC"}

package/dist/caddy/admin.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The one seam between the Caddy provider and a running Caddy: every call to Caddy's admin API goes
+ * through a CaddyAdmin, and nothing in this directory reaches Caddy any other way.
+ *
+ * ★ CADDY's OWN MANAGEMENT API, NOT A FILE AND A SIGNAL. Decision 23 (vault consolidation plan,
+ *   2026-09-21): `POST /load` applies a Caddyfile with a graceful reload and rolls back a config
+ *   Caddy refuses; `GET /config/` reports what is running. Read in caddyserver/caddy v2.11.4,
+ *   caddyconfig/load.go and admin.go, and in the API docs (caddyserver.com/docs/api).
+ * ★ A SEAM, THE SAME SHAPE AS launchd's HostRunner, so the lifecycle runs against a fake admin
+ *   server in tests and a consumer can plug in another route to the API (an SSH-forwarded socket
+ *   today; a remote runner later) without touching the provider. PROMISES, NOT EFFECTS, for the
+ *   same reason as HostRunner: a consumer writing their own implements plain async functions.
+ * ⛔ THE ADMIN API HAS NO AUTHENTICATION. Anyone who reaches it can replace every site. It stays on
+ *   loopback or a unix socket; localCaddyAdmin() refuses anything else (local-admin.ts).
+ */
+import * as Context from 'effect/Context';
+import * as Layer from 'effect/Layer';
+/** One admin API exchange. ⛔ `body` may hold the running config — never log it whole. */
+export type CaddyAdminResponse = {
+    readonly status: number;
+    readonly body: string;
+};
+export type CaddyAdminRequest = {
+    readonly method: 'GET' | 'POST';
+    /** Absolute API path: `/load`, `/adapt`, `/config/`. */
+    readonly path: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+};
+/**
+ * Where the admin listener is, in the terms Caddy's own `admin` option uses — so a Caddyfile that
+ * would move the listener away from where the provider talks to it can be refused (admin-guard.ts).
+ */
+export type CaddyAdminListener = {
+    readonly kind: 'tcp';
+    readonly hostHeader: string;
+    readonly port: number;
+} | {
+    readonly kind: 'unix';
+    readonly path: string;
+};
+export interface CaddyAdmin {
+    /** Where requests go, for error messages and the resource's attributes. Never a credential. */
+    readonly endpoint: string;
+    /**
+     * The listener as Caddy sees it. `hostHeader` is the Host every request carries: Caddy checks it
+     * against `admin.origins` (admin.go checkHost) on any loopback TCP listener.
+     */
+    readonly listener: CaddyAdminListener;
+    /**
+     * Send one request. Resolves with ANY status — classifying it is the caller's job
+     * (admin-calls.ts). Rejects only when there was no HTTP exchange at all: with a
+     * CaddyUnreachableError when nothing accepted the connection, any other Error otherwise.
+     */
+    request(request: CaddyAdminRequest): Promise<CaddyAdminResponse>;
+}
+/**
+ * Nothing accepted the connection — Caddy is not running, or not listening yet. A transport rejects
+ * with THIS only when the request provably never reached Caddy (refused, no socket file), because
+ * the provider treats it differently from every other failure: a stopped Caddy must not fail the
+ * PLAN that would bring it back (its launchd job in the same stack) — see config.ts.
+ */
+export declare class CaddyUnreachableError extends Error {
+    readonly name = "CaddyUnreachableError";
+}
+declare const CaddyAdminService_base: Context.ServiceClass<CaddyAdminService, "homeflare/caddy/CaddyAdmin", CaddyAdmin>;
+/** The Effect service the Caddy provider reads its admin transport from. */
+export declare class CaddyAdminService extends CaddyAdminService_base {
+}
+/** Provide a transport to the provider: `Layer.provide(caddyAdminLayer(localCaddyAdmin()))`. */
+export declare const caddyAdminLayer: (admin: CaddyAdmin) => Layer.Layer<CaddyAdminService>;
+export {};
+//# sourceMappingURL=admin.d.ts.map

package/dist/caddy/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/caddy/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,yFAAyF;AACzF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,MAAM,WAAW,UAAU;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClE;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAkB,IAAI,2BAA2B;CAClD;;AAED,4EAA4E;AAC5E,qBAAa,iBAAkB,SAAQ,sBAEtC;CAAG;AAEJ,gGAAgG;AAChG,eAAO,MAAM,eAAe,UAAW,UAAU,KAAG,KAAK,CAAC,KAAK,CAAC,iBAAiB,CACxC,CAAC"}

package/dist/caddy/caddyfile-tripwire.d.ts

@@ -0,0 +1,5 @@
+/** One line's tokens: whitespace-separated, "double-quoted" and `backquoted` kept whole, # comments dropped. */
+export declare const tokensOf: (line: string) => string[];
+/** Refusals for a Caddyfile's text. Empty means nothing tripped. */
+export declare const caddyfileSecretProblems: (caddyfile: string) => string[];
+//# sourceMappingURL=caddyfile-tripwire.d.ts.map

package/dist/caddy/caddyfile-tripwire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caddyfile-tripwire.d.ts","sourceRoot":"","sources":["../../src/caddy/caddyfile-tripwire.ts"],"names":[],"mappings":"AAgEA,gHAAgH;AAChH,eAAO,MAAM,QAAQ,SAAU,MAAM,KAAG,MAAM,EAuB7C,CAAC;AAoCF,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,cAAe,MAAM,KAAG,MAAM,EAOjE,CAAC"}

package/dist/caddy/config-form.d.ts

@@ -0,0 +1,27 @@
+export interface CaddyConfigProps {
+    /**
+     * The whole Caddyfile. Applied with `POST /load` (Content-Type `text/caddyfile`); it REPLACES the
+     * running config. ⛔ Never a secret. ⚠️ `import` paths resolve against Caddy's working directory
+     * (the API adapts with no file name), so keep them absolute.
+     */
+    caddyfile: string;
+    /**
+     * The file Caddy was started with (`caddy run --config <this>`), when the same Caddyfile is also
+     * written there — `caddyWithFile()` sets it from its HostFile. Sent as
+     * `Caddy-Config-Source-File` so a load keeps Caddy's SIGUSR1 reload-from-file working.
+     */
+    sourceFile?: string;
+}
+export interface CaddyConfigAttributes {
+    /**
+     * SHA-256 of the ADAPTED JSON Caddy reported after the last apply (digest.ts canonical form) —
+     * never the config itself. Drift is the live config hashing to anything else.
+     */
+    configSha256: string;
+    /** The admin endpoint the config was applied through (no credential; the API has none). */
+    endpoint: string;
+    /** The `sourceFile` prop as applied. */
+    sourceFile?: string;
+}
+export declare const configProblems: (props: CaddyConfigProps) => string[];
+//# sourceMappingURL=config-form.d.ts.map

package/dist/caddy/config-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-form.d.ts","sourceRoot":"","sources":["../../src/caddy/config-form.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAWD,eAAO,MAAM,cAAc,UAAW,gBAAgB,KAAG,MAAM,EAiB9D,CAAC"}

package/dist/caddy/config-lifecycle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { type CaddyConfigAttributes, type CaddyConfigProps } from './config-form.ts';
+type Desired = {
+    readonly digest: string;
+    readonly warnings: readonly string[];
+};
+/**
+ * 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 declare const desiredConfig: (admin: CaddyAdmin, props: CaddyConfigProps) => Promise<Desired>;
+/** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
+export declare const readLive: (admin: CaddyAdmin, sourceFile?: string) => Promise<CaddyConfigAttributes>;
+/**
+ * ★ 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 declare const diffConfig: (admin: CaddyAdmin, news: CaddyConfigProps, output: CaddyConfigAttributes) => Promise<Diff>;
+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 declare const reconcileConfig: (admin: CaddyAdmin, props: CaddyConfigProps) => Promise<Applied>;
+export {};
+//# sourceMappingURL=config-lifecycle.d.ts.map

package/dist/caddy/config-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-lifecycle.d.ts","sourceRoot":"","sources":["../../src/caddy/config-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ7C,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAEtB,MAAM,kBAAkB,CAAC;AAQ1B,KAAK,OAAO,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAcjF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UACjB,UAAU,SACV,gBAAgB,KACtB,OAAO,CAAC,OAAO,CAUjB,CAAC;AAEF,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,UACZ,UAAU,eACJ,MAAM,KAClB,OAAO,CAAC,qBAAqB,CAI9B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,UACd,UAAU,QACX,gBAAgB,UACd,qBAAqB,KAC5B,OAAO,CAAC,IAAI,CAWd,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,gGAAgG;AAChG,eAAO,MAAM,eAAe,UACnB,UAAU,SACV,gBAAgB,KACtB,OAAO,CAAC,OAAO,CAmCjB,CAAC"}

package/dist/caddy/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `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 * as Provider from 'alchemy/Provider';
+import { CaddyAdminService } from './admin.ts';
+import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
+export type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
+export interface CaddyConfig extends Resource<'Caddy.Config', CaddyConfigProps, CaddyConfigAttributes> {
+}
+export declare const CaddyConfig: import("alchemy").ResourceClass<CaddyConfig>;
+export declare const CaddyConfigProvider: () => import("effect/Layer").Layer<Provider.Provider<CaddyConfig>, never, CaddyAdminService>;
+//# sourceMappingURL=config.d.ts.map

package/dist/caddy/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/caddy/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAyB,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGhF,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEhF,MAAM,WAAW,WAAY,SAAQ,QAAQ,CAC3C,cAAc,EACd,gBAAgB,EAChB,qBAAqB,CACtB;CAAG;AAEJ,eAAO,MAAM,WAAW,8CAEtB,CAAC;AAsBH,eAAO,MAAM,mBAAmB,8FAsD7B,CAAC"}

package/dist/caddy/digest.d.ts

@@ -0,0 +1,7 @@
+/** Parse a config body Caddy returned. ⚠️ An empty config is the JSON `null`, not an error. */
+export declare const parseConfig: (text: string) => unknown;
+/** The canonical text of a parsed config: sorted keys, no whitespace. */
+export declare const canonicalConfig: (config: unknown) => string;
+/** SHA-256 of the canonical form — what the resource stores and compares, never the config. */
+export declare const configDigest: (config: unknown) => string;
+//# sourceMappingURL=digest.d.ts.map

package/dist/caddy/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../src/caddy/digest.ts"],"names":[],"mappings":"AAmCA,+FAA+F;AAC/F,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG,OAAsC,CAAC;AAElF,yEAAyE;AACzE,eAAO,MAAM,eAAe,WAAY,OAAO,KAAG,MACA,CAAC;AAEnD,+FAA+F;AAC/F,eAAO,MAAM,YAAY,WAAY,OAAO,KAAG,MAA4C,CAAC"}

package/dist/caddy/fake-caddy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+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;
+};
+export declare const fakeCaddy: (options?: {
+    unix?: string;
+    running?: unknown;
+    origins?: string[];
+    listenPort?: number;
+}) => FakeCaddy;
+//# sourceMappingURL=fake-caddy.d.ts.map

package/dist/caddy/fake-caddy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-caddy.d.ts","sourceRoot":"","sources":["../../src/caddy/fake-caddy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IACtB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,IAAI,IAAI,IAAI,CAAC;CACd,CAAC;AAqDF,eAAO,MAAM,SAAS,aACX;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,KACrF,SAoEF,CAAC"}

package/dist/caddy/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Caddy for Alchemy — a running Caddy's config, declared as Caddyfile text and applied through
+ * Caddy's own admin API (`POST /load`, `GET /config/`).
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The lifecycle,
+ *   the digest, the guards and the admin calls are internals; an `export *` would publish them.
+ * ⛔ THE ADMIN API STAYS ON LOOPBACK OR A UNIX SOCKET. It has no authentication; localCaddyAdmin()
+ *   refuses any other address, and a Caddyfile that would move or expose it is refused before load.
+ * Guide, order of file and load, `--resume` and secrets: docs/caddy.md.
+ */
+export type { CaddyAdmin, CaddyAdminListener, CaddyAdminRequest, CaddyAdminResponse, } from './admin.ts';
+export { CaddyAdminService, CaddyUnreachableError, caddyAdminLayer } from './admin.ts';
+export { CaddyAdminError } from './admin-calls.ts';
+export type { CaddyConfigAttributes, CaddyConfigProps } from './config.ts';
+export { CaddyConfig, CaddyConfigProvider } from './config.ts';
+export type { LocalCaddyAdminOptions } from './local-admin.ts';
+export { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin } from './local-admin.ts';
+export { caddyProviders } from './providers.ts';
+export type { CaddyWithFileProps } from './with-file.ts';
+export { caddyWithFile } from './with-file.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/caddy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/caddy/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}