@homeflare/alchemy 0.29.1 → 0.30.0

package/dist/grafana/index.js

@@ -0,0 +1,149 @@
+// src/grafana/datasource.ts
+import { Resource } from "alchemy";
+import * as Provider from "alchemy/Provider";
+import * as grafana from "@distilled.cloud/grafana";
+import * as Data from "effect/Data";
+import * as Effect2 from "effect/Effect";
+
+// src/grafana/resource.ts
+import { isResolved } from "alchemy/Diff";
+import * as Effect from "effect/Effect";
+var grafanaOperations = (spec) => {
+  const read = (props) => spec.fetchLive(props).pipe(Effect.map((live) => live === undefined ? undefined : spec.attributes(live, props)));
+  return {
+    read,
+    diff: (news, output) => Effect.gen(function* () {
+      if (output === undefined || !isResolved(news))
+        return;
+      const live = yield* read(news);
+      if (live === undefined)
+        return { action: "update" };
+      if (spec.matches(live, news))
+        return { action: "noop" };
+      return spec.update === undefined ? { action: "replace" } : { action: "update" };
+    }),
+    reconcile: (news) => Effect.gen(function* () {
+      const before = yield* spec.fetchLive(news);
+      if (before === undefined) {
+        yield* spec.create(news);
+      } else if (spec.update !== undefined) {
+        const mapped = spec.attributes(before, news);
+        if (mapped === undefined || spec.matches(mapped, news)) {} else {
+          yield* spec.update(news, before);
+        }
+      }
+      const after = yield* read(news);
+      if (after === undefined) {
+        return yield* Effect.die(new Error("grafanaOperations: the write returned no error but the object is still absent. " + "Read back rather than trusting the response status."));
+      }
+      return after;
+    }),
+    destroy: (olds) => Effect.gen(function* () {
+      const live = yield* spec.fetchLive(olds);
+      if (live === undefined)
+        return;
+      yield* spec.destroy(olds, live);
+    })
+  };
+};
+var grafanaHandlers = (spec) => {
+  const ops = grafanaOperations(spec);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }) => ops.read(olds),
+    diff: ({ news, output }) => ops.diff(news, output),
+    reconcile: ({ news }) => ops.reconcile(news),
+    delete: ({ olds }) => ops.destroy(olds)
+  };
+};
+
+// src/grafana/datasource.ts
+var GrafanaDatasource = Resource("Grafana.Datasource");
+
+class GrafanaSecretRefUnsetError extends Data.TaggedError("GrafanaSecretRefUnsetError") {
+}
+var resolveSecureJsonData = (refs) => Effect2.gen(function* () {
+  if (refs === undefined)
+    return;
+  const out = {};
+  for (const [field, envVar] of Object.entries(refs)) {
+    const raw = process.env[envVar];
+    if (raw === undefined || raw.trim() === "") {
+      return yield* Effect2.fail(new GrafanaSecretRefUnsetError({
+        message: `${envVar} is unset. Export the value of secureJsonData.${field} there — ` + "never as an Alchemy prop."
+      }));
+    }
+    out[field] = raw.trim();
+  }
+  return out;
+});
+var fields = (props) => ({
+  name: props.name,
+  type: props.type,
+  ...props.access === undefined ? {} : { access: props.access },
+  ...props.basicAuth === undefined ? {} : { basicAuth: props.basicAuth },
+  ...props.basicAuthUser === undefined ? {} : { basicAuthUser: props.basicAuthUser },
+  ...props.database === undefined ? {} : { database: props.database },
+  ...props.isDefault === undefined ? {} : { isDefault: props.isDefault },
+  ...props.jsonData === undefined ? {} : { jsonData: props.jsonData },
+  ...props.url === undefined ? {} : { url: props.url },
+  ...props.user === undefined ? {} : { user: props.user },
+  ...props.withCredentials === undefined ? {} : { withCredentials: props.withCredentials }
+});
+var spec = {
+  attributes: (live) => ({
+    access: live.access ?? "",
+    id: live.id ?? 0,
+    isDefault: live.isDefault ?? false,
+    name: live.name ?? "",
+    orgId: live.orgId ?? 0,
+    readOnly: live.readOnly ?? false,
+    type: live.type ?? "",
+    uid: live.uid ?? "",
+    url: live.url ?? "",
+    version: live.version ?? 0
+  }),
+  create: (props) => Effect2.flatMap(resolveSecureJsonData(props.secureJsonDataRefs), (secureJsonData) => grafana.addDataSource({
+    ...fields(props),
+    ...secureJsonData === undefined ? {} : { secureJsonData },
+    uid: props.uid
+  })),
+  destroy: (props) => grafana.deleteDataSourceByUID({ uid: props.uid }),
+  fetchLive: (props) => grafana.getDataSourceByUID({ uid: props.uid }).pipe(Effect2.catchTag("NotFound", () => Effect2.succeed(undefined))),
+  matches: (attributes, props) => (props.name === undefined || attributes.name === props.name) && (props.type === undefined || attributes.type === props.type) && (props.url === undefined || attributes.url === props.url) && (props.access === undefined || attributes.access === props.access) && (props.isDefault === undefined || attributes.isDefault === props.isDefault),
+  update: (props, live) => Effect2.flatMap(resolveSecureJsonData(props.secureJsonDataRefs), (secureJsonData) => grafana.updateDataSourceByUID({
+    ...fields(props),
+    ...secureJsonData === undefined ? {} : { secureJsonData },
+    ...live.version === undefined ? {} : { version: live.version },
+    uid: props.uid
+  }))
+};
+var handlers = grafanaHandlers(spec);
+var GrafanaDatasourceProvider = () => Provider.effect(GrafanaDatasource, Effect2.succeed(GrafanaDatasource.Provider.of(handlers)));
+// src/grafana/credentials.ts
+import { Credentials } from "@distilled.cloud/grafana/Credentials";
+import { ConfigError } from "@distilled.cloud/grafana/Errors";
+import * as Effect3 from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+var resolve = (target) => Effect3.sync(() => process.env[target.tokenEnv]).pipe(Effect3.flatMap((raw) => raw === undefined || raw.trim() === "" ? Effect3.fail(new ConfigError({
+  message: `${target.tokenEnv} is not set. Export the Grafana service-account token there ` + `— never as an Alchemy prop — before running a stack that declares a resource ` + `against ${target.baseUrl}.`
+})) : Effect3.succeed({
+  apiBaseUrl: target.baseUrl.replace(/\/+$/, ""),
+  token: Redacted.make(raw.trim()),
+  ...target.orgId === undefined ? {} : { orgId: target.orgId }
+})), Effect3.orDie);
+var grafanaCredentials = (target) => Layer.succeed(Credentials, resolve(target));
+// src/grafana/providers.ts
+import * as Layer2 from "effect/Layer";
+var grafanaProviders = (target) => GrafanaDatasourceProvider().pipe(Layer2.provide(grafanaCredentials(target)));
+export {
+  GrafanaDatasource,
+  GrafanaDatasourceProvider,
+  GrafanaSecretRefUnsetError,
+  grafanaCredentials,
+  grafanaProviders
+};
+
+//# debugId=DA921F3915B68A6164756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/grafana/index.js.map

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../src/grafana/datasource.ts", "../src/grafana/resource.ts", "../src/grafana/credentials.ts", "../src/grafana/providers.ts"],
+  "sourcesContent": [
+    "/**\n * `Grafana.Datasource` — one Grafana data source, keyed by `uid`.\n *\n * ★ WHY `uid` IS REQUIRED, NOT GENERATED. `getDataSourceByUID`/`updateDataSourceByUID`/\n *   `deleteDataSourceByUID` are all UID-keyed, and `getDataSources` (list) takes no filter — so\n *   locating a datasource this resource didn't create means listing the whole org and matching by\n *   name, the same ambiguity netbox/resource.ts's `soleMatch` exists to catch. Requiring `uid` up\n *   front (Grafana accepts a caller-chosen one on create — `AddDataSourceRequest.uid`) sidesteps\n *   it entirely: `read`/`reconcile`/`destroy` all key on the one field the API itself is keyed on.\n *   `teslamate-grafana`'s live datasource (provisioned from a file, not this resource) has a\n *   Grafana-generated uid; the census in the handoff script records it so a first declaration can\n *   name it explicitly.\n *\n * ⛔ `secureJsonData` (e.g. a datasource password) NEVER APPEARS AS A LITERAL PROP (S25).\n *   `secureJsonDataRefs` takes env var NAMES instead; `resolveSecureJsonData` reads them from\n *   `process.env` fresh inside `create`/`update`'s own effect, never at plan time and never\n *   returned in `attributes` — Grafana's own read API agrees: `DataSource.secureJsonFields` on a\n *   GET is a map of booleans (is-it-set), never the value.\n */\nimport { Resource } from 'alchemy';\nimport * as Provider from 'alchemy/Provider';\nimport * as grafana from '@distilled.cloud/grafana';\nimport * as Data from 'effect/Data';\nimport * as Effect from 'effect/Effect';\nimport { type GrafanaSpec, grafanaHandlers } from './resource.ts';\n\nexport interface DatasourceProps {\n  uid: string;\n  name: string;\n  /** e.g. `postgres`, `prometheus`, `influxdb` — the Grafana plugin id. */\n  type: string;\n  url?: string;\n  access?: 'proxy' | 'direct';\n  database?: string;\n  user?: string;\n  basicAuth?: boolean;\n  basicAuthUser?: string;\n  isDefault?: boolean;\n  withCredentials?: boolean;\n  jsonData?: Record<string, unknown>;\n  /** Secure field name (e.g. `password`) -> env var NAME holding its value. Never the value. */\n  secureJsonDataRefs?: Record<string, string>;\n}\n\nexport interface DatasourceAttributes {\n  uid: string;\n  id: number;\n  name: string;\n  type: string;\n  url: string;\n  access: string;\n  orgId: number;\n  isDefault: boolean;\n  readOnly: boolean;\n  version: number;\n}\n\nexport interface GrafanaDatasource extends Resource<\n  'Grafana.Datasource',\n  DatasourceProps,\n  DatasourceAttributes,\n  never\n> {}\n\nexport const GrafanaDatasource = Resource<GrafanaDatasource>('Grafana.Datasource');\n\n/** A named secure-field env var is unset — a domain refusal, not a distilled error. */\nexport class GrafanaSecretRefUnsetError extends Data.TaggedError('GrafanaSecretRefUnsetError')<{\n  readonly message: string;\n}> {}\n\n/** Reads every named env var fresh, inside the caller's effect (S24) — never at plan time. */\nconst resolveSecureJsonData = (\n  refs: Record<string, string> | undefined,\n): Effect.Effect<Record<string, string> | undefined, GrafanaSecretRefUnsetError> =>\n  Effect.gen(function* () {\n    if (refs === undefined) return undefined;\n    const out: Record<string, string> = {};\n    for (const [field, envVar] of Object.entries(refs)) {\n      const raw = process.env[envVar];\n      if (raw === undefined || raw.trim() === '') {\n        return yield* Effect.fail(\n          new GrafanaSecretRefUnsetError({\n            message:\n              `${envVar} is unset. Export the value of secureJsonData.${field} there — ` +\n              'never as an Alchemy prop.',\n          }),\n        );\n      }\n      out[field] = raw.trim();\n    }\n    return out;\n  });\n\n/** `exactOptionalPropertyTypes` means an undeclared field must be OMITTED, never sent as `undefined`. */\nconst fields = (props: DatasourceProps) => ({\n  name: props.name,\n  type: props.type,\n  ...(props.access === undefined ? {} : { access: props.access }),\n  ...(props.basicAuth === undefined ? {} : { basicAuth: props.basicAuth }),\n  ...(props.basicAuthUser === undefined ? {} : { basicAuthUser: props.basicAuthUser }),\n  ...(props.database === undefined ? {} : { database: props.database }),\n  ...(props.isDefault === undefined ? {} : { isDefault: props.isDefault }),\n  ...(props.jsonData === undefined ? {} : { jsonData: props.jsonData }),\n  ...(props.url === undefined ? {} : { url: props.url }),\n  ...(props.user === undefined ? {} : { user: props.user }),\n  ...(props.withCredentials === undefined ? {} : { withCredentials: props.withCredentials }),\n});\n\nexport const spec: GrafanaSpec<\n  DatasourceProps,\n  grafana.DataSource,\n  DatasourceAttributes,\n  | grafana.AddDataSourceError\n  | grafana.GetDataSourceByUIDError\n  | grafana.UpdateDataSourceByUIDError\n  | grafana.DeleteDataSourceByUIDError\n  | GrafanaSecretRefUnsetError\n> = {\n  attributes: (live) => ({\n    access: live.access ?? '',\n    id: live.id ?? 0,\n    isDefault: live.isDefault ?? false,\n    name: live.name ?? '',\n    orgId: live.orgId ?? 0,\n    readOnly: live.readOnly ?? false,\n    type: live.type ?? '',\n    uid: live.uid ?? '',\n    url: live.url ?? '',\n    version: live.version ?? 0,\n  }),\n  create: (props) =>\n    Effect.flatMap(resolveSecureJsonData(props.secureJsonDataRefs), (secureJsonData) =>\n      grafana.addDataSource({\n        ...fields(props),\n        ...(secureJsonData === undefined ? {} : { secureJsonData }),\n        uid: props.uid,\n      }),\n    ),\n  destroy: (props) => grafana.deleteDataSourceByUID({ uid: props.uid }),\n  fetchLive: (props) =>\n    grafana\n      .getDataSourceByUID({ uid: props.uid })\n      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),\n  /**\n   * ⛔ AN UNDECLARED FIELD IS NEITHER COMPARED NOR SENT — the same rule every family in this\n   *   estate follows. `secureJsonDataRefs` is never compared: Grafana never returns the value to\n   *   diff against, only whether a field is set (`secureJsonFields`), so this resource cannot\n   *   detect drift in a secret's value — only in whether one is configured at all.\n   */\n  matches: (attributes, props) =>\n    (props.name === undefined || attributes.name === props.name) &&\n    (props.type === undefined || attributes.type === props.type) &&\n    (props.url === undefined || attributes.url === props.url) &&\n    (props.access === undefined || attributes.access === props.access) &&\n    (props.isDefault === undefined || attributes.isDefault === props.isDefault),\n  update: (props, live) =>\n    Effect.flatMap(resolveSecureJsonData(props.secureJsonDataRefs), (secureJsonData) =>\n      grafana.updateDataSourceByUID({\n        ...fields(props),\n        ...(secureJsonData === undefined ? {} : { secureJsonData }),\n        ...(live.version === undefined ? {} : { version: live.version }),\n        uid: props.uid,\n      }),\n    ),\n};\n\nexport const handlers = grafanaHandlers(spec);\n\nexport const GrafanaDatasourceProvider = () =>\n  Provider.effect(GrafanaDatasource, Effect.succeed(GrafanaDatasource.Provider.of(handlers)));\n",
+    "/**\n * One shape for every Grafana object this family declares — mirroring `../forgejo/resource.ts`\n * and `../netbox/resource.ts` exactly, minus the credentials wrapping those two bake in.\n *\n * ★ CREDENTIALS ARE NOT PROVIDED HERE. Forgejo and NetBox each manage exactly one instance for\n *   this house, so their engines close over a hardcoded `CredentialsFromEnv`. Grafana does not —\n *   see `credentials.ts`'s note on `grafana.homeflare.dev` vs `teslamate-grafana` — so `Credentials`\n *   stays a context requirement on every handler here, and `providers.ts`'s `grafanaProviders`\n *   supplies it per target with `Layer.provide`, the same composition `litellm/providers.ts` uses.\n *\n * ⚠️ `NotFound` IS FOLDED TO \"ABSENT\" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE — the\n *   same split forgejo's and netbox's engines use. `Effect.catchTag`'s tag-literal inference needs\n *   a concrete error union to resolve `\"NotFound\"` against; a spec's `E` is only concrete at each\n *   resource file's own call site.\n */\nimport { isResolved } from 'alchemy/Diff';\nimport type { Input } from 'alchemy/Input';\nimport type { GrafanaOpContext } from '@distilled.cloud/grafana/Protocol';\nimport * as Effect from 'effect/Effect';\n\n/**\n * One Grafana object's distilled calls. `Live` is whatever the SDK decodes (a `DataSource`, …) —\n * no untyped `Record<string, unknown>`. `E` is left to each resource file to declare (the union\n * of the distilled operations it actually calls plus any domain refusal, e.g. an unset secret-ref\n * env var), so a call site's precise error union flows straight through instead of being widened\n * by hand here.\n */\nexport type GrafanaSpec<Props extends object, Live, Attributes, E> = {\n  /** Already folds the SDK's `NotFound` to `undefined` via its own `catchTag` — see the note above. */\n  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, GrafanaOpContext>;\n  readonly attributes: (live: Live, props: Props) => Attributes | undefined;\n  readonly matches: (attributes: Attributes, props: Props) => boolean;\n  readonly create: (props: Props) => Effect.Effect<unknown, E, GrafanaOpContext>;\n  readonly update?: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;\n  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;\n};\n\nexport const grafanaOperations = <Props extends object, Live, Attributes, E>(\n  spec: GrafanaSpec<Props, Live, Attributes, E>,\n) => {\n  const read = (props: Props) =>\n    spec\n      .fetchLive(props)\n      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));\n\n  return {\n    read,\n\n    diff: (news: Input<Props>, output: Attributes | undefined) =>\n      Effect.gen(function* () {\n        if (output === undefined || !isResolved(news)) return undefined;\n        const live = yield* read(news);\n        if (live === undefined) return { action: 'update' } as const;\n        if (spec.matches(live, news)) return { action: 'noop' } as const;\n        return spec.update === undefined\n          ? ({ action: 'replace' } as const)\n          : ({ action: 'update' } as const);\n      }),\n\n    /**\n     * ★ OBSERVES BEFORE IT WRITES (S9, S10) — THE WHOLE OF \"ADOPT\" FOR THIS FAMILY. A `uid` this\n     *   Grafana instance already has is bound and, when it already matches the declaration,\n     *   left alone; only a genuinely absent `uid` is created. Declaring exactly what is live\n     *   changes nothing on `reconcile`, the same posture netbox/resource.ts documents as\n     *   \"adopt is the default posture, not a flag\".\n     */\n    reconcile: (news: Props) =>\n      Effect.gen(function* () {\n        const before = yield* spec.fetchLive(news);\n        if (before === undefined) {\n          yield* spec.create(news);\n        } else if (spec.update !== undefined) {\n          const mapped = spec.attributes(before, news);\n          if (mapped === undefined || spec.matches(mapped, news)) {\n            /* adoption or already converged — no write */\n          } else {\n            yield* spec.update(news, before);\n          }\n        }\n        const after = yield* read(news);\n        if (after === undefined) {\n          return yield* Effect.die(\n            new Error(\n              'grafanaOperations: the write returned no error but the object is still absent. ' +\n                'Read back rather than trusting the response status.',\n            ),\n          );\n        }\n        return after;\n      }),\n\n    destroy: (olds: Props) =>\n      Effect.gen(function* () {\n        const live = yield* spec.fetchLive(olds);\n        if (live === undefined) return;\n        yield* spec.destroy(olds, live);\n      }),\n  };\n};\n\n/**\n * The five provider handlers for a spec'd Grafana object, wired once. `Credentials` and\n * `HttpClient.HttpClient` stay ambient context requirements — see the file header.\n *\n * ⚠️ `list` answers empty — an org's full datasource list is not a page this family sweeps for\n *   adoption; adoption stays explicit, the same reasoning forgejo's and netbox's engines give.\n */\nexport const grafanaHandlers = <Props extends object, Live, Attributes extends object, E>(\n  spec: GrafanaSpec<Props, Live, Attributes, E>,\n) => {\n  const ops = grafanaOperations(spec);\n  return {\n    list: () => Effect.succeed([]),\n    read: ({ olds }: { olds: Props }) => ops.read(olds),\n    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>\n      ops.diff(news, output),\n    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),\n    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),\n  };\n};\n",
+    "/**\n * Grafana credentials for this family — a URL plus a TOKEN REFERENCE (an env var NAME), never a\n * literal secret. Wraps `@distilled.cloud/grafana`'s own `Credentials` context directly (S23 —\n * reuse the SDK's own client rather than inventing a second one); this file only adds the house's\n * lazy, per-instance resolution on top of it.\n *\n * ★ ONE `GRAFANA_TOKEN`/`GRAFANA_URL` PAIR ISN'T ENOUGH FOR THIS HOUSE. Unlike Forgejo (one\n *   instance), the estate runs at least two Grafanas — `grafana.homeflare.dev` and\n *   `teslamate-grafana` on CT100, which the unit's own comment says has \"Own Access SaaS OIDC\n *   client, never grafana.homeflare.dev's\". The SDK's `CredentialsFromEnv` reads one fixed pair\n *   of names, so a stack declaring against more than one instance needs a target per instance —\n *   `grafanaCredentials(target)` below, parameterized the way `litellm/credentials.ts` and\n *   `proxmox/credentials.ts` already are in this kit.\n *\n * ⛔ THE TOKEN NEVER TOUCHES A PROP OR AN ATTRIBUTE (S25). `tokenEnv` is a NAME, resolved from\n *   `process.env` fresh inside the credentials effect on every request (S24) — a layer built once\n *   still re-reads the environment each time an operation runs, the same laziness\n *   `litellm/credentials.ts` and the SDK's own `forgejo`/`netbox` `CredentialsFromEnv` have.\n *\n * ⚠️ THE SDK's `Credentials` SERVICE VALUE TYPE IS `Effect.Effect<Config, never, never>` — the\n *   error channel is `never` (credentials.d.ts). A missing env var can only surface as a defect\n *   here, via `Effect.orDie`, the same trade-off `forgejo/resource.ts` and `netbox/resource.ts`\n *   already accept for their own `CredentialsFromEnv`; it is not a choice this file introduces.\n */\nimport { type Config, Credentials } from '@distilled.cloud/grafana/Credentials';\nimport { ConfigError } from '@distilled.cloud/grafana/Errors';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\nimport * as Redacted from 'effect/Redacted';\n\nexport interface GrafanaTarget {\n  /** Instance origin, e.g. `https://tesla.homeflare.dev/dash` — never `/api`; the SDK appends it. */\n  readonly baseUrl: string;\n  /** Env var NAME holding a Grafana service-account token. Never the value itself. */\n  readonly tokenEnv: string;\n  /** Selects the org a call applies to, via `X-Grafana-Org-Id`. Omit for the default org. */\n  readonly orgId?: number | string;\n}\n\nconst resolve = (target: GrafanaTarget): Effect.Effect<Config, never, never> =>\n  Effect.sync(() => process.env[target.tokenEnv]).pipe(\n    Effect.flatMap((raw) =>\n      raw === undefined || raw.trim() === ''\n        ? Effect.fail(\n            new ConfigError({\n              message:\n                `${target.tokenEnv} is not set. Export the Grafana service-account token there ` +\n                `— never as an Alchemy prop — before running a stack that declares a resource ` +\n                `against ${target.baseUrl}.`,\n            }),\n          )\n        : Effect.succeed({\n            apiBaseUrl: target.baseUrl.replace(/\\/+$/, ''),\n            token: Redacted.make(raw.trim()),\n            ...(target.orgId === undefined ? {} : { orgId: target.orgId }),\n          } satisfies Config),\n    ),\n    Effect.orDie,\n  );\n\n/** The lazy, per-instance layer `grafanaProviders(target)` composes by default. */\nexport const grafanaCredentials = (target: GrafanaTarget): Layer.Layer<Credentials> =>\n  Layer.succeed(Credentials, resolve(target));\n\nexport type { Credentials };\n",
+    "/**\n * The Grafana providers for one instance, with its credentials, as one layer for a stack.\n *\n *     Layer.mergeAll(grafanaProviders({ baseUrl: '...', tokenEnv: 'GRAFANA_TOKEN' }), …)\n *\n * ★ ONE CALL PER INSTANCE. A stack declaring resources against both `grafana.homeflare.dev` and\n *   `teslamate-grafana` composes `grafanaProviders(targetA)` and `grafanaProviders(targetB)` —\n *   each resource type's `Resource` constructor is a single global registration, so the SAME\n *   `Grafana.Datasource` type serves both; only the credential layer differs per call.\n * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime, the same as\n *   `litellmProviders`/`netboxProviders`-style families in this kit assume; a stack that already\n *   deploys anything over HTTP already has one.\n */\nimport * as Layer from 'effect/Layer';\nimport { type GrafanaTarget, grafanaCredentials } from './credentials.ts';\nimport { GrafanaDatasourceProvider } from './datasource.ts';\n\nexport const grafanaProviders = (target: GrafanaTarget) =>\n  GrafanaDatasourceProvider().pipe(Layer.provide(grafanaCredentials(target)));\n"
+  ],
+  "mappings": ";AAmBA;AACA;AACA;AACA;AACA;;;ACRA;AAGA;AAmBO,IAAM,oBAAoB,CAC/B,SACG;AAAA,EACH,MAAM,OAAO,CAAC,UACZ,KACG,UAAU,KAAK,EACf,KAAY,WAAI,CAAC,SAAU,SAAS,YAAY,YAAY,KAAK,WAAW,MAAM,KAAK,CAAE,CAAC;AAAA,EAE/F,OAAO;AAAA,IACL;AAAA,IAEA,MAAM,CAAC,MAAoB,WAClB,WAAI,UAAU,GAAG;AAAA,MACtB,IAAI,WAAW,aAAa,CAAC,WAAW,IAAI;AAAA,QAAG;AAAA,MAC/C,MAAM,OAAO,OAAO,KAAK,IAAI;AAAA,MAC7B,IAAI,SAAS;AAAA,QAAW,OAAO,EAAE,QAAQ,SAAS;AAAA,MAClD,IAAI,KAAK,QAAQ,MAAM,IAAI;AAAA,QAAG,OAAO,EAAE,QAAQ,OAAO;AAAA,MACtD,OAAO,KAAK,WAAW,YAClB,EAAE,QAAQ,UAAU,IACpB,EAAE,QAAQ,SAAS;AAAA,KACzB;AAAA,IASH,WAAW,CAAC,SACH,WAAI,UAAU,GAAG;AAAA,MACtB,MAAM,SAAS,OAAO,KAAK,UAAU,IAAI;AAAA,MACzC,IAAI,WAAW,WAAW;AAAA,QACxB,OAAO,KAAK,OAAO,IAAI;AAAA,MACzB,EAAO,SAAI,KAAK,WAAW,WAAW;AAAA,QACpC,MAAM,SAAS,KAAK,WAAW,QAAQ,IAAI;AAAA,QAC3C,IAAI,WAAW,aAAa,KAAK,QAAQ,QAAQ,IAAI,GAAG,CAExD,EAAO;AAAA,UACL,OAAO,KAAK,OAAO,MAAM,MAAM;AAAA;AAAA,MAEnC;AAAA,MACA,MAAM,QAAQ,OAAO,KAAK,IAAI;AAAA,MAC9B,IAAI,UAAU,WAAW;AAAA,QACvB,OAAO,OAAc,WACnB,IAAI,MACF,oFACE,qDACJ,CACF;AAAA,MACF;AAAA,MACA,OAAO;AAAA,KACR;AAAA,IAEH,SAAS,CAAC,SACD,WAAI,UAAU,GAAG;AAAA,MACtB,MAAM,OAAO,OAAO,KAAK,UAAU,IAAI;AAAA,MACvC,IAAI,SAAS;AAAA,QAAW;AAAA,MACxB,OAAO,KAAK,QAAQ,MAAM,IAAI;AAAA,KAC/B;AAAA,EACL;AAAA;AAUK,IAAM,kBAAkB,CAC7B,SACG;AAAA,EACH,MAAM,MAAM,kBAAkB,IAAI;AAAA,EAClC,OAAO;AAAA,IACL,MAAM,MAAa,eAAQ,CAAC,CAAC;AAAA,IAC7B,MAAM,GAAG,WAA4B,IAAI,KAAK,IAAI;AAAA,IAClD,MAAM,GAAG,MAAM,aACb,IAAI,KAAK,MAAM,MAAM;AAAA,IACvB,WAAW,GAAG,WAA4B,IAAI,UAAU,IAAI;AAAA,IAC5D,QAAQ,GAAG,WAA4B,IAAI,QAAQ,IAAI;AAAA,EACzD;AAAA;;;ADtDK,IAAM,oBAAoB,SAA4B,oBAAoB;AAAA;AAG1E,MAAM,mCAAwC,iBAAY,4BAA4B,EAE1F;AAAC;AAGJ,IAAM,wBAAwB,CAC5B,SAEO,YAAI,UAAU,GAAG;AAAA,EACtB,IAAI,SAAS;AAAA,IAAW;AAAA,EACxB,MAAM,MAA8B,CAAC;AAAA,EACrC,YAAY,OAAO,WAAW,OAAO,QAAQ,IAAI,GAAG;AAAA,IAClD,MAAM,MAAM,QAAQ,IAAI;AAAA,IACxB,IAAI,QAAQ,aAAa,IAAI,KAAK,MAAM,IAAI;AAAA,MAC1C,OAAO,OAAc,aACnB,IAAI,2BAA2B;AAAA,QAC7B,SACE,GAAG,uDAAuD,mBAC1D;AAAA,MACJ,CAAC,CACH;AAAA,IACF;AAAA,IACA,IAAI,SAAS,IAAI,KAAK;AAAA,EACxB;AAAA,EACA,OAAO;AAAA,CACR;AAGH,IAAM,SAAS,CAAC,WAA4B;AAAA,EAC1C,MAAM,MAAM;AAAA,EACZ,MAAM,MAAM;AAAA,KACR,MAAM,WAAW,YAAY,CAAC,IAAI,EAAE,QAAQ,MAAM,OAAO;AAAA,KACzD,MAAM,cAAc,YAAY,CAAC,IAAI,EAAE,WAAW,MAAM,UAAU;AAAA,KAClE,MAAM,kBAAkB,YAAY,CAAC,IAAI,EAAE,eAAe,MAAM,cAAc;AAAA,KAC9E,MAAM,aAAa,YAAY,CAAC,IAAI,EAAE,UAAU,MAAM,SAAS;AAAA,KAC/D,MAAM,cAAc,YAAY,CAAC,IAAI,EAAE,WAAW,MAAM,UAAU;AAAA,KAClE,MAAM,aAAa,YAAY,CAAC,IAAI,EAAE,UAAU,MAAM,SAAS;AAAA,KAC/D,MAAM,QAAQ,YAAY,CAAC,IAAI,EAAE,KAAK,MAAM,IAAI;AAAA,KAChD,MAAM,SAAS,YAAY,CAAC,IAAI,EAAE,MAAM,MAAM,KAAK;AAAA,KACnD,MAAM,oBAAoB,YAAY,CAAC,IAAI,EAAE,iBAAiB,MAAM,gBAAgB;AAC1F;AAEO,IAAM,OAST;AAAA,EACF,YAAY,CAAC,UAAU;AAAA,IACrB,QAAQ,KAAK,UAAU;AAAA,IACvB,IAAI,KAAK,MAAM;AAAA,IACf,WAAW,KAAK,aAAa;AAAA,IAC7B,MAAM,KAAK,QAAQ;AAAA,IACnB,OAAO,KAAK,SAAS;AAAA,IACrB,UAAU,KAAK,YAAY;AAAA,IAC3B,MAAM,KAAK,QAAQ;AAAA,IACnB,KAAK,KAAK,OAAO;AAAA,IACjB,KAAK,KAAK,OAAO;AAAA,IACjB,SAAS,KAAK,WAAW;AAAA,EAC3B;AAAA,EACA,QAAQ,CAAC,UACA,gBAAQ,sBAAsB,MAAM,kBAAkB,GAAG,CAAC,mBACvD,sBAAc;AAAA,OACjB,OAAO,KAAK;AAAA,OACX,mBAAmB,YAAY,CAAC,IAAI,EAAE,eAAe;AAAA,IACzD,KAAK,MAAM;AAAA,EACb,CAAC,CACH;AAAA,EACF,SAAS,CAAC,UAAkB,8BAAsB,EAAE,KAAK,MAAM,IAAI,CAAC;AAAA,EACpE,WAAW,CAAC,UAEP,2BAAmB,EAAE,KAAK,MAAM,IAAI,CAAC,EACrC,KAAY,iBAAS,YAAY,MAAa,gBAAQ,SAAS,CAAC,CAAC;AAAA,EAOtE,SAAS,CAAC,YAAY,WACnB,MAAM,SAAS,aAAa,WAAW,SAAS,MAAM,UACtD,MAAM,SAAS,aAAa,WAAW,SAAS,MAAM,UACtD,MAAM,QAAQ,aAAa,WAAW,QAAQ,MAAM,SACpD,MAAM,WAAW,aAAa,WAAW,WAAW,MAAM,YAC1D,MAAM,cAAc,aAAa,WAAW,cAAc,MAAM;AAAA,EACnE,QAAQ,CAAC,OAAO,SACP,gBAAQ,sBAAsB,MAAM,kBAAkB,GAAG,CAAC,mBACvD,8BAAsB;AAAA,OACzB,OAAO,KAAK;AAAA,OACX,mBAAmB,YAAY,CAAC,IAAI,EAAE,eAAe;AAAA,OACrD,KAAK,YAAY,YAAY,CAAC,IAAI,EAAE,SAAS,KAAK,QAAQ;AAAA,IAC9D,KAAK,MAAM;AAAA,EACb,CAAC,CACH;AACJ;AAEO,IAAM,WAAW,gBAAgB,IAAI;AAErC,IAAM,4BAA4B,MAC9B,gBAAO,mBAA0B,gBAAQ,kBAAkB,SAAS,GAAG,QAAQ,CAAC,CAAC;;AElJ5F;AACA;AACA;AACA;AACA;AAWA,IAAM,UAAU,CAAC,WACR,aAAK,MAAM,QAAQ,IAAI,OAAO,SAAS,EAAE,KACvC,gBAAQ,CAAC,QACd,QAAQ,aAAa,IAAI,KAAK,MAAM,KACzB,aACL,IAAI,YAAY;AAAA,EACd,SACE,GAAG,OAAO,yEACV,kFACA,WAAW,OAAO;AACtB,CAAC,CACH,IACO,gBAAQ;AAAA,EACb,YAAY,OAAO,QAAQ,QAAQ,QAAQ,EAAE;AAAA,EAC7C,OAAgB,cAAK,IAAI,KAAK,CAAC;AAAA,KAC3B,OAAO,UAAU,YAAY,CAAC,IAAI,EAAE,OAAO,OAAO,MAAM;AAC9D,CAAkB,CACxB,GACO,aACT;AAGK,IAAM,qBAAqB,CAAC,WAC3B,cAAQ,aAAa,QAAQ,MAAM,CAAC;;ACjD5C;AAIO,IAAM,mBAAmB,CAAC,WAC/B,0BAA0B,EAAE,KAAW,eAAQ,mBAAmB,MAAM,CAAC,CAAC;",
+  "debugId": "DA921F3915B68A6164756E2164756E21",
+  "names": []
+}

