@homeflare/alchemy 0.27.1 → 0.27.3

package/src/forgejo/org-actions-secrets.ts

@@ -1,36 +1,32 @@
 /**
  * `Forgejo.OrgSecret` — org-level Actions secret metadata at `/orgs/{org}/actions/secrets/{name}`.
  *
- * ★ CHOICE: AUTHORED WITH WRITE-ONLY VALUE VIA ENV, NOT REFUSED. The OpenAPI in
- *   `<estate>/mcp-servers/docs/api/upstream/forgejo.json` shows `Secret` returns only `name` and
- *   `created_at` — never the `data` field — so attributes stay metadata-only. Create/update is PUT
- *   with body `{ data }`, which does not fit POST/PATCH; this family uses the `upsert` seam on
- *   `ForgejoSpec` instead of hand-rolling provider handlers.
+ * ★ CHOICE: AUTHORED WITH WRITE-ONLY VALUE VIA ENV, NOT REFUSED. `organization.Secret` (the
+ *   package's typed output) has only `name` and `created_at` — never `data` — so attributes stay
+ *   metadata-only. Create/update is `updateOrgSecret`, a PUT with `{ data }`, which does not fit
+ *   POST/PATCH; this family uses the `upsert` seam on `ForgejoSpec` instead of a plain create.
  *
  * ⛔ THE SECRET VALUE IS NEVER A PROP OR AN ATTRIBUTE. It is read from `FORGEJO_ORG_SECRET_{org}_{name}`
  *   (see orgSecretEnvKey) at PUT time when the name is absent from the list. Once present, reconcile
  *   noops — the API cannot confirm the value matches, and re-PUT on every deploy would rotate
  *   unintentionally. Rotate by destroy-then-create or a manual PUT outside Alchemy.
  *
- * ⚠️ PUT ANSWERS 201/204 WITH NO BODY — client.ts treats empty responses as `undefined`; read-back
- *   uses the list endpoint, not the PUT response.
- *
  * ⛔ TOKEN NEEDS `write:organization` TO PUT — list needs `read:organization`.
  *
  * ⛔ THE FILE NAME IS PLURAL ON PURPOSE AND MUST STAY THAT WAY. `.gitignore:198` carries
  *   `*-secret.*` — the rule that stops `client-secret.json` and friends being committed — and it
  *   matches a SOURCE file called `org-secret.ts` just as happily. This family was first authored
  *   under that name: it existed on disk, typechecked, passed oxlint, was imported by alchemy.run.ts
- *   and appeared in NO `git status`. It would have been committed as a broken import for everyone
- *   else, with the local tree green the whole time. `scripts/husky/ignored-imports.ts` is the gate
- *   that now catches the class; this comment is for whoever is tempted to rename it back.
+ *   and appeared in NO `git status`. `scripts/husky/ignored-imports.ts` is the gate that now
+ *   catches the class; this comment is for whoever is tempted to rename it back.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as organization from '@distilled.cloud/forgejo/organization';
+import * as Data from 'effect/Data';
 import * as Effect from 'effect/Effect';
-import { ForgejoError, forgejo } from './client.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { orgSecretEnvKey, text } from './values.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { orgSecretEnvKey } from './values.ts';
 
 export interface OrgSecretProps {
   org: string;
@@ -54,46 +50,58 @@ export interface ForgejoOrgSecret extends Resource<
 
 export const ForgejoOrgSecret = Resource<ForgejoOrgSecret>('Forgejo.OrgSecret');
 
+/** Domain refusal, not a distilled error — the env var this family reads the secret value from is unset. */
+export class ForgejoSecretEnvUnsetError extends Data.TaggedError('ForgejoSecretEnvUnsetError')<{
+  readonly message: string;
+}> {}
+
 const secretData = (org: string, name: string) =>
   Effect.gen(function* () {
     const key = orgSecretEnvKey(org, name);
     const raw = process.env[key];
     if (raw === undefined || raw.trim() === '') {
       return yield* Effect.fail(
-        new ForgejoError(
-          0,
-          'PUT',
-          `orgs/${org}/actions/secrets/${name}`,
-          `${key} is unset. Export the secret value there — never as an Alchemy prop.`,
-        ),
+        new ForgejoSecretEnvUnsetError({
+          message: `${key} is unset. Export the secret value there — never as an Alchemy prop.`,
+        }),
       );
     }
     return raw.trim();
   });
 
