@davidvornholt/standards 0.2.0 → 0.4.0

package/README.md

@@ -1,14 +1,20 @@
 # @davidvornholt/standards
 
-CLI for bootstrapping, synchronizing, and validating repositories that consume
-[davidvornholt/standards](https://github.com/davidvornholt/standards).
+CLI for bootstrapping, synchronizing, and validating repositories that consume [davidvornholt/standards](https://github.com/davidvornholt/standards).
 
 ```sh
 bunx @davidvornholt/standards init
 standards sync
 standards check
 standards doctor
+standards github --check
+standards github --apply
 ```
 
-See the standards repository README for the ownership model and adoption
-workflow.
+`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.
+
+## Configuration
+
+- **`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.
+
+See the standards repository README for the ownership model and adoption workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,12 @@
   "files": [
     "LICENSE",
     "README.md",
-    "src/cli.ts"
+    "src/cli.ts",
+    "src/github-api.ts",
+    "src/github-apply.ts",
+    "src/github-commands.ts",
+    "src/github-diff.ts",
+    "src/github-settings.ts"
   ],
   "scripts": {
     "lint": "biome check --error-on-warnings .",

package/src/cli.ts

@@ -32,6 +32,9 @@ import {
   sep,
 } from 'node:path';
 import process from 'node:process';
+import { CANONICAL_SETTINGS_FILE, LOCAL_SETTINGS_FILE } from './github-api';
+import { runGithubApply, runGithubCheck } from './github-commands';
+import { loadGithubSettings } from './github-settings';
 
 const { YAML: BunYaml } = await import('bun');
 
@@ -71,13 +74,14 @@ type Source = {
   readonly cleanup: () => void;
 };
 
-type Command = 'check' | 'doctor' | 'init' | 'sync';
+type Command = 'check' | 'doctor' | 'github' | 'help' | 'init' | 'sync';
 
 type CliOptions = {
-  readonly command: Command;
+  readonly command: Command | undefined;
   readonly consumer: string;
   readonly dryRun: boolean;
   readonly from: string | undefined;
+  readonly apply: boolean;
 };
 
 const sha256 = (buf: Buffer): string =>
@@ -457,7 +461,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
     );
     console.error(problems.join('\n'));
     console.error(
-      'These files are read-only. Restore them with `just sync-standards`, or move your change upstream.',
+      'These files are read-only. Restore them with `bun standards sync`, or move your change upstream.',
     );
     return false;
   }
@@ -706,6 +710,20 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
     problems.push(...inspectPackageJson(packageRaw));
   }
 
