@biffo/cli 0.298.22 → 0.298.24

package/dist/index.js

@@ -371,6 +371,39 @@ function isTemplateOwned(relPath, manifest) {
   const u = longestMatch(relPath, manifest.userOwned);
   return t > u;
 }
+function leadingSegmentOverlap(relPath, pattern) {
+  const pathSegs = relPath.split("/");
+  const patternSegs = pattern.replace(/\/$/, "").split("/");
+  let shared = 0;
+  for (let i = 0; i < Math.min(pathSegs.length, patternSegs.length); i++) {
+    if (patternSegs[i] !== pathSegs[i]) break;
+    shared++;
+  }
+  return shared;
+}
+function explainOwnership(relPath, manifest) {
+  let templateOwnedMatch = null;
+  let bestTemplateLen = -1;
+  for (const p of manifest.templateOwned) {
+    const len = matchLength(relPath, p);
+    if (len > bestTemplateLen) {
+      bestTemplateLen = len;
+      templateOwnedMatch = p;
+    }
+  }
+  let bestShared = 0;
+  let nearestUserOwnedEntries = [];
+  for (const p of manifest.userOwned) {
+    const shared = leadingSegmentOverlap(relPath, p);
+    if (shared > bestShared) {
+      bestShared = shared;
+      nearestUserOwnedEntries = [p];
+    } else if (shared === bestShared && shared > 0) {
+      nearestUserOwnedEntries.push(p);
+    }
+  }
+  return { templateOwnedMatch, nearestUserOwnedEntries };
+}
 function toPosix(p) {
   return sep === "/" ? p : p.split(sep).join("/");
 }
@@ -11755,8 +11788,8 @@ async function runOwnershipCheck(argv) {
     const { stdout } = await execa("git", ["diff", "--cached", "--name-status"], { cwd: root });
     ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
     if (messageFile) {
-      const { readFileSync: readFileSync45, existsSync: existsSync54 } = await import("fs");
-      if (existsSync54(messageFile)) commitMessage = readFileSync45(messageFile, "utf8");
+      const { readFileSync: readFileSync45, existsSync: existsSync55 } = await import("fs");
+      if (existsSync55(messageFile)) commitMessage = readFileSync45(messageFile, "utf8");
     }
   } else {
     const base = process.env["GITHUB_BASE_REF"] ?? args[0];
@@ -12463,6 +12496,71 @@ ${BOLD2}What to do${OFF2}
   process.exit(1);
 }
 