-const handlers = forgejoHandlers<OrgSecretProps, OrgSecretAttributes>({
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  OrgSecretProps,
+  organization.Secret,
+  OrgSecretAttributes,
+  | organization.OrgListActionsSecretsError
+  | organization.UpdateOrgSecretError
+  | organization.DeleteOrgSecretError
+  | ForgejoSecretEnvUnsetError
+> = {
   attributes: (live, props) => ({
-    createdAt: text(live['created_at']),
+    createdAt: live.created_at,
     name: props.name,
     org: props.org,
   }),
-  collection: (props) => `orgs/${props.org}/actions/secrets/${props.name}`,
-  createForm: () => ({}),
-  locate: (props) =>
-    forgejo<Record<string, unknown>[]>('GET', `orgs/${props.org}/actions/secrets?limit=200`).pipe(
-      Effect.map((rows) =>
-        Array.isArray(rows) ? rows.find((row) => row['name'] === props.name) : undefined,
-      ),
+  destroy: (props) => organization.deleteOrgSecret({ org: props.org, secretname: props.name }),
+  fetchLive: (props) =>
+    organization.orgListActionsSecrets({ org: props.org, limit: 200 }).pipe(
+      Effect.map((rows) => rows.find((row) => row.name === props.name)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
     ),
   matches: () => true,
-  path: (props) => `orgs/${props.org}/actions/secrets/${props.name}`,
   upsert: (props, before) =>
-    Effect.gen(function* () {
-      if (before !== undefined) return;
-      const data = yield* secretData(props.org, props.name);
-      yield* forgejo('PUT', `orgs/${props.org}/actions/secrets/${props.name}`, { data });
-    }),
-});
+    before !== undefined
+      ? Effect.void
+      : Effect.flatMap(secretData(props.org, props.name), (data) =>
+          Effect.asVoid(
+            organization.updateOrgSecret({ data, org: props.org, secretname: props.name }),
+          ),
+        ),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoOrgSecretProvider = () =>
   Provider.effect(ForgejoOrgSecret, Effect.succeed(ForgejoOrgSecret.Provider.of(handlers)));

package/src/forgejo/org-label.test.ts

@@ -0,0 +1,100 @@
+/**
+ * `Forgejo.OrgLabel`'s `fetchLive` against a fake Forgejo — the "list, then find by name" pattern
+ * (labels, teams, hooks and org secrets all share it, since Gitea addresses them by numeric id,
+ * not name). Two absent cases fold to `undefined` the same way, for different reasons:
+ *
+ * - the org itself is gone: `orgListLabels` answers a real distilled `NotFound` (404), caught by
+ *   the same `catchTag('NotFound', ...)` idiom every `fetchLive` in this family ends with.
+ * - the org exists but has no label by that name: the list call succeeds, and `.find()` returns
+ *   `undefined` on its own — no error, let alone a typed one, is involved.
+ *
+ * A 401 on the list still propagates unfolded, same as repository.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as organization from '@distilled.cloud/forgejo/organization';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeForgejo, fakeForgejoLayer } from './fake-forgejo.ts';
+import { spec } from './org-label.ts';
+
+const LABELS_PATH = '/api/v1/orgs/homeflare/labels';
+
+const fetchLabel = (fetchFn: typeof globalThis.fetch, name: string) =>
+  organization.orgListLabels({ limit: 200, org: 'homeflare' }).pipe(
+    Effect.map((rows) => rows.find((row) => row.name === name)),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+    Effect.provide(fakeForgejoLayer(fetchFn)),
+  );
+
+describe('Forgejo.OrgLabel fetchLive', () => {
+  test('a live label matched by name decodes into the typed row', async () => {
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === LABELS_PATH
+        ? Response.json([{ color: 'ff0000', id: 7, name: 'bug' }])
+        : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(fetchLabel(fake.fetch, 'bug'));
+    expect(live?.id).toBe(7);
+  });
+
+  test('a name absent from a successful list is undefined — no error at all', async () => {
+    const fake = fakeForgejo(() => Response.json([{ color: 'ff0000', id: 7, name: 'bug' }]));
+    const live = await Effect.runPromise(fetchLabel(fake.fetch, 'enhancement'));
+    expect(live).toBeUndefined();
+  });
+
+  test('the org itself missing (404 on the list) folds to undefined too', async () => {
+    const fake = fakeForgejo(() => fakeFailure(404, 'org does not exist'));
+    const live = await Effect.runPromise(fetchLabel(fake.fetch, 'bug'));
+    expect(live).toBeUndefined();
+  });
+
+  test('a 401 on the list propagates — never folded to absent', async () => {
+    // ⚠️ 401 rather than 403: `orgListLabels` only declares `NotFound` beyond the shared default
+    //   channel — Unauthorized is in that shared set for every operation regardless.
+    const fake = fakeForgejo(() => fakeFailure(401, 'bad token'));
+    const failure = await Effect.runPromise(Effect.flip(fetchLabel(fake.fetch, 'bug')));
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('Forgejo.OrgLabel spec — the actual exported production functions', () => {
+  // ⛔ Proves the real `fetchLive` + `attributes` in org-label.ts, not a parallel
+  //   reimplementation — see the same note in repository.test.ts.
+  const props = { color: 'ff0000', name: 'bug', org: 'homeflare' };
+
+  const readThrough = (fetchFn: typeof globalThis.fetch) =>
+    Effect.runPromise(
+      spec.fetchLive(props).pipe(
+        Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+        Effect.provide(fakeForgejoLayer(fetchFn)),
+      ),
+    );
+
+  test('spec.fetchLive + spec.attributes match the old field mapping', async () => {
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === LABELS_PATH
+        ? Response.json([
+            { color: 'FF0000', description: 'something is broken', id: 7, name: 'bug' },
+          ])
+        : fakeFailure(404, 'not found'),
+    );
+    // ⚠️ `color()` lowercases — the wire value `FF0000` must compare equal to the declared `ff0000`.
+    expect(await readThrough(fake.fetch)).toEqual({
+      color: 'ff0000',
+      description: 'something is broken',
+      exclusive: false,
+      labelId: 7,
+      name: 'bug',
+      org: 'homeflare',
+    });
+  });
+
+  test('a label absent from the list through spec.fetchLive is undefined', async () => {
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === LABELS_PATH
+        ? Response.json([{ color: '00ff00', id: 9, name: 'enhancement' }])
+        : fakeFailure(404, 'not found'),
+    );
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});

package/src/forgejo/org-label.ts

@@ -12,18 +12,19 @@
  *   from the stack does not DELETE it unless the caller opts into `.pipe(RemovalPolicy.destroy())`.
  *   That matches the script's never-delete posture while still allowing a deliberate destroy.
  *
- * ⚠️ THE WIRE PATH USES NUMERIC ID, NOT NAME — measured on live org labels: PATCH and DELETE are
- *   `/orgs/{org}/labels/{id}`. `locate` lists by name; `wirePath` uses the id from that row.
+ * ⚠️ THE WIRE PATH USES NUMERIC ID, NOT NAME — measured on live org labels: edit and delete are
+ *   `orgEditLabel`/`orgDeleteLabel({ org, id })`. `fetchLive` lists by name; the id comes off that
+ *   row for `update`/`destroy`, the same seam the hand-rolled `wirePath` used.
  *
  * ⛔ TOKEN NEEDS `write:organization` FOR RECONCILE — the mcp-read token lacks it (POST 403
  *   measured 2026-09-13). Plan/deploy needs a provision-scoped credential in `FORGEJO_TOKEN`.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as organization from '@distilled.cloud/forgejo/organization';
 import * as Effect from 'effect/Effect';
-import { forgejo } from './client.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, color, text } from './values.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { color } from './values.ts';
 
 export interface OrgLabelProps {
   /** Organization login — `homeflare` / `HomeFlare` must match the live org. */
@@ -57,44 +58,53 @@ export const ForgejoOrgLabel = Resource<ForgejoOrgLabel>('Forgejo.OrgLabel', {
   defaultRemovalPolicy: 'retain',
 });
 
-const handlers = forgejoHandlers<OrgLabelProps, OrgLabelAttributes>({
-  attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      color: color(live['color']),
-      description: text(live['description']),
-      exclusive: bool(live['exclusive']),
-      labelId: id,
-      name: props.name,
-      org: props.org,
-    };
-  },
-  collection: (props) => `orgs/${props.org}/labels`,
-  createForm: (props) => ({
-    color: color(props.color),
-    description: props.description ?? '',
-    exclusive: props.exclusive ?? false,
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  OrgLabelProps,
+  organization.Label,
+  OrgLabelAttributes,
+  | organization.OrgCreateLabelError
+  | organization.OrgEditLabelError
+  | organization.OrgDeleteLabelError
+  | organization.OrgListLabelsError
+> = {
+  attributes: (live, props) => ({
+    color: color(live.color),
+    description: live.description ?? '',
+    exclusive: live.exclusive ?? false,
+    labelId: live.id,
     name: props.name,
+    org: props.org,
   }),
-  locate: (props) =>
-    forgejo<Record<string, unknown>[]>('GET', `orgs/${props.org}/labels?limit=200`).pipe(
-      Effect.map((rows) =>
-        Array.isArray(rows) ? rows.find((row) => row['name'] === props.name) : undefined,
-      ),
+  create: (props) =>
+    organization.orgCreateLabel({
+      color: color(props.color),
+      description: props.description ?? '',
+      exclusive: props.exclusive ?? false,
+      name: props.name,
+      org: props.org,
+    }),
+  destroy: (props, live) => organization.orgDeleteLabel({ org: props.org, id: live.id }),
+  fetchLive: (props) =>
+    organization.orgListLabels({ org: props.org, limit: 200 }).pipe(
+      Effect.map((rows) => rows.find((row) => row.name === props.name)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
     ),
   matches: (attributes, props) =>
     attributes.color === color(props.color) &&
     attributes.description === (props.description ?? '') &&
     attributes.exclusive === (props.exclusive ?? false),
-  path: (props) => `orgs/${props.org}/labels/${props.name}`,
-  updateForm: (props) => ({
-    color: color(props.color),
-    description: props.description ?? '',
-    exclusive: props.exclusive ?? false,
-  }),
-  wirePath: (props, live) => `orgs/${props.org}/labels/${String(live['id'])}`,
-});
+  update: (props, live) =>
+    organization.orgEditLabel({
+      color: color(props.color),
+      description: props.description ?? '',
+      exclusive: props.exclusive ?? false,
+      id: live.id,
+      org: props.org,
+    }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoOrgLabelProvider = () =>
   Provider.effect(ForgejoOrgLabel, Effect.succeed(ForgejoOrgLabel.Provider.of(handlers)));

package/src/forgejo/org-team.ts

@@ -3,24 +3,31 @@
  *
  * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json` (Forgejo 16.x OpenAPI): create is
  *   `POST /orgs/{org}/teams`; read/update/delete use numeric id at `/teams/{id}` — not the name.
+ *   Now `organization.orgCreateTeam` / `orgListTeams` / `orgEditTeam` / `orgDeleteTeam`.
  *
- * ⚠️ PATCH AND DELETE USE `/teams/{id}` — same seam as org labels. `locate` lists by name;
- *   `wirePath` carries the id from that row.
+ * ⚠️ `orgEditTeam`/`orgDeleteTeam` TAKE ONLY `{ id, ... }` — NO `org` FIELD. The package's schema
+ *   confirms Forgejo's edit/delete routes are `/teams/{id}` with no org segment; `fetchLive` lists
+ *   by name and `update`/`destroy` carry the id off that row, same seam as org labels.
+ *
+ * ⚠️ `live.permission` IS TYPED `"none" | "read" | "write" | "admin" | "owner"` IN THE PACKAGE —
+ *   wider than this family's own `TeamPermission`. The guard below keeps the original behaviour:
+ *   an out-of-range value (`none`/`owner`) folds `attributes` to `undefined` rather than lying
+ *   about which of the three this family manages the team is at.
  *
  * ⛔ TOKEN NEEDS `write:organization` TO CREATE OR PATCH — read list/get needs `read:organization`.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as organization from '@distilled.cloud/forgejo/organization';
 import * as Effect from 'effect/Effect';
-import { forgejo } from './client.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, recordEqual, stringArray, stringRecord, text } from './values.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { recordEqual, stringArray, stringRecord } from './values.ts';
 
 export type TeamPermission = 'read' | 'write' | 'admin';
 
 export interface OrgTeamProps {
   org: string;
-  /** Team name — primary locate key; sent on every PATCH body. */
+  /** Team name — primary locate key; sent on every edit body. */
   name: string;
   description?: string;
   permission?: TeamPermission;
@@ -62,31 +69,37 @@ const teamForm = (props: OrgTeamProps) => ({
   ...(props.unitsMap === undefined ? {} : { units_map: props.unitsMap }),
 });
 
-const handlers = forgejoHandlers<OrgTeamProps, OrgTeamAttributes>({
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  OrgTeamProps,
+  organization.Team,
+  OrgTeamAttributes,
+  | organization.OrgCreateTeamError
+  | organization.OrgEditTeamError
+  | organization.OrgDeleteTeamError
+  | organization.OrgListTeamsError
+> = {
   attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    const permission = text(live['permission'], 'read');
+    const permission = live.permission ?? 'read';
     if (permission !== 'read' && permission !== 'write' && permission !== 'admin') return undefined;
     return {
-      canCreateOrgRepo: bool(live['can_create_org_repo']),
-      description: text(live['description']),
-      includesAllRepositories: bool(live['includes_all_repositories']),
+      canCreateOrgRepo: live.can_create_org_repo ?? false,
+      description: live.description ?? '',
+      includesAllRepositories: live.includes_all_repositories ?? false,
       name: props.name,
       org: props.org,
       permission,
-      teamId: id,
-      units: stringArray(live['units']),
-      unitsMap: stringRecord(live['units_map']),
+      teamId: live.id,
+      units: stringArray(live.units ?? []),
+      unitsMap: stringRecord(live.units_map ?? {}),
     };
   },
-  collection: (props) => `orgs/${props.org}/teams`,
-  createForm: teamForm,
-  locate: (props) =>
-    forgejo<Record<string, unknown>[]>('GET', `orgs/${props.org}/teams?limit=200`).pipe(
-      Effect.map((rows) =>
-        Array.isArray(rows) ? rows.find((row) => row['name'] === props.name) : undefined,
-      ),
+  create: (props) => organization.orgCreateTeam({ org: props.org, ...teamForm(props) }),
+  destroy: (_props, live) => organization.orgDeleteTeam({ id: live.id }),
+  fetchLive: (props) =>
+    organization.orgListTeams({ org: props.org, limit: 200 }).pipe(
+      Effect.map((rows) => rows.find((row) => row.name === props.name)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
     ),
   matches: (attributes, props) =>
     attributes.description === (props.description ?? '') &&
@@ -96,10 +109,10 @@ const handlers = forgejoHandlers<OrgTeamProps, OrgTeamAttributes>({
     (props.units === undefined ||
       stringArray(props.units).join('\0') === attributes.units.join('\0')) &&
     (props.unitsMap === undefined || recordEqual(attributes.unitsMap, props.unitsMap)),
-  path: (props) => `orgs/${props.org}/teams/${props.name}`,
-  updateForm: teamForm,
-  wirePath: (_props, live) => `teams/${String(live['id'])}`,
-});
+  update: (props, live) => organization.orgEditTeam({ id: live.id, ...teamForm(props) }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoOrgTeamProvider = () =>
   Provider.effect(ForgejoOrgTeam, Effect.succeed(ForgejoOrgTeam.Provider.of(handlers)));

package/src/forgejo/repo-webhook-form.ts

@@ -1,15 +1,20 @@
 /**
- * JSON bodies for `Forgejo.RepoWebhook` — split to keep repo-webhook.ts under the line cap.
+ * `config` bodies for `Forgejo.RepoWebhook` — split to keep repo-webhook.ts under the line cap.
  *
  * ⛔ `config.secret` IS NEVER A PROP. When present it is read from `FORGEJO_HOOK_SECRET_*` at
  *   create/update time only (see hookSecretEnvKey in values.ts). Alchemy attributes are Postgres
  *   plaintext — a webhook HMAC secret must not be stored there.
+ *
+ * ⛔ NO `name` FIELD ON EITHER SIDE. `@distilled.cloud/forgejo`'s `RepoCreateHookRequest` and
+ *   `Hook` (the create input and the read/list output) have no `name` property — verified against
+ *   the package's schema. The hand-rolled client sent `name: props.name` on create anyway; Gitea's
+ *   JSON decoder silently dropped it, so `locate` never actually matched by name either (its
+ *   `row['name']` read was always `undefined` on an untyped response) — matching was always by
+ *   URL in practice. `props.name`/`RepoWebhookAttributes.name` stay as this family's own stable
+ *   key; nothing on the wire carries it.
  */
 import type { RepoWebhookProps } from './repo-webhook.ts';
-import { hookSecretEnvKey, stringRecord, text } from './values.ts';
-
-export const hookUrl = (live: Record<string, unknown>) =>
-  text(live['url']) || text(stringRecord(live['config'])['url']);
+import { hookSecretEnvKey } from './values.ts';
 
 export const hookConfigForm = (props: RepoWebhookProps, includeSecret: boolean) => {
   const config: Record<string, string> = {
@@ -23,25 +28,3 @@ export const hookConfigForm = (props: RepoWebhookProps, includeSecret: boolean)
   }
   return config;
 };
-
-export const createHookForm = (props: RepoWebhookProps) => ({
-  active: props.active ?? true,
-  ...(props.authorizationHeader === undefined
-    ? {}
-    : { authorization_header: props.authorizationHeader }),
-  ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
-  config: hookConfigForm(props, true),
-  events: props.events,
-  name: props.name,
-  type: props.type,
-});
-
-export const updateHookForm = (props: RepoWebhookProps) => ({
-  active: props.active ?? true,
-  ...(props.authorizationHeader === undefined
-    ? {}
-    : { authorization_header: props.authorizationHeader }),
-  ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
-  config: hookConfigForm(props, false),
-  events: props.events,
-});

package/src/forgejo/repo-webhook.ts

@@ -2,7 +2,13 @@
  * `Forgejo.RepoWebhook` — one repository webhook under `/repos/{owner}/{repo}/hooks`.
  *
  * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection; read/update/delete
- *   use numeric hook id at `/repos/{owner}/{repo}/hooks/{id}`. `locate` lists and matches on `name`.
+ *   use numeric hook id at `/repos/{owner}/{repo}/hooks/{id}`. Now `repository.repoCreateHook` /
+ *   `repoListHooks` / `repoEditHook` / `repoDeleteHook`. `fetchLive` lists and matches on `url` —
+ *   see repo-webhook-form.ts for why name was never the real match key.
+ *
+ * ⚠️ `Hook.url` IS A REQUIRED STRING IN THE PACKAGE'S SCHEMA — the `config.url` fallback the
+ *   hand-rolled client carried (`stringRecord(live['config'])['url']`) is gone; a response
+ *   without `url` now fails the operation's decode.
  *
  * ⛔ NO WEBHOOK `secret` IN PROPS OR ATTRIBUTES. Optional HMAC material is env-only at write time
  *   (`FORGEJO_HOOK_SECRET_*` — see repo-webhook-form.ts). `hookConfigPublic` strips `secret` on read.
@@ -11,11 +17,11 @@
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as repository from '@distilled.cloud/forgejo/repository';
 import * as Effect from 'effect/Effect';
-import { forgejo } from './client.ts';
-import { createHookForm, hookUrl, updateHookForm } from './repo-webhook-form.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, hookConfigPublic, stringArray, text } from './values.ts';
+import { hookConfigForm } from './repo-webhook-form.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { hookConfigPublic, stringArray } from './values.ts';
 
 export type RepoWebhookType =
   | 'dingtalk'
@@ -33,7 +39,7 @@ export type RepoWebhookType =
 export interface RepoWebhookProps {
   owner: string;
   repo: string;
-  /** Stable locate key — also sent as Hook.name on create. */
+  /** Stable locate key on this side only — Forgejo hooks have no `name` field (see the form file). */
   name: string;
   type: RepoWebhookType;
   url: string;
@@ -68,38 +74,51 @@ export interface ForgejoRepoWebhook extends Resource<
 
 export const ForgejoRepoWebhook = Resource<ForgejoRepoWebhook>('Forgejo.RepoWebhook');
 
-const handlers = forgejoHandlers<RepoWebhookProps, RepoWebhookAttributes>({
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  RepoWebhookProps,
+  repository.Hook,
+  RepoWebhookAttributes,
+  | repository.RepoCreateHookError
+  | repository.RepoEditHookError
+  | repository.RepoDeleteHookError
+  | repository.RepoListHooksError
+> = {
   attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    const config = hookConfigPublic(live['config']);
-    const type = text(live['type']);
+    const config = hookConfigPublic(live.config);
     return {
-      active: bool(live['active'], true),
-      authorizationHeader: text(live['authorization_header']),
-      branchFilter: text(live['branch_filter']),
-      contentType: text(config['content_type'], text(live['content_type'], 'json')),
-      events: stringArray(live['events']),
-      hookId: id,
+      active: live.active ?? true,
+      authorizationHeader: live.authorization_header ?? '',
+      branchFilter: live.branch_filter ?? '',
+      contentType: config['content_type'] ?? live.content_type ?? 'json',
+      events: stringArray(live.events ?? []),
+      hookId: live.id,
       name: props.name,
       owner: props.owner,
       repo: props.repo,
-      type: type as RepoWebhookType,
-      url: hookUrl(live),
+      type: live.type as RepoWebhookType,
+      url: live.url,
     };
   },
-  collection: (props) => `repos/${props.owner}/${props.repo}/hooks`,
-  createForm: createHookForm,
-  locate: (props) =>
-    forgejo<Record<string, unknown>[]>(
-      'GET',
-      `repos/${props.owner}/${props.repo}/hooks?limit=200`,
-    ).pipe(
-      Effect.map((rows) =>
-        Array.isArray(rows)
-          ? rows.find((row) => text(row['name']) === props.name || hookUrl(row) === props.url)
-          : undefined,
-      ),
+  create: (props) =>
+    repository.repoCreateHook({
+      active: props.active ?? true,
+      ...(props.authorizationHeader === undefined
+        ? {}
+        : { authorization_header: props.authorizationHeader }),
+      ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
+      config: hookConfigForm(props, true),
+      events: props.events,
+      owner: props.owner,
+      repo: props.repo,
+      type: props.type,
+    }),
+  destroy: (props, live) =>
+    repository.repoDeleteHook({ owner: props.owner, repo: props.repo, id: live.id }),
+  fetchLive: (props) =>
+    repository.repoListHooks({ owner: props.owner, repo: props.repo, limit: 200 }).pipe(
+      Effect.map((rows) => rows.find((row) => row.url === props.url)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
     ),
   matches: (attributes, props) =>
     attributes.type === props.type &&
@@ -109,10 +128,22 @@ const handlers = forgejoHandlers<RepoWebhookProps, RepoWebhookAttributes>({
     attributes.branchFilter === (props.branchFilter ?? '') &&
     attributes.authorizationHeader === (props.authorizationHeader ?? '') &&
     stringArray(props.events).join('\0') === attributes.events.join('\0'),
-  path: (props) => `repos/${props.owner}/${props.repo}/hooks/${props.name}`,
-  updateForm: updateHookForm,
-  wirePath: (props, live) => `repos/${props.owner}/${props.repo}/hooks/${String(live['id'])}`,
-});
+  update: (props, live) =>
+    repository.repoEditHook({
+      active: props.active ?? true,
+      ...(props.authorizationHeader === undefined
+        ? {}
+        : { authorization_header: props.authorizationHeader }),
+      ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
+      config: hookConfigForm(props, false),
+      events: props.events,
+      id: live.id,
+      owner: props.owner,
+      repo: props.repo,
+    }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoRepoWebhookProvider = () =>
   Provider.effect(ForgejoRepoWebhook, Effect.succeed(ForgejoRepoWebhook.Provider.of(handlers)));