@homeflare/alchemy 0.29.1 → 0.30.0

package/docs/upstream-conformance.md

@@ -225,6 +225,29 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
 13. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
     fakes (S28, H12). Live suites need a place to run, and that is a maintainer decision.
 
+14. **`grafana/*` (added 2026-09-24) ships only `Datasource` — a real SDK gap, not scope-trimming.**
+    Measured against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball's
+    `lib/services/grafana.d.ts` (4,938 lines): the package has no create/read/update/delete
+    operations for folders (only `updateFolderPermissions` exists), plain dashboards (only
+    snapshot/public-dashboard routes exist — no `POST /dashboards/db`, no
+    `GET/DELETE /dashboards/uid/{uid}`), alert rules or contact points (both have only a
+    `routeGet*Export` read-only route under `/v1/provisioning/`, no create/update/delete). S1
+    found no upstream `Alchemy` family for any of these either. Full detail:
+    [grafana.md](./grafana.md#the-sdk-gap--why-only-datasource-ships). **Decision:** maintainer,
+    on whether the kit patches distilled (S22) or waits for upstream to add the routes — S23
+    forbids a hand-rolled `HttpClient` client for the missing pieces alone, half a family through
+    the SDK and half through a second client.
+    - ⛔ **Same open gaps as `forgejo/*` and `netbox/*` above:** `read` never answers `Unowned`
+      (H1), and credentials come from an explicit env var NAME at call time rather than an
+      `alchemy/Auth` provider (S24) — here the house's own `grafanaCredentials(target)`, not the
+      SDK's `CredentialsFromEnv`, because more than one Grafana instance exists on this estate
+      (grafana.md's own Credentials section).
+    - Measured, read-only, on `teslamate-grafana.service` (CT100, `teslamate/grafana:4.2.0`,
+      Grafana 13.1.3): one datasource (file-provisioned, not API-managed — a live example this
+      family COULD adopt), dashboards baked into the image (not API-managed either way), and no
+      folders, alert rules or contact points configured — consistent with the gap being real
+      rather than merely unexploited. No stack yet imports `@homeflare/alchemy/grafana`.
+
 ## Conforms
 
 - **`paperless/*` (`Tag`, `DocumentType`, `StoragePath`, `CustomField`)** — ✅ **S23 fixed
@@ -263,6 +286,20 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
   an Output. That fix also belongs in the engine upstream.
 - **`verify/*`** (`hf-adopt-verify`) runs Alchemy's own planner. It exists because beta.79
   labels every cold adoption as an update (H6).
+- **`google-workspace/*`** (new 2026-09-24, `Group`, `GroupMember`, `DomainAlias`, `OrgUnit`)
+  is built directly on `@distilled.cloud/google-workspace@1.0.0-rc.12`'s typed
+  `unstable/admin_directory_v1` operations from the first commit — no hand-rolled client ever
+  existed for it to migrate off (S23), so there is no `client.ts` deletion to record. Every
+  `fetchLive` is get-by-key with its own `catchTag('NotFound', …)`, the same split forgejo's and
+  netbox's engines use (resource.ts). Get-by-key rather than NetBox's list-then-disambiguate,
+  since Directory addresses every object this family models by a stable key. ⛔ **Diverges on
+  credentials, same shape as the rest of this ledger (S24):** `GOOGLE_ACCESS_TOKEN` is read at
+  call time through the SDK's own `CredentialsFromEnv` — but here the SDK provides no way to
+  MINT that token at all (no service-account/DWD support), so a Bun wrapper outside this
+  package (H8, unwritten by this PR) is load-bearing in a way NetBox's/Forgejo's simple
+  API-token env vars are not. SDK gaps (the `unstable/` service tree, no per-operation error
+  beyond the shared 4xx set, no group-alias update) and the full credential/scope setup:
+  [google-workspace.md](./google-workspace.md).
 
 ## The Bun line
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.29.1",
+  "version": "0.30.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",
@@ -84,6 +84,14 @@
       "types": "./dist/litellm/index.d.ts",
       "default": "./dist/litellm/index.js"
     },
+    "./google-workspace": {
+      "types": "./dist/google-workspace/index.d.ts",
+      "default": "./dist/google-workspace/index.js"
+    },
+    "./grafana": {
+      "types": "./dist/grafana/index.d.ts",
+      "default": "./dist/grafana/index.js"
+    },
     "./verify": {
       "types": "./dist/verify/index.d.ts",
       "default": "./dist/verify/index.js"

package/src/caddy/config-format-warning.test.ts

@@ -0,0 +1,91 @@
+/**
+ * The "Caddyfile is not formatted" warning gets its OWN clear line, at both PLAN time
+ * (config-reconcile.ts's diffConfig) and DEPLOY time (config.ts's CaddyConfigProvider reconcile)
+ * — format-warnings.ts's split, wired into both. Captured with a Logger, the house pattern for
+ * asserting on `Effect.logWarning` (proxmox/lxc-harness.ts's `collect`).
+ *
+ * format-warnings.test.ts already covers the split itself in isolation; this file is the proof
+ * that plan and deploy actually call it, so a Caddyfile nobody ran through `caddy fmt` gets the
+ * fix line — not silence, and not just the adapter's own warning buried among others.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Logger from 'effect/Logger';
+import { caddyAdminLayer } from './admin.ts';
+import { CaddyConfig, CaddyConfigProvider } from './config.ts';
+import { diffConfig } from './config-reconcile.ts';
+import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+const UNFORMATTED = `${SITE}\t`; // fake-caddy.ts: a TAB anywhere is its "not formatted" trigger
+const ids = { fqn: 'stack/caddy', id: 'caddy', instanceId: 'i-1' };
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+const setup = () => {
+  const made = fakeDefaultCaddy();
+  fake = made.caddy;
+  return made;
+};
+
+/** Runs `effect` and returns its result plus every `Effect.logWarning` line it emitted. */
+const withWarnings = async <A>(effect: Effect.Effect<A, unknown, never>) => {
+  const warnings: string[] = [];
+  const collect = Logger.make((options) => {
+    if (options.logLevel === 'Warn') warnings.push(String(options.message));
+  });
+  const value = await Effect.runPromise(effect.pipe(Effect.provide(Logger.layer([collect]))));
+  return { value, warnings };
+};
+
+describe('the formatting warning is surfaced distinctly', () => {
+  test('plan: diffConfig logs the fix line for an unformatted Caddyfile', async () => {
+    const { admin } = setup();
+    const output = { configSha256: 'stub', endpoint: admin.endpoint };
+    const { value, warnings } = await withWarnings(
+      diffConfig({ caddyfile: UNFORMATTED }, output).pipe(Effect.provide(caddyAdminLayer(admin))),
+    );
+    expect(value).toEqual({ action: 'update' });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('caddy fmt');
+    expect(warnings[0]).toContain(admin.endpoint);
+  });
+
+  test('plan: a formatted Caddyfile logs nothing', async () => {
+    const { admin } = setup();
+    const output = { configSha256: 'stub', endpoint: admin.endpoint };
+    const { warnings } = await withWarnings(
+      diffConfig({ caddyfile: SITE }, output).pipe(Effect.provide(caddyAdminLayer(admin))),
+    );
+    expect(warnings).toEqual([]);
+  });
+
+  test('deploy: the real CaddyConfigProvider logs the fix line, not the raw adapter text', async () => {
+    const { admin } = setup();
+    const program = Effect.gen(function* () {
+      const provider = yield* CaddyConfig.Provider;
+      return yield* provider.reconcile({
+        ...ids,
+        bindings: [] as never,
+        news: { caddyfile: UNFORMATTED },
+        olds: undefined,
+        output: undefined as never,
+        session: undefined as never,
+      });
+    }).pipe(
+      Effect.provide(CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(admin)))),
+      // reconcile with no state needs an adopt decision; a fresh Caddy has nothing to adopt.
+      Effect.provideService(AdoptPolicy, true),
+    );
+    const { warnings } = await withWarnings(program as Effect.Effect<unknown, unknown, never>);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('caddy fmt');
+    expect(warnings.some((w) => w.includes('Caddyfile input is not formatted'))).toBe(false);
+  });
+});

