@homeflare/alchemy 0.13.0 → 0.15.0

package/docs/repo-policy-ruleset-hazards.md

@@ -0,0 +1,65 @@
+# `declareRepoPolicy` — the ruleset half's hazards
+
+Everything here is about `GitHub.Ruleset` in `alchemy@2.0.0-beta.79`, not about the
+policy this kit declares. It is extracted from [repo-policy.md](./repo-policy.md) so the
+reasoning stays whole rather than being shaved to fit a line cap.
+
+⚠️ **`GitHub.Repository` shares none of it.** Its `reconcile` probes by name, converges
+onto whatever is live, and `PATCH`es only the fields it holds. The two halves of the
+helper fail differently, which is the whole reason this file exists.
+
+## ⛔ The ruleset cannot be adopted — it duplicates
+
+Read out of `alchemy@2.0.0-beta.79`'s own source on 2026-09-22
+(`node_modules/alchemy/lib/github/Ruleset.js`):
+
+- `read` returns `undefined` whenever there is no prior `output`. Alchemy's adoption
+  routes on what `read` reports, so with no state the engine plans a **create**.
+- `reconcile` looks the live ruleset up **only by the id in that output**. With none, it
+  calls `createRepoRuleset` unconditionally — it never searches by name.
+
+GitHub permits several rulesets with the same name on one repository, so nothing errors.
+The repository quietly ends up with **two `main` rulesets, both enforcing**, and the
+second one is the only one Alchemy will ever converge.
+
+**Before the first deploy onto a repository that already has a ruleset:**
+
+```sh
+gh api repos/<owner>/<repo>/rulesets --jq '.[] | select(.target=="branch") | "\(.id) \(.name)"'
+```
+
+Delete the hand-made ruleset of the same name, or give this one a `rulesetName` of its
+own. After the first deploy the state carries the id and every later deploy converges
+that one ruleset.
+
+★ **Or take the repository half only.** `repoPolicy` returns the two prop objects
+separately, so a stack whose ruleset is already owned by something else can declare the
+settings that adopt cleanly and leave the ruleset alone:
+
+```ts
+yield * GitHub.Repository('api', repoPolicy({ owner, repository, checks }).repository);
+```
+
+⚠️ **`GitHub.Repository` does not share the problem.** Its `reconcile` probes by name and
+converges onto whatever is live, so the repository half adopts cleanly on the first
+deploy even though the plan prints `create`. The two halves of this helper fail
+differently, which is exactly why it is worth writing down.
+
+⛔ **The ruleset half never plans a no-op — measured, not inferred.** Alchemy `deepEqual`s
+the live ruleset against the parameters **it** builds, and it builds a strict subset of
+what GitHub stores. Read live on 2026-09-22 from this repo's own ruleset, GitHub returns
+`required_status_checks.parameters.do_not_enforce_on_create: false` and, on a
+`pull_request` rule, `required_reviewers`, `allowed_merge_methods` and
+`require_extra_approval_for_unattributed_changes` — none of which Alchemy sends. The
+comparison is therefore unequal **forever**, and every deploy issues an idempotent
+`updateRepoRuleset`. It is convergence noise, not drift: the write is the same payload
+each time. But do not expect a clean plan, and do not read the write as a change.
+
+⛔ **The ruleset's `rules` and `bypass_actors` are replaced wholesale, not merged.**
+Alchemy sends the full desired list. Any rule type this helper does not express —
+`creation`, `update`, `required_linear_history`, `required_signatures`,
+`required_deployments`, tag and file-path rules — is **dropped** from a ruleset Alchemy
+owns, as is any bypass actor added by hand. Because the ruleset cannot be adopted this
+cannot wipe a pre-existing one on a first deploy; it bites on a ruleset Alchemy created
+that someone later edited in the GitHub UI. The repository half does not behave this way:
+Alchemy `PATCH`es only the fields it holds, so settings outside `settings` are untouched.

package/docs/repo-policy.md

