@botbuddy/cli 1.2.2 → 1.4.1

package/src/locks.mjs

@@ -0,0 +1,154 @@
+import { hostname } from "node:os";
+
+export class LocksUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LocksUsageError";
+  }
+}
+
+function readValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new LocksUsageError(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function requireHost(host) {
+  if (!host || host === "local" || host === "localhost" || host === "127.0.0.1") {
+    throw new LocksUsageError("--host must be a real machine hostname for typed local resources");
+  }
+  return host;
+}
+
+export function buildAcquireResourcesPayload(args, options = {}) {
+  const defaultHost = options.defaultHost || hostname();
+  let host = defaultHost;
+  let ticketId;
+  let ticketUrl;
+  let prId;
+  let prUrl;
+  let noTicketReason;
+  let noPrReason;
+  let environment;
+  let laneSlot;
+  let vitePort;
+  let backendPort;
+  let url;
+  const requestedPorts = [];
+  let wantsMcp = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "-p":
+      case "--port": {
+        const next = args[i + 1];
+        const portType = next && !next.startsWith("-") ? next : "frontend";
+        if (next && !next.startsWith("-")) i++;
+        if (!["frontend", "backend"].includes(portType)) {
+          throw new LocksUsageError("--port must be frontend or backend");
+        }
+        requestedPorts.push(portType);
+        break;
+      }
+      case "-m":
+      case "--mcp":
+        wantsMcp = true;
+        break;
+      case "--host":
+        host = readValue(args, i, arg);
+        i++;
+        break;
+      case "--lane":
+      case "--slot":
+        laneSlot = readValue(args, i, arg);
+        i++;
+        break;
+      case "--vite-port":
+        vitePort = readValue(args, i, arg);
+        i++;
+        break;
+      case "--backend-port":
+        backendPort = readValue(args, i, arg);
+        i++;
+        break;
+      case "--url":
+        url = readValue(args, i, arg);
+        i++;
+        break;
+      case "-t":
+      case "--ticket":
+        ticketId = readValue(args, i, arg);
+        i++;
+        break;
+      case "--ticket-url":
+        ticketUrl = readValue(args, i, arg);
+        i++;
+        break;
+      case "--pr":
+        prId = readValue(args, i, arg);
+        i++;
+        break;
+      case "--pr-url":
+        prUrl = readValue(args, i, arg);
+        i++;
+        break;
+      case "--no-ticket-reason":
+        noTicketReason = readValue(args, i, arg);
+        i++;
+        break;
+      case "--no-pr-reason":
+        noPrReason = readValue(args, i, arg);
+        i++;
+        break;
+      case "--environment":
+        environment = readValue(args, i, arg);
+        i++;
+        break;
+      default:
+        throw new LocksUsageError(`Unknown locks option: ${arg}`);
+    }
+  }
+
+  const resources = [];
+  const typedHost = requireHost(host);
+
+  for (const portType of requestedPorts) {
+    const subtype = portType === "backend" ? "backend_port" : "vite_port";
+    const slot = portType === "backend" ? backendPort : vitePort;
+    resources.push({
+      resource_type: "port",
+      port_type: portType,
+      subtype,
+      host: typedHost,
+      ...(slot ? { slot } : {}),
+      ...(url ? { url } : {}),
+    });
+  }
+
+  if (wantsMcp) {
+    resources.push({
+      resource_type: "mcp_server",
+      subtype: "playwright_lane",
+      host: typedHost,
+      ...(laneSlot ? { slot: laneSlot } : {}),
+    });
+  }
+
+  if (!resources.length) {
+    throw new LocksUsageError("Usage: botbuddy locks -p [frontend|backend] -m [--host hostname] [--lane slot] [--vite-port port] [-t ticket] [--pr id]");
+  }
+
+  return {
+    resources,
+    ...(ticketId ? { ticket_id: ticketId } : {}),
+    ...(ticketUrl ? { ticket_url: ticketUrl } : {}),
+    ...(noTicketReason ? { no_ticket_reason: noTicketReason } : {}),
+    ...(prId ? { pr_id: prId } : {}),
+    ...(prUrl ? { pr_url: prUrl } : {}),
+    ...(noPrReason ? { no_pr_reason: noPrReason } : {}),
+    ...(environment ? { environment } : {}),
+  };
+}

package/src/locks.test.mjs