package/src/caddy/config-reconcile.ts

@@ -14,6 +14,7 @@ import { messageOf, refuse, short, wrapOperation } from './config-errors.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 import { claimable, desiredConfig, readLive } from './config-lifecycle.ts';
 import { configDigest } from './digest.ts';
+import { formattingFixLine, splitFormattingWarning } from './format-warnings.ts';
 
 /**
  * ★ NEVER `replace`. Nothing in the props names a different object: a new Caddyfile is a reload of
@@ -27,6 +28,11 @@ export const diffConfig = (
   Effect.gen(function* () {
     const { endpoint } = yield* CaddyAdminService;
     const want = yield* desiredConfig(news);
+    // ★ SURFACED AT PLAN TIME, NOT JUST DEPLOY TIME. `want.warnings` otherwise goes nowhere here —
+    //   only the formatting warning gets its own clear line; the rest keep logging at reconcile
+    //   (config.ts), same as before this change.
+    const { formatting } = splitFormattingWarning(want.warnings);
+    if (formatting.length > 0) yield* Effect.logWarning(formattingFixLine(endpoint));
     const live = yield* readLive();
     const converged =
       want.digest === live.configSha256 &&

package/src/caddy/config.ts

@@ -35,6 +35,7 @@ import { isUnreachable } from './caddy-http-client.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 import { probeLive, readLive } from './config-lifecycle.ts';
 import { diffConfig, reconcileConfig } from './config-reconcile.ts';
+import { formattingFixLine, splitFormattingWarning } from './format-warnings.ts';
 
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 
@@ -136,7 +137,13 @@ export const CaddyConfigProvider = () =>
             const takeOver = sameCaddy || (yield* adoptEnabled(fqn));
             const stored = output === undefined ? {} : { stored: output.configSha256 };
             const applied = yield* reconcileConfig(news, { takeOver, ...stored });
-            for (const warning of applied.warnings) {
+            // ★ THE FORMATTING WARNING GETS ITS OWN LINE, NAMING THE FIX — separate from the rest,
+            //   which keep logging exactly as before (format-warnings.ts).
+            const { formatting, rest } = splitFormattingWarning(applied.warnings);
+            if (formatting.length > 0) {
+              yield* Effect.logWarning(formattingFixLine(admin.endpoint));
+            }
+            for (const warning of rest) {
               yield* Effect.logWarning(`Caddy.Config at ${admin.endpoint}: ${warning}`);
             }
             return applied.attributes;

package/src/caddy/format-warnings.test.ts

@@ -0,0 +1,50 @@
+/**
+ * splitFormattingWarning() / formattingFixLine() — pure, so no fake Caddy is needed: the
+ * behavior that matters is which warning(s) get pulled out and what the fix line says.
+ */
+import { describe, expect, test } from 'bun:test';
+import { formattingFixLine, splitFormattingWarning } from './format-warnings.ts';
+
+const FORMATTING = 'Caddyfile:1: Caddyfile input is not formatted';
+const OTHER = 'Caddyfile:3: unrecognized directive: reverse_proxyy';
+
+describe('splitFormattingWarning', () => {
+  test('pulls the formatting warning out, leaving the rest untouched', () => {
+    expect(splitFormattingWarning([OTHER, FORMATTING])).toEqual({
+      formatting: [FORMATTING],
+      rest: [OTHER],
+    });
+  });
+
+  test('formatting is empty, and rest unchanged, when there is no formatting warning', () => {
+    expect(splitFormattingWarning([OTHER])).toEqual({ formatting: [], rest: [OTHER] });
+  });
+
+  test('an empty list splits into no formatting warning and no rest', () => {
+    expect(splitFormattingWarning([])).toEqual({ formatting: [], rest: [] });
+  });
+
+  test('matches by substring, so a differing file:line still counts as the formatting warning', () => {
+    const elsewhere = '/etc/Caddyfile:42: Caddyfile input is not formatted';
+    expect(splitFormattingWarning([elsewhere])).toEqual({ formatting: [elsewhere], rest: [] });
+  });
+
+  test('TWO formatting warnings (e.g. an unformatted import) both survive — neither is dropped', () => {
+    // ⛔ Regression: a `.find()` here would keep only the first AND (via `.filter()`) strip the
+    //   second out of `rest` too — silently discarding it from both branches at once.
+    const second = '/etc/Caddyfile.d/site.caddy:1: Caddyfile input is not formatted';
+    expect(splitFormattingWarning([FORMATTING, OTHER, second])).toEqual({
+      formatting: [FORMATTING, second],
+      rest: [OTHER],
+    });
+  });
+});
+
+describe('formattingFixLine', () => {
+  test('names the endpoint and both fixes, never just the adapter’s own warning text', () => {
+    const line = formattingFixLine('http://127.0.0.1:2019');
+    expect(line).toContain('http://127.0.0.1:2019');
+    expect(line).toContain('caddy fmt');
+    expect(line).toContain('formatCaddyfile()');
+  });
+});

