@biffo/cli 0.142.3 → 0.145.0

package/dist/index.js

@@ -7732,8 +7732,139 @@ siblingCommand.addCommand(siblingCheckIdentityCommand);
 // src/commands/check.ts
 import { Command as Command23 } from "commander";
 
-// src/scripts/check-core-ownership.ts
+// src/scripts/check-branch-protection.ts
+import { Octokit as Octokit2 } from "@octokit/rest";
 import { execa as execa5 } from "execa";
+
+// src/lib/branch-protection-audit.ts
+function auditBranch(branch, protection) {
+  if (protection === null) {
+    return [
+      {
+        branch,
+        kind: "unprotected",
+        detail: "no branch protection at all \u2014 direct pushes, force-pushes and merges with red or absent checks are all permitted"
+      }
+    ];
+  }
+  const findings = [];
+  const checks = protection.required_status_checks;
+  if (!checks || (checks.contexts ?? []).length === 0) {
+    findings.push({
+      branch,
+      kind: "no-required-checks",
+      detail: "protection exists but requires no status checks, so a PR is mergeable before any check has run"
+    });
+  } else if (checks.strict !== true) {
+    findings.push({
+      branch,
+      kind: "not-strict",
+      detail: "required checks are not strict, so a branch can merge without being up to date with the base"
+    });
+  }
+  if (protection.allow_force_pushes?.enabled === true) {
+    findings.push({ branch, kind: "force-push-allowed", detail: "force-pushes are permitted" });
+  }
+  if (protection.allow_deletions?.enabled === true) {
+    findings.push({ branch, kind: "deletion-allowed", detail: "branch deletion is permitted" });
+  }
+  return findings;
+}
+function formatFindings(findings) {
+  return findings.map((f) => `  ${f.branch}: ${f.detail}`).join("\n");
+}
+
+// src/scripts/check-branch-protection.ts
+var BRANCHES = ["dev", "staging", "main"];
+function tokenFromEnv() {
+  const token = process.env["GITHUB_TOKEN"] ?? process.env["GH_TOKEN"] ?? "";
+  if (!token) {
+    console.error(
+      "\u2717 branch-protection guard: no GitHub token.\n  Set GITHUB_TOKEN or GH_TOKEN. Reading protection needs admin on the repo,\n  so a default read-only CI token is not enough \u2014 this guard is meant to be\n  run deliberately, not on every PR."
+    );
+    process.exit(2);
+  }
+  return token;
+}
+async function resolveRepo(explicit) {
+  if (explicit) {
+    const [owner, repo] = explicit.split("/");
+    if (!owner || !repo) {
+      console.error(`\u2717 branch-protection guard: --repo must be "owner/name", got "${explicit}"`);
+      process.exit(2);
+    }
+    return { owner, repo };
+  }
+  const { stdout } = await execa5("git", ["remote", "get-url", "origin"]);
+  const m = /github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/.exec(stdout.trim());
+  if (!m?.[1] || !m[2]) {
+    console.error(
+      `\u2717 branch-protection guard: cannot parse a GitHub repo from origin "${stdout.trim()}"`
+    );
+    process.exit(2);
+  }
+  return { owner: m[1], repo: m[2] };
+}
+async function runBranchProtectionCheck(explicitRepo) {
+  const { owner, repo } = await resolveRepo(explicitRepo);
+  const octokit = new Octokit2({
+    auth: tokenFromEnv(),
+    log: { debug: () => {
+    }, info: () => {
+    }, warn: () => {
+    }, error: console.error }
+  });
+  const findings = [];
+  const audited = [];
+  for (const branch of BRANCHES) {
+    try {
+      await octokit.repos.getBranch({ owner, repo, branch });
+    } catch (err) {
+      if (err.status === 404) continue;
+      throw err;
+    }
+    audited.push(branch);
+    try {
+      const { data } = await octokit.repos.getBranchProtection({ owner, repo, branch });
+      findings.push(...auditBranch(branch, data));
+    } catch (err) {
+      if (err.status === 404) {
+        findings.push(...auditBranch(branch, null));
+        continue;
+      }
+      if (err.status === 403) {
+        console.error(
+          `\u2717 branch-protection guard: GitHub returned 403 reading ${owner}/${repo}.
+  Either the token lacks admin, or this org/plan cannot protect private repos.
+  The latter is the condition that caused #715 \u2014 protection was skipped at
+  scaffold time and never revisited. It is a finding, not a reason to pass.`
+        );
+        process.exit(1);
+      }
+      throw err;
+    }
+  }
+  if (audited.length === 0) {
+    console.error(
+      `\u2717 branch-protection guard: ${owner}/${repo} has none of ${BRANCHES.join("/")}.
+  A repo with no dev branch has not been migrated (biffo-template#559).`
+    );
+    process.exit(1);
+  }
+  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."
+    );
+    process.exit(1);
+  }
+  console.log(`\u2713 branch-protection guard: ${owner}/${repo} (${audited.join(", ")}) OK`);
+}
+
+// src/scripts/check-core-ownership.ts
+import { execa as execa6 } from "execa";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
 var RED = "\x1B[31m";
