@botbuddy/cli 1.67.0 → 1.68.0

package/src/status-band-relay.mjs

@@ -0,0 +1,104 @@
+// BOT-3135 / BOT-3152. The band's relay child (`bb status-band relay`): arms ONE
+// `bb wait` on the band's own subjects and reports how it ended. It runs this
+// installed package's own `wait` through the node that runs it — no PATH lookup,
+// no shell, no repo checkout — and never reads BB itself.
+import { execFile as nodeExecFile } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+// Under the 10-minute ceiling a mod gives a one-shot child, so a stuck
+// relay can never outlive one arm; the mod re-arms from the cursor.
+export const WAIT_TIMEOUT_SECONDS = 570;
+const SHORT_TIMEOUT_REASON =
+  "bb-status band relay: re-armed from its cursor every 570 s by the mod";
+const KEY = "(?:BOT|ENT)-[1-9]\\d{0,5}";
+const REPO = "[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}";
+// BOT-3136: the epic row wakes on its Linear project.
+const PROJECT = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+// BOT-3152 AC-2: any staging incident of the session's tenant opening or closing.
+const STAGING = "event:type=staging_incident";
+const CONDITION = new RegExp(
+  `^(?:linear:issue=${KEY}|unblocked:${KEY}|pr-(?:state|review):repo=${REPO},pr=[1-9]\\d{0,6}|event:type=linear_project,subject=${PROJECT}|${STAGING})$`,
+);
+const CURSOR = /^\d{1,16}$/;
+// The band's largest list: 5 tickets, 5 PRs (state + review), blockers, epic, staging.
+const MAX_CONDITIONS = 18;
+export const CLI_ENTRY = join(resolve(dirname(fileURLToPath(import.meta.url)), ".."), "bin", "botbuddy.mjs");
+
+function invalid() {
+  throw new Error("invalid_arguments");
+}
+
+export function relayArgs(argv) {
+  const conditions = [];
+  let since = null;
+  for (let i = 0; i < argv.length; i += 2) {
+    const [flag, value] = [argv[i], argv[i + 1]];
+    if (typeof value !== "string") invalid();
+    if (flag === "--cond" && CONDITION.test(value) && !value.includes("..") && !conditions.includes(value)) conditions.push(value);
+    else if (flag === "--since" && since === null && CURSOR.test(value)) since = value;
+    else invalid();
+  }
+  if (conditions.length < 1 || conditions.length > MAX_CONDITIONS) invalid();
+  return { conditions, since };
+}
+
+// The receipt is bb's last JSON line; only the fields the mod needs leave here.
+export function summarize(exit, stdout) {
+  let receipt = null;
+  for (const line of String(stdout).trim().split("\n").reverse()) {
+    try {
+      receipt = JSON.parse(line);
+      break;
+    } catch {
+      /* banner or log line */
+    }
+  }
+  const cursor = receipt?.next_cursor == null ? null : String(receipt.next_cursor);
+  const id = receipt?.wait_session_id;
+  return {
+    exit,
+    outcome: typeof receipt?.outcome === "string" && /^[a-z_]{1,40}$/.test(receipt.outcome) ? receipt.outcome : "error",
+    wait_id: typeof id === "string" && /^[0-9a-z-]{1,64}$/i.test(id) ? id : null,
+    next_cursor: cursor && CURSOR.test(cursor) ? cursor : null,
+  };
+}
+
+export async function runRelay(
+  argv,
+  { execPath = process.execPath, cliEntry = CLI_ENTRY, execFile = promisify(nodeExecFile), cwd } = {},
+) {
+  const { conditions, since } = relayArgs(argv);
+  const args = [
+    cliEntry,
+    "wait",
+    ...conditions,
+    "--timeout",
+    String(WAIT_TIMEOUT_SECONDS),
+    "--allow-short-timeout",
+    SHORT_TIMEOUT_REASON,
+    ...(since ? ["--since", since] : []),
+  ];
+  try {
+    const { stdout } = await execFile(execPath, args, {
+      cwd,
+      maxBuffer: 4 * 1024 * 1024,
+      timeout: (WAIT_TIMEOUT_SECONDS + 25) * 1000,
+    });
+    return summarize(0, stdout);
+  } catch (error) {
+    return summarize(typeof error?.code === "number" ? error.code : 7, error?.stdout ?? "");
+  }
+}
+
+export async function main(argv, { out = process.stdout, cwd = process.cwd() } = {}) {
+  let res;
+  try {
+    res = await runRelay(argv, { cwd });
+  } catch {
+    res = { exit: 4, outcome: "error", error: "invalid_arguments", wait_id: null, next_cursor: null };
+  }
+  out.write(JSON.stringify(res) + "\n");
+  return 0;
+}

package/src/status-band.mjs