@@ -0,0 +1,155 @@
+# Repository policy
+
+One call that declares a GitHub repository's merge policy and the ruleset that enforces
+it: squash-only merges, auto-merge on, head branches deleted, and a ruleset over the
+default branch that blocks deletion and force pushes and requires the checks you name.
+
+```ts
+import { declareRepoPolicy } from '@homeflare/alchemy/github';
+import * as Effect from 'effect/Effect';
+
+Effect.gen(function* () {
+  // policy.repository → GitHub.Repository, policy.ruleset → GitHub.Ruleset
+  const policy = yield* declareRepoPolicy('api', {
+    owner: 'my-org',
+    repository: 'api',
+    checks: ['ci', 'secret scan'],
+  });
+});
+```
+
+Provide `GitHub.providers()`. This subpath ships **no provider of its own** — everything
+here composes Alchemy's first-class `GitHub.Repository` and `GitHub.Ruleset`.
+
+`repoPolicy(options)` is the same thing without the resources: the two prop objects, pure,
+for a test or for a stack that wants to declare them itself.
+
+## What it declares
+
+| where               | property                                 | value           |
+| ------------------- | ---------------------------------------- | --------------- |
+| `GitHub.Repository` | `allowSquashMerge`                       | `true`          |
+| `GitHub.Repository` | `allowMergeCommit`, `allowRebaseMerge`   | `false`         |
+| `GitHub.Repository` | `allowAutoMerge`                         | `autoMerge`     |
+| `GitHub.Repository` | `deleteBranchOnMerge`                    | `true`          |
+| `GitHub.Ruleset`    | `conditions.include`                     | `include`       |
+| `GitHub.Ruleset`    | `rules.deletion`, `rules.nonFastForward` | `true`          |
+| `GitHub.Ruleset`    | `rules.requiredStatusChecks.checks`      | `checks`        |
+| `GitHub.Ruleset`    | `strictRequiredStatusChecksPolicy`       | always `false`  |
+| `GitHub.Ruleset`    | `bypassActors`                           | `[]` by default |
+| `GitHub.Ruleset`    | `rules.pullRequest`                      | only if asked   |
+
+Everything about the repository that is **not** merge policy — description, topics,
+visibility, `hasWiki` — goes in `settings` and is merged underneath. ⛔ The policy fields
+are spread after it, and `RepoPolicyRepositorySettings` omits them, so `settings` cannot
+re-open a merge method through the back door.
+
+⛔ **`baseUrl` is a top-level option, not a `settings` field.** GitHub Enterprise has to
+apply to both resources or to neither; setting it on one would leave the repository on an
+Enterprise host and its ruleset on github.com.
+
+## ⛔ Auto-merge with nothing required merges immediately
+
+`gh pr merge --auto` reads like a queue. It is one **only while something is
+outstanding**. With no required status check and no required review pending, GitHub
+merges the pull request on the spot — the flag does not wait for CI that was never
+required to start.
+
+So `repoPolicy` refuses `autoMerge` whenever the ruleset would not hold anything back.
+⛔ **Five different inputs produce "nothing outstanding", and all five are refused:**
+
+| input                                     | why it merges anyway                                          |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| no `checks` and no `requiredApprovals`    | nothing is pending, so `--auto` merges now                    |
+| `enforcement: 'disabled'` / `'evaluate'`  | the rules are listed and none of them block — the quiet door  |
+| `include: []`                             | the ruleset matches no ref; GitHub still shows it as `active` |
+| a blank ref pattern, e.g. `include: ['']` | length is not coverage — matches no ref, past the guard       |
+| `exclude` cancelling every `include`      | exclusions win; reads as a narrowing, acts as an off switch   |
+
+★ The last two were found by adversarial review after the first cut shipped. The guard
+counted the array and spread `exclude` raw, so `include: ['   ']` and
+`include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` both produced an active
+ruleset over nothing with `allowAutoMerge: true` — the same end state the empty-array
+guard exists to prevent, through the door beside it.
+
+⚠️ **Exact cancellation only.** Deciding in general whether a glob `exclude` swallows an
+`include` means reimplementing GitHub's matcher and being quietly wrong about it. The
+helper refuses the decidable case — every `include` pattern appearing verbatim in
+`exclude` — and leaves `exclude: ['refs/heads/*']` to the operator.
+
+⚠️ **`bypassActors` is not checked against `autoMerge`, and is `[]` by default.** An actor
+you add can bypass the required checks; whether GitHub's auto-merge then lands the pull
+request on red was not measured here. Add bypass actors deliberately.
+
+⚠️ The test is "nothing outstanding", not "no checks" — a required review holds the pull
+request open just as a required check does, so `requiredApprovals` with an empty `checks`
+is allowed.
+
+A repository that has no green run to require yet is a real state; say so explicitly:
+
+```ts
+declareRepoPolicy('new-repo', { owner, repository, checks: [], autoMerge: false });
+```
+
+The branch is still protected — deletion and force pushes are blocked either way. Turn
+`autoMerge` and `checks` on together once there is a green run to name.
+
+## ⛔ Every context in `checks` must always report
+
+A required context that never reports is not "passed", it is **pending**, and the pull
+request waits on it forever — auto-merge included, which is the failure that looks like
+the tool being broken.
+
+Name an aggregate job that runs `if: always()` and fails when any upstream job did. Do
+not name a job behind a `paths:` filter, a matrix leg, or anything a skipped workflow can
+silence. Contexts are trimmed, de-duplicated and **sorted**, so writing the same two the
+other way round is not a diff.
+
+## ⛔ The ruleset half has hazards of its own
+
+The vendor `Ruleset` **cannot be adopted** — a first deploy onto a repository that
+already has a ruleset of that name creates a **second** one beside it, both enforcing —
+it **never plans a no-op**, and it replaces its `rules` and `bypass_actors` **wholesale**.
+None of that applies to the repository half.
+
+⛔ Read [repo-policy-ruleset-hazards.md](./repo-policy-ruleset-hazards.md) before the
+first deploy. It carries the preflight `gh api repos/<owner>/<repo>/rulesets` command and
+the repository-half-only escape hatch.
+
+## Required reviews are opt-in, and `0` is refused
+
+Omit `requiredApprovals` and no `pull_request` rule is declared at all — the house
+default, where a pull request is gated by its checks.
+
+`requiredApprovals: 2` declares the rule, with stale reviews dismissed on push.
+
+⛔ `requiredApprovals: 0` is **refused**, not treated as "no reviews". Zero approvals is
+the solo-maintainer shape — every change through a pull request, no second person — and
+it works only with `require_extra_approval_for_unattributed_changes: false`. Alchemy's
+`Ruleset` has no property for that field, and GitHub defaults it to `true` when it is
+omitted (measured 2026-09-17), which blocks the very pull requests the zero was meant to
+let through. Accepting it would ship a rule that does the opposite of what it says.
+
+## ★ `strict` is always off, and is not a parameter
+
+"Require branches to be up to date before merging" means every merge to the default
+branch invalidates every other open pull request. With auto-merge on, that is a re-run
+storm that settles only when the queue empties. The checks still have to pass; they just
+do not have to have passed against the very tip.
+
+## ★ `~DEFAULT_BRANCH`, not `refs/heads/main`
+
+`include` defaults to `['~DEFAULT_BRANCH']`, which GitHub resolves per repository. One
+policy covers a repo whose default branch is `master` or `trunk`, and renaming the
+default branch later does not leave the ruleset pointing at a branch that no longer
+exists. Pass your own `include`/`exclude` for anything else.
+
+## ★ Both resources retain
+
+`retain` is already the vendor default for `Repository` and `Ruleset`. The helper pipes
+it anyway, so that a vendor change cannot quietly turn "drop this call from the stack"
+into "delete the repository" or "unprotect the default branch". Opt into deletion with
+`RemovalPolicy.destroy()` at the call site if you really mean it.
+
+`adopt: true` / `adopt: false` pipe Alchemy's adopt policy onto both resources; omitted,
+the deploy's own policy decides. ⚠️ It changes nothing about the ruleset hazard above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -36,6 +36,10 @@
       "types": "./dist/forgejo/index.d.ts",
       "default": "./dist/forgejo/index.js"
     },