package/dist/grafana/providers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Grafana providers for one instance, with its credentials, as one layer for a stack.
+ *
+ *     Layer.mergeAll(grafanaProviders({ baseUrl: '...', tokenEnv: 'GRAFANA_TOKEN' }), …)
+ *
+ * ★ ONE CALL PER INSTANCE. A stack declaring resources against both `grafana.homeflare.dev` and
+ *   `teslamate-grafana` composes `grafanaProviders(targetA)` and `grafanaProviders(targetB)` —
+ *   each resource type's `Resource` constructor is a single global registration, so the SAME
+ *   `Grafana.Datasource` type serves both; only the credential layer differs per call.
+ * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime, the same as
+ *   `litellmProviders`/`netboxProviders`-style families in this kit assume; a stack that already
+ *   deploys anything over HTTP already has one.
+ */
+import * as Layer from 'effect/Layer';
+import { type GrafanaTarget } from './credentials.ts';
+export declare const grafanaProviders: (target: GrafanaTarget) => Layer.Layer<import("alchemy").Provider<import("./datasource.ts").GrafanaDatasource>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=providers.d.ts.map

package/dist/grafana/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/grafana/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,kBAAkB,CAAC;AAG1E,eAAO,MAAM,gBAAgB,WAAY,aAAa,sJACuB,CAAC"}