+// src/scripts/check-orphan-ratchet.ts
+import { existsSync as existsSync46 } from "fs";
+import { basename as basename2 } from "path";
+function reportOrphan(entry, manifest) {
+  console.error(`  ${entry.path}`);
+  const { templateOwnedMatch, nearestUserOwnedEntries } = explainOwnership(entry.path, manifest);
+  console.error(
+    `    claimed by templateOwned entry: ${templateOwnedMatch ?? "(none \u2014 unexpected)"}`
+  );
+  if (nearestUserOwnedEntries.length > 0) {
+    console.error(`    nearest sanctioned carve-out(s): ${nearestUserOwnedEntries.join(", ")}`);
+    console.error(
+      "    \u2014 move it under one of those, OR add it to biffo.divergence.json with a Core-Divergence trailer if it belongs there permanently."
+    );
+  } else {
+    console.error(
+      "    no userOwned entry shares any leading path segment with this file \u2014 core-manifest.json has no carve-out anywhere near it today."
+    );
+    console.error(
+      "    Either this is a core capability that belongs upstream in biffo-template, or it needs a new carve-out declared in core-manifest.json. classify()/isTemplateOwned() cannot tell those apart automatically (#1714) \u2014 that judgement is the author's."
+    );
+  }
+}
+async function runOrphanRatchetCheck(opts = {}) {
+  if (opts.instanceDir !== void 0 && !existsSync46(opts.instanceDir)) {
+    console.error(
+      `\u2717 orphan-ratchet guard: --instance-dir ${opts.instanceDir} does not exist \u2014 cannot tell whether it carries unsanctioned files, and that is not the same as a clean pass.`
+    );
+    process.exit(2);
+    return;
+  }
+  const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const theirsDir = opts.theirsDir ?? root;
+  const instanceDir = opts.instanceDir ?? theirsDir;
+  const baseDir = opts.baseDir ?? theirsDir;
+  const label = opts.label ?? (basename2(instanceDir) || instanceDir);
+  if (instanceDir === theirsDir && baseDir === theirsDir) {
+    console.log(
+      "self-check mode: --instance-dir was not given, so it defaulted to --theirs-dir (this repo's own root) alongside --base-dir \u2014 all three trees are the same, so this run can only ever find zero orphans by construction. See this script's doc comment. Pass a real instance tree with --instance-dir for a check that can actually find something. biffo-template#1714."
+    );
+  }
+  const manifest = readCoreManifest(theirsDir);
+  const plan = await planCoreUpgrade({ baseDir, oursDir: instanceDir, theirsDir, manifest });
+  const baseline = readOrphanBaseline(instanceDir);
+  const ratchet = checkOrphanRatchet(plan.orphaned.length, baseline);
+  console.log(
+    `examined ${label}: ${plan.orphaned.length} unsanctioned file(s) under a template-owned path (baseline ${baseline === null ? "none recorded" : String(baseline.count)}), against template tree ${theirsDir}`
+  );
+  if (plan.orphaned.length === 0) {
+    console.log(`\u2713 orphan-ratchet guard (${label}): no unsanctioned files`);
+    return;
+  }
+  console.error(
+    `${ratchet.increased ? "\u2717" : "\xB7"} orphan-ratchet guard (${label}): ${String(plan.orphaned.length)} unsanctioned instance file(s) under a template-owned path (#1026)${ratchet.increased ? " \u2014 INCREASED over the recorded baseline" : ""}:`
+  );
+  for (const entry of plan.orphaned) reportOrphan(entry, manifest);
+  if (ratchet.increased) {
+    console.error(
+      `
+baseline was ${String(ratchet.baseline)}, now ${String(ratchet.count)}. See biffo-template#1026 and biffo-template#1714.`
+    );
+    process.exit(1);
+  }
+}
+
 // src/scripts/check-pipe-trap.ts
 import { readFileSync as readFileSync37, readdirSync as readdirSync22 } from "fs";
 import { join as join52, relative as relative9 } from "path";
@@ -12737,16 +12835,16 @@ async function runPluginAllowlistConventionCheck() {
 }
 
 // src/scripts/check-plugin-collisions.ts
-import { existsSync as existsSync47 } from "fs";
+import { existsSync as existsSync48 } from "fs";
 import { join as join55 } from "path";
 
 // src/lib/plugin-collision-guard.ts
-import { existsSync as existsSync46, readdirSync as readdirSync23, statSync as statSync14 } from "fs";
+import { existsSync as existsSync47, readdirSync as readdirSync23, statSync as statSync14 } from "fs";
 import { join as join54 } 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 (!existsSync46(dir)) return [];
