@homeflare/alchemy 0.31.2 → 0.32.0

package/docs/opnsense.md

@@ -0,0 +1,146 @@
+# OPNsense — `@homeflare/alchemy/opnsense`
+
+Declares `Opnsense.Firewall.Alias`, `.Category` and `.Group` against
+`@distilled.cloud/opnsense` (aliased onto `@homeflare/distilled-opnsense@0.2.0` —
+[`distilled-interim.md`](./distilled-interim.md)). Built 2026-09-24. **READ-ONLY BY
+DESIGN** — see "The policy" below before reading anything else here. This is the
+estate's **edge firewall**: nothing in this family's code, or in building it,
+contacted the live box, and nothing about it may reconfigure one. (The vendor
+version pin below WAS confirmed against the live box once, read-only, during
+review — see "Vendor version" below; that probe used neither this family's
+code nor this SDK's generated client.)
+
+## Vendor version — measured 2026-09-24
+
+`@homeflare/distilled-opnsense`'s own README carries its generation pin:
+`opnsense/core`/`opnsense/plugins` tag `26.7.2`. That pin used to be an
+**inference** from a captured package list, never measured live (SSH to the
+edge is forbidden by house policy — a failed probe gets the caller's IP
+CrowdSec-banned). This PR's review measured it instead (Probe 14, 2026-09-24),
+live and read-only, over the HTTPS API only — no SSH:
+
+- `firmware-info` returned `200` with `product_version=26.7.2_2`.
+- `alias-search` returned `200` (keys: `current`, `rowCount`, `rows`, `total`).
+
+So the pin is now **measured**, not inferred: the live edge runs `26.7.2_2`,
+one patch ahead of the `26.7.2` tag the model/controller shape was generated
+from — the same series the "patch releases rarely change shape" reasoning
+already relied on, now confirmed rather than assumed. `alias-search`'s 200
+also confirms the live box's Firewall Alias API answers in the shape this SDK
+expects, even though this family reads through `get()`, not `search*` (below).
+
+## Resource set, and why these three
+
+The SDK covers 8 controllers / 83 operations (Firewall Alias/Category/Group/Filter,
+Routing Gateways, and the `os-frr` plugin's Quagga/BGP). This first import pass
+picks the three whose SDK module exports BOTH a `get()` (the whole model, keyed by
+uuid) and a `search<Item>` operation (a paginated list, OPNsense's own POST-shaped
+read) — genuine "list and get" configuration objects, not runtime state:
+
+- **Built**: `firewall_alias`, `firewall_category`, `firewall_group` (interface
+  groups, not permission groups).
+- **Skipped, and why**:
+  - `firewall_filter` (rules) and `routing_settings` (gateways) export `get()` but
+    no `search*` — no distinct list operation, so they miss this pass's own bar.
+    Rules are also the most consequential, highest-churn object in the model;
+    deferred to its own pass rather than folded in here.
+  - `quagga_general` is a global settings singleton, not a collection of items —
+    no uuid, nothing to adopt "by id".
+  - `quagga_bgp` mixes several item types (aspath, communitylist, neighbor,
+    peergroup, prefixlist, redistribution, routemap) with no `search*` for any of
+    them — deferred as a unit rather than picking one sub-type arbitrarily.
+  - `quagga_service` is pure runtime control (start/stop/restart/status) — the
+    task's own "not runtime state" exclusion, textbook case.
+
+## Why `get()`, never `getItem`/`searchItem`, for the three that shipped
+
+`get()` returns the WHOLE model tree in one GET —
+`{ alias: { aliases: { alias: { <uuid>: AliasItem, ... } } } }` for Alias, and the
+equivalent nesting for Category/Group (see each resource file's header for the
+exact path). Finding one item by uuid is then an object-key lookup, never an
+ambiguous request.
+
+That sidesteps two real gaps MEASURED in this early SDK, not a stylistic choice:
+
+1. **`firewall_alias` has no per-item get at all** — only `get` (whole model) and
+   `searchAlias` (paginated) exist.
+2. **`firewall_category`/`firewall_group` DO export `getCategory`/`getGroup`**,
+   but their generated request schema carries no `uuid` path parameter at all
+   (`GetCategoryRequest`/`GetGroupRequest` are both `S.Struct({})` against a `uri`
+   with no `{uuid}` placeholder) — a generation gap in this SDK, not a design
+   choice. Filed as an SDK gap below rather than worked around with a raw path.
+
+`searchAlias`/`searchCategory`/`searchGroup` were also passed over for `list()`
+building (they stay unused) because their generated request schema exposes no
+typed limit/offset/searchPhrase at all — a large object set could silently
+page-truncate through a naive use of them, where `get()` has no pagination to
+fall short of.
+
+## The policy: reconcile and delete always refuse
+
+Tim, 2026-09-24: UniFi and OPNsense are read-only for now. `policy.ts`'s
+`OpnsenseWriteRefused` is the ONLY error `reconcile`/`delete` can raise on any of
+the three resources — neither handler imports an `add`/`set`/`del`/`toggle`
+operation from the SDK. `reconcile` still observes with one `get()` first, so the
+refusal can say whether it would have created or updated; `delete` observes
+nothing and refuses unconditionally. `write-refusal.test.ts` proves it with a fake
+HTTP client that fails the test itself on any non-GET request, exercised through
+the exact `handlers` object each resource's `Provider` wraps — not a lower-level
+seam a real provider bypasses.
+
+Lifting this is a kit change (edit `policy.ts`, write the create/update/delete
+bodies these resources do not have), never a prop. There is no `allowWrite` flag.
+
+## Adopt is `adopt(true)`, not silent (S7, S8, H1)
+
+None of Alias, Category or Group carries an ownership marker OPNsense itself
+understands. Following upstream's `Snippet.ts` reference for a marker-less API
+(the same posture `../discord` documents, not NetBox's silent-adopt gap): a cold
+read (no persisted `output`) that finds a live object at the declared uuid
+returns `Unowned(attrs)`, so declaring it fails `OwnedBySomeoneElse` **unless**
+`adopt(true)` is set. Each resource's convenience constructor
+(`firewallAlias`/`firewallCategory`/`firewallGroup`) pipes `adopt(true)` on by
+default (H5).
+
+## The declaration renderer
+
+`aliasPropsFromLive`/`categoryPropsFromLive`/`groupPropsFromLive` (the barrel's
+names for each resource file's `propsFromLive`, itself the same function as
+`attributesOf` — see each `*-form.ts`'s header) are pure: given the uuid `get()`'s
+map key names and the item decoded at that key, they return exactly the props a
+declaration needs so `matches` reports noop against it. A future import script
+iterates `Object.entries(map)` from one `get()` call and calls the matching
+renderer once per row to generate an `alchemy.run.ts` row — no such script ships
+in this change.
+
+## Credentials
+
+`OPNSENSE_URL` / `OPNSENSE_API_KEY` / `OPNSENSE_API_SECRET`, read **at call time**
+via `@distilled.cloud/opnsense/Credentials`'s own `CredentialsFromEnv` (Basic
+auth, the vendor's own scheme), re-exported from `credentials.ts` rather than
+re-implemented. No OpenBao mint yet (H8's target is unreleased); a deploy process
+exports the three variables itself today. This package never reads, logs or
+mints them.
+
+The only key that exists today is a **ROOT API key** — not scoped to Firewall
+Alias/Category/Group, or to read-only. That is one more reason "The policy"
+above refuses every write unconditionally rather than trusting a props-level
+flag: any write path this key could reach would carry root's full blast
+radius on the estate's edge firewall, not just these three object types.
+
+## SDK gaps
+
+- 🔴 **`getCategory`/`getGroup`'s missing `uuid` path parameter** (above) — a
+  distilled generation gap, not exercised by this family, worth fixing upstream
+  in the distilled clone before a later pass tries to use either operation.
+- **No vendor constraint table**, unlike NetBox/Paperless — this pass did not
+  walk `vendor-schema` for OPNsense's field limits (e.g. `CategoryItem.color`'s
+  `/^[0-9a-fA-F]{6}$/` pattern); a malformed declaration would only be caught if
+  writes were ever lifted, not at plan time.
+- **`password`/`username`/`authtype`/`expire`** (the URL-fetch alias credential
+  fields) and **`path_expression`** (`urljson`-only) are left off `AliasProps`
+  entirely — S25 for the first four, narrow scope for the fifth. See
+  `alias-form.ts`'s header.
+- **No live lifecycle test** (H12): tests run against `fake-opnsense.ts`, a
+  loopback fake, not the real edge. This task had no credentials and was told
+  not to look for any.

package/docs/provider-standard.md

@@ -124,7 +124,7 @@ The files currently on the wrong side of the line are listed in
 | `caddy`             | Caddy 2.11.4                           | source comments only ⚠️           |
 | `forgejo`           | Forgejo 16.0.3                         | source comments only ⚠️           |
 | `talos`             | Talos v1.13 docs (never measured live) | source comments only ⚠️           |
-| `launchd` / `linux` | macOS 27 / systemd 257                 | source comments only ⚠️           |
+| `launchd` / `linux` | macOS 27 / systemd 257 / Podman 5.4.2  | source comments only ⚠️           |
 
 ⚠️ These rows record a version only in prose, so no test catches a drift. `schemas/manifest.json`
 also repeats the PVE, PBS and UniFi entries, which means there are two manifests for one

package/docs/quadlet-container.md

@@ -0,0 +1,132 @@
+# `Podman.Container` — `@homeflare/alchemy/linux`
+
+Status: active
+Verified: 2026-09-24
+
+One Podman [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
+`.container` file, declared, plus the systemd unit Podman's own generator
+turns it into — the container half of [linux-host.md](./linux-host.md)'s
+`Systemd.Unit` family, over the same `HostRunner` seam.
+
+★ **Why not `Docker.Container`.** Upstream Alchemy's resource was measured and
+rejected for three reasons: no host-network prop (every container CT100 runs
+uses `--network host`), `environment` puts `Redacted` secrets in Alchemy state,
+and systemd already supervises the containers this stack declares. Quadlet
+sidesteps all three: `Network=host` is a real value, `Environment=` is refused
+if it looks like a secret (below), and the GENERATED unit is what systemd
+supervises — this resource only ever declares the `.container` file that
+produces it.
+
+## Keys checked against the doc, not invented
+
+Every `[Container]` key below is checked against `podman-systemd.unit(5)`,
+**Podman 5.4** (`containers/podman` tag `v5.4.0`,
+`docs/source/markdown/podman-systemd.unit.5.md`, read 2026-09-24) — CT100 runs
+Podman 5.4.2 (`podman --version`, measured over `ssh ct100`, read-only,
+2026-09-24). `[Container]` is typed, unlike `Systemd.Unit`'s freeform
+`sections`, because Quadlet's own schema — unlike bare `systemd.unit(5)` — IS
+one vendor's documented, versioned surface. Adding a key later means checking
+it against the same doc and adding a field; there is no raw `[Container]`
+escape hatch, on purpose (see secrets, below).
+
+```ts
+PodmanContainer('grafana-primary', {
+  name: 'grafana-primary',
+  container: {
+    containerName: 'grafana-primary',
+    environmentFile: ['/etc/grafana-primary/env'],
+    image: 'docker.io/grafana/grafana:12.2.1',
+    network: 'host',
+    volume: ['grafana-primary-data:/var/lib/grafana'],
+  },
+  install: { wantedBy: ['multi-user.target'] },
+  service: { restart: 'always', restartSec: '5s' },
+});
+```
+
+Supported `[Container]` keys: `Image`, `ContainerName`, `Network` (supports
+`'host'`), `Volume` (repeatable), `EnvironmentFile` (repeatable), `Environment`
+(repeatable `KEY=VALUE`, never a secret), `PublishPort` (repeatable, refused
+together with `network: 'host'`), `Exec`, `User`, `AutoUpdate`
+(`'registry' | 'local'`), `PodmanArgs` (repeatable). `[Unit]`
+(`Description`/`Documentation` typed, everything else verbatim lines — same
+approach `Systemd.Unit` uses for the whole file, because these three sections
+stay systemd's own directive set even inside a `.container` file), `[Service]`
+(`Restart`/`RestartSec` typed, everything else verbatim), and `[Install]`
+(`WantedBy`/`RequiredBy`/`Alias` — the only three keys Quadlet honours for a
+`.container` file; NOT `Also`, which plain `systemd.unit(5)` allows).
+
+## Secrets: `EnvironmentFile=`, never `Environment=`
+
+⛔ **A secret belongs in a host path an out-of-band renderer maintains**
+(openbao-agent), named in `container.environmentFile` — never in
+`container.environment`, which is rendered into a 0644 file and stored
+unencrypted in Alchemy state, the same two reasons `Systemd.Unit`'s `content`
+is never secret.
+
+⚠️ **The refusal is best-effort, not a scanner** — `container-secrets.ts`. It
+refuses an `Environment=` key whose NAME says what it holds (`SECRET`,
+`TOKEN`, `PASSWORD`, `API_KEY`, …) and a handful of value shapes real vendor
+tokens take (`Bearer `, `ghp_`, `AKIA`, a JWT's `eyJ`, …). It cannot prove a
+value is safe, only refuse the obvious mistake — `container-secrets.test.ts`
+proves the refusal fires before any write, and that the renderer itself has no
+independent filter (validation is the only backstop, which is why every write
+path calls it first).
+
+## Lifecycle — where it differs from `Systemd.Unit`
+
+Order is **write, `daemon-reload`, VERIFY the generator, then start or restart
+the generated `<name>.service` only for a real change** — see
+`container-lifecycle.ts` and `container-generator.ts` for the full reasoning,
+each doc-cited. In brief:
+
+- ⛔ **The generated unit is never `systemctl enable`d.** MEASURED on CT100,
+  2026-09-24: `caddy.container` declares `[Install] WantedBy=multi-user.target`
+  and nothing ever ran `systemctl enable caddy`; `systemctl is-enabled
+caddy.service` prints `generated`, and
+  `/run/systemd/generator/multi-user.target.wants/caddy.service` is a symlink
+  the GENERATOR put there — doc-confirmed (`podman-systemd.unit(5)`): a
+  generated unit is transient, and `systemctl enable` "does not work" on one;
+  Quadlet applies `[Install]` itself, at every `daemon-reload`. So there is no
+  `enabled` prop: declaring `install.wantedBy` **is** the enablement.
+- ⛔ **A generator failure is a typed `QuadletGeneratorError`, never "absent".**
+  `systemd.generator(7)` (tag `v257`): `daemon-reload` deletes ALL generator
+  output and reruns every generator from the files on disk NOW. So a
+  `.container` file Quadlet refuses has no generated unit at all — even one
+  that generated fine a moment ago. An UPDATE that fails verification
+  therefore restores the LAST-KNOWN-GOOD file and reloads again, rather than
+  leaving the bad file for the next deploy to retry (`Systemd.Unit`'s own
+  choice, unit-lifecycle.ts): here "the next deploy" might be a reboot, and by
+  then the container this resource already promised running has no unit at
+  all. A CREATE that fails removes the file it wrote, same as `Systemd.Unit`.
+- ⚠️ **The one open question.** Whether an ALREADY-ACTIVE unit's `LoadState`
+  stays `loaded` through a failed regeneration (systemd need not
+  garbage-collect a referenced unit) was not measured — doing so needs writing
+  a broken file to a live host, which read-only access forbids. If it does,
+  `LoadState`/`SourcePath` alone would not catch a failed update to a
+  container that was already running; the restore-last-known-good step does
+  not depend on catching it, since it always leaves the host at a file known
+  to generate.
+- `SourcePath` (added to `systemctl.ts`'s `SHOW_PROPERTIES`, additive for
+  `Systemd.Unit`) ties the generated unit back to the `.container` file —
+  MEASURED on CT100: `SourcePath=/etc/containers/systemd/caddy.container`. A
+  mismatch means a same-named file earlier in Quadlet's search path is
+  generating the unit instead of ours — a takeover, not a success.
+- Directory allowlist is Quadlet's OWN rootful search path (doc, "Podman Unit
+  Search Path"): `/run/containers/systemd`, `/etc/containers/systemd`,
+  `/usr/share/containers/systemd` — CT100's `caddy.container` lives in the
+  middle one.
+- Adopt, restart-on-change, delete (stop, remove the file, reload — no
+  `disable`, since it was never enabled through systemctl) and the rename
+  (delete-first replace) contract are otherwise identical to `Systemd.Unit`'s
+  — see [linux-host.md](./linux-host.md).
+
+## The CT100 fixture
+
+`container-fixture.test.ts` renders the same directives as CT100's live
+`caddy.container` (read read-only over `ssh ct100`, 2026-09-24) and checks
+every line matches. Not byte-for-byte: CT100's file interleaves long prose
+comments between directives, and a typed `[Container]` has nowhere to attach
+"this comment goes between these two keys" — the same limit `Systemd.Unit`'s
+`renderUnit` has for the identical reason. The test proves directive parity;
+the file explains why byte parity is not the right bar for a typed resource.

package/docs/unifi.md

@@ -0,0 +1,93 @@
+# UniFi Network — `@homeflare/alchemy/unifi`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** `Unifi.Network` and `Unifi.FirewallZone` read and
+adopt; neither has a create, an update body or a working delete. `reconcile`/`delete` both fail
+with a typed `UnifiWriteRefused` naming the policy rather than calling any SDK write operation.
+Lifting the rule is a kit change — a PR that adds a write path, reviewed as one — not a flag a
+stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
+
+## What's declared, and why these two first
+
+`Unifi.Network` (`getNetworkDetails`/`getNetworksOverviewPage`) and `Unifi.FirewallZone`
+(`getFirewallZone`/`getFirewallZones`) — both list+get pairs over genuine, stable configuration,
+not runtime state (a connected client, a device statistic, a hotspot voucher, a switch stack).
+`Site` was the SDK README's other first suggestion; it has no `getSite`, only the list operation,
+so it fails this house's own "both a list and a get" bar for a first import. `FirewallPolicy` is
+also a list+get config object, but its `source`/`destination`/`ipProtocolScope` fields carry
+several of the vendor's converter-flattened discriminator variants each, and its ordering
+endpoint replaces the whole rule list — modelling that correctly is a bigger, separate PR.
+
+## Credentials
+
+Two environment variables, read **at call time**, never props — the SDK's own
+`CredentialsFromEnv` (`@distilled.cloud/unifi-network/Credentials`):
+
+| variable                     | holds                                               |
+| ---------------------------- | --------------------------------------------------- |
+| `UNIFI_NETWORK_API_KEY`      | an Integrations → API Key from the console's own UI |
+| `UNIFI_NETWORK_API_BASE_URL` | the console's integration API root — see below      |
+
+⛔ **Neither has a default**, and neither is ever logged, committed or persisted in state.
+
+⛔ **No console identifier, endpoint host or other live value ever appears in code, tests,
+fixtures, commits or a PR.** The base URL shape depends on how the console is reached: a cloud
+connector's is `https://api.ui.com/v1/connector/consoles/<consoleId>/proxy/network/integration`
+(`<consoleId>` is an account identifier); a local console is reached directly,
+`<endpoint>/proxy/network/integration`, where `<endpoint>` is a hostname behind a TLS certificate
+the caller trusts. Treat any UniFi base URL as sensitive; this package's tests use only the RFC
+2606 placeholder `https://unifi.example.com`.
+
+The estate's own credential lives in OpenBao at `kv/infra/unifi/api` — fields `api_key`,
+`connector_id`, `console`, `endpoint`, `site`, `transport` (`transport=local`: this console is
+reached directly, not through the cloud connector). A separate `kv/infra/unifi/site-manager`
+token is the _cloud_ Site Manager API credential, a different door (below) this family never
+reads.
+
+✅ **Auth was measured live, read-only, on 2026-09-24.** The OpenAPI document declares no
+`securitySchemes` at all — `X-API-KEY` comes from Ubiquiti's own Integration API guide, not the
+machine-readable spec (`@distilled.cloud/unifi-network/src/credentials.ts`'s own header) — but a
+hand-run, read-only probe confirmed it works against the estate's local console: `X-API-KEY`
+returns HTTP 200 on both `GET /v1/info` (key: `applicationVersion`) and `GET /v1/sites` (keys:
+`count`, `data`, `limit`, `offset`, `totalCount`). The _same_ key against the `api.ui.com` cloud
+connector returns 401 — the wrong door for a key minted on a local console, not evidence the
+cloud shape rejects `X-API-KEY` outright; `kv/infra/unifi/site-manager` is the separate cloud
+credential, untouched by this family. Only reads were probed, by hand, outside this package's own
+test suite — nothing in this PR's code exercises the vendor API live, and a write path would still
+need its own verification.
+
+## Adopt is the default posture, and it never writes
+
+`adopt(true)` is piped onto every resource by its convenience constructor (`network(...)`,
+`firewallZone(...)`) — H5. A cold read of a live match answers `Unowned(attrs)` (H1, the
+`Cloudflare/Snippets/Snippet.ts` reference every marker-less family here follows: UniFi Network
+objects carry no tag or metadata field this stack could stamp), and `adopt(true)` turns that into
+a silent bind instead of an `OwnedBySomeoneElse` refusal — the deploy never needs `--adopt`.
+
+⚠️ **A forced post-adoption reconcile still runs once (H6), and it still makes no write.**
+Beta.79 forces one `reconcile` call after every cold adoption whether or not `diff` said noop.
+`resource.ts`'s `reconcile` handles this the same way `discord/resource.ts` does: it reads the
+live object again and only refuses when it is missing (would need a create) or drifted (would
+need a write); an exact match returns the live attributes and calls nothing.
+
+## `list` answers `[]`
+
+`GET /v1/sites/{siteId}/networks` answers every network on the site. Adoption stays explicit —
+the same reasoning `Proxmox.User`'s and NetBox's own `list` give.
+
+## The declaration renderer
+
+`declareNetwork(live, siteId)` and `declareFirewallZone(live, siteId)` are pure functions: given
+one `getNetworkDetails`/`getFirewallZone` response, they return the `Props` a declaration needs
+so its plan is a no-op. A later import script reads every object on a site and writes one
+`network('<id>', declareNetwork(live, siteId))` row per result into `alchemy.run.ts` — nothing
+here performs that write; these two functions are what the script would call.
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57** (OpenAPI 3.1.0, 44 paths), via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.2.0`
+(`docs/distilled-interim.md`). Traps in the underlying API that this read-only family cannot
+trigger but a future write path must respect — whole-object `PUT`, ordering endpoints that
+replace the whole list, `removeDevice` unadopting and factory-resetting hardware — are recorded
+in the distilled package's own `README.md` and in the estate's `docs/unifi-api-notes.md`
+(outside this repo).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -100,6 +100,14 @@
       "types": "./dist/discord/index.d.ts",
       "default": "./dist/discord/index.js"
     },
+    "./unifi": {
+      "types": "./dist/unifi/index.d.ts",
+      "default": "./dist/unifi/index.js"
+    },
+    "./opnsense": {
+      "types": "./dist/opnsense/index.d.ts",
+      "default": "./dist/opnsense/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -110,9 +118,11 @@
     "@distilled.cloud/grafana": "npm:@homeflare/distilled-grafana@0.2.0",
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
+    "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
     "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0",
-    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0"
+    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0",
+    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },
   "peerDependencies": {
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",

package/src/linux/container-fixture.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Renders the SAME directives as CT100's live `caddy.container`
+ * (`/etc/containers/systemd/caddy.container`, read read-only over `ssh ct100` 2026-09-24) and checks
+ * every line against that fixture.
+ *
+ * ⚠️ NOT BYTE-FOR-BYTE, AND HERE IS EXACTLY WHY NOT. `renderContainerFile` renders a TYPED
+ *   `ContainerProps` — the whole point of this family (container-form.ts's header) — and CT100's
+ *   file interleaves long prose comments BETWEEN directives inside `[Unit]` and `[Container]`
+ *   (why host networking, the OpenBao-unreachable note, the rate-limit warning). There is nowhere
+ *   in a typed prop to attach "this comment goes between EnvironmentFile= and Environment=": the
+ *   comments are the file's OWN authored documentation, not data this resource's props carry.
+ *   `Systemd.Unit` has the identical limit for the same reason — `unit-form.ts`'s `renderUnit`
+ *   is lines-in-order with no comment slots either. So this fixture proves DIRECTIVE parity
+ *   (every key, in a stable order, with CT100's exact values) rather than text-diff parity; the
+ *   `[Unit]`/`[Service]`/`[Install]` VALUES below are copied verbatim from CT100's file, and the
+ *   `[Container]` ones from CT100's `[X-Container]` section (Quadlet 5.x renders that heading;
+ *   this family emits the pre-5.x `[Container]` spelling, both documented (podman-systemd.unit(5))).
+ */
+import { expect, test } from 'bun:test';
+import { type ContainerProps, renderContainerFile } from './container-form.ts';
+
+// ★ Copied verbatim from CT100's /etc/containers/systemd/caddy.container, 2026-09-24.
+const caddy: ContainerProps = {
+  container: {
+    containerName: 'caddy',
+    environment: { CADDY_CONFIG: '/etc/caddy/Caddyfile' },
+    environmentFile: ['/etc/caddy/cf-token.env'],
+    image: 'localhost/homeflare/caddy:2.11.4-hf1',
+    network: 'host',
+    volume: [
+      '/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
+      '/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
+      '/etc/caddy/cf-token.env:/run/cf/token.env:ro',
+      'caddy-data:/data',
+      'caddy-config:/config',
+    ],
+  },
+  install: { wantedBy: ['multi-user.target'] },
+  name: 'caddy',
+  service: { restart: 'always', restartSec: '5s' },
+  unit: {
+    description: 'HomeFlare TLS front door (Caddy, DNS-01)',
+    documentation:
+      'https://gitlab.homeflare.dev/homeflare/homeflare-config/-/tree/main/hosts/ct100/caddy',
+    lines: [
+      ['After', 'network-online.target'],
+      ['Wants', 'network-online.target'],
+      ['After', 'caddy-cf-token.service'],
+      ['Wants', 'caddy-cf-token.service'],
+    ],
+  },
+};
+
+test('renders every directive CT100’s live caddy.container carries', () => {
+  const rendered = renderContainerFile(caddy);
+  const expected = [
+    '[Unit]',
+    'Description=HomeFlare TLS front door (Caddy, DNS-01)',
+    'Documentation=https://gitlab.homeflare.dev/homeflare/homeflare-config/-/tree/main/hosts/ct100/caddy',
+    'After=network-online.target',
+    'Wants=network-online.target',
+    'After=caddy-cf-token.service',
+    'Wants=caddy-cf-token.service',
+    '[Container]',
+    'Image=localhost/homeflare/caddy:2.11.4-hf1',
+    'ContainerName=caddy',
+    'Network=host',
+    'EnvironmentFile=/etc/caddy/cf-token.env',
+    'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
+    'Volume=/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
+    'Volume=/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
+    'Volume=/etc/caddy/cf-token.env:/run/cf/token.env:ro',
+    'Volume=caddy-data:/data',
+    'Volume=caddy-config:/config',
+    '[Service]',
+    'Restart=always',
+    'RestartSec=5s',
+    '[Install]',
+    'WantedBy=multi-user.target',
+  ];
+  for (const line of expected) expect(rendered).toContain(line);
+  // Every non-blank, non-header line in our render is one of the expected lines — nothing invented.
+  const ours = rendered.split('\n').filter((line) => line !== '' && !line.startsWith('['));
+  expect(ours.sort()).toEqual(expected.filter((line) => !line.startsWith('[')).sort());
+});
+
+test('no comment lines — the one documented gap, not an accident', () => {
+  // Quadlet accepts `#`/`;` comments in a .container file; renderUnit (unit-form.ts) never emits
+  // one, in this family or Systemd.Unit's. CT100's own comments live only in the file this
+  // resource would MANAGE, never in state — restating them is a future prop, not a bug here.
+  expect(renderContainerFile(caddy)).not.toMatch(/^\s*[#;]/m);
+});