@deeeed/metamask-harness 0.70.1 → 0.71.0

package/dist/run-diagnostics.js

@@ -3,8 +3,27 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { getAdapterSurface } from "./adapters/surface.js";
-import { runnerDir } from "./paths.js";
-import { ensureExtensionConsoleCapture } from "./adapters/extension/console-capture.js";
+import { recipeRuntimePath, runnerDir } from "./paths.js";
+import { ensureExtensionConsoleCapture, extensionCaptureFiles, extensionCdpPort } from "./adapters/extension/console-capture.js";
+import {
+  ensureTerminalConsoleCapture,
+  terminalCaptureFiles,
+  terminalCdpPort,
+  terminalRuntimeFile
+} from "./adapters/terminal/console-capture.js";
+import {
+  collectorOwnerMarker,
+  collectorStatus,
+  verifyCapture
+} from "../library/actions/shared/console-collector.mjs";
+import {
+  allowlistMatch,
+  classifyConsoleRecord,
+  consoleRecords,
+  libraryRootsFromEnv,
+  loadConsoleAllowlist,
+  messageSignature
+} from "../library/actions/shared/console-findings.mjs";
 const MAX_CAPTURE_BYTES = 512 * 1024;
 const MAX_FINDINGS = 20;
 const MAX_PREVIEW_CHARS = 320;
@@ -26,7 +45,9 @@ function formatRunDiagnosticsForHuman(diagnostics, adapter) {
   const lines = [`${status} \u2014 ${diagnostics.note}`];
   for (const finding of diagnostics.findings) {
     const count = finding.count > 1 ? ` \xD7${finding.count}` : "";
-    lines.push(`${finding.level.toUpperCase()}${count} \u2014 ${finding.preview}`);
+    const source = finding.source ? ` [${finding.source}]` : "";
+    const allowed = finding.allowlisted ? ` (allowlisted: ${finding.allowlisted.reason})` : "";
+    lines.push(`${finding.level.toUpperCase()}${count}${source} \u2014 ${finding.preview}${allowed}`);
   }
   return lines;
 }
