@homeflare/alchemy 0.1.0

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

@@ -0,0 +1,220 @@
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+/**
+ * `Cloudflare.R2BucketLock` — the lock rule set on one R2 bucket, declared rather than applied by
+ * hand. A bucket lock is a RETENTION FLOOR: while a rule covers an object, no API call, no
+ * lifecycle rule and no credential can delete it.
+ *
+ * 🔴 WHY THIS EXISTS AT ALL, AND WHAT IT REPLACES. a consuming stack shipped the retention floor as a
+ *   documented `wrangler r2 bucket lock add …` step in the runbook, on the measured ground that
+ *   `alchemy@2.0.0-beta.77` has no lock property anywhere in its R2 namespace. That measurement is
+ *   still true and it was the wrong conclusion: a step a human runs once is a step an Alchemy plan
+ *   can never show missing, so removing the floor by hand leaves that stack, its plan and
+ *   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.
+ *
+ * ⚠️ 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
+ *   `homeflare-git`. Declaring this resource on a bucket whose live rules nobody has read would
+ *   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 * as Effect from 'effect/Effect';
+import { CloudflareApi } from './client.ts';
+import {
+  type Jurisdiction,
+  type R2LockRule,
+  jurisdictionOf,
+  rulesEqual,
+  toBody,
+} from './lock-rules.ts';
+import type { Providers } from './providers.ts';
+
+export interface R2BucketLockProps {
+  readonly accountId: string;
+  readonly bucketName: string;
+  /** ⚠️ Part of the bucket's IDENTITY, not a preference — a bucket in another jurisdiction is another bucket. */
+  readonly jurisdiction?: Jurisdiction;
+  /**
+   * ⛔ REQUIRED, AND ITS EMPTY VALUE IS THE DANGEROUS ONE. `rules: []` means NO FLOOR: it is what
+   *   `delete` sends to take a lock off deliberately. An optional property would let a declaration
+   *   that simply forgot it send `[]` and silently unlock the repository, reporting success — the
+   *   same reasoning `LiteLLM.McpServer.allowedTools` is required for.
+   */
+  readonly rules: readonly R2LockRule[];
+}
+
+export type R2BucketLockAttributes = {
+  readonly bucketName: string;
+  readonly jurisdiction: Jurisdiction;
+  readonly rules: readonly R2LockRule[];
+};
+
+export interface R2BucketLock extends Resource<
+  'Cloudflare.R2BucketLock',
+  R2BucketLockProps,
+  R2BucketLockAttributes,
+  never,
+  Providers
+> {}
+
+// ⚠️ EXPLICIT ANNOTATION, REQUIRED BY isolatedDeclarations. This file was internal to a
+//   monorepo before it was published; a published package emits its .d.ts from a separate
+//   tsc pass, so every exported symbol must state its type rather than infer it.
+export const R2BucketLock: ResourceClass<R2BucketLock> = Resource<R2BucketLock>(
+  'Cloudflare.R2BucketLock',
+  {
+    /**
+     * ⛔ RETAIN, AND ON THIS RESOURCE IT IS NOT THE ESTATE'S HABIT BUT THE WHOLE POINT. A lock is a
+     *   safety floor: removing the declaration must not remove the floor, because the state it
+     *   protects is the only physical backup of the estate's one Postgres. `delete` below is
+     *   implemented — a provider that cannot delete cannot be tested or corrected — and it is
+     *   reachable only by an operator running the CLI directly, past a deploy wrapper.
+     */
+    defaultRemovalPolicy: 'retain',
+  },
+);
+
+/**
+ * 🔴 A 404 HERE IS "NOTHING TO ADOPT", AND THE FIRST PLAN PROVED IT IS THE ORDINARY CASE.
+ *   Measured 2026-09-15, an alchemy plan --detailed on a bucket that does not
+ *   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.
+ *
+ * ⛔ 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
+ *   `{ rules: [] }` for one whose rules were removed; both mean the floor is gone.
+ * ⚠️ `Unowned` UNTIL THIS STACK HAS WRITTEN IT. A lock someone applied by hand — which is exactly
+ *   what the retired runbook step did — must not be silently rewritten by a mistyped declaration;
+ *   the planner refuses until the resource is piped through `adopt(true)`, which is one line an
+ *   operator reads in the diff. An adopted rule set that already MATCHES then costs no request at
+ *   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.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,
+    );
+    if (live === undefined) return undefined;
+    const rules = (live.rules ?? []) as readonly R2LockRule[];
+    if (rules.length === 0) return undefined;
+    const attributes: R2BucketLockAttributes = {
+      bucketName: props.bucketName,
+      jurisdiction,
+      rules,
+    };
+    return written ? attributes : Unowned(attributes);
+  });
+
+/**
+ * ⛔ A NO-OP MAKES NO REQUEST, AND ON A LOCK THAT MATTERS MORE THAN TIDINESS. `PUT` replaces the
+ *   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.
+ */
+export const reconcileLock = (
+  client: Cloudflare,
+  news: R2BucketLockProps,
+  output: R2BucketLockAttributes | undefined,
+): Effect.Effect<R2BucketLockAttributes> =>
+  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,
+        jurisdiction,
+        ...toBody(news.rules),
+      }),
+    );
+    return { bucketName: news.bucketName, jurisdiction, rules: news.rules };
+  });
+
+/**
+ * ⛔ DELETING THIS RESOURCE MEANS PUTTING AN EMPTY RULE SET, WHICH IS UNLOCKING THE BUCKET. It is
+ *   implemented because the retirement path is real — R2 refuses to empty a bucket while any lock
+ *   rule is configured, so retiring the repository has to start here — and it is behind
+ *   `defaultRemovalPolicy: 'retain'` and the estate CLI's refusal of `destroy` precisely because
+ *   no ordinary deploy should ever reach it.
+ */
+export const deleteLock = (
+  client: Cloudflare,
+  output: R2BucketLockAttributes,
+  accountId: string,
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    yield* Effect.promise(() =>
+      client.r2.buckets.locks.update(output.bucketName, {
+        account_id: accountId,
+        jurisdiction: output.jurisdiction,
+        rules: [],
+      }),
+    );
+  });
+
+export const R2BucketLockProvider = () =>
+  Provider.effect(
+    R2BucketLock,
+    Effect.gen(function* () {
+      const client = yield* CloudflareApi;
+      return R2BucketLock.Provider.of({
+        /**
+         * ⛔ EMPTY, AND ALCHEMY'S OWN CONTRACT ASKS FOR EXACTLY THAT. `ProviderService.list`:
+         *   "Resources with no native enumeration API (… sub-resources keyed entirely by a parent)
+         *   should return an empty array rather than throwing." There is no list-locks endpoint —
+         *   a lock is reachable only through the bucket that owns it — so enumerating would mean
+         *   listing every bucket in the account and GETting each one's lock.
+         * ⛔⛔ AND `nuke.singleton` IS WHY THAT IS NOT MERELY UNAVAILABLE BUT UNWANTED. `list`
+         *   feeds `alchemy unsafe nuke`, which lists and then deletes; `delete` here is an UNLOCK.
+         *   A working enumeration would hand one command the ability to strip the retention floor
+         *   off every bucket in the account — the precise event a floor exists to make impossible.
+         *   `singleton` is the documented word for it: always-present configuration whose delete
+         *   resets rather than removes.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { singleton: true },
+        read: Effect.fn(function* ({ olds, output }) {
+          const props = olds ?? undefined;
+          if (props === undefined) return undefined;
+          return yield* readLock(client, props, output !== undefined);
+        }),
+        reconcile: Effect.fn(({ news, output }) => reconcileLock(client, news, output)),
+        delete: Effect.fn(({ olds, output }) => deleteLock(client, output, olds.accountId)),
+      });
+    }),
+  );

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

@@ -0,0 +1,29 @@
+/**
+ * Create/PATCH bodies for `Forgejo.BranchProtection` — extracted for the 250-line cap.
+ *
+ * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json` — create posts
+ *   `CreateBranchProtectionOption`; update sends `EditBranchProtectionOption` fields only.
+ */
+import type { BranchProtectionProps } from './branch-protection.ts';
+
+export const branchProtectionForm = (props: BranchProtectionProps) => ({
+  ...(props.applyToAdmins === undefined ? {} : { apply_to_admins: props.applyToAdmins }),
+  ...(props.dismissStaleApprovals === undefined
+    ? {}
+    : { dismiss_stale_approvals: props.dismissStaleApprovals }),
+  ...(props.enablePush === undefined ? {} : { enable_push: props.enablePush }),
+  ...(props.enableStatusCheck === undefined
+    ? {}
+    : { enable_status_check: props.enableStatusCheck }),
+  ...(props.ignoreStaleApprovals === undefined
+    ? {}
+    : { ignore_stale_approvals: props.ignoreStaleApprovals }),
+  ...(props.requireSignedCommits === undefined
+    ? {}
+    : { require_signed_commits: props.requireSignedCommits }),
+  ...(props.requiredApprovals === undefined ? {} : { required_approvals: props.requiredApprovals }),
+  ...(props.statusCheckContexts === undefined
+    ? {}
+    : { status_check_contexts: props.statusCheckContexts }),
+  rule_name: props.branchName,
+});

package/src/forgejo/branch-protection.ts

@@ -0,0 +1,101 @@
+/**
+ * `Forgejo.BranchProtection` — one rule at `/repos/{owner}/{repo}/branch_protections/{name}`.
+ *
+ * ★ READ OFF `house/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`.
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — dropping a protection rule from the stack must not silently
+ *   unprotect a branch; opt into `.pipe(RemovalPolicy.destroy())` to DELETE.
+ *
+ * ⛔ TOKEN NEEDS `write:repository` TO CREATE OR PATCH — get needs `read:repository`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+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';
+
+export interface BranchProtectionProps {
+  owner: string;
+  repo: string;
+  /** Branch or rule name — path key and `rule_name` on the wire. */
+  branchName: string;
+  requiredApprovals?: number;
+  enablePush?: boolean;
+  enableStatusCheck?: boolean;
+  requireSignedCommits?: boolean;
+  dismissStaleApprovals?: boolean;
+  ignoreStaleApprovals?: boolean;
+  applyToAdmins?: boolean;
+  statusCheckContexts?: string[];
+}
+
+export interface BranchProtectionAttributes {
+  owner: string;
+  repo: string;
+  branchName: string;
+  requiredApprovals: number;
+  enablePush: boolean;
+  enableStatusCheck: boolean;
+  requireSignedCommits: boolean;
+  dismissStaleApprovals: boolean;
+  ignoreStaleApprovals: boolean;
+  applyToAdmins: boolean;
+  statusCheckContexts: string[];
+}
+
+export interface ForgejoBranchProtection extends Resource<
+  'Forgejo.BranchProtection',
+  BranchProtectionProps,
+  BranchProtectionAttributes,
+  never,
+  ForgejoRequirements
+> {}
+
+export const ForgejoBranchProtection = Resource<ForgejoBranchProtection>(
+  'Forgejo.BranchProtection',
+  { 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']),
+      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,
+  matches: (attributes, props) =>
+    attributes.requiredApprovals === (props.requiredApprovals ?? 0) &&
+    attributes.enablePush === (props.enablePush ?? true) &&
+    attributes.enableStatusCheck === (props.enableStatusCheck ?? false) &&
+    attributes.requireSignedCommits === (props.requireSignedCommits ?? false) &&
+    attributes.dismissStaleApprovals === (props.dismissStaleApprovals ?? false) &&
+    attributes.ignoreStaleApprovals === (props.ignoreStaleApprovals ?? false) &&
+    attributes.applyToAdmins === (props.applyToAdmins ?? false) &&
+    (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,
+});
+
+export const ForgejoBranchProtectionProvider = () =>
+  Provider.effect(
+    ForgejoBranchProtection,
+    Effect.succeed(ForgejoBranchProtection.Provider.of(handlers)),
+  );

package/src/forgejo/client.ts

@@ -0,0 +1,136 @@
+/**
+ * One authenticated call to the Forgejo (Gitea) API at `/api/v1`.
+ *
+ * ★ PLAIN `fetch`, NO TLS ESCAPE HATCH — your Forgejo host serves a real certificate on :443,
+ *   and the local daemon on :3000 is loopback. There is no `rejectUnauthorized` switch to leave
+ *   on by accident elsewhere.
+ *
+ * ⚠️ GITEA DOES NOT WRAP ANSWERS IN `{"data": ...}` THE WAY PVE DOES. MEASURED 2026-09-13 on
+ *   the live daemon: `GET /api/v1/version` returns `{"version":"16.0.3"}`; `GET /api/v1/user`
+ *   returns the user object; `GET /api/v1/orgs/HomeFlare/repos` returns a JSON array. A caller
+ *   that unwraps a non-existent envelope sees `undefined` and calls a healthy object "absent".
+ *
+ * ⛔ THE TOKEN IS NEVER A PROP. Read `FORGEJO_TOKEN` from the environment at call time only.
+ *   Alchemy persists attributes unencrypted and this estate's state store is Postgres dumped
+ *   nightly — nothing stored may be a credential.
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+
+const PATH_PREFIX = '/api/v1';
+
+/**
+ * The Forgejo instance, from `FORGEJO_URL`. Trailing slash stripped.
+ *
+ * ⛔ NO DEFAULT HOSTNAME. This used to fall back to the author's own instance, which is
+ *   fine inside one estate and wrong in a published package: a consumer who forgets the
+ *   variable would silently point at someone else's server rather than being told.
+ * ⚠️ Read at CALL time, never at module scope — a value captured at import is pinned to
+ *   whatever the first isolate saw.
+ */
+export const apiBase = (): string => {
+  const raw = process.env['FORGEJO_URL'];
+  if (raw === undefined || raw.trim() === '') {
+    throw new Error(
+      'FORGEJO_URL is not set. Point it at your Forgejo instance, e.g. https://git.example.com',
+    );
+  }
+  return raw.trim().replace(/\/$/, '');
+};
+
+const token = (): Effect.Effect<string, ForgejoError> =>
+  Effect.gen(function* () {
+    const raw = process.env['FORGEJO_TOKEN'];
+    if (raw === undefined || raw.trim() === '') {
+      return yield* Effect.fail(
+        new ForgejoError(
+          0,
+          'GET',
+          '',
+          'FORGEJO_TOKEN is unset. Mint a scoped token and export it — never store it in Alchemy props.',
+        ),
+      );
+    }
+    return raw.trim();
+  });
+
+export class ForgejoError extends Error {
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    detail: string,
+  ) {
+    super(`Forgejo ${method} ${path} -> ${String(status)}: ${detail}`);
+    this.name = 'ForgejoError';
+  }
+}
+
+/**
+ * ⚠️ `Authorization: token <value>`, NOT `Bearer`. Gitea docs and MEASURED behaviour on this
+ *   estate: Bearer is treated as OAuth2 and rejected; `token` is the documented API-key form.
+ */
+const authorization = (value: string) => ({ Authorization: `token ${value}` });
+
+/** One JSON call. Returns the parsed body, or `undefined` when the response is empty (DELETE). */
+export const forgejo = <T>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* token();
+    const url = `${apiBase()}${PATH_PREFIX}/${path.replace(/^\//, '')}`;
+    /**
+     * ★ THROUGH `HttpClient`, NOT THE GLOBAL `fetch` — the idiom Alchemy's own providers follow
+     *   (src/Hetzner/Providers.ts builds on `FetchHttpClient.layer`; there is no bare fetch in its
+     *   Docker, Kubernetes or GitHub providers). It buys a typed error channel, interruption when
+     *   a plan is cancelled, the runtime's tracing, and a client a test can replace without
+     *   monkey-patching a global. house/proxmox/src/resource.ts carries the same note.
+     */
+    const client = yield* HttpClient.HttpClient;
+    /**
+     * ⛔ THE CONTENT TYPE GOES ON `bodyText`, NOT IN THE HEADER MAP, AND PUTTING IT IN BOTH IS HOW
+     *   THIS PACKAGE SHIPPED UNABLE TO WRITE AT ALL.
+     *
+     * 🔴 THE BUG, MEASURED THE FIRST TIME A WRITE WAS EVER ATTEMPTED. The header map DID carry
+     *   `Content-Type: application/json` — and `bodyText(s)` with no second argument sets
+     *   `text/plain` and OVERWRITES it, because it is piped AFTER `setHeaders`. Forgejo answered
+     *       422 {"message":"[]: Unsupported Content-Type"}
+     *   on `PATCH orgs/homeflare/labels/1`. Every create and every update in every family here was
+     *   broken, identically, from the day the client was written.
+     *
+     * ⛔ NOTHING CAUGHT IT BECAUSE NOTHING HAD EVER WRITTEN. The only credential on the shelf was
+     *   `mcp-read`, which answers 403 before a request body is ever parsed — so read, adopt, diff
+     *   and plan all worked perfectly and the write path had literally never executed. A provider
+     *   that has never performed its own writes is not a tested provider, whatever the plan says.
+     *
+     * ⚠️ `bodyJsonUnsafe` WOULD ALSO WORK. `bodyText` with an explicit type is used instead
+     *   because it makes the content type visible at the call site, which is the thing that was
+     *   invisible before.
+     */
+    const request = HttpClientRequest.make(method)(url).pipe(
+      HttpClientRequest.setHeaders({ ...authorization(credential), Accept: 'application/json' }),
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    const response = yield* client
+      .execute(request)
+      .pipe(Effect.mapError((cause) => new ForgejoError(0, method, path, String(cause))));
+    // ⛔ Status first, body once — a Gitea error body is JSON but a proxy's 502 is not.
+    if (response.status < 200 || response.status >= 300) {
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(
+        new ForgejoError(response.status, method, path, detail.slice(0, 300)),
+      );
+    }
+    // ⚠️ 204 AND AN EMPTY BODY ARE REAL: a label DELETE answers no content, and `json` on an empty
+    //   body fails. Read text once and parse only when there is something to parse.
+    const text = yield* response.text.pipe(
+      Effect.mapError((cause) => new ForgejoError(0, method, path, String(cause))),
+    );
+    // ⚠️ PUT/DELETE on actions secrets and hooks often answer 201/204 with no body — same trap as DELETE.
+    return (text === '' ? undefined : JSON.parse(text)) as T;
+  });

package/src/forgejo/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Forgejo providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY.
+ *   These are the symbols a real stack consumes; the rest of the files are internals a
+ *   provider needs but a consumer should not depend on. An `export *` here would publish
+ *   every helper as API and make the next refactor a breaking change.
+ * ★ Anything unlisted is still reachable by path if you genuinely need it — that is a
+ *   deliberate, visible act rather than an accident of barrelling.
+ */
+export { ForgejoBranchProtectionProvider } from './branch-protection.ts';
+export { ForgejoOrgSecretProvider } from './org-actions-secrets.ts';
+export { ForgejoOrgLabel, ForgejoOrgLabelProvider, type OrgLabelProps } from './org-label.ts';
+export { ForgejoOrgTeamProvider } from './org-team.ts';
+export { ForgejoRepoWebhookProvider } from './repo-webhook.ts';
+export { ForgejoRepository, ForgejoRepositoryProvider } from './repository.ts';
+export { ForgejoTeamMember, ForgejoTeamMemberProvider } from './team-member.ts';

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

@@ -0,0 +1,99 @@
+/**
+ * `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
+ *   `house/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.
+ *
+ * ⛔ 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.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+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';
+
+export interface OrgSecretProps {
+  org: string;
+  /** Secret name — path key; value lives in env, not here. */
+  name: string;
+}
+
+export interface OrgSecretAttributes {
+  org: string;
+  name: string;
+  createdAt: string;
+}
+
+export interface ForgejoOrgSecret extends Resource<
+  'Forgejo.OrgSecret',
+  OrgSecretProps,
+  OrgSecretAttributes,
+  never,
+  ForgejoRequirements
+> {}
+
+export const ForgejoOrgSecret = Resource<ForgejoOrgSecret>('Forgejo.OrgSecret');
+
+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.`,
+        ),
+      );
+    }
+    return raw.trim();
+  });
+
+const handlers = forgejoHandlers<OrgSecretProps, OrgSecretAttributes>({
+  attributes: (live, props) => ({
+    createdAt: text(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,
+      ),
+    ),
+  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 });
+    }),
+});
+
+export const ForgejoOrgSecretProvider = () =>
+  Provider.effect(ForgejoOrgSecret, Effect.succeed(ForgejoOrgSecret.Provider.of(handlers)));