package/src/caddy/format-warnings.ts

@@ -0,0 +1,39 @@
+/**
+ * Pulls Caddy's adapter "Caddyfile input is not formatted" warning(s) out of a warnings list, so
+ * config.ts's reconcile (deploy) and config-reconcile.ts's diffConfig (plan) can show it as one
+ * clear, actionable line instead of burying it among the rest.
+ *
+ * ★ THIS IS THE COMMON CASE, NOT AN EDGE ONE. admin-calls.ts's module doc: the Caddyfile adapter
+ *   warns on EVERY unformatted input (adapter.go FormattingDifference) — every declared Caddyfile
+ *   that was not run through `caddy fmt` (or format.ts's formatCaddyfile()) carries this warning
+ *   on every plan and every deploy, indistinguishable from the rest unless split out.
+ */
+
+/** The exact adapter message (caddyserver/caddy v2.11.4, adapter.go FormattingDifference). */
+const NOT_FORMATTED = 'Caddyfile input is not formatted';
+
+export type SplitWarnings = {
+  /**
+   * Every warning THAT IS the formatting one — usually one, but an `import`ed file can add
+   * another with its own file:line, and this keeps every one of them (never just the first): a
+   * `.find()` here would silently drop the rest, not merely leave them uncounted.
+   */
+  readonly formatting: readonly string[];
+  /** Every other warning, in order, formatting removed. */
+  readonly rest: readonly string[];
+};
+
+/** Separates the formatting warning(s) (by substring, matching admin-calls.ts's `describe()`). */
+export const splitFormattingWarning = (warnings: readonly string[]): SplitWarnings => ({
+  formatting: warnings.filter((warning) => warning.includes(NOT_FORMATTED)),
+  rest: warnings.filter((warning) => !warning.includes(NOT_FORMATTED)),
+});
+
+/**
+ * One clear line naming the fix — never just the adapter's own warning text, and never repeated
+ * per formatting warning: however many `formatting` holds, this is logged once (config.ts,
+ * config-reconcile.ts), since restating the same fix N times is its own noise.
+ */
+export const formattingFixLine = (endpoint: string): string =>
+  `Caddy.Config at ${endpoint}: Caddyfile is not formatted — run \`caddy fmt\` on it, or format ` +
+  "it with this package's formatCaddyfile() before declaring it, to silence this warning.";

