@homeflare/alchemy 0.29.1 → 0.30.0

package/src/google-workspace/resource.ts

@@ -0,0 +1,162 @@
+/**
+ * One shape for every Google Workspace Directory object — the same four operations, different
+ * distilled call.
+ *
+ * ⛔ THE ALTERNATIVE IS COPYING THE SAME HANDLERS PER RESOURCE. Groups, group members, domain
+ *   aliases and org units are all create / read / update / delete against
+ *   `@distilled.cloud/google-workspace`'s typed `admin_directory_v1` operations. Hand-rolling the
+ *   fourth copy is where someone drops the read-back or the `isResolved` guard and the plan lies.
+ *
+ * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE — mirroring `../forgejo/resource.ts`'s engine exactly.
+ *   The Directory API addresses every object this family models by a stable key (an email, a
+ *   domain alias name, an org unit path), so — unlike NetBox's page-then-disambiguate `locateOne`
+ *   — `fetchLive` is always a plain get-by-key.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE — the
+ *   same split forgejo's and netbox's engines use. `Effect.catchTag`'s tag-literal inference needs
+ *   a concrete error union to resolve `"NotFound"` against; a spec's `E` is only concrete at each
+ *   resource file's own call site.
+ *
+ * ★ ADOPT IS THE DEFAULT POSTURE, NOT A FLAG. `reconcile` LOCATES before it writes: a group or org
+ *   unit the Workspace already has is bound, not duplicated — Tim's own domain (schenanigans.com)
+ *   predates this code. `spec.attributes` always maps the FULL live object, so a bound row reads
+ *   back byte-identical to what Workspace actually holds — the exact-as-live half of `adopt(true)`;
+ *   the other half (refusing to bind without it) is upstream's `AdoptPolicy`, unchanged here.
+ *
+ * ⛔ CREDENTIALS ARE NEVER A PROP (S24/S25). See `credentials.ts` for what a stack passes instead.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/google-workspace/Credentials';
+import type { GoogleWorkspaceOpContext } from '@distilled.cloud/google-workspace/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+
+/**
+ * ★ WHAT EVERY HANDLER NEEDS FROM THE CALLER'S RUNTIME, after Credentials are provided below.
+ *   `GoogleWorkspaceOpContext` is `Credentials | HttpClient.HttpClient`; `googleWorkspaceHandlers`
+ *   closes over `CredentialsFromEnv` itself (`GOOGLE_ACCESS_TOKEN` / `GOOGLE_PROJECT_ID` — see
+ *   credentials.ts), so a consuming stack only has to provide `HttpClient.HttpClient`, the same
+ *   shape every other distilled-backed family in this kit asks for.
+ */
+export type GoogleWorkspaceRequirements = HttpClient.HttpClient;
+
+/**
+ * One Directory object's distilled calls. `Live` is whatever the SDK decodes (a `Group`, a
+ * `Member`, a `DomainAlias`, an `OrgUnit`) — never an untyped response body.
+ *
+ * `E` is left to each resource file to declare (the union of the distilled operations it
+ * actually calls), so a call site's precise per-operation error union flows straight through
+ * instead of being widened by hand here.
+ */
+export type GoogleWorkspaceSpec<Props extends object, Live, Attributes, E> = {
+  /** Already folds a real "absent" outcome — a `catchTag('NotFound', ...)` at the call site. */
+  readonly fetchLive: (
+    props: Props,
+  ) => Effect.Effect<Live | undefined, E, GoogleWorkspaceOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /** Absent for an existence-only family (none here yet, but `GroupMember` could become one). */
+  readonly create?: (props: Props) => Effect.Effect<unknown, E, GoogleWorkspaceOpContext>;
+  readonly update?: (
+    props: Props,
+    live: Live,
+  ) => Effect.Effect<unknown, E, GoogleWorkspaceOpContext>;
+  readonly destroy: (
+    props: Props,
+    live: Live,
+  ) => Effect.Effect<unknown, E, GoogleWorkspaceOpContext>;
+  /** For the read-back-failure message. */
+  readonly describe: (props: Props) => string;
+};
+
+export const googleWorkspaceOperations = <Props extends object, Live, Attributes, E>(
+  spec: GoogleWorkspaceSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        if (spec.matches(live, news)) return { action: 'noop' } as const;
+        return spec.update === undefined
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* spec.fetchLive(news);
+        if (before === undefined) {
+          if (spec.create === undefined) {
+            return yield* Effect.die(
+              new Error(`${spec.describe(news)}: spec declares no create for a missing object`),
+            );
+          }
+          yield* spec.create(news);
+        } else if (spec.update !== undefined) {
+          const mapped = spec.attributes(before, news);
+          // ⚠️ ADOPTION IS THE `mapped === undefined` CASE TOO: a row this spec cannot map is not
+          //   a row to PATCH blindly.
+          if (mapped !== undefined && !spec.matches(mapped, news)) {
+            yield* spec.update(news, before);
+          }
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              `${spec.describe(news)}: the write returned no error but the object is still ` +
+                'absent. Directory returns the object it wrote — read back rather than trusting ' +
+                'the status code.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* spec.fetchLive(olds);
+        if (live === undefined) return;
+        yield* spec.destroy(olds, live);
+      }),
+  };
+};
+
+/**
+ * The five provider handlers for a spec'd Directory object, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE, NOT BY EVERY CALLER. `CredentialsFromEnv` resolves
+ *   `GOOGLE_ACCESS_TOKEN` on the calling fiber per request (credentials.ts's own note), so this
+ *   closure keeps that laziness — nothing is captured at module load.
+ *
+ * ⛔ IT STOPS AT THE HANDLERS AND DOES NOT RETURN THE LAYER — same reasoning as `forgejoHandlers`.
+ *
+ * ⚠️ `list` answers empty. The Directory API's list endpoints page the whole domain — every group,
+ *   every org unit — so adoption stays explicit rather than sweeping (same posture as NetBox and
+ *   Forgejo; the census handoff script, not this provider, is where a full inventory belongs).
+ */
+export const googleWorkspaceHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: GoogleWorkspaceSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = googleWorkspaceOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, GoogleWorkspaceOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => withCredentials(ops.read(olds)),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      withCredentials(ops.diff(news, output)),
+    reconcile: ({ news }: { news: Props }) => withCredentials(ops.reconcile(news)),
+    delete: ({ olds }: { olds: Props }) => withCredentials(ops.destroy(olds)),
+  };
+};

