@bugmole/cli 0.5.0 → 0.6.0

package/scripts/bugmole.ts

@@ -9,6 +9,7 @@ import dotenv from "dotenv";
 import YAML from "yaml";
 import { resolveLocalStorageDirectory } from "../src/storage/storage-directory.js";
 import { adoptLegacyEnv, preferExisting } from "../src/runtime/legacy-names.js";
+import { approvalModeOf, workerApprovalMode, type ApprovalMode } from "../src/registry/task-scheduling.js";
 
 type Mode =
   | "api-key"
@@ -25,10 +26,13 @@ type Mode =
   | "serve"
   | "gateway"
   | "run-once"
+  | "propose"
+  | "roles"
   | "reset"
   | "cursor-driver"
   | "suite"
-  | "init-env";
+  | "init-env"
+  | "secrets";
 
 function readArg(name: string, argv = process.argv): string | undefined {
   const i = argv.indexOf(name);
@@ -45,23 +49,42 @@ export function parseArgs(argv = process.argv): Record<string, any> {
   if (positionalCommand === "gateway") args.gateway = true;
   if (positionalCommand === "run-once") args.runonce = true;
   if (positionalCommand === "reset") args.reset = true;
+  if (positionalCommand === "roles") args.roles = true;
+  if (positionalCommand === "secrets") args.secrets = true;
+  if (positionalCommand === "propose") {
+    args.propose = true;
+    const file = argv.slice(argv.indexOf("propose") + 1).find((arg) => !arg.startsWith("--"));
+    if (file) args.proposefile = file;
+  }
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg.startsWith("--")) {
-      const key = arg.slice(2).replace(/-/g, "");
+      const name = arg.slice(2);
+      const key = name.replace(/-/g, "");
       const next = argv[i + 1];
       const value = next && !next.startsWith("--") ? next : true;
       if (value !== true) i++;
-      // Try to parse as number or boolean
-      if (value === true || value === "true") args[key] = true;
-      else if (value === "false") args[key] = false;
-      else if (!isNaN(Number(value))) args[key] = Number(value);
-      else args[key] = value;
+      // Only counts and durations become numbers: `--grep 404` or
+      // `--project 2024` are names, and must stay strings.
+      let parsed: unknown;
+      if (value === true || value === "true") parsed = true;
+      else if (value === "false") parsed = false;
+      else if (NUMERIC_FLAGS.has(key.toLowerCase()) && value.trim() !== "" && !isNaN(Number(value))) parsed = Number(value);
+      else parsed = value;
+      args[key] = parsed;
+      // Modes read either spelling: --file-path is args.filepath and args.filePath.
+      const camel = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+      if (camel !== key) args[camel] = parsed;
     }
   }
   return args;
 }
 