+    "./github": {
+      "types": "./dist/github/index.d.ts",
+      "default": "./dist/github/index.js"
+    },
     "./openbao": {
       "types": "./dist/openbao/index.d.ts",
       "default": "./dist/openbao/index.js"

package/src/github/index.ts

@@ -0,0 +1,23 @@
+/**
+ * GitHub helpers for Alchemy — one repository's house policy in one call.
+ *
+ * ⛔ THIS SUBPATH SHIPS NO PROVIDER, AND DELIBERATELY SO. GitHub is first-class in
+ *   Alchemy; everything here composes the vendor's own `Repository` and `Ruleset`.
+ *   Provide `GitHub.providers()` exactly as you would without it.
+ * ★ WHY IT EXISTS ANYWAY. "Open a pull request, let auto-merge land it" is safe only when
+ *   five repository properties and four ruleset rules all agree, and every way of getting
+ *   one of them wrong is silent — an auto-merge that lands on red, a force push that
+ *   rewrites the branch a release tagged, a required context nothing ever reports. One
+ *   call puts the whole policy in one place, and one place is where it gets fixed.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API. `repo-policy-form.ts` is reachable by path if you
+ *   genuinely need an internal — a deliberate act rather than an accident of barrelling.
+ */
+export {
+  type RepoPolicy,
+  type RepoPolicyBypassActor,
+  type RepoPolicyOptions,
+  type RepoPolicyRepositorySettings,
+  repoPolicy,
+} from './repo-policy-form.ts';
+export { type DeclareRepoPolicyOptions, declareRepoPolicy } from './repo-policy.ts';

package/src/github/repo-policy-form.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, test } from 'bun:test';
+import { type RepoPolicyRepositorySettings, repoPolicy } from './repo-policy-form.ts';
+
+const base = { checks: ['ci', 'secret scan'], owner: 'acme', repository: 'widget' } as const;
+
+describe('repoPolicy — the repository half', () => {
+  test('squash only, auto-merge on, head branches deleted', () => {
+    const { repository } = repoPolicy(base);
+
+    expect(repository).toMatchObject({
+      allowAutoMerge: true,
+      allowMergeCommit: false,
+      allowRebaseMerge: false,
+      allowSquashMerge: true,
+      deleteBranchOnMerge: true,
+      name: 'widget',
+      owner: 'acme',
+    });
+  });
+
+  test('caller settings pass through but cannot re-open a merge method', () => {
+    // ⛔ The policy fields are spread AFTER `settings` for exactly this reason. A caller
+    //   who could turn merge commits back on here would defeat the helper silently.
+    // ★ `RepoPolicyRepositorySettings` already OMITS the merge keys, so this cast is the
+    //   only way to write the call at all — the type is the first guard, this is the
+    //   second, for a JavaScript consumer the compiler never sees.
+    const settings = { allowMergeCommit: true, description: 'a widget' } as unknown;
+    const { repository } = repoPolicy({
+      ...base,
+      settings: settings as RepoPolicyRepositorySettings,
+    });
+
+    expect(repository.description).toBe('a widget');
+    expect(repository.allowMergeCommit).toBe(false);
+  });
+});
+
+describe('repoPolicy — the ruleset half', () => {
+  test('covers the default branch, blocks deletion and force pushes, strict off', () => {
+    const { ruleset } = repoPolicy(base);
+
+    expect(ruleset).toMatchObject({
+      enforcement: 'active',
+      name: 'main',
+      owner: 'acme',
+      repository: 'widget',
+      target: 'branch',
+    });
+    expect(ruleset.conditions).toEqual({ exclude: [], include: ['~DEFAULT_BRANCH'] });
+    expect(ruleset.rules?.deletion).toBe(true);
+    expect(ruleset.rules?.nonFastForward).toBe(true);
+    expect(ruleset.rules?.requiredStatusChecks?.strictRequiredStatusChecksPolicy).toBe(false);
+  });
+
+  test('nobody bypasses unless the caller names an actor', () => {
+    expect(repoPolicy(base).ruleset.bypassActors).toEqual([]);
+    expect(
+      repoPolicy({ ...base, bypassActors: [{ actorId: 5, actorType: 'RepositoryRole' }] }).ruleset
+        .bypassActors,
+    ).toEqual([{ actorId: 5, actorType: 'RepositoryRole' }]);
+  });
+
+  test('checks are trimmed, de-duplicated and sorted, so re-ordering is not a diff', () => {
+    // ⚠️ THE NO-OP PROPERTY. GitHub stores the contexts in the order they were sent, so
+    //   an unsorted list would diff against itself the first time someone wrote the same
+    //   two contexts the other way round — a deploy that changes nothing and says it did.
+    const one = repoPolicy({ ...base, checks: ['ci', 'secret scan'] });
+    const other = repoPolicy({ ...base, checks: [' secret scan ', 'ci', 'ci'] });
+
+    expect(other).toEqual(one);
+    expect(one.ruleset.rules?.requiredStatusChecks?.checks).toEqual([
+      { context: 'ci' },
+      { context: 'secret scan' },
+    ]);
+  });
+
+  test('the ruleset name and the refs it covers are the callers', () => {
+    const { ruleset } = repoPolicy({
+      ...base,
+      exclude: ['refs/heads/dev/*'],
+      include: ['refs/heads/release/*'],
+      rulesetName: 'release',
+    });
+
+    expect(ruleset.name).toBe('release');
+    expect(ruleset.conditions).toEqual({
+      exclude: ['refs/heads/dev/*'],
+      include: ['refs/heads/release/*'],
+    });
+  });
+});
+
+describe('repoPolicy — required reviews are opt-in', () => {
+  test('no pull_request rule unless approvals were asked for', () => {
+    expect(repoPolicy(base).ruleset.rules?.pullRequest).toBeUndefined();
+  });
+
+  test('asking for approvals declares the rule and dismisses stale reviews', () => {
+    expect(repoPolicy({ ...base, requiredApprovals: 2 }).ruleset.rules?.pullRequest).toEqual({
+      dismissStaleReviewsOnPush: true,
+      requiredApprovingReviewCount: 2,
+    });
+  });
+
+  test('zero approvals is refused, naming the flag Alchemy cannot send', () => {
+    // ⛔ Not pedantry: 0 is the solo-maintainer shape, and it needs a field the vendor
+    //   resource has no property for. Accepting it would ship a rule that blocks the
+    //   pull requests it was written to allow.
+    expect(() => repoPolicy({ ...base, requiredApprovals: 0 })).toThrow(
+      /require_extra_approval_for_unattributed_changes/,
+    );
+  });
+
+  test('a fractional or negative count is refused too', () => {
+    expect(() => repoPolicy({ ...base, requiredApprovals: 1.5 })).toThrow(/whole number/);
+    expect(() => repoPolicy({ ...base, requiredApprovals: -1 })).toThrow(/whole number/);
+  });
+});
+
+describe('repoPolicy — the auto-merge trap', () => {
+  test('auto-merge with nothing required at all is refused', () => {
+    // ⛔ THE TRAP THIS HELPER EXISTS FOR. `gh pr merge --auto` is a queue only while
+    //   something is outstanding; with nothing required GitHub merges on the spot.
+    expect(() => repoPolicy({ ...base, checks: [] })).toThrow(/immediately/);
+  });
+
+  test('a required review is something outstanding, so an empty checks list is fine', () => {
+    // ⚠️ The guard is not "no checks": auto-merge waits on a required approval too, and
+    //   refusing that combination would block a legitimate review-gated repository.
+    const { repository, ruleset } = repoPolicy({ ...base, checks: [], requiredApprovals: 1 });
+
+    expect(repository.allowAutoMerge).toBe(true);
+    expect(ruleset.rules?.requiredStatusChecks).toBeUndefined();
+    expect(ruleset.rules?.pullRequest?.requiredApprovingReviewCount).toBe(1);
+  });
+
+  test('turning auto-merge off is the only way to declare an empty checks list', () => {
+    const { repository, ruleset } = repoPolicy({ ...base, autoMerge: false, checks: [] });
+
+    expect(repository.allowAutoMerge).toBe(false);
+    expect(ruleset.rules?.requiredStatusChecks).toBeUndefined();
+    // The branch is still protected — that is the point of the bootstrap state.
+    expect(ruleset.rules?.deletion).toBe(true);
+    expect(ruleset.rules?.nonFastForward).toBe(true);
+  });
+
+  test('a blank context is refused rather than stored as a check nothing reports', () => {
+    expect(() => repoPolicy({ ...base, checks: ['ci', '  '] })).toThrow(/blank/);
+  });
+
+  test('auto-merge over a ruleset that is not enforcing is refused', () => {
+    // ⚠️ THE QUIET DOOR. The checks are listed on the ruleset and none of them block
+    //   anything, so auto-merge lands the pull request while the plan looks correct.
+    expect(() => repoPolicy({ ...base, enforcement: 'evaluate' })).toThrow(/enforcement/);
+    expect(() => repoPolicy({ ...base, enforcement: 'disabled' })).toThrow(/immediately/);
+    expect(
+      repoPolicy({ ...base, autoMerge: false, enforcement: 'evaluate' }).ruleset.enforcement,
+    ).toBe('evaluate');
+  });
+
+  test('an explicitly empty include is refused — it would match no ref at all', () => {
+    // ⚠️ THE QUIETEST DOOR. GitHub still shows the ruleset as active; it just covers
+    //   nothing, so every rule on it is decorative.
+    expect(() => repoPolicy({ ...base, include: [] })).toThrow(/matches no ref/);
+  });
+
+  test('a blank ref pattern is refused — length is not coverage', () => {
+    // ⚠️ THE DOOR BESIDE THE GUARD. `['   ']` has length 1, so a guard that counts the
+    //   array passes it; GitHub then stores a condition that matches nothing. Identical
+    //   end state to `include: []`, reached past the check that exists to stop it.
+    expect(() => repoPolicy({ ...base, include: ['   '] })).toThrow(/blank/);
+    expect(() => repoPolicy({ ...base, exclude: [''] })).toThrow(/blank/);
+  });
+
+  test('an exclude that cancels every include is refused', () => {
+    // ⚠️ THE DOOR THAT READS AS A NARROWING. Exclusions win in a GitHub ruleset, so this
+    //   is a ruleset over nothing — but it looks like scoping, not like switching off.
+    expect(() => repoPolicy({ ...base, exclude: ['~DEFAULT_BRANCH'] })).toThrow(
+      /cancels every include/,
+    );
+    expect(() =>
+      repoPolicy({
+        ...base,
+        exclude: ['refs/heads/release/*', 'refs/heads/main'],
+        include: ['refs/heads/main', 'refs/heads/release/*'],
+      }),
+    ).toThrow(/cancels every include/);
+  });
+
+  test('an exclude that leaves an include standing is a narrowing, and allowed', () => {
+    // ★ EXACT CANCELLATION ONLY. Deciding glob overlap in general means reimplementing
+    //   GitHub's matcher; a narrow guard that is always right beats a broad one that
+    //   false-refuses a legitimate scope.
+    const { ruleset } = repoPolicy({
+      ...base,
+      exclude: ['refs/heads/release/*'],
+      include: ['~DEFAULT_BRANCH', 'refs/heads/release/*'],
+    });
+
+    // ★ Sorted, so `refs/…` precedes the `~` tokens — the ordering is normalization, not
+    //   a preference, and it is what keeps a second deploy from diffing against itself.
+    expect(ruleset.conditions).toEqual({
+      exclude: ['refs/heads/release/*'],
+      include: ['refs/heads/release/*', '~DEFAULT_BRANCH'],
+    });
+  });
+
+  test('ref patterns are trimmed, de-duplicated and sorted, so re-ordering is not a diff', () => {
+    const one = repoPolicy({ ...base, include: ['refs/heads/main', 'refs/heads/release/*'] });
+    const other = repoPolicy({
+      ...base,
+      include: [' refs/heads/release/* ', 'refs/heads/main', 'refs/heads/main'],
+    });
+
+    expect(other).toEqual(one);
+  });
+});
+
+describe('repoPolicy — one host for both halves', () => {
+  test('baseUrl reaches the repository and the ruleset, or neither', () => {
+    // ⛔ Setting it on one would point the repository at an Enterprise host and its
+    //   ruleset at github.com — two halves of one policy on two different instances.
+    const { repository, ruleset } = repoPolicy({ ...base, baseUrl: 'github.example.com' });
+
+    expect(repository.baseUrl).toBe('github.example.com');
+    expect(ruleset.baseUrl).toBe('github.example.com');
+
+    const plain = repoPolicy(base);
+    expect('baseUrl' in plain.repository).toBe(false);
+    expect('baseUrl' in plain.ruleset).toBe(false);
+  });
+});
+
+describe('repoPolicy — required inputs', () => {
+  test('an empty owner or repository is refused', () => {
+    expect(() => repoPolicy({ ...base, owner: ' ' })).toThrow(/owner is required/);
+    expect(() => repoPolicy({ ...base, repository: '' })).toThrow(/repository is required/);
+  });
+});

