@deeeed/metamask-harness 0.51.5 → 0.51.7

package/dist/commands/domain.js

@@ -0,0 +1,56 @@
+import {
+  changedFiles,
+  classifyDomain,
+  configPath,
+  discoverLibraries,
+  readConfig
+} from "../review/knowledge.js";
+import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
+import { adapterFromOptions } from "./review.js";
+async function handleDomain(argv) {
+  const parsed = parseArgs(argv, "domain");
+  const target = targetPath(parsed.options);
+  const json = optionFlag(parsed.options, "json");
+  const declared = optionString(parsed.options, "domain") ?? process.env.MM_HARNESS_DOMAIN;
+  const detected = adapterFromOptions(parsed.options, target);
+  const adapter = detected === "unscoped" ? void 0 : detected;
+  if (declared) {
+    emit(json, { domain: declared, source: "declared", adapter: adapter ?? null, target });
+    return 0;
+  }
+  if (!adapter) {
+    throw usageError("No MetaMask checkout detected: pass --adapter <mobile|extension|core> or --domain <name>.");
+  }
+  const config = readConfig(configPath());
+  const libraries = discoverLibraries({ target, config });
+  const { base, files } = changedFiles(target, optionString(parsed.options, "base"));
+  const matches = classifyDomain(files, adapter, libraries);
+  const best = matches[0];
+  emit(json, {
+    domain: best?.domain ?? null,
+    source: best ? "owned-paths" : "none",
+    adapter,
+    target,
+    base,
+    changedFiles: files.length,
+    libraries: libraries.map((library) => ({ name: library.name, root: library.root, source: library.source, revision: library.revision ?? null })),
+    matches: matches.map((match) => ({ domain: match.domain, library: match.library.root, matched: match.matched }))
+  });
+  return 0;
+}
+function emit(json, payload) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ command: "domain", ...payload }, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${payload.domain ?? "none"}
+`);
+  const best = payload.matches?.[0];
+  const detail = payload.source === "declared" ? "declared via --domain or MM_HARNESS_DOMAIN" : best ? `owned-paths match in ${best.library} (${best.matched.length} of ${payload.changedFiles} changed files)` : `no library owns the ${payload.changedFiles} changed files (base ${payload.base}; libraries scanned: ${payload.libraries?.length ?? 0})`;
+  process.stderr.write(`domain: ${detail}
+`);
+}
+export {
+  handleDomain
+};

package/dist/commands/help.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { color } from "../cli-color.js";
 import { detectAdapter } from "../harness.js";
 import { optionString, parseArgs, targetPath } from "./parse-args.js";
+import { handleHelpReview } from "./review.js";
 const UNSCOPED_NEXT = "cd into a MetaMask checkout or pass --adapter <mobile|extension|core>";
 function validHelpLine(value) {
   return typeof value === "string" || Boolean(value && typeof value.text === "string" && Array.isArray(value.adapters) && value.adapters.length > 0 && value.adapters.every((adapter) => ["mobile", "extension", "core"].includes(adapter)));
@@ -70,6 +71,7 @@ function renderRecipeHelp(topic, harnessVersion, adapter) {
 }
 function handleHelp(argv, context) {
   const parsed = parseArgs(argv, "help");
+  if (parsed.positional[0] === "review") return handleHelpReview(argv, context.harnessVersion);
   const target = targetPath(parsed.options);
   const adapter = optionString(parsed.options, "adapter") ?? detectAdapter(target) ?? "unscoped";
   const topic = loadRecipeHelp(context.packageRoot);

package/dist/commands/pr-body.js

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BODY_FILE, renderPrBody } from "../pr-body/render.js";
+import { optionFlag, optionString, parseArgs, usageError } from "./parse-args.js";
+const USAGE = "Usage: mm-harness pr-body render <task-dir> [--command <text>] [--out <file>] [--json]";
+async function handlePrBody(argv) {
+  const parsed = parseArgs(argv, "pr-body");
+  const [action, taskArg] = parsed.positional;
+  if (action !== "render" || !taskArg) throw usageError(USAGE);
+  const taskDir = path.resolve(taskArg);
+  if (!fs.existsSync(path.join(taskDir, "artifacts"))) {
+    throw usageError(`${taskDir} has no artifacts/ directory; pass the task directory mm-harness task init wrote.`);
+  }
+  const command = optionString(parsed.options, "command");
+  const result = renderPrBody({ taskDir, ...command ? { command } : {} });
+  const out = path.resolve(optionString(parsed.options, "out") ?? path.join(taskDir, "artifacts", BODY_FILE));
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, result.body);
+  if (optionFlag(parsed.options, "json")) {
+    process.stdout.write(`${JSON.stringify({ command: "pr-body", subcommand: "render", status: "ok", taskDir, out, ...result, body: void 0 }, null, 2)}
+`);
+  } else {
+    process.stdout.write(`pr body: ${out}
+  ${result.sections.join("\n  ")}
+`);
+  }
+  return 0;
+}
+export {
+  handlePrBody
+};

package/dist/commands/review.js

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import { detectAdapter } from "../harness.js";
+import { runnerDir } from "../paths.js";
+import {
+  configPath,
+  loadDomainKnowledge,
+  parityAdapter,
+  readConfig,
+  referenceHint,
+  renderReviewChecklist,
+  renderReviewHelp,
+  resolveLibrary,
+  resolveReference,
+  defaultBaseRef
+} from "../review/knowledge.js";
+import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
+const EXIT_OK = 0;
+let cachedHarnessVersion;
+function harnessVersion() {
+  if (cachedHarnessVersion === void 0) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(runnerDir, "package.json"), "utf8"));
+    cachedHarnessVersion = pkg.version ?? "unknown";
+  }
+  return cachedHarnessVersion;
+}
+function adapterFromOptions(options, target) {
+  const raw = optionString(options, "adapter") ?? optionString(options, "platform");
+  if (raw !== void 0) {
+    if (raw !== "mobile" && raw !== "extension" && raw !== "core") throw usageError(`--adapter must be mobile, extension, or core (got ${raw}).`);
+    return raw;
+  }
+  return detectAdapter(target) ?? "unscoped";
+}
+function resolveReviewContext(options, { fetch = true } = {}) {
+  const target = targetPath(options);
+  const adapter = adapterFromOptions(options, target);
+  const domain = optionString(options, "domain") ?? process.env.MM_HARNESS_DOMAIN;
+  const config = readConfig(configPath());
+  const context = { target, adapter, ...domain ? { domain } : {} };
+  if (domain) {
+    const library = resolveLibrary(domain, { target, config, fetch });
+    if (library) context.knowledge = loadDomainKnowledge(library, adapter === "unscoped" ? void 0 : adapter);
+    else if (fetch) throw usageError(`No library found for domain "${domain}". Set RECIPE_LIBRARY_PATH="${domain}=<path>" or run: mm-harness config set libraries.${domain} <path>`);
+  }
+  const parity = parityAdapter(adapter);
+  if (parity) {
+    const reference = resolveReference(parity, { target, config });
+    if (reference) context.reference = reference;
+    else context.referenceMissing = `no ${parity} checkout found (${referenceHint(parity)})`;
+  }
+  return context;
+}
+function handleHelpReview(argv, harnessVersion2) {
+  const parsed = parseArgs(argv, "help");
+  const context = resolveReviewContext(parsed.options, { fetch: false });
+  const input = {
+    adapter: context.adapter,
+    harnessVersion: harnessVersion2,
+    ...context.domain ? { domain: context.domain } : {},
+    ...context.knowledge ? { knowledge: context.knowledge } : {},
+    ...context.reference ? { reference: context.reference } : {},
+    ...context.referenceMissing ? { referenceMissing: context.referenceMissing } : {}
+  };
+  if (optionFlag(parsed.options, "json")) {
+    process.stdout.write(`${JSON.stringify({ command: "help", topic: "review", ...input }, null, 2)}
+`);
+  } else {
+    process.stdout.write(renderReviewHelp(input));
+  }
+  return EXIT_OK;
+}
+async function handleReview(argv, version = harnessVersion()) {
+  const parsed = parseArgs(argv, "review");
+  const subcommand = parsed.positional[0];
+  if (subcommand !== "checklist") {
+    throw usageError("Usage: mm-harness review checklist [--domain <name>] [--since <sha>] [--base <ref>] [--out <file>] [--json]");
+  }
+  const context = resolveReviewContext(parsed.options);
+  const since = optionString(parsed.options, "since");
+  const base = optionString(parsed.options, "base") ?? defaultBaseRef(context.target);
+  const checklist = renderReviewChecklist({
+    adapter: context.adapter,
+    target: context.target,
+    base,
+    harnessVersion: version,
+    ...since ? { since } : {},
+    ...context.domain ? { domain: context.domain } : {},
+    ...context.knowledge ? { knowledge: context.knowledge } : {},
+    ...context.reference ? { reference: context.reference } : {},
+    ...context.referenceMissing ? { referenceMissing: context.referenceMissing } : {}
+  });
+  const out = optionString(parsed.options, "out");
+  if (out) {
+    const file = path.resolve(out);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, checklist);
+  }
+  if (optionFlag(parsed.options, "json")) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          command: "review",
+          subcommand: "checklist",
+          target: context.target,
+          adapter: context.adapter,
+          domain: context.domain ?? null,
+          library: context.knowledge?.library ?? null,
+          reference: context.reference ?? null,
+          referenceMissing: context.referenceMissing ?? null,
+          base,
+          since: since ?? null,
+          out: out ? path.resolve(out) : null,
+          checklist
+        },
+        null,
+        2
+      )}
+`
+    );
+  } else if (out) {
+    process.stdout.write(`review checklist: ${path.resolve(out)}
+`);
+  } else {
+    process.stdout.write(checklist);
+  }
+  return EXIT_OK;
+}
+export {
+  adapterFromOptions,
+  handleHelpReview,
+  handleReview,
+  harnessVersion,
+  resolveReviewContext
+};