package/src/caddy/format.test.ts

@@ -0,0 +1,105 @@
+/**
+ * formatCaddyfile()'s Effect wiring, proven against a fake `caddy` — a tiny shell script that
+ * "formats" by stripping trailing whitespace per line — so stdin-in/stdout-out plumbing, the
+ * exit-code check and missing-binary detection are exercised without a real Caddy on the runner.
+ * The last block runs the REAL `caddy fmt` and is skipped, its name saying why, when there is none
+ * on PATH (S42: tests are Bun-native, so `Bun.which` decides, not a hand-rolled PATH search).
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { layer as BunServicesLayer } from '@effect/platform-bun/BunServices';
+import * as Effect from 'effect/Effect';
+import { CaddyFmtFailed, CaddyFmtNotFound, formatCaddyfile } from './format.ts';
+
+/** Only understands `fmt -`: stdin in, "formatted" stdout out — `FAIL_MARKER` fakes a bad parse. */
+const FAKE_SCRIPT = `#!/bin/sh
+if [ "$1" != "fmt" ] || [ "$2" != "-" ]; then
+  echo "fake caddy: unexpected args: $*" >&2
+  exit 2
+fi
+input="$(cat)"
+case "$input" in
+  *FAIL_MARKER*)
+    echo "fake caddy: syntax error" >&2
+    exit 1
+    ;;
+esac
+printf '%s' "$input" | sed -E 's/[[:space:]]+$//'
+`;
+
+const dir = mkdtempSync(join(tmpdir(), 'hf-caddy-fmt-'));
+const fakeBinary = join(dir, 'hf-fake-caddy');
+writeFileSync(fakeBinary, FAKE_SCRIPT, { mode: 0o755 });
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const run = (text: string, options?: Parameters<typeof formatCaddyfile>[1]) =>
+  Effect.runPromise(formatCaddyfile(text, options).pipe(Effect.provide(BunServicesLayer)));
+
+const runFailure = (text: string, options?: Parameters<typeof formatCaddyfile>[1]) =>
+  Effect.runPromise(
+    formatCaddyfile(text, options).pipe(Effect.provide(BunServicesLayer), Effect.flip),
+  );
+
+describe('formatCaddyfile — Effect wiring against a fake binary', () => {
+  test('pipes text to stdin and returns the formatted stdout', async () => {
+    // ⚠️ The fake reads stdin through `$(cat)`, which — like real shell command substitution —
+    //   drops a trailing newline; that is the fake's plumbing, not formatCaddyfile()'s.
+    const out = await run('foo   \nbar\t\n', { binaryPath: fakeBinary });
+    expect(out).toBe('foo\nbar');
+  });
+
+  test('a non-zero exit becomes a typed CaddyFmtFailed, stderr included — never the input back', async () => {
+    const failure = await runFailure('site FAIL_MARKER', { binaryPath: fakeBinary });
+    expect(failure).toBeInstanceOf(CaddyFmtFailed);
+    expect((failure as CaddyFmtFailed).exitCode).toBe(1);
+    expect(failure.message).toContain('syntax error');
+  });
+
+  test('a missing binary fails with the typed CaddyFmtNotFound — never silently skipped', async () => {
+    const missing = join(dir, 'does-not-exist-caddy');
+    const failure = await runFailure('x', { binaryPath: missing });
+    expect(failure).toBeInstanceOf(CaddyFmtNotFound);
+    expect((failure as CaddyFmtNotFound).binaryPath).toBe(missing);
+    expect(failure.message).toContain(missing);
+  });
+
+  test('the default binary name resolves through PATH, not only an absolute path', async () => {
+    const pathDir = mkdtempSync(join(tmpdir(), 'hf-caddy-fmt-path-'));
+    writeFileSync(join(pathDir, 'caddy'), FAKE_SCRIPT, { mode: 0o755 });
+    const original = process.env['PATH'];
+    // ★ Prepended, so this fake wins even when a real `caddy` also sits on PATH.
+    process.env['PATH'] = `${pathDir}:${original ?? ''}`;
+    try {
+      expect(await run('baz  \n')).toBe('baz');
+    } finally {
+      process.env['PATH'] = original;
+      rmSync(pathDir, { recursive: true, force: true });
+    }
+  });
+});
+
+const realCaddy = Bun.which('caddy');
+// ⚠️ DELIBERATELY NOT `caddy fmt`'s own canonical style — no space before `{`, spaces instead of
+//   a tab, and the closing brace indented — every one of which `caddy fmt` actually rewrites, so
+//   `expect(formatted).not.toBe(UNFORMATTED)` below cannot pass by accident on already-formatted
+//   input. (Caught in review: a tab-indented, flush-brace fixture here IS canonical caddy fmt
+//   style, which would make that assertion fail on a correctly working formatCaddyfile().)
+const UNFORMATTED = 'example.com{\n    reverse_proxy 127.0.0.1:8080\n    }\n';
+
+describe('formatCaddyfile — real caddy binary', () => {
+  test.skipIf(realCaddy === null)(
+    realCaddy === null
+      ? 'formats a known-unformatted Caddyfile (skipped: no caddy on PATH)'
+      : 'formats a known-unformatted Caddyfile, and formatting twice is idempotent',
+    async () => {
+      const formatted = await run(UNFORMATTED);
+      expect(formatted).not.toBe(UNFORMATTED);
+      // ★ THE REAL PROOF IT IS FORMATTED: running caddy's own formatter over its own output changes
+      //   nothing. (Never asserted against a fixed expected string — that would pin this test to
+      //   one caddy build's exact formatting choices.)
+      expect(await run(formatted)).toBe(formatted);
+    },
+  );
+});