@@ -0,0 +1,126 @@
+// BOT-3152: `bb status-band` — the bb-status band's host side, run from the
+// installed CLI (never a repo checkout), and its one-time Claude Code install.
+//
+//   bb status-band read --harness-session-id <uuid> [--ticket-id K[,K…]] [--skip-epic]
+//   bb status-band relay --cond <condition>… [--since <cursor>]
+//   bb status-band install
+//
+// `read` and `relay` print one JSON line for the mod. `install` points the
+// `botbuddy-labs` Claude Code marketplace at the plugin shipped in this package
+// and installs `bb-status` at user scope, so every worktree gets the band.
+import { execFile as nodeExecFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+export const MARKETPLACE = "botbuddy-labs";
+export const PLUGIN = "bb-status";
+const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = resolve(HERE, "..");
+export const MARKETPLACE_DIR = join(PACKAGE_ROOT, "claude-plugin");
+
+const HELP = `bb status-band <read|relay|install>
+
+  read --harness-session-id <uuid> [--ticket-id KEY[,KEY…]] [--skip-epic]
+        One JSON snapshot of this worktree's BB session for the bb-status band.
+  relay --cond <condition>… [--since <cursor>]
+        Arm one bb wait on the band's subjects and print how it ended.
+  install
+        Install the bb-status band into Claude Code once, at user scope, from
+        this installed CLI package. bb setup and bb update run it for you.`;
+
+export async function cmdStatusBand(args, { log = (l) => console.log(l), out = process.stdout } = {}) {
+  const [sub, ...rest] = args;
+  if (sub === "read") {
+    const { main } = await import("./status-band-read.mjs");
+    return main(rest, { out });
+  }
+  if (sub === "relay") {
+    const { main } = await import("./status-band-relay.mjs");
+    return main(rest, { out });
+  }
+  if (sub === "install") {
+    const result = await installStatusBand();
+    log(statusBandLine(result));
+    return result.status === "failed" ? 1 : 0;
+  }
+  log(HELP);
+  return sub === undefined || sub === "--help" || sub === "-h" || sub === "help" ? 0 : 2;
+}
+
+// A plugin served from a repo checkout dies with that checkout (the BOT-3152
+// fragility), so only a package installed under node_modules is offered.
+export function isInstalledPackage(root = PACKAGE_ROOT) {
+  return root.split(sep).includes("node_modules");
+}
+
+async function claudeJson(run, args) {
+  const { stdout } = await run(["plugin", ...args, "--json"]);
+  return JSON.parse(stdout);
+}
+
+/**
+ * Point `botbuddy-labs` at this package's plugin folder and install `bb-status`
+ * at user scope. Idempotent; never throws. Returns { status, … } where status is
+ * installed | updated | unchanged | skipped | failed.
+ */
+export async function installStatusBand({
+  marketplaceDir = MARKETPLACE_DIR,
+  packageRoot = PACKAGE_ROOT,
+  claude = "claude",
+  execFileImpl = promisify(nodeExecFile),
+  readJson = async (p) => JSON.parse(await readFile(p, "utf8")),
+} = {}) {
+  if (!isInstalledPackage(packageRoot)) return { status: "skipped", reason: "not_installed_package" };
+  const run = (args) => execFileImpl(claude, args, { timeout: 60_000, maxBuffer: 4 * 1024 * 1024 });
+  try {
+    await run(["--version"]);
+  } catch {
+    return { status: "skipped", reason: "claude_missing" };
+  }
+  let shipped;
+  try {
+    shipped = (await readJson(join(marketplaceDir, PLUGIN, ".claude-plugin", "plugin.json"))).version;
+  } catch {
+    return { status: "failed", reason: "plugin_missing_from_package" };
+  }
+  try {
+    const markets = await claudeJson(run, ["marketplace", "list"]);
+    const current = Array.isArray(markets) ? markets.find((m) => m?.name === MARKETPLACE) : null;
+    const repointed = Boolean(current) && resolve(String(current.path ?? "")) !== resolve(marketplaceDir);
+    if (repointed) await run(["plugin", "marketplace", "remove", MARKETPLACE]);
+    if (!current || repointed) await run(["plugin", "marketplace", "add", marketplaceDir, "--scope", "user"]);
+    else await run(["plugin", "marketplace", "update", MARKETPLACE]);
+    const plugins = await claudeJson(run, ["list"]);
+    const mine = Array.isArray(plugins) ? plugins.find((p) => p?.id === PLUGIN_ID && p?.scope === "user") : null;
+    if (mine && mine.version === shipped && mine.enabled !== false && !repointed) {
+      return { status: "unchanged", version: shipped };
+    }
+    if (mine && !repointed) await run(["plugin", "update", PLUGIN_ID, "--scope", "user"]);
+    else await run(["plugin", "install", PLUGIN_ID, "--scope", "user"]);
+    if (mine && mine.enabled === false) await run(["plugin", "enable", PLUGIN_ID, "--scope", "user"]);
+    return { status: mine && !repointed ? "updated" : "installed", version: shipped, ...(repointed ? { replaced: String(current.path ?? "") } : {}) };
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error).trim().split("\n")[0].slice(0, 200);
+    return { status: "failed", reason: "claude_plugin_command_failed", detail };
+  }
+}
+
+export function statusBandLine(result) {
+  switch (result?.status) {
+    case "installed":
+      return `bb-status band installed in Claude Code (user scope, v${result.version}); new sessions show it. Run /reload-plugins in open ones.`;
+    case "updated":
+      return `bb-status band updated in Claude Code to v${result.version}; new sessions show it. Run /reload-plugins in open ones.`;
+    case "unchanged":
+      return `bb-status band already installed in Claude Code (v${result.version}).`;
+    case "skipped":
+      return result.reason === "claude_missing"
+        ? "bb-status band skipped: no claude command on PATH."
+        : "bb-status band skipped: this bb runs from a checkout, not an installed package (npm i -g @botbuddy/cli).";
+    default:
+      return `bb-status band could not be installed (${result?.reason ?? "unknown"}${result?.detail ? `: ${result.detail}` : ""}); run bb status-band install to retry.`;
+  }
+}

