@homeflare/alchemy 0.29.1 → 0.30.0

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

package/src/google-workspace/group-member.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `GoogleWorkspace.GroupMember`'s `spec` against a fake Directory API — unlike
+ * `Forgejo.TeamMember`, this membership has mutable fields (`role`, `deliverySettings`), so
+ * `matches` can see real drift, not just existence.
+ */
+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 './group-member.ts';
+
+// ⚠️ `@` is percent-encoded by the SDK's own path-token encoder — match the wire form (see the
+//   same note in group.test.ts).
+const MEMBER_PATH =
+  '/admin/directory/v1/groups/team%40schenanigans.com/members/tim%40schenanigans.com';
+const props = {
+  email: 'tim@schenanigans.com',
+  group: 'team@schenanigans.com',
+  role: 'OWNER' as const,
+};
+
+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.GroupMember spec.fetchLive + spec.attributes', () => {
+  test('a live member decodes with its role and delivery settings', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === MEMBER_PATH
+        ? Response.json({
+            delivery_settings: 'ALL_MAIL',
+            email: 'tim@schenanigans.com',
+            id: 'member-1',
+            role: 'OWNER',
+            status: 'ACTIVE',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      deliverySettings: 'ALL_MAIL',
+      email: 'tim@schenanigans.com',
+      group: 'team@schenanigans.com',
+      memberId: 'member-1',
+      role: 'OWNER',
+      status: 'ACTIVE',
+    });
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(404, 'not found', 'NOT_FOUND'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});
+
+describe('GoogleWorkspace.GroupMember spec.matches — role and delivery drift', () => {
+  const live = {
+    deliverySettings: 'ALL_MAIL',
+    email: 'tim@schenanigans.com',
+    group: 'team@schenanigans.com',
+    memberId: 'member-1',
+    role: 'MEMBER',
+    status: 'ACTIVE',
+  };
+
+  test('a declared role different from live is drift', () => {
+    expect(spec.matches(live, props)).toBe(false);
+  });
+
+  test('the same role, and an undeclared deliverySettings converging to ALL_MAIL, is no drift', () => {
+    expect(spec.matches({ ...live, role: 'OWNER' }, props)).toBe(true);
+  });
+
+  test('a declared deliverySettings different from live is drift even with a matching role', () => {
+    expect(
+      spec.matches(
+        { ...live, deliverySettings: 'DIGEST', role: 'OWNER' },
+        {
+          ...props,
+          deliverySettings: 'NONE',
+        },
+      ),
+    ).toBe(false);
+  });
+});

package/src/google-workspace/group-member.ts

