@davidvornholt/standards 0.9.0 → 0.10.0

package/README.md

@@ -12,7 +12,7 @@ standards github --check
 standards github --apply
 ```
 
-`github --check` compares the live GitHub repository (merge settings and rulesets) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges the live repository to exactly the declared state. `check` runs the same comparison whenever `.github/settings.json` is present. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets, still converge repository merge settings, and print an unprotected-branch notice on every run.
+`github --check` compares the live GitHub repository (merge settings and rulesets) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges the live repository to exactly the declared state. `check` runs the same comparison whenever `.github/settings.json` is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. `--apply` re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.
 
 `structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. `check` includes `structure`, so these rules gate every consumer PR.
 
@@ -21,7 +21,7 @@ standards github --apply
 ## Configuration
 
 - **`sync-standards.local.json`** (optional) — consumer-owned sync policy at the repo root, validated by `doctor`/`check` and every `init`/`sync` even when an explicit ref or local source makes its `"ref"` irrelevant. All fields optional; a missing file means the defaults. `"ref"` is a non-empty single-line string that pins a tag, branch, or full commit sha to sync from instead of `main` (an explicit `--ref` overrides it; a local-path `--from` source is used as-is and ignores only the validated pin). `"autoSync": false` is read by the standards-sync workflow, not the CLI, and skips the weekly scheduled run. Version 0.7.0 removes the legacy `STANDARDS_AUTO_SYNC` and `STANDARDS_SYNC_REF` variable behavior; consumers must upgrade the package and lockfile before adopting a policy file.
-- **`.github/settings.local.json` `"rulesetEnforcement": "unavailable-on-plan"`** (optional) — declares that the repository's GitHub plan cannot enforce rulesets (private repositories on GitHub Free, both personal accounts and organizations). `github --check` and `--apply` then skip rulesets instead of comparing them, because a comparison cannot be trusted there: personal accounts answer ruleset reads with HTTP 403, and free-plan organizations report declared rulesets as active while silently not enforcing them. Repository merge settings are still checked and converged, and both commands print an unprotected-branch notice on every run. The only accepted value is `"unavailable-on-plan"` (enforcement is the default; omit the key on paid plans), and combining the opt-out with additional local rulesets is rejected. After upgrading the plan, remove the declaration and run `bun standards github --apply` to restore enforcement.
-- **`GH_TOKEN` / `GITHUB_TOKEN`** (optional) — GitHub API token for the `github` command and the GitHub portion of `check`. When neither is set, the token from the local `gh` CLI is used; with no token at all, reads still work on public repositories. `--apply` and private-repo reads need an authenticated token, and repo merge settings are only visible (and thus verifiable) to admin tokens — non-admin runs report them as unverifiable.
+- **`.github/settings.local.json` `"rulesetEnforcement": "unavailable-on-plan"`** (optional) — declares that the repository's GitHub plan cannot enforce rulesets (private repositories on GitHub Free, both personal accounts and organizations). `github --check` and `--apply` then skip rulesets instead of comparing them, because a comparison cannot be trusted there: personal accounts answer ruleset reads with HTTP 403, and free-plan organizations report declared rulesets as active while silently not enforcing them. Plan-gated repository settings that only function alongside branch protection (`allow_auto_merge`) are skipped for the same reason — GitHub accepts a PATCH for them with HTTP 200 and silently keeps the old value. The remaining repository merge settings are still checked and converged, and both commands print an unprotected-branch notice on every run. The only accepted value is `"unavailable-on-plan"` (enforcement is the default; omit the key on paid plans), and combining the opt-out with additional local rulesets is rejected. After upgrading the plan, remove the declaration and run `bun standards github --apply` to restore enforcement.
+- **`GH_TOKEN` / `GITHUB_TOKEN`** (optional) — GitHub API token for the `github` command and the GitHub portion of `check`. When neither is set, the token from the local `gh` CLI is used; with no token at all, reads still work on public repositories. `--apply` needs an admin token. GitHub's REST API reveals repo merge settings only to write-capable viewers — `check` retries REST-hidden keys over GraphQL, which serves them to read-only tokens — and ruleset `bypass_actors` requires repository Administration read; a token that still cannot see declared state fails the check rather than passing unverified. In CI, where the workflow token can never hold that permission, the canonical workflow decrypts `ci.github_settings_read_token` from the SOPS-encrypted `secrets/ci.yaml` — a fine-grained PAT with read-only "Administration" access to the repository.
 
 See the standards repository README for the ownership model and adoption workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,7 @@
     "src/github-command-shared.ts",
     "src/github-commands.ts",
     "src/github-diff.ts",
