@deeeed/metamask-harness 0.3.8 → 0.4.0

package/src/doctor.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { color } from './cli-color.ts';
 import { readRuntimeContextField, resolveRuntimeContextPath } from './harness.ts';
 import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from './paths.ts';
 import type {
@@ -100,26 +101,32 @@ const RUNTIME_CONTEXT_FIELDS: ReadonlyArray<{
   envVars: readonly string[];
   envVar: string | null;
   customize: string;
+  adapters: readonly MetaMaskRecipeAdapter[];
 }> = [
-  { key: 'slotId', envVars: ['RECIPE_SLOT_ID'], envVar: 'RECIPE_SLOT_ID', customize: 'farmslot dispatch writes this' },
-  { key: 'extensionId', envVars: ['RECIPE_HARNESS_EXTENSION_ID'], envVar: 'RECIPE_HARNESS_EXTENSION_ID', customize: 'auto-resolved; edit file to pin' },
-  { key: 'cdpPort', envVars: ['RECIPE_CDP_PORT', 'CDP_PORT'], envVar: 'CDP_PORT', customize: 'edit file or pass --cdp-port' },
-  { key: 'runtimeStart.approved', envVars: ['RECIPE_RUNTIME_START_APPROVED'], envVar: 'RECIPE_RUNTIME_START_APPROVED', customize: 'edit file (true/false)' },
-  { key: 'runtimeStart.command', envVars: [], envVar: null, customize: 'edit file' },
-  { key: 'runtimeStart.readyUrl', envVars: ['RECIPE_RUNTIME_READY_URL'], envVar: 'RECIPE_RUNTIME_READY_URL', customize: 'edit file' },
+  { key: 'slotId', envVars: ['RECIPE_SLOT_ID'], envVar: 'RECIPE_SLOT_ID', customize: 'farmslot dispatch writes this', adapters: ['mobile', 'extension', 'core'] },
+  { key: 'extensionId', envVars: ['RECIPE_HARNESS_EXTENSION_ID'], envVar: 'RECIPE_HARNESS_EXTENSION_ID', customize: 'auto-resolved; edit file to pin', adapters: ['extension'] },
+  { key: 'cdpPort', envVars: ['RECIPE_CDP_PORT', 'CDP_PORT'], envVar: 'CDP_PORT', customize: 'edit file or pass --cdp-port', adapters: ['extension'] },
+  { key: 'runtimeStart.approved', envVars: ['RECIPE_RUNTIME_START_APPROVED'], envVar: 'RECIPE_RUNTIME_START_APPROVED', customize: 'edit file (true/false)', adapters: ['mobile', 'extension'] },
+  { key: 'runtimeStart.command', envVars: [], envVar: null, customize: 'edit file', adapters: ['mobile', 'extension'] },
+  { key: 'runtimeStart.readyUrl', envVars: ['RECIPE_RUNTIME_READY_URL'], envVar: 'RECIPE_RUNTIME_READY_URL', customize: 'edit file', adapters: ['mobile', 'extension'] },
 ];
 
 // Report every runtime-context field with its current value and where it came from
 // (live env override > file > unset default), reusing the harness's own file reader
 // so doctor and dispatch agree on resolution. Absent file → fileExists:false and
 // every field falls back to env or default; the path shows where it WOULD live.
-export function runtimeContextSummary(target: string): MetaMaskRuntimeContextReport {
+// An adapter scopes the report to that platform's fields — an extension-only row
+// (cdpPort, extensionId) is noise on a mobile or core slot.
+export function runtimeContextSummary(target: string, adapter?: MetaMaskRecipeAdapter): MetaMaskRuntimeContextReport {
   const contextPath = resolveRuntimeContextPath(target);
   const envOverride = process.env.RECIPE_RUNTIME_CONTEXT ?? null;
   const fileExists = fs.existsSync(contextPath);
   const file = envOverride ?? path.relative(target, contextPath);
   const fields: Record<string, MetaMaskRuntimeContextField> = {};
-  for (const spec of RUNTIME_CONTEXT_FIELDS) {
+  const specs = adapter
+    ? RUNTIME_CONTEXT_FIELDS.filter((spec) => spec.adapters.includes(adapter))
+    : RUNTIME_CONTEXT_FIELDS;
+  for (const spec of specs) {
     const envValue = spec.envVars
       .map((name) => process.env[name])
       .find((value) => value !== undefined && value !== '');
@@ -137,16 +144,21 @@ export function runtimeContextSummary(target: string): MetaMaskRuntimeContextRep
 
 // Human-readable runtime-context section for `doctor` without --json.
 export function renderRuntimeContext(runtimeContext: MetaMaskRuntimeContextReport): string {
+  // Human render: set values read bright with their provenance highlighted;
+  // unset defaults read dim so the eye lands on what is actually configured.
+  const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
   const lines: string[] = [];
   lines.push(
     runtimeContext.fileExists
-      ? `runtime-context: ${runtimeContext.file} (present)`
-      : `runtime-context: ${runtimeContext.file} (absent — written by farmslot prepare/dispatch)`,
+      ? `${out('label', 'runtime-context:')} ${runtimeContext.file} ${out('ok', '(present)')}`
+      : `${out('label', 'runtime-context:')} ${runtimeContext.file} ${out('dim', '(absent — written by farmslot prepare/dispatch)')}`,
   );
   for (const [key, field] of Object.entries(runtimeContext.fields)) {
-    const value = field.value ?? '(unset)';
+    const isSet = field.value !== undefined && field.value !== null && field.value !== '';
+    const value = isSet ? out('ok', String(field.value)) : out('dim', '(unset)');
     const origin = field.source === 'env' && field.envVar ? `env ${field.envVar}` : field.source;
-    lines.push(`  ${key.padEnd(22)} ${value}  [${origin}] — ${field.customize}`);
+    const originTag = isSet ? out('accent', `[${origin}]`) : out('dim', `[${origin}]`);
+    lines.push(`  ${key.padEnd(22)} ${value}  ${originTag} ${out('dim', `— ${field.customize}`)}`);
   }
   return lines.join('\n');
 }
@@ -189,7 +201,7 @@ export function createDoctorReport(
     compatibilityMode: mode,
     shape: repoShape(target),
     fixture: fixtureSummary(target),
-    runtimeContext: runtimeContextSummary(target),
+    runtimeContext: runtimeContextSummary(target, adapter),
     manifestValidation: manifestValidation.summary,
   };
 }

package/src/mm-harness-cli.ts

@@ -7,11 +7,13 @@
 // teach; genuinely-unknown commands fall to commander's default.
 
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { Command } from 'commander';
 
+import { color } from './cli-color.ts';
 import { handleUpdate, maybeNudge } from './commands/update.ts';
 
 // …/src → its parent is the package root that holds scripts/.
@@ -57,14 +59,37 @@ Example:
   mm-harness actions --adapter mobile
   mm-harness actions --adapter extension --raw`,
   },
+  {
+    name: 'stop',
+    summary: 'Stop the dev server this checkout owns (mobile Metro / extension webpack watcher) and close its log window.',
+    example: 'mm-harness stop',
+    helpText: `mm-harness stop [flags]
+
+  Stop the dev server this checkout owns and close its tmux log-tail window,
+  scoped to this checkout so concurrent slots are untouched. Idempotent —
+  nothing running is success, not an error. Behavior is per platform:
+    mobile     stop the port-scoped Metro dev server
+    extension  stop the checkout's webpack watcher (pid file + orphan scan)
+    core       headless — no dev server to stop (teaching error)
+
+  --port <port>                      Dev-server port (default: the checkout's slot context)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness stop
+  mm-harness stop --port 8061`,
+  },
   {
     name: 'call',
     summary: 'Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).',
-    example: 'mm-harness call unlock',
+    example: 'mm-harness call ensure_unlocked',
     helpText: `mm-harness call <action> [--arg k=v ...] [flags]
 
   Run one action in isolation as a one-node recipe through the real engine path.
-  Fuzzy short-name: 'unlock' resolves to 'metamask.wallet.unlock' if unique; ambiguous = exit 2.
+  Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
+  if unique; ambiguous = exit 2. Actions differ per adapter — list this checkout's
+  with: mm-harness actions.
 
   --arg k=v                          Action field value (repeatable)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
@@ -74,9 +99,9 @@ Example:
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
 
-Example:
-  mm-harness call unlock --adapter extension
-  mm-harness call command --arg cmd="echo hi" --adapter core --json`,
+Example (real actions; run mm-harness actions for this checkout's full set):
+  mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
+  mm-harness call command --arg cmd="echo hi" --adapter core   # the universal action (all adapters)`,
   },
   {
     name: 'flows',
@@ -220,8 +245,10 @@ Example:
 
   --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
   --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
-  --source <metro|app>               Log source (default metro)
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --source <label>                   Log source per adapter — mobile: metro|app (default metro);
+                                     extension: webpack|watcher|rebuild|app (default webpack).
+                                     Core is headless (teaching error).
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
 
@@ -345,7 +372,7 @@ const HELP_GROUPS: HelpGroup[] = [
   {
     title: 'DAILY LOOP',
     blurb: 'what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)',
-    commands: ['launch', 'logs', 'debug', 'fixtures'],
+    commands: ['launch', 'stop', 'logs', 'debug', 'fixtures'],
   },
   {
     title: 'DISCOVER',
@@ -375,19 +402,51 @@ function commandMeta(name: string): { summary: string; example: string; planned:
   return { summary: '', example: '', planned: false };
 }
 
+// Slot context the orchestrator's prepare wrote into the checkout, when the
+// help is run from inside one. Presence-gated: no context, no line.
+function detectedSlotLine(out: (style: string, text: string) => string): string | null {
+  const ctxPath = path.join(
+    process.cwd(),
+    process.env.RECIPE_RUNTIME_DIR || 'temp/recipe/runtime',
+    'agentic-runtime.json',
+  );
+  try {
+    const ctx = JSON.parse(fs.readFileSync(ctxPath, 'utf8')) as Record<string, unknown>;
+    const parts: string[] = [];
+    if (ctx.slotId) parts.push(`slot ${out('ok', String(ctx.slotId))}`);
+    if (ctx.simulator) parts.push(`device ${out('ok', String(ctx.simulator))}`);
+    if (ctx.metroPort) parts.push(`metro :${out('ok', String(ctx.metroPort))}`);
+    if (ctx.gitBranch) parts.push(`branch ${out('info', String(ctx.gitBranch))}`);
+    if (parts.length === 0) return null;
+    return `${out('label', 'SLOT')} — this checkout is a prepared slot: ${parts.join(' · ')}`;
+  } catch {
+    return null;
+  }
+}
+
 function groupedHelp(): string {
+  const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
   const lines: string[] = [];
-  lines.push('mm-harness — one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.');
+  lines.push(`${out('bold', 'mm-harness')} — one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.`);
   lines.push('Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.');
-  lines.push('Grammar: mm-harness <command> [target] [flags]   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)');
+  lines.push(`Grammar: ${out('cmd', 'mm-harness <command> [target] [flags]')}   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)`);
+  if (process.env.MM_HARNESS_BIN) {
+    lines.push('');
+    lines.push(`${out('warn', 'DEV OVERRIDE ACTIVE')} — this run is served by MM_HARNESS_BIN=${out('path', process.env.MM_HARNESS_BIN)} (unset it to return to the installed/global bin).`);
+  }
+  const slotLine = detectedSlotLine(out);
+  if (slotLine) {
+    lines.push('');
+    lines.push(slotLine);
+  }
   for (const group of HELP_GROUPS) {
     lines.push('');
-    lines.push(`${group.title} — ${group.blurb}:`);
+    lines.push(`${out('label', group.title)} — ${group.blurb}:`);
     for (const name of group.commands) {
       const meta = commandMeta(name);
       const planned = meta.planned ? '   (planned)' : '';
-      lines.push(`  ${name.padEnd(10)} ${meta.summary}${planned}`);
-      lines.push(`               ${meta.example}`);
+      lines.push(`  ${out('cmd', name.padEnd(10))} ${meta.summary}${planned}`);
+      lines.push(`               ${out('comment', meta.example)}`);
     }
   }
   lines.push('');