@@ -0,0 +1,60 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildAcquireResourcesPayload } from "./locks.mjs";
+
+test("locks --mcp emits a typed host-scoped Playwright lane request", () => {
+  const payload = buildAcquireResourcesPayload(["--mcp", "--ticket", "BOT-660"], {
+    defaultHost: "macbook-pro",
+  });
+
+  assert.deepEqual(payload, {
+    resources: [
+      {
+        resource_type: "mcp_server",
+        subtype: "playwright_lane",
+        host: "macbook-pro",
+      },
+    ],
+    ticket_id: "BOT-660",
+  });
+});
+
+test("locks --mcp can pin a lane slot and preserve PR metadata", () => {
+  const payload = buildAcquireResourcesPayload(
+    ["--mcp", "--host", "Jonos-MBP.localdomain", "--lane", "4", "--pr", "#197"],
+    { defaultHost: "ignored-host" },
+  );
+
+  assert.deepEqual(payload, {
+    resources: [
+      {
+        resource_type: "mcp_server",
+        subtype: "playwright_lane",
+        host: "Jonos-MBP.localdomain",
+        slot: "4",
+      },
+    ],
+    pr_id: "#197",
+  });
+});
+
+test("locks --port emits typed Vite port metadata with slot and URL", () => {
+  const payload = buildAcquireResourcesPayload(
+    ["--port", "frontend", "--vite-port", "4179", "--url", "http://127.0.0.1:4179"],
+    { defaultHost: "macbook-pro" },
+  );
+
+  assert.deepEqual(payload, {
+    resources: [
+      {
+        resource_type: "port",
+        port_type: "frontend",
+        subtype: "vite_port",
+        host: "macbook-pro",
+        slot: "4179",
+        url: "http://127.0.0.1:4179",
+      },
+    ],
+  });
+});

package/src/oauth-loopback.mjs