@@ -0,0 +1,126 @@
+/**
+ * `GoogleWorkspace.GroupMember` — one user or group's membership in one Directory group.
+ *
+ * ★ WHY THIS DOES NOT MODEL A `GoogleWorkspace.User`. `email` here identifies whoever the group
+ *   member is (a user's primary email, or another group's), the same way Forgejo's
+ *   `TeamMember.username` (team-member.ts) never creates the account it references. The Directory
+ *   API needs no user resource to exist in this family for a membership to be declared — see
+ *   group.ts's own note on why users are out of scope.
+ *
+ * ⚠️ UNLIKE `Forgejo.TeamMember`, A MEMBERSHIP HERE IS NOT EXISTENCE-ONLY. `role`
+ *   (`OWNER`/`MANAGER`/`MEMBER`) and `deliverySettings` (`ALL_MAIL`/`DIGEST`/`DAILY`/`NONE`/
+ *   `DISABLED`) are both mutable in place via `patchMembers` — so this spec declares `update`,
+ *   not `upsert`, the same shape `group.ts`/`domain-alias.ts` use.
+ *
+ * ⛔ GROUP CYCLES ARE THE VENDOR'S TO REFUSE, NOT THIS FAMILY'S. `insertMembers`/`patchMembers`
+ *   surface a cycle as `BadRequest`, which this spec's error union already carries un-narrowed —
+ *   nothing here guesses at "member is itself an ancestor group".
+ */
+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 { ciEqual, text } from './values.ts';
+
+export type MemberRole = 'OWNER' | 'MANAGER' | 'MEMBER';
+export type DeliverySettings = 'ALL_MAIL' | 'DIGEST' | 'DAILY' | 'NONE' | 'DISABLED';
+
+export interface GroupMemberProps {
+  /** The group's email, alias or id — same key `Group.email` declares. */
+  group: string;
+  /** The member's email (a user or another group). Primary key alongside `group`. */
+  email: string;
+  /** @default 'MEMBER' */
+  role?: MemberRole;
+  /** @default 'ALL_MAIL' */
+  deliverySettings?: DeliverySettings;
+}
+
+export interface GroupMemberAttributes {
+  group: string;
+  email: string;
+  memberId: string;
+  role: string;
+  deliverySettings: string;
+  /** Read-only — `ACTIVE` for a normal member, `PENDING` while an invite is outstanding. */
+  status: string;
+}
+
+export interface GoogleWorkspaceGroupMember extends Resource<
+  'GoogleWorkspace.GroupMember',
+  GroupMemberProps,
+  GroupMemberAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceGroupMember = Resource<GoogleWorkspaceGroupMember>(
+  'GoogleWorkspace.GroupMember',
+);
+
+const defaultRole = (props: GroupMemberProps): MemberRole => props.role ?? 'MEMBER';
+const defaultDelivery = (props: GroupMemberProps): DeliverySettings =>
+  props.deliverySettings ?? 'ALL_MAIL';
+
+const attributesOf = (
+  live: directory.Member,
+  props: GroupMemberProps,
+): GroupMemberAttributes | undefined => {
+  if (live.email === undefined || !ciEqual(live.email, props.email)) return undefined;
+  return {
+    deliverySettings: text(live.delivery_settings),
+    email: live.email,
+    group: props.group,
+    memberId: text(live.id),
+    role: text(live.role),
+    status: text(live.status),
+  };
+};
+
+/** ★ EXPORTED for direct testing — see group-member.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  GroupMemberProps,
+  directory.Member,
+  GroupMemberAttributes,
+  | directory.GetMembersError
+  | directory.InsertMembersError
+  | directory.PatchMembersError
+  | directory.DeleteMembersError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertMembers({
+      body: {
+        delivery_settings: defaultDelivery(props),
+        email: props.email,
+        role: defaultRole(props),
+      },
+      groupKey: props.group,
+    }),
+  describe: (props) => `groups/${props.group}/members/${props.email}`,
+  destroy: (props, live) =>
+    directory.deleteMembers({ groupKey: props.group, memberKey: text(live.id) || props.email }),
+  fetchLive: (props) =>
+    directory
+      .getMembers({ groupKey: props.group, memberKey: props.email })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.role === defaultRole(props) &&
+    attributes.deliverySettings === defaultDelivery(props),
+  update: (props, live) =>
+    directory.patchMembers({
+      body: { delivery_settings: defaultDelivery(props), role: defaultRole(props) },
+      groupKey: props.group,
+      memberKey: text(live.id) || props.email,
+    }),
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceGroupMemberProvider = () =>
+  Provider.effect(
+    GoogleWorkspaceGroupMember,
+    Effect.succeed(GoogleWorkspaceGroupMember.Provider.of(handlers)),
+  );

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

@@ -0,0 +1,93 @@
+/**
+ * `GoogleWorkspace.Group`'s `spec` against a fake Directory API — get-by-key, unlike NetBox's
+ * list-then-disambiguate (resource.ts's own note on why this family never needs `locateOne`).
+ */
+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 './group.ts';
+
+// ⚠️ `@` is percent-encoded by the SDK's own path-token encoder (`encodeURIComponent`), and
+//   `URL#pathname` does not decode an already-encoded sequence back — match the wire form.
+const GROUP_PATH = '/admin/directory/v1/groups/team%40schenanigans.com';
+const props = { email: 'team@schenanigans.com', name: 'Team', description: 'the team' };
+
+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.Group spec.fetchLive + spec.attributes', () => {
+  test('a live group decodes into the full attribute set — adopt(true) exact-as-live', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({
+            adminCreated: true,
+            aliases: ['old-team@schenanigans.com'],
+            description: 'the team',
+            directMembersCount: '3',
+            email: 'team@schenanigans.com',
+            id: '01234567890',
+            name: 'Team',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      adminCreated: true,
+      aliases: ['old-team@schenanigans.com'],
+      description: 'the team',
+      directMembersCount: '3',
+      email: 'team@schenanigans.com',
+      groupId: '01234567890',
+      name: 'Team',
+      nonEditableAliases: [],
+    });
+  });
+
+  test('a 404 folds to undefined — the standard "not created yet" case', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(404, 'not found', 'NOT_FOUND'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+
+  test('a 403 propagates unfolded — never treated as absent', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(403, 'forbidden', 'PERMISSION_DENIED'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('GoogleWorkspace.Group spec.matches', () => {
+  const live = {
+    adminCreated: false,
+    aliases: [],
+    description: 'the team',
+    directMembersCount: '0',
+    email: 'team@schenanigans.com',
+    groupId: 'x',
+    name: 'Team',
+    nonEditableAliases: [],
+  };
+
+  test('declared description and name equal to live — no drift', () => {
+    expect(spec.matches(live, props)).toBe(true);
+  });
+
+  test('a changed description is drift', () => {
+    expect(spec.matches(live, { ...props, description: 'a different team' })).toBe(false);
+  });
+
+  test('an undeclared name converges to the email local-part deterministically', () => {
+    const { name: _name, ...withoutName } = props;
+    expect(spec.matches({ ...live, name: 'team' }, withoutName)).toBe(true);
+    expect(spec.matches(live, withoutName)).toBe(false);
+  });
+});