@biffo/cli 0.146.3 → 0.148.0

package/_skeletons/plugin-template/AGENTS.md

@@ -66,7 +66,39 @@ repo; only its product differs.
   before merge: `git log origin/<branch> -1`. A green PR page is not proof your
   latest local commit reached it.
 
-## 7. CI runners — two steps this repo cannot do for itself
+## 7. Creating this repo correctly (read once, at birth)
+
+**No `biffo` command creates a standalone plugin repo.** `biffo plugin create`
+scaffolds a plugin _into an existing checkout_; a repo like this one is made by
+hand. So the governance that `biffo init` and `biffo sibling create` apply
+automatically is **not applied here**, and has to be set deliberately.
+
+That gap is not theoretical: both existing plugin repos ran with **no branch
+protection at all**, and `biffo-plugin-ideation#54` was merged with both CI jobs
+still in progress because nothing stopped it (biffo-template#714).
+
+After creating the repo and pushing this skeleton:
+
+```bash
+# 1. Auto-merge must be ON, or `gh pr merge --auto` merges IMMEDIATELY
+#    rather than queuing — see the warning below.
+gh api -X PATCH repos/<org>/<repo> -f allow_auto_merge=true -f delete_branch_on_merge=true
+
+# 2. Protect dev, deriving the required checks from what CI actually reports.
+#    Run it once CI has gone green at least twice, so there is something to derive from.
+biffo check branch-protection --repo <org>/<repo> --fix
+
+# 3. Confirm it took.
+biffo check branch-protection --repo <org>/<repo>
+```
+
+> **`--auto` is not a safety net on an unconfigured repo.** With
+> `allow_auto_merge` disabled, `gh pr merge --squash --auto` does not queue — it
+> merges _now_ if the PR is mergeable at that instant. On an unprotected branch
+> that means merging with checks still running. Steps 1 and 2 together are what
+> make the documented flow behave as documented; either alone is not enough.
+
+## 8. CI runners — two steps this repo cannot do for itself
 
 The workflows use `runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}`, so they
 work anywhere by default and route to a self-hosted fleet when one exists. Two
@@ -83,7 +115,7 @@ fleet:
 If a job is queued and nothing is happening, check the grant before anything
 else. It is the failure that looks exactly like patience.
 
-## 8. Security
+## 9. Security
 
 - **Never commit secrets** (keys, tokens, credentials, `.env` values).
 - **Never silently disable a security gate.** If one must be loosened, do it in

package/dist/index.js

@@ -638,6 +638,10 @@ var DEFAULT_STATUS_CHECKS = [
   "Secret Scan",
   "Terraform Validate & Security"
 ];
+var REPO_MERGE_SETTINGS = {
+  allow_auto_merge: true,
+  delete_branch_on_merge: true
+};
 var GitHubAdapter = class {
   octokit;
   templateOwner;
@@ -775,6 +779,7 @@ var GitHubAdapter = class {
         org,
         name: repo,
         private: true,
+        ...REPO_MERGE_SETTINGS,
         ...description !== void 0 ? { description } : {}
       });
       log.success(`Repository created: ${data2.html_url}`);
@@ -785,6 +790,7 @@ var GitHubAdapter = class {
     const { data } = await this.octokit.repos.createForAuthenticatedUser({
       name: repo,
       private: true,
+      ...REPO_MERGE_SETTINGS,
       ...description !== void 0 ? { description } : {}
     });
     log.success(`Repository created: ${data.html_url}`);
@@ -7736,6 +7742,72 @@ import { Command as Command23 } from "commander";
 import { Octokit as Octokit2 } from "@octokit/rest";
 import { execa as execa5 } from "execa";
 
+// src/lib/branch-protection-apply.ts
+var CONTEXT_CONSISTENCY_THRESHOLD = 2 / 3;
+var RECENT_COMMIT_WINDOW = 6;
+function deriveRequiredContexts(observed) {
+  const shasNewestFirst = [];
+  for (const { headSha } of observed) {
+    if (!shasNewestFirst.includes(headSha)) shasNewestFirst.push(headSha);
+  }
+  const window = shasNewestFirst.slice(0, RECENT_COMMIT_WINDOW);
+  if (window.length === 0) return [];
+  const seenOn = /* @__PURE__ */ new Map();
+  for (const { name, headSha } of observed) {
+    if (!window.includes(headSha)) continue;
+    const set = seenOn.get(name) ?? /* @__PURE__ */ new Set();
+    set.add(headSha);
+    seenOn.set(name, set);
+  }
+  const required = Math.ceil(window.length * CONTEXT_CONSISTENCY_THRESHOLD);
+  return [...seenOn.entries()].filter(([, shas]) => shas.size >= required).map(([name]) => name).sort();
+}
+function protectionParamsFor(contexts) {
+  return {
+    required_status_checks: { strict: true, contexts: [...contexts].sort() },
+    enforce_admins: false,
+    required_pull_request_reviews: {
+      required_approving_review_count: 0,
+      dismiss_stale_reviews: false
+    },
+    restrictions: null,
+    required_linear_history: true,
+    allow_force_pushes: false,
+    allow_deletions: false
+  };
+}
+function planProtection(branch, exists, observed) {
+  if (!exists) {
+    return {
+      branch,
+      action: "skip",
+      reason: "branch does not exist",
+      contexts: []
+    };
+  }
+  const contexts = deriveRequiredContexts(observed);
+  if (contexts.length === 0) {
+    return {
+      branch,
+      action: "skip",
+      reason: "no check has reported consistently enough to require \u2014 applying protection with an empty context list would make the branch look protected while admitting any PR",
+      contexts: []
+    };
+  }
+  return {
+    branch,
+    action: "apply",
+    reason: `requiring ${contexts.length} context(s) observed on recent commits`,
+    contexts
+  };
+}
+function formatPlans(plans) {
+  return plans.map(
+    (p) => p.action === "apply" ? `  ${p.branch}: apply \u2014 ${p.reason}
+${p.contexts.map((c) => `      \u2022 ${c}`).join("\n")}` : `  ${p.branch}: skip \u2014 ${p.reason}`
+  ).join("\n");
+}
+
 // src/lib/branch-protection-audit.ts
 function auditBranch(branch, protection) {
   if (protection === null) {
@@ -7805,7 +7877,16 @@ async function resolveRepo(explicit) {
   }
   return { owner: m[1], repo: m[2] };
 }
-async function runBranchProtectionCheck(explicitRepo) {
+async function observedChecks(octokit, owner, repo, branch) {
+  const { data } = await octokit.actions.listWorkflowRunsForRepo({
+    owner,
+    repo,
+    branch,
+    per_page: 60
+  });
+  return data.workflow_runs.filter((r) => r.status === "completed").map((r) => ({ name: r.name ?? "", headSha: r.head_sha })).filter((c) => c.name !== "");
+}
+async function runBranchProtectionCheck(explicitRepo, options = {}) {
   const { owner, repo } = await resolveRepo(explicitRepo);
   const octokit = new Octokit2({
     auth: tokenFromEnv(),
@@ -7851,12 +7932,39 @@ async function runBranchProtectionCheck(explicitRepo) {
     );
     process.exit(1);
   }
+  if (findings.length > 0 && options.fix) {
+    const defaultBranch = (await octokit.repos.get({ owner, repo })).data.default_branch;
+    const observed = await observedChecks(octokit, owner, repo, defaultBranch);
+    const plans = audited.map((branch) => planProtection(branch, true, observed));
+    console.log(`Backfilling protection on ${owner}/${repo}:
+`);
+    console.log(formatPlans(plans));
+    let applied = 0;
+    for (const plan of plans.filter((p) => p.action === "apply")) {
+      await octokit.repos.updateBranchProtection({
+        owner,
+        repo,
+        branch: plan.branch,
+        ...protectionParamsFor(plan.contexts)
+      });
+      applied += 1;
+    }
+    if (applied === 0) {
+      console.error(
+        "\n\u2717 nothing applied \u2014 no branch had a check reporting consistently enough to require.\n  Protection with an empty context list is worse than none: a PR reads CLEAN before\n  any run registers. Get CI reporting on this repo first."
+      );
+      process.exit(1);
+    }
+    console.log(`
+\u2713 protection applied to ${applied} branch(es). Re-run without --fix to verify.`);
+    return;
+  }
   if (findings.length > 0) {
     console.error(`\u2717 branch-protection guard: ${owner}/${repo}
 `);
     console.error(formatFindings(findings));
     console.error(
-      "\n  Protection is applied once at scaffold time and skipped silently on a 403 (#715).\n  Fix with the repo settings API, matching the policy \u2014 not the exact required\n  checks, which legitimately differ per repo."
+      "\n  Protection is applied once at scaffold time and skipped silently on a 403 (#715),\n  and standalone plugin repos are created outside the CLI so it never runs at all\n  (#714). Re-run with --fix to backfill it from the checks this repo actually reports."
     );
     process.exit(1);
   }
@@ -8269,8 +8377,11 @@ checkCommand.command("plugin-terraform").description("Verify every template-owne
 });
 checkCommand.command("branch-protection").description(
   "Verify dev/staging/main are actually protected \u2014 scaffolding skips this on a 403 (#715)"
-).option("--repo <owner/name>", "Repo to audit; defaults to this checkout's origin remote").action(async (opts) => {
-  await runBranchProtectionCheck(opts.repo);
+).option("--repo <owner/name>", "Repo to audit; defaults to this checkout's origin remote").option(
+  "--fix",
+  "Backfill protection from the checks this repo actually reports (#714, #715). Refuses to apply an empty required-check list, which would look protected and admit anything."
+).action(async (opts) => {
+  await runBranchProtectionCheck(opts.repo, { fix: opts.fix });
 });
 function rawArgsAfter(subcommand) {
   const at = process.argv.indexOf(subcommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.146.3",
+  "version": "0.148.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",