package/src/caddy/format.ts

@@ -0,0 +1,121 @@
+/**
+ * `formatCaddyfile(text)` — pipes a Caddyfile through the LOCAL `caddy fmt -` binary (stdin in,
+ * formatted text out), the same formatter the `caddy fmt` CLI command runs
+ * (caddyconfig/caddyfile Format in caddyserver/caddy).
+ *
+ * ⛔ THERE IS NO ADMIN API FOR THIS. `caddy fmt` is a CLI-only feature (cmd/commandfuncs.go); no
+ *   `/adapt`, `/load` or other admin endpoint formats a Caddyfile, so this never belongs in
+ *   `@distilled.cloud/caddy` — measured 2026-09-24. It shells out instead, the same pattern
+ *   talos/talosctl.ts uses for a vendor CLI Alchemy does not wrap.
+ * ⛔ NEVER REIMPLEMENTED IN TS. The Caddyfile grammar's formatting rules live in the Go adapter;
+ *   a hand-rolled formatter would drift from it silently. This module only ever runs the real
+ *   binary.
+ * ⛔ A MISSING OR FAILING BINARY FAILS THE EFFECT — IT NEVER RETURNS THE INPUT UNCHANGED.
+ *   `CaddyFmtNotFound` and `CaddyFmtFailed` are typed, catchTag-able failures (S21); there is no
+ *   fallback path that silently skips formatting.
+ * ★ WHY THIS MATTERS: admin-calls.ts's module doc — Caddy's adapter warns "Caddyfile input is not
+ *   formatted" on EVERY unformatted input (adapter.go FormattingDifference), which shares the
+ *   `/load` response body with the refused-but-200 trap. format-warnings.ts surfaces that warning
+ *   distinctly in plan/deploy output; this function is how a caller silences it — by formatting
+ *   the Caddyfile before declaring it, not by ignoring the warning.
+ */
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+import * as ChildProcess from 'effect/unstable/process/ChildProcess';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import type * as PlatformError from 'effect/PlatformError';
+
+/** `caddy` resolved on `PATH`, unless the caller points at a specific build. */
+export const DEFAULT_CADDY_BINARY = 'caddy';
+
+/** The configured binary is not on `PATH` (or not executable) — install Caddy, or fix the path. */
+export class CaddyFmtNotFound extends Error {
+  readonly _tag = 'CaddyFmtNotFound';
+  constructor(
+    readonly binaryPath: string,
+    cause: PlatformError.PlatformError,
+  ) {
+    super(
+      `formatCaddyfile: "${binaryPath}" was not found (${cause.message}). Install Caddy so it is ` +
+        'on PATH, or pass { binaryPath } naming the exact build the target Caddy runs.',
+    );
+    this.name = 'CaddyFmtNotFound';
+  }
+}
+
+/** The binary ran but exited non-zero — a syntax error in `text`, most likely. */
+export class CaddyFmtFailed extends Error {
+  readonly _tag = 'CaddyFmtFailed';
+  constructor(
+    readonly binaryPath: string,
+    readonly exitCode: number,
+    stderr: string,
+  ) {
+    super(
+      `formatCaddyfile: "${binaryPath} fmt -" exited ${String(exitCode)}: ${stderr.slice(0, 300)}`,
+    );
+    this.name = 'CaddyFmtFailed';
+  }
+}
+
+export type FormatCaddyfileOptions = {
+  /** The `caddy` binary to run `fmt -` against. @default DEFAULT_CADDY_BINARY, resolved on PATH. */
+  readonly binaryPath?: string;
+};
+
+/**
+ * Format a Caddyfile the way `caddy fmt` would, by actually running it — never a TS
+ * reimplementation. Requires `ChildProcessSpawner` (S19: no `node:child_process`, no
+ * `async`/`await`); provide `@effect/platform-node`'s or `@effect/platform-bun`'s layer.
+ */
+export const formatCaddyfile = (
+  text: string,
+  options: FormatCaddyfileOptions = {},
+): Effect.Effect<
+  string,
+  // ⚠️ A raw PlatformError still escapes for anything that is not "missing binary" (a permission
+  //   problem, a process the OS killed mid-run) — narrower than that would misname what happened.
+  CaddyFmtNotFound | CaddyFmtFailed | PlatformError.PlatformError,
+  ChildProcessSpawner.ChildProcessSpawner
+> =>
+  Effect.gen(function* () {
+    const binaryPath = options.binaryPath ?? DEFAULT_CADDY_BINARY;
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const input = new TextEncoder().encode(text);
+    const result = yield* ChildProcess.make(binaryPath, ['fmt', '-'], {
+      detached: false,
+      stderr: 'pipe',
+      stdin: Stream.make(input),
+      stdout: 'pipe',
+    }).pipe(
+      spawner.spawn,
+      Effect.flatMap((child) =>
+        Effect.all(
+          {
+            exitCode: child.exitCode,
+            stderr: child.stderr.pipe(
+              Stream.decodeText,
+              Stream.mkString,
+              Effect.map((out) => out.trim()),
+            ),
+            stdout: child.stdout.pipe(Stream.decodeText, Stream.mkString),
+          },
+          { concurrency: 'unbounded' },
+        ),
+      ),
+      Effect.scoped,
+      // ⛔ ENOENT (the binary is missing) becomes the typed, named failure above — every other
+      //   PlatformError (a permission problem, a killed process) propagates as-is, still typed.
+      Effect.catchTag(
+        'PlatformError',
+        (error): Effect.Effect<never, CaddyFmtNotFound | PlatformError.PlatformError> =>
+          error.reason._tag === 'NotFound'
+            ? Effect.fail(new CaddyFmtNotFound(binaryPath, error))
+            : Effect.fail(error),
+      ),
+    );
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(new CaddyFmtFailed(binaryPath, result.exitCode, result.stderr));
+    }
+    return result.stdout;
+  });