@@ -7744,7 +7875,7 @@ async function runOwnershipCheck(argv) {
   const stagedFlag = args.indexOf("--staged");
   const staged = stagedFlag !== -1;
   const messageFile = staged ? args[stagedFlag + 1] : void 0;
-  const root = (await execa5("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const root = (await execa6("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   if (!isInstanceRepo(root)) {
     console.log("\u2713 core ownership guard: skipped \u2014 this is the template, which owns these paths.");
     return;
@@ -7753,11 +7884,11 @@ async function runOwnershipCheck(argv) {
   let deletedFiles = [];
   let commitMessage = "";
   if (staged) {
-    const { stdout } = await execa5("git", ["diff", "--cached", "--name-status"], { cwd: root });
+    const { stdout } = await execa6("git", ["diff", "--cached", "--name-status"], { cwd: root });
     ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
     if (messageFile) {
-      const { readFileSync: readFileSync25, existsSync: existsSync32 } = await import("fs");
-      if (existsSync32(messageFile)) commitMessage = readFileSync25(messageFile, "utf8");
+      const { readFileSync: readFileSync25, existsSync: existsSync34 } = await import("fs");
+      if (existsSync34(messageFile)) commitMessage = readFileSync25(messageFile, "utf8");
     }
   } else {
     const base = process.env["GITHUB_BASE_REF"] ?? args[0];
@@ -7765,18 +7896,18 @@ async function runOwnershipCheck(argv) {
       console.error("No base ref: set GITHUB_BASE_REF or pass a base branch as the first argument.");
       process.exit(2);
     }
-    await execa5("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
-    const { stdout } = await execa5("git", ["diff", "--name-status", `origin/${base}...HEAD`], {
+    await execa6("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
+    const { stdout } = await execa6("git", ["diff", "--name-status", `origin/${base}...HEAD`], {
       cwd: root
     });
     ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
-    const { stdout: log2 } = await execa5("git", ["log", "--format=%B", `origin/${base}..HEAD`], {
+    const { stdout: log2 } = await execa6("git", ["log", "--format=%B", `origin/${base}..HEAD`], {
       cwd: root,
       reject: false
     });
     commitMessage = log2;
   }
-  const { stdout: gitBranch } = await execa5("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+  const { stdout: gitBranch } = await execa6("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
     cwd: root,
     reject: false
   });
@@ -7857,12 +7988,103 @@ ${BOLD}If the divergence is deliberate${OFF}
   process.exit(1);
 }
 
+// src/scripts/check-plugin-collisions.ts
+import { existsSync as existsSync32 } from "fs";
+import { join as join32 } from "path";
+import { execa as execa7 } from "execa";
+
+// src/lib/plugin-collision-guard.ts
+import { existsSync as existsSync31, readdirSync as readdirSync13, statSync as statSync7 } from "fs";
+import { join as join31 } from "path";
+var PYTEST_SPECIAL = /* @__PURE__ */ new Set(["conftest.py"]);
+var IGNORED_DIRS = /* @__PURE__ */ new Set([".venv", "node_modules", "__pycache__", ".git", "dist", "build"]);
+function subdirectories(dir) {
+  if (!existsSync31(dir)) return [];
+  return readdirSync13(dir).filter((entry) => {
+    if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) return false;
+    try {
+      return statSync7(join31(dir, entry)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+function regularPackagesOf(pluginDir2) {
+  return subdirectories(pluginDir2).filter((name) => existsSync31(join31(pluginDir2, name, "__init__.py"))).sort();
+}
+function bareTestModulesOf(pluginDir2) {
+  const testsDir = join31(pluginDir2, "tests");
+  if (!existsSync31(testsDir)) return [];
+  if (existsSync31(join31(testsDir, "__init__.py"))) return [];
+  return readdirSync13(testsDir).filter((f) => f.endsWith(".py") && !PYTEST_SPECIAL.has(f)).sort();
+}
+function findCollisions(servicesDir, pluginDirs) {
+  const plugins = (pluginDirs ?? subdirectories(servicesDir)).filter((name) => !name.startsWith("_")).filter((name) => name !== "api").sort();
+  const collisions = [];
+  const gather = (kind, namesOf) => {
+    const claims = /* @__PURE__ */ new Map();
+    for (const plugin of plugins) {
+      for (const name of namesOf(join31(servicesDir, plugin))) {
+        claims.set(name, [...claims.get(name) ?? [], plugin]);
+      }
+    }
+    for (const [name, owners] of [...claims.entries()].sort()) {
+      if (owners.length > 1) collisions.push({ kind, name, plugins: owners.sort() });
+    }
+  };
+  gather("regular-package", regularPackagesOf);
+  gather("test-module", bareTestModulesOf);
+  return collisions;
+}
+function formatCollisions(collisions) {
+  const lines = [];
+  for (const c of collisions) {
+    if (c.kind === "regular-package") {
+      lines.push(
+        `  regular package '${c.name}' is defined by: ${c.plugins.join(", ")}`,
+        `    Regular packages do not merge across sys.path \u2014 the first found shadows`,
+        `    the rest, and the plugin that breaks is whichever loaded second.`,
+        `    Fix: load these modules by file path instead of making '${c.name}' a`,
+        `    package (drop its __init__.py), or give it a plugin-scoped name.`
+      );
+    } else {
+      lines.push(
+        `  test module '${c.name}' is shipped by: ${c.plugins.join(", ")}`,
+        `    pytest's prepend import mode imports test modules by bare basename, so`,
+        `    only one of these can be collected.`,
+        `    Fix: prefix it with the plugin name, e.g. '${c.plugins[0]}_${c.name}'.`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/scripts/check-plugin-collisions.ts
+async function runPluginCollisionCheck() {
+  const root = (await execa7("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const servicesDir = join32(root, "services");
+  if (!existsSync32(servicesDir)) {
+    console.log("\u2713 plugin collision guard: no services/ directory \u2014 nothing to compare");
+    return;
+  }
+  const collisions = findCollisions(servicesDir);
+  if (collisions.length > 0) {
+    console.error("\u2717 plugin collision guard: two plugins claim the same importable name\n");
+    console.error(formatCollisions(collisions));
+    console.error(
+      "\nThis breaks the plugin that loads *second*, which is usually the one that\nwas already working. See biffo-template#688."
+    );
+    process.exit(1);
+  }
+  console.log("\u2713 plugin collision guard: OK");
+}
+
 // src/scripts/check-plugin-terraform.ts
-import { execa as execa6 } from "execa";
+import { execa as execa8 } from "execa";
 
 // src/lib/plugin-terraform-guard.ts
-import { existsSync as existsSync31, readFileSync as readFileSync24, readdirSync as readdirSync13 } from "fs";
-import { dirname as dirname9, join as join31, relative as relative6, sep as sep3 } from "path";
+import { existsSync as existsSync33, readFileSync as readFileSync24, readdirSync as readdirSync14 } from "fs";
+import { dirname as dirname9, join as join33, relative as relative6, sep as sep3 } from "path";
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".worktrees", "dist", ".venv", "__pycache__"]);
 var PLUGIN_MANIFEST_FILE2 = "biffo.plugin.json";
 function findPluginManifests(root) {
@@ -7870,16 +8092,16 @@ function findPluginManifests(root) {
   const walk = (dir) => {
     let entries;
     try {
-      entries = readdirSync13(dir, { withFileTypes: true });
+      entries = readdirSync14(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name)) continue;
-        walk(join31(dir, entry.name));
+        walk(join33(dir, entry.name));
       } else if (entry.isFile() && entry.name === PLUGIN_MANIFEST_FILE2) {
-        found.push(relative6(root, join31(dir, entry.name)).split(sep3).join("/"));
+        found.push(relative6(root, join33(dir, entry.name)).split(sep3).join("/"));
       }
     }
   };
@@ -7904,14 +8126,14 @@ function readSubscriptions(absManifestPath) {
 }
 function checkPluginTerraform(root) {
   const violations = [];
-  const coreManifest = existsSync31(join31(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
+  const coreManifest = existsSync33(join33(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
   for (const manifest of findPluginManifests(root)) {
     if (coreManifest && !isTemplateOwned(manifest, coreManifest)) continue;
-    const absManifest = join31(root, manifest);
+    const absManifest = join33(root, manifest);
     const subscriptions = readSubscriptions(absManifest);
     if (subscriptions === null) continue;
     const pluginDir2 = dirname9(absManifest);
-    if (existsSync31(join31(pluginDir2, "terraform"))) continue;
+    if (existsSync33(join33(pluginDir2, "terraform"))) continue;
     const relPluginDir = relative6(root, pluginDir2).split(sep3).join("/");
     violations.push({
       manifest,
@@ -7931,7 +8153,7 @@ function formatViolations(violations) {
 
 // src/scripts/check-plugin-terraform.ts
 async function runPluginTerraformCheck() {
-  const root = (await execa6("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const root = (await execa8("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   const violations = checkPluginTerraform(root);
   if (violations.length > 0) {
     console.error("\u2717 plugin Terraform guard: event subscriptions with no infrastructure\n");
@@ -7942,7 +8164,7 @@ async function runPluginTerraformCheck() {
 }
 
 // src/scripts/check-release-subject.ts
-import { execa as execa7 } from "execa";
+import { execa as execa9 } from "execa";
 
 // src/lib/release-version.ts
 var MINOR_TYPES = /* @__PURE__ */ new Set(["feat"]);
@@ -7980,13 +8202,13 @@ async function runReleaseSubjectCheck(argv) {
     console.error("No base ref: set GITHUB_BASE_REF or pass a base branch as the first argument.");
     process.exit(2);
   }
-  const root = (await execa7("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
-  await execa7("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
-  const { stdout } = await execa7("git", ["diff", "--name-only", `origin/${base}...HEAD`], {
+  const root = (await execa9("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  await execa9("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
+  const { stdout } = await execa9("git", ["diff", "--name-only", `origin/${base}...HEAD`], {
     cwd: root
   });
   const changedFiles = stdout.split("\n").map((s) => s.trim()).filter(Boolean);
-  const subject = process.env["PR_TITLE"]?.trim() || (await execa7("git", ["log", "-1", "--format=%s"], { cwd: root })).stdout.trim();
+  const subject = process.env["PR_TITLE"]?.trim() || (await execa9("git", ["log", "-1", "--format=%s"], { cwd: root })).stdout.trim();
   const manifest = readCoreManifest(root);
   const { unparseable, bump, templateOwnedChanges, skippedAsInstance } = checkReleaseSubject(
     changedFiles,
@@ -8031,7 +8253,7 @@ async function runReleaseSubjectCheck(argv) {
 
 // src/commands/check.ts
 var checkCommand = new Command23("check").description(
-  "Repo guards (ownership, release subject, plugin terraform) \u2014 run in CI and git hooks"
+  "Repo guards (ownership, release subject, plugin terraform, plugin collisions) run in CI and git hooks, plus out-of-band audits (branch protection)"
 );
 checkCommand.command("ownership").description("Refuse changes to template-owned paths in an instance (#370)").argument("[base]", "Base branch to diff against; defaults to $GITHUB_BASE_REF").option("--staged <messageFile>", "Check staged changes instead of a branch diff (commit hook)").allowExcessArguments(true).action(async () => {
   await runOwnershipCheck(rawArgsAfter("ownership"));
@@ -8039,9 +8261,17 @@ checkCommand.command("ownership").description("Refuse changes to template-owned
 checkCommand.command("release-subject").description("Require a Conventional Commits PR title on template-owned changes (#423)").argument("[base]", "Base branch to diff against; defaults to $GITHUB_BASE_REF").action(async () => {
   await runReleaseSubjectCheck(rawArgsAfter("release-subject"));
 });
+checkCommand.command("plugin-collisions").description("Refuse two vendored plugins claiming the same importable name (#688)").action(async () => {
+  await runPluginCollisionCheck();
+});
 checkCommand.command("plugin-terraform").description("Verify every template-owned plugin declaring infra ships a Terraform module").action(async () => {
   await runPluginTerraformCheck();
 });
+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);
+});
 function rawArgsAfter(subcommand) {
   const at = process.argv.indexOf(subcommand);
   return at === -1 ? [] : process.argv.slice(at + 1);

package/package.json

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