package/src/google-workspace/values.ts

@@ -0,0 +1,36 @@
+/**
+ * Wire coercions shared across Google Workspace resources.
+ *
+ * ⚠️ EVERY FIELD ON A GENERATED DIRECTORY TYPE IS `S.optional(...)` (the SDK does not know which
+ *   fields Google always sends), so a live read is `string | undefined` even for a field the API
+ *   guarantees in practice. These helpers turn that into the settled value a `matches()` compares
+ *   against, mirroring `../netbox/values.ts` and `../forgejo/values.ts` for the same reason: a
+ *   `diff` that compared `undefined` against a declared default would see drift forever.
+ */
+
+/** `''` for absent — Directory objects that omit a text field mean "no value", not `undefined`. */
+export const text = (value: string | undefined): string => value ?? '';
+
+export const bool = (value: boolean | undefined): boolean => value === true;
+
+/**
+ * Wire arrays compared in sorted order. `StringList` (group aliases, org unit paths in a search)
+ * decodes to `string[] | undefined`; Directory does not promise an order.
+ */
+export const stringArray = (value: readonly string[] | undefined): string[] =>
+  value === undefined ? [] : [...value].toSorted();
+
+/**
+ * Every user- and group-facing key in this family is case-insensitive on the wire (Google lower-
+ * cases email addresses and org unit path segments internally) but a declaration may be typed in
+ * mixed case. Compare through this, never with `===`, or an adopted object drifts on every plan.
+ */
+export const ciEqual = (left: string, right: string): boolean =>
+  left.toLowerCase() === right.toLowerCase();
+
+/** An org unit path as the API wants it for a path segment: no leading `/`. */
+export const stripLeadingSlash = (path: string): string => path.replace(/^\/+/, '');
+
+/** An org unit path as attributes should read it back: exactly one leading `/`. */
+export const withLeadingSlash = (path: string): string =>
+  path.startsWith('/') ? path : `/${path}`;

package/src/grafana/credentials.ts