@@ -34,27 +55,64 @@ async function beginRunDiagnostics(adapter, projectRoot) {
   const source = getAdapterSurface(adapter).appLogSource(projectRoot);
   if (!source) return null;
   const mobileIssueBuffer = adapter === "mobile" && process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME !== "1" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
-  if (adapter === "extension") {
-    await ensureExtensionConsoleCapture(projectRoot).catch(() => void 0);
+  let capture;
+  if (adapter === "extension" || adapter === "terminal") {
+    const start = adapter === "extension" ? ensureExtensionConsoleCapture : ensureTerminalConsoleCapture;
+    const startError = await start(projectRoot).then(() => void 0, (error) => error instanceof Error ? error.message : String(error));
+    const { extensionLog, pageLog, pidFile } = adapter === "extension" ? extensionCaptureFiles(projectRoot) : terminalCaptureFiles(projectRoot);
+    const cdpPort = adapter === "extension" ? extensionCdpPort() : terminalCdpPort();
+    capture = { adapter, projectRoot, extensionLog, pageLog, pidFile, ...cdpPort ? { cdpPort } : {}, ...startError ? { startError } : {} };
   }
+  const walletLogPath = adapter === "terminal" ? terminalRuntimeFile(projectRoot, "wallet-requests.jsonl") : null;
+  const walletStat = walletLogPath ? safeStat(walletLogPath) : null;
   const stat = safeStat(source.path);
   return {
     source,
     offset: stat?.size ?? 0,
     ...stat ? { inode: stat.ino } : {},
-    ...mobileIssueBuffer ? { mobileIssueBuffer } : {}
+    ...mobileIssueBuffer ? { mobileIssueBuffer } : {},
+    ...capture ? { capture } : {},
+    ...walletLogPath ? { walletLog: { path: walletLogPath, offset: walletStat?.size ?? 0, ...walletStat ? { inode: walletStat.ino } : {} } } : {}
   };
 }
+async function verifyConsoleCapture(capture) {
+  if (capture.startError) return { verified: false, detail: `the console collector did not start: ${capture.startError}` };
+  if (!capture.cdpPort) return { verified: false, detail: "no CDP port for the console collector" };
+  const status = collectorStatus({
+    pidFile: capture.pidFile,
+    extensionLog: capture.extensionLog,
+    marker: collectorOwnerMarker(path.dirname(capture.pidFile)),
+    cdpPort: capture.cdpPort
+  });
+  if (!status.ok) return { verified: false, detail: status.detail };
+  let control;
+  if (capture.adapter === "extension") {
+    let extensionId = null;
+    try {
+      extensionId = fs.readFileSync(recipeRuntimePath(capture.projectRoot, "extension.id"), "utf8").trim();
+    } catch {
+      extensionId = null;
+    }
+    control = await verifyCapture({ cdpPort: capture.cdpPort, log: capture.extensionLog, target: "extension", extensionId });
+  } else {
+    const browser = readJsonRecord(terminalRuntimeFile(capture.projectRoot, "browser.json"));
+    if (typeof browser?.appOrigin !== "string") return { verified: false, detail: "no slot browser state (browser.json) to verify the page console capture against" };
+    control = await verifyCapture({ cdpPort: capture.cdpPort, log: capture.pageLog, target: "page", appOrigin: browser.appOrigin });
+  }
+  return { verified: control.ok, detail: control.ok ? `${status.detail}; ${control.detail}` : control.detail };
+}
 function isRunDiagnosticsDocument(value) {
   if (!isRecord(value) || value.schemaVersion !== 1 || value.scope !== "recipe-run-application") return false;
   if (value.status !== "clean" && value.status !== "review" && value.status !== "unavailable") return false;
   return typeof value.note === "string" && Array.isArray(value.findings);
 }
-function finishRunDiagnostics(baseline, result) {
+async function finishRunDiagnostics(baseline, result) {
   if (!baseline) return result;
   try {
     const bufferedIssues = baseline.mobileIssueBuffer ? collectMobileIssueBuffer(baseline.mobileIssueBuffer.projectRoot) : void 0;
-    const { diagnostics, rawAppLog } = collectRunDiagnosticsCapture(baseline, bufferedIssues);
+    const allowlist = loadConsoleAllowlist(recipeLibraryRoots(result.summaryPath));
+    const capture = baseline.capture ? await verifyConsoleCapture(baseline.capture) : void 0;
+    const { diagnostics, rawAppLog } = collectRunDiagnosticsCapture(baseline, bufferedIssues, allowlist, capture);
     const artifactsDir = path.dirname(result.summaryPath);
     const diagnosticsPath = path.join(artifactsDir, "diagnostics.json");
     fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}
@@ -87,16 +145,17 @@ function finishRunDiagnostics(baseline, result) {
     };
   }
 }
-function collectRunDiagnostics(baseline, bufferedIssues) {
-  return collectRunDiagnosticsCapture(baseline, bufferedIssues).diagnostics;
+function collectRunDiagnostics(baseline, bufferedIssues, allowlist = null, capture) {
+  return collectRunDiagnosticsCapture(baseline, bufferedIssues, allowlist, capture).diagnostics;
 }
-function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
+function collectRunDiagnosticsCapture(baseline, bufferedIssues, allowlist = null, capture) {
   const stat = safeStat(baseline.source.path);
   const source = {
     label: baseline.source.label,
     path: baseline.source.path,
     startOffset: baseline.offset,
     endOffset: stat?.size ?? baseline.offset,
+    inode: void 0,
     bytesRead: 0,
     truncated: false,
     inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected",
@@ -111,22 +170,31 @@ function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
     const bytesToRead = Math.min(available, MAX_CAPTURE_BYTES);
     source.startOffset = startOffset;
     source.endOffset = stat.size;
+    source.inode = stat.ino;
     source.bytesRead = bytesToRead;
     source.truncated = available > MAX_CAPTURE_BYTES;
     if (bytesToRead > 0) rawAppLog = readSlice(baseline.source.path, startOffset, bytesToRead);
+    if (source.truncated) rawAppLog = rawAppLog.subarray(0, rawAppLog.lastIndexOf(10) + 1);
   }
   const text = rawAppLog.toString("utf8");
+  const lineFindings = consoleRecords(text).map(classifyRecord).filter((finding) => finding !== null);
+  applyConsoleAllowlist(lineFindings, allowlist);
   const allFindings = dedupeFindings(
     [
-      ...text.split(/\r?\n/u).map(classifyLine).filter((finding) => finding !== null),
-      ...(bufferedIssues ?? []).map(classifyBufferedIssue).filter((finding) => finding !== null)
+      ...lineFindings,
+      ...(bufferedIssues ?? []).map(classifyBufferedIssue).filter((finding) => finding !== null),
+      ...baseline.walletLog ? walletLogFindings(baseline.walletLog) : []
     ]
   );
-  const findings = allFindings.slice(0, MAX_FINDINGS);
+  const applied = allFindings.filter((finding) => finding.level === "info").length;
+  allFindings.sort((a, b) => Number(a.level === "info") - Number(b.level === "info"));
+  const findings = allFindings.slice(0, MAX_FINDINGS).map(stripInternal);
   const counts = countFindings(allFindings);
   const omittedFindingCount = Math.max(0, allFindings.length - findings.length);
-  const status = counts.total > 0 ? "review" : stat || bufferedIssues !== void 0 && bufferedIssues !== null ? "clean" : "unavailable";
-  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; showing ${findings.length} preview(s) and omitting ${omittedFindingCount}. Relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
+  const captureFailed = capture !== void 0 && !capture.verified;
+  const status = counts.total > 0 ? "review" : !captureFailed && !source.truncated && (stat || bufferedIssues !== void 0 && bufferedIssues !== null) ? "clean" : "unavailable";
+  const captureNote = (captureFailed ? ` Console capture was not verified: ${capture.detail}.` : "") + (source.truncated ? ` The run's log exceeded ${MAX_CAPTURE_BYTES} bytes; only its start was checked.` : "");
+  const note = (counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; showing ${findings.length} preview(s) and omitting ${omittedFindingCount}. Relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.") + captureNote;
   return { diagnostics: {
     schemaVersion: 1,
     scope: "recipe-run-application",
@@ -135,24 +203,47 @@ function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
     note,
     source,
     counts,
+    ...allowlist ? { allowlist: { entries: allowlist.entries.length, applied, problems: allowlist.problems } } : {},
+    ...capture ? { capture } : {},
     displayedFindingCount: findings.length,
     omittedFindingCount,
     findings
   }, rawAppLog };
 }
-function classifyLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed) return null;
-  let level = null;
-  if (/\bEXCEPTION\s{2,}|\b(?:Uncaught|UnhandledPromiseRejection|FATAL EXCEPTION)\b/iu.test(trimmed)) {
-    level = "exception";
-  } else if (/^(?:ERROR\s{2,}|\[error\]\s*)/iu.test(trimmed) || /\]\s+ERROR\s{2,}/u.test(trimmed)) {
-    level = "error";
-  } else if (/^(?:WARN(?:ING)?\s{2,}|\[warn(?:ing)?\]\s*)/iu.test(trimmed) || /\]\s+WARN(?:ING)?\s{2,}/u.test(trimmed)) {
-    level = "warning";
+function classifyRecord(record) {
+  const classified = classifyConsoleRecord(record);
+  if (!classified) return null;
+  const line = record.line;
+  const signature = messageSignature(redactDiagnosticText(classified.message));
+  return {
+    ...makeFinding(classified.level, line.trim(), `${classified.source}|${signature}`),
+    source: classified.source,
+    signature: redactPreview(signature),
+    firstFrame: classified.firstFrame ? redactPreview(classified.firstFrame) : null,
+    event: classified.key
+  };
+}
+function walletLogFindings(walletLog) {
+  const stat = safeStat(walletLog.path);
+  if (!stat) return [];
+  const sameFile = walletLog.inode === void 0 || walletLog.inode === stat.ino;
+  const start = sameFile && stat.size >= walletLog.offset ? walletLog.offset : 0;
+  const findings = [];
+  for (const line of readSlice(walletLog.path, start, stat.size - start).toString("utf8").split("\n")) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(entry)) continue;
+    let text = null;
+    if (entry.kind === "blocked-mainnet" && entry.probe !== true) text = `blocked-mainnet: ${String(entry.transport ?? "request")} to ${String(entry.url ?? "?")}`;
+    else if (entry.kind === "refused-mainnet") text = `refused-mainnet: ${String(entry.method ?? "?")} (${String(entry.reason ?? "?")})`;
+    else if (entry.kind === "unattributed") text = `unattributed wallet ${entry.binding === "request" ? "request" : "log entry"}${typeof entry.method === "string" ? ` (${entry.method})` : ""}`;
+    if (text) findings.push({ ...makeFinding("error", text, `wallet|${text}`), source: "wallet", signature: text, firstFrame: null });
   }
