paseo-bm-plugin 0.0.0-placeholder.0

package/server/setup-skills.ts

@@ -0,0 +1,121 @@
+/**
+ * Whether the agent skills the roles rely on are installed, as the Paseo
+ * daemon sees them (delta 20260916-setup-screen §3.3). Read-only: the plugin
+ * never installs or removes a skill.
+ *
+ * Same lists and rules as the CLI (`src/skills/detect.ts`) and `manager.md`:
+ * Claude Code counts only its own directory; Codex counts the shared
+ * `~/.agents/skills` or its own. The plugin payload cannot import `src/`, so
+ * the two short lists are repeated here and pinned by a test.
+ *
+ * Pi and OpenCode (delta 20260921 §4.2.6, F8) count only their own
+ * directory, `~/.pi/agent/skills` and `~/.config/opencode/skill` (singular),
+ * checked the same way as Claude's. No environment variable moves them in this
+ * release, and the CLI (`--skills-agents`, `doctor`) does not look at them.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const REQUIRED_SKILLS = [
+  "feature-workflow",
+  "reviewing-plan",
+  "converting-plan-to-beads",
+  "polishing-beads",
+  "implementing-beads",
+] as const;
+export const OPTIONAL_SKILLS = ["architecture-premise-audit", "authoring-workspace-protocol"] as const;
+
+export type SkillState = "ok" | "missing" | "broken";
+
+export interface SkillRow {
+  name: string;
+  required: boolean;
+  claude: SkillState;
+  codex: SkillState;
+  pi: SkillState;
+  opencode: SkillState;
+  /** Why a copy is broken, when one is. */
+  problem: string | null;
+}
+
+export interface SkillsStatus {
+  checkedAt: string;
+  dirs: { shared: string; claude: string; codex: string; pi: string; opencode: string };
+  skills: SkillRow[];
+  /** Required skills not usable, per agent. */
+  missingRequired: { claude: number; codex: number; pi: number; opencode: number };
+  installCommand: string;
+}
+
+export interface SkillDeps {
+  env?: NodeJS.ProcessEnv;
+  homedir?: () => string;
+  readFile?: (path: string) => string;
+  now?: () => Date;
+}
+
+export function skillDirs(deps: SkillDeps = {}): SkillsStatus["dirs"] {
+  const env = deps.env ?? process.env;
+  const home = (deps.homedir ?? homedir)();
+  return {
+    shared: join(home, ".agents", "skills"),
+    claude: join(env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"), "skills"),
+    codex: join(env.CODEX_HOME ?? join(home, ".codex"), "skills"),
+    pi: join(home, ".pi", "agent", "skills"),
+    opencode: join(home, ".config", "opencode", "skill"),
+  };
+}
+
+/** One copy of a skill: `ok`, `missing`, or `broken` with the reason. */
+export function checkSkillAt(dir: string, name: string, read: (path: string) => string): { state: SkillState; problem: string | null } {
+  let text: string;
+  try {
+    text = read(join(dir, name, "SKILL.md"));
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return { state: "missing", problem: null };
+    return { state: "broken", problem: `${join(dir, name, "SKILL.md")} cannot be read (${code ?? "error"})` };
+  }
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+  const declared = frontmatter === undefined ? null : /^name:\s*["']?([^"'\n]+?)["']?\s*$/m.exec(frontmatter)?.[1] ?? null;
+  if (declared === null) return { state: "broken", problem: `${name}/SKILL.md has no \`name:\` in its frontmatter` };
+  if (declared !== name) return { state: "broken", problem: `${name}/SKILL.md declares name \`${declared}\`` };
+  return { state: "ok", problem: null };
+}
+
+function best(...states: Array<{ state: SkillState; problem: string | null }>): { state: SkillState; problem: string | null } {
+  return states.find((entry) => entry.state === "ok") ?? states.find((entry) => entry.state === "broken") ?? states[0]!;
+}
+
+export function skillsStatus(deps: SkillDeps = {}): SkillsStatus {
+  const read = deps.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+  const dirs = skillDirs(deps);
+  const rows: SkillRow[] = [...REQUIRED_SKILLS, ...OPTIONAL_SKILLS].map((name) => {
+    const claude = checkSkillAt(dirs.claude, name, read);
+    const codex = best(checkSkillAt(dirs.shared, name, read), checkSkillAt(dirs.codex, name, read));
+    const pi = checkSkillAt(dirs.pi, name, read);
+    const opencode = checkSkillAt(dirs.opencode, name, read);
+    return {
+      name,
+      required: (REQUIRED_SKILLS as readonly string[]).includes(name),
+      claude: claude.state,
+      codex: codex.state,
+      pi: pi.state,
+      opencode: opencode.state,
+      problem: claude.problem ?? codex.problem ?? pi.problem ?? opencode.problem,
+    };
+  });
+  return {
+    checkedAt: (deps.now ?? (() => new Date()))().toISOString(),
+    dirs,
+    skills: rows,
+    missingRequired: {
+      claude: rows.filter((row) => row.required && row.claude !== "ok").length,
+      codex: rows.filter((row) => row.required && row.codex !== "ok").length,
+      pi: rows.filter((row) => row.required && row.pi !== "ok").length,
+      opencode: rows.filter((row) => row.required && row.opencode !== "ok").length,
+    },
+    installCommand: `npx -y skills add cuongntr/agent-skills -g -a claude-code codex -s ${REQUIRED_SKILLS.join(" ")} -y`,
+  };
+}

package/server/setup-tools.ts

@@ -0,0 +1,162 @@
+/**
+ * The beads tools the Worker depends on — `br` and `bv` — and `bd` for
+ * information (delta 20260916-setup-screen §3.4).
+ *
+ * Finding and version-checking is read-only. Installing runs only the
+ * documented command for a tool that is missing, only when the user pressed
+ * Install and confirmed it on the Setup screen.
+ */
+import { execFile } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { DashboardError } from "../shared/contracts";
+
+export type ToolId = "br" | "bv" | "bd";
+
+export interface ToolInfo {
+  id: ToolId;
+  name: string;
+  purpose: string;
+  required: boolean;
+  path: string | null;
+  version: string | null;
+  latestKnown: string | null;
+  installCommand: string | null;
+  updateCommand: string | null;
+  homepage: string;
+}
+
+/** Newest releases seen on the projects' pages, and when (not fetched at runtime). */
+export const LATEST_KNOWN = { br: "0.6.0", bv: "v0.25.0", checkedOn: "2026-09-16" } as const;
+
+const BR_SCRIPT =
+  "curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh | bash -s -- --skip-skills";
+/** Pinned to the commit the beads_viewer README asks installers to use. */
+const BV_SCRIPT =
+  "curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/a43b8e85a39664381566abdfd85dc8fcbfdcb773/install.sh | bash";
+
+const DESCRIPTIONS: Record<ToolId, { name: string; purpose: string; required: boolean; homepage: string }> = {
+  br: {
+    name: "br — beads_rust",
+    purpose: "The issue tracker the Worker uses to create, update and close beads.",
+    required: true,
+    homepage: "https://github.com/Dicklesworthstone/beads_rust",
+  },
+  bv: {
+    name: "bv — beads_viewer",
+    purpose: "Triage and dependency views over the same beads (agents use its --robot-* modes).",
+    required: true,
+    homepage: "https://github.com/Dicklesworthstone/beads_viewer",
+  },
+  bd: {
+    name: "bd — beads (Go)",
+    purpose: "The original beads CLI. Optional when br is installed.",
+    required: false,
+    homepage: "https://github.com/steveyegge/beads",
+  },
+};
+
+export interface ToolDeps {
+  env?: NodeJS.ProcessEnv;
+  homedir?: () => string;
+  isExecutable?: (path: string) => boolean;
+  run?: (file: string, args: string[], timeoutMs: number) => Promise<{ code: number; output: string }>;
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function run(file: string, args: string[], timeoutMs: number): Promise<{ code: number; output: string }> {
+  return new Promise((resolve) => {
+    execFile(file, args, { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+      const code = error === null ? 0 : typeof (error as { code?: unknown }).code === "number" ? (error as { code: number }).code : 1;
+      resolve({ code, output: `${stdout}${stderr}` });
+    });
+  });
+}
+
+/** The daemon's PATH, then the places the documented installers use. */
+export function searchDirs(deps: ToolDeps = {}): string[] {
+  const env = deps.env ?? process.env;
+  const home = (deps.homedir ?? homedir)();
+  const fromPath = (env.PATH ?? "").split(delimiter).filter((dir) => dir !== "");
+  const extra = [join(home, ".local", "bin"), "/opt/homebrew/bin", "/usr/local/bin", join(home, ".cargo", "bin"), join(home, "go", "bin")];
+  return [...new Set([...fromPath, ...extra])];
+}
+
+export function findTool(name: string, deps: ToolDeps = {}): string | null {
+  const check = deps.isExecutable ?? isExecutable;
+  for (const dir of searchDirs(deps)) {
+    const candidate = join(dir, name);
+    if (check(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** First line of `--version` output, without the tool name. */
+export function versionOf(output: string): string | null {
+  const line = output.split("\n").map((part) => part.trim()).find((part) => part !== "");
+  if (line === undefined) return null;
+  return line.replace(/^(?:br|bv|bd)\s+(?:version\s+)?/i, "").trim() || null;
+}
+
+export function commandsFor(id: ToolId, brewPath: string | null): { install: string | null; update: string | null } {
+  if (id === "bd") return { install: null, update: null };
+  if (brewPath !== null) {
+    return { install: `brew install dicklesworthstone/tap/${id}`, update: `brew upgrade dicklesworthstone/tap/${id}` };
+  }
+  const script = id === "br" ? BR_SCRIPT : BV_SCRIPT;
+  return { install: script, update: script };
+}
+
+export async function toolsStatus(deps: ToolDeps = {}): Promise<ToolInfo[]> {
+  const exec = deps.run ?? run;
+  const brew = findTool("brew", deps);
+  return Promise.all(
+    (["br", "bv", "bd"] as const).map(async (id): Promise<ToolInfo> => {
+      const path = findTool(id, deps);
+      // Only ever `--version`: a bare `bv` opens an interactive TUI.
+      const version = path === null ? null : versionOf((await exec(path, ["--version"], 5000)).output);
+      const commands = commandsFor(id, brew);
+      return {
+        id,
+        ...DESCRIPTIONS[id],
+        path,
+        version,
+        latestKnown: id === "bd" ? null : LATEST_KNOWN[id],
+        installCommand: commands.install,
+        updateCommand: commands.update,
+      };
+    }),
+  );
+}
+
+export const INSTALL_TIMEOUT_MS = 300_000;
+
+/**
+ * Runs the documented install command for a missing tool. The user pressed
+ * Install and confirmed the exact command before this is called.
+ */
+export async function installTool(id: "br" | "bv", deps: ToolDeps = {}): Promise<{ command: string; code: number; tail: string[] }> {
+  if (findTool(id, deps) !== null) {
+    throw new DashboardError("E_TOOL_PRESENT", `${id} is already installed; update it with the command shown on the Setup screen`);
+  }
+  const command = commandsFor(id, findTool("brew", deps)).install!;
+  const exec = deps.run ?? run;
+  const env = deps.env ?? process.env;
+  // A login shell, so the installer sees the user's usual PATH (brew, curl).
+  const result = await exec(env.SHELL?.endsWith("zsh") ? "/bin/zsh" : "/bin/bash", ["-lc", command], INSTALL_TIMEOUT_MS);
+  const tail = result.output.split("\n").filter((line) => line.trim() !== "").slice(-40);
+  if (result.code !== 0) {
+    throw new DashboardError("E_TOOL_INSTALL_FAILED", `\`${command}\` exited with ${result.code}: ${tail.slice(-3).join(" | ")}`);
+  }
+  return { command, code: result.code, tail };
+}

package/server/shell.ts

@@ -0,0 +1,68 @@
+/**
+ * Reading the shell commands agents ran. One place, because two modules asked
+ * the same question ("did this `br` command act on beads?") with two different
+ * rules and could disagree about the same line.
+ *
+ * All three rules below were found on real agent output (WP-214 acceptance).
+ */
+import { BEAD_ID } from "./bm-report";
+
+/**
+ * Splits a shell line into the commands it runs, with quoted arguments blanked:
+ * `grep -iE 'makefile|pytest'` contains pipes and a runner's name inside the
+ * quotes, and must not look like two commands, one of them a test run.
+ */
+export function commandSegments(line: string): string[] {
+  return line
+    .replace(/'[^']*'|"[^"]*"/g, " ARG ")
+    .split(/&&|\|\||[;\n|]/)
+    .map((segment) => segment.trim().replace(/^[(\s]+/, ""))
+    .filter((segment) => segment !== "");
+}
+
+export type BrVerb = "create" | "update" | "close";
+
+export interface BrAction {
+  verb: BrVerb;
+  ids: string[];
+  /** An update that moves its beads to `in_progress` (`--status in_progress` or `--claim`). */
+  startsWork: boolean;
+}
+
+function startsWork(tokens: readonly string[]): boolean {
+  return tokens.some(
+    (token, index) =>
+      token === "--claim" ||
+      token === "--status=in_progress" ||
+      ((token === "--status" || token === "-s") && tokens[index + 1] === "in_progress"),
+  );
+}
+
+/**
+ * The `br create | update | close` commands in a shell line that actually act.
+ *
+ * - A `--help`, `-h` or `--dry-run` command only looked (a Worker ran
+ *   `br create --help` to orient itself, and the beads step read as done).
+ * - Bead ids are positional arguments only, read before the first flag.
+ *   Scanning the whole line read `-l "feature:format-date"` and the prose of
+ *   `-r "… a single-line docstring …"` as ids: one request reported 6 closed
+ *   beads instead of 1.
+ * - `br create` names no id at all: `br` mints it.
+ */
+export function brActions(line: string): BrAction[] {
+  const out: BrAction[] = [];
+  for (const segment of commandSegments(line)) {
+    const match = /^br\s+(create|update|close)\b(.*)$/i.exec(segment);
+    if (match === null) continue;
+    const tokens = match[2]!.trim().split(/\s+/).filter((token) => token !== "");
+    if (tokens.some((token) => token === "--help" || token === "-h" || token === "--dry-run")) continue;
+    const ids: string[] = [];
+    for (const token of tokens) {
+      if (token.startsWith("-")) break;
+      if (BEAD_ID.test(token)) ids.push(token);
+    }
+    const verb = match[1]!.toLowerCase() as BrVerb;
+    out.push({ verb, ids, startsWork: verb === "update" && startsWork(tokens) });
+  }
+  return out;
+}