@homeflare/alchemy 0.1.0

package/src/forgejo/org-label.ts

@@ -0,0 +1,100 @@
+/**
+ * `Forgejo.OrgLabel` — one org-level issue label shared across every repository in the org.
+ *
+ * ★ RETIRES `house/nix/homeflare-config/hosts/macmini/forgejo/labels-reconcile.sh`, which
+ *   converged the whole `labels.yaml` file in one shot. That script CREATED and PATCHED labels
+ *   from the spec and REPORTED `EXTRA` labels present live but absent from the file — it never
+ *   deleted them, because removing a label strips it from every issue that carries it.
+ *
+ * ★ THIS RESOURCE DOES NOT REMOVE EXTRA LABELS EITHER. Alchemy manages only labels you declare;
+ *   labels on the org that nobody declared stay untouched — the same boundary as the script's
+ *   `EXTRA … NOT deleted` lines. Removing a declaration defaults to `retain`, so dropping a label
+ *   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.
+ *
+ * ⛔ 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 Effect from 'effect/Effect';
+import { forgejo } from './client.ts';
+import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
+import { bool, color, text } from './values.ts';
+
+export interface OrgLabelProps {
+  /** Organization login — `homeflare` / `HomeFlare` must match the live org. */
+  org: string;
+  /** Label name — primary key for locate; immutable on update. */
+  name: string;
+  /** Six-digit hex, with or without `#`. */
+  color: string;
+  description?: string;
+  exclusive?: boolean;
+}
+
+export interface OrgLabelAttributes {
+  org: string;
+  name: string;
+  labelId: number;
+  color: string;
+  description: string;
+  exclusive: boolean;
+}
+
+export interface ForgejoOrgLabel extends Resource<
+  'Forgejo.OrgLabel',
+  OrgLabelProps,
+  OrgLabelAttributes,
+  never,
+  ForgejoRequirements
+> {}
+
+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,
+    name: props.name,
+  }),
+  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,
+      ),
+    ),
+  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'])}`,
+});
+
+export const ForgejoOrgLabelProvider = () =>
+  Provider.effect(ForgejoOrgLabel, Effect.succeed(ForgejoOrgLabel.Provider.of(handlers)));

package/src/forgejo/org-team.ts

@@ -0,0 +1,105 @@
+/**
+ * `Forgejo.OrgTeam` — one organization team under `/orgs/{org}/teams`.
+ *
+ * ★ READ OFF `house/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.
+ *
+ * ⚠️ PATCH AND DELETE USE `/teams/{id}` — same seam as org labels. `locate` lists by name;
+ *   `wirePath` carries the id from that row.
+ *
+ * ⛔ 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 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';
+
+export type TeamPermission = 'read' | 'write' | 'admin';
+
+export interface OrgTeamProps {
+  org: string;
+  /** Team name — primary locate key; sent on every PATCH body. */
+  name: string;
+  description?: string;
+  permission?: TeamPermission;
+  units?: string[];
+  unitsMap?: Record<string, string>;
+  includesAllRepositories?: boolean;
+  canCreateOrgRepo?: boolean;
+}
+
+export interface OrgTeamAttributes {
+  org: string;
+  name: string;
+  teamId: number;
+  description: string;
+  permission: TeamPermission;
+  units: string[];
+  unitsMap: Record<string, string>;
+  includesAllRepositories: boolean;
+  canCreateOrgRepo: boolean;
+}
+
+export interface ForgejoOrgTeam extends Resource<
+  'Forgejo.OrgTeam',
+  OrgTeamProps,
+  OrgTeamAttributes,
+  never,
+  ForgejoRequirements
+> {}
+
+export const ForgejoOrgTeam = Resource<ForgejoOrgTeam>('Forgejo.OrgTeam');
+
+const teamForm = (props: OrgTeamProps) => ({
+  can_create_org_repo: props.canCreateOrgRepo ?? false,
+  description: props.description ?? '',
+  includes_all_repositories: props.includesAllRepositories ?? false,
+  name: props.name,
+  ...(props.permission === undefined ? {} : { permission: props.permission }),
+  ...(props.units === undefined ? {} : { units: props.units }),
+  ...(props.unitsMap === undefined ? {} : { units_map: props.unitsMap }),
+});
+
+const handlers = forgejoHandlers<OrgTeamProps, OrgTeamAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    const permission = text(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']),
+      name: props.name,
+      org: props.org,
+      permission,
+      teamId: 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,
+      ),
+    ),
+  matches: (attributes, props) =>
+    attributes.description === (props.description ?? '') &&
+    attributes.permission === (props.permission ?? 'read') &&
+    attributes.includesAllRepositories === (props.includesAllRepositories ?? false) &&
+    attributes.canCreateOrgRepo === (props.canCreateOrgRepo ?? false) &&
+    (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'])}`,
+});
+
+export const ForgejoOrgTeamProvider = () =>
+  Provider.effect(ForgejoOrgTeam, Effect.succeed(ForgejoOrgTeam.Provider.of(handlers)));

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

