@homeflare/alchemy 0.27.1 → 0.27.3

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

@@ -0,0 +1,139 @@
+/**
+ * `readLock` / `reconcileLock` / `deleteLock` against the fake Cloudflare in fake-r2-lock.ts, the
+ * same direct style mesh-node-token.test.ts uses for `fetchMeshNodeToken`: run the plain Effect
+ * under `fakeR2LockLayer`, no Provider or engine harness needed.
+ *
+ * ★ THE POINT OF THIS FILE IS THE TAGGED-ERROR PATHS, per the transport swap onto
+ *   `@distilled.cloud/cloudflare/r2`: `NoSuchBucket` is matched by Cloudflare's own error code
+ *   (10006), never by HTTP status, and only `readLock` treats it as "nothing to adopt" —
+ *   `reconcileLock`/`deleteLock` let it die like any other tagged error.
+ */
+import type { CloudflareOpContext } from '@distilled.cloud/cloudflare/r2';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import {
+  FAKE_ACCOUNT,
+  type FakeR2Lock,
+  fakeFailure,
+  fakeR2Lock,
+  fakeR2LockLayer,
+  writes,
+} from './fake-r2-lock.ts';
+import type { R2LockRule } from './lock-rules.ts';
+import { type R2BucketLockProps, deleteLock, readLock, reconcileLock } from './r2-bucket-lock.ts';
+
+const run = <A, E>(fake: FakeR2Lock, effect: Effect.Effect<A, E, CloudflareOpContext>) =>
+  Effect.runPromise(effect.pipe(Effect.provide(fakeR2LockLayer(fake))));
+
+const dies = <A, E>(fake: FakeR2Lock, effect: Effect.Effect<A, E, CloudflareOpContext>) =>
+  Effect.runPromiseExit(effect.pipe(Effect.provide(fakeR2LockLayer(fake))));
+
+const rule: R2LockRule = {
+  id: 'keep-30d',
+  enabled: true,
+  condition: { type: 'Age', maxAgeSeconds: 2_592_000 },
+};
+
+const props = (over: Partial<R2BucketLockProps> = {}): R2BucketLockProps => ({
+  accountId: FAKE_ACCOUNT,
+  bucketName: 'my-backups',
+  rules: [rule],
+  ...over,
+});
+
+describe('readLock', () => {
+  test('a bucket that does not exist (NoSuchBucket, code 10006) reads as absent', async () => {
+    const fake = fakeR2Lock();
+    expect(await run(fake, readLock(props(), false))).toBeUndefined();
+  });
+
+  test('a bucket that exists but was never locked reads as absent', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    expect(await run(fake, readLock(props(), false))).toBeUndefined();
+  });
+
+  test('a locked bucket, written by this stack, reads as plain attributes', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    await run(fake, reconcileLock(props(), undefined));
+    const attrs = await run(fake, readLock(props(), true));
+    expect(Unowned.is(attrs)).toBe(false);
+    expect(attrs).toEqual({ bucketName: 'my-backups', jurisdiction: 'default', rules: [rule] });
+  });
+
+  test('a locked bucket, not yet written by this stack, reads Unowned', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    await run(fake, reconcileLock(props(), undefined));
+    const attrs = await run(fake, readLock(props(), false));
+    expect(Unowned.is(attrs)).toBe(true);
+  });
+
+  test('NoSuchBucket is matched by code, not by HTTP status', async () => {
+    // ⛔ THE PROOF THAT THIS IS catchTag, NOT A STATUS CHECK: code 10006 at a non-404 status is
+    //   still caught. The old `cloudflare` SDK's `instanceof NotFoundError` could only ever match
+    //   a 404; distilled's error matcher does not look at status at all for this tag.
+    const fake = fakeR2Lock({
+      onRoute: () => fakeFailure(400, 10006, 'The specified bucket does not exist.'),
+    });
+    expect(await run(fake, readLock(props(), false))).toBeUndefined();
+  });
+
+  test('a different tagged error at 404 is NOT swallowed as NoSuchBucket', async () => {
+    // ⛔ code 7003 is `InvalidRoute`, not `NoSuchBucket` — even at the same 404 status a plain
+    //   status check would have treated as "no bucket". `catchTag('NoSuchBucket', …)` leaves it
+    //   alone, and `Effect.orDie` turns it into a defect.
+    const fake = fakeR2Lock({ onRoute: () => fakeFailure(404, 7003, 'Invalid route') });
+    const exit = await dies(fake, readLock(props(), false));
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+  });
+});
+
+describe('reconcileLock', () => {
+  test('writes nothing when the declared rules already match', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    const output = await run(fake, reconcileLock(props(), undefined));
+    fake.seen.length = 0;
+    const again = await run(fake, reconcileLock(props(), output));
+    expect(again).toEqual(output);
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('PUTs the whole rule set when it differs from output', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    await run(fake, reconcileLock(props(), undefined));
+    expect(writes(fake)).toEqual(['PUT']);
+    expect(fake.locks.get('my-backups')).toEqual([rule]);
+  });
+
+  test('NoSuchBucket is NOT caught here: a genuinely missing bucket dies', async () => {
+    const fake = fakeR2Lock();
+    const exit = await dies(fake, reconcileLock(props(), undefined));
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+  });
+});
+
+describe('deleteLock', () => {
+  test('PUTs an empty rule set, unlocking the bucket', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    const output = await run(fake, reconcileLock(props(), undefined));
+    fake.seen.length = 0;
+    await run(fake, deleteLock(output, FAKE_ACCOUNT));
+    expect(writes(fake)).toEqual(['PUT']);
+    expect(fake.locks.has('my-backups')).toBe(false);
+  });
+
+  test('NoSuchBucket is NOT caught here either: a genuinely missing bucket dies', async () => {
+    const fake = fakeR2Lock();
+    const output = await run(
+      fakeR2Lock({ existingBuckets: ['my-backups'] }),
+      reconcileLock(props(), undefined),
+    );
+    const exit = await dies(fake, deleteLock(output, FAKE_ACCOUNT));
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+  });
+});

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