@homeflare/alchemy 0.51.0 → 0.52.0

package/src/linux/container-form.ts

@@ -16,6 +16,15 @@
  *   `containerProblems` below. A container that needs a secret takes `EnvironmentFile=` pointing at
  *   a host path an out-of-band secret renderer (openbao-agent) maintains; this family never reads
  *   or renders that file's contents.
+ * ⛔ `Environment=` VALUES ARE ALWAYS QUOTED, VIA container-env-quote.ts — measured 2026-10-11:
+ *   unquoted, a spaced value splits at its first space, a quoted fragment re-parses into a bogus
+ *   variable, and an unknown C escape drops the line's assignments silently (ice2/grafana-oidc.md;
+ *   the live podman 5.4.2 generator reproduced all three). Quoting costs the PARSE nothing — the
+ *   generator reads a quoted line as exactly one assignment — and it also stops systemd expanding
+ *   `%` specifiers in values. It is NOT free at deploy: every Environment line's BYTES change, so
+ *   the first deploy after this bump rewrites the file and RESTARTS every container declaring
+ *   `environment` (all 13 on ct100; only grafana's values change meaning) — plan it as one window.
+ *   Newlines are refused, never encoded (same module).
  * ⛔ `[Install]` SUPPORTS ONLY `Alias=`/`WantedBy=`/`RequiredBy=` FOR A `.container` FILE (same doc,
  *   "Currently, only the Alias, WantedBy and RequiredBy keys are supported") — NOT `Also=`, which
  *   plain `systemd.unit(5)` allows and unit-text.ts's `INSTALL_KEYS` therefore lists. See
@@ -23,9 +32,14 @@
  */
 import { type UnitSection, configDigest, digestOf, renderUnit } from './unit-form.ts';
 import { podmanArgsProblems, secretLikeEnvironment, secretLikeLines } from './container-secrets.ts';
+import { environmentLines, environmentValueProblems } from './container-env-quote.ts';
+import { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES } from './container-paths.ts';
 
 /** ★ Reused, not redefined: same digest and `restartOn`-join contract as Systemd.Unit. */
 export { configDigest, digestOf };
+// ★ The search path lives in container-paths.ts (file-length cap) and is re-exported here so every
+//   importer and the barrel keep one import site — the API does not move.
+export { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES };
 
 export type UnitLine = readonly [key: string, value: string];
 
@@ -64,7 +78,8 @@ export type ContainerSection = {
 export type ContainerProps = {
   /** The Quadlet file's basename, WITHOUT `.container`. Written as `<name>.container`. */
   name: string;
-  /** @default QUADLET_DEFAULT_DIRECTORY. Must be one of QUADLET_SEARCH_DIRECTORIES (below). */
+  /** @default QUADLET_DEFAULT_DIRECTORY. Must be one of QUADLET_SEARCH_DIRECTORIES
+   *  (container-paths.ts, where the search path now lives). */
   directory?: string;
   /** `[Unit]` — `Description=`/`Documentation=` typed, everything else verbatim (see file header). */
   unit?: { description?: string; documentation?: string; lines?: readonly UnitLine[] };
@@ -103,25 +118,8 @@ export type ContainerAttributes = {
 };
 
 /**
- * Podman's OWN rootful search path, most specific first — `podman-systemd.unit(5)`, "Podman Unit
- * Search Path", Podman 5.4, read 2026-09-24: "Quadlet files for the root user can be placed in the
- * following directories ordered in precedence" (`/run` over `/etc` over `/usr/share`).
- * ★ CT100's `caddy.container` lives in the middle one — measured live, `cat` over `ssh ct100`,
- *   2026-09-24: `/etc/containers/systemd/caddy.container`.
- * ⛔ A directory outside this list is invisible to Quadlet: the generator only reads these three, so
- *   a file elsewhere is a `.container` file with no `.service` ever generated from it — silently,
- *   unlike `Systemd.Unit`'s directory check, which at least writes a unit systemd could load if only
- *   it were enabled. See `containerProblems`.
+ * ★ A conservative subset of what Quadlet itself accepts as a unit name: no template `@`, no `/`.
  */
-export const QUADLET_SEARCH_DIRECTORIES = [
-  '/run/containers/systemd',
-  '/etc/containers/systemd',
-  '/usr/share/containers/systemd',
-] as const;
-
-export const QUADLET_DEFAULT_DIRECTORY = '/etc/containers/systemd';
-
-/** ★ A conservative subset of what Quadlet itself accepts as a unit name: no template `@`, no `/`. */
 export const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 
 export const containerPathFor = (props: Pick<ContainerProps, 'name' | 'directory'>): string =>
@@ -149,13 +147,8 @@ const containerLines = (c: ContainerSection): UnitLine[] => [
   ...(c.exec === undefined ? [] : [['Exec', c.exec] as UnitLine]),
   ...(c.autoUpdate === undefined ? [] : [['AutoUpdate', c.autoUpdate] as UnitLine]),
   ...(c.environmentFile ?? []).map((file): UnitLine => ['EnvironmentFile', file]),
-  // ★ Sorted by key: a stable render for a plain object whose own key order JS does not promise.
-  ...Object.keys(c.environment ?? {})
-    .sort()
-    .map((key): UnitLine => [
-      'Environment',
-      `${key}=${(c.environment as Record<string, string>)[key]}`,
-    ]),
+  // ⛔ Always quoted, via container-env-quote.ts (see this file's header) — sorted there too.
+  ...environmentLines(c.environment ?? {}),
   ...(c.volume ?? []).map((volume): UnitLine => ['Volume', volume]),
   ...(c.publishPort ?? []).map((port): UnitLine => ['PublishPort', port]),
   ...(c.podmanArgs ?? []).map((arg): UnitLine => ['PodmanArgs', arg]),
@@ -225,19 +218,30 @@ export const containerProblems = (props: ContainerProps): string[] => {
       (problem) => `container.${problem}`,
     ),
   );
+  // ⛔ Newlines in a key or value are refused before anything renders: a .container file is read
+  //   line by line, so a raw newline ends the assignment mid-value and whatever follows parses as a
+  //   NEW directive (key injection when a value comes from external config). Strings here so one
+  //   plan shows every refusal at once; the typed error stays the contract for direct renderers.
+  const envProblems = environmentValueProblems(props.container.environment ?? {});
+  found.push(...envProblems);
   // ★ Every OTHER rendered line — `Exec=`/`PodmanArgs=` and the `unit`/`service`/`install` escape
   //   hatches — checked too, so a secret cannot reach the file through a field this typed check does
   //   not otherwise inspect. `container.environment`'s OWN lines are excluded: `secretLikeEnvironment`
   //   above already checked them, with a better error message (the actual env var name).
+  //   ⛔ The sweep renders WITHOUT the environment (a newline value cannot throw here); the NUL
+  //   check is skipped when the environment could not render — the refusals above are its result.
+  const { environment: _env, ...withoutEnvironment } = props.container;
   found.push(
     ...secretLikeLines([
       ...unitLines(props),
-      ...containerLines(props.container).filter(([key]) => key !== 'Environment'),
+      // ⛔ No `Environment` filter needed: the destructure above removed the only field whose
+      //   lines would carry it, so `containerLines` here emits none — a filter would be dead code.
+      ...containerLines(withoutEnvironment),
       ...serviceLines(props),
       ...installLines(props),
     ]),
   );
-  if (renderContainerFile(props).includes('\u0000'))
+  if (envProblems.length === 0 && renderContainerFile(props).includes('\u0000'))
     found.push('the rendered .container file contains NUL');
   return found;
 };

package/src/linux/container-paths.ts

@@ -0,0 +1,21 @@
+/**
+ * Where Quadlet looks for `.container` files — split out of container-form.ts under the file-length
+ * cap, with the measured context that justifies every entry kept intact.
+ *
+ * Podman's OWN rootful search path, most specific first — `podman-systemd.unit(5)`, "Podman Unit
+ * Search Path", Podman 5.4, read 2026-09-24: "Quadlet files for the root user can be placed in the
+ * following directories ordered in precedence" (`/run` over `/etc` over `/usr/share`).
+ * ★ CT100's `caddy.container` lives in the middle one — measured live, `cat` over `ssh ct100`,
+ *   2026-09-24: `/etc/containers/systemd/caddy.container`.
+ * ⛔ A directory outside this list is invisible to Quadlet: the generator only reads these three, so
+ *   a file elsewhere is a `.container` file with no `.service` ever generated from it — silently,
+ *   unlike `Systemd.Unit`'s directory check, which at least writes a unit systemd could load if only
+ *   it were enabled. See `containerProblems`.
+ */
+export const QUADLET_SEARCH_DIRECTORIES = [
+  '/run/containers/systemd',
+  '/etc/containers/systemd',
+  '/usr/share/containers/systemd',
+] as const;
+
+export const QUADLET_DEFAULT_DIRECTORY = '/etc/containers/systemd';

package/src/unifi/network-scope.test.ts

@@ -9,6 +9,7 @@ import * as Effect from 'effect/Effect';
 import * as Exit from 'effect/Exit';
 import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
 import { type NetworkProps, spec } from './network.ts';
+import { IMMUTABLE_KEYS, REMOVABLE_KEYS, SETTABLE_KEYS } from './network-scope.ts';
 import { UnifiLiveDriftedSinceDeploy, UnifiUpdateDidNotConverge } from './policy.ts';
 import { unifiOperations } from './resource.ts';
 
@@ -71,6 +72,26 @@ const tagOf = (exit: Exit.Exit<unknown, unknown>) => {
 const puts = (fake: { seen: ReadonlyArray<{ method: string }> }) =>
   fake.seen.filter((s) => s.method === 'PUT');
 
+// ⛔ EXACT-CONTENTS PIN. The three allowlists are the whole write scope: a widened SETTABLE_KEYS or
+//   REMOVABLE_KEYS would let a whole-object PUT reach a key the controller reads "off" when omitted,
+//   and a narrowed IMMUTABLE_KEYS would let a patch move the network (`zoneId`/`vlanId`/`management`/
+//   `deviceId`) or the management LAN (`default` is refused separately, not listed here). A widening
+//   with a key no behaviour test below names would keep them all green, so each list is pinned to
+//   its EXACT contents — a mutation fails this test even when nothing else does.
+describe('the three key sets are pinned to their exact contents', () => {
+  test('SETTABLE_KEYS is exactly ipv6Configuration', () => {
+    expect([...SETTABLE_KEYS]).toEqual(['ipv6Configuration']);
+  });
+
+  test('REMOVABLE_KEYS is exactly ipv6Configuration', () => {
+    expect([...REMOVABLE_KEYS]).toEqual(['ipv6Configuration']);
+  });
+
+  test('IMMUTABLE_KEYS is exactly zoneId/vlanId/management/deviceId', () => {
+    expect([...IMMUTABLE_KEYS]).toEqual(['zoneId', 'vlanId', 'management', 'deviceId']);
+  });
+});
+
 describe('removable-field allowlist (omission would turn the block off)', () => {
   test.each([
     ['ipv4Configuration', 'ipv4Configuration'],

package/src/unifi/network.ts

@@ -1,5 +1,6 @@
 /**
- * `Unifi.Network` — one network on a UniFi Network site, READ-ONLY (`policy.ts`).
+ * `Unifi.Network` — one network on a UniFi Network site, the ONE family with a write path
+ *   (`policy.ts` lifts Tim's read-only rule for exactly this update; see `network-update.ts`).
  *
  * ★ WHY NETWORK IS IN THE FIRST IMPORT SET. `getNetworkDetails`/`getNetworksOverviewPage`
  *   (`../../distilled-unifi-network/src/services/networks.ts`) is a list+get pair over

package/src/unifi/write-op-reference.test.ts

@@ -4,8 +4,9 @@
  * what those operations are named. `resource.ts`'s engine and `policy.ts`'s refusal never call one
  * today; nothing in the TYPE SYSTEM stops a future family file from importing, say,
  * `unifi_devices.adoptDevice` and calling it directly, bypassing `unifiOperations` altogether.
- * `GetOnlyHttpClient` (`resource.ts`) is the runtime backstop if one ever did; this is the static
- * one, so the mistake is caught at test time instead of by a wire-level defect.
+ * The wire guard (`wire-guard.ts`'s `guardedHttpClient`, `GetOnlyHttpClient` = empty allow
+ * list) is the runtime backstop if one ever did; this is the static one, so the mistake is
+ * caught at test time instead of by a wire-level defect.
  *
  * ⚠️ REWRITTEN (2026-09-26, red team, IMPORTANT-2). The previous version parsed import statements
  *   structurally (namespace alias + `.op`, or a named import's LOCAL name) and missed: the SDK's