@@ -0,0 +1,47 @@
+/**
+ * JSON 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.
+ */
+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']);
+
+export const hookConfigForm = (props: RepoWebhookProps, includeSecret: boolean) => {
+  const config: Record<string, string> = {
+    content_type: props.contentType ?? 'json',
+    url: props.url,
+  };
+  if (includeSecret) {
+    const key = hookSecretEnvKey(props.owner, props.repo, props.name);
+    const secret = process.env[key]?.trim();
+    if (secret !== undefined && secret !== '') config['secret'] = secret;
+  }
+  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

@@ -0,0 +1,118 @@
+/**
+ * `Forgejo.RepoWebhook` — one repository webhook under `/repos/{owner}/{repo}/hooks`.
+ *
+ * ★ READ OFF `house/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`.
+ *
+ * ⛔ 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.
+ *
+ * ⛔ TOKEN NEEDS `write:repository` TO CREATE OR PATCH — list/get needs `read:repository`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+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';
+
+export type RepoWebhookType =
+  | 'dingtalk'
+  | 'discord'
+  | 'feishu'
+  | 'forgejo'
+  | 'gitea'
+  | 'gogs'
+  | 'msteams'
+  | 'packagist'
+  | 'slack'
+  | 'telegram'
+  | 'wechatwork';
+
+export interface RepoWebhookProps {
+  owner: string;
+  repo: string;
+  /** Stable locate key — also sent as Hook.name on create. */
+  name: string;
+  type: RepoWebhookType;
+  url: string;
+  events: string[];
+  contentType?: 'json' | 'form';
+  active?: boolean;
+  branchFilter?: string;
+  authorizationHeader?: string;
+}
+
+export interface RepoWebhookAttributes {
+  owner: string;
+  repo: string;
+  name: string;
+  hookId: number;
+  type: RepoWebhookType;
+  url: string;
+  contentType: string;
+  events: string[];
+  active: boolean;
+  branchFilter: string;
+  authorizationHeader: string;
+}
+
+export interface ForgejoRepoWebhook extends Resource<
+  'Forgejo.RepoWebhook',
+  RepoWebhookProps,
+  RepoWebhookAttributes,
+  never,
+  ForgejoRequirements
+> {}
+
+export const ForgejoRepoWebhook = Resource<ForgejoRepoWebhook>('Forgejo.RepoWebhook');
+
+const handlers = forgejoHandlers<RepoWebhookProps, RepoWebhookAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    const config = hookConfigPublic(live['config']);
+    const type = text(live['type']);
+    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,
+      name: props.name,
+      owner: props.owner,
+      repo: props.repo,
+      type: type as RepoWebhookType,
+      url: hookUrl(live),
+    };
+  },
+  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,
+      ),
+    ),
+  matches: (attributes, props) =>
+    attributes.type === props.type &&
+    attributes.url === props.url &&
+    attributes.active === (props.active ?? true) &&
+    attributes.contentType === (props.contentType ?? 'json') &&
+    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'])}`,
+});
+
+export const ForgejoRepoWebhookProvider = () =>
+  Provider.effect(ForgejoRepoWebhook, Effect.succeed(ForgejoRepoWebhook.Provider.of(handlers)));

package/src/forgejo/repository.ts