-  if (!level) return null;
-  return makeFinding(level, trimmed);
+  return findings;
 }
 function classifyBufferedIssue(value) {
   if (!isRecord(value) || typeof value.text !== "string") return null;
@@ -160,15 +251,26 @@ function classifyBufferedIssue(value) {
   const level = rawLevel === "warn" || rawLevel === "warning" ? "warning" : rawLevel === "error" ? "error" : rawLevel === "exception" ? "exception" : null;
   return level ? makeFinding(level, value.text) : null;
 }
-function makeFinding(level, text) {
+function makeFinding(level, text, groupKey) {
   const preview = redactPreview(text.trim());
-  const identity = preview.replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?\b/gu, "[TIME]").replace(/\[(?:sw|page:[^\]]+|console:[^\]]+)\]/gu, "[APP]").replace(/^(?:(?:WARN(?:ING)?|ERROR|EXCEPTION|\[TIME\]|\[APP\])\s*)+/u, "");
+  const identity = groupKey ?? preview.replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?\b/gu, "[TIME]").replace(/\[(?:sw|page:[^\]]+|console:[^\]]+)\]/gu, "[APP]").replace(/^(?:(?:WARN(?:ING)?|ERROR|EXCEPTION|\[TIME\]|\[APP\])\s*)+/u, "");
   return {
     level,
     fingerprint: createHash("sha256").update(`${level}|${identity}`).digest("hex").slice(0, 12),
     preview
   };
 }