package/src/github/repo-policy-form.ts

@@ -0,0 +1,173 @@
+/**
+ * `repoPolicy` — one repository's house merge policy, as plain Alchemy props.
+ *
+ * ★ PURE ON PURPOSE, AND TYPE-ONLY IMPORTS. The exact shape a stack will deploy can be
+ *   asserted in a unit test with no credentials, no network and no Effect runtime.
+ *   `repo-policy.ts` is the thin half that turns these props into resources, and
+ *   `repo-policy-guards.ts` holds everything this refuses and why.
+ *
+ * ⛔ AUTO-MERGE WITH NOTHING TO WAIT FOR MERGES IMMEDIATELY. `gh pr merge --auto` is a
+ *   queue only while something is outstanding. Five different inputs produce "nothing
+ *   outstanding" — no `checks` and no `requiredApprovals`, an `enforcement` that is not
+ *   `active`, and three ways to land a ruleset that matches no ref (an empty `include`, a
+ *   blank ref pattern, an `exclude` that cancels every `include`). All five are refused.
+ *   See the guards module.
+ *
+ * ⛔ EVERY CONTEXT IN `checks` MUST ALWAYS REPORT. A required context that never reports
+ *   is not "passed", it is "pending", and the pull request waits on it forever —
+ *   auto-merge included. Point this at an aggregate job that runs `if: always()` and
+ *   fails when any upstream job did, never at a job behind a `paths:` filter, a matrix
+ *   leg, or anything a skipped workflow can silence.
+ */
+import type { RepositoryProps, RulesetProps } from 'alchemy/GitHub';
+import {
+  assertAutoMergeWaits,
+  normalizeChecks,
+  normalizeExclude,
+  normalizeInclude,
+  requireName,
+  resolveApprovals,
+} from './repo-policy-guards.ts';
+
+/** Alchemy's own bypass-actor shape, re-exported so a caller imports one module, not two. */
+export type RepoPolicyBypassActor = NonNullable<RulesetProps['bypassActors']>[number];
+
+/**
+ * Repository fields the policy does NOT own — description, topics, visibility, …
+ * ⛔ Merged UNDERNEATH the policy, so a caller can describe their repo but cannot quietly
+ *   re-enable merge commits through this door. The omitted keys are the policy itself.
+ * ⛔ `baseUrl` IS OMITTED TOO, and is a top-level option instead. Setting it on only one
+ *   of the two resources would point the repository at a GitHub Enterprise host and its
+ *   ruleset at github.com — two halves of one policy on two different instances.
+ */
+export type RepoPolicyRepositorySettings = Omit<
+  RepositoryProps,
+  | 'allowAutoMerge'
+  | 'allowMergeCommit'
+  | 'allowRebaseMerge'
+  | 'allowSquashMerge'
+  | 'baseUrl'
+  | 'deleteBranchOnMerge'
+  | 'name'
+  | 'owner'
+>;
+
+export interface RepoPolicyOptions {
+  /** Repository owner — a user or organization login. */
+  readonly owner: string;
+  /** Repository name. */
+  readonly repository: string;
+  /**
+   * Status-check contexts a pull request must pass, named exactly as the job reports
+   * them. Trimmed, de-duplicated and sorted, so re-ordering the list is not a diff.
+   */
+  readonly checks: readonly string[];
+  /** @default true — with nothing required it is refused, not quietly downgraded. */
+  readonly autoMerge?: boolean;
+  /** @default 'main' */
+  readonly rulesetName?: string;
+  /** Ref patterns the ruleset covers. @default ['~DEFAULT_BRANCH'] */
+  readonly include?: readonly string[];
+  /**
+   * Ref patterns exempted from it. @default []
+   * ⛔ Exclusions win over inclusions, so one that cancels every `include` is refused —
+   *   it reads as a narrowing and acts as an off switch.
+   */
+  readonly exclude?: readonly string[];
+  /** Who may bypass the ruleset. @default [] — nobody, administrators included. */
+  readonly bypassActors?: readonly RepoPolicyBypassActor[];
+  /**
+   * Approving reviews a pull request needs. Omit for none — `0` is refused rather than
+   * read as "no reviews"; `resolveApprovals` in the guards module says why.
+   */
+  readonly requiredApprovals?: number;
+  /** @default 'active' — anything else is refused alongside `autoMerge`. */
+  readonly enforcement?: 'active' | 'disabled' | 'evaluate';
+  /** GitHub Enterprise host, applied to BOTH resources or to neither. */
+  readonly baseUrl?: string;
+  /** Everything about the repository that is not merge policy. */
+  readonly settings?: RepoPolicyRepositorySettings;
+}
+
+export interface RepoPolicy {
+  readonly repository: RepositoryProps;
+  readonly ruleset: RulesetProps;
+}
+
+const DEFAULT_RULESET_NAME = 'main';
+/**
+ * ★ `~DEFAULT_BRANCH`, NOT `refs/heads/main`. GitHub resolves it per repository, so one
+ *   policy covers a repo whose default branch is `master` or `trunk`, and renaming the
+ *   default branch later does not silently leave the ruleset pointing at nothing.
+ */
+const DEFAULT_INCLUDE: readonly string[] = ['~DEFAULT_BRANCH'];
+
+/**
+ * The house policy for one repository: squash-only merges, auto-merge on, head branches
+ * deleted, and a ruleset over the default branch that blocks deletion and force pushes
+ * and requires `checks`.
+ *
+ * ★ `strictRequiredStatusChecksPolicy` IS ALWAYS FALSE, AND NOT A PARAMETER. "Require
+ *   branches to be up to date" means every merge to the default branch invalidates every
+ *   other open pull request, which with auto-merge on is a re-run storm that converges
+ *   only when the queue empties. The checks still have to pass; they just do not have to
+ *   have passed against the very tip.
+ */
+export function repoPolicy(options: RepoPolicyOptions): RepoPolicy {
+  const owner = requireName('owner', options.owner);
+  const repository = requireName('repository', options.repository);
+  const checks = normalizeChecks(options.checks);
+  const include = normalizeInclude(options.include, DEFAULT_INCLUDE);
+  const exclude = normalizeExclude(options.exclude, include);
+  const autoMerge = options.autoMerge ?? true;
+  const enforcement = options.enforcement ?? 'active';
+  const approvals = resolveApprovals(options.requiredApprovals);
+  assertAutoMergeWaits({ approvals, autoMerge, checkCount: checks.length, enforcement });
+  const host = options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl };
+
+  return {
+    repository: {
+      ...options.settings,
+      ...host,
+      // ⛔ Squash only. The ruleset's own `allowed_merge_methods` is not reachable through
+      //   Alchemy's `pullRequest` rule, so the repository is the only place this holds.
+      allowAutoMerge: autoMerge,
+      allowMergeCommit: false,
+      allowRebaseMerge: false,
+      allowSquashMerge: true,
+      deleteBranchOnMerge: true,
+      name: repository,
+      owner,
+    },
+    ruleset: {
+      ...host,
+      bypassActors: [...(options.bypassActors ?? [])],
+      conditions: { exclude, include },
+      enforcement,
+      name: options.rulesetName ?? DEFAULT_RULESET_NAME,
+      owner,
+      repository,
+      rules: {
+        deletion: true,
+        nonFastForward: true,
+        ...(approvals === undefined
+          ? {}
+          : {
+              pullRequest: {
+                dismissStaleReviewsOnPush: true,
+                requiredApprovingReviewCount: approvals,
+              },
+            }),
+        ...(checks.length === 0
+          ? {}
+          : {
+              requiredStatusChecks: {
+                checks: checks.map((context) => ({ context })),
+                strictRequiredStatusChecksPolicy: false,
+              },
+            }),
+      },
+      target: 'branch',
+    },
+  };
+}