@@ -0,0 +1,126 @@
+/**
+ * `Forgejo.Repository` — an organization-owned git repository.
+ *
+ * ★ MEASURED 2026-09-13 against the live daemon (`GET /api/v1/repos/HomeFlare/homeflare-config`):
+ *   responses are flat JSON with `private`, `has_issues`, `default_branch`, etc. Create is
+ *   `POST /orgs/{org}/repos`; read/update/delete use `/repos/{owner}/{repo}`.
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — history, issues and packages in a repo are irreplaceable.
+ *   Opt into deletion with `.pipe(RemovalPolicy.destroy())`; `delete` below is fully implemented.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
+import { bool, text } from './values.ts';
+
+export interface RepositoryProps {
+  /** Organization login — the owner segment in `HomeFlare/homeflare-config`. */
+  org: string;
+  /** Repository name. Changing it is a replace, not an update. */
+  name: string;
+  description?: string;
+  private?: boolean;
+  hasIssues?: boolean;
+  hasWiki?: boolean;
+  hasProjects?: boolean;
+  /** Only applied when the repository already has at least one branch. */
+  defaultBranch?: string;
+  /** Create an initial commit with a README when the repository is new. */
+  autoInit?: boolean;
+}
+
+export interface RepositoryAttributes {
+  org: string;
+  name: string;
+  repoId: number;
+  description: string;
+  private: boolean;
+  hasIssues: boolean;
+  hasWiki: boolean;
+  hasProjects: boolean;
+  defaultBranch: string;
+  empty: boolean;
+}
+
+export interface ForgejoRepository extends Resource<
+  'Forgejo.Repository',
+  RepositoryProps,
+  RepositoryAttributes,
+  never,
+  ForgejoRequirements
+> {}
+
+export const ForgejoRepository = Resource<ForgejoRepository>('Forgejo.Repository', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const handlers = forgejoHandlers<RepositoryProps, RepositoryAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      defaultBranch: text(live['default_branch'], 'main'),
+      description: text(live['description']),
+      empty: bool(live['empty']),
+      hasIssues: bool(live['has_issues'], true),
+      hasProjects: bool(live['has_projects'], true),
+      hasWiki: bool(live['has_wiki'], true),
+      name: props.name,
+      org: props.org,
+      private: bool(live['private'], true),
+      repoId: id,
+    };
+  },
+  collection: (props) => `orgs/${props.org}/repos`,
+  createForm: (props) => ({
+    auto_init: props.autoInit ?? false,
+    description: props.description ?? '',
+    has_issues: props.hasIssues ?? true,
+    has_projects: props.hasProjects ?? true,
+    has_wiki: props.hasWiki ?? true,
+    name: props.name,
+    private: props.private ?? true,
+  }),
+  /**
+   * ⛔ AN UNDECLARED FIELD IS NEITHER COMPARED NOR SENT — the rule every other family in this
+   *   estate follows (storage.ts, backup-job.ts, and all four Pbs.* families say it in those
+   *   words), and this file was the exception.
+   *
+   * 🔴 WHAT THE EXCEPTION DID. Five fields were compared against a DEFAULT rather than skipped:
+   *   `description ?? ''`, and `?? true` for private, hasIssues, hasWiki and hasProjects. So a
+   *   declaration that simply did not mention `hasWiki` asserted "the wiki is ON", and one that
+   *   did not mention `description` asserted "the description is EMPTY" — and `updateForm` sent
+   *   both. Declaring a repo you only wanted to rename would have wiped its description and
+   *   switched features on, reported as a plain `update`. Only `defaultBranch` was written
+   *   correctly, on the line below, which is what the other five now copy.
+   *
+   * ⚠️ THE PRICE, STATED: dropping a line no longer resets a field. Clear one out of band in the
+   *   Forgejo UI or with a direct PATCH. It costs no forever-diff, because an undeclared field is
+   *   not compared either.
+   *
+   * ⚠️ `private` IS THE ONE WORTH DECLARING ANYWAY ON EVERY REPO. Leaving it undeclared now means
+   *   Alchemy will not notice a repository being made public. That is the correct trade for a
+   *   generic family — undeclared is unmanaged, not assumed — but it is a real gap, so say it
+   *   explicitly in each declaration rather than relying on a default that no longer exists.
+   */
+  matches: (attributes, props) =>
+    (props.description === undefined || attributes.description === props.description) &&
+    (props.private === undefined || attributes.private === props.private) &&
+    (props.hasIssues === undefined || attributes.hasIssues === props.hasIssues) &&
+    (props.hasWiki === undefined || attributes.hasWiki === props.hasWiki) &&
+    (props.hasProjects === undefined || attributes.hasProjects === props.hasProjects) &&
+    (props.defaultBranch === undefined || attributes.defaultBranch === props.defaultBranch),
+  path: (props) => `repos/${props.org}/${props.name}`,
+  updateForm: (props) => ({
+    ...(props.defaultBranch === undefined ? {} : { default_branch: props.defaultBranch }),
+    ...(props.description === undefined ? {} : { description: props.description }),
+    ...(props.hasIssues === undefined ? {} : { has_issues: props.hasIssues }),
+    ...(props.hasProjects === undefined ? {} : { has_projects: props.hasProjects }),
+    ...(props.hasWiki === undefined ? {} : { has_wiki: props.hasWiki }),
+    ...(props.private === undefined ? {} : { private: props.private }),
+  }),
+});
+
+export const ForgejoRepositoryProvider = () =>
+  Provider.effect(ForgejoRepository, Effect.succeed(ForgejoRepository.Provider.of(handlers)));

