@botbuddy/cli 1.5.1 → 1.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/botbuddy-release-repair.json

@@ -0,0 +1 @@
+{"schema_version":1,"source_version":"1.5.1","source_identity":"1bc59a77cac3a2df9a24764a6ae8c4df3fc9e002701396f6a97dd2dfa84589c6"}

package/src/publish-equal.mjs

@@ -4,14 +4,15 @@
 //
 // Used by .github/workflows/publish-cli-package.yml when the version already
 // exists on npm: an equivalent package is a safe idempotent skip; any drift
-// means cli/ changed without a version bump and must fail loudly so the change
-// cannot merge green while staying unpublished.
+// triggers a fresh release-time version allocation so the change cannot merge
+// green while staying unpublished.
 //
 // The comparison excludes ONLY npm-injected manifest fields (notably gitHead,
 // which npm stamps into the tarball's package.json from the publishing commit).
 // Every other manifest field (bin, files, engines, …) and every shipped file
 // is compared, so a genuine metadata change still counts as drift.
 
+import { createHash } from "node:crypto";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 
@@ -22,6 +23,7 @@ import { join, relative } from "node:path";
 // included, is compared. Key ORDER is still canonicalised so incidental
 // ordering never reads as drift.
 const NPM_INJECTED_KEYS = [];
+const RELEASE_REPAIR_RECEIPT = "src/botbuddy-release-repair.json";
 
 // Deep, key-sorted canonical form so incidental key ordering never reads as a
 // difference.
@@ -112,9 +114,62 @@ export function isPrerelease(v) {
   return parseSemver(v).pre.length > 0;
 }
 
