@homeflare/alchemy 0.29.1 → 0.31.0

package/src/discord/resource.ts

@@ -0,0 +1,164 @@
+/**
+ * One shape for every Discord application-command object — global and guild-scoped alike.
+ *
+ * ⛔ THE ALTERNATIVE IS COPYING THE SAME READ/RECONCILE/DELETE PER RESOURCE. `application-command.ts`
+ *   and `guild-application-command.ts` differ only in which distilled operations they call and
+ *   whether `guild_id` is part of identity — so the read/diff/reconcile/delete flow lives here
+ *   once, mirroring `../netbox/resource.ts`'s `netboxOperations`/`netboxHandlers` split.
+ *
+ * ★ UNLIKE NETBOX, THIS FOLLOWS UPSTREAM'S `Snippet.ts` READ/RECONCILE SHAPE EXACTLY (S7–S9), NOT
+ *   netbox's "adopt silently" gap (H1). Discord commands carry no ownership marker of any kind —
+ *   no tags, no metadata field a bot could stamp — so this is precisely the "marker-less API" S8
+ *   describes, and `Snippet.ts@v2.0.0-beta.79#read` is the cited reference: an existing match is
+ *   `Unowned(attrs)` on a cold read (no persisted `output`), and plain attributes on a warm read
+ *   (persisted `output` says we already made or adopted this exact command). `adopt(true)` (H5),
+ *   piped onto each resource by the constructors in the two resource files, is what turns that
+ *   `Unowned` into a silent one-time takeover instead of an `OwnedBySomeoneElse` refusal.
+ *
+ * ★ RECONCILE IS ONE UPSERT CALL, LIKE `Snippet.ts`'s `putSnippet`. Discord's own docs for both
+ *   Create Global/Guild Application Command say a command with the same name (and type) as an
+ *   existing one OVERWRITES it — the create endpoint is a true upsert, not a create-only call that
+ *   409s on a name collision. ⚠️ REASONED NOT MEASURED (no token available to this task; see
+ *   `docs/discord.md`): this is Discord's documented behaviour, unchanged across API v10, but it
+ *   has not been exercised against the real API by this change. One call therefore converges
+ *   greenfield create, routine update AND adoption alike — there is no separate PATCH path, and
+ *   S10's "zero write calls when there is no drift" is still honoured because `reconcile` skips
+ *   the call entirely when `spec.matches` already holds.
+ *
+ * ⚠️ `list` ANSWERS EMPTY, ON PURPOSE, EVEN THOUGH THE DISTILLED LIST OPERATIONS EXIST. A bot's
+ *   guild command set is exactly what `hf-discord-halibut.service` bulk-overwrites at every
+ *   restart (see `docs/discord.md#halibut`); a `nuke` that enumerated and swept every live command
+ *   would fight that ownership, not just this resource's own declarations. Adoption stays
+ *   explicit, the same reasoning netbox's `list` gives for a shared instance predating the kit.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { DiscordOpContext } from '@distilled.cloud/discord/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { CredentialsFromEnv } from './credentials.ts';
+
+/**
+ * What every stack must still provide after `discordHandlers` bakes in `CredentialsFromEnv`
+ * (below): the transport. `DiscordOpContext` is `Credentials | HttpClient.HttpClient`, so once
+ * `Credentials` is supplied, `HttpClient.HttpClient` is what remains — mirroring
+ * `../netbox/resource.ts#NetboxRequirements`.
+ */
+export type DiscordRequirements = HttpClient.HttpClient;
+
+/** Every Discord command resource's identity key, regardless of scope. */
+export interface DiscordCommandIdentity {
+  readonly name: string;
+}
+
+/**
+ * One Discord command object's distilled calls. `Live` is whatever the SDK decodes
+ * (`ApplicationCommandResponse`); `E` is left to each resource file to declare, so a call site's
+ * precise error union (in practice always `DiscordOpError` — see `protocol.ts` — because every
+ * generated Discord operation shares one error channel) flows straight through.
+ */
+export type DiscordSpec<
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+> = {
+  /** Locate the live command by its declared name within this spec's scope (app, or app+guild). */
+  readonly fetchByName: (props: Props) => Effect.Effect<Live | undefined, E, DiscordOpContext>;
+  readonly attributes: (live: Live) => Attributes;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  readonly upsertBody: (props: Props) => Record<string, unknown>;
+  /** POST create-or-overwrite — see the upsert note above. */
+  readonly upsert: (
+    props: Props,
+    body: Record<string, unknown>,
+  ) => Effect.Effect<Live, E, DiscordOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, DiscordOpContext>;
+  /** For error messages and test descriptions. */
+  readonly describe: (props: Props) => string;
+};
+
+export const discordOperations = <
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: DiscordSpec<Props, Live, Attributes, E>,
+) => ({
+  read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+    Effect.gen(function* () {
+      const live = yield* spec.fetchByName(olds);
+      if (live === undefined) return undefined;
+      const attrs = spec.attributes(live);
+      // Warm read: a prior apply already created or adopted this exact command — ours.
+      if (output !== undefined) return attrs;
+      // Cold read (fresh store, or state lost): no ownership marker exists on this vendor,
+      // so any match is `Unowned` until `adopt(true)` (or `--adopt`) says otherwise (S7, S8).
+      return Unowned(attrs);
+    }),
+
+  diff: (news: Input<Props>, output: Attributes | undefined) =>
+    Effect.gen(function* () {
+      if (output === undefined || !isResolved(news)) return undefined;
+      const live = yield* spec.fetchByName(news);
+      if (live === undefined) return { action: 'update' } as const;
+      return spec.matches(spec.attributes(live), news)
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: (news: Props) =>
+    Effect.gen(function* () {
+      const before = yield* spec.fetchByName(news);
+      if (before !== undefined && spec.matches(spec.attributes(before), news)) {
+        // Already exactly what is declared — S10: no write.
+        return spec.attributes(before);
+      }
+      const body = spec.upsertBody(news);
+      const after = yield* spec.upsert(news, body);
+      return spec.attributes(after);
+    }),
+
+  // ⚠️ GAP, NOT SOLVED: a TOCTOU race between the fetch above and the delete call below could
+  //   see Discord answer 404 on a command that vanished between the two — S11 asks that race to
+  //   be treated as success, `catchTag('NotFound', …)`. The SDK's declared error type for every
+  //   operation does not include `NotFound` (see `docs/discord.md#sdk-gaps` — measured, not
+  //   assumed), so there is no typed tag to catch here without an unsafe cast. Left unhandled.
+  destroy: (olds: Props) =>
+    Effect.gen(function* () {
+      const live = yield* spec.fetchByName(olds);
+      if (live === undefined) return;
+      yield* spec.destroy(olds, live);
+    }),
+});
+
+/**
+ * The four provider handlers for a spec'd Discord command, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE. `CredentialsFromEnv` resolves `DISCORD_BOT_TOKEN` /
+ *   `DISCORD_TOKEN` on the calling fiber per request (credentials.ts), so this closure keeps that
+ *   laziness — nothing is captured at module load.
+ */
+export const discordHandlers = <
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: DiscordSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = discordOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, DiscordOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+      withCredentials(ops.read({ olds, output })),
+    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/discord/retry.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Discord's 429 handling — proving the SDK's OWN default retry policy (`@distilled.cloud/core`'s
+ * `makeDefault`, threaded through every operation via `retry: Retry.Retry` — see `resource.ts`'s
+ * header note and `docs/discord.md#rate-limits`), not a house re-implementation. This file exists
+ * because "respect Discord's rate limits with a bounded retry" is a requirement this task must
+ * satisfy, and the honest way to satisfy it here is to prove the SDK already does — nothing in
+ * `resource.ts` installs a `Discord.Retry.policy` of its own, so if this test ever failed to
+ * retry, or failed to STOP retrying, there would be nothing in this package to fix; the fix would
+ * be in `@distilled.cloud/discord`.
+ *
+ * ⛔ A TEST THAT CANNOT FAIL PROVES NOTHING. Both cases below assert on the fake's own call count
+ *   (`fake.seen.length`), not just on the eventual Effect outcome — a policy that retried once,
+ *   or one that retried forever, would each still "eventually succeed" or "eventually fail" on
+ *   SOME outcome; the call count is what makes "bounded" a real, checkable claim rather than an
+ *   assumption the test's own passing would not have caught.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { spec } from './guild-application-command.ts';
+import type { GuildApplicationCommandProps } from './guild-application-command.ts';
+import { fakeDiscord, fakeDiscordLayer, fakeRateLimited } from './fake-discord.ts';
+
+const APP = '111111111111111111';
+const GUILD = '222222222222222222';
+const CMD_PATH = `/applications/${APP}/guilds/${GUILD}/commands`;
+const PROPS: GuildApplicationCommandProps = { applicationId: APP, guildId: GUILD, name: 'ping' };
+
+const liveCommand = () => ({
+  application_id: APP,
+  default_member_permissions: null,
+  description: '',
+  guild_id: GUILD,
+  id: '999',
+  name: 'ping',
+  nsfw: false,
+  type: 1,
+  version: '1',
+});
+
+describe('the SDK default Retry policy on a 429', () => {
+  test('two 429s (Retry-After: 0) then a 200 — retried, and it converges', async () => {
+    const fake = fakeDiscord((method, url, _body, callNumber) => {
+      if (method !== 'GET' || url.pathname !== CMD_PATH) return new Response(null, { status: 500 });
+      return callNumber <= 2 ? fakeRateLimited(0) : Response.json([liveCommand()]);
+    });
+    const live = await Effect.runPromise(
+      spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('999');
+    expect(fake.seen).toHaveLength(3);
+  }, 15_000);
+
+  /**
+   * ★ THE BOUND ITSELF. `@distilled.cloud/core`'s `makeDefault` caps this at `Schedule.recurs(8)`
+   *   — 8 retries, 9 attempts total — regardless of how long the server keeps answering 429. A
+   *   server that never recovers must still let the caller find out, in bounded time, rather than
+   *   parking the fiber forever; that is the literal meaning of "bounded retry".
+   */
+  test('429 forever is a bounded number of attempts, then a typed failure — never an infinite loop', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? fakeRateLimited(0)
+        : new Response(null, { status: 500 }),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('TooManyRequests');
+    // 1 initial attempt + at most 8 retries. Strictly greater than 1 proves a retry happened at
+    // all; at most 9 proves it stopped rather than continuing past the documented bound.
+    expect(fake.seen.length).toBeGreaterThan(1);
+    expect(fake.seen.length).toBeLessThanOrEqual(9);
+  }, 15_000);
+});

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

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

package/src/google-workspace/credentials.ts

@@ -0,0 +1,75 @@
+/**
+ * Google Workspace credentials for the house — a lazy reference, never the key.
+ *
+ * ⛔ THE DISTILLED SDK'S OWN `Credentials` SERVICE TAKES ONE THING: an already-minted OAuth2
+ *   bearer access token (`@distilled.cloud/google-workspace/Credentials` — read at
+ *   `node_modules/@distilled.cloud/google-workspace/src/credentials.ts`, 2026-09-24: "API-compatible
+ *   port of the distilled gcp credentials module … no ADC, no service-account signing, no refresh
+ *   flow"). It has no service-account JSON shape and no domain-wide-delegation JWT exchange built
+ *   in — minting the token is entirely outside the SDK's surface.
+ *
+ * ★ SO THE HOUSE PATTERN IS H8'S, UNCHANGED: a short-lived credential is minted from OpenBao and
+ *   exported into the DEPLOY PROCESS's environment only, by a Bun wrapper the operator runs — the
+ *   same shape the kit's Proxmox subpath already uses for its own OpenBao-sourced token. This
+ *   family adds nothing that signs a JWT or talks to Google's token endpoint; that stays Tim's
+ *   wrapper script, documented in the README, because building it here would be a second,
+ *   hand-rolled auth flow next to the one the SDK already exposes (S23).
+ *
+ * ⛔ NEVER THE KEY. `GoogleWorkspaceKeyRef` below is a REFERENCE to where a service-account key
+ *   lives — an OpenBao path, a delegated admin subject and the scopes the wrapper requests — not
+ *   the key itself. Nothing in this family reads, parses or holds private key material; `describeKeyRef`
+ *   is pure string formatting for docs and the census handoff header, and it is tested (below) to
+ *   never accept or echo anything shaped like a key.
+ *
+ * Re-exported so a consumer imports one module for both the distilled service and the house
+ * reference type: `import { CredentialsFromEnv, fromAccessToken, type GoogleWorkspaceKeyRef } from
+ * '@homeflare/alchemy/google-workspace'`.
+ */
+export {
+  type Config as GoogleWorkspaceConfig,
+  Credentials,
+  CredentialsFromEnv,
+  fromAccessToken,
+} from '@distilled.cloud/google-workspace/Credentials';
+
+/** Env var the SDK's `CredentialsFromEnv` reads — the wrapper mints into THIS var, nothing else. */
+export const GOOGLE_ACCESS_TOKEN_ENV = 'GOOGLE_ACCESS_TOKEN';
+/** Optional — only meaningful if a resource ever needs to scope a call to a GCP project. */
+export const GOOGLE_PROJECT_ID_ENV = 'GOOGLE_PROJECT_ID';
+
+/**
+ * Where the service-account key that a wrapper exchanges for `GOOGLE_ACCESS_TOKEN` lives —
+ * documentation and typing only. A stack file may keep one of these next to its declarations so
+ * the OpenBao path, delegated admin and scopes are reviewable in the same diff as the resources
+ * they authorize — nothing here reads OpenBao or Google, and no field may hold a key, a token or
+ * a private key fragment.
+ */
+export interface GoogleWorkspaceKeyRef {
+  /** OpenBao KV path, e.g. `kv/google-workspace/service-accounts/directory-admin`. */
+  readonly openBaoPath: string;
+  /** The Workspace admin the service account impersonates via domain-wide delegation. */
+  readonly delegatedAdmin: string;
+  /** OAuth scopes the wrapper requests — keep this the least the declared resources need. */
+  readonly scopes: readonly string[];
+}
+
+/** Substrings that must never appear in a `GoogleWorkspaceKeyRef` field — this is a reference. */
+const KEY_SHAPED = /-----BEGIN|private_key|"type":\s*"service_account"/i;
+
+/**
+ * A one-line, key-free description for docs and the census handoff header. Throws rather than
+ * formatting a ref whose fields look like they hold key material — a `GoogleWorkspaceKeyRef` is
+ * a pointer, and this is the one place that assumption is checked instead of assumed.
+ */
+export const describeKeyRef = (ref: GoogleWorkspaceKeyRef): string => {
+  for (const [field, value] of Object.entries(ref)) {
+    const text = Array.isArray(value) ? value.join(',') : String(value);
+    if (KEY_SHAPED.test(text)) {
+      throw new Error(`GoogleWorkspaceKeyRef.${field} looks like key material, not a reference`);
+    }
+  }
+  return (
+    `service account at OpenBao:${ref.openBaoPath}, delegating as ${ref.delegatedAdmin}, ` +
+    `scopes: ${ref.scopes.join(' ')}`
+  );
+};

package/src/google-workspace/domain-alias.test.ts

@@ -0,0 +1,69 @@
+/**
+ * `GoogleWorkspace.DomainAlias`'s `spec` against a fake Directory API — no `update` operation
+ * exists (domain-alias.ts's own note), so this only proves `fetchLive`/`attributes`/`matches`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import {
+  fakeFailure,
+  fakeGoogleWorkspace,
+  fakeGoogleWorkspaceLayer,
+} from './fake-google-workspace.ts';
+import { spec } from './domain-alias.ts';
+
+const ALIAS_PATH = '/admin/directory/v1/customer/my_customer/domainaliases/alias.schenanigans.com';
+const props = { domainAliasName: 'alias.schenanigans.com', parentDomainName: 'schenanigans.com' };
+
+const readThrough = (fetchFn: typeof globalThis.fetch) =>
+  Effect.runPromise(
+    spec.fetchLive(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+      Effect.provide(fakeGoogleWorkspaceLayer(fetchFn)),
+    ),
+  );
+
+describe('GoogleWorkspace.DomainAlias spec.fetchLive + spec.attributes', () => {
+  test('a live alias decodes with the default my_customer scope', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === ALIAS_PATH
+        ? Response.json({
+            creationTime: '1700000000000',
+            domainAliasName: 'alias.schenanigans.com',
+            parentDomainName: 'schenanigans.com',
+            verified: true,
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      creationTime: '1700000000000',
+      customer: 'my_customer',
+      domainAliasName: 'alias.schenanigans.com',
+      parentDomainName: 'schenanigans.com',
+      verified: true,
+    });
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(404, 'not found', 'NOT_FOUND'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});
+
+describe('GoogleWorkspace.DomainAlias spec.matches and spec.update', () => {
+  const live = {
+    creationTime: '1700000000000',
+    customer: 'my_customer',
+    domainAliasName: 'alias.schenanigans.com',
+    parentDomainName: 'schenanigans.com',
+    verified: true,
+  };
+
+  test('the same parentDomainName is no drift', () => {
+    expect(spec.matches(live, props)).toBe(true);
+  });
+
+  test('a different parentDomainName is drift — and since there is no update, diff replaces', () => {
+    expect(spec.matches(live, { ...props, parentDomainName: 'homeflare.dev' })).toBe(false);
+    expect(spec.update).toBeUndefined();
+  });
+});

package/src/google-workspace/domain-alias.ts

@@ -0,0 +1,116 @@
+/**
+ * `GoogleWorkspace.DomainAlias` — one secondary-domain alias on the Workspace account
+ * (`admin/directory/v1/customer/{customer}/domainaliases`).
+ *
+ * ⛔ NO `update` OPERATION EXISTS. The Directory API ships `get`/`insert`/`delete`/`list` for
+ *   domain aliases and nothing else — measured against `admin_directory_v1.ts`: there is no
+ *   `patchDomainAliases` or `updateDomainAliases`. `spec.update` is intentionally absent, so
+ *   `resource.ts`'s `diff` reports `replace` for any drift rather than an unsendable PATCH — the
+ *   same fallback NetBox's `netboxOperations` and Forgejo's `forgejoOperations` give a spec with
+ *   no `update`.
+ *
+ * ★ `domainAliasName` IS THE WHOLE IDENTITY. `parentDomainName` only matters at create time —
+ *   Google refuses reparenting an alias in place, so a declared `parentDomainName` that no longer
+ *   matches the live row is exactly the identity change `replace` exists for.
+ *
+ * ⚠️ THE HOUSE'S CLOUDFLARE ZONES (`homeflare.dev`, `aimto.app`, `schenanigans.com`, `taslabs.net`
+ *   — `site/live.site.json` in homeflare-landscape) are DNS zones, not Workspace domains by
+ *   themselves; a zone only becomes a valid `parentDomainName` once it is added and verified as a
+ *   primary or secondary domain in the Workspace admin console. This family does not verify a
+ *   domain — Google's verification is a TXT/CNAME challenge outside the Directory API's write
+ *   surface — so `create` will fail with `BadRequest` against an unverified domain, which is
+ *   correct: nothing here should silently paper over a step the account owner has to do by hand.
+ */
+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 { bool, ciEqual, text } from './values.ts';
+
+export interface DomainAliasProps {
+  /** The unique id for the Workspace account, or `my_customer` for the caller's own account. */
+  customer?: string;
+  /** The alias domain name — primary key for locate. */
+  domainAliasName: string;
+  /** The primary or secondary domain this alias resolves to. Immutable — a change replaces. */
+  parentDomainName: string;
+}
+
+export interface DomainAliasAttributes {
+  customer: string;
+  domainAliasName: string;
+  parentDomainName: string;
+  /** Read-only. */
+  verified: boolean;
+  /** Read-only, ISO-ish epoch-ms string as Google returns it. */
+  creationTime: string;
+}
+
+export interface GoogleWorkspaceDomainAlias extends Resource<
+  'GoogleWorkspace.DomainAlias',
+  DomainAliasProps,
+  DomainAliasAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceDomainAlias = Resource<GoogleWorkspaceDomainAlias>(
+  'GoogleWorkspace.DomainAlias',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+const customerOf = (props: DomainAliasProps): string => props.customer ?? 'my_customer';
+
+const attributesOf = (
+  live: directory.DomainAlias,
+  props: DomainAliasProps,
+): DomainAliasAttributes | undefined => {
+  if (live.domainAliasName === undefined || !ciEqual(live.domainAliasName, props.domainAliasName)) {
+    return undefined;
+  }
+  return {
+    creationTime: text(live.creationTime),
+    customer: customerOf(props),
+    domainAliasName: live.domainAliasName,
+    parentDomainName: text(live.parentDomainName),
+    verified: bool(live.verified),
+  };
+};
+
+/** ★ EXPORTED for direct testing — see domain-alias.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  DomainAliasProps,
+  directory.DomainAlias,
+  DomainAliasAttributes,
+  | directory.GetDomainAliasesError
+  | directory.InsertDomainAliasesError
+  | directory.DeleteDomainAliasesError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertDomainAliases({
+      body: { domainAliasName: props.domainAliasName, parentDomainName: props.parentDomainName },
+      customer: customerOf(props),
+    }),
+  describe: (props) => `customer/${customerOf(props)}/domainaliases/${props.domainAliasName}`,
+  destroy: (props, live) =>
+    directory.deleteDomainAliases({
+      customer: customerOf(props),
+      domainAliasName: text(live.domainAliasName) || props.domainAliasName,
+    }),
+  fetchLive: (props) =>
+    directory
+      .getDomainAliases({ customer: customerOf(props), domainAliasName: props.domainAliasName })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) => attributes.parentDomainName === props.parentDomainName,
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceDomainAliasProvider = () =>
+  Provider.effect(
+    GoogleWorkspaceDomainAlias,
+    Effect.succeed(GoogleWorkspaceDomainAlias.Provider.of(handlers)),
+  );

package/src/google-workspace/fake-google-workspace.ts

@@ -0,0 +1,54 @@
+/**
+ * A minimal in-memory Directory API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring
+ * `../netbox/fake-netbox.ts` and `../forgejo/fake-forgejo.ts`. Tests exercise distilled's REAL
+ * path assembly, JSON encode/decode and status→typed-error matching (`404` → `NotFound`, `403` →
+ * `Forbidden`, …) — nothing about that matching is re-implemented here, only the wire responses a
+ * scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. The token is a placeholder that is never a real bearer token, and
+ *   no request this fake answers ever leaves the process.
+ */
+import { type Credentials, fromAccessToken } from '@distilled.cloud/google-workspace/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_TOKEN = 'placeholder-google-workspace-token';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** Google's own `{ error: { code, message, status } }` failure envelope — matching protocol.ts. */
+export const fakeFailure = (status: number, message: string, googleStatus: string) =>
+  Response.json({ error: { code: status, message, status: googleStatus } }, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature. A test that expects no request at all asserts `seen` is empty.
+ */
+export const fakeGoogleWorkspace = (route: (method: string, url: URL) => Response) => {
+  const seen: Seen[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    return route(request.method, url);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen };
+};
+
+/**
+ * distilled Credentials + the real FetchHttpClient over the fake — `GoogleWorkspaceOpContext`,
+ * what every resource file's exported `spec.fetchLive` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers` (each resource file's `googleWorkspaceHandlers(spec)` export).
+ *   `handlers` bakes in `CredentialsFromEnv`, which resolves `GOOGLE_ACCESS_TOKEN` through
+ *   Effect's `Config` — whose default provider snapshots `process.env` once and never re-reads it
+ *   (measured in the forgejo migration, kit PR 180). So a test cannot point `handlers` at a fake
+ *   server; it calls `spec.fetchLive`/`spec.attributes` directly instead, with this explicit
+ *   layer, exercising exactly the same production code without that env seam.
+ */
+export const fakeGoogleWorkspaceLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = fromAccessToken({ accessToken: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));