@homeflare/alchemy 0.26.0 → 0.27.1

package/src/github/repository-ruleset-write-refusals.test.ts

@@ -0,0 +1,199 @@
+/**
+ * (ii) The write-recording fake, refusals: duplicate names, bypass widening, an undeclared live
+ * rule, required checks omitted, and a never-reported context each make ZERO writes; and a
+ * readback mismatch fails even though the write itself "succeeded" (S10). The happy paths
+ * (create, noop, update) are repository-ruleset-write.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeGetOnlyFake, makeRecordingFake } from './repository-ruleset-fake-octokit.ts';
+import type { RulesetOctokit } from './repository-ruleset-probe.ts';
+import {
+  BASE_PULL_REQUEST,
+  fails,
+  props,
+  reconcileAgainst,
+  reconcileWithOctokit,
+  tagOf,
+} from './repository-ruleset-test-helpers.ts';
+
+describe('refusals make zero writes', () => {
+  test('duplicate ruleset names', async () => {
+    const fake: RulesetOctokit = {
+      list: () =>
+        Effect.succeed([
+          { id: 1, name: 'main', target: 'branch' },
+          { id: 2, name: 'main', target: 'branch' },
+        ]),
+      get: () => Effect.succeed(undefined),
+      create: () => Effect.fail(new Error('must not be called')),
+      update: () => Effect.fail(new Error('must not be called')),
+      delete: () => Effect.fail(new Error('must not be called')),
+      hasContextReportedSuccess: () => Effect.succeed(true),
+    };
+    const error = await fails(reconcileWithOctokit(fake, props()));
+    expect(tagOf(error)).toBe('DuplicateRuleset');
+  });
+
+  test('bypass widening', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const error = await fails(
+      reconcileWithOctokit(fake, props({ bypassActors: [{ actorType: 'OrganizationAdmin' }] }), {
+        rulesetId: 1,
+      }),
+    );
+    expect(tagOf(error)).toBe('BypassActorWidened');
+  });
+
+  test('a refused live rule type (e.g. workflows) blocks any write', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [{ type: 'workflows', parameters: {} }],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const error = await fails(reconcileWithOctokit(fake, props(), { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('UndeclaredLiveRule');
+  });
+
+  // Regression for a bug this family's own first cut shipped with: an omitted boolean rule
+  // (as opposed to one explicitly declared `false`) was treated as "fully owned, so absence
+  // is the removal" and never refused — meaning forgetting `deletion: true` in a declaration
+  // would silently drop branch-deletion protection from a live ruleset on the next update.
+  // Found by self-review, not by a failing test; see undeclaredLiveRuleRefusal's own comment.
+  test('an omitted boolean rule (not declared false) the live ruleset has blocks any write', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'non_fast_forward' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    // Declares pullRequest but says nothing at all about `deletion` — not even `false`.
+    const declaration = props({
+      rules: { nonFastForward: true, pullRequest: BASE_PULL_REQUEST },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('UndeclaredLiveRule');
+  });
+
+  test('the SAME live ruleset with deletion explicitly declared false is a deliberate removal, not refused', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeRecordingFake({ widgets: live });
+    fake.reportedContexts.add('ci');
+    const declaration = props({
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+    });
+    await reconcileAgainst(fake, declaration, { rulesetId: 1 }).pipe(Effect.runPromise);
+    expect(fake.writes).toHaveLength(1);
+    expect(fake.writes[0]?.op).toBe('update');
+    const sentTypes = fake.writes[0]?.body?.rules?.map((r) => r.type);
+    expect(sentTypes).not.toContain('deletion');
+  });
+
+  test('required checks omitted while the live ruleset has them', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        {
+          type: 'required_status_checks',
+          parameters: { required_status_checks: [{ context: 'ci' }] },
+        },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      rules: { deletion: true, nonFastForward: true, pullRequest: BASE_PULL_REQUEST },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('RequiredChecksOmitted');
+  });
+
+  test('a never-reported context refuses before any write', async () => {
+    const fake = makeRecordingFake({});
+    // `reportedContexts` starts empty — `ci` has never reported.
+    const error = await fails(reconcileAgainst(fake, props()));
+    expect(tagOf(error)).toBe('NeverReportedContext');
+    expect(fake.writes).toHaveLength(0);
+  });
+});
+
+describe('readback', () => {
+  test('fails when the independent re-read does not match what was sent', async () => {
+    // A hand-built fake, not `makeRecordingFake` — the point here is specifically that `get`
+    // (the INDEPENDENT re-read) can disagree with what `create` echoed back, simulating GitHub
+    // accepting the write but not persisting it as declared (S10: never trust the write's own
+    // report as proof).
+    const created = {
+      id: 1,
+      name: 'main',
+      target: 'branch',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        {
+          type: 'pull_request',
+          parameters: { required_approving_review_count: 0, allowed_merge_methods: ['squash'] },
+        },
+      ],
+    };
+    const persisted = {
+      ...created,
+      rules: [
+        // GitHub silently kept every method instead of narrowing to squash.
+        {
+          type: 'pull_request',
+          parameters: {
+            required_approving_review_count: 0,
+            allowed_merge_methods: ['merge', 'squash', 'rebase'],
+          },
+        },
+      ],
+    };
+    const fake: RulesetOctokit = {
+      list: () => Effect.succeed([]),
+      get: () => Effect.succeed(persisted),
+      create: () => Effect.succeed(created),
+      update: () => Effect.fail(new Error('not exercised')),
+      delete: () => Effect.fail(new Error('not exercised')),
+      hasContextReportedSuccess: () => Effect.succeed(true),
+    };
+    const declaration = props({
+      rules: { deletion: true, nonFastForward: true, pullRequest: BASE_PULL_REQUEST },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration));
+    expect(tagOf(error)).toBe('ReadbackMismatch');
+  });
+});

package/src/github/repository-ruleset-write.test.ts

@@ -0,0 +1,83 @@
+/**
+ * (ii) The write-recording fake, happy paths: a create sends the extension flag and
+ * `allowedMergeMethods`; a matching live ruleset makes zero writes (S10); one drifted field
+ * makes exactly one `update`, never a create. Refusals (zero writes) and the readback check
+ * are repository-ruleset-write-refusals.test.ts, split out to stay under the 250-line cap.
+ */
+import { describe, expect, test } from 'bun:test';
+import { makeRecordingFake } from './repository-ruleset-fake-octokit.ts';
+import { desiredWireRuleset } from './repository-ruleset-form.ts';
+import { props, reconcileAgainst, run } from './repository-ruleset-test-helpers.ts';
+
+describe('create', () => {
+  test('sends allowedMergeMethods and the extension flag, and nothing else creates', async () => {
+    const fake = makeRecordingFake({});
+    fake.reportedContexts.add('ci');
+    const attrs = await run(reconcileAgainst(fake, props()));
+    expect(fake.writes).toHaveLength(1);
+    const [write] = fake.writes;
+    expect(write?.op).toBe('create');
+    expect(write?.repo).toBe('widgets');
+    const pr = write?.body?.rules?.find((r) => r.type === 'pull_request');
+    expect(
+      (pr as { parameters: Record<string, unknown> }).parameters.allowed_merge_methods,
+    ).toEqual(['squash']);
+    expect(
+      (pr as { parameters: Record<string, unknown> }).parameters
+        .require_extra_approval_for_unattributed_changes,
+    ).toBe(false);
+    expect(attrs.name).toBe('main');
+  });
+});
+
+describe('noop and update', () => {
+  test('a matching live ruleset makes zero writes', async () => {
+    const desired = desiredWireRuleset(props());
+    const fake = makeRecordingFake({
+      widgets: {
+        id: 1,
+        name: desired.name,
+        target: desired.target,
+        source_type: 'Repository',
+        enforcement: desired.enforcement,
+        bypass_actors: desired.bypass_actors as never,
+        conditions: desired.conditions,
+        rules: desired.rules as never,
+      },
+    });
+    fake.reportedContexts.add('ci');
+    await run(reconcileAgainst(fake, props(), { rulesetId: 1 }));
+    expect(fake.writes).toHaveLength(0);
+  });
+
+  test('one drifted field makes exactly one update, never a create', async () => {
+    const desired = desiredWireRuleset(props());
+    const fake = makeRecordingFake({
+      widgets: {
+        id: 1,
+        name: desired.name,
+        target: desired.target,
+        source_type: 'Repository',
+        enforcement: desired.enforcement,
+        bypass_actors: desired.bypass_actors as never,
+        conditions: desired.conditions,
+        rules: (desired.rules ?? []).map((r) =>
+          r.type === 'pull_request'
+            ? {
+                ...r,
+                parameters: {
+                  ...r.parameters,
+                  allowed_merge_methods: ['merge', 'squash', 'rebase'],
+                },
+              }
+            : r,
+        ) as never,
+      },
+    });
+    fake.reportedContexts.add('ci');
+    await run(reconcileAgainst(fake, props(), { rulesetId: 1 }));
+    expect(fake.writes).toHaveLength(1);
+    const [write] = fake.writes;
+    expect(write?.op).toBe('update');
+  });
+});

