@homeflare/alchemy 0.29.1 → 0.31.0

package/src/google-workspace/org-unit.ts

@@ -0,0 +1,143 @@
+/**
+ * `GoogleWorkspace.OrgUnit` — one organizational unit (`admin/directory/v1/customer/{id}/orgunits`).
+ *
+ * ★ `orgUnitPath` IS THE IDENTITY the way `NetboxPrefix.prefix` is. Google's own doc line is
+ *   copied onto `OrgUnitProps.orgUnitPath` below because it is the one field this resource cannot
+ *   get wrong: it is DERIVED on read (`parentOrgUnitPath` + `name`) but AUTHORED as a full path on
+ *   write, and the API's own path-parameter form drops the leading `/` (`GetOrgunitsRequest`'s
+ *   `orgUnitPath` doc: "the full path … minus the leading `/`"). `values.ts`'s
+ *   `stripLeadingSlash`/`withLeadingSlash` are the one place that asymmetry is handled.
+ *
+ * ⛔ THIS RESOURCE DOES NOT REMOVE SUB-UNITS OR MOVE USERS. Deleting an org unit that still has
+ *   children or members fails server-side (Directory refuses rather than cascading) — nothing
+ *   here retries around that refusal, matching S11's "observe before deleting", not "force
+ *   through".
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — an org unit governs which Workspace services a user can
+ *   reach (Google's own doc line on `orgUnitPath`); deleting one out from under live users is
+ *   exactly the kind of hard-to-reverse action this policy exists to require an explicit opt-in
+ *   for.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as directory from '@distilled.cloud/google-workspace/unstable/admin_directory_v1';
+import * as Effect from 'effect/Effect';
+import type { GoogleWorkspaceRequirements, GoogleWorkspaceSpec } from './resource.ts';
+import { googleWorkspaceHandlers } from './resource.ts';
+import { stripLeadingSlash, text, withLeadingSlash } from './values.ts';
+
+export interface OrgUnitProps {
+  /** The unique id for the Workspace account, or `my_customer` for the caller's own account. */
+  customerId?: string;
+  /**
+   * The full path to the organizational unit, e.g. `/Contractors/2026`. Required. In order to
+   * edit an `orgUnitPath`, either update `name` or `parentOrgUnitPath` — this field is derived on
+   * read, not itself patchable, so declaring a different path here plans a `replace`.
+   */
+  orgUnitPath: string;
+  /** The parent's full path, e.g. `/Contractors`. Omit for a top-level unit under `/`. */
+  parentOrgUnitPath?: string;
+  description?: string;
+}
+
+export interface OrgUnitAttributes {
+  customerId: string;
+  orgUnitPath: string;
+  parentOrgUnitPath: string;
+  name: string;
+  description: string;
+  orgUnitId: string;
+}
+
+export interface GoogleWorkspaceOrgUnit extends Resource<
+  'GoogleWorkspace.OrgUnit',
+  OrgUnitProps,
+  OrgUnitAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceOrgUnit = Resource<GoogleWorkspaceOrgUnit>('GoogleWorkspace.OrgUnit', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const customerOf = (props: OrgUnitProps): string => props.customerId ?? 'my_customer';
+/** The path segment the API wants, split from its own leading-name component for `name`/`insert`. */
+const nameOf = (props: OrgUnitProps): string =>
+  props.orgUnitPath.split('/').filter(Boolean).pop() ?? props.orgUnitPath;
+const parentOf = (props: OrgUnitProps): string => props.parentOrgUnitPath ?? '/';
+
+const attributesOf = (
+  live: directory.OrgUnit,
+  props: OrgUnitProps,
+): OrgUnitAttributes | undefined => {
+  const livePath = live.orgUnitPath === undefined ? undefined : withLeadingSlash(live.orgUnitPath);
+  if (livePath === undefined || livePath.toLowerCase() !== props.orgUnitPath.toLowerCase()) {
+    return undefined;
+  }
+  return {
+    customerId: customerOf(props),
+    description: text(live.description),
+    name: text(live.name),
+    orgUnitId: text(live.orgUnitId),
+    orgUnitPath: livePath,
+    parentOrgUnitPath: text(live.parentOrgUnitPath),
+  };
+};
+
+/** ★ EXPORTED for direct testing — see org-unit.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  OrgUnitProps,
+  directory.OrgUnit,
+  OrgUnitAttributes,
+  | directory.GetOrgunitsError
+  | directory.InsertOrgunitsError
+  | directory.PatchOrgunitsError
+  | directory.DeleteOrgunitsError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertOrgunits({
+      body: {
+        description: props.description ?? '',
+        name: nameOf(props),
+        parentOrgUnitPath: parentOf(props),
+      },
+      customerId: customerOf(props),
+    }),
+  describe: (props) => `customer/${customerOf(props)}/orgunits${props.orgUnitPath}`,
+  destroy: (props, live) =>
+    directory.deleteOrgunits({
+      customerId: customerOf(props),
+      orgUnitPath: stripLeadingSlash(text(live.orgUnitPath) || props.orgUnitPath),
+    }),
+  fetchLive: (props) =>
+    directory
+      .getOrgunits({
+        customerId: customerOf(props),
+        orgUnitPath: stripLeadingSlash(props.orgUnitPath),
+      })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.description === (props.description ?? '') &&
+    attributes.parentOrgUnitPath === parentOf(props) &&
+    attributes.name === nameOf(props),
+  update: (props, live) =>
+    directory.patchOrgunits({
+      body: {
+        description: props.description ?? '',
+        name: nameOf(props),
+        parentOrgUnitPath: parentOf(props),
+      },
+      customerId: customerOf(props),
+      orgUnitPath: stripLeadingSlash(text(live.orgUnitPath) || props.orgUnitPath),
+    }),
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceOrgUnitProvider = () =>
+  Provider.effect(
+    GoogleWorkspaceOrgUnit,
+    Effect.succeed(GoogleWorkspaceOrgUnit.Provider.of(handlers)),
+  );

package/src/google-workspace/providers.ts

@@ -0,0 +1,26 @@
+/**
+ * Every Google Workspace provider, wired once — the same role `litellmProviders`/`netboxProviders`-
+ * style helpers play elsewhere in this kit (S16: "a subpath's `providers()` plays the same role" as
+ * upstream's `Providers.ts`).
+ *
+ *     Layer.mergeAll(googleWorkspaceProviders(), …the stack's other providers)
+ *
+ * ⚠️ CREDENTIALS ARE NOT A PARAMETER HERE. Every handler already closes over
+ *   `CredentialsFromEnv` inside `resource.ts` (`GOOGLE_ACCESS_TOKEN`, resolved at call time — see
+ *   credentials.ts), so this layer only wires the four resource providers together. `HttpClient`
+ *   is NOT provided here either — it is ambient in every Alchemy runtime, the same note
+ *   `litellm/providers.ts` makes for its own family.
+ */
+import * as Layer from 'effect/Layer';
+import { GoogleWorkspaceDomainAliasProvider } from './domain-alias.ts';
+import { GoogleWorkspaceGroupProvider } from './group.ts';
+import { GoogleWorkspaceGroupMemberProvider } from './group-member.ts';
+import { GoogleWorkspaceOrgUnitProvider } from './org-unit.ts';
+
+export const googleWorkspaceProviders = () =>
+  Layer.mergeAll(
+    GoogleWorkspaceGroupProvider(),
+    GoogleWorkspaceGroupMemberProvider(),
+    GoogleWorkspaceDomainAliasProvider(),
+    GoogleWorkspaceOrgUnitProvider(),
+  );

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

@@ -0,0 +1,186 @@
+/**
+ * `googleWorkspaceOperations`'s shared `diff`/`reconcile` engine, exercised end-to-end through a
+ * fake Directory API — not just through a resource's own `spec.matches`/`fetchLive` in isolation.
+ *
+ * 🔴 WHY THIS FILE EXISTS. An adversarial review of this family (2026-09-24) found that every
+ *   other test here calls `spec.fetchLive`/`spec.attributes`/`spec.matches` directly and never
+ *   `googleWorkspaceOperations(spec).diff`/`.reconcile` — so a bug INSIDE `resource.ts` itself
+ *   (shared by all four resources) could invert `diff`'s `noop`/`update` branches, or skip the
+ *   "write returned no error but the object is still absent" die-guard, and no test here would
+ *   catch it. This file closes that gap: it drives the real engine against real specs (`group.ts`,
+ *   whose spec HAS `update`, and `domain-alias.ts`, whose spec does NOT), through the same fake
+ *   HTTP layer every other test in this family uses.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { spec as aliasSpec } from './domain-alias.ts';
+import {
+  fakeFailure,
+  fakeGoogleWorkspace,
+  fakeGoogleWorkspaceLayer,
+} from './fake-google-workspace.ts';
+import { spec as groupSpec } from './group.ts';
+import { googleWorkspaceOperations } from './resource.ts';
+
+const groupOps = googleWorkspaceOperations(groupSpec);
+const groupProps = { email: 'ops@schenanigans.com', name: 'Ops', description: 'ops team' };
+const GROUP_PATH = '/admin/directory/v1/groups/ops%40schenanigans.com';
+
+describe('googleWorkspaceOperations(group spec).reconcile', () => {
+  test('absent → create, then read back — the happy create path', async () => {
+    let created = false;
+    const fake = fakeGoogleWorkspace((method, url) => {
+      if (method === 'POST' && url.pathname === '/admin/directory/v1/groups') {
+        created = true;
+        return Response.json({ email: groupProps.email, name: 'Ops' });
+      }
+      if (method === 'GET' && url.pathname === GROUP_PATH) {
+        return created
+          ? Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' })
+          : fakeFailure(404, 'not found', 'NOT_FOUND');
+      }
+      return fakeFailure(404, 'not found', 'NOT_FOUND');
+    });
+    const attrs = await Effect.runPromise(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(created).toBe(true);
+    expect(attrs.email).toBe(groupProps.email);
+  });
+
+  test('present and matching → no PATCH is ever sent', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    await Effect.runPromise(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((r) => r.method === 'PATCH')).toBe(false);
+  });
+
+  test('present and drifted → PATCH is sent exactly once', async () => {
+    let patched = false;
+    const fake = fakeGoogleWorkspace((method, url) => {
+      if (method === 'PATCH' && url.pathname === GROUP_PATH) {
+        patched = true;
+        return Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' });
+      }
+      if (method === 'GET' && url.pathname === GROUP_PATH) {
+        return Response.json({
+          description: 'stale description',
+          email: groupProps.email,
+          name: 'Ops',
+        });
+      }
+      return fakeFailure(404, 'not found', 'NOT_FOUND');
+    });
+    await Effect.runPromise(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(patched).toBe(true);
+  });
+
+  test('a write that reports success but leaves the object absent dies — never lies to the plan', async () => {
+    const fake = fakeGoogleWorkspace(
+      (method, url) =>
+        method === 'POST' && url.pathname === '/admin/directory/v1/groups'
+          ? Response.json({})
+          : fakeFailure(404, 'not found', 'NOT_FOUND'), // every GET stays 404, even after "create"
+    );
+    const failed = await Effect.runPromiseExit(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(failed._tag).toBe('Failure');
+  });
+});
+
+describe('googleWorkspaceOperations(group spec).diff', () => {
+  const live = {
+    adminCreated: false,
+    aliases: [],
+    description: 'ops team',
+    directMembersCount: '0',
+    email: groupProps.email,
+    groupId: 'x',
+    name: 'Ops',
+    nonEditableAliases: [],
+  };
+
+  test('output undefined → undefined (engine default: treat as update)', async () => {
+    // ⚠️ `diff` short-circuits on `output === undefined` before it ever reads — no request is
+    //   made — but the Effect's TYPE still carries `GoogleWorkspaceOpContext`, so a layer is
+    //   still required to satisfy `runPromise`. `fake.seen` below proves the short-circuit.
+    const fake = fakeGoogleWorkspace(() => fakeFailure(500, 'must not be called', 'INTERNAL'));
+    const result = await Effect.runPromise(
+      groupOps
+        .diff(groupProps, undefined)
+        .pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('matching live → noop, read through the real fake', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    const result = await Effect.runPromise(
+      groupOps.diff(groupProps, live).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('drifted live, spec HAS update → action is update, not replace', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({
+            description: 'a different description',
+            email: groupProps.email,
+            name: 'Ops',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    const result = await Effect.runPromise(
+      groupOps.diff(groupProps, live).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'update' });
+  });
+});
+
+describe('googleWorkspaceOperations(domain-alias spec).diff — spec has NO update', () => {
+  const aliasOps = googleWorkspaceOperations(aliasSpec);
+  const aliasProps = {
+    domainAliasName: 'alias.schenanigans.com',
+    parentDomainName: 'schenanigans.com',
+  };
+  const ALIAS_PATH =
+    '/admin/directory/v1/customer/my_customer/domainaliases/alias.schenanigans.com';
+  const liveAttrs = {
+    creationTime: '0',
+    customer: 'my_customer',
+    domainAliasName: aliasProps.domainAliasName,
+    parentDomainName: aliasProps.parentDomainName,
+    verified: true,
+  };
+
+  test('drifted live, spec has NO update → replace, never update', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === ALIAS_PATH
+        ? Response.json({
+            domainAliasName: aliasProps.domainAliasName,
+            parentDomainName: 'homeflare.dev',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    const result = await Effect.runPromise(
+      aliasOps
+        .diff(aliasProps, liveAttrs)
+        .pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'replace' });
+  });
+});

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 };