@homeflare/alchemy 0.27.0 → 0.27.2

package/src/cloudflare/r2-bucket-lock.ts

@@ -14,16 +14,17 @@ import { Resource, type ResourceClass } from 'alchemy/Resource';
  *   every gate completely green. The operator's rule (2026-09-15) is to cover such a gap with a
  *   custom resource over the vendor's SDK, which is what this is.
  *
- * ⛔ THE SDK ALREADY HAD IT, AND THAT IS WORTH SAYING BECAUSE IT DECIDED THE SHAPE. Measured
- *   2026-09-15 in `cloudflare@4.5.0`, `resources/r2/buckets/locks.d.ts`:
- *
- *       update(bucketName: string, params: LockUpdateParams, options?): APIPromise<…>
- *       get(bucketName: string, params: LockGetParams, options?): APIPromise<LockGetResponse>
- *
- *   over `PUT`/`GET /accounts/{account_id}/r2/buckets/{bucket_name}/lock` with the jurisdiction
- *   carried as the `cf-r2-jurisdiction` header (`locks.mjs:17` and `:41`). So there is no raw
- *   `client.put` fallback here and no path string this package invented — the fallback the rule
- *   allows was not needed.
+ * ★ OVER `@distilled.cloud/cloudflare/r2`, THE SAME SDK `Cloudflare.MeshNode` USES
+ *   (mesh-node-api.ts), NOT THE `cloudflare` NPM SDK THIS RESOURCE USED TO CALL. Measured
+ *   2026-09-23 in distilled `1.0.0-rc.12` (the version alchemy@2.0.0-beta.79 pins),
+ *   `packages/cloudflare/src/services/r2.ts`: `getBucketLock` / `putBucketLock` cover the same
+ *   `GET`/`PUT /accounts/{account_id}/r2/buckets/{bucket_name}/lock` route the old SDK's
+ *   `r2.buckets.locks.get`/`.update` did — same `rules[]` body, the `cf-r2-jurisdiction` header
+ *   spelled as the `jurisdiction` field — but typed as `NoSuchBucket | InvalidRoute |
+ *   CloudflareRateLimited | CloudflareError` instead of an opaque HTTP status, so the "bucket
+ *   does not exist yet" case below is `catchTag('NoSuchBucket', …)`, never a status check. This
+ *   is also the swap that lets `client.ts` (the hand-rolled `cloudflare@4.5.0` wrapper) go away:
+ *   nothing else in the kit imported it.
  *
  * ⚠️ THE RULE SET IS A REPLACE, NOT A MERGE. `PUT` takes the WHOLE list, exactly like R2's
  *   lifecycle rules — which is the trap a consuming stack records for
@@ -31,10 +32,12 @@ import { Resource, type ResourceClass } from 'alchemy/Resource';
  *   drop them, so `read` fetches them first and `reconcile` refuses to write when they already
  *   match.
  */
