@bugmole/cli 0.5.0 → 0.6.0

package/src/runtime/project-identity.test.ts

@@ -0,0 +1,161 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { RegistryRequestError, projectInactiveMessage } from "../registry/control-plane-client.js";
+import { runInitWizard } from "./init-wizard.js";
+import { SCOPE_MESSAGE, describeDetection, detectProjectIdentity, discoverApps } from "./project-identity.js";
+import { announceProjectIdentity, isClaimConflict } from "./serve-worker.js";
+
+async function monorepo(remote = "https://ada:ghp_secret@github.com/Acme/Shop.git") {
+  const root = await mkdtemp(path.join(os.tmpdir(), "bugmole-identity-"));
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  execFileSync("git", ["remote", "add", "origin", remote], { cwd: root });
+  await writeFile(path.join(root, "package.json"), JSON.stringify({ name: "shop", private: true, workspaces: ["apps/*", "packages/*"], devDependencies: { react: "19" } }));
+  await mkdir(path.join(root, "apps/web/src/app"), { recursive: true });
+  await writeFile(path.join(root, "apps/web/package.json"), JSON.stringify({ dependencies: { next: "16", react: "19" } }));
+  await mkdir(path.join(root, "apps/mobile"), { recursive: true });
+  await writeFile(path.join(root, "apps/mobile/package.json"), JSON.stringify({ dependencies: { expo: "54", "react-native": "0.81" } }));
+  await mkdir(path.join(root, "packages/ui"), { recursive: true });
+  await writeFile(path.join(root, "packages/ui/package.json"), JSON.stringify({ name: "ui", peerDependencies: { react: "19" } }));
+  await mkdir(path.join(root, "apps/web/node_modules/next"), { recursive: true });
+  await writeFile(path.join(root, "apps/web/node_modules/next/package.json"), JSON.stringify({ dependencies: { react: "19" } }));
+  return root;
+}
+
+function captureConsole() {
+  const lines: string[] = [];
+  const original = { log: console.log, warn: console.warn };
+  console.log = (...args: unknown[]) => lines.push(args.join(" "));
+  console.warn = (...args: unknown[]) => lines.push(args.join(" "));
+  return { lines, restore: () => Object.assign(console, original) };
+}
+
+test("a monorepo's apps are found separately, and a workspace root isn't one of them", async () => {
+  const root = await monorepo();
+  try {
+    assert.deepEqual(discoverApps(root), [
+      { path: "apps/mobile", kind: "mobile", framework: "Expo" },
+      { path: "apps/web", kind: "web", framework: "Next.js" },
+    ]);
+    const atRoot = detectProjectIdentity({ cwd: root });
+    assert.equal(atRoot.reason, "ambiguous", "never collapses two apps into one project");
+    assert.equal(atRoot.identity, null);
+    assert.match(describeDetection(atRoot).join("\n"), /has 2 apps: apps\/mobile \(Expo\), apps\/web \(Next\.js\)[\s\S]*--app-path/);
+
+    const inWeb = detectProjectIdentity({ cwd: path.join(root, "apps/web/src/app") });
+    assert.deepEqual(inWeb.identity, { kind: "repo", remote: "github.com/acme/shop", appPath: "apps/web" });
+    assert.equal(inWeb.preview?.key, "repo:github.com/acme/shop#apps/web");
+    assert.doesNotMatch(JSON.stringify(inWeb.identity), /ghp_secret|ada/, "the remote's credentials never leave the machine");
+
+    const chosen = detectProjectIdentity({ cwd: root, appPath: "apps/mobile", appUrl: "http://localhost:8081" });
+    assert.deepEqual(chosen.identity, { kind: "repo", remote: "github.com/acme/shop", appPath: "apps/mobile", appUrl: "http://localhost:8081" });
+    assert.equal(chosen.app?.kind, "mobile");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("without a remote, a public URL identifies the app by domain; data projects are out of scope", async () => {
+  const app = await mkdtemp(path.join(os.tmpdir(), "bugmole-identity-solo-"));
+  const data = await mkdtemp(path.join(os.tmpdir(), "bugmole-identity-data-"));
+  try {
+    execFileSync("git", ["init", "-q"], { cwd: app });
+    await writeFile(path.join(app, "package.json"), JSON.stringify({ dependencies: { vue: "3" } }));
+    assert.equal(detectProjectIdentity({ cwd: app }).reason, "unidentified");
+    assert.deepEqual(detectProjectIdentity({ cwd: app, appUrl: "https://www.shop.example.com/cart" }).preview?.key, "domain:shop.example.com");
+
+    await writeFile(path.join(data, "train.ipynb"), "{}");
+    await writeFile(path.join(data, "requirements.txt"), "pandas\ntorch\n");
+    const detection = detectProjectIdentity({ cwd: data });
+    assert.equal(detection.reason, "no_app");
+    assert.ok(describeDetection(detection).includes(SCOPE_MESSAGE));
+    assert.match(SCOPE_MESSAGE, /web apps and mobile apps \(Android and iOS\).*out of scope/);
+  } finally {
+    await rm(app, { recursive: true, force: true });
+    await rm(data, { recursive: true, force: true });
+  }
+});
+
+test("bugmole init says when there's no web or mobile app to test", async () => {
+  const cwd = await mkdtemp(path.join(os.tmpdir(), "bugmole-init-scope-"));
+  const output = captureConsole();
+  try {
+    await runInitWizard({ cwd, nonInteractive: true });
+  } finally {
+    output.restore();
+    await rm(cwd, { recursive: true, force: true });
+  }
+  assert.ok(output.lines.includes(SCOPE_MESSAGE), output.lines.join("\n"));
+});
+
+test("bugmole init sends the app's identity and joins the project that already exists for it", async () => {
+  const root = await monorepo();
+  const cwd = path.join(root, "apps/web");
+  const saved = { key: process.env.BUGMOLE_API_KEY, registry: process.env.BUGMOLE_REGISTRY_URL };
+  const realFetch = globalThis.fetch;
+  const sent: Array<Record<string, any>> = [];
+  process.env.BUGMOLE_API_KEY = "bm_live_test";
+  process.env.BUGMOLE_REGISTRY_URL = "https://registry.test";
+  globalThis.fetch = (async (_url: string, init: RequestInit) => {
+    sent.push(JSON.parse(String(init.body)));
+    return Response.json({ project: { id: "shop-web" }, existing: true }, { status: 200 });
+  }) as typeof fetch;
+  const output = captureConsole();
+  try {
+    const result = await runInitWizard({ cwd, nonInteractive: true, projectId: "my-copy" });
+    assert.equal(result.config.projectId, "shop-web");
+    assert.equal(result.config.appPath, "apps/web");
+    const config = await readFile(path.join(cwd, result.configPath), "utf8");
+    assert.match(config, /^project:\n  id: shop-web$/m);
+    assert.match(config, /app_path: "apps\/web"/);
+    assert.match(await readFile(path.join(cwd, result.envPath), "utf8"), /^BUGMOLE_PROJECT_ID=shop-web$/m);
+  } finally {
+    output.restore();
+    globalThis.fetch = realFetch;
+    for (const [name, value] of [["BUGMOLE_API_KEY", saved.key], ["BUGMOLE_REGISTRY_URL", saved.registry]] as const) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+    await rm(root, { recursive: true, force: true });
+  }
+  assert.deepEqual(sent[0].identity, { kind: "repo", remote: "github.com/acme/shop", appPath: "apps/web" });
+  assert.match(output.lines.join("\n"), /Found a web app \(Next\.js\) at apps\/web/);
+  assert.match(output.lines.join("\n"), /already project shop-web in the workspace; joined it/);
+});
+
+test("a paused project is its own refusal: serve prints the activation link instead of treating it as a lost claim", async () => {
+  const paused = new RegistryRequestError(409, "project_inactive", "This project is paused", { activateUrl: "https://dash.test/?project=shop" });
+  assert.equal(isClaimConflict(paused), false);
+  assert.equal(isClaimConflict(new RegistryRequestError(409)), true);
+  assert.match(paused.message, /This project is paused \(409 project_inactive\)/);
+  assert.equal(
+    projectInactiveMessage("shop", "https://dash.test/?project=shop"),
+    "Project shop is paused because nobody used it for a while, so it won't run tests or tasks. A project member can activate it: https://dash.test/?project=shop.",
+  );
+
+  const root = await monorepo();
+  const logged: string[] = [];
+  const log = { log: (line: string) => logged.push(line), warn: (line: string) => logged.push(line) };
+  const reported: unknown[] = [];
+  try {
+    await announceProjectIdentity({
+      reportIdentity: async (identity) => {
+        reported.push(identity);
+        return { identity: null, inactiveAt: "2026-09-01T00:00:00Z", activateUrl: "https://dash.test/?project=shop" };
+      },
+    }, "shop", { cwd: root, appPath: "apps/web" }, log);
+    await announceProjectIdentity({
+      reportIdentity: async () => {
+        throw new RegistryRequestError(409, "identity_mismatch", "This project is github.com/acme/shop (apps/web), not github.com/acme/shop (apps/mobile).");
+      },
+    }, "shop", { cwd: root, appPath: "apps/mobile" }, log);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+  assert.deepEqual(reported, [{ kind: "repo", remote: "github.com/acme/shop", appPath: "apps/web" }]);
+  assert.match(logged[0], /Project shop is paused .* activate it: https:\/\/dash\.test\/\?project=shop/);
+  assert.match(logged[1], /not github\.com\/acme\/shop \(apps\/mobile\)/);
+});

package/src/runtime/project-identity.ts

@@ -0,0 +1,232 @@
+/**
+ * Which app the CLI is running in, and so which Bugmole project it belongs to.
+ *
+ * One app is one project. A local app is identified by its git repository
+ * (the normalized remote, never its credentials) plus the app's folder in it,
+ * so two teammates who clone the same repository pair with the same project,
+ * and each app of a monorepo gets its own. With no git remote, a public app
+ * URL identifies it by domain instead. See src/registry/project-identity.ts.
+ *
+ * Bugmole tests web apps and mobile apps (Android, iOS). A repository with
+ * neither, such as a data pipeline or a model, is out of scope; `bugmole init`
+ * says so rather than guessing.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  describeIdentity,
+  domainIdentityFromUrl,
+  normalizeAppPath,
+  normalizeGitRemote,
+  repoIdentity,
+  type ProjectIdentity,
+  type ProjectIdentityInput,
+} from "../registry/project-identity.js";
+
+export type AppKind = "web" | "mobile";
+
+export type DetectedApp = {
+  /** The app's folder relative to the repository root (POSIX); "." for the root. */
+  path: string;
+  kind: AppKind;
+  /** What gave it away, e.g. "Next.js", "Android", "Expo". */
+  framework: string;
+};
+
+export type ProjectIdentityDetection = {
+  /** What the CLI sends the registry (credential-free); null when nothing identifies the app. */
+  identity: ProjectIdentityInput | null;
+  /** The identity as the registry will store it, for messages. */
+  preview: ProjectIdentity | null;
+  /** The app the CLI is in, when it could tell. */
+  app: DetectedApp | null;
+  /** Every web or mobile app found in the repository. */
+  apps: DetectedApp[];
+  repoRoot: string;
+  /** Why there is no identity: no web/mobile app, several apps and no way to pick, or no remote and no public URL. */
+  reason?: "no_app" | "ambiguous" | "unidentified";
+  /** The --app-url given, when nothing in the folder is an app. */
+  appUrl?: string;
+};
+
+export const SCOPE_MESSAGE =
+  "Bugmole tests web apps and mobile apps (Android and iOS). Data and AI projects, such as notebooks, pipelines and models, are out of scope.";
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache", "coverage",
+  "vendor", "Pods", "DerivedData", ".gradle", ".idea", ".vscode", "target", "__pycache__", ".venv", "venv", "tmp",
+]);
+
+const WEB_DEPENDENCIES: Array<[string, string]> = [
+  ["next", "Next.js"], ["nuxt", "Nuxt"], ["@sveltejs/kit", "SvelteKit"], ["@remix-run/react", "Remix"], ["astro", "Astro"],
+  ["gatsby", "Gatsby"], ["@angular/core", "Angular"], ["vue", "Vue"], ["svelte", "Svelte"], ["solid-js", "Solid"],
+  ["preact", "Preact"], ["ember-source", "Ember"], ["@builder.io/qwik", "Qwik"], ["react-dom", "React"], ["vite", "Vite"],
+  // Server-rendered sites: their pages come from the server, not a front-end framework.
+  ["express", "Express"], ["fastify", "Fastify"], ["koa", "Koa"], ["hono", "Hono"], ["@hapi/hapi", "hapi"], ["@nestjs/core", "NestJS"],
+];
+const MOBILE_DEPENDENCIES: Array<[string, string]> = [["expo", "Expo"], ["react-native", "React Native"], ["@capacitor/core", "Capacitor"], ["@ionic/core", "Ionic"]];
+
+function readJson(file: string): Record<string, any> | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, any>;
+  } catch {
+    return null;
+  }
+}
+
+function readText(file: string): string {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** Whether a folder is a web or mobile app by what it contains, or null. */
+export function classifyApp(dir: string): { kind: AppKind; framework: string } | null {
+  const pkg = readJson(path.join(dir, "package.json"));
+  if (pkg) {
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) } as Record<string, unknown>;
+    const mobile = MOBILE_DEPENDENCIES.find(([name]) => name in deps);
+    if (mobile) return { kind: "mobile", framework: mobile[1] };
+    const web = WEB_DEPENDENCIES.find(([name]) => name in deps);
+    if (web) return { kind: "web", framework: web[1] };
+  }
+  if (/flutter\s*:/.test(readText(path.join(dir, "pubspec.yaml")))) return { kind: "mobile", framework: "Flutter" };
+  for (const gradle of ["build.gradle", "build.gradle.kts", "app/build.gradle", "app/build.gradle.kts"]) {
+    if (/com\.android\.application/.test(readText(path.join(dir, gradle)))) return { kind: "mobile", framework: "Android" };
+  }
+  let entries: fs.Dirent[] = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  if (entries.some((entry) => entry.isDirectory() && /\.(xcodeproj|xcworkspace)$/.test(entry.name))) return { kind: "mobile", framework: "iOS" };
+  if (fs.existsSync(path.join(dir, "manage.py")) && /django/i.test(readText(path.join(dir, "manage.py")))) return { kind: "web", framework: "Django" };
+  if (fs.existsSync(path.join(dir, "config", "routes.rb"))) return { kind: "web", framework: "Rails" };
+  if (fs.existsSync(path.join(dir, "artisan"))) return { kind: "web", framework: "Laravel" };
+  if (fs.existsSync(path.join(dir, "index.html")) || fs.existsSync(path.join(dir, "public", "index.html"))) return { kind: "web", framework: "Static site" };
+  return null;
+}
+
+/** A workspace root (npm/yarn/pnpm workspaces, Turborepo, Nx, Lerna) holds apps; it isn't one. */
+function isWorkspaceRoot(dir: string): boolean {
+  const pkg = readJson(path.join(dir, "package.json"));
+  if (pkg?.workspaces) return true;
+  return ["pnpm-workspace.yaml", "turbo.json", "nx.json", "lerna.json"].some((file) => fs.existsSync(path.join(dir, file)));
+}
+
+/** Every web or mobile app in a repository, outermost first; an app's own subfolders aren't searched. */
+export function discoverApps(repoRoot: string, maxDepth = 4): DetectedApp[] {
+  const apps: DetectedApp[] = [];
+  const visit = (dir: string, depth: number) => {
+    const relative = path.relative(repoRoot, dir).split(path.sep).join("/") || ".";
+    if (!(depth === 0 && isWorkspaceRoot(dir))) {
+      const found = classifyApp(dir);
+      if (found) {
+        apps.push({ path: relative, ...found });
+        return;
+      }
+    }
+    if (depth >= maxDepth) return;
+    let entries: fs.Dirent[] = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+      visit(path.join(dir, entry.name), depth + 1);
+    }
+  };
+  visit(repoRoot, 0);
+  return apps;
+}
+
+function git(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8", timeout: 5_000 }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The repository root containing `cwd`, or null outside a git checkout. */
+export function gitRoot(cwd: string): string | null {
+  const root = git(cwd, ["rev-parse", "--show-toplevel"]);
+  return root ? fs.realpathSync(root) : null;
+}
+
+/** The repository's remote ("origin", else the first one), normalized: no credentials ever leave the machine. */
+export function gitRemote(repoRoot: string): string | null {
+  const origin = git(repoRoot, ["remote", "get-url", "origin"]);
+  if (origin) return normalizeGitRemote(origin);
+  const first = git(repoRoot, ["remote"])?.split(/\r?\n/)[0]?.trim();
+  return first ? normalizeGitRemote(git(repoRoot, ["remote", "get-url", first])) : null;
+}
+
+/**
+ * Works out which app `cwd` is: the app folder that contains it, the app
+ * named by `appPath`, or the repository's only app. With several apps and no
+ * way to choose, it doesn't pick one (so apps are never collapsed into one
+ * project) and reports "ambiguous".
+ */
+export function detectProjectIdentity(options: { cwd: string; appPath?: string; appUrl?: string }): ProjectIdentityDetection {
+  const cwd = fs.realpathSync(options.cwd);
+  const repoRoot = gitRoot(cwd) ?? cwd;
+  const apps = discoverApps(repoRoot);
+  let app: DetectedApp | null = null;
+  const requested = options.appPath !== undefined ? normalizeAppPath(options.appPath) : undefined;
+  if (requested) {
+    const classified = classifyApp(path.join(repoRoot, requested));
+    app = apps.find((item) => item.path === requested) ?? (classified ? { path: requested, ...classified } : null);
+  } else {
+    const here = path.relative(repoRoot, cwd).split(path.sep).join("/") || ".";
+    // The deepest app folder that contains the working directory.
+    app = apps
+      .filter((item) => item.path === "." || here === item.path || here.startsWith(`${item.path}/`))
+      .sort((a, b) => b.path.length - a.path.length)[0] ?? null;
+    if (!app && here === "." && apps.length === 1) app = apps[0];
+  }
+  const base = { app, apps, repoRoot };
+  if (!app && apps.length > 1 && !requested) return { ...base, identity: null, preview: null, reason: "ambiguous" };
+  if (!app && !apps.length) {
+    // Still identifiable by a public URL, but nothing here looks like a web or mobile app.
+    const byUrl = domainIdentityFromUrl(options.appUrl);
+    return { ...base, identity: byUrl ? { appUrl: options.appUrl } : null, preview: byUrl, reason: "no_app", ...(options.appUrl ? { appUrl: options.appUrl } : {}) };
+  }
+  const remote = gitRemote(repoRoot);
+  const appPath = app?.path ?? requested ?? ".";
+  const preview = remote ? repoIdentity(remote, appPath, options.appUrl) : null;
+  if (preview) {
+    return { ...base, identity: { kind: "repo", remote, appPath, ...(preview.origin ? { appUrl: preview.origin } : {}) }, preview };
+  }
+  const byUrl = domainIdentityFromUrl(options.appUrl);
+  if (byUrl) return { ...base, identity: { appUrl: byUrl.origin ?? undefined }, preview: byUrl };
+  return { ...base, identity: null, preview: null, reason: "unidentified" };
+}
+
+/** The lines `bugmole init` prints about which app it found. */
+export function describeDetection(detection: ProjectIdentityDetection): string[] {
+  if (detection.reason === "no_app") {
+    if (detection.appUrl) return [`Nothing in ${detection.repoRoot} looks like a web or mobile app; Bugmole will test the app at ${detection.appUrl}.`];
+    return [
+      `No web or mobile app found in ${detection.repoRoot}. If it serves a website, pass its address with --app-url.`,
+      SCOPE_MESSAGE,
+    ];
+  }
+  if (detection.reason === "ambiguous") {
+    return [
+      `This repository has ${detection.apps.length} apps: ${detection.apps.map((app) => `${app.path} (${app.framework})`).join(", ")}.`,
+      "Each app is its own Bugmole project. Run `bugmole init` in the app's folder, or pass --app-path <folder>.",
+    ];
+  }
+  const lines: string[] = [];
+  if (detection.app) lines.push(`Found a ${detection.app.kind} app (${detection.app.framework}) at ${detection.app.path}.`);
+  if (detection.preview) lines.push(`This project is ${describeIdentity(detection.preview)}; teammates who clone the same repository join it.`);
+  else lines.push("No git remote or public app URL identifies this app yet; add a remote so teammates join the same project.");
+  return lines;
+}

package/src/runtime/project-roles.test.ts

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import YAML from "yaml";
+import {
+  collectRoleSuggestions, holdAgentRoleWrites, projectActorProblem, projectRoles, proposeRoleSuggestions, readSpecRoles, rolesClient,
+} from "./project-roles.js";
+
+async function specDir(files: Record<string, string>) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-roles-"));
+  for (const [name, content] of Object.entries(files)) await fs.writeFile(path.join(directory, name), content);
+  return directory;
+}
+
+const ROLES_YAML = [
+  "roles:",
+  "  - name: user",
+  "    description: Signed-in user.",
+  "  - name: admin",
+  "    description: Admin.",
+  "    status: suggested",
+  "  - name: robot",
+  "    status: rejected",
+].join("\n");
+
+test("roles.yaml entries without a status are confirmed; suggested and rejected ones aren't usable", async () => {
+  const dir = await specDir({ "roles.yaml": ROLES_YAML });
+  assert.deepEqual(readSpecRoles(dir).map((role) => `${role.name}:${role.status}`), ["user:confirmed", "admin:suggested", "robot:rejected"]);
+  const roles = await projectRoles({ runtime: { spec_dir: dir } }, null);
+  assert.deepEqual(roles.usable, ["user"]);
+  assert.deepEqual(roles.suggested, ["admin"]);
+  assert.equal(projectActorProblem(roles, "user"), null);
+  assert.match(projectActorProblem(roles, "admin")!, /only suggested/);
+  assert.match(projectActorProblem(roles, "robot")!, /rejected/);
+});
+
+test("a person's decision in the dashboard wins over roles.yaml", async () => {
+  const dir = await specDir({ "roles.yaml": ROLES_YAML });
+  const client = {
+    listRoles: async () => ({
+      roles: [
+        { id: "r1", name: "admin", description: "Admin.", status: "confirmed" as const, source: "role_gated_route", evidence: "route /admin" },
+        { id: "r2", name: "user", description: "User.", status: "rejected" as const, source: "spec", evidence: null },
+      ],
+    }),
+  };
+  const roles = await projectRoles({ runtime: { spec_dir: dir } }, client);
+  assert.deepEqual(roles.usable, ["admin"]);
+  assert.match(projectActorProblem(roles, "user")!, /rejected/);
+
+  const down = await projectRoles({ runtime: { spec_dir: dir } }, { listRoles: async () => { throw new Error("offline"); } });
+  assert.equal(down.registryRead, false);
+  assert.deepEqual(down.usable, ["user"], "without the registry, roles.yaml decides");
+});
+
+test("only a machine with an API key and a project asks the registry", () => {
+  assert.equal(rolesClient({ project: { id: "shop" } }, {}), null);
+  assert.equal(rolesClient({}, { BUGMOLE_API_KEY: "bm_x" }), null);
+  assert.ok(rolesClient({ project: { id: "shop" } }, { BUGMOLE_API_KEY: "bm_x" }));
+});
+
+test("an agent writing roles.yaml can only suggest: new or promoted roles are held back", () => {
+  const next = [
+    "roles:",
+    "  - name: user",
+    "  - name: admin",
+    "  - name: robot",
+    "  - name: support",
+    "    status: suggested",
+  ].join("\n");
+  const { content, heldBack } = holdAgentRoleWrites(ROLES_YAML, next);
+  assert.deepEqual(heldBack, ["admin", "robot"]);
+  const written = YAML.parse(content).roles as Array<{ name: string; status?: string }>;
+  assert.equal(written.find((role) => role.name === "user")!.status, undefined, "a confirmed role is left as it was");
+  assert.equal(written.find((role) => role.name === "admin")!.status, "suggested");
+  assert.equal(written.find((role) => role.name === "robot")!.status, "rejected", "a rejected role stays rejected");
+  assert.equal(written.find((role) => role.name === "support")!.status, "suggested");
+
+  const fresh = holdAgentRoleWrites(null, "roles:\n  - name: guest\n");
+  assert.deepEqual(fresh.heldBack, ["guest"]);
+  assert.equal(holdAgentRoleWrites(null, "not: [valid").heldBack.length, 0, "unparseable content is left to the writer");
+});
+
+test("discovery evidence turns into suggestions, and settled roles are not re-proposed", async () => {
+  const graph = {
+    nodes: [{ id: "screen:/login", route: "/login" }, { id: "screen:/admin", route: "/admin" }],
+    edges: [],
+    journeys: [{ id: "flow:login", name: "Login", actor: "user" }],
+  };
+  const dir = await specDir({ "journeys.graph.json": JSON.stringify(graph), "roles.yaml": ROLES_YAML });
+  const suggestions = collectRoleSuggestions({ runtime: { spec_dir: dir } });
+  assert.deepEqual(suggestions.map((item) => item.name).sort(), ["admin", "guest", "member", "user"]);
+
+  const sent: string[] = [];
+  const results = await proposeRoleSuggestions(suggestions, {
+    proposeRole: async (input) => {
+      sent.push(input.name);
+      if (input.name === "guest") throw new Error("Registry request failed (500)");
+      return { role: { id: `r-${input.name}`, name: input.name, description: input.description, status: "suggested", source: input.source, evidence: input.evidence } };
+    },
+  }, ["user"]);
+  assert.ok(!sent.includes("user"), "a confirmed role isn't suggested again");
+  assert.equal(results.find((item) => item.name === "guest")!.status, "not_sent");
+  assert.equal(results.find((item) => item.name === "admin")!.status, "suggested");
+});