package/src/github/repository-ruleset.ts

@@ -0,0 +1,219 @@
+/**
+ * `GitHub.RepositoryRuleset` — a bridge resource for the one thing upstream `GitHub.Ruleset`
+ * cannot do: find a ruleset that already exists before creating a second one with the same
+ * name.
+ *
+ * ⛔ THE HAZARD THIS EXISTS TO CLOSE. Read out of `alchemy@2.0.0-beta.79`'s own source
+ *   (`node_modules/alchemy/src/GitHub/Ruleset.ts`, `reconcile`): `let observed = output ===
+ *   undefined ? undefined : yield* getRuleset(news, output.rulesetId)`. With no prior state,
+ *   `observed` stays `undefined` and `createRepoRuleset` runs UNCONDITIONALLY — there is no
+ *   probe by name. GitHub permits several rulesets with one name on a repository, so nothing
+ *   errors; the repo quietly ends up with two, both enforcing. `declareRepoPolicy` in this same
+ *   package (repo-policy.ts) documents the same hazard and tells a caller to check `gh api
+ *   repos/<owner>/<repo>/rulesets` by hand before every first deploy. This resource makes that
+ *   check the engine's own job: `read`/`reconcile` list-and-filter by name+target before ever
+ *   creating (see repository-ruleset-probe.ts).
+ *
+ * ★ WHY A NEW TYPE STRING, NOT A PATCHED `GitHub.Ruleset`. Upstream's `Ruleset` cannot be
+ *   edited from here — it ships inside the `alchemy` package. `GitHub.RepositoryRuleset` is a
+ *   distinct `Provider` (its own `Context.Service` keyed by this type string — see
+ *   `alchemy/src/Provider.ts#Provider`), so it is declared and merged into a stack's provider
+ *   layer independently of `GitHub.providers()` — the same way `postgres/database.ts` merges
+ *   `PostgresDatabaseProvider()` beside it. Nothing about upstream's `GitHub.Providers`
+ *   collection needs touching for the two to coexist in one stack. Props are a strict superset
+ *   of upstream's `RulesetProps` (H14: the type string sits inside upstream's own `GitHub`
+ *   namespace, recorded as house difference H15 below for the client choice).
+ *
+ * ⛔ H15: CLIENT IS OCTOKIT, NOT DISTILLED — A NAMED DIVERGENCE FROM S23. The house's default is
+ *   `@distilled.cloud/*` when a vendor SDK exists there, and `@distilled.cloud/github@1.0.0-rc.12`
+ *   does ship `createRepoRuleset`/`updateRepoRuleset`. But it has NO field for
+ *   `require_extra_approval_for_unattributed_changes` (measured 2026-09-22: grep of its
+ *   generated types), and its request bodies are plain `effect/Schema` `S.Struct`s, which strip
+ *   properties a schema does not declare on encode — REASONED, not measured against distilled
+ *   itself; repository-ruleset-wire.test.ts measures the Octokit side of the same question
+ *   instead, because Octokit is the client this file actually uses. That flag is the entire
+ *   reason this resource exists for the 0-approval, solo-maintainer shape (see
+ *   repo-policy-guards.ts's `resolveApprovals` for the same story on the upstream-only path):
+ *   GitHub defaults it to `true` when absent, which blocks the very pull requests a `0` was
+ *   meant to allow. `octokitFor`/`GitHubCredentials` are upstream's own EXPORTED building
+ *   blocks (S23's second clause: reuse Alchemy's own client construction), so the client itself
+ *   is not hand-rolled — only the choice of Octokit over distilled is a recorded divergence.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { GitHubCredentials, RulesetProps } from 'alchemy/GitHub';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import {
+  allowedMergeMethodsRefusal,
+  approvalCountRefusal,
+} from './repository-ruleset-constraints.ts';
+import { RulesetConstraintRefused } from './repository-ruleset-errors.ts';
+import { makeRulesetOctokit } from './repository-ruleset-octokit.ts';
+import { type RulesetRecord, probeByName } from './repository-ruleset-probe.ts';
+import { reconcileRuleset } from './repository-ruleset-reconcile.ts';
+
+type UpstreamRules = NonNullable<RulesetProps['rules']>;
+
+export interface RepositoryRulesetReviewerRule {
+  readonly filePatterns: readonly string[];
+  readonly minimumApprovals: number;
+  readonly reviewer: { readonly actorId: number; readonly actorType: 'Team' };
+}
+
+export interface RepositoryRulesetPullRequestRule extends NonNullable<
+  UpstreamRules['pullRequest']
+> {
+  /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
+  readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
+  readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
+  /** `require_extra_approval_for_unattributed_changes` — see H15 above. Only `false` is
+   * modeled: sending `true` has no house use, and GitHub already defaults absent to `true`. */
+  readonly extraApprovalForUnattributedChanges?: false;
+}
+
+export interface RepositoryRulesetStatusChecksRule extends NonNullable<
+  UpstreamRules['requiredStatusChecks']
+> {
+  readonly doNotEnforceOnCreate?: boolean;
+}
+
+export interface RepositoryRulesetRules extends Omit<
+  UpstreamRules,
+  'pullRequest' | 'requiredStatusChecks'
+> {
+  readonly pullRequest?: RepositoryRulesetPullRequestRule;
+  /** `undefined`: no opinion (refused if the live ruleset already has one — see
+   * repository-ruleset-guards.ts). `false`: declare its ABSENCE — removes a live one. */
+  readonly requiredStatusChecks?: RepositoryRulesetStatusChecksRule | false;
+}
+
+export interface RepositoryRulesetProps extends Omit<RulesetProps, 'rules'> {
+  readonly rules?: RepositoryRulesetRules;
+}
+
+export interface RepositoryRulesetAttributes {
+  readonly rulesetId: number;
+  readonly nodeId: string | undefined;
+  readonly name: string;
+  readonly createdAt: string | undefined;
+  readonly updatedAt: string | undefined;
+}
+
+export interface RepositoryRuleset extends Resource<
+  'GitHub.RepositoryRuleset',
+  RepositoryRulesetProps,
+  RepositoryRulesetAttributes,
+  never,
+  GitHubCredentials
+> {}
+
+export const RepositoryRuleset = Resource<RepositoryRuleset>('GitHub.RepositoryRuleset', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const attrsOf = (r: RulesetRecord): RepositoryRulesetAttributes => ({
+  rulesetId: r.id,
+  nodeId: r.node_id,
+  name: r.name,
+  createdAt: r.created_at,
+  updatedAt: r.updated_at,
+});
+
+/** Plan-time-only refusals — no live data needed, so these run before any read (schema-codegen's
+ * rule: check the form before the "no previous state" branch, never after it). */
+function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefused | undefined {
+  const approvals = props.rules?.pullRequest?.requiredApprovingReviewCount;
+  if (approvals !== undefined) {
+    const reason = approvalCountRefusal(approvals);
+    if (reason !== undefined) {
+      return new RulesetConstraintRefused({
+        field: 'rules.pullRequest.requiredApprovingReviewCount',
+        reason,
+      });
+    }
+  }
+  const methods = props.rules?.pullRequest?.allowedMergeMethods;
+  if (methods !== undefined) {
+    const reason = allowedMergeMethodsRefusal(methods);
+    if (reason !== undefined) {
+      return new RulesetConstraintRefused({
+        field: 'rules.pullRequest.allowedMergeMethods',
+        reason,
+      });
+    }
+  }
+  return undefined;
+}
+
+export const repositoryRulesetHandlers = RepositoryRuleset.Provider.of({
+  // Account-wide, cross-repo enumeration duplicates upstream `GitHub.Ruleset`'s own `list` for
+  // no benefit here — every RepositoryRuleset is declared once, by name, in a checkout's own
+  // stack (S12 already defaults this; nuke should never touch a `retain` ruleset regardless).
+  list: () => Effect.succeed([]),
+  nuke: { skip: true },
+
+  read: ({ output, olds }) =>
+    Effect.gen(function* () {
+      const octokit = makeRulesetOctokit(olds.baseUrl);
+      if (output === undefined) {
+        const match = yield* probeByName(octokit, {
+          owner: olds.owner,
+          repo: olds.repository,
+          name: olds.name,
+          target: olds.target ?? 'branch',
+        });
+        // Identical is not ours (H1): a name match with no prior state needs adopt(true).
+        return match === undefined ? undefined : Unowned(attrsOf(match));
+      }
+      const byId = yield* octokit.get({
+        owner: olds.owner,
+        repo: olds.repository,
+        rulesetId: output.rulesetId,
+      });
+      if (byId !== undefined) return attrsOf(byId);
+      const byName = yield* probeByName(octokit, {
+        owner: olds.owner,
+        repo: olds.repository,
+        name: olds.name,
+        target: olds.target ?? 'branch',
+      });
+      return byName === undefined ? undefined : attrsOf(byName);
+    }),
+
+  // Plain function, not `Effect.fn(function* …)` — there is nothing here to `yield*`, and an
+  // empty generator is its own lint hazard (oxlint's `require-yield`) for a reason: it reads as
+  // an unfinished `Effect.gen` body.
+  diff: ({ news, olds }) =>
+    Effect.succeed(
+      isResolved(news) &&
+        olds !== undefined &&
+        (news.owner !== olds.owner || news.repository !== olds.repository)
+        ? ({ action: 'replace' } as const)
+        : undefined,
+    ),
+
+  reconcile: ({ news, output }) =>
+    reconcileRuleset({
+      octokit: makeRulesetOctokit(news.baseUrl),
+      news,
+      output,
+      constraintRefusal,
+      attrsOf,
+    }),
+
+  delete: ({ olds, output }) =>
+    Effect.gen(function* () {
+      if (output?.rulesetId === undefined) return;
+      const octokit = makeRulesetOctokit(olds.baseUrl);
+      yield* octokit.delete({
+        owner: olds.owner,
+        repo: olds.repository,
+        rulesetId: output.rulesetId,
+      });
+    }),
+});
+
+export const RepositoryRulesetProvider = () =>
+  Provider.succeed(RepositoryRuleset, repositoryRulesetHandlers);

package/src/launchd/port-claims.ts

@@ -3,13 +3,12 @@
  * runtime-portable (no `Bun.*`, no `node:*`), so a future Linux consumer (systemd units, under
  * `/linux`) can import it unchanged.
  *
- * ★ MIRRORS house/nix's REGISTRY, NOT A NEW RULE. `lib-ports.nix` (house @ 92cff7f) collides on
- *   `lib.attrValues ports` alone — `dupes = lib.subtractLists (lib.unique vals) vals` — keying on
- *   the PORT NUMBER by itself; address and protocol are never read. `portClaimProblems` below keys
- *   the same way on purpose: it replaces that check for the jobs a kit stack declares, and a looser
- *   or stricter rule would silently diverge from the registry it takes over from. What that trades
- *   away — a wildcard bind beside a specific one on the same port both succeed, silently splitting
- *   traffic — is measured in docs/launchd-ports.md, not assumed.
+ * ★ KEYS ON THE PORT NUMBER ALONE, NOT A NEW RULE. `portClaimProblems` below matches the estate's
+ *   existing port-collision strictness — address and protocol never read — deliberately: a looser
+ *   or stricter rule here would be a second, inconsistent source of truth for jobs migrating off a
+ *   host's own port registry (still enforcing that same strictness until a job leaves it). What
+ *   this trades away — a wildcard bind beside a specific one on the same port both succeed,
+ *   silently splitting traffic — is measured in docs/launchd-ports.md, not assumed.
  * ★ IN THE STACK PROGRAM, NOT A PROVIDER — same shape as `catalogBinary()` (../release/catalog.ts).
  *   Two reasons, both structural to Alchemy 2.0.0-beta.79: Alchemy never diffs a first `create`
  *   whose props still hold an unresolved `Output`, and every mini job's `programArguments` carries
@@ -38,8 +37,8 @@ const describeAddress = (address: string | undefined): string => address ?? 'uns
 const describeOwner = (owner: string): string => (owner === '' ? '(empty owner)' : owner);
 
 /**
- * Everything wrong with a set of claims; empty when none collide. ★ KEYS ON `port` ALONE, exactly
- *   like `lib-ports.nix`'s `assertNoCollision` — see the file header for why.
+ * Everything wrong with a set of claims; empty when none collide. ★ KEYS ON `port` ALONE — see the
+ *   file header for why.
  */
 export const portClaimProblems = (claims: readonly PortClaim[]): string[] => {
   const found: string[] = [];