+const NUMERIC_FLAGS = new Set([
+  "timeout", "maxpages", "maxdepth", "localregistryport", "artifactport", "gatewayport", "pollinterval",
+  "nudgeinterval", "nudgemaxnudges", "nudgeinactivitythreshold", "nudgeprogressreporttimeout",
+]);
+
 export function printHelp(init = false): void {
   if (init) {
     console.log(`Usage: bugmole init [options]
@@ -71,40 +94,87 @@ Initialize .bugmole/config.yaml and .bugmole.env without reading credentials.
 Options:
   --non-interactive           Use defaults and never prompt
   --force                     Overwrite an existing configuration
-  --storage-provider <name>   local, gcs, s3, or r2
+  --storage-provider <name>   local, bugmole, gcs, s3, or r2
+  --bucket <name>             Bucket for gcs, s3 or r2
+  --region <region>           S3 region
+  --account-id <id>           R2 account ID
+  --cloud-project-id <id>     Google Cloud project for gcs
+  --endpoint <url>            Custom storage endpoint
+  --project-id <id>           Project identifier (default: the folder name)
+  --project-name <name>       Project display name
+  --environment <name>        Environment name (default: local)
+  --spec-dir <folder>         Where flows, plans and roles live (default: ./spec)
   --workspace-id <id>         Workspace identifier
   --workspace-name <name>     Workspace display name
   --app-id <id>               Default app identifier
   --app-name <name>           Default app display name
+  --app-path <folder>         The app's folder in a repository with several apps
+  --app-url <url>             The app's URL (a public one identifies the project by domain)
   --config <path>             Configuration output path
-  --help                      Show this help`);
+  --help                      Show this help
+
+Bugmole tests web apps and mobile apps (Android and iOS). One app is one
+project: a repository's git remote plus the app's folder identify it, so
+teammates who clone the same repository join the same project.`);
     return;
   }
   console.log(`Usage: bugmole [command] [options]
 
 Commands:
   init                        Initialize a project configuration
-  api-key create              Generate a one-time machine API key
+  api-key create              Generate a one-time machine API key (needs a key with keys:write;
+                                the dashboard's API keys page works without one)
+    --name <name>             What the key is for
+    --project-ids <ids>       Comma-separated projects it may use
   --mcp                       Start the MCP server
   artifacts serve             Serve local artifacts to the dashboard over loopback
     --artifact-port <port>    Loopback port (default: 3190)
     --dashboard-origin <url>  Allowed dashboard origin
+  propose <file.json>         Propose test-case changes (add, change, retire) for review;
+                                once accepted each becomes a new revision and the old one obsolete
+  secrets                     List the {{secret.NAME}}s your flows use and where each comes from
+  secrets set <NAME>          Keep a value in this machine's secure store (typed hidden, or piped on stdin)
+  secrets delete <NAME>       Remove it. Or map names to your vault (gcpsm://, awssm://, keychain://,
+                                env://) under secrets: in the config
+  roles                       List the project's roles: confirmed ones are used for test cases and runs
+  roles suggest <name>        Suggest a role for a person to confirm on the dashboard's Roles page
+    --evidence <text>         What points at it (a sign-in wall, a gated route or menu)
+    --description <text>      Who this is and what they can do
+    --from-evidence           Suggest every role the journey graph, blockers and roles.yaml imply
   serve                       Start the local artifact bridge and HTTP MCP server
     --no-open                  Print the dashboard handoff without opening a browser
+    --approval <mode>         manual | auto | extreme: only take tasks this mode would allow.
+                                Stricter than the project's mode, never looser (sets BUGMOLE_APPROVAL).
     --dashboard-url <url>     Dashboard URL for the handoff (overrides BUGMOLE_DASHBOARD_URL)
     --local-registry          Stand in for the real registry locally (overrides BUGMOLE_LOCAL_REGISTRY)
                                 so queueing tasks/runs and this worker executing them works without
-                                a real Aegis login or a BUGMOLE_API_KEY scoped to this project.
+                                signing in or a BUGMOLE_API_KEY scoped to this project.
     --local-registry-port     Local registry stub port (default: 4600, or BUGMOLE_LOCAL_REGISTRY_PORT)
   gateway                     Multiplex project serve workers over loopback
     --gateway-port <port>     Loopback port (default: 3191)
     --gateway-secret <value>  Shared secret for worker registration
   reset                       Delete current-project execution data after confirmation
+    --yes                     Skip the typed confirmation (scripts and CI)
   run-once                    Execute one Bugmole Cloud run and exit (used inside cloud runners;
                                 reads BUGMOLE_REGISTRY_URL, BUGMOLE_RUN_ID, BUGMOLE_RUN_TOKEN)
-  --mode <mode>               explore, plan, run, report, review, propose-diff, or suite
+  --mode <mode>               explore, plan, run, report, review, propose-diff, suite, or discover
+  --app-path <folder>         The app's folder in a repository with several apps
+  --app-url <url>             The app's URL
+  --timeout <ms>              How long a flow may take
+  --mode explore              Learn the app's screens from its source, or by crawling it
+    --base-url <url>          The running app
+  --mode plan                 Write a runnable plan for a journey
+    --journey-id <id>         The journey to plan
+    --actor <role>            A confirmed role to plan it for
+  --mode discover             Click through a running app and write a flow for each page and form
+    --base-url <url>          The running app
+    --out <dir>               Where to write the flows (required)
+    --sign-in <flow>          Sign in with this flow first, to explore the signed-in app
+    --max-pages <n>           Stop after this many pages
+    --max-depth <n>           Follow links at most this many clicks from the start
+    --open-each-page          Open every page directly as well as by clicking
   --mode suite                Run a directory of web flows against a running app
-    --flows <dir>             Flow directory (default: .maestro)
+    --flows <dir>             Flow directory (default: spec/flows, then flows, then .maestro)
     --base-url <url>          Application base URL (or BUGMOLE_BASE_URL)
     --artifacts-dir <dir>     Evidence directory (default: qa/bugmole-runs)
     --project <id>            Project id used in the evidence path
@@ -129,6 +199,9 @@ export function resolveMode(args: Record<string, any>): Mode {
   if (args.gateway === true) return "gateway";
   if (args.runonce === true) return "run-once";
   if (args.reset === true) return "reset";
+  if (args.propose === true) return "propose";
+  if (args.roles === true) return "roles";
+  if (args.secrets === true) return "secrets";
   if (args.artifacts === true) return "artifacts";
   return (args.mode ?? "mcp") as Mode;
 }
@@ -138,9 +211,10 @@ export function resolveMode(args: Record<string, any>): Mode {
 // step needs it to fail the build, so `--mode run` is the one mode whose exit code
 // reflects the result rather than just whether the process threw.
 export function runModeExitCode(mode: string, result: unknown): number {
-  if (mode !== "run") return 0;
   const status = result && typeof result === "object" ? (result as { status?: unknown }).status : undefined;
-  return status === "success" ? 0 : 1;
+  // A run passes only when it all passed; the other modes fail on an error.
+  if (mode === "run") return status === "success" ? 0 : 1;
+  return status === "error" ? 1 : 0;
 }
 
 export function shouldOpenServeBrowser(
@@ -210,6 +284,19 @@ export function resolveLocalRegistryEnabled(args: Record<string, any>): boolean
 // every fetch with "bad port" — 4190 is the reserved ManageSieve port).
 const DEFAULT_LOCAL_REGISTRY_PORT = 4600;
 
+/**
+ * `--approval manual|auto|extreme` for `bugmole serve`. It becomes
+ * BUGMOLE_APPROVAL so every part of this process (worker, MCP, the coding
+ * agent driver) holds back the same tasks. Returns null for a bad value.
+ */
+export function applyApprovalFlag(args: Record<string, any>, env: Record<string, string | undefined> = process.env): ApprovalMode | undefined | null {
+  if (args.approval === undefined) return workerApprovalMode(env);
+  const mode = approvalModeOf(typeof args.approval === "string" ? args.approval.trim() : "");
+  if (!mode) return null;
+  env.BUGMOLE_APPROVAL = mode;
+  return mode;
+}
+
 export function resolveLocalRegistryPort(args: Record<string, any>): number {
   if (typeof args.localregistryport === "number") return args.localregistryport;
   const fromEnv = process.env.BUGMOLE_LOCAL_REGISTRY_PORT?.trim();
@@ -352,6 +439,13 @@ async function main() {
   if (positionalCommand === "artifacts") args.artifacts = true;
   if (positionalCommand === "serve") args.serve = true;
   if (positionalCommand === "reset") args.reset = true;
+  if (positionalCommand === "roles") args.roles = true;
+  if (positionalCommand === "secrets") args.secrets = true;
+  if (positionalCommand === "propose") {
+    args.propose = true;
+    const file = process.argv.slice(process.argv.indexOf("propose") + 1).find((arg) => !arg.startsWith("--"));
+    if (file) args.proposefile = file;
+  }
   // quiet: dotenv 17 prints an "injected env" banner on every load, which
   // would land in the middle of this CLI's own output.
   dotenv.config({ path: preferExisting(".bugmole.env", ".valk.env"), quiet: true });
@@ -385,29 +479,38 @@ async function main() {
 
   // Init must run from the caller's workspace, not the package directory.
   if (resolveMode(args) === "init") {
-    const { runInitWizard } = await import("../src/runtime/init-wizard.js");
-    await runInitWizard({
-      nonInteractive: args.noninteractive === true,
-      force: args.force === true,
-      configPath: args.config,
-      workspaceId: args.workspaceid,
-      workspaceName: args.workspacename,
-      projectId: args.projectid,
-      projectName: args.projectname,
-      appId: args.appid,
-      appName: args.appname,
-      environment: args.environment,
-      specDir: args.specdir,
-      evidenceManifest: args.evidencemanifest,
-      evidenceScreenshots: args.evidencescreenshots,
-      artifactsDir: args.artifactsdir,
-      storageProvider: args.storageprovider,
-      bucket: args.bucket,
-      region: args.region,
-      endpoint: args.endpoint,
-      cloudProjectId: args.cloudprojectid,
-      accountId: args.accountid,
-    });
+    const { runInitWizard, PlanLimitError, describePlanLimit } = await import("../src/runtime/init-wizard.js");
+    try {
+      await runInitWizard({
+        nonInteractive: args.noninteractive === true,
+        force: args.force === true,
+        configPath: args.config,
+        workspaceId: args.workspaceid,
+        workspaceName: args.workspacename,
+        projectId: args.projectid,
+        projectName: args.projectname,
+        appId: args.appid,
+        appName: args.appname,
+        environment: args.environment,
+        specDir: args.specdir,
+        evidenceManifest: args.evidencemanifest,
+        evidenceScreenshots: args.evidencescreenshots,
+        artifactsDir: args.artifactsdir,
+        storageProvider: args.storageprovider,
+        bucket: args.bucket,
+        region: args.region,
+        endpoint: args.endpoint,
+        cloudProjectId: args.cloudprojectid,
+        accountId: args.accountid,
+        appPath: typeof args.apppath === "string" ? args.apppath : undefined,
+        appUrl: typeof args.appurl === "string" ? args.appurl : undefined,
+      });
+    } catch (error) {
+      // A plan limit is an answer, not a crash: say what the plan allows and where to upgrade.
+      if (!(error instanceof PlanLimitError)) throw error;
+      console.error(describePlanLimit(error));
+      process.exitCode = 1;
+    }
     return;
   }
 
@@ -449,23 +552,56 @@ async function main() {
     return;
   }
 
+  // Suite and discover run without a project configuration, but use its
+  // secrets: map when there is one, so flows can type values from a vault.
+  const flowSecrets = async (projectId: string) => {
+    const { secretMap } = await import("../src/runtime/secret-sources.js");
+    const { withFlowSecrets } = await import("../src/runtime/secret-driver.js");
+    let cfg: { secrets?: unknown; project?: { id?: string } } | null = null;
+    try {
+      if (fs.existsSync(path.resolve(workspaceRoot, configPath))) cfg = loadConfig(path.resolve(workspaceRoot, configPath));
+    } catch {
+      cfg = null;
+    }
+    const { map, problems } = secretMap(cfg);
+    for (const problem of problems) console.warn(`[Bugmole] ${problem}`);
+    const id = cfg?.project?.id ?? projectId;
+    return (driver: import("../src/runtime/driver.js").AppDriver) => withFlowSecrets(driver, { map, projectId: id });
+  };
+
   // A web suite is deterministic: it needs a running app and flow files, not
   // an LLM or a project configuration, so it runs in any workspace as-is.
   if (mode === "suite") {
     const { runWebSuite } = await import("../src/runtime/web-suite.js");
+    let configured: { project?: { id?: string }; runtime?: { spec_dir?: string } } | null = null;
+    try {
+      if (fs.existsSync(path.resolve(workspaceRoot, configPath))) configured = loadConfig(path.resolve(workspaceRoot, configPath));
+    } catch {
+      configured = null;
+    }
+    // Evidence goes under the project's ID, so reset finds it.
+    const suiteProject = typeof args.project === "string" ? args.project : configured?.project?.id ?? path.basename(workspaceRoot);
+    // The first flows folder that exists: spec/flows (where the docs put
+    // them), flows/, then .maestro.
+    const specFlows = path.join(configured?.runtime?.spec_dir ?? "spec", "flows");
+    const defaultFlows = [specFlows, "flows", ".maestro"].find((dir) => fs.existsSync(path.resolve(workspaceRoot, dir)));
+    if (typeof args.flows !== "string" && !defaultFlows) {
+      throw new Error(`No flows folder found (looked for ${specFlows}, flows and .maestro). Pass --flows <dir>.`);
+    }
     const { targetsFromFlags } = await import("../src/runtime/browser-matrix.js");
     const baseUrl = typeof args.baseurl === "string" ? args.baseurl : process.env.BUGMOLE_BASE_URL;
     if (!baseUrl) throw new Error("--base-url (or BUGMOLE_BASE_URL) is required for --mode suite");
     const report = await runWebSuite({
-      flowsDir: path.resolve(workspaceRoot, typeof args.flows === "string" ? args.flows : ".maestro"),
+      flowsDir: path.resolve(workspaceRoot, typeof args.flows === "string" ? args.flows : defaultFlows!),
       baseUrl,
       artifactsDir: path.resolve(workspaceRoot, typeof args.artifactsdir === "string" ? args.artifactsdir : preferExisting(path.join(workspaceRoot, "qa/bugmole-runs"), path.join(workspaceRoot, "qa/valkyrie-runs"))),
-      projectId: typeof args.project === "string" ? args.project : path.basename(workspaceRoot),
+      projectId: suiteProject,
       headless: args.headed !== true,
       timeoutMs: typeof args.timeout === "number" ? args.timeout : undefined,
       grep: typeof args.grep === "string" ? args.grep : undefined,
       shareSession: args.sharesession === true,
       targets: targetsFromFlags(args.browsers, args.devices),
+      wrapDriver: await flowSecrets(suiteProject),
     });
     const { total, passed, failed, blocked } = report.totals;
     console.log(`[Bugmole] Suite ${passed}/${total} passed (${failed} failed, ${blocked} blocked). Report: ${report.reportPath}`);
@@ -489,7 +625,8 @@ async function main() {
       if (typeof args.signin === "string") {
         const { PlaywrightDriver } = await import("../src/runtime/playwright-driver.js");
         storageState = path.join(sessionDir, "session-state.json");
-        const signIn = await new PlaywrightDriver({ headless: args.headed !== true }).run({
+        const projectId = typeof args.project === "string" ? args.project : path.basename(workspaceRoot);
+        const signIn = await (await flowSecrets(projectId))(new PlaywrightDriver({ headless: args.headed !== true })).run({
           runId: `discover-${Date.now()}`,
           projectId: typeof args.project === "string" ? args.project : path.basename(workspaceRoot),
           journeyId: "sign-in",
@@ -520,10 +657,25 @@ async function main() {
       }
       await fs.promises.writeFile(
         path.join(outDir, "discovery.json"),
-        `${JSON.stringify({ baseUrl: result.baseUrl, pages: result.pages.map(({ route, heading, title, path: via }) => ({ route, heading, title, via })), events: result.events }, null, 2)}\n`,
+        `${JSON.stringify({
+          baseUrl: result.baseUrl,
+          pages: result.pages.map(({ route, heading, title, path: via }) => ({ route, heading, title, via })),
+          limits: result.limits,
+          events: result.events,
+        }, null, 2)}\n`,
         "utf8",
       );
-      console.log(`[Bugmole] Discovered ${result.pages.length} pages and wrote ${result.flows.length} flows to ${path.relative(workspaceRoot, outDir) || "."}`);
+      // Flows found signed in only pass signed in: put the sign-in flow first
+      // in the folder, so a suite with --share-session signs in, then runs them.
+      if (typeof args.signin === "string") {
+        await fs.promises.copyFile(path.resolve(workspaceRoot, args.signin), path.join(outDir, "00-sign-in.yaml"));
+      }
+      const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? "" : "s"}`;
+      const outName = path.relative(workspaceRoot, outDir) || ".";
+      console.log(`[Bugmole] Discovered ${plural(result.pages.length, "page")} and wrote ${plural(result.flows.length, "flow")} to ${outName}`);
+      if (result.flows.length) {
+        console.log(`[Bugmole] Run them: bugmole --mode suite --flows ${outName} --base-url ${baseUrl}${typeof args.signin === "string" ? " --share-session" : ""}`);
+      }
       if (result.pages.length === 0) process.exitCode = 1;
     } finally {
       // Holds the app's cookies and tokens: never outlives the exploration.
@@ -549,7 +701,13 @@ async function main() {
   // Serve only needs the local runtime/storage and registry settings. Full
   // execution validation belongs to plan/run modes, which require LLM and
   // browser configuration that an idle worker does not use.
-  if (mode !== "serve" && mode !== "artifacts" && mode !== "explore") {
+  if (mode === "secrets") {
+    const { runSecretsCommand } = await import("../src/runtime/secrets-cli.js");
+    process.exitCode = await runSecretsCommand(cfg, process.argv, { workspaceRoot });
+    return;
+  }
+
+  if (mode !== "serve" && mode !== "artifacts" && mode !== "explore" && mode !== "roles") {
     const { validateConfigOrThrow } = await import("../src/runtime/config-validate.js");
     validateConfigOrThrow(cfg);
   }
@@ -563,7 +721,36 @@ async function main() {
 
   // Dispatch modes
   switch (mode) {
+    case "roles": {
+      const { parseRolesCommand, runRolesCommand } = await import("../src/runtime/roles-cli.js");
+      const command = parseRolesCommand(process.argv, args);
+      if ("error" in command) {
+        console.error(command.error);
+        process.exit(2);
+      }
+      for (const line of await runRolesCommand(cfg, command)) console.log(`[Bugmole] ${line}`);
+      return;
+    }
+    case "propose": {
+      if (typeof args.proposefile !== "string") {
+        console.error("Usage: bugmole propose <changes.json>");
+        process.exit(2);
+      }
+      const { proposeFromFile } = await import("../src/runtime/propose-cli.js");
+      const proposals = await proposeFromFile(cfg, args.proposefile);
+      for (const proposal of proposals) {
+        const state = proposal.status === "pending" ? "waiting for a manager's review" : proposal.status;
+        console.log(`[Bugmole] ${proposal.action} ${proposal.caseSetId}/${proposal.caseId}: ${state} (${proposal.id})`);
+      }
+      return;
+    }
     case "serve": {
+      const approval = applyApprovalFlag(args);
+      if (approval === null) {
+        console.error("[Bugmole] --approval must be manual, auto or extreme");
+        process.exit(2);
+      }
+      if (approval) console.log(`[Bugmole] Approval: ${approval}. This worker waits for a person's approval on ${approval === "manual" ? "every task" : approval === "auto" ? "tasks that change code" : "nothing"}, whatever the project allows.`);
       const remoteStorage = Boolean(cfg.storage?.provider && cfg.storage.provider !== "local");
       let closeBridge: () => void = () => {};
       if (remoteStorage) {
@@ -602,7 +789,7 @@ async function main() {
         console.log(`[Bugmole] MCP will start on the configured HTTP port`);
         console.log(`[Bugmole] Capability expires at ${bridge.expiresAt}`);
         if (!process.env.BUGMOLE_AEGIS_EMAIL?.trim()) {
-          console.warn("[Bugmole] No BUGMOLE_AEGIS_EMAIL found; enter your Aegis email on the login page to generate rid.");
+          console.warn("[Bugmole] Sign in with your Bugmole account email on the page that opens.");
         }
         console.log(
           `[Bugmole] Dashboard handoff: ${buildDashboardHandoffUrl(dashboardHandoff.toString(), cfg.project?.id ?? "default", fragment)}`,
@@ -711,7 +898,7 @@ async function startMcpServerForServe(cfg: any): Promise<void> {
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   main().catch((err) => {
-    console.error(`[Bugmole MCP] fatal: ${err?.message ?? err}`);
+    console.error(`[Bugmole] ${err?.message ?? err}`);
     process.exit(1);
   });
 }

package/scripts/sync-byok.d.mts

@@ -0,0 +1,2 @@
+export const byokCopy: string;
+export const BYOK_HEADER: string;

package/scripts/sync-byok.mjs

@@ -0,0 +1,18 @@
+// Vendors Arcana's bring-your-own-vault resolver (packages/byok/src/byok.ts
+// in theaiinc/arcana) into src/vendor/byok.ts, verbatim under a header. It is
+// one dependency-free file, so the CLI ships it without the Arcana app.
+//   ARCANA_DIR=~/arcana node scripts/sync-byok.mjs
+import { readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "..");
+export const byokCopy = path.join(root, "src/vendor/byok.ts");
+export const BYOK_HEADER = "// VENDORED from theaiinc/arcana packages/byok/src/byok.ts by `node scripts/sync-byok.mjs` — change it there, then sync.\n";
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const arcana = process.env.ARCANA_DIR ?? path.join(os.homedir(), "arcana");
+  const source = await readFile(path.join(arcana, "packages/byok/src/byok.ts"), "utf8");
+  await writeFile(byokCopy, BYOK_HEADER + source);
+  console.log(`Wrote ${path.relative(root, byokCopy)} from ${arcana}`);
+}

package/scripts/sync-plan-catalog.d.mts

@@ -1,3 +1,6 @@
 export const catalogSource: string;
 export const catalogCopy: string;
 export const COPY_HEADER: string;
+export const scenarioSource: string;
+export const scenarioCopy: string;
+export const SCENARIO_COPY_HEADER: string;

package/scripts/sync-plan-catalog.mjs

@@ -1,6 +1,7 @@
-// Copies the plan catalog into the dashboard, which deliberately builds
-// without importing files from outside apps/qa. Run after editing
-// src/billing/plan-catalog.ts; the root test suite fails if the copy drifts.
+// Copies files the dashboard shares with the CLI and registry into
+// apps/qa, which deliberately builds without importing files from outside
+// it. Run after editing a source below; the root test suite fails if a copy
+// drifts.
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
@@ -8,9 +9,18 @@ const root = path.resolve(import.meta.dirname, "..");
 export const catalogSource = path.join(root, "src/billing/plan-catalog.ts");
 export const catalogCopy = path.join(root, "apps/qa/src/lib/plan-catalog.ts");
 export const COPY_HEADER = "// GENERATED by `npm run sync:catalog` from src/billing/plan-catalog.ts — edit that file instead.\n";
+export const scenarioSource = path.join(root, "src/runtime/scenario-matrix.ts");
+export const scenarioCopy = path.join(root, "apps/qa/src/lib/scenario-matrix.ts");
+export const SCENARIO_COPY_HEADER = "// GENERATED by `npm run sync:catalog` from src/runtime/scenario-matrix.ts — edit that file instead.\n";
+
+const COPIES = [
+  [catalogSource, catalogCopy, COPY_HEADER],
+  [scenarioSource, scenarioCopy, SCENARIO_COPY_HEADER],
+];
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  const source = await readFile(catalogSource, "utf8");
-  await writeFile(catalogCopy, COPY_HEADER + source);
-  console.log(`Wrote ${path.relative(root, catalogCopy)}`);
+  for (const [source, copy, header] of COPIES) {
+    await writeFile(copy, header + await readFile(source, "utf8"));
+    console.log(`Wrote ${path.relative(root, copy)}`);
+  }
 }