package/src/runtime/project-roles.ts

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { ControlPlaneClient, type RegistryRole } from "../registry/control-plane-client.js";
+import {
+  actorProblem, normalizeRoleName, specRoleStatus, suggestRoles, suggestedRoleNames, usableRoleNames,
+  type RoleRecord, type RoleSuggestion,
+} from "../registry/roles.js";
+
+/**
+ * The runtime side of roles (see src/registry/roles.ts): reading the
+ * project's spec/roles.yaml and the registry's decisions, telling the
+ * planner which actors it may use, and turning discovery evidence into
+ * suggestions a person decides on.
+ */
+
+function readYaml(filePath: string): any {
+  try {
+    return YAML.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function specDirOf(cfg: any): string {
+  return cfg?.runtime?.spec_dir || "./spec";
+}
+
+/** spec/roles.yaml as role records; an entry without `status` is confirmed. */
+export function readSpecRoles(specDir: string): RoleRecord[] {
+  const doc = readYaml(path.join(specDir, "roles.yaml"));
+  if (!Array.isArray(doc?.roles)) return [];
+  return doc.roles
+    .filter((role: any) => typeof role?.name === "string")
+    .map((role: any) => ({
+      name: role.name,
+      description: typeof role.description === "string" ? role.description : null,
+      status: specRoleStatus(role),
+      source: "spec",
+    }));
+}
+
+/** A registry client when this machine has a project API key; otherwise null. */
+export function rolesClient(cfg: any, env: Record<string, string | undefined> = process.env): ControlPlaneClient | null {
+  const apiKey = env.BUGMOLE_API_KEY?.trim() || cfg?.registry?.api_key;
+  const projectId = cfg?.project?.id;
+  if (!apiKey || !projectId) return null;
+  const registryUrl = env.BUGMOLE_REGISTRY_URL?.trim() || cfg?.registry?.url || "https://api.bugmole.com";
+  return new ControlPlaneClient({ registryUrl, apiKey, projectId });
+}
+
+export type ProjectRoles = {
+  spec: RoleRecord[];
+  registry: RoleRecord[];
+  /** False when there is a registry but it couldn't be read; roles.yaml decided alone. */
+  registryRead: boolean;
+  usable: string[];
+  suggested: string[];
+};
+
+/** Everything the planner and pipeline need to know about roles right now. */
+export async function projectRoles(cfg: any, client: Pick<ControlPlaneClient, "listRoles"> | null = rolesClient(cfg)): Promise<ProjectRoles> {
+  const spec = readSpecRoles(specDirOf(cfg));
+  let registry: RoleRecord[] = [];
+  let registryRead = true;
+  if (client) {
+    try {
+      registry = (await client.listRoles()).roles.map((role: RegistryRole) => ({ name: role.name, description: role.description, status: role.status, source: role.source }));
+    } catch {
+      registryRead = false;
+    }
+  }
+  return { spec, registry, registryRead, usable: usableRoleNames(spec, registry), suggested: suggestedRoleNames(spec, registry) };
+}
+
+/** Why `actor` can't be planned for, or null when it is a confirmed role. */
+export function projectActorProblem(roles: ProjectRoles, actor: string): string | null {
+  return actorProblem(actor, roles.spec, roles.registry);
+}
+
+/** Suggestions from the project's journey graph, blockers and roles.yaml. */
+export function collectRoleSuggestions(cfg: any): RoleSuggestion[] {
+  const specDir = specDirOf(cfg);
+  const graph = readYaml(path.join(specDir, "journeys.graph.json"));
+  const blockers = readYaml(path.join(specDir, "blockers.yaml"));
+  const roles = readYaml(path.join(specDir, "roles.yaml"));
+  return suggestRoles({
+    nodes: Array.isArray(graph?.nodes) ? graph.nodes : [],
+    edges: Array.isArray(graph?.edges) ? graph.edges : [],
+    journeys: Array.isArray(graph?.journeys) ? graph.journeys : [],
+    blockers: Array.isArray(blockers?.blockers) ? blockers.blockers : [],
+    specRoles: Array.isArray(roles?.roles) ? roles.roles : [],
+  });
+}
+
+export type ProposedRole = { name: string; source: string; status: string; alreadyDecided?: boolean; error?: string };
+
+/**
+ * Sends each suggestion to the registry, where it waits for a person. Roles
+ * a person already decided on (or that roles.yaml already confirms) are
+ * left alone, so re-running discovery never re-asks a settled question.
+ */
+export async function proposeRoleSuggestions(
+  suggestions: RoleSuggestion[],
+  client: Pick<ControlPlaneClient, "proposeRole">,
+  alreadyUsable: string[] = [],
+): Promise<ProposedRole[]> {
+  const results: ProposedRole[] = [];
+  for (const suggestion of suggestions) {
+    if (alreadyUsable.includes(suggestion.name)) continue;
+    try {
+      const { role, alreadyDecided } = await client.proposeRole(suggestion);
+      results.push({ name: role.name, source: suggestion.source, status: role.status, ...(alreadyDecided ? { alreadyDecided } : {}) });
+    } catch (error) {
+      results.push({ name: suggestion.name, source: suggestion.source, status: "not_sent", error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return results;
+}
+
+/**
+ * An agent writing spec/roles.yaml may add roles, but only as suggestions:
+ * any role it adds, or tries to promote to confirmed, is written
+ * `status: suggested` (a rejected one stays rejected). Roles a person
+ * already confirmed are kept as they were. Returns the content to write and
+ * the names it held back.
+ */
+export function holdAgentRoleWrites(previous: string | null, next: string): { content: string; heldBack: string[] } {
+  let doc: any;
+  try {
+    doc = YAML.parse(next);
+  } catch {
+    return { content: next, heldBack: [] };
+  }
+  if (!Array.isArray(doc?.roles)) return { content: next, heldBack: [] };
+  let before: any = null;
+  try {
+    before = previous ? YAML.parse(previous) : null;
+  } catch {
+    before = null;
+  }
+  const previousStatus = new Map<string, string>();
+  for (const role of Array.isArray(before?.roles) ? before.roles : []) {
+    if (typeof role?.name === "string") previousStatus.set(normalizeRoleName(role.name) ?? role.name, specRoleStatus(role));
+  }
+  const heldBack: string[] = [];
+  for (const role of doc.roles) {
+    if (typeof role?.name !== "string") continue;
+    const key = normalizeRoleName(role.name) ?? role.name;
+    const wanted = specRoleStatus(role);
+    const had = previousStatus.get(key);
+    if (wanted !== "confirmed") continue;
+    if (had === "confirmed") continue;
+    role.status = had === "rejected" ? "rejected" : "suggested";
+    heldBack.push(role.name);
+  }
+  return heldBack.length ? { content: YAML.stringify(doc), heldBack } : { content: next, heldBack };
+}