@@ -0,0 +1,228 @@
+// BOT-1383: RFC 8252 loopback receiver for the CLI OAuth authorization-code
+// flow. The old `botbuddy login` fetched /authorize itself and searched the
+// first redirect for a code — but that first redirect only points the human at
+// the sign-in page, so login always failed with "No authorization code in
+// redirect". The browser owns the redirects and the human sign-in; the CLI's
+// only job is to listen on a loopback socket for the final callback the browser
+// is redirected to, validate it, and exchange the code.
+//
+// Everything here is dependency-free and testable: PKCE/state generation, URL
+// construction, the ephemeral 127.0.0.1 listener, browser opening, and the
+// bounded wait are all separate functions with injectable seams.
+
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import { spawn as realSpawn } from "node:child_process";
+
+// Bind the literal IPv4 loopback address, never a hostname. `localhost` can
+// resolve to ::1 while the OS hands us an IPv4 socket, so the registered
+// redirect URI and the listener must both speak 127.0.0.1 (edge case in ticket).
+export const LOOPBACK_HOST = "127.0.0.1";
+
+// AC-11: bounded default wait of five minutes.
+export const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+// A callback that could not be accepted. `code` is a stable machine reason, not
+// a secret — never carries the verifier, token, or authorization code.
+export class OAuthCallbackError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "OAuthCallbackError";
+    this.code = code;
+  }
+}
+
+// AC-4: PKCE S256 with a cryptographically random verifier.
+export function generatePkce() {
+  const codeVerifier = randomBytes(32).toString("base64url").slice(0, 43);
+  const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+  return { codeVerifier, codeChallenge };
+}
+
+// AC-4: cryptographically random state, fresh per login attempt.
+export function generateState() {
+  return randomBytes(16).toString("hex");
+}
+
+// AC-6/AC-7: build the complete /authorize URL. The browser follows it; the CLI
+// never fetches it. `redirectUri` must be the exact loopback callback we bound.
+export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, scope = "read write lock" }) {
+  const url = new URL(`${serverUrl}/authorize`);
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", scope);
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+// AC-9: the browser-facing page. Deliberately discloses nothing — no code,
+// state, verifier, or token — just a "you can close this tab" message.
+function htmlPage(message) {
+  return `<!doctype html><html><head><meta charset="utf-8"><title>BotBuddy</title></head>`
+    + `<body style="font-family:system-ui,-apple-system,sans-serif;max-width:32rem;margin:4rem auto;text-align:center">`
+    + `<h1>BotBuddy CLI</h1><p>${message}</p></body></html>`;
+}
+
+function respond(res, status, message) {
+  res.writeHead(status, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+  res.end(htmlPage(message));
+}
+
+// Create (but do not yet bind) a loopback receiver bound to the given expected
+// state. Usage:
+//   const receiver = createLoopbackReceiver({ expectedState });
+//   const { port, redirectUri } = await receiver.listen();
+//   ... register client with redirectUri, open browser at the authorize URL ...
+//   const { code } = await receiver.waitForCallback({ timeoutMs });
+//   await receiver.close();  // always, in a finally
+export function createLoopbackReceiver({ expectedState } = {}) {
+  let settled = false;
+  let resolveCb;
+  let rejectCb;
+  const done = new Promise((resolve, reject) => { resolveCb = resolve; rejectCb = reject; });
+  // Swallow the rejection if nobody has awaited yet; waitForCallback re-races it.
+  done.catch(() => {});
+
+  const finish = (fn, value) => {
+    if (settled) return;
+    settled = true;
+    fn(value);
+  };
+
+  const server = createServer((req, res) => {
+    let reqUrl;
+    try {
+      reqUrl = new URL(req.url, `http://${LOOPBACK_HOST}`);
+    } catch {
+      respond(res, 400, "Bad request.");
+      return;
+    }
+
+    // AC-8: accept only GET /callback. /favicon.ico and any other stray path is
+    // answered but ignored, and the listener keeps waiting.
+    if (req.method !== "GET" || reqUrl.pathname !== "/callback") {
+      respond(res, 404, "Not found.");
+      return;
+    }
+
+    const params = reqUrl.searchParams;
+    const returnedState = params.get("state");
+    const error = params.get("error");
+    const code = params.get("code");
+
+    // Validate state BEFORE trusting anything else (AC-8). A request that does
+    // not carry our exact state is untrusted noise — a stale/malicious tab, a
+    // localhost probe, a favicon follow. Reject THAT request with a 400 but keep
+    // listening: it must not settle the receiver, or a stray probe could abort a
+    // login whose legitimate callback has not arrived yet. Only a correct-state
+    // request below is trusted to complete or fail the login.
+    if (!returnedState || returnedState !== expectedState) {
+      respond(res, 400, "This request didn't match the current login. You can close this tab.");
+      return;
+    }
+
+    // AC-8: surface OAuth error/error_description (e.g. the user denied access).
+    if (error) {
+      const description = params.get("error_description") || "";
+      respond(res, 400, "Authentication failed. You can close this tab and return to the terminal.");
+      finish(rejectCb, new OAuthCallbackError(error, description || `Authorization error: ${error}`));
+      return;
+    }
+
+    if (!code) {
+      respond(res, 400, "Authentication failed: no authorization code. You can close this tab.");
+      finish(rejectCb, new OAuthCallbackError("missing_code", "Callback did not include an authorization code"));
+      return;
+    }
+
+    // AC-8: complete at most once. A retried/duplicate callback gets a friendly
+    // page but never triggers a second token exchange.
+    if (settled) {
+      respond(res, 200, "Sign-in already received. You can close this tab.");
+      return;
+    }
+    // Only the authorization has arrived here — the token exchange happens next
+    // in the CLI and may still fail. Don't claim final success in the browser or
+    // it would contradict a terminal token error; point the user to the terminal.
+    respond(res, 200, "Sign-in received. Return to your terminal to finish — you can close this tab.");
+    finish(resolveCb, { code });
+  });
+
+  function listen() {
+    return new Promise((resolve, reject) => {
+      const onError = (err) => reject(err);
+      server.once("error", onError);
+      // AC-2: 127.0.0.1 + OS-assigned ephemeral port (port 0). Never 0.0.0.0.
+      server.listen(0, LOOPBACK_HOST, () => {
+        server.removeListener("error", onError);
+        const { port } = server.address();
+        resolve({ port, redirectUri: `http://${LOOPBACK_HOST}:${port}/callback` });
+      });
+    });
+  }
+
+  function waitForCallback({ timeoutMs = DEFAULT_LOGIN_TIMEOUT_MS, setTimeout: setT = setTimeout, clearTimeout: clearT = clearTimeout } = {}) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+      timer = setT(() => {
+        finish(reject, new OAuthCallbackError("timeout", `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the authorization callback`));
+      }, timeoutMs);
+      if (typeof timer?.unref === "function") timer.unref();
+    });
+    return Promise.race([done, timeout]).finally(() => clearT(timer));
+  }
+
+  function close() {
+    return new Promise((resolve) => {
+      // closeAllConnections (Node 18.2+) drops lingering keep-alive sockets so
+      // close() resolves promptly; optional-chained for older 18.x.
+      server.closeAllConnections?.();
+      if (!server.listening) { resolve(); return; }
+      server.close(() => resolve());
+    });
+  }
+
+  return { listen, waitForCallback, close };
+}
+
+// AC-5: open the URL in the user's default browser using argument-based process
+// spawning — the URL is always a discrete argv entry, never shell-interpolated.
+// Cross-platform without a runtime dependency. Resolves once the child has
+// spawned; rejects if the opener is unavailable (headless / missing binary).
+export function openBrowser(url, { platform = process.platform, spawn = realSpawn } = {}) {
+  let command;
+  let args;
+  if (platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else if (platform === "win32") {
+    // Never route the URL through cmd.exe: `cmd /c start` re-parses the URL's
+    // unescaped `&` query separators as command separators, so `start` would
+    // receive only the URL prefix and the OAuth params would be dropped.
+    // rundll32's FileProtocolHandler hands the whole URL to the default browser
+    // as a single, unparsed argument — no shell, no `&` splitting.
+    command = "rundll32";
+    args = ["url.dll,FileProtocolHandler", url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: "ignore", detached: true });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    child.once("error", reject);
+    child.once("spawn", () => {
+      if (typeof child.unref === "function") child.unref();
+      resolve();
+    });
+  });
+}