package/src/forgejo/resource.ts

@@ -0,0 +1,171 @@
+/**
+ * One shape for every Forgejo object — the same four operations, different path and JSON body.
+ *
+ * ⛔ THE ALTERNATIVE IS COPYING THE SAME HANDLERS PER RESOURCE. Repositories, org labels, teams,
+ *   runners, branch protection and package settings are all create / read / update / delete over
+ *   `/api/v1` with JSON bodies. Hand-rolling the fourth copy is where someone drops the read-back
+ *   or the isResolved guard and the plan lies.
+ *
+ * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE. A new Forgejo object should be a spec plus ~forty
+ *   lines, not a hundred and thirty.
+ *
+ * ⚠️ GITEA ANSWERS WITH THE OBJECT DIRECTLY — NOT `{"data": ...}`. See client.ts. reconcile still
+ *   READS BACK after every write rather than trusting the status code alone.
+ *
+ * ★ WHY `Forgejo.Repository` DECLARES `defaultRemovalPolicy: 'retain'`, WRITTEN ONCE HERE.
+ *   Alchemy's own `GitHub.Repository` defaults to retain "because their contents are
+ *   irreplaceable". A git repository is the most irreplaceable object on this estate. `retain`
+ *   means the engine skips `provider.delete` when a resource is orphaned unless the caller opted
+ *   into `.pipe(RemovalPolicy.destroy())`. The `delete` handler is FULLY IMPLEMENTED anyway — a
+ *   stub that silently does nothing lies to whoever reads the plan.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { ForgejoError, forgejo } from './client.ts';
+
+/**
+ * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME — and it is NOT what the first draft said.
+ *
+ *   These resources declared `ChildProcessSpawner`, copied from house/proxmox, where it is there
+ *   because a PVE credential is minted by shelling out to `bao`. Nothing in this package shells
+ *   out: the token comes from `FORGEJO_TOKEN` in the environment. Declaring a service you never
+ *   use is not harmless — it makes a stack provide a layer for nothing, and it hides the one
+ *   service you DO need.
+ *
+ *   What is actually required is `HttpClient`, for the reason in client.ts: Alchemy's own
+ *   providers call through Effect's client rather than the global `fetch`.
+ */
+export type ForgejoRequirements = HttpClient.HttpClient;
+
+export type ForgejoSpec<Props extends object, Attributes> = {
+  /** `repos/HomeFlare/homeflare`, `orgs/homeflare/labels/40` — one object. */
+  readonly path: (props: Props) => string;
+  /** `orgs/HomeFlare/repos`, `orgs/homeflare/labels` — where a new one is POSTed. */
+  readonly collection: (props: Props) => string;
+  readonly attributes: (live: Record<string, unknown>, props: Props) => Attributes | undefined;
+  /** JSON body on create. ⚠️ Gitea takes JSON, not form encoding. */
+  readonly createForm: (props: Props) => Record<string, unknown>;
+  readonly updateForm?: (props: Props) => Record<string, unknown>;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /**
+   * When the stable key is not enough for the wire path — org labels are addressed by numeric id.
+   * `locate` lists or searches; `wirePath` builds update/delete paths from the live row.
+   */
+  readonly locate?: (
+    props: Props,
+  ) => Effect.Effect<Record<string, unknown> | undefined, ForgejoError, ForgejoRequirements>;
+  readonly wirePath?: (props: Props, live: Record<string, unknown>) => string;
+  /**
+   * When create is PUT upsert rather than POST — org actions secrets have no POST and no GET-by-name.
+   * `before === undefined` means absent; the callback decides whether to write. Existence-only families
+   * noop when `before` is set because the API never returns the value for comparison.
+   */
+  readonly upsert?: (
+    props: Props,
+    before: Record<string, unknown> | undefined,
+  ) => Effect.Effect<void, ForgejoError, ForgejoRequirements>;
+};
+
+/** ⚠️ Only 404 folds to "absent". A 403 is a real failure — folding it would plan a create over an existing object. */
+const absentOn404 = <A>(io: Effect.Effect<A, ForgejoError, ForgejoRequirements>) =>
+  io.pipe(
+    Effect.catchIf(
+      (cause): cause is ForgejoError => cause instanceof ForgejoError && cause.status === 404,
+      () => Effect.succeed(undefined as A),
+    ),
+  );
+
+export const forgejoOperations = <Props extends object, Attributes>(
+  spec: ForgejoSpec<Props, Attributes>,
+) => {
+  const fetchLive = (props: Props) =>
+    absentOn404(
+      spec.locate !== undefined
+        ? spec.locate(props)
+        : forgejo<Record<string, unknown>>('GET', spec.path(props)),
+    );
+
+  const objectPath = (props: Props, live: Record<string, unknown>) =>
+    spec.wirePath === undefined ? spec.path(props) : spec.wirePath(props, live);
+
+  const read = (props: Props) =>
+    fetchLive(props).pipe(
+      Effect.map((data) => (data === undefined ? undefined : spec.attributes(data, props))),
+    );
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        if (spec.matches(live, news)) return { action: 'noop' } as const;
+        return spec.updateForm === undefined
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* fetchLive(news);
+        if (spec.upsert !== undefined) {
+          yield* spec.upsert(news, before);
+        } else if (before === undefined) {
+          yield* forgejo('POST', spec.collection(news), spec.createForm(news));
+        } else if (spec.updateForm !== undefined) {
+          const mapped = spec.attributes(before, news);
+          if (mapped === undefined || spec.matches(mapped, news)) {
+            /* adoption or already converged — no PATCH */
+          } else {
+            const form = spec.updateForm(news);
+            if (Object.keys(form).length > 0) {
+              yield* forgejo('PATCH', objectPath(news, before), form);
+            }
+          }
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              `${spec.path(news)}: the write returned no error but the object is still absent. ` +
+                'Gitea returns the object directly — read back rather than trusting the status code.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* fetchLive(olds);
+        if (live === undefined) return;
+        yield* forgejo('DELETE', objectPath(olds, live));
+      }),
+  };
+};
+
+/**
+ * The five provider handlers for a spec'd Forgejo object, wired once.
+ *
+ * ⛔ IT STOPS AT THE HANDLERS AND DOES NOT RETURN THE LAYER — same reasoning as pveHandlers in
+ *   house/proxmox: wrapping `Provider.effect` here needs casts against Alchemy's `Props<R>`.
+ *
+ * ⚠️ `list` answers empty — Forgejo index endpoints return the whole org; adoption stays explicit.
+ */
+export const forgejoHandlers = <Props extends object, Attributes extends object>(
+  spec: ForgejoSpec<Props, Attributes>,
+) => {
+  const ops = forgejoOperations(spec);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      ops.diff(news, output),
+    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
+    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+  };
+};