package/dist/grafana/resource.d.ts

@@ -0,0 +1,68 @@
+import type { Input } from 'alchemy/Input';
+import type { GrafanaOpContext } from '@distilled.cloud/grafana/Protocol';
+import * as Effect from 'effect/Effect';
+/**
+ * One Grafana object's distilled calls. `Live` is whatever the SDK decodes (a `DataSource`, …) —
+ * no untyped `Record<string, unknown>`. `E` is left to each resource file to declare (the union
+ * of the distilled operations it actually calls plus any domain refusal, e.g. an unset secret-ref
+ * env var), so a call site's precise error union flows straight through instead of being widened
+ * by hand here.
+ */
+export type GrafanaSpec<Props extends object, Live, Attributes, E> = {
+    /** Already folds the SDK's `NotFound` to `undefined` via its own `catchTag` — see the note above. */
+    readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, GrafanaOpContext>;
+    readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+    readonly matches: (attributes: Attributes, props: Props) => boolean;
+    readonly create: (props: Props) => Effect.Effect<unknown, E, GrafanaOpContext>;
+    readonly update?: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;
+    readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;
+};
+export declare const grafanaOperations: <Props extends object, Live, Attributes, E>(spec: GrafanaSpec<Props, Live, Attributes, E>) => {
+    read: (props: Props) => Effect.Effect<Attributes | undefined, E, GrafanaOpContext>;
+    diff: (news: Input<Props>, output: Attributes | undefined) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | {
+        readonly action: 'replace';
+    } | undefined, E, GrafanaOpContext>;
+    /**
+     * ★ OBSERVES BEFORE IT WRITES (S9, S10) — THE WHOLE OF "ADOPT" FOR THIS FAMILY. A `uid` this
+     *   Grafana instance already has is bound and, when it already matches the declaration,
+     *   left alone; only a genuinely absent `uid` is created. Declaring exactly what is live
+     *   changes nothing on `reconcile`, the same posture netbox/resource.ts documents as
+     *   "adopt is the default posture, not a flag".
+     */
+    reconcile: (news: Props) => Effect.Effect<Attributes & ({} | null), E, GrafanaOpContext>;
+    destroy: (olds: Props) => Effect.Effect<void, E, GrafanaOpContext>;
+};
+/**
+ * The five provider handlers for a spec'd Grafana object, wired once. `Credentials` and
+ * `HttpClient.HttpClient` stay ambient context requirements — see the file header.
+ *
+ * ⚠️ `list` answers empty — an org's full datasource list is not a page this family sweeps for
+ *   adoption; adoption stays explicit, the same reasoning forgejo's and netbox's engines give.
+ */
+export declare const grafanaHandlers: <Props extends object, Live, Attributes extends object, E>(spec: GrafanaSpec<Props, Live, Attributes, E>) => {
+    list: () => Effect.Effect<never[], never, never>;
+    read: ({ olds }: {
+        olds: Props;
+    }) => Effect.Effect<Attributes | undefined, E, GrafanaOpContext>;
+    diff: ({ news, output }: {
+        news: Input<Props>;
+        output: Attributes | undefined;
+    }) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | {
+        readonly action: 'replace';
+    } | undefined, E, GrafanaOpContext>;
+    reconcile: ({ news }: {
+        news: Props;
+    }) => Effect.Effect<Attributes, E, GrafanaOpContext>;
+    delete: ({ olds }: {
+        olds: Props;
+    }) => Effect.Effect<void, E, GrafanaOpContext>;
+};
+//# sourceMappingURL=resource.d.ts.map

