@biffo/cli 0.60.4 → 0.61.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command23 } from "commander";
+import { Command as Command24 } from "commander";
 
 // src/commands/core.ts
 import { Command as Command4 } from "commander";
@@ -30,6 +30,9 @@ var CoreManifestSchema = z.object({
 });
 var CORE_VERSION_FILE = "core.version";
 var INSTANCE_CORE_FILE = "biffo.core.json";
+function isInstanceRepo(repoRoot) {
+  return existsSync(join(repoRoot, INSTANCE_CORE_FILE));
+}
 function parseCoreVersion(raw) {
   const match = SEMVER.exec(raw.trim());
   if (!match) {
@@ -156,7 +159,18 @@ var CoreManifestSchema2 = z2.object({
   version: z2.literal(1),
   note: z2.string().optional(),
   templateOwned: z2.array(z2.string()).min(1),
-  userOwned: z2.array(z2.string()).default([])
+  userOwned: z2.array(z2.string()).default([]),
+  /**
+   * Paths that version the core but are NOT distributed to instances.
+   *
+   * `cli/` is the case this exists for. The CLI is released from the same
+   * `core-v*` tag as everything else — its published version IS the core
+   * version (ADR-0006) — but an instance consumes it from npm and must not
+   * carry its source. Without this list a CLI-only change would look like "no
+   * template-owned change", the release job would cut nothing, and the fix
+   * would never reach npm for any instance to install.
+   */
+  released: z2.array(z2.string()).default([])
 });
 var HARD_EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git",
@@ -6957,13 +6971,400 @@ var siblingCommand = new Command21("sibling").description(
 );
 siblingCommand.addCommand(siblingCreateCommand);
 
+// src/commands/check.ts
+import { Command as Command22 } from "commander";
+
+// src/scripts/check-core-ownership.ts
+import { execa as execa5 } from "execa";
+
+// src/lib/core-ownership-guard.ts
+import { existsSync as existsSync28, readFileSync as readFileSync21 } from "fs";
+import { join as join29 } from "path";
+import { z as z7 } from "zod";
+var DIVERGENCE_FILE = "biffo.divergence.json";
+var DivergenceEntrySchema = z7.object({
+  prefix: z7.string().min(1),
+  reason: z7.string().min(1),
+  upstream: z7.string().min(1)
+});
+var DivergenceConfigSchema = z7.object({
+  note: z7.string().optional(),
+  warnOnly: z7.array(DivergenceEntrySchema).default([])
+});
+function readDivergenceConfig(repoRoot) {
+  const path = join29(repoRoot, DIVERGENCE_FILE);
+  if (!existsSync28(path)) return { warnOnly: [] };
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync21(path, "utf8"));
+  } catch (err) {
+    throw new Error(`${DIVERGENCE_FILE} is not valid JSON: ${err.message}`);
+  }
+  const parsed = DivergenceConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`${DIVERGENCE_FILE} is invalid:
+${issues}`);
+  }
+  return parsed.data;
+}
+function parseDivergenceTrailer(commitMessage) {
+  const body = commitMessage.split("\n").filter((line) => !line.startsWith("#")).join("\n");
+  const match = /^Core-Divergence:[ \t]*(\S.*?)[ \t]*$/m.exec(body);
+  return match?.[1] ?? null;
+}
+function resolveBranch(env, gitBranch) {
+  return (env["GITHUB_HEAD_REF"] || env["GITHUB_REF_NAME"] || gitBranch).trim();
+}
+function parseNameStatus(stdout) {
+  const changed = [];
+  const deleted = [];
+  for (const line of stdout.split("\n")) {
+    const parts = line.split("	").filter(Boolean);
+    const status = parts[0];
+    const path = parts[parts.length - 1];
+    if (!status || !path || parts.length < 2) continue;
+    changed.push(path);
+    if (status.startsWith("D")) deleted.push(path);
+  }
+  return { changed, deleted };
+}
+function checkCoreOwnership({
+  changedFiles,
+  manifest,
+  isInstance,
+  branch = "",
+  commitMessage = "",
+  warnOnly = []
+}) {
+  const empty = { blocked: [], warned: [], divergenceReason: null };
+  if (!isInstance) return { skipped: "template", ...empty };
+  if (branch.startsWith(UPGRADE_BRANCH_PREFIX)) return { skipped: "upgrade-branch", ...empty };
+  const templateOwned = changedFiles.filter((f) => isTemplateOwned(f, manifest));
+  const acknowledged = (path) => warnOnly.filter((entry) => path.startsWith(entry.prefix)).reduce(
+    (best, entry) => !best || entry.prefix.length > best.prefix.length ? entry : best,
+    void 0
+  );
+  const warned = [];
+  const offending = [];
+  for (const path of templateOwned) {
+    const entry = acknowledged(path);
+    if (entry) warned.push({ path, entry });
+    else offending.push(path);
+  }
+  const divergenceReason = parseDivergenceTrailer(commitMessage);
+  if (offending.length > 0 && divergenceReason !== null) {
+    return { skipped: "divergence-trailer", blocked: [], warned, divergenceReason };
+  }
+  return { skipped: null, blocked: offending, warned, divergenceReason: null };
+}
+
+// src/scripts/check-core-ownership.ts
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var RED = "\x1B[31m";
+var YELLOW = "\x1B[33m";
+var OFF = "\x1B[0m";
+async function runOwnershipCheck(argv) {
+  const args = argv.filter((a) => a !== "--");
+  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();
+  if (!isInstanceRepo(root)) {
+    console.log("\u2713 core ownership guard: skipped \u2014 this is the template, which owns these paths.");
+    return;
+  }
+  let changedFiles;
+  let deletedFiles = [];
+  let commitMessage = "";
+  if (staged) {
+    const { stdout } = await execa5("git", ["diff", "--cached", "--name-status"], { cwd: root });
+    ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
+    if (messageFile) {
+      const { readFileSync: readFileSync23, existsSync: existsSync30 } = await import("fs");
+      if (existsSync30(messageFile)) commitMessage = readFileSync23(messageFile, "utf8");
+    }
+  } else {
+    const base = process.env["GITHUB_BASE_REF"] ?? args[0];
+    if (!base) {
+      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`], {
+      cwd: root
+    });
+    ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
+    const { stdout: log2 } = await execa5("git", ["log", "--format=%B", `origin/${base}..HEAD`], {
+      cwd: root,
+      reject: false
+    });
+    commitMessage = log2;
+  }
+  const { stdout: gitBranch } = await execa5("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd: root,
+    reject: false
+  });
+  const branch = resolveBranch(process.env, gitBranch);
+  const result = checkCoreOwnership({
+    changedFiles,
+    manifest: readCoreManifest(root),
+    isInstance: true,
+    branch,
+    commitMessage,
+    warnOnly: readDivergenceConfig(root).warnOnly
+  });
+  for (const { path, entry } of result.warned) {
+    console.error(
+      `${YELLOW}\u26A0 ${path}${OFF} ${DIM}\u2014 known divergence in ${entry.prefix} (${entry.upstream}); still conflicts at the next core upgrade.${OFF}`
+    );
+  }
+  if (result.skipped === "upgrade-branch") {
+    console.log("\u2713 core ownership guard: skipped \u2014 this is a core-upgrade branch.");
+    return;
+  }
+  if (result.skipped === "divergence-trailer") {
+    console.log(
+      `\u2713 core ownership guard: allowed by Core-Divergence: ${result.divergenceReason ?? ""}`
+    );
+    return;
+  }
+  if (result.blocked.length === 0) {
+    console.log("\u2713 core ownership guard: no template-owned paths changed.");
+    return;
+  }
+  const shown = result.blocked.slice(0, 15);
+  const more = result.blocked.length - shown.length;
+  console.error(`
+${RED}${BOLD}\u2717 This change edits template-owned paths.${OFF}
+
+${shown.map((p) => `    ${RED}${p}${OFF}`).join("\n")}${more > 0 ? `
+    ${DIM}\u2026and ${more} more${OFF}` : ""}
+
+${BOLD}Why this is blocked${OFF}
+  core-manifest.json marks these as owned by biffo-template. Changing them here
+  breaks nothing today \u2014 it becomes a merge conflict at the next
+  \`biffo core upgrade\`, long after the reasoning is gone.
+
+${BOLD}What to do instead${OFF}
+  Make the change in biffo-template, release it, and take it here with
+  \`biffo core upgrade\`. Instance-specific behaviour belongs in a user-owned
+  path \u2014 see core-manifest.json for the split.
+
+${result.blocked.some((p) => deletedFiles.includes(p)) ? `${BOLD}Some of these are deletions${OFF}
+  Deleting a template-owned file is not a smaller change than editing one \u2014 a
+  core upgrade will not restore it (#395), so the instance loses it silently and
+  for ever. If the file genuinely should not exist, delete it in biffo-template.
+
+` : ""}${BOLD}If the divergence is deliberate${OFF}
+  Record it in the commit message and it is allowed:
+
+    ${DIM}Core-Divergence: <why this instance must differ from the template>${OFF}
+
+  Raise an upstream issue too, so it does not stay divergent by accident. For a
+  boundary you knowingly sit astride, add a warn-only prefix to ${DIVERGENCE_FILE}.
+`);
+  process.exit(1);
+}
+
+// src/scripts/check-plugin-terraform.ts
+import { execa as execa6 } from "execa";
+
+// src/lib/plugin-terraform-guard.ts
+import { existsSync as existsSync29, readFileSync as readFileSync22, readdirSync as readdirSync12 } from "fs";
+import { dirname as dirname9, join as join30, 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) {
+  const found = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync12(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        walk(join30(dir, entry.name));
+      } else if (entry.isFile() && entry.name === PLUGIN_MANIFEST_FILE2) {
+        found.push(relative6(root, join30(dir, entry.name)).split(sep3).join("/"));
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+function readSubscriptions(absManifestPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync22(absManifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const subs = parsed["event_subscriptions"];
+  if (!Array.isArray(subs) || subs.length === 0) return null;
+  return subs.map((sub, i) => {
+    if (typeof sub !== "object" || sub === null) return `#${i}`;
+    const { source, detail_type: detailType } = sub;
+    return `${String(source ?? "?")}/${String(detailType ?? "?")}`;
+  });
+}
+function checkPluginTerraform(root) {
+  const violations = [];
+  const coreManifest = existsSync29(join30(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
+  for (const manifest of findPluginManifests(root)) {
+    if (coreManifest && !isTemplateOwned(manifest, coreManifest)) continue;
+    const absManifest = join30(root, manifest);
+    const subscriptions = readSubscriptions(absManifest);
+    if (subscriptions === null) continue;
+    const pluginDir2 = dirname9(absManifest);
+    if (existsSync29(join30(pluginDir2, "terraform"))) continue;
+    const relPluginDir = relative6(root, pluginDir2).split(sep3).join("/");
+    violations.push({
+      manifest,
+      expectedTerraformDir: relPluginDir ? `${relPluginDir}/terraform` : "terraform",
+      subscriptions
+    });
+  }
+  return violations;
+}
+function formatViolations(violations) {
+  return violations.map(
+    (v) => `  ${v.manifest} declares ${v.subscriptions.length} event subscription(s) (${v.subscriptions.join(", ")}) but ships no ${v.expectedTerraformDir}/.
+    Without it there is no Lambda and no EventBridge rule, so those events never reach the plugin \u2014 and \`biffo plugin install\` skips the Terraform copy silently.
+    Fix: copy modules/plugins/_template/ to ${v.expectedTerraformDir}/ and set handler/event_subscriptions to match the manifest.`
+  ).join("\n\n");
+}
+
+// src/scripts/check-plugin-terraform.ts
+async function runPluginTerraformCheck() {
+  const root = (await execa6("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");
+    console.error(formatViolations(violations));
+    process.exit(1);
+  }
+  console.log("\u2713 plugin Terraform guard: OK");
+}
+
+// src/scripts/check-release-subject.ts
+import { execa as execa7 } from "execa";
+
+// src/lib/release-version.ts
+var MINOR_TYPES = /* @__PURE__ */ new Set(["feat"]);
+var SUBJECT = /^([a-z]+)(?:\([^)]*\))?(!)?:\s+\S/;
+function parseConventionalSubject(subject) {
+  const match = SUBJECT.exec(subject.trim());
+  if (!match?.[1]) return null;
+  return { type: match[1], breaking: match[2] === "!" };
+}
+function bumpKindFor(subjects) {
+  for (const subject of subjects) {
+    const parsed = parseConventionalSubject(subject);
+    if (parsed && (parsed.breaking || MINOR_TYPES.has(parsed.type))) return "minor";
+  }
+  return "patch";
+}
+
+// src/lib/release-subject-guard.ts
+function checkReleaseSubject(changedFiles, subject, manifest, isInstance) {
+  const templateOwnedChanges = changedFiles.filter((f) => isTemplateOwned(f, manifest));
+  const parsed = parseConventionalSubject(subject);
+  const releases = !isInstance && templateOwnedChanges.length > 0;
+  return {
+    templateOwnedChanges,
+    unparseable: releases && parsed === null,
+    bump: parsed === null ? null : bumpKindFor([subject]),
+    skippedAsInstance: isInstance
+  };
+}
+
+// src/scripts/check-release-subject.ts
+async function runReleaseSubjectCheck(argv) {
+  const base = process.env["GITHUB_BASE_REF"] ?? argv[0];
+  if (!base) {
+    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`], {
+    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 manifest = readCoreManifest(root);
+  const { unparseable, bump, templateOwnedChanges, skippedAsInstance } = checkReleaseSubject(
+    changedFiles,
+    subject,
+    manifest,
+    isInstanceRepo(root)
+  );
+  if (skippedAsInstance) {
+    console.log(
+      `\u2713 release subject guard: skipped \u2014 this is an instance (${INSTANCE_CORE_FILE} present), not the template. Instances cut no core-v* release, so the title is not a release input.`
+    );
+    return;
+  }
+  if (templateOwnedChanges.length === 0) {
+    console.log(
+      "\u2713 release subject guard: no template-owned change, so this PR releases nothing and its title is not a release input."
+    );
+    return;
+  }
+  if (unparseable) {
+    console.error(
+      `
+\u2717 Pull request title is not a Conventional Commits subject.
+
+  Title: ${subject}
+
+  This PR changes ${templateOwnedChanges.length} template-owned path(s), so merging it cuts a core release:
+` + templateOwnedChanges.slice(0, 10).map((p) => `    - ${p}`).join("\n") + (templateOwnedChanges.length > 10 ? `
+    \u2026 and ${templateOwnedChanges.length - 10} more` : "") + `
+
+  Squash-merge makes this title the commit subject on \`main\`, and the release job derives the version bump from it (ADR-0006, #423). A title it cannot parse silently becomes a patch \u2014 so a feature would ship as one, and instances tracking the minor line would never see it.
+
+  Retitle as \`type(scope): summary\` \u2014 e.g. \`feat(api): add run history endpoint\`. Use \`feat\` for a feature, \`fix\` for a fix, a trailing \`!\` for a breaking change.
+`
+    );
+    process.exit(1);
+  }
+  console.log(
+    `\u2713 release subject guard: "${subject}" \u2192 ${bump ?? "patch"} release for ${templateOwnedChanges.length} template-owned change(s).`
+  );
+}
+
+// src/commands/check.ts
+var checkCommand = new Command22("check").description(
+  "Repo guards (ownership, release subject, plugin terraform) \u2014 run in CI and git hooks"
+);
+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"));
+});
+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-terraform").description("Verify every template-owned plugin declaring infra ships a Terraform module").action(async () => {
+  await runPluginTerraformCheck();
+});
+function rawArgsAfter(subcommand) {
+  const at = process.argv.indexOf(subcommand);
+  return at === -1 ? [] : process.argv.slice(at + 1);
+}
+
 // src/commands/teardown.ts
 import { execSync as execSync7 } from "child_process";
 import { GetCallerIdentityCommand as GetCallerIdentityCommand3, STSClient as STSClient3 } from "@aws-sdk/client-sts";
 import chalk20 from "chalk";
-import { Command as Command22 } from "commander";
+import { Command as Command23 } from "commander";
 import inquirer8 from "inquirer";
-var teardownCommand = new Command22("teardown").description(
+var teardownCommand = new Command23("teardown").description(
   "Destroy all infrastructure then remove the repo, IAM role, and state bucket \u2014 single command"
 ).option("--project <name>", "Project name to tear down (reads session if omitted)").option("--skip-destroy", "Skip terraform destroy (only use if infrastructure is already gone)").option(
   "--confirm <name>",
@@ -7371,7 +7772,7 @@ function resolveGithubToken4() {
 }
 
 // src/index.ts
-var program = new Command23();
+var program = new Command24();
 function cliVersion() {
   try {
     return getLatestCoreVersion();
@@ -7388,6 +7789,7 @@ program.addCommand(pluginCommand);
 program.addCommand(dataCommand);
 program.addCommand(coreCommand);
 program.addCommand(siblingCommand);
+program.addCommand(checkCommand);
 registerNonInteractive(program);
 program.parseAsync().catch((err) => {
   if (err instanceof NonInteractiveError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.60.4",
+  "version": "0.61.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",
@@ -34,9 +34,9 @@
     "lint:fix": "eslint src/ --fix",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "check:release-subject": "tsx src/scripts/check-release-subject.ts",
-    "check:core-ownership": "tsx src/scripts/check-core-ownership.ts",
-    "check:plugin-terraform": "tsx src/scripts/check-plugin-terraform.ts",
+    "check:release-subject": "tsx src/index.ts check release-subject",
+    "check:core-ownership": "tsx src/index.ts check ownership",
+    "check:plugin-terraform": "tsx src/index.ts check plugin-terraform",
     "sync:core-tag": "tsx src/scripts/sync-core-tag.ts",
     "report:publish-failure": "tsx src/scripts/report-publish-failure.ts"
   },