+function applyConsoleAllowlist(findings, allowlist) {
+  if (!allowlist) return;
+  for (const finding of findings) {
+    if (!finding.event) continue;
+    const match = allowlistMatch({ source: finding.source, key: finding.event }, allowlist);
+    if (!match) continue;
+    finding.allowlisted = { reason: match.reason, entry: match.index, file: match.file, ...match.temporary ? { temporary: true } : {} };
+    finding.level = "info";
+    finding.fingerprint = createHash("sha256").update(`${finding.fingerprint}|info|${match.file}#${match.index}`).digest("hex").slice(0, 12);
+  }
+}
 function armMobileIssueBuffer(projectRoot) {
   const armed = runMobileIssueCommand(projectRoot, "issues-arm");
   if (!armed) return false;
@@ -209,10 +311,17 @@ function dedupeFindings(findings) {
   return [...byFingerprint.values()];
 }
 function countFindings(findings) {
-  const counts = { total: findings.length, warning: 0, error: 0, exception: 0 };
-  for (const finding of findings) counts[finding.level] += 1;
+  const counts = { total: 0, warning: 0, error: 0, exception: 0, info: 0 };
+  for (const finding of findings) {
+    counts[finding.level] += 1;
+    if (finding.level !== "info") counts.total += 1;
+  }
   return counts;
 }
+function stripInternal(finding) {
+  const { event: _event, ...rest } = finding;
+  return rest;
+}
 function readSlice(filePath, offset, length) {
   const fd = fs.openSync(filePath, "r");
   try {
@@ -266,6 +375,13 @@ function indexDiagnosticSummary(summaryPath, diagnostics) {
   fs.writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}
 `);
 }
+function recipeLibraryRoots(summaryPath) {
+  const summary = readJsonRecord(summaryPath);
+  const libraries = isRecord(summary?.recipeLibraries) ? summary.recipeLibraries : null;
+  const sources = Array.isArray(libraries?.sources) ? libraries.sources : [];
+  const roots = sources.map((source) => isRecord(source) && typeof source.root === "string" ? source.root : null).filter((root) => Boolean(root));
+  return roots.length ? roots : libraryRootsFromEnv();
+}
 function readJsonRecord(filePath) {
   try {
     const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
@@ -282,5 +398,6 @@ export {
   collectRunDiagnostics,
   finishRunDiagnostics,
   formatRunDiagnosticsForHuman,
-  readRunDiagnosticsDocument
+  readRunDiagnosticsDocument,
+  verifyConsoleCapture
 };

package/dist/runner.js

@@ -89,7 +89,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
         const { createAgentDeviceUiTransport } = await importMetaMaskNativeUiProvider();
         return createAgentDeviceUiTransport(options2);
       }
-    }, preparedLiveAdapters)
+    }, preparedLiveAdapters, { hudPolicy: options.autoHud === true ? "show" : "auto" })
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
   const lifecycle = mobileSourceAwareLifecycleAdapters(

package/dist/runtime-context.js

@@ -91,7 +91,7 @@ function validExistingContext(context, repoRoot, runtimeDir, adapter) {
       if (runtimeStart[field] !== void 0 && (typeof runtimeStart[field] !== "string" || runtimeStart[field].length === 0)) return false;
     }
   }
-  const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial"] : ["cdpPort", "extensionId"];
+  const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial"] : adapter === "terminal" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : ["cdpPort", "extensionId"];
   if (forbiddenResources.some((field) => context[field] !== void 0)) return false;
   return true;
 }
@@ -107,7 +107,7 @@ function localDefaults(repoRoot, adapter, existing) {
   if (adapter === "extension" && !numericEnv("RECIPE_CDP_PORT", "CDP_PORT") && !existing.cdpPort) {
     defaults.cdpPort = claimLocalPort(repoRoot, "cdp", 2e4 + offset);
   }
-  if (adapter !== "core" && !numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") && !existing.watcherPort && !existing.metroPort && !existing.devServerPort) {
+  if (adapter !== "core" && adapter !== "terminal" && !numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") && !existing.watcherPort && !existing.metroPort && !existing.devServerPort) {
     defaults.watcherPort = claimLocalPort(repoRoot, "watcher", (adapter === "extension" ? 3e4 : 4e4) + offset);
   }
   return defaults;
@@ -164,7 +164,7 @@ function runtimeResources(adapter, existing, defaults) {
     watcherPort,
     devServerPort: watcherPort
   };
-  if (adapter === "extension") {
+  if (adapter === "extension" || adapter === "terminal") {
     shared.cdpPort = numericEnv("RECIPE_CDP_PORT", "CDP_PORT") ?? existing.cdpPort ?? defaults.cdpPort;
   } else {
     shared.metroPort = watcherPort;

package/docs/CONTRIBUTING.md

@@ -93,7 +93,7 @@ The input path is argv 1 and `METAMASK_RECIPE_ADAPTER_INPUT`. Its document is:
 ```json
 {
   "schemaVersion": 1,
-  "platform": "mobile|extension|core",
+  "platform": "mobile|extension|core|terminal",
   "action": "metamask.example.action",
   "node": {},
   "context": {

package/library/actions/shared/console-allowlist-add.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Write console allowlist entries (schemaVersion 3) from a real capture, so
+// entries are copied from observed events instead of written by hand.
+//
+// Usage:
+//   node console-allowlist-add.mjs <run artifacts dir | capture log> [options]
+//     --allowlist <file>   the library's diagnostics/console-allowlist.json
+//                          (default: from RECIPE_LIBRARY_PATH, first library)
+//     --reason <text>      why these events are noise (required with --write)
+//     --link <url>         code or issue the reason points at
+//     --temporary          the entry goes once a known fix lands
+//     --pick <n,n,...>     the candidates to write (numbers from the listing)
+//     --write              append the picked candidates to the allowlist
+//                          (needs --pick: every entry is a deliberate choice)
+// A run artifacts dir is read through its diagnostics.json: the run's slice of
+// the raw slot capture (diagnostics-app-log.txt is redacted, so its query
+// strings would not match). Without --write it lists the candidates: every
+// warning, error or exception no entry matches yet, one per distinct event.
+
+import { closeSync, fstatSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  ALLOWLIST_RELATIVE_PATH,
+  allowlistEntryFor,
+  allowlistMatch,
+  classifyConsoleRecord,
+  consoleRecords,
+  libraryRootsFromEnv,
+  loadConsoleAllowlist,
+} from './console-findings.mjs';
+
+function parseArgs(argv) {
+  const options = { input: null, allowlist: null, reason: null, link: null, temporary: false, pick: null, write: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--allowlist') options.allowlist = argv[++index];
+    else if (arg === '--reason') options.reason = argv[++index];
+    else if (arg === '--link') options.link = argv[++index];
+    else if (arg === '--temporary') options.temporary = true;
+    else if (arg === '--pick') options.pick = String(argv[++index]).split(',').map(Number);
+    else if (arg === '--write') options.write = true;
+    else if (!options.input && !arg.startsWith('--')) options.input = arg;
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  if (!options.input) throw new Error('usage: console-allowlist-add.mjs <run artifacts dir | capture log> [--allowlist <file>] [--reason <text>] [--link <url>] [--temporary] [--pick <n,...>] [--write]');
+  return options;
+}
+
+// The capture text a run diagnosed, or a whole log file.
+export function captureText(input) {
+  const run = readJsonOr(path.join(input, 'diagnostics.json'), null);
+  if (run) {
+    const { source } = run;
+    const fd = openSync(source.path, 'r');
+    try {
+      // The same file the run diagnosed: its inode, and long enough.
+      const stat = fstatSync(fd);
+      if ((source.inode !== undefined && source.inode !== stat.ino) || stat.size < source.endOffset) {
+        throw new Error(`${source.path} is not the capture the run diagnosed (it was rotated or replaced since)`);
+      }
+      return readFileSync(fd).subarray(source.startOffset, source.endOffset).toString('utf8');
+    } finally {
+      closeSync(fd);
+    }
+  }
+  return readFileSync(input, 'utf8');
+}
+
+// Distinct events no entry matches yet, as entries without a reason.
+export function allowlistCandidates(text, allowlist = { entries: [] }) {
+  const candidates = new Map();
+  for (const record of consoleRecords(text)) {
+    const finding = classifyConsoleRecord(record);
+    if (!finding || allowlistMatch(finding, allowlist)) continue;
+    const entry = allowlistEntryFor(finding);
+    const id = JSON.stringify(entry);
+    const known = candidates.get(id);
+    if (known) known.count += 1;
+    else candidates.set(id, { entry, level: finding.level, count: 1 });
+  }
+  return [...candidates.values()];
+}
+
+function readJsonOr(file, fallback) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return fallback;
+    throw error;
+  }
+}
+
+export function appendEntries(file, entries) {
+  const document = readJsonOr(file, { schemaVersion: 3, entries: [] });
+  if (document.schemaVersion !== 3) throw new Error(`${file} is schemaVersion ${document.schemaVersion}; convert it to 3 first`);
+  document.entries.push(...entries);
+  writeFileSync(file, `${JSON.stringify(document, null, 2)}\n`);
+}
+
+function main(argv) {
+  const options = parseArgs(argv);
+  const roots = options.allowlist ? [] : libraryRootsFromEnv();
+  const file = options.allowlist ?? (roots[0] ? path.join(roots[0], ALLOWLIST_RELATIVE_PATH) : null);
+  const allowlist = file ? loadConsoleAllowlist([path.dirname(path.dirname(file))]) : { entries: [], problems: [] };
+  const candidates = allowlistCandidates(captureText(options.input), allowlist);
+  const picked = options.pick ? candidates.filter((_, index) => options.pick.includes(index + 1)) : candidates;
+  if (!options.write) {
+    candidates.forEach((candidate, index) => {
+      process.stdout.write(`${index + 1}. ${candidate.level} ×${candidate.count}\n${JSON.stringify(candidate.entry, null, 2)}\n`);
+    });
+    if (candidates.length === 0) process.stdout.write('every warning and error in this capture is already allowlisted\n');
+    return 0;
+  }
+  if (!file) throw new Error('--write needs --allowlist <file> (or RECIPE_LIBRARY_PATH)');
+  if (!options.reason?.trim()) throw new Error('--write needs --reason');
+  if (!options.pick?.length) throw new Error('--write needs --pick <n,...>: choose the candidates to allowlist from the listing');
+  const entries = picked.map(({ entry }) => ({
+    ...entry,
+    reason: options.reason.trim(),
+    ...(options.link ? { link: options.link } : {}),
+    ...(options.temporary ? { temporary: true } : {}),
+  }));
+  appendEntries(file, entries);
+  process.stdout.write(`appended ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} to ${file}\n`);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`console-allowlist-add: ${error.message}\n`);
+    process.exitCode = 2;
+  }
+}