package/src/update-check.mjs

@@ -144,7 +144,7 @@ export function readInstalledVersion({ npmBin = "npm", shellOpt = {}, probeImpl
 
 // `botbuddy update` waits for npm because the terminal result, rather than the
 // child-process launch, is the only trustworthy confirmation an update worked.
-export function cmdUpdate({ version = VERSION, spawnImpl = spawn, probeImpl = spawnSync, readInstalledVersion: installedVersion = readInstalledVersion, refreshPools = refreshPoolsFromNewPackage, log = (line) => console.log(line), platform = process.platform, stderr = process.stderr } = {}) {
+export function cmdUpdate({ version = VERSION, spawnImpl = spawn, probeImpl = spawnSync, readInstalledVersion: installedVersion = readInstalledVersion, refreshPools = refreshPoolsFromNewPackage, installBand = installBandFromNewPackage, log = (line) => console.log(line), platform = process.platform, stderr = process.stderr } = {}) {
   // BOT-1566 (Codex P1/P2): on Windows npm is the `npm.cmd` shim, and Node
   // cannot spawn a .cmd file shell-free (docs) — run it through a shell on
   // win32 (args are all static constants, so no injection surface) and select
@@ -208,6 +208,11 @@ export function cmdUpdate({ version = VERSION, spawnImpl = spawn, probeImpl = sp
         .catch((error) => {
           try { stderr.write(`botbuddy update: the installed staging pools were not refreshed (${error?.message ?? error}); run bb staging-pool status\n`); } catch { /* ignore */ }
         })
+        // BOT-3152: the new package re-points the bb-status band at itself; never an exit code.
+        .then(() => installBand({ npmBin, shellOpt, probeImpl, log }))
+        .catch((error) => {
+          try { stderr.write(`botbuddy update: the bb-status band was not refreshed (${error?.message ?? error}); run bb status-band install\n`); } catch { /* ignore */ }
+        })
         .finally(() => resolve(0));
     });
   });
@@ -299,6 +304,15 @@ export async function refreshInstalledPools({
   return results;
 }
 
+// BOT-3152: run the NEW package's `status-band install` (this process is the old
+// one), so Claude Code's bb-status band and its marketplace match the update.
+export async function installBandFromNewPackage({ npmBin, shellOpt, probeImpl, log, nodeBin = process.execPath, execFileImpl = promisify(execFile) }) {
+  const root = readNpmGlobalRoot({ npmBin, shellOpt, probeImpl });
+  const { stdout } = await execFileImpl(nodeBin, [join(root, "@botbuddy", "cli", "bin", "botbuddy.mjs"), "status-band", "install"], { timeout: 180_000, maxBuffer: 1024 * 1024 });
+  const line = String(stdout).trim().split("\n").filter(Boolean).pop();
+  if (line) log(line);
+}
+
 // The default for `cmdUpdate`: locate the newly installed package and refresh with it.
 export async function refreshPoolsFromNewPackage({ installedVersion, npmBin, shellOpt, probeImpl, log, stderr }) {
   const root = readNpmGlobalRoot({ npmBin, shellOpt, probeImpl });

package/src/wait-core.mjs

@@ -119,6 +119,9 @@ export const SIGNAL_TYPES = Object.freeze([
   // BOT-3136: one signal per member-issue change of a Linear project (an epic),
   // subject = the project's lower-case UUID. Tenant-primary like linear_issue.
   "linear_project",
+  // BOT-3152: a staging incident of the caller's tenant opening or closing
+  // (subject = owner/repo). The bb-status band's staging banner wakes on it.
+  "staging_incident",
 ]);
 
 const LOCK_SUBTYPES = Object.freeze(["playwright_lane", "vite_port", "backend_port", "supabase_local"]);

package/src/wait.mjs

@@ -255,6 +255,9 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       event:type=linear_project,subject=<Linear project UUID>;
                                       it wakes when any issue in that project changes, joins
                                       or leaves it (the band's epic row, BOT-3136).
+                                      Staging state uses event:type=staging_incident;
+                                      it wakes when one of your tenant's staging incidents
+                                      opens or closes (the band's staging banner, BOT-3152).
 
 OPTIONS
   Review intervention: exact-head Codex waits have a durable one-shot diagnostic.