mandrel-platform 0.17.2 → 0.18.0

package/scripts/check-repo-settings.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * check-repo-settings.mjs
+ *
+ * GitHub-side repo-settings drift dashboard (Story #171).
+ *
+ * The 2026-07-01 settings-level audit (repo-ops consumers matrix §3a, roadmap
+ * §2.1) found real divergence in GitHub repo settings the platform shipped no
+ * contract for: default Actions workflow token permissions, merge-method
+ * allow-list, squash-commit source, auto-merge, and whether Actions can
+ * approve pull requests. `config/repo-settings.schema.json` /
+ * `docs/runbooks/repo-settings.json` encode the decided fleet baseline; this
+ * script reads each consumer's LIVE settings over the GitHub API
+ * (`gh api repos/{owner}/{repo}`) and reports drift against that baseline.
+ *
+ * Mirrors the shape of `check-pin-drift.mjs`: data-driven consumer registry
+ * (reuses `scripts/pin-drift-consumers.json` — same fleet, no second registry
+ * to keep in sync), an injectable `runGh` seam for offline testing, pure
+ * exported classifier functions, `--json` / `--strict` flags, and
+ * `GITHUB_STEP_SUMMARY` integration.
+ *
+ * Non-blocking by design (standing decision #10 — drift is repaired via
+ * auto-repair PRs / a dashboard, never a hard gate): the default exit code is
+ * 0 even when drift is found. `--strict` is an explicit opt-in for a one-off
+ * enforcement run; the scheduled dashboard invocation never passes it.
+ *
+ * Usage:
+ *   node scripts/check-repo-settings.mjs
+ *   node scripts/check-repo-settings.mjs --config scripts/pin-drift-consumers.json
+ *   node scripts/check-repo-settings.mjs --baseline docs/runbooks/repo-settings.json
+ *   node scripts/check-repo-settings.mjs --json      # machine-readable envelope
+ *   node scripts/check-repo-settings.mjs --strict     # exit 1 on any drift
+ *
+ * Exit codes:
+ *   0 — report emitted. Without --strict this is the default even when drift
+ *       is present (report, don't block).
+ *   1 — with --strict: at least one consumer drifts from the baseline.
+ *       Without --strict: only on a fatal error (bad config, gh failure).
+ */
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string[]} argv
+ * @returns {{ config: string, baseline: string, json: boolean, strict: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let config = "scripts/pin-drift-consumers.json";
+  let baseline = "docs/runbooks/repo-settings.json";
+  let json = false;
+  let strict = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--config") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        config = next;
+        i += 1;
+      }
+    } else if (a === "--baseline") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        baseline = next;
+        i += 1;
+      }
+    } else if (a === "--json") {
+      json = true;
+    } else if (a === "--strict") {
+      strict = true;
+    }
+  }
+  return { config, baseline, json, strict };
+}
+
+// ---------------------------------------------------------------------------
+// Baseline dimensions
+// ---------------------------------------------------------------------------
+
+/**
+ * The baseline keys this checker understands, mapped to how to read the
+ * equivalent field off `gh api repos/{owner}/{repo}` (repo settings) or
+ * `gh api repos/{owner}/{repo}/actions/permissions/workflow` (Actions
+ * workflow-permissions, a separate endpoint GitHub does not fold into the
+ * main repo payload).
+ */
+const REPO_FIELDS = [
+  "allowSquashMerge",
+  "allowMergeCommit",
+  "allowRebaseMerge",
+  "squashMergeCommitTitle",
+  "squashMergeCommitMessage",
+  "deleteBranchOnMerge",
+  "allowAutoMerge",
+];
+const ACTIONS_FIELDS = ["actionsDefaultWorkflowPermissions", "actionsCanApprovePullRequestReviews"];
+
+const REPO_FIELD_TO_API_KEY = {
+  allowSquashMerge: "allow_squash_merge",
+  allowMergeCommit: "allow_merge_commit",
+  allowRebaseMerge: "allow_rebase_merge",
+  squashMergeCommitTitle: "squash_merge_commit_title",
+  squashMergeCommitMessage: "squash_merge_commit_message",
+  deleteBranchOnMerge: "delete_branch_on_merge",
+  allowAutoMerge: "allow_auto_merge",
+};
+
+const ACTIONS_FIELD_TO_API_KEY = {
+  actionsDefaultWorkflowPermissions: "default_workflow_permissions",
+  actionsCanApprovePullRequestReviews: "can_approve_pull_request_reviews",
+};
+
+/**
+ * Map a live `gh api repos/{owner}/{repo}` payload to the baseline's field
+ * shape (camelCase, only the dimensions this contract governs).
+ *
+ * @param {Record<string, unknown>} repoPayload
+ * @returns {Record<string, unknown>}
+ */
+export function mapRepoSettings(repoPayload) {
+  const out = {};
+  for (const field of REPO_FIELDS) {
+    out[field] = repoPayload[REPO_FIELD_TO_API_KEY[field]];
+  }
+  return out;
+}
+
+/**
+ * Map a live `gh api repos/{owner}/{repo}/actions/permissions/workflow`
+ * payload to the baseline's field shape.
+ *
+ * @param {Record<string, unknown>} actionsPayload
+ * @returns {Record<string, unknown>}
+ */
+export function mapActionsSettings(actionsPayload) {
+  const out = {};
+  for (const field of ACTIONS_FIELDS) {
+    out[field] = actionsPayload[ACTIONS_FIELD_TO_API_KEY[field]];
+  }
+  return out;
+}
+
+/**
+ * Diff a consumer's live settings against the baseline for every dimension
+ * the baseline declares (unknown/extra baseline keys are ignored so the
+ * schema can grow without breaking this classifier).
+ *
+ * @param {Record<string, unknown>} live
+ * @param {Record<string, unknown>} baseline
+ * @returns {{ drifted: boolean, mismatches: Array<{ field: string, expected: unknown, actual: unknown }> }}
+ */
+export function diffSettings(live, baseline) {
+  const mismatches = [];
+  for (const field of [...REPO_FIELDS, ...ACTIONS_FIELDS]) {
+    if (!(field in baseline)) continue;
+    const expected = baseline[field];
+    const actual = live[field];
+    if (actual !== expected) {
+      mismatches.push({ field, expected, actual });
+    }
+  }
+  return { drifted: mismatches.length > 0, mismatches };
+}
+
+// ---------------------------------------------------------------------------
+// GitHub access
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `gh api <path>` and parse the JSON response.
+ *
+ * @param {string} apiPath
+ * @param {(args: string[]) => string} runGh
+ * @returns {unknown}
+ */
+function ghApiJson(apiPath, runGh) {
+  const raw = runGh(["api", apiPath, "-H", "Accept: application/vnd.github+json"]);
+  return JSON.parse(raw);
+}
+
+/**
+ * Default gh runner — shells out to the `gh` CLI. Same shape as
+ * check-pin-drift.mjs's defaultGhRunner so both scripts share test doubles.
+ *
+ * @param {string[]} args
+ * @returns {string}
+ */
+export function defaultGhRunner(args) {
+  return execFileSync("gh", args, {
+    encoding: "utf-8",
+    maxBuffer: 32 * 1024 * 1024,
+  });
+}
+
+/**
+ * Fetch one consumer's live settings across both endpoints and map them to
+ * the baseline's field shape.
+ *
+ * @param {string} repo  "owner/repo".
+ * @param {(args: string[]) => string} runGh
+ * @returns {Record<string, unknown>}
+ */
+export function fetchConsumerSettings(repo, runGh) {
+  const repoPayload = ghApiJson(`repos/${repo}`, runGh);
+  const actionsPayload = ghApiJson(`repos/${repo}/actions/permissions/workflow`, runGh);
+  return { ...mapRepoSettings(repoPayload), ...mapActionsSettings(actionsPayload) };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full drift report for the configured consumers against the
+ * given baseline.
+ *
+ * @param {{ consumers: Array<{ name: string, repo: string, branch?: string }> }} config
+ * @param {Record<string, unknown>} baseline
+ * @param {(args: string[]) => string} runGh
+ * @returns {{ baseline: Record<string, unknown>, consumers: Array<object> }}
+ */
+export function buildReport(config, baseline, runGh) {
+  const consumers = config.consumers.map((consumer) => {
+    try {
+      const live = fetchConsumerSettings(consumer.repo, runGh);
+      const { drifted, mismatches } = diffSettings(live, baseline);
+      return { name: consumer.name, repo: consumer.repo, status: drifted ? "drift" : "current", live, mismatches };
+    } catch (err) {
+      return {
+        name: consumer.name,
+        repo: consumer.repo,
+        status: "error",
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  });
+  return { baseline, consumers };
+}
+
+/**
+ * @param {ReturnType<typeof buildReport>} report
+ * @returns {boolean}
+ */
+export function hasDrift(report) {
+  return report.consumers.some((c) => c.status === "drift");
+}
+
+/**
+ * @param {ReturnType<typeof buildReport>} report
+ * @returns {string}
+ */
+export function renderReport(report) {
+  const lines = [];
+  lines.push("## Repo-Settings Baseline Dashboard");
+  lines.push("");
+  lines.push(
+    "Non-blocking by design (standing decision #10) — drift is reported here, never a hard gate on a consumer's `main`.",
+  );
+  lines.push("");
+  lines.push("| Consumer | Status | Detail |");
+  lines.push("| -------- | ------ | ------ |");
+  for (const c of report.consumers) {
+    if (c.status === "current") {
+      lines.push(`| ${c.name} | ✅ current | matches baseline |`);
+    } else if (c.status === "error") {
+      lines.push(`| ${c.name} | ⚠️ error | ${c.error} |`);
+    } else {
+      const detail = c.mismatches
+        .map((m) => `${m.field}: expected \`${m.expected}\`, got \`${m.actual}\``)
+        .join("; ");
+      lines.push(`| ${c.name} | ❌ drift | ${detail} |`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   runGh?: (args: string[]) => string,
+ *   summaryPath?: string | undefined,
+ * }} [opts]
+ * @returns {number} exit code
+ */
+export function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runGh = defaultGhRunner,
+  summaryPath = process.env.GITHUB_STEP_SUMMARY,
+} = {}) {
+  const { config: configRel, baseline: baselineRel, json, strict } = parseArgv(argv);
+  const configPath = resolve(cwd, configRel);
+  const baselinePath = resolve(cwd, baselineRel);
+
+  let config;
+  let baseline;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    stderr.write(
+      `[repo-settings] ❌ failed to read config ${configPath}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+  try {
+    baseline = JSON.parse(readFileSync(baselinePath, "utf-8"));
+  } catch (err) {
+    stderr.write(
+      `[repo-settings] ❌ failed to read baseline ${baselinePath}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+  if (!Array.isArray(config.consumers)) {
+    stderr.write(`[repo-settings] ❌ config must define { consumers: [] }\n`);
+    return 1;
+  }
+
+  const report = buildReport(config, baseline, runGh);
+  const drift = hasDrift(report);
+
+  if (json) {
+    stdout.write(`${JSON.stringify({ kind: "repo-settings-report", drift, ...report }, null, 2)}\n`);
+  } else {
+    const text = renderReport(report);
+    stdout.write(`${text}\n`);
+    if (summaryPath) {
+      try {
+        appendFileSync(summaryPath, `${text}\n`);
+      } catch (err) {
+        stderr.write(
+          `[repo-settings] ⚠ could not write job summary: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+      }
+    }
+  }
+
+  if (strict && drift) {
+    stderr.write(`[repo-settings] ❌ drift detected (--strict)\n`);
+    return 1;
+  }
+  return 0;
+}
+
+// Direct-invocation guard (matches the repo's other scripts/*.mjs entry style).
+const invokedDirectly =
+  process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
+if (invokedDirectly) {
+  process.exit(runCli());
+}

package/scripts/check-repo-settings.test.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+/**
+ * check-repo-settings.test.mjs — node:test suite for the Story #171
+ * repo-settings drift dashboard.
+ *
+ * Exercises the pure classifiers (mapRepoSettings/mapActionsSettings,
+ * diffSettings) directly, and the full buildReport/runCli pipeline with an
+ * injected `runGh` seam (offline — no real GitHub calls).
+ *
+ * Run: node scripts/check-repo-settings.test.mjs   (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, test } from "node:test";
+import {
+  mapRepoSettings,
+  mapActionsSettings,
+  diffSettings,
+  buildReport,
+  hasDrift,
+  renderReport,
+  runCli,
+  parseArgv,
+} from "./check-repo-settings.mjs";
+
+const BASELINE = {
+  allowSquashMerge: true,
+  allowMergeCommit: false,
+  allowRebaseMerge: false,
+  squashMergeCommitTitle: "PR_TITLE",
+  squashMergeCommitMessage: "PR_BODY",
+  deleteBranchOnMerge: true,
+  allowAutoMerge: true,
+  actionsDefaultWorkflowPermissions: "read",
+  actionsCanApprovePullRequestReviews: false,
+};
+
+test("mapRepoSettings maps GitHub's snake_case repo payload to camelCase baseline fields", () => {
+  const payload = {
+    allow_squash_merge: true,
+    allow_merge_commit: false,
+    allow_rebase_merge: false,
+    squash_merge_commit_title: "PR_TITLE",
+    squash_merge_commit_message: "PR_BODY",
+    delete_branch_on_merge: true,
+    allow_auto_merge: true,
+    // extra fields the repo payload carries that the schema does not govern
+    full_name: "owner/repo",
+  };
+  const mapped = mapRepoSettings(payload);
+  assert.deepEqual(mapped, {
+    allowSquashMerge: true,
+    allowMergeCommit: false,
+    allowRebaseMerge: false,
+    squashMergeCommitTitle: "PR_TITLE",
+    squashMergeCommitMessage: "PR_BODY",
+    deleteBranchOnMerge: true,
+    allowAutoMerge: true,
+  });
+});
+
+test("mapActionsSettings maps the Actions workflow-permissions payload", () => {
+  const payload = { default_workflow_permissions: "write", can_approve_pull_request_reviews: true };
+  assert.deepEqual(mapActionsSettings(payload), {
+    actionsDefaultWorkflowPermissions: "write",
+    actionsCanApprovePullRequestReviews: true,
+  });
+});
+
+test("diffSettings reports no mismatches when live matches baseline", () => {
+  const { drifted, mismatches } = diffSettings({ ...BASELINE }, BASELINE);
+  assert.equal(drifted, false);
+  assert.deepEqual(mismatches, []);
+});
+
+test("diffSettings flags every drifted field (domio-shaped: write token perms)", () => {
+  const live = { ...BASELINE, actionsDefaultWorkflowPermissions: "write" };
+  const { drifted, mismatches } = diffSettings(live, BASELINE);
+  assert.equal(drifted, true);
+  assert.deepEqual(mismatches, [
+    { field: "actionsDefaultWorkflowPermissions", expected: "read", actual: "write" },
+  ]);
+});
+
+test("diffSettings flags multiple mismatches (athportal-shaped: merge methods + squash source)", () => {
+  const live = {
+    ...BASELINE,
+    allowMergeCommit: true,
+    allowRebaseMerge: true,
+    squashMergeCommitMessage: "COMMIT_MESSAGES",
+  };
+  const { mismatches } = diffSettings(live, BASELINE);
+  const fields = mismatches.map((m) => m.field).sort();
+  assert.deepEqual(fields, ["allowMergeCommit", "allowRebaseMerge", "squashMergeCommitMessage"]);
+});
+
+test("diffSettings ignores baseline keys that are not in the field list (schema _note, $schema)", () => {
+  const baselineWithExtras = { ...BASELINE, $schema: "../../config/repo-settings.schema.json", _note: "..." };
+  const { drifted } = diffSettings({ ...BASELINE }, baselineWithExtras);
+  assert.equal(drifted, false);
+});
+
+function fakeRunGh(responses) {
+  return (args) => {
+    const path = args[1]; // ["api", "<path>", ...]
+    if (!(path in responses)) {
+      throw new Error(`fakeRunGh: no stub for ${path}`);
+    }
+    return JSON.stringify(responses[path]);
+  };
+}
+
+test("buildReport: consumer matching the baseline reports 'current'", () => {
+  const config = { consumers: [{ name: "domio", repo: "dsj1984/domio" }] };
+  const runGh = fakeRunGh({
+    "repos/dsj1984/domio": {
+      allow_squash_merge: true,
+      allow_merge_commit: false,
+      allow_rebase_merge: false,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/dsj1984/domio/actions/permissions/workflow": {
+      default_workflow_permissions: "write",
+      can_approve_pull_request_reviews: false,
+    },
+  });
+  const report = buildReport(config, BASELINE, runGh);
+  assert.equal(report.consumers[0].status, "drift");
+  assert.deepEqual(report.consumers[0].mismatches, [
+    { field: "actionsDefaultWorkflowPermissions", expected: "read", actual: "write" },
+  ]);
+  assert.equal(hasDrift(report), true);
+});
+
+test("buildReport: consumer fully matching baseline reports 'current' and no drift", () => {
+  const config = { consumers: [{ name: "swarm-os", repo: "Beestera/swarm-os" }] };
+  const runGh = fakeRunGh({
+    "repos/Beestera/swarm-os": {
+      allow_squash_merge: true,
+      allow_merge_commit: false,
+      allow_rebase_merge: false,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/Beestera/swarm-os/actions/permissions/workflow": {
+      default_workflow_permissions: "read",
+      can_approve_pull_request_reviews: false,
+    },
+  });
+  const report = buildReport(config, BASELINE, runGh);
+  assert.equal(report.consumers[0].status, "current");
+  assert.equal(hasDrift(report), false);
+});
+
+test("buildReport: a gh failure for one consumer surfaces as 'error', not a thrown exception", () => {
+  const config = { consumers: [{ name: "broken", repo: "owner/broken" }] };
+  const runGh = () => {
+    throw new Error("gh: repository not found");
+  };
+  const report = buildReport(config, BASELINE, runGh);
+  assert.equal(report.consumers[0].status, "error");
+  assert.match(report.consumers[0].error, /not found/);
+  assert.equal(hasDrift(report), false, "an error is not itself drift");
+});
+
+test("renderReport renders the non-blocking framing and per-consumer rows", () => {
+  const report = {
+    baseline: BASELINE,
+    consumers: [
+      { name: "domio", repo: "dsj1984/domio", status: "current" },
+      {
+        name: "athportal",
+        repo: "dsj1984/athportal",
+        status: "drift",
+        mismatches: [{ field: "allowMergeCommit", expected: false, actual: true }],
+      },
+      { name: "broken", repo: "owner/broken", status: "error", error: "boom" },
+    ],
+  };
+  const text = renderReport(report);
+  assert.match(text, /never a hard gate/);
+  assert.match(text, /domio.*✅ current/);
+  assert.match(text, /athportal.*❌ drift/);
+  assert.match(text, /allowMergeCommit/);
+  assert.match(text, /broken.*⚠️ error/);
+});
+
+test("parseArgv reads --config/--baseline/--json/--strict", () => {
+  const parsed = parseArgv(["--config", "foo.json", "--baseline", "bar.json", "--json", "--strict"]);
+  assert.deepEqual(parsed, { config: "foo.json", baseline: "bar.json", json: true, strict: true });
+});
+
+test("parseArgv defaults to the shared pin-drift consumer registry and the runbook baseline", () => {
+  const parsed = parseArgv([]);
+  assert.equal(parsed.config, "scripts/pin-drift-consumers.json");
+  assert.equal(parsed.baseline, "docs/runbooks/repo-settings.json");
+});
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "repo-settings-test-"));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test("runCli --strict exits 1 when drift is present; exits 0 without --strict (non-blocking default)", () => {
+  const config = { consumers: [{ name: "domio", repo: "dsj1984/domio" }] };
+  const runGh = fakeRunGh({
+    "repos/dsj1984/domio": {
+      allow_squash_merge: true,
+      allow_merge_commit: true, // drift
+      allow_rebase_merge: false,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/dsj1984/domio/actions/permissions/workflow": {
+      default_workflow_permissions: "read",
+      can_approve_pull_request_reviews: false,
+    },
+  });
+
+  const stdout = { write: () => {} };
+  const stderr = { write: () => {} };
+
+  const configPath = join(tmpDir, "consumers.json");
+  const baselinePath = join(tmpDir, "baseline.json");
+  writeFileSync(configPath, JSON.stringify(config));
+  writeFileSync(baselinePath, JSON.stringify(BASELINE));
+
+  const exitNonStrict = runCli({
+    argv: ["--config", configPath, "--baseline", baselinePath],
+    cwd: tmpDir,
+    stdout,
+    stderr,
+    runGh,
+    summaryPath: undefined,
+  });
+  assert.equal(exitNonStrict, 0, "non-strict never fails on drift");
+
+  const exitStrict = runCli({
+    argv: ["--config", configPath, "--baseline", baselinePath, "--strict"],
+    cwd: tmpDir,
+    stdout,
+    stderr,
+    runGh,
+    summaryPath: undefined,
+  });
+  assert.equal(exitStrict, 1, "--strict fails on drift");
+});
+
+test("runCli --json emits a machine-readable envelope with the drift verdict", () => {
+  const config = { consumers: [{ name: "swarm-os", repo: "Beestera/swarm-os" }] };
+  const runGh = fakeRunGh({
+    "repos/Beestera/swarm-os": {
+      allow_squash_merge: true,
+      allow_merge_commit: false,
+      allow_rebase_merge: false,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/Beestera/swarm-os/actions/permissions/workflow": {
+      default_workflow_permissions: "read",
+      can_approve_pull_request_reviews: false,
+    },
+  });
+
+  let out = "";
+  const stdout = { write: (s) => (out += s) };
+  const stderr = { write: () => {} };
+
+  const configPath = join(tmpDir, "consumers.json");
+  const baselinePath = join(tmpDir, "baseline.json");
+  writeFileSync(configPath, JSON.stringify(config));
+  writeFileSync(baselinePath, JSON.stringify(BASELINE));
+
+  const exit = runCli({
+    argv: ["--config", configPath, "--baseline", baselinePath, "--json"],
+    cwd: tmpDir,
+    stdout,
+    stderr,
+    runGh,
+    summaryPath: undefined,
+  });
+  assert.equal(exit, 0);
+  const parsed = JSON.parse(out);
+  assert.equal(parsed.kind, "repo-settings-report");
+  assert.equal(parsed.drift, false);
+  assert.equal(parsed.consumers[0].status, "current");
+});
+
+test("runCli exits 1 on a fatal config-read error (missing file)", () => {
+  let errOut = "";
+  const exit = runCli({
+    argv: ["--config", join(tmpDir, "does-not-exist.json")],
+    cwd: tmpDir,
+    stdout: { write: () => {} },
+    stderr: { write: (s) => (errOut += s) },
+    runGh: () => {
+      throw new Error("should not be called");
+    },
+    summaryPath: undefined,
+  });
+  assert.equal(exit, 1);
+  assert.match(errOut, /failed to read config/);
+});