-export function normalizeManifest(json) {
+function compareMain(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+function incrementPatch(main) {
+  if (!Number.isSafeInteger(main[2]) || main[2] === Number.MAX_SAFE_INTEGER) {
+    throw new Error(`cannot allocate a patch version after ${main.join(".")}`);
+  }
+  return [main[0], main[1], main[2] + 1];
+}
+
+// Allocate a release-only version once a tarball drifted from an immutable npm
+// version. Stable releases advance from the greatest published stable version,
+// preserving the established latest-tag ordering. Prereleases advance past the
+// greatest published core version and retain a prerelease component, so they
+// cannot accidentally become latest while still being greater than `next`.
+// `unique` is a monotonic CI-run identity, not a timestamp, and is only used
+// after a drift is confirmed.
+export function nextUnpublishedVersion(local, publishedVersions, unique = "release") {
+  const parsedLocal = parseSemver(local);
+  if (!Array.isArray(publishedVersions)) throw new Error("published versions must be an array");
+
+  let greatestStable = parsedLocal.main;
+  let greatestCore = parsedLocal.main;
+  for (const version of publishedVersions) {
+    const parsed = parseSemver(version);
+    if (compareMain(parsed.main, greatestCore) > 0) greatestCore = parsed.main;
+    if (parsed.pre.length === 0 && compareMain(parsed.main, greatestStable) > 0) {
+      greatestStable = parsed.main;
+    }
+  }
+
+  if (parsedLocal.pre.length === 0) return incrementPatch(greatestStable).join(".");
+  if (!/^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/.test(unique)) {
+    throw new Error(`not a prerelease identifier: ${unique}`);
+  }
+  return `${incrementPatch(greatestCore).join(".")}-release.${unique}`;
+}
+
+// Kept as the narrow public helper for the stable publish path and for
+// straightforward unit fixtures. The workflow uses nextUnpublishedVersion so
+// a drifted prerelease remains safely tagged as a prerelease too.
+export function nextUnpublishedStableVersion(local, publishedVersions) {
+  parseStable(local);
+  const next = nextUnpublishedVersion(local, publishedVersions);
+  parseStable(next);
+  return next;
+}
+
+export function normalizeManifest(json, { ignoreVersion = false } = {}) {
   const m = JSON.parse(json);
   for (const k of NPM_INJECTED_KEYS) delete m[k];
+  if (ignoreVersion) delete m.version;
   return JSON.stringify(canon(m));
 }
 
@@ -133,7 +188,7 @@ function walkRelative(root) {
 }
 
 // Compare two extracted `package/` directories. Returns { equal, reason }.
-export function packagesEquivalent(localDir, pubDir) {
+export function packagesEquivalent(localDir, pubDir, { ignoreVersion = false } = {}) {
   const localFiles = walkRelative(localDir);
   const pubFiles = walkRelative(pubDir);
   if (localFiles.join("\n") !== pubFiles.join("\n")) {
@@ -146,7 +201,7 @@ export function packagesEquivalent(localDir, pubDir) {
     const a = readFileSync(join(localDir, rel));
     const b = readFileSync(join(pubDir, rel));
     if (rel === "package.json") {
-      if (normalizeManifest(a.toString("utf8")) !== normalizeManifest(b.toString("utf8"))) {
+      if (normalizeManifest(a.toString("utf8"), { ignoreVersion }) !== normalizeManifest(b.toString("utf8"), { ignoreVersion })) {
         return { equal: false, reason: "package.json differs beyond npm-injected fields (e.g. bin/files/engines)" };
       }
     } else if (!a.equals(b)) {
@@ -164,8 +219,47 @@ export function packagesEquivalent(localDir, pubDir) {
   return { equal: true };
 }
 
+// A release-time repair carries a shipped receipt. It prevents an intentional
+// restore of any historical tarball from being mistaken for an earlier repair
+// of this exact source package. Versions and the receipt itself are excluded
+// so the identity represents only the source package being repaired.
+export function releaseRepairIdentity(packageDir) {
+  const hash = createHash("sha256");
+  for (const rel of walkRelative(packageDir)) {
+    if (rel === RELEASE_REPAIR_RECEIPT) continue;
+    const path = join(packageDir, rel);
+    const content = rel === "package.json"
+      ? normalizeManifest(readFileSync(path, "utf8"), { ignoreVersion: true })
+      : readFileSync(path);
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(String(statSync(path).mode & 0o777));
+    hash.update("\0");
+    hash.update(content);
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+// True only when `candidateDir` bears the receipt emitted by this workflow for
+// the exact local source. A content-only historical match is deliberately not
+// enough: it must still publish so the restored artifact becomes latest.
+export function matchesReleaseRepair(localDir, candidateDir) {
+  try {
+    const receipt = JSON.parse(readFileSync(join(candidateDir, RELEASE_REPAIR_RECEIPT), "utf8"));
+    const localVersion = JSON.parse(readFileSync(join(localDir, "package.json"), "utf8")).version;
+    const sourceIdentity = releaseRepairIdentity(localDir);
+    return receipt.schema_version === 1
+      && receipt.source_version === localVersion
+      && receipt.source_identity === sourceIdentity
+      && releaseRepairIdentity(candidateDir) === sourceIdentity;
+  } catch {
+    return false;
+  }
+}
+
 // CLI: `node cli-publish-equal.mjs <localPackageDir> <publishedPackageDir>`.
-// Exit 0 = equivalent (safe skip); exit 3 = drift (must fail the publish job).
+// Exit 0 = equivalent (safe skip); exit 3 = drift (must allocate a new version).
 if (import.meta.url === `file://${process.argv[1]}`) {
   const args = process.argv.slice(2);
   // `--gt <next> <current>`: exit 0 iff stable `next` > stable `current`.
@@ -192,6 +286,60 @@ if (import.meta.url === `file://${process.argv[1]}`) {
       process.exit(2);
     }
   }
+  // `--next-version <local> <unique>` reads the registry's JSON versions list
+  // on stdin and prints an absent semver suitable for a drifted package.
+  if (args[0] === "--next-version") {
+    const [, local, unique] = args;
+    try {
+      const input = JSON.parse(readFileSync(0, "utf8"));
+      const versions = Array.isArray(input) ? input : [input];
+      console.log(nextUnpublishedVersion(local, versions, unique));
+      process.exit(0);
+    } catch (err) {
+      console.error(String(err.message ?? err));
+      process.exit(2);
+    }
+  }
+  if (args[0] === "--repair-identity") {
+    const [, packageDir] = args;
+    if (!packageDir) {
+      console.error("usage: publish-equal.mjs --repair-identity <packageDir>");
+      process.exit(2);
+    }
+    try {
+      console.log(releaseRepairIdentity(packageDir));
+      process.exit(0);
+    } catch (err) {
+      console.error(String(err.message ?? err));
+      process.exit(2);
+    }
+  }
+  if (args[0] === "--is-release-repair") {
+    const [, localDir, candidateDir] = args;
+    if (!localDir || !candidateDir) {
+      console.error("usage: publish-equal.mjs --is-release-repair <localPackageDir> <candidatePackageDir>");
+      process.exit(2);
+    }
+    process.exit(matchesReleaseRepair(localDir, candidateDir) ? 0 : 3);
+  }
+  // `--ignore-version <localPackageDir> <publishedPackageDir>` compares the
+  // shipped package while disregarding only package.json's version. The
+  // workflow uses this after confirmed drift to recognize an earlier
+  // release-time repair of the same source tarball on a rerun.
+  if (args[0] === "--ignore-version") {
+    const [, localDir, pubDir] = args;
+    if (!localDir || !pubDir) {
+      console.error("usage: publish-equal.mjs --ignore-version <localPackageDir> <publishedPackageDir>");
+      process.exit(2);
+    }
+    const result = packagesEquivalent(localDir, pubDir, { ignoreVersion: true });
+    if (result.equal) {
+      console.log("identical except package version");
+      process.exit(0);
+    }
+    console.error("drift: " + result.reason);
+    process.exit(3);
+  }
   const [localDir, pubDir] = args;
   if (!localDir || !pubDir) {
     console.error("usage: publish-equal.mjs <localPackageDir> <publishedPackageDir> | --gt <next> <current>");

package/src/wait-core.mjs

@@ -217,6 +217,17 @@ const VALIDATORS = {
     if (!String(p.sha).trim()) throw new Error("ci sha must be non-empty");
     return { repo, scope: "sha", sha: String(p.sha).trim(), pr: p.pr != null ? String(p.pr).trim() : null };
   },
+  "staging-green"(p) {
+    const repo = p.repo != null ? String(p.repo).trim() : null;
+    if (!repo || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+      throw new Error("staging-green needs repo=<owner/repo>");
+    }
+    const extras = Object.keys(p).filter((key) => key !== "repo");
+    if (extras.length > 0) {
+      throw new Error("staging-green accepts only repo=<owner/repo>");
+    }
+    return { repo };
+  },
   // BOT-1247 — unblocked: wake when a ticket's LAST open blocker clears (its
   // open-blocker count transitions >0 → 0). Level-triggered: a ticket already
   // unblocked (or never blocked) at registration is granted immediately with
@@ -643,6 +654,18 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       return signal.subject_key === `${params.repo}#${params.pr}` ||
         (signal.payload?.pr_number != null && String(signal.payload.pr_number) === params.pr);
     }
+    case "staging-green": {
+      if (signal.signal_type !== "staging_gate" || signal.subject_key !== params.repo) return false;
+      const payload = signal.payload ?? {};
+      // A staging_gate signal is also used for manual overrides and red/freeze
+      // transitions. This public condition is deliberately narrower: only the
+      // webhook's evidenced, automatic recovery may wake a delivery session.
+      return (payload.reason === "green_recovery" || payload.reason === "already_green") &&
+        payload.source === "automatic_workflow_recovery" &&
+        payload.verified === true &&
+        payload.gate_open === false &&
+        payload.operational_status === "healthy";
+    }
     case "unblocked": {
       // Wakes on the ticket_unblocked spine signal for this ticket (the server emits both
       // the genuine >0→0 transition and the level-triggered `already_unblocked` echo).

package/src/wait.mjs

@@ -78,6 +78,9 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       a PR's CI reaching a terminal conclusion (owner-scoped);
                                       GitHub Actions or an external check_suite provider.
                                       A repo with no CI feed is rejected (no_signal_source).
+  staging-green:repo=<owner/repo>    verified automatic recovery of an enabled staging gate.
+                                      Wakes only after a complete non-vacuous workflow success;
+                                      manual resolutions, overrides, skipped, and neutral runs do not match.
   event:type=<signal_type>[,subject=<key>]
                                       raw signal-spine match (escape hatch)
 
@@ -211,6 +214,7 @@ async function registerWait(opts, conditions, deadlineIso) {
       "wait_tenant_unresolved",
       "wait_cross_tenant",
       "wait_tenant_mismatch",
+      "staging_repository_unconfigured",
       // BOT-1259: a `linear` condition set spanning multiple workspaces can't bind one
       // tenant; the server rejects it (register one wait per workspace) — a hard stop, not
       // a transient error, so don't fall back to an untracked live-only wait.