package/src/profile-bootstrap.mjs

@@ -0,0 +1,104 @@
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { ensureProfileCredentialBackend, readProfileIdentity, readProfileRetryIdentity, recordProfileRetryIdentity, installProfileCredential, profileCredentialEnvironment } from "./agent-credential-store.mjs";
+import { callToolJson } from "./api.mjs";
+
+const PROFILES = Object.freeze({
+  "botbuddy-dev": Object.freeze({ tenant: "botbuddy" }),
+  "supplyguard-dev": Object.freeze({ tenant: "supply-guard" }),
+});
+
+function getAgentProfile(name) {
+  return PROFILES[name] ?? null;
+}
+
+export class ProfileBootstrapError extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+}
+
+export function defaultProfileAgentName(profile) {
+  const host = hostname().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  const suffix = randomUUID().replace(/-/g, "").slice(0, 12);
+  return `${profile}-${host || "host"}-${suffix}`;
+}
+
+function registrationCredential(data) {
+  return typeof data?.agent_api_key === "string"
+    ? data.agent_api_key
+    : typeof data?.api_key === "string"
+      ? data.api_key
+      : null;
+}
+
+export async function bootstrapProfile(profileName, {
+  name = null,
+  call = callToolJson,
+  readIdentity = readProfileIdentity,
+  readRetryIdentity = readProfileRetryIdentity,
+  recordRetryIdentity = recordProfileRetryIdentity,
+  store = installProfileCredential,
+  ensureBackend = ensureProfileCredentialBackend,
+} = {}) {
+  const profile = getAgentProfile(profileName);
+  if (!profile) throw new ProfileBootstrapError("profile_required");
+  try { ensureBackend(); } catch { throw new ProfileBootstrapError("profile_agent_required"); }
+
+  const existing = await readIdentity(profileName);
+  const retryIdentity = existing ? null : await readRetryIdentity(profileName);
+  // A mismatched local entry is never reused. A fresh server-attested
+  // registration replaces it atomically, so the documented recovery command
+  // cannot loop forever on stale metadata.
+  const reusableIdentity = existing?.tenant === profile.tenant ? existing.agentId : retryIdentity?.agentId ?? null;
+  const agentName = name ?? (existing?.tenant === profile.tenant ? existing.name : retryIdentity?.name ?? defaultProfileAgentName(profileName));
+  const args = {
+    name: agentName,
+    type: "codex",
+    tenant_id: profile.tenant,
+    ...(reusableIdentity ? { agent_id: reusableIdentity } : {}),
+  };
+  const response = await call("register_agent", args);
+  const data = response?.data;
+  if (!response?.ok || (response.isError && data?.code !== "FRESH_CONNECTION_REQUIRED")) {
+    throw new ProfileBootstrapError("profile_agent_required");
+  }
+  if (!data?.agent_id || typeof data.agent_id !== "string") {
+    throw new ProfileBootstrapError("profile_agent_required");
+  }
+  if (typeof data.tenant_id !== "string") {
+    await recordRetryIdentity({ profile: profileName, agentId: data.agent_id, name: agentName });
+    throw new ProfileBootstrapError("profile_tenant_attestation_missing");
+  }
+  if (data.tenant_id !== profile.tenant) {
+    throw new ProfileBootstrapError("profile_credential_wrong_tenant");
+  }
+  const token = registrationCredential(data);
+  if (!token) throw new ProfileBootstrapError("profile_agent_required");
+
+  await store({
+    profile: profileName,
+    tenant: profile.tenant,
+    agentId: data.agent_id,
+    name: agentName,
+    token,
+  });
+  return {
+    schema_version: 1,
+    outcome: "installed",
+    profile: profileName,
+    tenant_id: profile.tenant,
+    agent_id: data.agent_id,
+    credential_source: "keychain_profile_slot",
+    shell_refresh: `source <(npx --yes @botbuddy/cli@latest profile env ${profileName})`,
+    gui_refresh: "$HOME/.local/bin/botbuddy-mcp-env.sh",
+  };
+}
+
+export function profileShellRefresh(profileName) {
+  const tokenEnv = profileCredentialEnvironment(profileName);
+  if (!tokenEnv) throw new ProfileBootstrapError("profile_required");
+  return `if botbuddy_profile_token="$(security find-generic-password -a \"$USER\" -s \"${tokenEnv}\" -w)"; then export ${tokenEnv}="$botbuddy_profile_token"; unset botbuddy_profile_token; else unset botbuddy_profile_token; false; fi`;
+}