package/src/caddy/index.ts

@@ -24,6 +24,13 @@ export { CaddyAdminService, caddyAdminLayer } from './admin.ts';
 export { isUnreachable } from './caddy-http-client.ts';
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config.ts';
 export { CaddyConfig, CaddyConfigProvider } from './config.ts';
+export {
+  CaddyFmtFailed,
+  CaddyFmtNotFound,
+  DEFAULT_CADDY_BINARY,
+  formatCaddyfile,
+  type FormatCaddyfileOptions,
+} from './format.ts';
 export type { LocalCaddyAdminOptions } from './local-admin.ts';
 export { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin } from './local-admin.ts';
 export { caddyProviders } from './providers.ts';

package/src/caddy/providers.test.ts

@@ -224,13 +224,21 @@ describe('the barrel', () => {
       'CaddyAdminService',
       'CaddyConfig',
       'CaddyConfigProvider',
+      // The two typed failures formatCaddyfile() can raise — see format.ts.
+      'CaddyFmtFailed',
+      'CaddyFmtNotFound',
       'DEFAULT_ADMIN_ADDRESS',
+      // `caddy` resolved on PATH, unless formatCaddyfile()'s caller points at a build — format.ts.
+      'DEFAULT_CADDY_BINARY',
       // Caddyfile TEXT for an Access-protected route, not a resource — see
       // access-forward-auth.ts. It pairs with @homeflare/cloudflare/access-auth.
       'accessForwardAuth',
       'caddyAdminLayer',
       'caddyProviders',
       'caddyWithFile',
+      // `caddy fmt -`, piped through the local binary — see format.ts's module doc for why this
+      // is never a TS reimplementation and never belongs in @distilled.cloud/caddy.
+      'formatCaddyfile',
       // The type guard config.ts's plan-time escape hatch narrows unreachable failures with —
       // exported so a consumer's own transport (an SSH forward, a remote runner) can reuse it.
       'isUnreachable',

package/src/google-workspace/credentials.test.ts

@@ -0,0 +1,40 @@
+/**
+ * `describeKeyRef` — proves it formats a plain reference and refuses anything key-shaped, so the
+ * one place this family turns a `GoogleWorkspaceKeyRef` into text (docs, the census handoff
+ * header) cannot be handed a real credential by mistake.
+ */
+import { describe, expect, test } from 'bun:test';
+import { type GoogleWorkspaceKeyRef, describeKeyRef } from './credentials.ts';
+
+const REF: GoogleWorkspaceKeyRef = {
+  delegatedAdmin: 'admin@schenanigans.com',
+  openBaoPath: 'kv/google-workspace/service-accounts/directory-admin',
+  scopes: ['https://www.googleapis.com/auth/admin.directory.group.readonly'],
+};
+
+describe('describeKeyRef', () => {
+  test('formats a plain reference — path, delegated admin, scopes', () => {
+    const line = describeKeyRef(REF);
+    expect(line).toContain('kv/google-workspace/service-accounts/directory-admin');
+    expect(line).toContain('admin@schenanigans.com');
+    expect(line).toContain('admin.directory.group.readonly');
+  });
+
+  test('refuses an openBaoPath that looks like a PEM private key', () => {
+    expect(() =>
+      describeKeyRef({ ...REF, openBaoPath: '-----BEGIN PRIVATE KEY-----\nMIIE...' }),
+    ).toThrow(/looks like key material/);
+  });
+
+  test('refuses a scopes entry that looks like a service-account JSON blob', () => {
+    expect(() =>
+      describeKeyRef({ ...REF, scopes: ['{"type": "service_account", "private_key": "x"}'] }),
+    ).toThrow(/looks like key material/);
+  });
+
+  test('refuses a delegatedAdmin field carrying a private_key fragment', () => {
+    expect(() => describeKeyRef({ ...REF, delegatedAdmin: 'private_key leaked here' })).toThrow(
+      /looks like key material/,
+    );
+  });
+});