@@ -0,0 +1,65 @@
+/**
+ * Grafana credentials for this family — a URL plus a TOKEN REFERENCE (an env var NAME), never a
+ * literal secret. Wraps `@distilled.cloud/grafana`'s own `Credentials` context directly (S23 —
+ * reuse the SDK's own client rather than inventing a second one); this file only adds the house's
+ * lazy, per-instance resolution on top of it.
+ *
+ * ★ ONE `GRAFANA_TOKEN`/`GRAFANA_URL` PAIR ISN'T ENOUGH FOR THIS HOUSE. Unlike Forgejo (one
+ *   instance), the estate runs at least two Grafanas — `grafana.homeflare.dev` and
+ *   `teslamate-grafana` on CT100, which the unit's own comment says has "Own Access SaaS OIDC
+ *   client, never grafana.homeflare.dev's". The SDK's `CredentialsFromEnv` reads one fixed pair
+ *   of names, so a stack declaring against more than one instance needs a target per instance —
+ *   `grafanaCredentials(target)` below, parameterized the way `litellm/credentials.ts` and
+ *   `proxmox/credentials.ts` already are in this kit.
+ *
+ * ⛔ THE TOKEN NEVER TOUCHES A PROP OR AN ATTRIBUTE (S25). `tokenEnv` is a NAME, resolved from
+ *   `process.env` fresh inside the credentials effect on every request (S24) — a layer built once
+ *   still re-reads the environment each time an operation runs, the same laziness
+ *   `litellm/credentials.ts` and the SDK's own `forgejo`/`netbox` `CredentialsFromEnv` have.
+ *
+ * ⚠️ THE SDK's `Credentials` SERVICE VALUE TYPE IS `Effect.Effect<Config, never, never>` — the
+ *   error channel is `never` (credentials.d.ts). A missing env var can only surface as a defect
+ *   here, via `Effect.orDie`, the same trade-off `forgejo/resource.ts` and `netbox/resource.ts`
+ *   already accept for their own `CredentialsFromEnv`; it is not a choice this file introduces.
+ */
+import { type Config, Credentials } from '@distilled.cloud/grafana/Credentials';
+import { ConfigError } from '@distilled.cloud/grafana/Errors';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+
+export interface GrafanaTarget {
+  /** Instance origin, e.g. `https://tesla.homeflare.dev/dash` — never `/api`; the SDK appends it. */
+  readonly baseUrl: string;
+  /** Env var NAME holding a Grafana service-account token. Never the value itself. */
+  readonly tokenEnv: string;
+  /** Selects the org a call applies to, via `X-Grafana-Org-Id`. Omit for the default org. */
+  readonly orgId?: number | string;
+}
+
+const resolve = (target: GrafanaTarget): Effect.Effect<Config, never, never> =>
+  Effect.sync(() => process.env[target.tokenEnv]).pipe(
+    Effect.flatMap((raw) =>
+      raw === undefined || raw.trim() === ''
+        ? Effect.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}.`,
+            }),
+          )
+        : Effect.succeed({
+            apiBaseUrl: target.baseUrl.replace(/\/+$/, ''),
+            token: Redacted.make(raw.trim()),
+            ...(target.orgId === undefined ? {} : { orgId: target.orgId }),
+          } satisfies Config),
+    ),
+    Effect.orDie,
+  );
+
+/** The lazy, per-instance layer `grafanaProviders(target)` composes by default. */
+export const grafanaCredentials = (target: GrafanaTarget): Layer.Layer<Credentials> =>
+  Layer.succeed(Credentials, resolve(target));
+
+export type { Credentials };

package/src/grafana/datasource.test.ts

@@ -0,0 +1,183 @@
+/**
+ * `Grafana.Datasource` against a fake Grafana, proving the tagged-error paths, the secure-field
+ * reference seam (S25) and the observe-before-write "adopt" posture (S9/S10) — all through the
+ * REAL `@distilled.cloud/grafana` protocol (path assembly, JSON decode, status→typed-error
+ * matching), not re-implemented by hand. Mirrors `../forgejo/repository.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+import { GrafanaSecretRefUnsetError, spec } from './datasource.ts';
+
+const DS_PATH = '/api/datasources/uid/teslamate';
+const CREATE_PATH = '/api/datasources';
+
+const liveJson = {
+  access: 'proxy',
+  id: 7,
+  isDefault: true,
+  name: 'TeslaMate',
+  orgId: 1,
+  readOnly: false,
+  type: 'postgres',
+  uid: 'teslamate',
+  url: '127.0.0.1:5432',
+  version: 1,
+};
+
+const props = { name: 'TeslaMate', type: 'postgres', uid: 'teslamate' };
+
+describe('spec.fetchLive', () => {
+  test('a live datasource decodes into typed attributes', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DS_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live?.name).toBe('TeslaMate');
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      access: 'proxy',
+      id: 7,
+      isDefault: true,
+      name: 'TeslaMate',
+      orgId: 1,
+      readOnly: false,
+      type: 'postgres',
+      uid: 'teslamate',
+      url: '127.0.0.1:5432',
+      version: 1,
+    });
+    expect(fake.seen).toEqual([{ method: 'GET', path: DS_PATH }]);
+  });
+
+  test('a 404 folds to undefined — the exact idiom this family uses', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'Data source not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 401 propagates — Unauthorized is a real failure, never folded to absent', async () => {
+    const fake = fakeGrafana(() => fakeFailure(401, 'bad token'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('secure field references (S25)', () => {
+  const ENV_VAR = 'GRAFANA_FAMILY_TEST_DS_PASSWORD';
+
+  test('create resolves the env var fresh and sends it as secureJsonData, never as a prop', async () => {
+    process.env[ENV_VAR] = 's3cret';
+    try {
+      const fake = fakeGrafana((method, url) =>
+        method === 'POST' && url.pathname === CREATE_PATH
+          ? Response.json({ datasource: liveJson, id: 7, message: 'ok', name: 'TeslaMate' })
+          : fakeFailure(404, 'unexpected request'),
+      );
+      await Effect.runPromise(
+        spec
+          .create({ ...props, secureJsonDataRefs: { password: ENV_VAR } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      );
+      expect(fake.seen).toEqual([{ method: 'POST', path: CREATE_PATH }]);
+      // ⛔ THE POINT OF THIS TEST. Asserting only that a POST landed proves nothing about what it
+      //   carried — this is where a dropped `secureJsonData` spread would actually be caught.
+      expect(fake.bodies[0]).toMatchObject({ secureJsonData: { password: 's3cret' } });
+    } finally {
+      delete process.env[ENV_VAR];
+    }
+  });
+
+  test('create refuses with a typed error when the ref is unset — and never sends the request', async () => {
+    const fake = fakeGrafana(() => fakeFailure(500, 'should not be reached'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec
+          .create({ ...props, secureJsonDataRefs: { password: 'DEFINITELY_UNSET_VAR_XYZ' } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaSecretRefUnsetError);
+    expect(fake.seen).toEqual([]);
+  });
+});
+
+describe('reconcile — adopt semantics', () => {
+  test('declaring exactly what is live is a noop: no create or update is ever sent', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DS_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(500, 'reconcile should not write when nothing changed'),
+    );
+    const ops = grafanaOperations(spec);
+    const after = await Effect.runPromise(
+      ops
+        .reconcile({ ...props, access: 'proxy', isDefault: true })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('teslamate');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a genuinely absent uid is created', async () => {
+    // ⚠️ STATEFUL ON PURPOSE. `reconcile` reads back AFTER writing (S9/S10) — a fake that always
+    //   404s the GET would make that read-back indistinguishable from the "write lied" defect
+    //   `resource.ts` raises, so the second GET must see what the POST just created.
+    let created = false;
+    const newOne = { ...liveJson, uid: 'new-one' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === '/api/datasources/uid/new-one') {
+        return created ? Response.json(newOne) : fakeFailure(404, 'not found');
+      }
+      if (method === 'POST' && url.pathname === CREATE_PATH) {
+        created = true;
+        return Response.json({ datasource: newOne, id: 7, message: 'ok', name: 'TeslaMate' });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    const ops = grafanaOperations(spec);
+    await Effect.runPromise(
+      ops
+        .reconcile({ ...props, uid: 'new-one' })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'POST' && s.path === CREATE_PATH)).toBe(true);
+  });
+});
+
+describe('destroy', () => {
+  test('deletes a live datasource by uid', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === DS_PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === DS_PATH) return Response.json({ message: 'ok' });
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([
+      { method: 'GET', path: DS_PATH },
+      { method: 'DELETE', path: DS_PATH },
+    ]);
+  });
+
+  test('destroying an absent uid sends no DELETE — idempotent (S11)', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'not found'));
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([{ method: 'GET', path: DS_PATH }]);
+  });
+});

package/src/grafana/datasource.ts

@@ -0,0 +1,171 @@
+/**
+ * `Grafana.Datasource` — one Grafana data source, keyed by `uid`.
+ *
+ * ★ WHY `uid` IS REQUIRED, NOT GENERATED. `getDataSourceByUID`/`updateDataSourceByUID`/
+ *   `deleteDataSourceByUID` are all UID-keyed, and `getDataSources` (list) takes no filter — so
+ *   locating a datasource this resource didn't create means 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 — `AddDataSourceRequest.uid`) sidesteps
+ *   it entirely: `read`/`reconcile`/`destroy` all key on the one field the API itself is keyed on.
+ *   `teslamate-grafana`'s live datasource (provisioned from a file, not this resource) has a
+ *   Grafana-generated uid; the census in the handoff script records it so a first declaration can
+ *   name it explicitly.
+ *
+ * ⛔ `secureJsonData` (e.g. a datasource password) NEVER APPEARS AS A LITERAL PROP (S25).
+ *   `secureJsonDataRefs` takes env var NAMES instead; `resolveSecureJsonData` reads them from
+ *   `process.env` fresh inside `create`/`update`'s own effect, never at plan time and never
+ *   returned in `attributes` — Grafana's own read API agrees: `DataSource.secureJsonFields` on a
+ *   GET is a map of booleans (is-it-set), never the value.
+ */
+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 Effect from 'effect/Effect';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+
+export interface DatasourceProps {
+  uid: string;
+  name: string;
+  /** e.g. `postgres`, `prometheus`, `influxdb` — the Grafana plugin id. */
+  type: string;
+  url?: string;
+  access?: 'proxy' | 'direct';
+  database?: string;
+  user?: string;
+  basicAuth?: boolean;
+  basicAuthUser?: string;
+  isDefault?: boolean;
+  withCredentials?: boolean;
+  jsonData?: Record<string, unknown>;
+  /** Secure field name (e.g. `password`) -> env var NAME holding its value. Never the value. */
+  secureJsonDataRefs?: Record<string, string>;
+}
+
+export interface DatasourceAttributes {
+  uid: string;
+  id: number;
+  name: string;
+  type: string;
+  url: string;
+  access: string;
+  orgId: number;
+  isDefault: boolean;
+  readOnly: boolean;
+  version: number;
+}
+
+export interface GrafanaDatasource extends Resource<
+  'Grafana.Datasource',
+  DatasourceProps,
+  DatasourceAttributes,
+  never
+> {}
+
+export const GrafanaDatasource = Resource<GrafanaDatasource>('Grafana.Datasource');
+
+/** A named secure-field env var is unset — a domain refusal, not a distilled error. */
+export class GrafanaSecretRefUnsetError extends Data.TaggedError('GrafanaSecretRefUnsetError')<{
+  readonly message: string;
+}> {}
+
+/** Reads every named env var fresh, inside the caller's effect (S24) — never at plan time. */
+const resolveSecureJsonData = (
+  refs: Record<string, string> | undefined,
+): Effect.Effect<Record<string, string> | undefined, GrafanaSecretRefUnsetError> =>
+  Effect.gen(function* () {
+    if (refs === undefined) return undefined;
+    const out: Record<string, string> = {};
+    for (const [field, envVar] of Object.entries(refs)) {
+      const raw = process.env[envVar];
+      if (raw === undefined || raw.trim() === '') {
+        return yield* Effect.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;
+  });
+
+/** `exactOptionalPropertyTypes` means an undeclared field must be OMITTED, never sent as `undefined`. */
+const fields = (props: DatasourceProps) => ({
+  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 }),
+});
+
+export const spec: GrafanaSpec<
+  DatasourceProps,
+  grafana.DataSource,
+  DatasourceAttributes,
+  | grafana.AddDataSourceError
+  | grafana.GetDataSourceByUIDError
+  | grafana.UpdateDataSourceByUIDError
+  | grafana.DeleteDataSourceByUIDError
+  | GrafanaSecretRefUnsetError
+> = {
+  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) =>
+    Effect.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(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  /**
+   * ⛔ AN UNDECLARED FIELD IS NEITHER COMPARED NOR SENT — the same rule every family in this
+   *   estate follows. `secureJsonDataRefs` is never compared: Grafana never returns the value to
+   *   diff against, only whether a field is set (`secureJsonFields`), so this resource cannot
+   *   detect drift in a secret's value — only in whether one is configured at all.
+   */
+  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) =>
+    Effect.flatMap(resolveSecureJsonData(props.secureJsonDataRefs), (secureJsonData) =>
+      grafana.updateDataSourceByUID({
+        ...fields(props),
+        ...(secureJsonData === undefined ? {} : { secureJsonData }),
+        ...(live.version === undefined ? {} : { version: live.version }),
+        uid: props.uid,
+      }),
+    ),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaDatasourceProvider = () =>
+  Provider.effect(GrafanaDatasource, Effect.succeed(GrafanaDatasource.Provider.of(handlers)));