+  if (!existsSync47(dir)) return [];
   return readdirSync23(dir).filter((entry) => {
     if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) return false;
     try {
@@ -12757,12 +12855,12 @@ function subdirectories(dir) {
   });
 }
 function regularPackagesOf(pluginDir2) {
-  return subdirectories(pluginDir2).filter((name) => existsSync46(join54(pluginDir2, name, "__init__.py"))).sort();
+  return subdirectories(pluginDir2).filter((name) => existsSync47(join54(pluginDir2, name, "__init__.py"))).sort();
 }
 function bareTestModulesOf(pluginDir2) {
   const testsDir = join54(pluginDir2, "tests");
-  if (!existsSync46(testsDir)) return [];
-  if (existsSync46(join54(testsDir, "__init__.py"))) return [];
+  if (!existsSync47(testsDir)) return [];
+  if (existsSync47(join54(testsDir, "__init__.py"))) return [];
   return readdirSync23(testsDir).filter((f) => f.endsWith(".py") && !PYTEST_SPECIAL.has(f)).sort();
 }
 function findCollisions(servicesDir, pluginDirs) {
@@ -12810,7 +12908,7 @@ function formatCollisions(collisions) {
 async function runPluginCollisionCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   const servicesDir = join55(root, "services");
-  if (!existsSync47(servicesDir)) {
+  if (!existsSync48(servicesDir)) {
     console.log("\u2713 plugin collision guard: no services/ directory \u2014 nothing to compare");
     return;
   }
@@ -12827,7 +12925,7 @@ async function runPluginCollisionCheck() {
 }
 
 // src/lib/plugin-terraform-guard.ts
-import { existsSync as existsSync48, readFileSync as readFileSync39, readdirSync as readdirSync24 } from "fs";
+import { existsSync as existsSync49, readFileSync as readFileSync39, readdirSync as readdirSync24 } from "fs";
 import { dirname as dirname10, join as join56, relative as relative10, sep as sep4 } from "path";
 var SKIP_DIRS3 = /* @__PURE__ */ new Set(["node_modules", ".git", ".worktrees", "dist", ".venv", "__pycache__"]);
 var PLUGIN_MANIFEST_FILE2 = "biffo.plugin.json";
@@ -12870,14 +12968,14 @@ function readSubscriptions(absManifestPath) {
 }
 function checkPluginTerraform(root) {
   const violations = [];
-  const coreManifest = existsSync48(join56(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
+  const coreManifest = existsSync49(join56(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
   for (const manifest of findPluginManifests(root)) {
     if (coreManifest && !isTemplateOwned(manifest, coreManifest)) continue;
     const absManifest = join56(root, manifest);
     const subscriptions = readSubscriptions(absManifest);
     if (subscriptions === null) continue;
     const pluginDir2 = dirname10(absManifest);
-    if (existsSync48(join56(pluginDir2, "terraform"))) continue;
+    if (existsSync49(join56(pluginDir2, "terraform"))) continue;
     const relPluginDir = relative10(root, pluginDir2).split(sep4).join("/");
     violations.push({
       manifest,
@@ -12908,11 +13006,11 @@ async function runPluginTerraformCheck() {
 }
 
 // src/scripts/check-plugin-tool-supply.ts
-import { existsSync as existsSync50 } from "fs";
+import { existsSync as existsSync51 } from "fs";
 import { join as join58 } from "path";
 
 // src/lib/plugin-tool-supply-audit.ts
-import { existsSync as existsSync49, readFileSync as readFileSync40, readdirSync as readdirSync25, statSync as statSync15 } from "fs";
+import { existsSync as existsSync50, readFileSync as readFileSync40, readdirSync as readdirSync25, statSync as statSync15 } from "fs";
 import { join as join57 } from "path";
 
 // src/lib/openrouter-model-snapshot.ts
@@ -13646,8 +13744,8 @@ function auditDeclaredModelIds(repoRoot, options = {}) {
   const now = options.now ?? /* @__PURE__ */ new Date();
   const configPath = join57(repoRoot, CONFIG_PY_PATH);
   const orchestrationPath = join57(repoRoot, ORCHESTRATION_SCHEMA_PATH);
-  const configMissing = !existsSync49(configPath);
-  const orchestrationSchemaMissing = !existsSync49(orchestrationPath);
+  const configMissing = !existsSync50(configPath);
+  const orchestrationSchemaMissing = !existsSync50(orchestrationPath);
   const knownSet = new Set(knownModelIds);
   const snapshotEmpty = knownModelIds.length === 0;
   const snapshotStale = isSnapshotStale(snapshotFetchedAt, now);
@@ -13864,7 +13962,7 @@ async function runPluginToolSupplyCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   let allOk = true;
   const pluginsRoot = join58(root, "services", "_plugins");
-  if (!existsSync50(pluginsRoot)) {
+  if (!existsSync51(pluginsRoot)) {
     console.log("\u2713 plugin tool-supply guard: no services/_plugins/ \u2014 nothing to audit");
   } else {
     const report = auditPluginToolSupply(pluginsRoot);
@@ -13895,7 +13993,7 @@ async function runPluginToolSupplyCheck() {
     }
   }
   const servicesApiRoot = join58(root, "services", "api");
-  if (!existsSync50(servicesApiRoot)) {
+  if (!existsSync51(servicesApiRoot)) {
     console.log("\u2713 plugin model-id guard: no services/api/ \u2014 nothing to audit");
   } else {
     const modelReport = auditDeclaredModelIds(root);
@@ -14272,7 +14370,7 @@ async function runSharedFileReductionCheck(args) {
 }
 
 // src/scripts/check-skeleton-drift.ts
-import { existsSync as existsSync51, readdirSync as readdirSync27 } from "fs";
+import { existsSync as existsSync52, readdirSync as readdirSync27 } from "fs";
 import { join as join60 } from "path";
 
 // src/lib/skeleton-drift-guard.ts
@@ -14399,7 +14497,7 @@ function discoverSkeletons(root) {
   } catch {
     return [];
   }
-  return entries.filter((name) => existsSync51(join60(skeletonsDir, name, ".github", "workflows", "ci.yml"))).sort();
+  return entries.filter((name) => existsSync52(join60(skeletonsDir, name, ".github", "workflows", "ci.yml"))).sort();
 }
 async function runSkeletonDriftCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
@@ -14408,7 +14506,7 @@ async function runSkeletonDriftCheck() {
   for (const name of skeletons) {
     const skeletonRoot = join60(root, "_skeletons", name);
     filesConsidered += findWorkflowFiles(skeletonRoot).length;
-    if (existsSync51(join60(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
+    if (existsSync52(join60(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
       filesConsidered += 1;
     }
   }
@@ -14458,7 +14556,7 @@ async function runTerraformInputCheck() {
 
 // src/commands/check.ts
 var checkCommand = new Command24("check").description(
-  "Repo guards (ownership, release subject, plugin terraform, plugin collisions, eventbridge-log-permissions, plugin-tool-supply, core-direct-paths, instance-adoption, cognito-invite-template, lambda-output, pipe-trap, codeql-suppression, skeleton-drift, terraform-input, plugin-allowlist-convention, migration-body-change) run in CI and git hooks, plus out-of-band audits (branch protection, plugin-staleness)"
+  "Repo guards (ownership, release subject, plugin terraform, plugin collisions, eventbridge-log-permissions, plugin-tool-supply, core-direct-paths, instance-adoption, orphan-ratchet, cognito-invite-template, lambda-output, pipe-trap, codeql-suppression, skeleton-drift, terraform-input, plugin-allowlist-convention, migration-body-change) run in CI and git hooks, plus out-of-band audits (branch protection, plugin-staleness)"
 );
 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"));
@@ -14521,6 +14619,22 @@ checkCommand.command("instance-adoption").description(
 ).action(async (opts) => {
   await runInstanceAdoptionCheck(opts);
 });
+checkCommand.command("orphan-ratchet").description(
+  "Refuse an instance-written file under a template-owned path with no sanctioned carve-out (#1026), reusing planCoreUpgrade's classify() and checkOrphanRatchet \u2014 previously reachable only from inside `biffo core upgrade`, so drift was discovered only ~90 core versions later by the upgrade it blocks (#1714). --instance-dir defaults to a SELF-CHECK (this repo's own tree, unlike instance-adoption above) that can only ever report zero \u2014 see the entrypoint's own doc comment for why that default exists anyway. Pass a real instance checkout for a check that can actually find something."
+).option(
+  "--instance-dir <dir>",
+  "The real instance tree to check (oursDir). Defaults to a self-check of this repo's own root, which always reports 0 orphans (#1714) \u2014 pass a real instance checkout for a meaningful result"
+).option(
+  "--theirs-dir <dir>",
+  "Template tree that defines ownership (theirsDir); defaults to this repo root"
+).option(
+  "--base-dir <dir>",
+  "Merge-base template tree (baseDir) \u2014 the template at the instance's CURRENT core version; defaults to --theirs-dir, which is only correct when the instance is already on the latest version"
+).option("--label <name>", "Label for the report; defaults to the basename of --instance-dir").action(
+  async (opts) => {
+    await runOrphanRatchetCheck(opts);
+  }
+);
 checkCommand.command("cognito-invite-template").description(
   "Refuse a Cognito invite_message_template missing a required member or placeholder (#356) \u2014 terraform validate is silent on this, so a fresh deploy fails on its first apply"
 ).action(async () => {
@@ -14587,7 +14701,7 @@ function rawArgsAfter(subcommand) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync52, readFileSync as readFileSync44 } from "fs";
+import { existsSync as existsSync53, readFileSync as readFileSync44 } from "fs";
 import { join as join61, resolve as resolve20 } from "path";
 import chalk21 from "chalk";
 import { Command as Command25 } from "commander";
@@ -14768,7 +14882,7 @@ async function runDoctor(options, deps = { git: new GitAdapter() }) {
 }
 function readLocalCoreVersion(cwd) {
   const path = join61(cwd, INSTANCE_CORE_FILE);
-  if (!existsSync52(path)) return null;
+  if (!existsSync53(path)) return null;
   try {
     return extractVersionField(readFileSync44(path, "utf8"));
   } catch {
@@ -14791,7 +14905,7 @@ function extractVersionField(contents) {
 }
 function readFossil(cwd) {
   const path = join61(cwd, CORE_VERSION_FILE);
-  if (!existsSync52(path)) return null;
+  if (!existsSync53(path)) return null;
   try {
     const value = readFileSync44(path, "utf8").trim();
     return value === "" ? null : value;
@@ -15242,13 +15356,13 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 import { Command as Command27 } from "commander";
 
 // src/lib/packaged-scripts.ts
-import { existsSync as existsSync53 } from "fs";
+import { existsSync as existsSync54 } from "fs";
 import { dirname as dirname11, join as join62 } from "path";
 function findPackagedScript(startDir, relativePath) {
   let dir = startDir;
   for (; ; ) {
     const candidate = join62(dir, relativePath);
-    if (existsSync53(candidate)) return candidate;
+    if (existsSync54(candidate)) return candidate;
     const parent = dirname11(dir);
     if (parent === dir) return null;
     dir = parent;

package/package.json

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

package/scripts/claim.sh

@@ -243,6 +243,21 @@ while [ $# -gt 0 ]; do
       shift 2
       ;;
     -h | --help) usage ;;
+    -*)
+      # An unrecognized flag must never fall into the catch-all below (#1741).
+      # It used to: a token that starts with `-` but matches none of the
+      # cases above fell straight into `*) ISSUE="$1"; shift ;;`, so
+      # `--bogus` silently became the "issue number" -- corrupting ISSUE with
+      # flag text instead of the real positional argument -- and the script
+      # went on to fail the `[!0-9]*` check below with "give an issue
+      # number", a message that describes the SYMPTOM (ISSUE is not
+      # numeric) and hides the actual CAUSE (an unsupported flag was typed).
+      # Refusing here, at the point the flag is actually unrecognized, says
+      # what is really wrong instead of a confusing knock-on error.
+      echo "${RED}claim: unrecognized flag '$1'${OFF}" >&2
+      echo "${DIM}  Known flags: -R/--repo, --check, --as, --release, --guard, -h/--help.${OFF}" >&2
+      exit 2
+      ;;
     *)
       ISSUE="$1"
       shift