@botbuddy/cli 1.5.5 → 1.6.0

package/bin/bb-pw.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runPw } from "../src/pw/run.mjs";
+
+runPw(process.argv.slice(2)).then((code) => process.exit(code)).catch((error) => {
+  console.error(`bb-pw: ${error?.message ?? error}`);
+  process.exit(1);
+});

package/bin/botbuddy.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { run } from "../src/commands.mjs";
 
-run(process.argv.slice(2)).catch((err) => {
+run(process.argv.slice(2)).then((code) => {
+  if (typeof code === "number") process.exitCode = code;
+}).catch((err) => {
   console.error(`\x1b[31m✗\x1b[0m ${err?.message || err}`);
   process.exit(1);
 });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
-    "botbuddy": "./bin/botbuddy.mjs"
+    "botbuddy": "./bin/botbuddy.mjs",
+    "bb-pw": "./bin/bb-pw.mjs"
   },
   "files": [
     "bin/",
@@ -20,9 +21,13 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@playwright/cli": "0.1.17",
+    "playwright": "1.62.0-alpha-1783623505000"
   }
 }

package/src/commands.mjs

@@ -11,6 +11,7 @@ import { runWait } from "./wait.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 import { bootstrapProfile, ProfileBootstrapError, profileShellRefresh } from "./profile-bootstrap.mjs";
+import { runPw } from "./pw/run.mjs";
 
 export async function run(argv) {
   loadConfig();
@@ -32,6 +33,7 @@ export async function run(argv) {
     case "docker": return cmdDocker(args);
     case "run": return cmdRun(args);
     case "wait": return runWait(args);
+    case "pw": return runPw(args);
     case "profile": return cmdProfile(args);
     case "resources": return callTool("list_resources");
     case "agents": return callTool("list_agents");
@@ -101,6 +103,10 @@ ${bold("AGENT WAITS")}
   wait [--any] <condition>... [options]
                               Wait once for a pushed BotBuddy signal
 
+${bold("BROWSER LANES")}
+  pw <lane> <verb> [args…]    Drive a lock-gated Playwright lane
+  pw --help                   Show bb-pw-compatible lane usage
+
 ${bold("OTHER")}
   locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
   help                       Show this help

package/src/pw/args.mjs

@@ -0,0 +1,28 @@
+import { TARGET_VERBS, parseTargetFlags, hasTargetFlags, buildLocatorTarget, classifyTarget, isSnapshotRef } from "./targets.mjs";
+export const GLOBAL_VERBS = new Set(["list", "close-all", "kill-all", "reap"]);
+const secret = /^@ENV:(.+)$/;
+export function resolveRef(value, env = process.env) {
+  const match = secret.exec(String(value));
+  if (!match) return { value, secret: false };
+  if (!env[match[1]]) throw new Error(`bb-pw: env var ${match[1]} referenced by ${value} is not set`);
+  return { value: env[match[1]], ref: value, secret: true };
+}
+export const normaliseLane = (token) => String(token).replace(/^agent-0*/, "").replace(/^lane-/, "");
+function validLane(lane) { return /^[1-9]\d*$/.test(lane); }
+export function planInvocation(argv, env = process.env) {
+  if (!argv.length) throw new Error("bb-pw: usage: bb-pw <lane> <verb> [args…]  (or: bb-pw <reap|list|close-all|kill-all>)");
+  if (GLOBAL_VERBS.has(argv[0])) return argv[0] === "reap" ? { scope: "global", verb: "reap", mode: "reap" } : { scope: "global", verb: argv[0], mode: "exec", execArgv: argv };
+  const lane = normaliseLane(argv[0]), verb = argv[1];
+  if (!validLane(lane) || !verb) throw new Error(`bb-pw: usage: lane must be a positive integer and include a verb`);
+  if (verb === "status") return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: "status" };
+  const rest = argv.slice(2); let forwarded = rest, target = null, fresh = false;
+  if (TARGET_VERBS.has(verb)) {
+    const parsed = parseTargetFlags(rest); fresh = parsed.fresh;
+    forwarded = hasTargetFlags(parsed.flags) ? [buildLocatorTarget(parsed.flags), ...parsed.rest] : parsed.rest;
+    target = forwarded.find((value) => !String(value).startsWith("--")) ?? null;
+    if (fresh && target && isSnapshotRef(target)) throw new Error("bb-pw: --fresh cannot target a snapshot ref; use a stable locator");
+  }
+  const resolved = forwarded.map((value) => resolveRef(value, env));
+  const sensitive = resolved.some((value) => value.secret);
+  return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: sensitive ? "socket" : "exec", execArgv: sensitive ? null : [`-s=lane-${lane}`, verb, ...forwarded], socketArgs: sensitive ? [verb, ...resolved.map((value) => value.value)] : null, telemetryUrl: ["goto", "open", "go-back", "go-forward", "reload"].includes(verb) ? (resolved[0]?.secret ? resolved[0].ref : forwarded[0] ?? null) : null, secretValues: resolved.filter((value) => value.secret).map((value) => String(value.value)), rollup: verb === "close", target, targetKind: target === null ? null : classifyTarget(target), fresh };
+}

