@bugmole/cli 0.4.0 → 0.6.0

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 };
+}

package/src/runtime/propose-cli.ts

@@ -0,0 +1,66 @@
+// `bugmole propose <file>`: a developer proposes test-case changes from a
+// file, the way an agent does with bugmole_propose_test_case.
+//
+//   { "caseSetId": "login", "summary": "Why, for every change below",
+//     "changes": [ { "caseId": "TC-login", "action": "change", "case": { ... } },
+//                  { "caseId": "TC-old", "action": "retire", "summary": "Why this one" } ] }
+//
+// Each change names its case; the revision being changed is read from the
+// project's storage, so the file never has to track revision numbers.
+import fs from "node:fs";
+import { ControlPlaneClient, type RegistryProposal } from "../registry/control-plane-client.js";
+import { activeRevision, caseProblem, revisionOf, type CaseSetDocument } from "../registry/test-case-revisions.js";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import { applyAcceptedProposals } from "./apply-proposals.js";
+
+type ProposalFile = {
+  caseSetId?: unknown;
+  summary?: unknown;
+  changes?: Array<{ caseId?: unknown; action?: unknown; case?: Record<string, unknown>; summary?: unknown }>;
+};
+
+export function registryClient(cfg: any, env: Record<string, string | undefined> = process.env): ControlPlaneClient {
+  const apiKey = env.BUGMOLE_API_KEY ?? cfg.registry?.api_key;
+  if (!apiKey) throw new Error("BUGMOLE_API_KEY is required to propose changes");
+  if (!cfg.project?.id) throw new Error("A project id is required to propose changes");
+  return new ControlPlaneClient({ registryUrl: env.BUGMOLE_REGISTRY_URL ?? cfg.registry?.url ?? "https://api.bugmole.com", apiKey, projectId: cfg.project.id });
+}
+
+/** Proposes every change in the file; stops at the first invalid one before sending anything. */
+export async function proposeFromFile(cfg: any, filePath: string, client: Pick<ControlPlaneClient, "proposeTestCaseChange" | "listUnappliedProposals" | "reportProposalApplied"> = registryClient(cfg)): Promise<RegistryProposal[]> {
+  const file = JSON.parse(fs.readFileSync(filePath, "utf8")) as ProposalFile;
+  const caseSetId = typeof file.caseSetId === "string" ? file.caseSetId : "";
+  if (!caseSetId) throw new Error(`${filePath}: caseSetId is required`);
+  if (!Array.isArray(file.changes) || !file.changes.length) throw new Error(`${filePath}: changes must list at least one change`);
+  const store = createProjectObjectStore(cfg);
+  const key = `${projectPrefix(cfg.project?.id ?? "default")}/test-cases/${caseSetId}.json`;
+  if (!(await store.has(key))) throw new Error(`There's no case set ${caseSetId} in this project's storage`);
+  const caseSet = JSON.parse(await store.getText(key)) as CaseSetDocument;
+
+  const requests = file.changes.map((change, index) => {
+    const where = `${filePath}: change ${index + 1}`;
+    const caseId = typeof change.caseId === "string" ? change.caseId : "";
+    const action = change.action as "add" | "change" | "retire";
+    const summary = typeof change.summary === "string" && change.summary.trim() ? change.summary : typeof file.summary === "string" ? file.summary : "";
+    if (action !== "add" && action !== "change" && action !== "retire") throw new Error(`${where}: action must be add, change or retire`);
+    if (!summary.trim()) throw new Error(`${where}: say why in summary`);
+    const current = activeRevision(caseSet, caseId);
+    if (action !== "add" && !current) throw new Error(`${where}: ${caseId} has no current revision`);
+    if (action === "add" && current) throw new Error(`${where}: ${caseId} already exists; use change`);
+    if (action !== "retire") {
+      const problem = caseProblem({ ...(change.case ?? {}), caseId } as never);
+      if (problem) throw new Error(`${where}: ${problem}`);
+    }
+    return {
+      caseSetId, caseId, action, summary, source: "cli" as const,
+      ...(current ? { baseRevision: revisionOf(current) } : {}),
+      ...(action !== "retire" ? { case: change.case } : {}),
+    };
+  });
+  const proposals: RegistryProposal[] = [];
+  for (const request of requests) proposals.push((await client.proposeTestCaseChange(request)).proposal);
+  // Accepted on arrival (extreme mode) on the project's own storage: write them now.
+  if (proposals.some((proposal) => proposal.status === "accepted" && !proposal.appliedAt)) await applyAcceptedProposals(cfg, client);
+  return proposals;
+}

package/src/runtime/record-run-verdicts.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { recordRunVerdicts } from "./record-run-verdicts.js";
+
+function setup() {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "bugmole-verdicts-"));
+  const cfg = { storage: { provider: "local", local: { directory } } };
+  const base = path.join(directory, "projects", "shop");
+  fs.mkdirSync(path.join(base, "test-cases"), { recursive: true });
+  fs.writeFileSync(path.join(base, "test-cases", "checkout-cases.json"), JSON.stringify({
+    caseSetId: "checkout-cases",
+    journeyId: "checkout",
+    cases: [
+      { caseId: "TC-login", nodeId: "screen:/login", title: "Sign in" },
+      { caseId: "TC-logout", nodeId: "screen:/logout", title: "Sign out" },
+    ],
+  }));
+  const read = (relative: string) => JSON.parse(fs.readFileSync(path.join(base, relative), "utf8"));
+  const history = () => fs.readdirSync(path.join(base, "test-case-history", "checkout-cases"));
+  return { cfg, directory, read, history };
+}
+
+test("a scoped retest judges only its cases and keeps every other case's latest verdict", async () => {
+  const { cfg, directory, read, history } = setup();
+  try {
+    const nodes = [
+      { nodeId: "screen:/login", outcome: "PASS" as const, status: "success" as const },
+      { nodeId: "screen:/logout", outcome: "FAIL" as const, status: "failed" as const, reason: { message: "Nothing happened" } },
+    ];
+    const full = await recordRunVerdicts(cfg, "shop", "checkout", nodes, "run_full");
+    assert.deepEqual(full, { caseSetId: "checkout-cases", judged: 2 });
+
+    const retest = await recordRunVerdicts(
+      cfg,
+      "shop",
+      "checkout",
+      [{ nodeId: "screen:/login", outcome: "FAIL", status: "failed" }, { nodeId: "screen:/logout", outcome: "PASS", status: "success" }],
+      "run_retest",
+      undefined,
+      { caseSetId: "checkout-cases", caseIds: ["TC-logout"] },
+    );
+    assert.deepEqual(retest, { caseSetId: "checkout-cases", judged: 1 });
+    const latest = read("test-case-results/checkout-cases.json");
+    assert.equal(latest.runId, "run_retest");
+    const byCase = Object.fromEntries(latest.results.map((item: { caseId: string; status: string }) => [item.caseId, item.status]));
+    assert.deepEqual(byCase, { "TC-login": "passed", "TC-logout": "passed" }, "the login verdict is the full run's, not the retest's");
+
+    const entries = history();
+    assert.equal(entries.length, 2);
+    const retestEntry = JSON.parse(fs.readFileSync(path.join(directory, "projects", "shop", "test-case-history", "checkout-cases", entries.find((name) => name.endsWith("-run_retest.json"))!), "utf8"));
+    assert.deepEqual(retestEntry.results.map((item: { caseId: string }) => item.caseId), ["TC-logout"], "history holds only what the retest judged");
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+});