+    "src/github-live-drift.ts",
     "src/github-settings-parse.ts",
     "src/github-settings.ts",
     "src/structure-check.ts",

package/src/github-api.ts

@@ -111,6 +111,53 @@ export const loadDeclared = async (
   );
 };
 
+const GRAPHQL_MERGE_FIELDS: ReadonlyMap<string, string> = new Map([
+  ['allow_auto_merge', 'autoMergeAllowed'],
+  ['allow_merge_commit', 'mergeCommitAllowed'],
+  ['allow_rebase_merge', 'rebaseMergeAllowed'],
+  ['allow_squash_merge', 'squashMergeAllowed'],
+  ['delete_branch_on_merge', 'deleteBranchOnMerge'],
+  ['merge_commit_message', 'mergeCommitMessage'],
+  ['merge_commit_title', 'mergeCommitTitle'],
+  ['squash_merge_commit_message', 'squashMergeCommitMessage'],
+  ['squash_merge_commit_title', 'squashMergeCommitTitle'],
+]);
+
+// REST omits repository merge settings for read-only viewers (they surface
+// only with write access — community discussion #153258), but GraphQL serves
+// the same values, with identical enum spellings, to any token that can read
+// the repository. This keeps a read-only PAT sufficient for the check.
+// Returns only the keys GraphQL answered; the rest stay unverifiable.
+export const fetchMergeSettingsViaGraphql = async (
+  token: string | null,
+  repo: string,
+  keys: ReadonlyArray<string>,
+): Promise<Readonly<Record<string, unknown>>> => {
+  const mapped = keys.filter((key) => GRAPHQL_MERGE_FIELDS.has(key));
+  const [owner, name] = repo.split('/');
+  if (mapped.length === 0 || owner === undefined || name === undefined) {
+    return {};
+  }
+  const fields = mapped.map((key) => GRAPHQL_MERGE_FIELDS.get(key)).join(' ');
+  const response = await request(token, 'POST', '/graphql', {
+    query: `query { repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { ${fields} } }`,
+  });
+  if (response.status !== HTTP_OK || !isRecord(response.body)) {
+    return {};
+  }
+  const data = isRecord(response.body.data) ? response.body.data : null;
+  const repository =
+    data !== null && isRecord(data.repository) ? data.repository : null;
+  if (repository === null) {
+    return {};
+  }
+  return Object.fromEntries(
+    mapped
+      .map((key) => [key, repository[GRAPHQL_MERGE_FIELDS.get(key) ?? '']])
+      .filter(([, value]) => value !== undefined && value !== null),
+  );
+};
+
 export type LiveRulesets = {
   readonly rulesets: ReadonlyArray<Record<string, unknown>> | null;
   readonly problem: string | null;

package/src/github-apply.ts

@@ -11,8 +11,11 @@ import {
   request,
 } from './github-api';
 import { diffRepositorySettings, diffRuleset } from './github-diff';
-import type { GithubSettings } from './github-settings-parse';
+import { type GithubSettings, isRecord } from './github-settings-parse';
 
+// GitHub answers a PATCH containing a plan-unavailable setting with HTTP 200
+// and the old value, so the response body — the updated repository — is
+// diffed again instead of trusting the status code.
 export const applyRepositorySettings = async (
   token: string,
   repo: string,
@@ -24,9 +27,22 @@ export const applyRepositorySettings = async (
     return [];
   }
   const patched = await request(token, 'PATCH', `/repos/${repo}`, repository);
-  if (patched.status !== HTTP_OK) {
+  if (patched.status !== HTTP_OK || !isRecord(patched.body)) {
     throw new Error(apiError('updating repository settings', patched));
   }
+  const persisted = diffRepositorySettings(repository, patched.body);
+  const ignored = [
+    ...persisted.drifted,
+    ...persisted.unverifiable.map(
+      (key) =>
+        `repository setting "${key}" is missing from the update response`,
+    ),
+  ];
+  if (ignored.length > 0) {
+    throw new Error(
+      `GitHub returned HTTP 200 but ignored part of the update: ${ignored.join('; ')}. A silently ignored setting is usually unavailable on this GitHub plan; if this plan cannot protect branches, declare the ruleset-enforcement opt-out instead`,
+    );
+  }
   return ['updated repository merge settings'];
 };
 
@@ -37,8 +53,8 @@ export const applySummary = (
 ): string => {
   if (rulesetsSkipped) {
     return actions.length === 0
-      ? `standards github: repository settings already converged for ${repo}; rulesets skipped`
-      : `standards github: repository settings apply complete for ${repo}; rulesets skipped`;
+      ? `standards github: enforceable settings already converged for ${repo}; plan-gated settings skipped`
+      : `standards github: enforceable settings apply complete for ${repo}; plan-gated settings skipped`;
   }
   return actions.length === 0
     ? 'standards github: already converged; no changes'

package/src/github-command-shared.ts

@@ -1,11 +1,45 @@
-import type { GithubSettings } from './github-settings-parse';
+import {
+  ENFORCEMENT_OPT_OUT,
+  type GithubSettings,
+} from './github-settings-parse';
+
+// Repository settings that only function alongside branch protection, which
+// the ruleset-enforcement opt-out declares unavailable on the plan. GitHub
+// answers a PATCH for them with HTTP 200 and silently keeps the old value, so
+// they must be skipped, never applied-and-trusted.
+export const PLAN_GATED_REPOSITORY_KEYS: ReadonlySet<string> = new Set([
+  'allow_auto_merge',
+]);
+
+export const enforceableRepositorySettings = (
+  declared: GithubSettings,
+): Readonly<Record<string, unknown>> =>
+  declared.rulesetEnforcement === ENFORCEMENT_OPT_OUT
+    ? Object.fromEntries(
+        Object.entries(declared.repository).filter(
+          ([key]) => !PLAN_GATED_REPOSITORY_KEYS.has(key),
+        ),
+      )
+    : declared.repository;
 
 export const optOutEligibilityProblem = (
   repo: string,
   declared: GithubSettings,
   liveRepository: Readonly<Record<string, unknown>>,
 ): string | null =>
-  declared.rulesetEnforcement === 'unavailable-on-plan' &&
+  declared.rulesetEnforcement === ENFORCEMENT_OPT_OUT &&
   liveRepository.private !== true
     ? `.github/settings.local.json "rulesetEnforcement" may only be declared for a private repository; ${repo} is public`
     : null;
+
+// Declared state the token cannot see is a gate failure, not a pass with a
+// log line: a gate that cannot perform its comparison fails closed.
+export const unverifiableProblem = (
+  scope: string,
+  items: ReadonlyArray<string>,
+): ReadonlyArray<string> =>
+  items.length === 0
+    ? []
+    : [
+        `${scope} not visible to this token, so the gate cannot verify: ${items.join('; ')}. Use a token with read access to repository administration (in CI: ci.github_settings_read_token in secrets/ci.yaml), or verify locally with admin auth`,
+      ];

package/src/github-commands.ts

@@ -1,11 +1,10 @@
 // `standards github --check` verifies the live GitHub repository against the
-// declared settings and fails closed on any drift or API error. `standards
-// github --apply` converges the live repository; it needs an admin token, so
-// it runs locally rather than in CI.
+// declared settings and fails closed on any drift, API error, or declared
+// state the token cannot see. `standards github --apply` converges the live
+// repository; it needs an admin token, so it runs locally rather than in CI.
 
 import {
   apiError,
-  fetchLiveRulesets,
   HTTP_OK,
   loadDeclared,
   request,
@@ -17,14 +16,17 @@ import {
   applyRulesets,
   applySummary,
 } from './github-apply';
-import { optOutEligibilityProblem } from './github-command-shared';
-import { diffRepositorySettings, diffRulesets } from './github-diff';
-import { type GithubSettings, isRecord } from './github-settings-parse';
+import {
+  enforceableRepositorySettings,
+  optOutEligibilityProblem,
+} from './github-command-shared';
+import { collectLiveDrift } from './github-live-drift';
+import { isRecord } from './github-settings-parse';
 
 // Printed on every check and apply while the opt-out is declared: the skip
 // must stay louder than the comfort of a green gate.
 const UNENFORCEABLE_NOTICE =
-  'standards github: rulesets are declared unenforceable on this GitHub plan (.github/settings.local.json "rulesetEnforcement"); the default branch is NOT protected. After upgrading the plan, remove the declaration, then run `bun standards github --apply`.';
+  'standards github: rulesets are declared unenforceable on this GitHub plan (.github/settings.local.json "rulesetEnforcement"); the default branch is NOT protected, and plan-gated repository settings ("allow_auto_merge") are skipped. After upgrading the plan, remove the declaration, then run `bun standards github --apply`.';
 
 const reportProblems = (problems: ReadonlyArray<string>): void => {
   console.error(
@@ -33,74 +35,6 @@ const reportProblems = (problems: ReadonlyArray<string>): void => {
   console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
 };
 
-const repositoryDrift = async (
-  token: string | null,
-  repo: string,
-  declared: GithubSettings,
-): Promise<ReadonlyArray<string>> => {
-  const repoResponse = await request(token, 'GET', `/repos/${repo}`);
-  if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
-    return [apiError(`reading repository ${repo}`, repoResponse)];
-  }
-  const eligibilityProblem = optOutEligibilityProblem(
-    repo,
-    declared,
-    repoResponse.body,
-  );
-  if (eligibilityProblem !== null) {
-    return [eligibilityProblem];
-  }
-  const diff = diffRepositorySettings(declared.repository, repoResponse.body);
-  if (diff.unverifiable.length > 0) {
-    console.log(
-      `standards github: repository setting(s) not visible to this token, verify with admin auth: ${diff.unverifiable.join(', ')}`,
-    );
-  }
-  return diff.drifted;
-};
-
-const rulesetDrift = async (
-  token: string | null,
-  repo: string,
-  declared: GithubSettings,
-): Promise<ReadonlyArray<string>> => {
-  if (declared.rulesetEnforcement === 'unavailable-on-plan') {
-    return [];
-  }
-  const live = await fetchLiveRulesets(token, repo);
-  if (live.rulesets === null) {
-    return [live.problem ?? 'unable to read rulesets'];
-  }
-  const diff = diffRulesets(declared.rulesets, live.rulesets);
-  if (diff.unverifiable.length > 0) {
-    console.log(
-      `standards github: ruleset field(s) not visible to this token, verify with admin auth: ${diff.unverifiable.join('; ')}`,
-    );
-  }
-  return diff.drifted;
-};
-
-const collectLiveDrift = async (
-  consumer: string,
-  declared: GithubSettings,
-): Promise<ReadonlyArray<string>> => {
-  const repo = resolveGithubRepo(consumer);
-  if (repo === null) {
-    return ['cannot determine the GitHub repository from the origin remote'];
-  }
-  const token = resolveToken();
-  try {
-    return [
-      ...(await repositoryDrift(token, repo, declared)),
-      ...(await rulesetDrift(token, repo, declared)),
-    ];
-  } catch (error) {
-    return [
-      `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
-    ];
-  }
-};
-
 export const runGithubCheck = async (consumer: string): Promise<boolean> => {
   const declared = await loadDeclared(consumer);
   if (declared.merged?.rulesetEnforcement === 'unavailable-on-plan') {
@@ -119,7 +53,7 @@ export const runGithubCheck = async (consumer: string): Promise<boolean> => {
   }
   console.log(
     declared.merged?.rulesetEnforcement === 'unavailable-on-plan'
-      ? 'standards github: live repository settings match the declared configuration (rulesets skipped)'
+      ? 'standards github: live repository settings match the declared configuration (plan-gated settings skipped)'
       : 'standards github: live GitHub settings match the declared configuration',
   );
   return true;
@@ -165,7 +99,7 @@ export const runGithubApply = async (consumer: string): Promise<boolean> => {
       ...(await applyRepositorySettings(
         token,
         repo,
-        declared.merged.repository,
+        enforceableRepositorySettings(declared.merged),
         repoResponse.body,
       )),
     ];

package/src/github-diff.ts

@@ -89,8 +89,8 @@ const diffRules = (
 // Some ruleset fields — bypass_actors in particular — are only included in
 // API responses for admin viewers. A declared key that is absent on the live
 // side is unverifiable for this token, not drift: the same policy as
-// repository merge settings, so a non-admin CI token does not fail the gate
-// on state it cannot see.
+// repository merge settings, so callers can fail with a targeted
+// missing-visibility message instead of a bogus value mismatch.
 export const diffRuleset = (
   declared: Readonly<Record<string, unknown>>,
   live: Readonly<Record<string, unknown>>,
@@ -150,9 +150,9 @@ export const diffRulesets = (
 };
 
 // Repo merge settings are only visible to admin tokens; report invisible keys
-// as unverifiable instead of drifted so a non-admin CI token does not fail the
-// gate, while still surfacing that only a local admin check gives full
-// coverage.
+// as unverifiable instead of drifted so callers fail the gate with a
+// missing-visibility message that names the token fix, not a bogus value
+// mismatch.
 export const diffRepositorySettings = (
   declared: Readonly<Record<string, unknown>>,
   live: Readonly<Record<string, unknown>>,

package/src/github-live-drift.ts

@@ -0,0 +1,99 @@
+// Drift collection for `standards github --check`: compares the live GitHub
+// repository against the merged declaration and fails closed on state the
+// token cannot see. Command wiring lives in github-commands.ts.
+
+import {
+  apiError,
+  fetchLiveRulesets,
+  fetchMergeSettingsViaGraphql,
+  HTTP_OK,
+  request,
+  resolveGithubRepo,
+  resolveToken,
+} from './github-api';
+import {
+  enforceableRepositorySettings,
+  optOutEligibilityProblem,
+  unverifiableProblem,
+} from './github-command-shared';
+import { diffRepositorySettings, diffRulesets } from './github-diff';
+import { type GithubSettings, isRecord } from './github-settings-parse';
+
+const repositoryDrift = async (
+  token: string | null,
+  repo: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  const repoResponse = await request(token, 'GET', `/repos/${repo}`);
+  if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
+    return [apiError(`reading repository ${repo}`, repoResponse)];
+  }
+  const eligibilityProblem = optOutEligibilityProblem(
+    repo,
+    declared,
+    repoResponse.body,
+  );
+  if (eligibilityProblem !== null) {
+    return [eligibilityProblem];
+  }
+  const declaredRepository = enforceableRepositorySettings(declared);
+  const diff = diffRepositorySettings(declaredRepository, repoResponse.body);
+  if (diff.unverifiable.length === 0) {
+    return diff.drifted;
+  }
+  // REST hides merge settings from read-only tokens; retry the invisible
+  // keys over GraphQL before failing the gate.
+  const fallback = await fetchMergeSettingsViaGraphql(
+    token,
+    repo,
+    diff.unverifiable,
+  );
+  const rediff = diffRepositorySettings(declaredRepository, {
+    ...repoResponse.body,
+    ...fallback,
+  });
+  return [
+    ...rediff.drifted,
+    ...unverifiableProblem('repository setting(s)', rediff.unverifiable),
+  ];
+};
+
+const rulesetDrift = async (
+  token: string | null,
+  repo: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  if (declared.rulesetEnforcement === 'unavailable-on-plan') {
+    return [];
+  }
+  const live = await fetchLiveRulesets(token, repo);
+  if (live.rulesets === null) {
+    return [live.problem ?? 'unable to read rulesets'];
+  }
+  const diff = diffRulesets(declared.rulesets, live.rulesets);
+  return [
+    ...diff.drifted,
+    ...unverifiableProblem('ruleset field(s)', diff.unverifiable),
+  ];
+};
+
+export const collectLiveDrift = async (
+  consumer: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  const repo = resolveGithubRepo(consumer);
+  if (repo === null) {
+    return ['cannot determine the GitHub repository from the origin remote'];
+  }
+  const token = resolveToken();
+  try {
+    return [
+      ...(await repositoryDrift(token, repo, declared)),
+      ...(await rulesetDrift(token, repo, declared)),
+    ];
+  } catch (error) {
+    return [
+      `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
+    ];
+  }
+};