package/src/pw/coordinator.mjs

@@ -0,0 +1,12 @@
+import { SERVER_URL } from "../config.mjs";
+export function createProfileCoordinator({ profile, identity, fetchImpl = fetch } = {}) {
+  if (!profile?.token || !identity?.agentId || identity.tenant !== profile.tenant) return { kind: "unverified" };
+  let id = 0;
+  async function call(name, args) {
+    const response = await fetchImpl(SERVER_URL, { method: "POST", headers: { "content-type": "application/json", "x-agent-api-key": profile.token }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }) });
+    if (!response.ok) throw new Error(`BotBuddy lock verification returned HTTP ${response.status}`);
+    const json = await response.json(); if (json.error) throw new Error(json.error.message || "BotBuddy lock verification failed");
+    const text = json.result?.content?.find((item) => item.type === "text")?.text; try { return text ? JSON.parse(text) : {}; } catch { throw new Error("BotBuddy lock verification returned invalid JSON"); }
+  }
+  return { kind: "profile", async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null } : { held: false, heldBy: null }; }, async emit(event) { await call("record_lane_event", event); }, agentId: identity.agentId };
+}

package/src/pw/daemon.mjs

@@ -0,0 +1,13 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { createRequire } from "node:module";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export const daemonDir = (env = process.env) => env.BB_PW_DAEMON_DIR || join(homedir(), ".botbuddy", "pw-daemon");
+export function resolveCliBin(env = process.env) { if (env.BB_PW_CLI_BIN) return { cmd: "node", args: [env.BB_PW_CLI_BIN] }; const require = createRequire(import.meta.url); const pkg = require.resolve("@playwright/cli/package.json"), meta = JSON.parse(readFileSync(pkg, "utf8")), bin = typeof meta.bin === "string" ? meta.bin : meta.bin["playwright-cli"] || Object.values(meta.bin)[0]; return { cmd: "node", args: [join(dirname(pkg), bin)] }; }
+export function spawnExec(plan, env = process.env) { const { cmd, args } = resolveCliBin(env); return new Promise((resolve) => { const child = spawn(cmd, [...args, ...plan.execArgv], { stdio: "inherit", env: { ...env, PWTEST_DAEMON_SESSION_DIR: daemonDir(env) } }); child.on("exit", (code) => resolve(code ?? 1)); child.on("error", () => resolve(127)); }); }
+export function readSession(session, env = process.env) { const root = daemonDir(env); if (!existsSync(root)) return null; for (const item of readdirSync(root)) { try { return JSON.parse(readFileSync(join(root, item, `${session}.session`), "utf8")); } catch {} } return null; }
+export function sendToDaemon(socketPath, positional, { connect = net.createConnection, cwd = process.cwd(), timeoutMs = 30000 } = {}) { return new Promise((resolve) => { let done = false, buffer = "", socket; const finish = (value) => { if (!done) { done = true; socket?.destroy(); resolve(value); } }; socket = connect(socketPath, () => socket.write(JSON.stringify({ id: 1, method: "run", params: { args: { _: positional }, cwd } }) + "\n")); socket.on("data", (data) => { buffer += String(data); const newline = buffer.indexOf("\n"); if (newline < 0) return; try { const reply = JSON.parse(buffer.slice(0, newline)), text = reply.result?.text ?? ""; finish(reply.error || /^### Error\b/m.test(text) ? { ok: false, error: reply.error?.message ?? reply.error ?? text } : { ok: true, text }); } catch { finish({ ok: false, error: "bb-pw: malformed daemon reply" }); } }); socket.on("error", (error) => finish({ ok: false, error: error.message })); setTimeout(() => finish({ ok: false, error: "bb-pw: daemon socket timeout" }), timeoutMs).unref(); }); }
+export function socketAlive(socketPath, { connect = net.createConnection, timeoutMs = 1000 } = {}) { return new Promise((resolve) => { if (!socketPath) return resolve(false); let done = false, socket; const finish = (value) => { if (!done) { done = true; socket?.destroy(); resolve(value); } }; socket = connect(socketPath, () => finish(true)); socket.on("error", () => finish(false)); setTimeout(() => finish(false), timeoutMs).unref(); }); }
+export async function socketRun(plan, env = process.env) { const session = readSession(plan.session, env); return session?.socketPath ? sendToDaemon(session.socketPath, plan.socketArgs) : { ok: false, error: `bb-pw: no open daemon for ${plan.session}; open it first` }; }

package/src/pw/readiness.mjs

@@ -0,0 +1,4 @@
+export const NAV = "navigate";
+const interaction = new Set(["click", "fill", "type", "select", "press", "drag", "hover", "dblclick", "check", "uncheck"]);
+export function actionTypeFromMethod(method) { const value = String(method); return ["goto", "open", "go-back", "go-forward", "reload"].includes(value) ? NAV : value === "screenshot" ? "screenshot" : value === "snapshot" ? "snapshot" : interaction.has(value) ? "interaction" : "other"; }
+export function deriveSession(events, { meta = {} } = {}) { const ordered = [...events].sort((a,b) => a.ts-b.ts), type = (name) => ordered.filter((event) => actionTypeFromMethod(event.method) === name); const nav = type(NAV); return { ...meta, started_at: ordered[0]?.ts ?? null, ended_at: ordered.at(-1)?.ts ?? null, duration_ms: ordered.length ? ordered.at(-1).ts - ordered[0].ts : 0, active_ms: 0, idle_threshold_ms: 60000, navigations: nav.length, distinct_routes: [...new Set(nav.map((event) => { try { return new URL(event.url).pathname; } catch { return String(event.url).split("?")[0]; } }))], screenshots: type("screenshot").length, snapshots: type("snapshot").length, interactions: type("interaction").length, actions_total: ordered.length }; }

package/src/pw/reap.mjs

@@ -0,0 +1,5 @@
+import { execSync } from "node:child_process";
+import { readSession, socketAlive } from "./daemon.mjs";
+export const parsePs = (text) => String(text).split("\n").map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/)).filter(Boolean).map(([, pid, ppid, command]) => ({ pid: Number(pid), ppid: Number(ppid), command }));
+export const selectCliDaemons = (list) => list.flatMap((row) => { const found = /cliDaemon\.js\s+(\S+)/.exec(row.command); return found ? [{ ...row, lane: found[1] }] : []; });
+export async function reap({ env = process.env, stdout = process.stdout, exec = execSync, alive = socketAlive, kill = (pid) => { try { process.kill(pid, "SIGKILL"); } catch {} } } = {}) { const processes = selectCliDaemons(parsePs(exec("ps -axw -o pid=,ppid=,command=").toString())), stale = []; for (const daemon of processes) { if (!await alive(readSession(daemon.lane, env)?.socketPath)) { stale.push(daemon.pid); kill(daemon.pid); } } stdout.write(`bb-pw reap: ${stale.length} stale daemon(s) reaped${stale.length ? ` (${stale.join(",")})` : ""}\n`); return stale; }

package/src/pw/run.mjs

@@ -0,0 +1,24 @@
+import os from "node:os";
+import { planInvocation } from "./args.mjs";
+import { actionTypeFromMethod, NAV } from "./readiness.mjs";
+import { isStaleRefError, staleRefRemediation } from "./targets.mjs";
+import { createProfileCoordinator } from "./coordinator.mjs";
+import { resolveAgentProfile } from "../wait-profile.mjs";
+import { readProfileIdentity } from "../agent-credential-store.mjs";
+const hostFor = (env) => env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname();
+function help(out) { out.write("Usage: botbuddy pw [--profile <name>] <lane> <verb> [args…]\n\nAlias: bb-pw <lane> <verb> [args…]\n"); }
+function redact(value, secretValues = []) { return secretValues.reduce((text, secret) => secret ? text.split(secret).join("[redacted]") : text, String(value ?? "")); }
+async function gate({ env, host, lane, deps }) { if (env.BB_PW_NO_LOCK === "1") return { allowed: true }; let profile, identity; try { profile = await (deps.resolveProfile ?? resolveAgentProfile)({ cwd: deps.cwd ?? process.cwd(), env, explicitProfile: deps.profile ?? null }); identity = await (deps.readIdentity ?? readProfileIdentity)(profile.name); } catch (error) { return { allowed: false, message: `bb-pw: profile verification failed (${error.message}). Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work.` }; } const coordinator = deps.coordinator ?? createProfileCoordinator({ profile, identity, fetchImpl: deps.fetch }); if (!profile.token || !identity || identity.tenant !== profile.tenant || coordinator.kind !== "profile") return { allowed: false, message: "bb-pw: profile identity is missing or tenant-mismatched. Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work." }; try { const status = await coordinator.status({ host, slot: lane }); return status.held && status.heldBy === identity.agentId ? { allowed: true, coordinator } : { allowed: false, message: `bb-pw: lane lock playwright_lane:${host}:${lane} must be held by this profile. Acquire it first or set BB_PW_NO_LOCK=1 for local-only work.` }; } catch (error) { return { allowed: false, message: `bb-pw: could not verify lane lock (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` }; } }
+export async function runPw(argv, deps = {}) {
+  const env = deps.env ?? process.env, stdout = deps.stdout ?? process.stdout, stderr = deps.stderr ?? process.stderr; let args = [...argv]; if (["--help", "-h"].includes(args[0])) { help(stdout); return 0; } if (args[0] === "--profile") { if (!args[1]) { stderr.write("bb-pw: --profile needs a name\n"); return 2; } deps = { ...deps, profile: args[1] }; args = args.slice(2); }
+  let plan; try { plan = planInvocation(args, env); } catch (error) { stderr.write(`${error.message}\n`); return 2; }
+  const { spawnExec, socketRun } = deps.daemon ?? await import("./daemon.mjs");
+  if (plan.scope === "global") { if (plan.mode === "reap") { await (deps.reap ?? (await import("./reap.mjs")).reap)({ env, stdout }); return 0; } if (env.BB_PW_NO_LOCK !== "1") { stderr.write("bb-pw: close-all and kill-all require BB_PW_NO_LOCK=1 because they can affect lanes you do not own.\n"); return 3; } return spawnExec(plan, env); }
+  const telemetry = deps.telemetry ?? (await import("./telemetry.mjs")).makeTelemetry({ env }); const host = deps.host ?? hostFor(env);
+  const auth = await gate({ env, host, lane: plan.lane, deps }); if (!auth.allowed) { stderr.write(`${auth.message}\n`); return 3; }
+  if (plan.mode === "status") { const lock = auth.coordinator?.status ? await auth.coordinator.status({ host, slot: plan.lane }) : null; stdout.write(JSON.stringify({ lane: plan.lane, session: plan.session, host, lock, spooled_events: telemetry.count(plan.lane) }, null, 2) + "\n"); return 0; }
+  if (actionTypeFromMethod(plan.verb) !== "other") telemetry.append(plan.lane, { ts: Date.now(), method: plan.verb, url: actionTypeFromMethod(plan.verb) === NAV ? plan.telemetryUrl : null });
+  const inspect = plan.mode === "socket" || (actionTypeFromMethod(plan.verb) === "interaction" && (plan.targetKind === "ref" || plan.fresh)); let code;
+  if (inspect) { if (plan.fresh) await socketRun({ ...plan, socketArgs: ["snapshot"] }, env).catch(() => {}); const result = await socketRun({ ...plan, socketArgs: plan.socketArgs ?? plan.execArgv.slice(1) }, env); if (result.text) stdout.write(`${redact(result.text, plan.secretValues)}\n`); if (!result.ok) stderr.write(`${redact(plan.targetKind === "ref" && isStaleRefError(result.error) ? staleRefRemediation(plan.target) : result.error, plan.secretValues)}\n`); code = result.ok ? 0 : 1; } else code = await spawnExec(plan, env);
+  if (plan.rollup && code === 0) await telemetry.rollup({ lane: plan.lane, coordinator: auth.coordinator, host }); return code;
+}

package/src/pw/targets.mjs

@@ -0,0 +1,37 @@
+const REF = /^(f\d+)?e\d+$/;
+export const TARGET_VERBS = new Set(["click", "dblclick", "fill", "hover", "check", "uncheck", "select"]);
+export const isSnapshotRef = (value) => REF.test(String(value ?? ""));
+export const classifyTarget = (value) => /^getBy[A-Z]/.test(String(value ?? "")) ? "locator" : isSnapshotRef(value) ? "ref" : "selector";
+const BASE = ["role", "placeholder", "text", "testid", "label", "title", "alt"];
+const quote = (value) => `'${String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+export function parseTargetFlags(args) {
+  const flags = {}, rest = []; let fresh = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const match = /^--([a-z]+)(?:=(.*))?$/s.exec(String(args[index]));
+    if (!match) { rest.push(args[index]); continue; }
+    const [, name, inline] = match;
+    if (name === "fresh") { fresh = true; continue; }
+    if (name === "exact") { flags.exact = true; continue; }
+    if (![...BASE, "name"].includes(name)) { rest.push(args[index]); continue; }
+    const value = inline ?? args[++index];
+    if (value === undefined) throw new Error(`bb-pw: --${name} needs a value`);
+    flags[name] = value;
+  }
+  return { flags, rest, fresh };
+}
+export const hasTargetFlags = (flags) => Object.keys(flags).some((key) => key !== "exact");
+function exact(method, value, enabled) { return enabled ? `${method}(${quote(value)}, { exact: true })` : `${method}(${quote(value)})`; }
+export function buildLocatorTarget(flags) {
+  const bases = BASE.filter((name) => flags[name] !== undefined);
+  if (flags.name !== undefined && flags.role === undefined) throw new Error("bb-pw: --name qualifies --role; pass --role too");
+  if (bases.length !== 1) throw new Error(`bb-pw: give exactly one base locator, got: ${bases.map((name) => `--${name}`).join(", ") || "none"}`);
+  const base = bases[0], isExact = flags.exact === true;
+  if (base === "role") {
+    const opts = flags.name === undefined ? "" : `, { name: ${quote(flags.name)}${isExact ? ", exact: true" : ""} }`;
+    return `getByRole(${quote(flags.role)}${opts})`;
+  }
+  if (base === "testid") return `getByTestId(${quote(flags.testid)})`;
+  return exact({ placeholder: "getByPlaceholder", text: "getByText", label: "getByLabel", title: "getByTitle", alt: "getByAltText" }[base], flags[base], isExact);
+}
+export const isStaleRefError = (text) => /not found in the current page snapshot/i.test(String(text ?? ""));
+export const staleRefRemediation = (ref) => `bb-pw: snapshot ref ${ref} is stale — capture a new snapshot or use a stable locator (--role, --text, --testid)${""}.`;

package/src/pw/telemetry.mjs

@@ -0,0 +1,14 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { deriveSession } from "./readiness.mjs";
+const spoolDir = (env) => env.BB_PW_SPOOL_DIR || join(homedir(), ".botbuddy", "pw-spool");
+export function makeTelemetry({ env = process.env } = {}) {
+  const path = (lane) => join(spoolDir(env), `lane-${lane}.jsonl`);
+  const readEvents = (lane) => existsSync(path(lane)) ? readFileSync(path(lane), "utf8").split("\n").filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } }) : [];
+  return {
+    append(lane, event) { mkdirSync(spoolDir(env), { recursive: true }); appendFileSync(path(lane), JSON.stringify({ ts: event.ts, method: event.method, url: event.url ?? null }) + "\n"); },
+    count(lane) { return readEvents(lane).length; },
+    async rollup({ lane, coordinator, host }) { const events = readEvents(lane); if (!events.length) return { emitted: false, count: 0 }; const session = deriveSession(events, { meta: { host, slot: String(lane), ticket_id: env.BB_PW_TICKET_ID, ticket_url: env.BB_PW_TICKET_URL, pr_id: env.BB_PW_PR_ID, pr_url: env.BB_PW_PR_URL, branch: env.BB_PW_BRANCH, commit_sha: env.BB_PW_COMMIT, environment: env.BB_PW_ENV } }); const event = { ...session, started_at: new Date(session.started_at).toISOString(), ended_at: new Date(session.ended_at).toISOString(), ended_reason: "close" }; try { if (!coordinator?.emit) return { emitted: false, count: events.length, session: event }; await coordinator.emit(event); rmSync(path(lane), { force: true }); return { emitted: true, count: events.length, session: event }; } catch { return { emitted: false, count: events.length, session: event }; } },
+  };
+}

package/src/botbuddy-release-repair.json

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