-import type Cloudflare from 'cloudflare';
-import { NotFoundError } from 'cloudflare';
+import type { CloudflareOpContext } from '@distilled.cloud/cloudflare/r2';
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as r2 from '@distilled.cloud/cloudflare/r2';
+import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
-import { CloudflareApi } from './client.ts';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
 import {
   type Jurisdiction,
   type R2LockRule,
@@ -95,10 +98,12 @@ export const R2BucketLock: ResourceClass<R2BucketLock> = Resource<R2BucketLock>(
  *   exist yet: `404 {"success":false,"errors":[{"code":10006,"message":"The specified bucket does
  *   not exist."}]}` — raised from `read`, during PLANNING, before anything is created. Alchemy
  *   calls `read` for a resource with no prior state, so on every first deploy the lock is asked
- *   about a bucket the same plan is about to create. Letting that throw makes the resource
- *   impossible to plan; swallowing it with `catchAll` would also hide a 403 from a mis-scoped
- *   token, which is the failure this estate spends the most time on. So: 404 → absent, everything
- *   else propagates.
+ *   about a bucket the same plan is about to create. Code 10006 is exactly distilled's
+ *   `NoSuchBucket` tag (r2.ts's error matcher, `[{ code: 10006 }]`), so `catchTag` on it is the
+ *   same case the status check used to cover — but by the vendor's own error identity, not by
+ *   reading a number off the response. Letting it propagate would make the resource impossible to
+ *   plan; swallowing every failure would also hide a 403 from a mis-scoped token, which is the
+ *   failure this estate spends the most time on. So: `NoSuchBucket` → absent, everything else dies.
  *
  * ⛔ AN EMPTY LIVE RULE SET IS "NO LOCK", NOT "A LOCK WITH NOTHING IN IT", so it reads as absent
  *   and the resource CREATES. The API answers `{}` for a bucket that has never been locked and
@@ -110,26 +115,17 @@ export const R2BucketLock: ResourceClass<R2BucketLock> = Resource<R2BucketLock>(
  *   all, because `reconcile` below returns before writing.
  */
 export const readLock = (
-  client: Cloudflare,
   props: { accountId: string; bucketName: string; jurisdiction?: Jurisdiction },
   written: boolean,
-): Effect.Effect<R2BucketLockAttributes | undefined> =>
+): Effect.Effect<R2BucketLockAttributes | undefined, never, CloudflareOpContext> =>
   Effect.gen(function* () {
     const jurisdiction = jurisdictionOf(props);
-    const live = yield* Effect.tryPromise({
-      try: () =>
-        client.r2.buckets.locks.get(props.bucketName, {
-          account_id: props.accountId,
-          jurisdiction,
-        }),
-      catch: (cause) => cause,
-    }).pipe(
-      Effect.catchIf(
-        (cause) => cause instanceof NotFoundError,
-        () => Effect.succeed(undefined),
-      ),
-      Effect.orDie,
-    );
+    const live = yield* r2
+      .getBucketLock({ accountId: props.accountId, bucketName: props.bucketName, jurisdiction })
+      .pipe(
+        Effect.catchTag('NoSuchBucket', () => Effect.succeed(undefined)),
+        Effect.orDie,
+      );
     if (live === undefined) return undefined;
     const rules = (live.rules ?? []) as readonly R2LockRule[];
     if (rules.length === 0) return undefined;
@@ -146,22 +142,25 @@ export const readLock = (
  *   rule set; re-sending an identical one on every deploy is a write against the only thing
  *   standing between this repository and a delete, for no change. `output` is what the last deploy
  *   persisted (or what `read` just adopted), so the comparison costs nothing either.
+ * ⛔ `NoSuchBucket` IS NOT CAUGHT HERE. Unlike `read`, a `reconcile` that hits it means the bucket
+ *   this declaration names is genuinely gone — that is a real failure to surface, not a case to
+ *   paper over, so it dies like every other tagged error `putBucketLock` can raise.
  */
 export const reconcileLock = (
-  client: Cloudflare,
   news: R2BucketLockProps,
   output: R2BucketLockAttributes | undefined,
-): Effect.Effect<R2BucketLockAttributes> =>
+): Effect.Effect<R2BucketLockAttributes, never, CloudflareOpContext> =>
   Effect.gen(function* () {
     const jurisdiction = jurisdictionOf(news);
     if (output !== undefined && rulesEqual(output.rules, news.rules)) return output;
-    yield* Effect.promise(() =>
-      client.r2.buckets.locks.update(news.bucketName, {
-        account_id: news.accountId,
+    yield* r2
+      .putBucketLock({
+        accountId: news.accountId,
+        bucketName: news.bucketName,
         jurisdiction,
         ...toBody(news.rules),
-      }),
-    );
+      })
+      .pipe(Effect.orDie);
     return { bucketName: news.bucketName, jurisdiction, rules: news.rules };
   });
 
@@ -173,25 +172,34 @@ export const reconcileLock = (
  *   no ordinary deploy should ever reach it.
  */
 export const deleteLock = (
-  client: Cloudflare,
   output: R2BucketLockAttributes,
   accountId: string,
-): Effect.Effect<void> =>
+): Effect.Effect<void, never, CloudflareOpContext> =>
   Effect.gen(function* () {
-    yield* Effect.promise(() =>
-      client.r2.buckets.locks.update(output.bucketName, {
-        account_id: accountId,
+    yield* r2
+      .putBucketLock({
+        accountId,
+        bucketName: output.bucketName,
         jurisdiction: output.jurisdiction,
         rules: [],
-      }),
-    );
+      })
+      .pipe(Effect.orDie);
   });
 
 export const R2BucketLockProvider = () =>
   Provider.effect(
     R2BucketLock,
     Effect.gen(function* () {
-      const client = yield* CloudflareApi;
+      // ★ CAPTURED AT BUILD, LIKE `MeshNodeProvider`. `Credentials` and `HttpClient.HttpClient`
+      //   are the whole of distilled's `CloudflareOpContext` (r2.ts re-exports the type); pinning
+      //   them here rather than reading ambient context inside each handler keeps this provider
+      //   correct whether or not the stack also merges `Cloudflare.providers()`.
+      const services = Context.make(Credentials, yield* Credentials).pipe(
+        Context.add(HttpClient.HttpClient, yield* HttpClient.HttpClient),
+      );
+      const run = <A, E>(effect: Effect.Effect<A, E, CloudflareOpContext>) =>
+        Effect.provideContext(effect, services);
+
       return R2BucketLock.Provider.of({
         /**
          * ⛔ EMPTY, AND ALCHEMY'S OWN CONTRACT ASKS FOR EXACTLY THAT. `ProviderService.list`:
@@ -211,10 +219,10 @@ export const R2BucketLockProvider = () =>
         read: Effect.fn(function* ({ olds, output }) {
           const props = olds ?? undefined;
           if (props === undefined) return undefined;
-          return yield* readLock(client, props, output !== undefined);
+          return yield* run(readLock(props, output !== undefined));
         }),
-        reconcile: Effect.fn(({ news, output }) => reconcileLock(client, news, output)),
-        delete: Effect.fn(({ olds, output }) => deleteLock(client, output, olds.accountId)),
+        reconcile: Effect.fn(({ news, output }) => run(reconcileLock(news, output))),
+        delete: Effect.fn(({ olds, output }) => run(deleteLock(output, olds.accountId))),
       });
     }),
   );

package/src/forgejo/branch-protection-form.ts

@@ -1,12 +1,13 @@
 /**
- * Create/PATCH bodies for `Forgejo.BranchProtection` — extracted for the 250-line cap.
+ * Create/edit request bodies for `Forgejo.BranchProtection` — extracted for the 250-line cap.
  *
- * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json` — create posts
- *   `CreateBranchProtectionOption`; update sends `EditBranchProtectionOption` fields only.
+ * ★ `repoCreateBranchProtection`'s request carries `branch_name`; `repoEditBranchProtection`'s
+ *   carries `name` (the rule-name path segment) instead — both are covered by the two exports
+ *   below, so branch-protection.ts never builds the field list twice.
  */
 import type { BranchProtectionProps } from './branch-protection.ts';
 
-export const branchProtectionForm = (props: BranchProtectionProps) => ({
+const shared = (props: BranchProtectionProps) => ({
   ...(props.applyToAdmins === undefined ? {} : { apply_to_admins: props.applyToAdmins }),
   ...(props.dismissStaleApprovals === undefined
     ? {}
@@ -25,5 +26,11 @@ export const branchProtectionForm = (props: BranchProtectionProps) => ({
   ...(props.statusCheckContexts === undefined
     ? {}
     : { status_check_contexts: props.statusCheckContexts }),
-  rule_name: props.branchName,
 });
+
+export const createBranchProtectionForm = (props: BranchProtectionProps) => ({
+  ...shared(props),
+  branch_name: props.branchName,
+});
+
+export const editBranchProtectionForm = (props: BranchProtectionProps) => shared(props);

package/src/forgejo/branch-protection.ts

@@ -2,8 +2,13 @@
  * `Forgejo.BranchProtection` — one rule at `/repos/{owner}/{repo}/branch_protections/{name}`.
  *
  * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection;
- *   read/update/delete use the branch/rule name in the path segment `{name}`. Response carries
- *   `rule_name` (preferred) and deprecated `branch_name`.
+ *   read/update/delete use the branch/rule name in the path segment `{name}`. Now through
+ *   `@distilled.cloud/forgejo`'s `repository.repoCreateBranchProtection` /
+ *   `repoGetBranchProtection` / `repoEditBranchProtection` / `repoDeleteBranchProtection`.
+ *
+ * ⚠️ `BranchProtection.rule_name` IS A REQUIRED STRING IN THE PACKAGE'S SCHEMA — the deprecated
+ *   `branch_name` fallback the hand-rolled client carried is gone; a response missing `rule_name`
+ *   now fails the operation's own decode instead of this family silently treating it as absent.
  *
  * ⛔ `defaultRemovalPolicy: 'retain'` — dropping a protection rule from the stack must not silently
  *   unprotect a branch; opt into `.pipe(RemovalPolicy.destroy())` to DELETE.
@@ -12,10 +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 { branchProtectionForm } from './branch-protection-form.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, int, stringArray, text } from './values.ts';
+import { createBranchProtectionForm, editBranchProtectionForm } from './branch-protection-form.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { stringArray } from './values.ts';
 
 export interface BranchProtectionProps {
   owner: string;
@@ -59,26 +65,45 @@ export const ForgejoBranchProtection = Resource<ForgejoBranchProtection>(
   { defaultRemovalPolicy: 'retain' },
 );
 
-const handlers = forgejoHandlers<BranchProtectionProps, BranchProtectionAttributes>({
-  attributes: (live, props) => {
-    const ruleName = text(live['rule_name'], text(live['branch_name']));
-    if (ruleName === '') return undefined;
-    return {
-      applyToAdmins: bool(live['apply_to_admins']),
-      branchName: props.branchName,
-      dismissStaleApprovals: bool(live['dismiss_stale_approvals']),
-      enablePush: bool(live['enable_push'], true),
-      enableStatusCheck: bool(live['enable_status_check']),
-      ignoreStaleApprovals: bool(live['ignore_stale_approvals']),
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  BranchProtectionProps,
+  repository.BranchProtection,
+  BranchProtectionAttributes,
+  | repository.RepoCreateBranchProtectionError
+  | repository.RepoGetBranchProtectionError
+  | repository.RepoEditBranchProtectionError
+  | repository.RepoDeleteBranchProtectionError
+> = {
+  attributes: (live, props) => ({
+    applyToAdmins: live.apply_to_admins ?? false,
+    branchName: props.branchName,
+    dismissStaleApprovals: live.dismiss_stale_approvals ?? false,
+    enablePush: live.enable_push ?? true,
+    enableStatusCheck: live.enable_status_check ?? false,
+    ignoreStaleApprovals: live.ignore_stale_approvals ?? false,
+    owner: props.owner,
+    repo: props.repo,
+    requireSignedCommits: live.require_signed_commits ?? false,
+    requiredApprovals: live.required_approvals ?? 0,
+    statusCheckContexts: stringArray(live.status_check_contexts ?? []),
+  }),
+  create: (props) =>
+    repository.repoCreateBranchProtection({
+      owner: props.owner,
+      repo: props.repo,
+      ...createBranchProtectionForm(props),
+    }),
+  destroy: (props) =>
+    repository.repoDeleteBranchProtection({
       owner: props.owner,
       repo: props.repo,
-      requireSignedCommits: bool(live['require_signed_commits']),
-      requiredApprovals: int(live['required_approvals']),
-      statusCheckContexts: stringArray(live['status_check_contexts']),
-    };
-  },
-  collection: (props) => `repos/${props.owner}/${props.repo}/branch_protections`,
-  createForm: branchProtectionForm,
+      name: props.branchName,
+    }),
+  fetchLive: (props) =>
+    repository
+      .repoGetBranchProtection({ owner: props.owner, repo: props.repo, name: props.branchName })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
   matches: (attributes, props) =>
     attributes.requiredApprovals === (props.requiredApprovals ?? 0) &&
     attributes.enablePush === (props.enablePush ?? true) &&
@@ -90,9 +115,16 @@ const handlers = forgejoHandlers<BranchProtectionProps, BranchProtectionAttribut
     (props.statusCheckContexts === undefined ||
       stringArray(props.statusCheckContexts).join('\0') ===
         attributes.statusCheckContexts.join('\0')),
-  path: (props) => `repos/${props.owner}/${props.repo}/branch_protections/${props.branchName}`,
-  updateForm: branchProtectionForm,
-});
+  update: (props) =>
+    repository.repoEditBranchProtection({
+      owner: props.owner,
+      repo: props.repo,
+      name: props.branchName,
+      ...editBranchProtectionForm(props),
+    }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoBranchProtectionProvider = () =>
   Provider.effect(

package/src/forgejo/fake-forgejo.ts

@@ -0,0 +1,54 @@
+/**
+ * A minimal in-memory Forgejo v1 API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring
+ * `cloudflare/fake-mesh.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. No provider imports this file. The base URL is RFC 2606
+ *   `forgejo.example.com`, and the token is a placeholder.
+ */
+import { type Credentials, credentials } from '@distilled.cloud/forgejo/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://forgejo.example.com';
+export const FAKE_TOKEN = 'placeholder-forgejo-token';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** Forgejo's failure envelope — `{ message, url }` — matching protocol.ts's `errorEnvelope`. */
+export const fakeFailure = (status: number, message: string) =>
+  Response.json({ message, url: 'https://forgejo.example.com/api/v1/swagger' }, { 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 fakeForgejo = (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 — `ForgejoOpContext`, what every
+ * resource file's exported `spec.fetchLive` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers` (each resource file's `forgejoHandlers(spec)` export). `handlers`
+ *   bakes in `CredentialsFromEnv`, which resolves `FORGEJO_URL` / `FORGEJO_TOKEN` through Effect's
+ *   `Config` — whose default provider snapshots `process.env` once and never re-reads it (measured
+ *   2026-09-23: mutating `process.env` mid-test-run had no effect). 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 fakeForgejoLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = credentials({ baseUrl: FAKE_BASE, token: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

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();
+  });
+});