package/dist/grafana/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/grafana/resource.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,IAAI;IACnE,qGAAqG;IACrG,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC3F,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,UAAU,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACpE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC5F,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;CAC7F,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,QACnE,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;kBAExB,KAAK;iBAQX,KAAK,CAAC,KAAK,CAAC,UAAU,UAAU,GAAG,SAAS;yBAIZ,QAAQ;;yBACF,MAAM;;yBAEtC,SAAS;;IAI5B;;;;;;OAMG;sBACe,KAAK;oBAyBP,KAAK;CAOxB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,QAChF,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAI3C,IAAI;IACJ,IAAI,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IAChC,IAAI,qBAAqB;QAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;yBA9DlC,QAAQ;;yBACF,MAAM;;yBAEtC,SAAS;;IA6D5B,SAAS,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IACrC,MAAM,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;CAErC,CAAC"}

package/docs/caddy-fmt.md

@@ -0,0 +1,59 @@
+# Formatting a Caddyfile — `formatCaddyfile()`
+
+`caddy fmt` is a CLI-only feature (`cmd/commandfuncs.go`); nothing under `/adapt`, `/load` or any
+other admin endpoint formats a Caddyfile — measured 2026-09-24. `formatCaddyfile(text)` shells out
+to the LOCAL `caddy` binary instead — `caddy fmt -`, the text on stdin, the formatted text on
+stdout — the same formatter the CLI command runs. It never reimplements the Caddyfile grammar's
+formatting rules in TypeScript.
+
+```ts
+import * as Effect from 'effect/Effect';
+import { layer as BunServicesLayer } from '@effect/platform-bun/BunServices'; // or platform-node's
+import { formatCaddyfile } from '@homeflare/alchemy/caddy';
+
+const formatted = await Effect.runPromise(
+  formatCaddyfile(caddyfile).pipe(Effect.provide(BunServicesLayer)),
+);
+```
+
+| failure            | when                                                                               |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| `CaddyFmtNotFound` | the binary is not on `PATH` (or not executable)                                    |
+| `CaddyFmtFailed`   | it ran but exited non-zero — a syntax error in the text, most likely               |
+| `PlatformError`    | anything else the OS reported spawning it (a permission problem, a killed process) |
+
+⛔ **Never silently skipped.** A missing or failing binary always fails the Effect — there is no
+fallback path that returns the input back unformatted. Point at a specific build with
+`{ binaryPath }` (default: `DEFAULT_CADDY_BINARY`, i.e. `caddy`, resolved on `PATH`) — ideally the
+exact one the target Caddy runs, since `caddy fmt`'s own output can change between versions.
+
+Requires `ChildProcessSpawner` in scope (S19: no `node:child_process`, no `async`/`await`) —
+`@effect/platform-bun`'s or `@effect/platform-node`'s layer, or anything smaller that provides
+just that service.
+
+## Why it matters: the adapter's own warning
+
+Caddy's Caddyfile adapter warns `Caddyfile input is not formatted` on **every** unformatted input
+(`adapter.go` `FormattingDifference`) — not an edge case, the common one. That warning shares the
+`/load` response body with the refused-but-200 trap [caddy.md](./caddy.md)'s digest note and
+admin-calls.ts's module doc describe, so on its own it is easy to miss among other diagnostics.
+
+`Caddy.Config`'s plan (`diffConfig`) and deploy (`reconcile`) both pull it out of the warning list
+and log it as its own clear line naming the fix, separately from any other adapter warnings:
+
+> `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.`
+
+Before this, the warning was invisible at plan time (never logged at all) and, at deploy time,
+just one more line among the rest — easy to read past.
+
+★ **Formatting should never change the adapted JSON, so it should never cause drift.** `digest.ts`
+compares the adapted config; `caddy fmt` only changes whitespace and brace style in the Caddyfile
+TEXT, and the Caddyfile grammar treats runs of whitespace as plain token separators outside a
+quoted value, so re-flowing them should not change the token stream `/adapt` produces from it.
+⚠️ **Reasoned, not measured against a real Caddy in this repo** — this package has no caddy binary
+to adapt both forms and diff the JSON against. homeflare-mini's own "adapts with zero warnings"
+test (its own docs) is where that gets checked against a real `/adapt` call, on real rendered
+Caddyfiles. Running a declared Caddyfile through `formatCaddyfile()` before handing it to
+`CaddyConfig` silences the warning; it is not expected to ever show up as an update on the next
+plan, but that expectation rests on the grammar, not on a measurement taken here.

