@botbuddy/cli 1.33.4 → 1.33.6

package/package.json

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

package/src/stack-isolation.mjs

@@ -36,7 +36,9 @@ export const LEASED_STACKS_DIR = ".botbuddy/stacks";
 // therefore gets a contiguous block above all of them, and every block stays a
 // valid TCP port (61000 + 200×20 − 1 = 64999).
 export const LEASED_PORT_BASE = 61000;
-/** Ports reserved per leased stack (the repo declares 10; the rest is headroom). */
+/** Ports reserved per leased stack. botbuddy-web declares 10; a repo that declares
+ * none (Supply Guard) has 7 materialized for it from the Supabase defaults
+ * (BOT-1835). The rest is headroom. */
 export const LEASED_PORT_STRIDE = 20;
 /** Distinct blocks available. Two worktree+slot pairs CAN hash to one block; as
  * with the hermetic/e2e ports that is a loud `supabase start` port-bind failure,
@@ -119,6 +121,115 @@ export function portMapInConfig(toml) {
   return map;
 }
 
+/**
+ * BOT-1835 — every host port the Supabase CLI binds, with the value it uses when
+ * the config names none.
+ *
+ * An UNDECLARED port is not an absent port. The CLI decodes its own embedded
+ * `config.toml` template first and the repo's file on top, so a config that says
+ * nothing about `[studio]` still binds 54323 — the same 54323 every other stack
+ * on the machine falls back to. BOT-1798 rewrote only the ports a repo DECLARED,
+ * which is why botbuddy-web's leases landed on 61xxx while Supply Guard's — whose
+ * `supabase/config.toml` is one `project_id` line — kept the whole 543xx default
+ * block and collided with the SG shared stack and with each other.
+ *
+ * `bindsWhenUnset: false` means the CLI publishes that port only when the config
+ * names one (inbucket's smtp/pop3 ports), so such a service is remapped when it
+ * IS declared and never newly exposed when it is not. Its documented default
+ * still belongs in the avoid-set: a config that names 54325 collides with every
+ * other config that names 54325.
+ *
+ * `sections` lists the spellings of one service, canonical first: 2.116 renamed
+ * `[inbucket]` to `[local_smtp]` and still accepts the old name. The canonical
+ * entry is the one materialization CREATES when a config names none of them —
+ * `[inbucket]` deliberately, because every CLI in the field understands it
+ * (a version that only knows `[local_smtp]` would ignore an unknown section and
+ * silently bind the default, which is the bug).
+ *
+ * `[realtime]` is NOT here: the CLI publishes no host port for it (its section
+ * has `enabled`/`ip_version` only). A `[realtime] port` a repo declares anyway is
+ * still remapped by the generic declared-port pass below.
+ */
+export const SUPABASE_SERVICE_PORTS = Object.freeze([
+  { service: "api", label: "api gateway", sections: ["api"], key: "port", defaultPort: 54321, defaultEnabled: true },
+  { service: "db", label: "database", sections: ["db"], key: "port", defaultPort: 54322, defaultEnabled: true },
+  { service: "db-shadow", label: "shadow database", sections: ["db"], key: "shadow_port", defaultPort: 54320, defaultEnabled: true },
+  { service: "pooler", label: "connection pooler", sections: ["db.pooler"], key: "port", defaultPort: 54329, defaultEnabled: false },
+  { service: "studio", label: "studio", sections: ["studio"], key: "port", defaultPort: 54323, defaultEnabled: true },
+  { service: "mail", label: "mail testing UI", sections: ["inbucket", "local_smtp", "mailpit"], key: "port", defaultPort: 54324, defaultEnabled: true },
+  { service: "mail-smtp", label: "mail SMTP", sections: ["inbucket", "local_smtp", "mailpit"], key: "smtp_port", defaultPort: 54325, defaultEnabled: true, bindsWhenUnset: false },
+  { service: "mail-pop3", label: "mail POP3", sections: ["inbucket", "local_smtp", "mailpit"], key: "pop3_port", defaultPort: 54326, defaultEnabled: true, bindsWhenUnset: false },
+  { service: "analytics", label: "analytics", sections: ["analytics"], key: "port", defaultPort: 54327, defaultEnabled: true },
+  { service: "edge-inspector", label: "edge runtime inspector", sections: ["edge_runtime"], key: "inspector_port", defaultPort: 8083, defaultEnabled: true },
+].map(Object.freeze));
+
+/** Every port value the Supabase CLI would pick on its own — the set a leased
+ * stack's ports must avoid entirely, whichever repo it was materialized from. */
+export const SUPABASE_DEFAULT_PORTS = Object.freeze(
+  new Set(SUPABASE_SERVICE_PORTS.map((s) => s.defaultPort).filter((p) => p > 0)),
+);
+
+/** `[section] enabled = true|false` as a map, for the sections that declare it.
+ * Comments are not configuration; a value the CLI would not accept is ignored so
+ * the caller falls back to the documented default. */
+function enabledFlagsInConfig(toml) {
+  const flags = new Map();
+  let section = "";
+  for (const raw of String(toml).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("#")) continue;
+    const sec = /^\[([^\]]+)\]/.exec(line);
+    if (sec) { section = sec[1].trim(); continue; }
+    const dotted = /^([A-Za-z0-9_.]+)\.enabled\s*=\s*(true|false)\b/.exec(line);
+    if (dotted) { if (!flags.has(dotted[1])) flags.set(dotted[1], dotted[2] === "true"); continue; }
+    if (!section) continue;
+    const m = /^enabled\s*=\s*(true|false)\b/.exec(line);
+    if (m && !flags.has(section)) flags.set(section, m[1] === "true");
+  }
+  return flags;
+}
+
+/**
+ * What the Supabase CLI would actually do with `configText`, per service: which
+ * section spells it, whether the config declares its port, whether the CLI binds
+ * it at all, and the port it would end up using (`effectivePort` — declared, or
+ * the CLI's own default). This is the view BOTH the materializer (which ports
+ * must be made explicit) and the isolation assertion (which ports must differ
+ * from the default and from the shared stack's) are written against.
+ */
+export function supabaseServicePortState(configText) {
+  const ports = portMapInConfig(configText);
+  const flags = enabledFlagsInConfig(configText);
+  return SUPABASE_SERVICE_PORTS.map((svc) => {
+    const declaredSection = svc.sections.find((s) => ports.has(`${s}.${svc.key}`)) ?? null;
+    // A service is spelled by whichever of its aliases the config already uses —
+    // for its port, for any of its other ports, or for its `enabled` flag — so a
+    // `[local_smtp]` repo never gets an `[inbucket]` section appended beside it.
+    const usedSection = declaredSection
+      ?? svc.sections.find((s) => SUPABASE_SERVICE_PORTS.some((o) => o.service !== svc.service && o.sections.includes(s) && ports.has(`${s}.${o.key}`)))
+      ?? svc.sections.find((s) => flags.has(s))
+      ?? svc.sections[0];
+    const enabledSection = svc.sections.find((s) => flags.has(s));
+    const enabled = enabledSection === undefined ? svc.defaultEnabled : flags.get(enabledSection);
+    const declaredPort = declaredSection === null ? null : Number(ports.get(`${declaredSection}.${svc.key}`));
+    const fallback = svc.bindsWhenUnset === false ? null : svc.defaultPort;
+    const effectivePort = !enabled ? null : (declaredPort ?? fallback);
+    return {
+      service: svc.service,
+      label: svc.label,
+      key: svc.key,
+      defaultPort: svc.defaultPort,
+      section: usedSection,
+      qualifiedKey: `${usedSection}.${svc.key}`,
+      declared: declaredPort !== null,
+      declaredPort,
+      enabled,
+      bound: effectivePort !== null,
+      effectivePort,
+    };
+  });
+}
+
 /** Lowercase-alphanumeric tail of a ticket/slot, e.g. `BOT-1798` → `bot1798`. */
 function identityTag(ticket, slot) {
   const source = String(ticket ?? "").trim() || String(slot ?? "").trim();
@@ -153,6 +264,49 @@ export function leasedStackIdentity({ worktreeRoot, slot, ticket, nonce } = {})
 
 const PROJECT_ID_RE = /^[a-z][a-z0-9]{0,19}$/;
 
+const escapeRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * BOT-1835 — write `<key> = <port>` for a service the source config left implicit,
+ * into the config body `out` (an array of lines, mutated in place).
+ *
+ * Three placements, in order of how the source already spells that table:
+ *   1. a `[section]` header exists → the key joins it, directly under the header;
+ *   2. only ROOT-LEVEL dotted keys exist (`api.port = …`) → the key joins them in
+ *      the same dotted form, because TOML forbids re-opening with `[api]` a table
+ *      that dotted keys already defined;
+ *   3. the table is absent → append it. Appending only ever adds a port, never an
+ *      `enabled` flag, so materialization can never start a service the source
+ *      does not run.
+ */
+function insertSectionPort(out, section, key, port, defaultPort) {
+  const note = defaultPort > 0 ? `  # BOT-1835: undeclared, so the CLI would bind its default ${defaultPort}` : "";
+  const isComment = (line) => line.trim().startsWith("#");
+  const headerAt = out.findIndex((line) => !isComment(line) && new RegExp(`^\\s*\\[${escapeRe(section)}\\]\\s*(?:#.*)?$`).test(line));
+  if (headerAt >= 0) {
+    // After the section's LAST key, so a service needing two ports (`[db]`) reads
+    // in declaration order and a trailing comment keeps the line it introduces.
+    let at = headerAt;
+    for (let i = headerAt + 1; i < out.length; i++) {
+      if (!isComment(out[i]) && /^\s*\[[^\]]+\]/.test(out[i])) break;
+      if (!isComment(out[i]) && /^\s*[A-Za-z0-9_."']+.*=/.test(out[i])) at = i;
+    }
+    out.splice(at + 1, 0, `${key} = ${port}${note}`);
+    return;
+  }
+  const firstHeader = out.findIndex((line) => !isComment(line) && /^\s*\[[^\]]+\]/.test(line));
+  const limit = firstHeader < 0 ? out.length : firstHeader;
+  const dotted = new RegExp(`^\\s*${escapeRe(section)}\\.[A-Za-z0-9_]+\\s*=`);
+  let lastDotted = -1;
+  for (let i = 0; i < limit; i++) if (!isComment(out[i]) && dotted.test(out[i])) lastDotted = i;
+  if (lastDotted >= 0) {
+    out.splice(lastDotted + 1, 0, `${section}.${key} = ${port}${note}`);
+    return;
+  }
+  while (out.length && out[out.length - 1].trim() === "") out.pop();
+  out.push("", `[${section}]`, `${key} = ${port}${note}`, "");
+}
+
 /**
  * The worktree's own config with exactly THREE things changed: `project_id`,
  * every declared host port, and the edge runtime's own public origin. Everything
@@ -184,12 +338,12 @@ export function rewriteLeasedStackConfig(configText, { projectId, portBase } = {
   const bare = new RegExp(`^(\\s*)((?:[A-Za-z0-9]+_)?port)(\\s*=\\s*)${TOML_INT_PORT}(.*)$`);
   const dotted = new RegExp(`^(\\s*)([A-Za-z0-9_]+\\.(?:[A-Za-z0-9]+_)?port)(\\s*=\\s*)${TOML_INT_PORT}(.*)$`);
   const ports = new Map();
-  const assign = (key) => {
+  const assign = (key, why = `supabase/config.toml declares more than ${LEASED_PORT_STRIDE} host ports`) => {
     if (!ports.has(key)) {
       if (ports.size >= LEASED_PORT_STRIDE) {
         throw new Error(
-          `refusing to materialize an isolated leased stack: supabase/config.toml declares more than ${LEASED_PORT_STRIDE} host ports ` +
-            `(at "${key}") — the leased port block cannot hold them all, and reusing a port would collide inside the stack. ` +
+          `refusing to materialize an isolated leased stack: ${why} (at "${key}") — the leased port block ` +
+            `of ${LEASED_PORT_STRIDE} cannot hold them all, and reusing a port would collide inside the stack. ` +
             "Widen LEASED_PORT_STRIDE (and the band in docs/docker-capacity.md) before adding more services.",
         );
       }
@@ -224,6 +378,19 @@ export function rewriteLeasedStackConfig(configText, { projectId, portBase } = {
     }
     out.push(line);
   }
+  // BOT-1835 — then make the UNDECLARED ports explicit. Everything above remaps
+  // what the repo wrote down; a repo that writes nothing down (Supply Guard's
+  // config is a single `project_id` line) would otherwise inherit Supabase's own
+  // 543xx defaults and collide with the shared stack and with every other lease.
+  // Only services the CLI would actually bind are given a port — a disabled
+  // section, and a port the CLI publishes only when named (inbucket's
+  // smtp/pop3), stay exactly as the source left them.
+  for (const svc of supabaseServicePortState(configText)) {
+    if (svc.declared || !svc.bound) continue;
+    const port = assign(svc.qualifiedKey, `supabase/config.toml leaves the ${svc.label} port to Supabase's default (${svc.defaultPort}) and the leased block is already full`);
+    insertSectionPort(out, svc.section, svc.key, port, svc.defaultPort);
+  }
+
   // Pin the edge origin AFTER the port pass: [edge_runtime.secrets] may precede
   // [api] in the file, so the leased api port is only known once every line is seen.
   const apiPort = ports.get("api.port");
@@ -315,6 +482,34 @@ export function assertLeasedStackIsolated(rootConfigText, stackConfigText) {
   if (shared.length) {
     throw new Error(`refusing to lease a materialized stack that reuses the shared stack's port(s) ${shared.join(", ")}.`);
   }
+  // BOT-1835 — the checks above compare what the two configs WRITE DOWN, which is
+  // vacuous for a repo that writes nothing down: the CLI then binds its own
+  // defaults and the "isolated" stack is the 543xx block every other stack falls
+  // back to. So compare what the CLI would actually BIND, service by service.
+  const rootServices = new Map(supabaseServicePortState(rootConfigText).map((s) => [s.service, s]));
+  for (const svc of supabaseServicePortState(stackConfigText)) {
+    if (!svc.bound) continue;
+    if (!svc.declared) {
+      throw new Error(
+        `refusing to lease a materialized stack that leaves the ${svc.label} port undeclared: the Supabase CLI binds its own ` +
+          `default (${svc.defaultPort}) there, and so does every other stack on this host that declares none.`,
+      );
+    }
+    if (svc.effectivePort === svc.defaultPort) {
+      throw new Error(
+        `refusing to lease a materialized stack whose ${svc.label} port is Supabase's default (${svc.defaultPort}) — ` +
+          "the shared canonical stack and every other default-porting stack bind exactly that port.",
+      );
+    }
+    const rootPort = rootServices.get(svc.service)?.effectivePort ?? null;
+    if (rootPort !== null && svc.effectivePort === rootPort) {
+      throw new Error(
+        `refusing to lease a materialized stack whose ${svc.label} port (${svc.effectivePort}) is the port the worktree's own ` +
+          "stack uses — declared there or inherited from Supabase's defaults, it is the same bound socket.",
+      );
+    }
+  }
+
   // The edge runtime must emit THIS stack's public URLs (BOT-1798, Codex #928 R9).
   // A config that leaves `env(VITE_SUPABASE_URL)` in place — the repo default,
   // because a local `supabase start` exports the origin into the shell — resolves

package/src/stack.mjs

@@ -76,10 +76,12 @@ ${bold("up OPTIONS")}
   --host <host_key>      Pin to a canonical host. Omit to auto-select a beacon-fresh host.
   --repo <repo>          Repository the batch is for (e.g. botbuddy-web).
   --ticket <BOT-123>     Ticket the batch is for (also used to derive the slot).
-  --stack-path <relative> Stack directory inside the registered worktree (default: .).
-                         REQUIRED with --local-exec: point it at a slot-derived stack whose
-                         supabase/config.toml declares a DISTINCT project_id + remapped ports
-                         (never the worktree root's shared canonical project).
+  --stack-path <relative> ISOLATED stack directory inside the registered worktree. Required:
+                         the control plane refuses the worktree root (stack_path_root_refused,
+                         BOT-1797) because its supabase/config.toml is the repo's SHARED
+                         canonical project. Point it at a slot-derived stack whose
+                         supabase/config.toml declares a DISTINCT project_id + remapped ports,
+                         or use 'stack run', which materializes one for you.
   --purpose <text>       Free-text purpose recorded on the lease.
   --idle-ttl <seconds>   Idle seconds before the reaper STOPS an unused stack (default 1800).
   --timeout <seconds>    Max seconds to park for capacity before giving up (default ${DEFAULT_TIMEOUT_SEC}).
@@ -669,6 +671,39 @@ export function worktreeRegistrationHint(code, auth) {
     + `Run \`bb doctor --fix\` here to register its host + machine id, then retry.`;
 }
 
+// BOT-1797: the control plane refuses a Helper-backed lease whose stack_path is the
+// worktree root — its supabase/config.toml is the repo's SHARED canonical project, so
+// the Helper would start (and on reap destroy) the shared dev stack. This CLI always
+// materializes an isolated stack (BOT-1798), so seeing this code means a stale binary,
+// an explicit root --stack-path, or a wrapper that hand-rolls the lease call.
+export const STACK_PATH_ROOT_REFUSED_CODE = "stack_path_root_refused";
+
+// Only used when an older/leaner server sends the code with no message; the server's
+// own message is always preferred so the two can never drift.
+const STACK_PATH_ROOT_REFUSED_FALLBACK =
+  "the control plane refused a stack lease at the worktree root (the repo's shared stack). " +
+  "Upgrade with `npm i -g @botbuddy/cli@latest`, or pass --stack-path <isolated dir>.";
+
+/** The server's root refusal, verbatim, as one operator-facing line (or null). */
+export function stackPathRootRefusalNotice(code, message) {
+  if (code !== STACK_PATH_ROOT_REFUSED_CODE) return null;
+  return `${yellow("⚠")} stack: ${message || STACK_PATH_ROOT_REFUSED_FALLBACK}`;
+}
+
+/**
+ * Exit code for a lease the server REFUSED (`success: false`). A refused root path is a
+ * bad argument the caller must fix — INVALID (4) — not a backend fault, which automation
+ * reads as "the control plane is unhealthy, retry". Every other refusal keeps BACKEND (5).
+ */
+export function leaseRefusalExit(code) {
+  return code === STACK_PATH_ROOT_REFUSED_CODE ? EXIT.INVALID : EXIT.BACKEND;
+}
+
+/** The refusal text for a receipt: the server's message, else its code. */
+export function leaseRefusalError(data) {
+  return data?.message || data?.code || "lease request refused";
+}
+
 // The MCP lease endpoint accepts a session token in x-agent-api-key, whereas
 // the event-stream relay requires that same token in its bearer form too. Keep
 // the lease RPC shape unchanged and derive the relay-compatible form only at
@@ -1340,9 +1375,9 @@ export async function cmdUp(opts, {
   }
   const d = req.data;
   if (!d.success) {
-    const hint = worktreeRegistrationHint(d.code, auth);
+    const hint = worktreeRegistrationHint(d.code, auth) ?? stackPathRootRefusalNotice(d.code, d.message);
     if (hint) process.stderr.write(`${hint}\n`);
-    return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: d.message || d.code || "request refused", slot }), opts, EXIT.BACKEND);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: leaseRefusalError(d), slot }), opts, leaseRefusalExit(d.code));
   }
   let leaseId = d.lease_id;
   let state = d.state;
@@ -2007,9 +2042,10 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
     }
     if (!request.data?.success) {
-      const hint = worktreeRegistrationHint(request.data?.code, rpc.auth);
+      const hint = worktreeRegistrationHint(request.data?.code, rpc.auth)
+        ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message);
       if (hint) process.stderr.write(`${hint}\n`);
-      return { exitCode: EXIT.BACKEND, outcome: "error", error: request.data?.message || request.data?.code || "lease request refused" };
+      return { exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code, error: leaseRefusalError(request.data) };
     }
     leaseId = request.data.lease_id;
     if (request.data.reused) {
@@ -2154,7 +2190,9 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
 async function cmdRun(opts, childArgv) {
   const result = await runStackLifecycle(opts, childArgv);
   return emit(buildReceipt({
-    command: "run", outcome: result.outcome, lease_id: result.leaseId ?? null,
+    // BOT-1797: carry the server's typed refusal code (e.g. stack_path_root_refused)
+    // so automation can branch on it instead of matching the message text.
+    command: "run", outcome: result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
     child_exit_code: result.childExitCode ?? null, cleanup: result.cleanup?.ok ?? null,
     fenced: result.fenced ?? false, error: result.error ?? result.cleanup?.error ?? null,
   }), opts, result.exitCode);