package/dist/mm-harness-cli.js

@@ -35,9 +35,99 @@ const REAL = [
   --target <path>                    Checkout path (default: cwd)
   --json                             Load the same guide as structured agent context
 
+  help review [--domain <name>] prints the review guide: the base review every PR
+  gets, plus the team library's anti-pattern families, parity rule, and shared
+  package notes when --domain names a library (see mm-harness review --help).
+
 Example:
   mm-harness help
-  mm-harness help --json`
+  mm-harness help --json
+  mm-harness help review --domain perps`
+  },
+  {
+    name: "review",
+    summary: "Materialize a review checklist: base review + team library patterns + parity + verdict.",
+    example: "mm-harness review checklist --domain perps",
+    helpText: `mm-harness review checklist [flags]
+
+  Writes a phase-structured checklist (Setup, Base review, Domain patterns,
+  Parity, Verdict) that mm-harness checklist mark can track. Domain patterns are
+  one line per "##" section of the library's review/antipatterns.md; Parity names
+  the other platform's checkout when one resolves and says "not checked" otherwise.
+
+  Library resolution for --domain <name>: RECIPE_LIBRARY_PATH entry \u2192 engineer
+  config (mm-harness config) \u2192 sibling directory beside the checkout \u2192 shallow
+  fetch into <checkout>/.skills-cache/<name> (known libraries only). Reference
+  checkout resolution: MM_HARNESS_REF_<ADAPTER> \u2192 engineer config \u2192 sibling
+  checkout of that adapter.
+
+  --domain <name>   Team library to compose (default: MM_HARNESS_DOMAIN; none = base review only)
+  --since <sha>     Incremental re-review: scope the checklist to <sha>..HEAD
+  --base <ref>      Base ref for the diff range (default: origin/main when present)
+  --out <file>      Also write the checklist to <file>
+  --adapter, --target, --json
+
+Example:
+  mm-harness review checklist --domain perps
+  mm-harness review checklist --domain perps --since 4dd9be9 --out temp/tasks/review/CHECKLIST.md
+  mm-harness review checklist --json`
+  },
+  {
+    name: "domain",
+    summary: "Which team library owns the change: declared value first, else owned-paths.json against the changed files.",
+    example: "mm-harness domain",
+    helpText: `mm-harness domain [flags]
+
+  Prints the domain name (or "none"). A declared --domain / MM_HARNESS_DOMAIN wins;
+  otherwise the changed files (base...HEAD, working tree, untracked) are matched
+  against owned-paths.json in every reachable library (RECIPE_LIBRARY_PATH,
+  mm-harness config, sibling directories, .skills-cache).
+
+  --domain <name>   Declared domain (skips classification)
+  --base <ref>      Base ref for the changed-file range (default: origin/main when present)
+  --adapter, --target, --json
+
+Example:
+  mm-harness domain
+  mm-harness domain --json`
+  },
+  {
+    name: "pr-body",
+    summary: "Render the publishable PR body: the authored description plus the recipe and run log sections built from artifacts.",
+    example: "mm-harness pr-body render temp/tasks/dev/TAT-1",
+    helpText: `mm-harness pr-body render <task-dir> [flags]
+
+  Reads <task-dir>/artifacts/pr-description.md (the PR body the worker wrote in
+  the repository PR template shape) and inserts the machine sections rendered
+  from artifacts: "Validation Recipe" from artifacts/recipe.json, "Validation
+  Logs" from artifacts/recipe-run/report.md, and "Recipe Workflow" from
+  artifacts/workflow.mmd when it exists. Any such section the worker pasted by
+  hand is replaced. The sections go before the first checklist section, else at
+  the end. Fences are always longer than any backtick run in the content and
+  close on their own line. Writes <task-dir>/artifacts/pr-body.md.
+
+  --command <text>  Recipe invocation to show above the run log
+  --out <file>      Write elsewhere than artifacts/pr-body.md
+  --json            Machine-readable result
+
+Example:
+  mm-harness pr-body render temp/tasks/dev/TAT-1 --json`
+  },
+  {
+    name: "config",
+    summary: "Per-engineer machine locations for team libraries and reference checkouts.",
+    example: "mm-harness config set references.extension ~/dev/metamask-extension",
+    helpText: `mm-harness config <list|path|get <key>|set <key> <path>|unset <key>> [--json]
+
+  Stored outside every repo in ~/.mm-harness/config.json (override: MM_HARNESS_CONFIG).
+  Keys: libraries.<name> (team library checkout), references.<mobile|extension|core>
+  (the checkout used as the parity reference). Env always wins over config:
+  RECIPE_LIBRARY_PATH for libraries, MM_HARNESS_REF_<ADAPTER> for references.
+
+Example:
+  mm-harness config set libraries.perps ~/dev/experimental-metamask-recipe-perps
+  mm-harness config set references.extension ~/dev/metamask-extension
+  mm-harness config list`
   },
   {
     name: "tutorial",
@@ -783,12 +873,12 @@ const HELP_GROUPS = [
   {
     title: "DISCOVER",
     blurb: "discover atomic actions and reusable recipes (--json is the agent-primary form)",
-    commands: ["help", "tutorial", "actions", "call", "execution-template"]
+    commands: ["help", "tutorial", "actions", "call", "execution-template", "domain", "config"]
   },
   {
     title: "PROVE",
     blurb: "run recipes and inspect readiness",
-    commands: ["run", "last", "doctor", "check", "checklist", "recipe-quality"]
+    commands: ["run", "last", "doctor", "check", "checklist", "review", "pr-body", "recipe-quality"]
   },
   {
     title: "RUNTIME OVERLAY",

package/dist/pr-body/render.js

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import path from "node:path";
+const PROSE_FILE = "pr-description.md";
+const BODY_FILE = "pr-body.md";
+const RECIPE_HEADING = "## **Validation Recipe**";
+const LOGS_HEADING = "## **Validation Logs**";
+const WORKFLOW_HEADING = "## **Recipe Workflow**";
+function headingKey(heading) {
+  return heading.replace(/^#+\s*/, "").replace(/[*_`]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+const MACHINE_KEYS = new Set([RECIPE_HEADING, LOGS_HEADING, WORKFLOW_HEADING].map(headingKey));
+function levelTwoHeadingLines(lines) {
+  const found = [];
+  lines.forEach((line, index) => {
+    if (/^ {0,3}##(?!#)\s+\S/.test(line)) found.push(index);
+  });
+  return found;
+}
+function fenceFor(content) {
+  let longest = 0;
+  for (const run of content.match(/`+/g) ?? []) longest = Math.max(longest, run.length);
+  return "`".repeat(Math.max(3, longest + 1));
+}
+function fenced(content, info = "") {
+  const fence = fenceFor(content);
+  return `${fence}${info}
+${content.replace(/\n+$/, "")}
+${fence}`;
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function countRecipeNodes(recipe) {
+  if (!recipe || typeof recipe !== "object") return 0;
+  const record = recipe;
+  if (Array.isArray(record.nodes)) return record.nodes.length;
+  if (Array.isArray(record.steps)) return record.steps.length;
+  const workflow = record.workflow;
+  if (!workflow || typeof workflow !== "object") return 0;
+  return Object.values(workflow).reduce(
+    (total, value) => total + (Array.isArray(value) ? value.length : 0),
+    0
+  );
+}
+function recipeSection(file) {
+  const recipe = JSON.parse(fs.readFileSync(file, "utf8"));
+  const nodes = countRecipeNodes(recipe);
+  const record = recipe && typeof recipe === "object" ? recipe : {};
+  const title = typeof record.title === "string" ? record.title : typeof record.description === "string" ? record.description : "";
+  const summary = escapeHtml(`recipe.json (${nodes} steps${title ? ` \u2014 ${title.slice(0, 120)}` : ""})`);
+  return {
+    nodes,
+    body: [`<details><summary>${summary}</summary>`, "", fenced(JSON.stringify(recipe, null, 2), "json"), "</details>"].join("\n")
+  };
+}
+function logsSection(file, command) {
+  const report = fs.readFileSync(file, "utf8");
+  const status = /^Status:\s*(\S+)/m.exec(report)?.[1];
+  const nodes = /^Nodes:\s*(.+?)\s*$/m.exec(report)?.[1];
+  const summary = escapeHtml(status || nodes ? `Full output (${[nodes, status].filter(Boolean).join(", ")})` : "Full output");
+  const lines = [];
+  if (command) lines.push("Command:", "", fenced(command, "bash"), "");
+  lines.push(`<details><summary>${summary}</summary>`, "", fenced(report), "</details>");
+  return lines.join("\n");
+}
+function trimEnd(lines) {
+  let end = lines.length;
+  while (end > 0 && !lines[end - 1].trim()) end -= 1;
+  return lines.slice(0, end);
+}
+function renderPrBody(input) {
+  const artifacts = path.join(input.taskDir, "artifacts");
+  const prosePath = path.join(artifacts, PROSE_FILE);
+  if (!fs.existsSync(prosePath)) {
+    throw new Error(`Missing ${path.relative(input.taskDir, prosePath)}: write the PR description there first.`);
+  }
+  const recipePath = path.join(artifacts, "recipe.json");
+  const reportPath = path.join(artifacts, "recipe-run", "report.md");
+  const workflowPath = path.join(artifacts, "workflow.mmd");
+  const machine = [];
+  let recipe = null;
+  if (fs.existsSync(recipePath)) {
+    const rendered = recipeSection(recipePath);
+    recipe = { nodes: rendered.nodes, path: path.relative(input.taskDir, recipePath) };
+    machine.push([RECIPE_HEADING, rendered.body]);
+  } else {
+    machine.push([RECIPE_HEADING, "Not applicable: this task has no `artifacts/recipe.json`."]);
+  }
+  const hasReport = fs.existsSync(reportPath);
+  machine.push([
+    LOGS_HEADING,
+    hasReport ? logsSection(reportPath, input.command) : "Not applicable: no recipe run report under `artifacts/recipe-run/`."
+  ]);
+  const hasWorkflow = fs.existsSync(workflowPath);
+  if (hasWorkflow) {
+    machine.push([
+      WORKFLOW_HEADING,
+      ["<details><summary>workflow.mmd</summary>", "", fenced(fs.readFileSync(workflowPath, "utf8"), "mermaid"), "</details>"].join("\n")
+    ]);
+  }
+  const lines = fs.readFileSync(prosePath, "utf8").replace(/\r\n?/g, "\n").split("\n");
+  const headings = levelTwoHeadingLines(lines);
+  const keep = new Array(lines.length).fill(true);
+  let insertAt = lines.length;
+  headings.forEach((start, at) => {
+    const end = headings[at + 1] ?? lines.length;
+    const key = headingKey(lines[start]);
+    if (MACHINE_KEYS.has(key)) keep.fill(false, start, end);
+    else if (insertAt === lines.length && /checklist/.test(key)) insertAt = start;
+  });
+  const before = lines.slice(0, insertAt).filter((_, index) => keep[index]);
+  const after = lines.slice(insertAt).filter((_, index) => keep[insertAt + index]);
+  const generated = machine.flatMap(([heading, body2]) => [heading, "", body2, ""]);
+  const body = [...trimEnd(before), "", ...generated, ...after].join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "\n");
+  return {
+    body,
+    sections: machine.map(([heading]) => heading),
+    recipe,
+    run: hasReport ? { path: path.relative(input.taskDir, reportPath) } : null,
+    workflow: hasWorkflow ? { path: path.relative(input.taskDir, workflowPath) } : null
+  };
+}
+export {
+  BODY_FILE,
+  LOGS_HEADING,
+  PROSE_FILE,
+  RECIPE_HEADING,
+  WORKFLOW_HEADING,
+  countRecipeNodes,
+  escapeHtml,
+  fenceFor,
+  fenced,
+  headingKey,
+  levelTwoHeadingLines,
+  renderPrBody
+};