package/docs/caddy.md

@@ -81,6 +81,13 @@ the adapter's warnings, which the provider still reports as a refusal.
 `read` and `diff` plan a create/update with a warning (the plan-time `/adapt` did not run). The apply
 still needs Caddy, and fails loudly until it answers.
 
+## Formatting
+
+`formatCaddyfile(text)` runs the local `caddy fmt -` binary (there is no admin API for it). Plan
+and deploy both surface Caddy's own "not formatted" warning as one clear line naming the fix —
+formatting never changes the adapted JSON, so it can never cause drift. Details, the error types
+and the exact log line: [caddy-fmt.md](./caddy-fmt.md).
+
 ## Order: file, then `/load`
 
 `caddyWithFile()` passes the HostFile's `path` Output into the CaddyConfig, so Alchemy writes the

package/docs/credentials.md

@@ -45,3 +45,14 @@ the same two variable names the retired hand-rolled `credentials.ts` read (LiteL
 CLI client's variable names, not a house choice), still resolved on the calling fiber per request,
 never captured at module scope. `Authorization: Bearer <value>` is built by the package's protocol
 layer, not by this package. ⛔ The key is never a prop, for the same reason as above.
+
+The Google Workspace subpath (new 2026-09-24, on `@distilled.cloud/google-workspace`) resolves
+credentials through the SDK's own `CredentialsFromEnv`, which reads `GOOGLE_ACCESS_TOKEN` — but
+unlike NetBox/Forgejo/Paperless/LiteLLM's API-token schemes, this variable holds an OAuth2 bearer
+access token the SDK does not know how to mint: no ADC, no service-account signing, no refresh
+flow. A Bun wrapper (H8's shape, unwritten by this package) performs the domain-wide-delegation
+JWT exchange against a service-account key in OpenBao and exports the short-lived result into
+this one variable. `Authorization: Bearer <value>` is still built by the package's protocol layer.
+`GoogleWorkspaceKeyRef`/`describeKeyRef` (this subpath's own `credentials.ts`) are a typed,
+key-free REFERENCE to where that service-account key lives, for a stack file to keep alongside its
+declarations — full setup: [google-workspace.md](./google-workspace.md).

package/docs/google-workspace.md

@@ -0,0 +1,105 @@
+# Google Workspace — `@homeflare/alchemy/google-workspace`
+
+Four Admin SDK Directory objects: `Group`, `GroupMember`, `DomainAlias`, `OrgUnit`. Built on
+`@distilled.cloud/google-workspace@1.0.0-rc.12`'s `admin_directory_v1` service (S23) — every call
+is one of its typed operations, every error a `catchTag`.
+
+## Credential setup Tim needs
+
+⛔ **The distilled SDK takes one thing: an already-minted OAuth2 bearer access token.** Its
+`Credentials` service (`@distilled.cloud/google-workspace/Credentials`) has no service-account
+JSON shape and no domain-wide-delegation (DWD) JWT exchange — read at the installed package,
+2026-09-24: "API-compatible port of the distilled gcp credentials module … no ADC, no
+service-account signing, no refresh flow". Minting the token is entirely outside the SDK.
+
+★ **So this follows the house's existing pattern (H8), unchanged.** A Bun wrapper — the same
+shape the kit's Proxmox subpath already uses for its own OpenBao-sourced token — mints a
+short-lived token and exports it into the DEPLOY PROCESS's environment only:
+
+| variable              | holds                                                                |
+| --------------------- | -------------------------------------------------------------------- |
+| `GOOGLE_ACCESS_TOKEN` | a short-lived OAuth2 bearer token, delegated to a Workspace admin    |
+| `GOOGLE_PROJECT_ID`   | optional — only if a future resource needs to scope to a GCP project |
+
+This package does not write that wrapper. `credentials.ts` exports `GoogleWorkspaceKeyRef` — a
+typed REFERENCE (an OpenBao path, the delegated admin, the scopes) a stack file can keep next to
+its declarations for review, and `describeKeyRef()` to render it as one line of text. Neither
+holds, reads or accepts anything shaped like a key (`credentials.test.ts` asserts the refusal).
+
+### What Tim has to set up, once
+
+1. **A service account** in a Google Cloud project linked to the Workspace account, with
+   **domain-wide delegation** enabled in the Admin console (Security → API controls →
+   Domain-wide delegation) for the service account's client ID.
+2. **The least OAuth scopes the four resources need** — grant exactly these, nothing broader:
+
+   | resource               | scope                                                     |
+   | ---------------------- | --------------------------------------------------------- |
+   | `Group`, `GroupMember` | `https://www.googleapis.com/auth/admin.directory.group`   |
+   | `DomainAlias`          | `https://www.googleapis.com/auth/admin.directory.domain`  |
+   | `OrgUnit`              | `https://www.googleapis.com/auth/admin.directory.orgunit` |
+
+   `admin.directory.group` covers group **and** member CRUD — Google does not split them further
+   without also losing group create/update. A credential that only ever manages membership (never
+   creates or edits a group) can narrow to `admin.directory.group.member` instead.
+
+3. **The service account's key** goes in OpenBao, never on disk in this repo or anywhere a stack
+   file can reach: `kv/google-workspace/service-accounts/<name>`, matching the mount/catalog
+   pattern in `~/.claude/AGENTS.md`'s Cloudflare-credential section (same "mint, never reuse"
+   posture, different vendor).
+4. **The wrapper** reads that key from OpenBao, performs the DWD JWT-bearer exchange
+   (`https://oauth2.googleapis.com/token`, `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`,
+   `sub` = the delegated admin) for a token scoped to exactly the table above, and exports it as
+   `GOOGLE_ACCESS_TOKEN` before `alchemy.run.ts` runs — never printed, never logged, never written
+   to a file. This is the one piece this PR does not build; see
+   [upstream-conformance.md](./upstream-conformance.md) for why (S23: distilled owns the SDK
+   surface, the house owns minting, and the two should not be re-blended into a second hand-rolled
+   auth flow).
+
+### Read-only credential, for the census handoff
+
+The handoff script at `scratchpad/handoffs/23-workspace-census.sh` only lists — it never writes.
+Mint it a SEPARATE, narrower credential: `admin.directory.group.readonly`,
+`admin.directory.domain.readonly`, `admin.directory.orgunit.readonly`. Do not reuse the write
+credential above for a read-only script.
+
+## Adopt is the default posture
+
+`reconcile` fetches by key (email, alias name, or org unit path) before it writes — no NetBox-style
+list-then-disambiguate, because every object here has a stable key a human would type. An
+instance that already has "Schenanigans - Admin" or "Schenanigans - Google" (the groups the
+estate's Cloudflare Access policies already name — `docs/zero-trust-access-applications.md` in
+homeflare-landscape) is BOUND, never duplicated, and `attributes` always maps the FULL live row —
+the exact-as-live half of `adopt(true)`.
+
+## Users are out of scope
+
+`GoogleWorkspace.User` is not built. `insertUsers`/`patchUsers` accept a `password` field on the
+wire — one keystroke from becoming a prop, and Alchemy persists props unencrypted. No stack in
+this estate declares a Workspace user today (measured 2026-09-24). `GroupMember.email` references
+a user without ever creating, reading or storing one.
+
+## Removal is `retain` for everything but membership
+
+`Group`, `DomainAlias` and `OrgUnit` default to `retain` — each governs something else (Access
+policies, mail routing, service visibility) that outlives the declaration removing it.
+`GroupMember` does not: adding someone back to a group is cheap and reversible, so it uses the
+engine default (`destroy`).
+
+## SDK gaps, measured 2026-09-24
+
+- **`admin_directory_v1` lives under `unstable/`, not the SDK's preferred `services/` tree**
+  (`@distilled.cloud/google-workspace/unstable/admin_directory_v1`). The package's own `index.ts`
+  says "non-preferred versions" — this is the only Directory API version distilled generates, so
+  "non-preferred" describes distilled's own service catalog, not a deprecated Google API. Nothing
+  about the operations this family calls looked incomplete or wrong; flagged here per S23/S33 so a
+  future upgrade that moves it to `services/` is a one-line import change, not a surprise.
+- **No per-operation typed error beyond the shared `NotFound | Forbidden | BadRequest | Conflict`
+  set.** A cycle in group membership, an unverified domain on `insertDomainAliases`, or a
+  reparent-with-children refusal on `deleteOrgunits` all surface as `BadRequest` with a message,
+  not a resource-specific tag. S21 says a missing tag is fixed in the SDK, never worked around in
+  the resource — none of these three cases are worked around here; they propagate as `BadRequest`
+  same as any other 400.
+- **No `updateGroupsAliases`/`patchGroupsAliases`.** Group aliases are add/list/delete only,
+  matching `DomainAlias`'s own no-update shape — not modelled as a fifth resource in this PR
+  (out of scope: the task named domain aliases, not group aliases).

package/docs/grafana.md

@@ -0,0 +1,102 @@
+# Grafana — `@homeflare/alchemy/grafana`
+
+`Grafana.Datasource` declares one Grafana data source, keyed by `uid`. Every call goes through
+`@distilled.cloud/grafana@1.0.0-rc.12`'s typed operations, `catchTag('NotFound', ...)` in place of
+any status check. Built 2026-09-24 against the live target `teslamate-grafana.service` on CT100 —
+measured version **13.1.3** (`teslamate/grafana:4.2.0`), listening on `127.0.0.1:3100`, served
+publicly at `tesla.homeflare.dev/dash/`.
+
+## The SDK gap — why only `Datasource` ships
+
+Measured 2026-09-24 against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball (its
+`lib/services/grafana.d.ts`, 4,938 lines): the package has **no create/read/update/delete
+operations for folders, dashboards, alert rules or contact points**. It covers datasources in
+full (`addDataSource`, `getDataSourceByUID`, `updateDataSourceByUID`, `deleteDataSourceByUID`,
+`getDataSources`), plus org/user/team/role/report/annotation/library-element/public-dashboard/
+snapshot management — but:
+
+- **Folders:** only `updateFolderPermissions` exists. No `createFolder`, `getFolder` or
+  `deleteFolder` — Grafana's `/api/folders` and `/api/folders/{uid}` routes are entirely absent.
+- **Dashboards:** only snapshot and public-dashboard routes exist (`createDashboardSnapshot`,
+  `getPublicDashboard`, …). No `POST /api/dashboards/db`, no `GET /api/dashboards/uid/{uid}`, no
+  `DELETE /api/dashboards/uid/{uid}` — the plain dashboard CRUD route family is absent.
+- **Alert rules:** only `routeGetAlertRuleExport`/`routeGetAlertRuleGroupExport`/
+  `routeGetAlertRulesExport` exist — export (read-only) endpoints under `/api/v1/provisioning/`.
+  No create/update/delete for `/api/v1/provisioning/alert-rules{,/{uid}}`.
+- **Contact points:** only `routeGetContactpointsExport` exists, same story — no
+  `/api/v1/provisioning/contact-points{,/{uid}}` CRUD.
+
+This is recorded in [`docs/upstream-conformance.md`](./upstream-conformance.md) rather than worked
+around. Per S23, the fix is a distilled PR (regenerate against a spec that includes these routes,
+or patch them in per S22), not a hand-rolled `HttpClient` client in this package for the missing
+pieces alone — that would put half a family through the SDK and half through a second, parallel
+client, exactly what S23 exists to prevent.
+
+`teslamate-grafana` itself is consistent with this gap being real, not merely unexploited: its one
+datasource is API-manageable and already exists; its dashboards ship baked into the
+`teslamate/grafana` image and are provisioned by the container, not by any API call; it has no
+folders, alert rules or contact points configured at all (measured over ssh, read-only, 2026-09-24).
+
+## Credentials
+
+A `GrafanaTarget` — an instance origin plus a token env var NAME, never a literal value (S25):
+
+```ts
+import { grafanaProviders } from '@homeflare/alchemy/grafana';
+
+const teslamateGrafana = grafanaProviders({
+  baseUrl: 'https://tesla.homeflare.dev/dash',
+  tokenEnv: 'TESLAMATE_GRAFANA_TOKEN',
+});
+```
+
+`tokenEnv` is read fresh from `process.env` inside each operation's own effect (S24) — a layer
+built once still re-reads the environment on every request. This house wrapper exists because,
+unlike Forgejo (one instance for this estate), Grafana is not: `grafana.homeflare.dev` and
+`teslamate-grafana` are two instances with two different tokens, and the unit file for the latter
+says explicitly it uses "Own Access SaaS OIDC client, never grafana.homeflare.dev's" — one global
+`GRAFANA_TOKEN`/`GRAFANA_URL` pair (the SDK's own `CredentialsFromEnv`) cannot address both. A
+stack declaring resources against both instances calls `grafanaProviders` twice, once per target;
+the `Grafana.Datasource` resource type itself is one global registration shared by both calls.
+
+A datasource's `secureJsonData` (e.g. its password) follows the same rule: `secureJsonDataRefs`
+takes a map of field name to env var NAME, resolved the same way, never returned in `attributes` —
+Grafana's own read API agrees, since `DataSource.secureJsonFields` on a GET is a map of booleans
+(is-it-set), never the value.
+
+## Adopt semantics
+
+`reconcile` observes before it writes (S9/S10): a `uid` the target instance already has is bound,
+and when the declaration already matches what's live, nothing is sent — no create, no update.
+Declaring exactly what's live changes nothing. This is why `uid` is a **required** prop rather than
+generated: `getDataSourceByUID`/`updateDataSourceByUID`/`deleteDataSourceByUID` are all UID-keyed,
+and `getDataSources` (list) takes no filter, so locating an object this resource didn't create
+would mean listing the whole org and matching by name — the same ambiguity
+`netbox/resource.ts`'s `soleMatch` exists to catch. Requiring `uid` up front (Grafana accepts a
+caller-chosen one on create) sidesteps it: every operation keys on the one field the API itself is
+keyed on.
+
+## Example
+
+```ts
+import { GrafanaDatasource, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource', {
+  uid: '<the live uid — see the census handoff>',
+  name: 'TeslaMate',
+  type: 'postgres',
+  access: 'proxy',
+  isDefault: true,
+}) {}
+```
+
+```ts
+// …then provide `grafanaProviders({ baseUrl, tokenEnv })` alongside the stack's other providers.
+```
+
+## Not covered
+
+- **Folders, dashboards, alert rules, contact points.** Blocked on the SDK gap above — a
+  maintainer decision on whether to patch distilled or wait for upstream to add the routes.
+- **`read` never answers `Unowned`** — the same open gap forgejo's and netbox's own families
+  still carry (see upstream-conformance.md); a maintainer decision on the ownership-check shape.

package/docs/peers.md

@@ -54,6 +54,15 @@ enforces it. `@effect/sql-pg` is optional on `alchemy`'s own manifest (its modul
 does not reach `SQL/Postgres` unless a stack imports it); here it stays a plain peer like
 every other one.
 
+⚠️ **`@distilled.cloud/grafana` (added 2026-09-24, kit PR 222, ahead of `/grafana`) is
+required for the same reason `@distilled.cloud/forgejo` is: a plain dependency of this
+package, not something a hoisting installer can hide from a strict one.** Pinned to
+`1.0.0-rc.12`, the same distilled release line as every other pin on this page. Unlike
+Forgejo, this family is credential-parameterized per instance (`grafanaCredentials`/
+`grafanaProviders` take a `GrafanaTarget`, not a fixed env-var pair) — see
+[grafana.md](./grafana.md) for why one instance was never going to be enough for this
+estate. The peer itself does not change for that: it is still one package, one pin.
+
 ★ **`@distilled.cloud/netbox` (added 2026-09-23, moving `/netbox` off a hand-rolled
 `HttpClient` client the same way `/forgejo` did) is NOT on this install line, and that is
 deliberate — see [distilled-interim.md](./distilled-interim.md).** The real