+  // The GitHub settings seam only exists once the canonical declaration has
+  // been synced in; before that there is nothing to extend.
+  const canonicalSettings = await readTextIfPresent(
+    join(consumer, CANONICAL_SETTINGS_FILE),
+  );
+  if (canonicalSettings !== null) {
+    const localSettings = await readTextIfPresent(
+      join(consumer, LOCAL_SETTINGS_FILE),
+    );
+    problems.push(
+      ...loadGithubSettings(canonicalSettings, localSettings).problems,
+    );
+  }
+
   if (problems.length > 0) {
     console.error(
       `standards doctor: ${problems.length} integration problem(s):`,
@@ -717,8 +735,32 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
   return true;
 };
 
+const USAGE = `Usage: standards <command> [options]
+
+Commands:
+  init    Bootstrap a consumer repo: seed repo-owned files, mirror canonical files, write the lock
+  sync    Mirror canonical files from upstream and rewrite the lock
+  check   Verify canonical files, extension seams, and GitHub settings
+  doctor  Validate extension seams only
+  github  Compare (--check) or converge (--apply) live GitHub settings
+  help    Show this help
+
+Options:
+  --dir <path>   Consumer directory to operate on (default: current directory)
+  --from <src>   Upstream override for init/sync (GitHub repo or local path)
+  --dry-run      Preview a sync without writing anything
+  --check        With github: compare live settings to the declaration (default)
+  --apply        With github: converge the live repository (needs admin auth)`;
+
 const commandFromArg = (arg: string): Command => {
-  if (arg === 'check' || arg === 'doctor' || arg === 'init' || arg === 'sync') {
+  if (
+    arg === 'check' ||
+    arg === 'doctor' ||
+    arg === 'github' ||
+    arg === 'help' ||
+    arg === 'init' ||
+    arg === 'sync'
+  ) {
     return arg;
   }
   throw new Error(
@@ -749,12 +791,17 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   let consumer = process.cwd();
   let dryRun = false;
   let from: string | undefined;
+  let checkFlag = false;
+  let apply = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     switch (arg) {
+      case '--apply':
+        apply = true;
+        break;
       case '--check':
-        command = setCommand(command, 'check');
+        checkFlag = true;
         break;
       case '--dir':
         consumer = nextOptionValue(argv, index);
@@ -767,26 +814,119 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
         from = nextOptionValue(argv, index);
         index += 1;
         break;
+      case '--help':
+      case '-h':
+        command = setCommand(command, 'help');
+        break;
       default:
         command = setCommand(command, commandFromArg(arg));
     }
   }
 
+  if (checkFlag && command !== 'github') {
+    throw new Error('--check is only valid with the github command');
+  }
+  if (apply && command !== 'github') {
+    throw new Error('--apply is only valid with the github command');
+  }
+  if (apply && checkFlag) {
+    throw new Error('github accepts exactly one of --check or --apply');
+  }
+
   return {
-    command: command ?? 'sync',
+    command,
     consumer: resolve(consumer),
     dryRun,
     from,
+    apply,
   };
 };
 
+const runCheckCommand = async (consumer: string): Promise<boolean> => {
+  const driftIsClean = await runCheck(consumer);
+  const integrationIsValid = await runDoctor(consumer);
+  // The GitHub gate activates with the synced declaration and then fails
+  // closed: once .github/settings.json exists, an unreachable API or an
+  // unreadable origin is a failure, not a skip.
+  const githubIsConverged = existsSync(join(consumer, CANONICAL_SETTINGS_FILE))
+    ? await runGithubCheck(consumer)
+    : true;
+  return driftIsClean && integrationIsValid && githubIsConverged;
+};
+
+const runInitCommand = async (
+  consumer: string,
+  from: string | undefined,
+): Promise<void> => {
+  // Refuse before cloning upstream: re-initializing skips the lock, so it
+  // would silently overwrite local canonical edits and orphan files that
+  // upstream deleted (they leave the lock and no future sync removes them).
+  if (existsSync(join(consumer, 'sync-standards.lock'))) {
+    console.error(
+      'standards: already initialized (sync-standards.lock exists). Use `bun standards sync` to update.',
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const source = resolveSource(from ?? DEFAULT_UPSTREAM);
+  try {
+    const manifest = await loadManifest(
+      join(source.dir, 'sync-standards.json'),
+    );
+    await runInit(manifest, source, consumer);
+  } finally {
+    source.cleanup();
+  }
+};
+
+const runSyncCommand = async (
+  consumer: string,
+  from: string | undefined,
+  dryRun: boolean,
+): Promise<void> => {
+  const consumerManifest = await loadManifest(
+    join(consumer, 'sync-standards.json'),
+  );
+  const source = resolveSource(from ?? consumerManifest.upstream);
+  try {
+    const manifest = await loadManifest(
+      join(source.dir, 'sync-standards.json'),
+    );
+    await runSync(manifest, source, consumer, dryRun);
+  } finally {
+    source.cleanup();
+  }
+};
+
 const main = async (): Promise<void> => {
-  const { command, consumer, dryRun, from } = parseArgs(process.argv.slice(2));
+  const { command, consumer, dryRun, from, apply } = parseArgs(
+    process.argv.slice(2),
+  );
+
+  if (command === undefined) {
+    console.error('standards: a command is required\n');
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (command === 'help') {
+    console.log(USAGE);
+    return;
+  }
 
   if (command === 'check') {
-    const driftIsClean = await runCheck(consumer);
-    const integrationIsValid = await runDoctor(consumer);
-    if (!(driftIsClean && integrationIsValid)) {
+    if (!(await runCheckCommand(consumer))) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (command === 'github') {
+    const converged = apply
+      ? await runGithubApply(consumer)
+      : await runGithubCheck(consumer);
+    if (!converged) {
       process.exitCode = 1;
     }
     return;
@@ -800,41 +940,12 @@ const main = async (): Promise<void> => {
   }
 
   if (command === 'init') {
-    // Refuse before cloning upstream: re-initializing skips the lock, so it
-    // would silently overwrite local canonical edits and orphan files that
-    // upstream deleted (they leave the lock and no future sync removes them).
-    if (existsSync(join(consumer, 'sync-standards.lock'))) {
-      console.error(
-        'standards: already initialized (sync-standards.lock exists). Use `just sync-standards` to update.',
-      );
-      process.exitCode = 1;
-      return;
-    }
-    const source = resolveSource(from ?? DEFAULT_UPSTREAM);
-    try {
-      const manifest = await loadManifest(
-        join(source.dir, 'sync-standards.json'),
-      );
-      await runInit(manifest, source, consumer);
-    } finally {
-      source.cleanup();
-    }
+    await runInitCommand(consumer, from);
     return;
   }
 
   if (command === 'sync') {
-    const consumerManifest = await loadManifest(
-      join(consumer, 'sync-standards.json'),
-    );
-    const source = resolveSource(from ?? consumerManifest.upstream);
-    try {
-      const manifest = await loadManifest(
-        join(source.dir, 'sync-standards.json'),
-      );
-      await runSync(manifest, source, consumer, dryRun);
-    } finally {
-      source.cleanup();
-    }
+    await runSyncCommand(consumer, from, dryRun);
   }
 };
 

package/src/github-api.ts

@@ -0,0 +1,144 @@
+// GitHub API plumbing for declarative repository settings: token and repo
+// resolution, a minimal fetch wrapper, and shared loaders. The check/apply
+// commands live in github-commands.ts.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import process from 'node:process';
+import {
+  isRecord,
+  type LoadedGithubSettings,
+  loadGithubSettings,
+} from './github-settings';
+
+const API_ROOT = 'https://api.github.com';
+
+const GITHUB_REMOTE_PATTERN =
+  /github\.com[/:](?<repo>[^/]+\/[^/]+?)(?:\.git)?$/u;
+
+export const HTTP_OK = 200;
+export const HTTP_CREATED = 201;
+export const HTTP_NO_CONTENT = 204;
+
+export const CANONICAL_SETTINGS_FILE = '.github/settings.json';
+export const LOCAL_SETTINGS_FILE = '.github/settings.local.json';
+
+const quietExec = (
+  file: string,
+  args: ReadonlyArray<string>,
+): string | null => {
+  try {
+    const out = execFileSync(file, [...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+};
+
+// GH_TOKEN or GITHUB_TOKEN, else the local gh CLI. Null is still usable for
+// reads on public repositories.
+export const resolveToken = (): string | null => {
+  const fromEnv = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
+  if (fromEnv !== undefined && fromEnv.length > 0) {
+    return fromEnv;
+  }
+  return quietExec('gh', ['auth', 'token']);
+};
+
+export const resolveGithubRepo = (consumer: string): string | null => {
+  const url = quietExec('git', ['-C', consumer, 'remote', 'get-url', 'origin']);
+  return url?.match(GITHUB_REMOTE_PATTERN)?.groups?.repo ?? null;
+};
+
+export type ApiResponse = { readonly status: number; readonly body: unknown };
+
+export const request = async (
+  token: string | null,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<ApiResponse> => {
+  const response = await fetch(`${API_ROOT}${path}`, {
+    method,
+    headers: {
+      accept: 'application/vnd.github+json',
+      'x-github-api-version': '2022-11-28',
+      ...(token === null ? {} : { authorization: `Bearer ${token}` }),
+      ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  let parsed: unknown = null;
+  try {
+    parsed = text.length === 0 ? null : (JSON.parse(text) as unknown);
+  } catch {
+    parsed = text;
+  }
+  return { status: response.status, body: parsed };
+};
+
+export const apiError = (context: string, response: ApiResponse): string => {
+  const message =
+    isRecord(response.body) && typeof response.body.message === 'string'
+      ? response.body.message
+      : 'unexpected response';
+  return `${context}: HTTP ${response.status} ${message}`;
+};
+
+export const loadDeclared = async (
+  consumer: string,
+): Promise<LoadedGithubSettings> => {
+  const canonicalPath = join(consumer, CANONICAL_SETTINGS_FILE);
+  if (!existsSync(canonicalPath)) {
+    return {
+      merged: null,
+      problems: [
+        `${CANONICAL_SETTINGS_FILE} not found; run \`bun standards sync\` first`,
+      ],
+    };
+  }
+  const localPath = join(consumer, LOCAL_SETTINGS_FILE);
+  return loadGithubSettings(
+    await readFile(canonicalPath, 'utf8'),
+    existsSync(localPath) ? await readFile(localPath, 'utf8') : null,
+  );
+};
+
+export type LiveRulesets = {
+  readonly rulesets: ReadonlyArray<Record<string, unknown>> | null;
+  readonly problem: string | null;
+};
+
+// Only repository-sourced rulesets are managed; org-level rulesets a consumer
+// inherits are outside this declaration's authority.
+export const fetchLiveRulesets = async (
+  token: string | null,
+  repo: string,
+): Promise<LiveRulesets> => {
+  const list = await request(token, 'GET', `/repos/${repo}/rulesets`);
+  if (list.status !== HTTP_OK || !Array.isArray(list.body)) {
+    return { rulesets: null, problem: apiError('listing rulesets', list) };
+  }
+  const repoOwned = list.body
+    .filter(isRecord)
+    .filter((ruleset) => ruleset.source_type === 'Repository');
+  const detailed = await Promise.all(
+    repoOwned.map((ruleset) =>
+      request(token, 'GET', `/repos/${repo}/rulesets/${ruleset.id}`),
+    ),
+  );
+  const failed = detailed.find((response) => response.status !== HTTP_OK);
+  if (failed !== undefined) {
+    return { rulesets: null, problem: apiError('reading a ruleset', failed) };
+  }
+  return {
+    rulesets: detailed.map((response) => response.body).filter(isRecord),
+    problem: null,
+  };
+};

package/src/github-apply.ts

@@ -0,0 +1,99 @@
+// Ruleset reconciliation for `standards github --apply`: create, update, and
+// delete live rulesets so they converge on exactly the declared set. Mutations
+// throw on the first API failure so a partial apply is reported, not hidden.
+
+import {
+  apiError,
+  fetchLiveRulesets,
+  HTTP_CREATED,
+  HTTP_NO_CONTENT,
+  HTTP_OK,
+  request,
+} from './github-api';
+import { diffRuleset } from './github-diff';
+import type { GithubSettings } from './github-settings';
+
+const reconcileRuleset = async (
+  token: string,
+  repo: string,
+  ruleset: Readonly<Record<string, unknown>>,
+  liveRuleset: Readonly<Record<string, unknown>> | undefined,
+): Promise<string | null> => {
+  const name = String(ruleset.name);
+  if (liveRuleset === undefined) {
+    const created = await request(
+      token,
+      'POST',
+      `/repos/${repo}/rulesets`,
+      ruleset,
+    );
+    if (created.status !== HTTP_CREATED) {
+      throw new Error(apiError(`creating ruleset "${name}"`, created));
+    }
+    return `created ruleset "${name}"`;
+  }
+  const diff = diffRuleset(ruleset, liveRuleset);
+  if (diff.drifted.length === 0 && diff.unverifiable.length === 0) {
+    return null;
+  }
+  const updated = await request(
+    token,
+    'PUT',
+    `/repos/${repo}/rulesets/${liveRuleset.id}`,
+    ruleset,
+  );
+  if (updated.status !== HTTP_OK) {
+    throw new Error(apiError(`updating ruleset "${name}"`, updated));
+  }
+  return `updated ruleset "${name}"`;
+};
+
+const deleteRuleset = async (
+  token: string,
+  repo: string,
+  name: string,
+  liveRuleset: Readonly<Record<string, unknown>>,
+): Promise<string> => {
+  const deleted = await request(
+    token,
+    'DELETE',
+    `/repos/${repo}/rulesets/${liveRuleset.id}`,
+  );
+  if (deleted.status !== HTTP_NO_CONTENT) {
+    throw new Error(apiError(`deleting ruleset "${name}"`, deleted));
+  }
+  return `deleted undeclared ruleset "${name}"`;
+};
+
+export const applyRulesets = async (
+  token: string,
+  repo: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  const live = await fetchLiveRulesets(token, repo);
+  if (live.rulesets === null) {
+    throw new Error(live.problem ?? 'unable to read rulesets');
+  }
+  const liveByName = new Map(live.rulesets.map((r) => [String(r.name), r]));
+  const declaredNames = new Set(declared.rulesets.map((r) => String(r.name)));
+  const actions: Array<string> = [];
+  for (const ruleset of declared.rulesets) {
+    // biome-ignore lint/performance/noAwaitInLoops: GitHub advises against concurrent write requests (secondary rate limits); mutations run sequentially on purpose.
+    const action = await reconcileRuleset(
+      token,
+      repo,
+      ruleset,
+      liveByName.get(String(ruleset.name)),
+    );
+    if (action !== null) {
+      actions.push(action);
+    }
+  }
+  for (const [name, liveRuleset] of liveByName) {
+    if (!declaredNames.has(name)) {
+      // biome-ignore lint/performance/noAwaitInLoops: GitHub advises against concurrent write requests (secondary rate limits); mutations run sequentially on purpose.
+      actions.push(await deleteRuleset(token, repo, name, liveRuleset));
+    }
+  }
+  return actions;
+};

package/src/github-commands.ts

@@ -0,0 +1,149 @@
+// `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.
+
+import {
+  apiError,
+  fetchLiveRulesets,
+  HTTP_OK,
+  loadDeclared,
+  request,
+  resolveGithubRepo,
+  resolveToken,
+} from './github-api';
+import { applyRulesets } from './github-apply';
+import { diffRepositorySettings, diffRulesets } from './github-diff';
+import { type GithubSettings, isRecord } from './github-settings';
+
+const reportProblems = (problems: ReadonlyArray<string>): void => {
+  console.error(
+    `standards github: ${problems.length} problem(s) with declared GitHub settings:`,
+  );
+  console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
+};
+
+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();
+  const problems: Array<string> = [];
+  try {
+    const repoResponse = await request(token, 'GET', `/repos/${repo}`);
+    if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
+      problems.push(apiError(`reading repository ${repo}`, repoResponse));
+    } else {
+      const diff = diffRepositorySettings(
+        declared.repository,
+        repoResponse.body,
+      );
+      problems.push(...diff.drifted);
+      if (diff.unverifiable.length > 0) {
+        console.log(
+          `standards github: repository setting(s) not visible to this token, verify with admin auth: ${diff.unverifiable.join(', ')}`,
+        );
+      }
+    }
+    const live = await fetchLiveRulesets(token, repo);
+    if (live.rulesets === null) {
+      problems.push(live.problem ?? 'unable to read rulesets');
+    } else {
+      const rulesetDiff = diffRulesets(declared.rulesets, live.rulesets);
+      problems.push(...rulesetDiff.drifted);
+      if (rulesetDiff.unverifiable.length > 0) {
+        console.log(
+          `standards github: ruleset field(s) not visible to this token, verify with admin auth: ${rulesetDiff.unverifiable.join('; ')}`,
+        );
+      }
+    }
+  } catch (error) {
+    problems.push(
+      `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return problems;
+};
+
+export const runGithubCheck = async (consumer: string): Promise<boolean> => {
+  const declared = await loadDeclared(consumer);
+  const problems = [...declared.problems];
+  if (declared.merged !== null) {
+    problems.push(...(await collectLiveDrift(consumer, declared.merged)));
+  }
+  if (problems.length > 0) {
+    reportProblems(problems);
+    console.error(
+      'Converge with `bun standards github --apply` (admin auth), or fix the declaration.',
+    );
+    return false;
+  }
+  console.log(
+    'standards github: live GitHub settings match the declared configuration',
+  );
+  return true;
+};
+
+export const runGithubApply = async (consumer: string): Promise<boolean> => {
+  const declared = await loadDeclared(consumer);
+  if (declared.merged === null || declared.problems.length > 0) {
+    reportProblems(declared.problems);
+    return false;
+  }
+  const repo = resolveGithubRepo(consumer);
+  if (repo === null) {
+    console.error(
+      'standards github: cannot determine the GitHub repository from the origin remote',
+    );
+    return false;
+  }
+  const token = resolveToken();
+  if (token === null) {
+    console.error(
+      'standards github: apply needs an admin token; authenticate the gh CLI or set GH_TOKEN',
+    );
+    return false;
+  }
+  try {
+    const actions: Array<string> = [];
+    const repoResponse = await request(token, 'GET', `/repos/${repo}`);
+    if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
+      throw new Error(apiError(`reading repository ${repo}`, repoResponse));
+    }
+    const diff = diffRepositorySettings(
+      declared.merged.repository,
+      repoResponse.body,
+    );
+    if (diff.drifted.length > 0 || diff.unverifiable.length > 0) {
+      const patched = await request(
+        token,
+        'PATCH',
+        `/repos/${repo}`,
+        declared.merged.repository,
+      );
+      if (patched.status !== HTTP_OK) {
+        throw new Error(apiError('updating repository settings', patched));
+      }
+      actions.push('updated repository merge settings');
+    }
+    actions.push(...(await applyRulesets(token, repo, declared.merged)));
+    for (const action of actions) {
+      console.log(`  ${action}`);
+    }
+    console.log(
+      actions.length === 0
+        ? 'standards github: already converged; no changes'
+        : `standards github: apply complete for ${repo}`,
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `standards github: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return false;
+  }
+};

package/src/github-diff.ts

@@ -0,0 +1,172 @@
+// Drift comparison between declared GitHub settings (github-settings.ts) and
+// the live state returned by the GitHub API. Pure logic; no network.
+
+import { isRecord } from './github-settings';
+
+export type SettingsDiff = {
+  readonly drifted: ReadonlyArray<string>;
+  readonly unverifiable: ReadonlyArray<string>;
+};
+
+// Declared values must match live ones; keys GitHub adds to live objects are
+// ignored so new API defaults do not read as drift. Arrays must have the same
+// length, with each declared element matching a distinct live element — so an
+// added bypass actor or required check is drift even when the declared list is
+// a subset of the live one.
+export const subsetMatches = (declared: unknown, live: unknown): boolean => {
+  if (Array.isArray(declared)) {
+    if (!Array.isArray(live) || declared.length !== live.length) {
+      return false;
+    }
+    const remaining = [...(live as ReadonlyArray<unknown>)];
+    return declared.every((value) => {
+      const index = remaining.findIndex((candidate) =>
+        subsetMatches(value, candidate),
+      );
+      if (index === -1) {
+        return false;
+      }
+      remaining.splice(index, 1);
+      return true;
+    });
+  }
+  if (isRecord(declared)) {
+    return (
+      isRecord(live) &&
+      Object.entries(declared).every(([key, value]) =>
+        subsetMatches(value, live[key]),
+      )
+    );
+  }
+  return declared === live;
+};
+
+const RULESET_COMPARED_KEYS = [
+  'target',
+  'enforcement',
+  'conditions',
+  'bypass_actors',
+] as const;
+
+const diffRules = (
+  name: string,
+  declared: Readonly<Record<string, unknown>>,
+  live: Readonly<Record<string, unknown>>,
+): ReadonlyArray<string> => {
+  const drifted: Array<string> = [];
+  const declaredRules = Array.isArray(declared.rules)
+    ? declared.rules.filter(isRecord)
+    : [];
+  const liveRules = Array.isArray(live.rules)
+    ? live.rules.filter(isRecord)
+    : [];
+  const liveByType = new Map(
+    liveRules.map((rule) => [String(rule.type), rule]),
+  );
+  const declaredTypes = new Set(declaredRules.map((rule) => String(rule.type)));
+  for (const rule of declaredRules) {
+    const type = String(rule.type);
+    const liveRule = liveByType.get(type);
+    const declaredWithoutType = Object.fromEntries(
+      Object.entries(rule).filter(([key]) => key !== 'type'),
+    );
+    if (liveRule === undefined) {
+      drifted.push(`ruleset "${name}": missing rule "${type}"`);
+    } else if (!subsetMatches(declaredWithoutType, liveRule)) {
+      drifted.push(
+        `ruleset "${name}": rule "${type}" differs from the declared configuration`,
+      );
+    }
+  }
+  for (const type of liveByType.keys()) {
+    if (!declaredTypes.has(type)) {
+      drifted.push(`ruleset "${name}": has undeclared extra rule "${type}"`);
+    }
+  }
+  return drifted;
+};
+
+// 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.
+export const diffRuleset = (
+  declared: Readonly<Record<string, unknown>>,
+  live: Readonly<Record<string, unknown>>,
+): SettingsDiff => {
+  const name = String(declared.name);
+  const drifted: Array<string> = [];
+  const unverifiable: Array<string> = [];
+  for (const key of RULESET_COMPARED_KEYS) {
+    if (declared[key] !== undefined) {
+      if (live[key] === undefined) {
+        unverifiable.push(`ruleset "${name}": ${key}`);
+      } else if (!subsetMatches(declared[key], live[key])) {
+        drifted.push(
+          `ruleset "${name}": ${key} differs from the declared configuration`,
+        );
+      }
+    }
+  }
+  drifted.push(...diffRules(name, declared, live));
+  return { drifted, unverifiable };
+};
+
+// Live rulesets must be exactly the declared set: additions, removals, and
+// in-place edits are all drift.
+export const diffRulesets = (
+  declared: ReadonlyArray<Readonly<Record<string, unknown>>>,
+  live: ReadonlyArray<Readonly<Record<string, unknown>>>,
+): SettingsDiff => {
+  const drifted: Array<string> = [];
+  const unverifiable: Array<string> = [];
+  const liveByName = new Map(
+    live.map((ruleset) => [String(ruleset.name), ruleset]),
+  );
+  const declaredNames = new Set(
+    declared.map((ruleset) => String(ruleset.name)),
+  );
+  for (const ruleset of declared) {
+    const liveRuleset = liveByName.get(String(ruleset.name));
+    if (liveRuleset === undefined) {
+      drifted.push(
+        `ruleset "${ruleset.name}" is declared but missing on GitHub`,
+      );
+    } else {
+      const diff = diffRuleset(ruleset, liveRuleset);
+      drifted.push(...diff.drifted);
+      unverifiable.push(...diff.unverifiable);
+    }
+  }
+  for (const name of liveByName.keys()) {
+    if (!declaredNames.has(name)) {
+      drifted.push(
+        `ruleset "${name}" exists on GitHub but is not declared; declare it in .github/settings.local.json or delete it`,
+      );
+    }
+  }
+  return { drifted, unverifiable };
+};
+
+// 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.
+export const diffRepositorySettings = (
+  declared: Readonly<Record<string, unknown>>,
+  live: Readonly<Record<string, unknown>>,
+): SettingsDiff => {
+  const drifted: Array<string> = [];
+  const unverifiable: Array<string> = [];
+  for (const [key, value] of Object.entries(declared)) {
+    if (live[key] === undefined) {
+      unverifiable.push(key);
+    } else if (!subsetMatches(value, live[key])) {
+      drifted.push(
+        `repository setting "${key}" is ${JSON.stringify(live[key])} on GitHub, declared ${JSON.stringify(value)}`,
+      );
+    }
+  }
+  return { drifted, unverifiable };
+};

package/src/github-settings.ts

@@ -0,0 +1,174 @@
+// Declarative GitHub repository settings: parsing and seam merging for the
+// canonical `.github/settings.json` and the repo-owned
+// `.github/settings.local.json` extension. Pure logic only; drift comparison
+// lives in github-diff.ts and the API interaction in github-api.ts. Like
+// cli.ts, this module is zero-dependency so `bunx` can execute the published
+// package.
+
+export type GithubSettings = {
+  readonly repository: Readonly<Record<string, unknown>>;
+  readonly rulesets: ReadonlyArray<Readonly<Record<string, unknown>>>;
+};
+
+export type LoadedGithubSettings = {
+  readonly merged: GithubSettings | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const SETTINGS_KEYS = new Set(['repository', 'rulesets']);
+
+type ParseResult = {
+  readonly settings: GithubSettings | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const rulesetListProblems = (
+  rulesets: ReadonlyArray<unknown>,
+  label: string,
+): ReadonlyArray<string> => {
+  const problems: Array<string> = [];
+  const names = new Set<string>();
+  for (const [index, ruleset] of rulesets.entries()) {
+    if (
+      !(
+        isRecord(ruleset) &&
+        typeof ruleset.name === 'string' &&
+        ruleset.name.length > 0
+      )
+    ) {
+      problems.push(
+        `${label} rulesets[${index}] must be an object with a non-empty "name"`,
+      );
+    } else if (names.has(ruleset.name)) {
+      problems.push(
+        `${label} declares ruleset "${ruleset.name}" more than once`,
+      );
+    } else {
+      names.add(ruleset.name);
+    }
+  }
+  return problems;
+};
+
+const parseSettings = (raw: unknown, label: string): ParseResult => {
+  if (!isRecord(raw)) {
+    return { settings: null, problems: [`${label} must be a JSON object`] };
+  }
+  const problems: Array<string> = [];
+  for (const key of Object.keys(raw)) {
+    if (!SETTINGS_KEYS.has(key)) {
+      problems.push(`${label} has unknown key "${key}"`);
+    }
+  }
+  const repository = raw.repository ?? {};
+  if (!isRecord(repository)) {
+    problems.push(`${label} "repository" must be an object`);
+  }
+  const rulesets = raw.rulesets ?? [];
+  if (Array.isArray(rulesets)) {
+    problems.push(...rulesetListProblems(rulesets, label));
+  } else {
+    problems.push(`${label} "rulesets" must be an array`);
+  }
+  if (problems.length > 0) {
+    return { settings: null, problems };
+  }
+  return {
+    settings: {
+      repository: repository as Record<string, unknown>,
+      rulesets: rulesets as ReadonlyArray<Record<string, unknown>>,
+    },
+    problems: [],
+  };
+};
+
+type MergeResult = {
+  readonly merged: GithubSettings | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+// The seam may only add. Overriding a canonical repository key or redefining a
+// canonical ruleset could weaken the canonical floor; GitHub layers multiple
+// rulesets strictest-wins, so adding a ruleset is always safe.
+const mergeSettings = (
+  canonical: GithubSettings,
+  local: GithubSettings,
+): MergeResult => {
+  const problems: Array<string> = [];
+  for (const key of Object.keys(local.repository)) {
+    if (key in canonical.repository) {
+      problems.push(
+        `.github/settings.local.json repository."${key}" would override a canonical value; canonical settings are read-only`,
+      );
+    }
+  }
+  const canonicalNames = new Set(canonical.rulesets.map((r) => r.name));
+  for (const ruleset of local.rulesets) {
+    if (canonicalNames.has(ruleset.name)) {
+      problems.push(
+        `.github/settings.local.json ruleset "${ruleset.name}" collides with a canonical ruleset; add a separately named ruleset to tighten further`,
+      );
+    }
+  }
+  if (problems.length > 0) {
+    return { merged: null, problems };
+  }
+  return {
+    merged: {
+      repository: { ...canonical.repository, ...local.repository },
+      rulesets: [...canonical.rulesets, ...local.rulesets],
+    },
+    problems: [],
+  };
+};
+
+type JsonParse = {
+  readonly value: unknown;
+  readonly problem: string | null;
+};
+
+const parseJson = (raw: string, label: string): JsonParse => {
+  try {
+    return { value: JSON.parse(raw) as unknown, problem: null };
+  } catch {
+    return { value: null, problem: `${label} must contain valid JSON` };
+  }
+};
+
+// Parse both files and merge them, gathering every problem before failing.
+export const loadGithubSettings = (
+  canonicalRaw: string,
+  localRaw: string | null,
+): LoadedGithubSettings => {
+  const problems: Array<string> = [];
+  const canonicalJson = parseJson(canonicalRaw, '.github/settings.json');
+  if (canonicalJson.problem !== null) {
+    problems.push(canonicalJson.problem);
+  }
+  if (localRaw === null) {
+    problems.push(
+      '.github/settings.local.json must exist; seed it with {"repository":{},"rulesets":[]}',
+    );
+  }
+  const localJson =
+    localRaw === null
+      ? null
+      : parseJson(localRaw, '.github/settings.local.json');
+  if (localJson !== null && localJson.problem !== null) {
+    problems.push(localJson.problem);
+  }
+  if (problems.length > 0) {
+    return { merged: null, problems };
+  }
+  const canonical = parseSettings(canonicalJson.value, '.github/settings.json');
+  const local = parseSettings(localJson?.value, '.github/settings.local.json');
+  problems.push(...canonical.problems, ...local.problems);
+  if (canonical.settings === null || local.settings === null) {
+    return { merged: null, problems };
+  }
+  const merged = mergeSettings(canonical.settings, local.settings);
+  return { merged: merged.merged, problems: [...problems, ...merged.problems] };
+};