@deeeed/metamask-harness 0.2.0

package/orchestration/extension/runtime.ts

@@ -0,0 +1,407 @@
+// runtime.ts — extension runtime prepare/health over CDP.
+// App/instance control.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, recipeRuntimeDir, resolveLocalProtocolRoot, resolveRequiredLocalProtocolRoot, runnerDir } from '../../runner/src/paths.ts';
+
+// Runtime health uses package dependencies. Launching a host-managed validation
+// browser remains a dev-only path because it needs pool/project scripts from a
+// checkout.
+const { CdpSession, jsonGet, sleep } = await importRecipeHarnessRuntimeCdp();
+const { extensionIdFromTarget } = await importRecipeHarnessRuntimeBrowserExtension();
+
+export interface ExtensionRuntimeOptions {
+  projectRoot: string;
+  cdpPort?: string | number;
+  slot?: string;
+  launchExistingDist?: boolean;
+  validationRuntimeDir?: string;
+  healthTimeoutMs?: number;
+}
+
+export interface ExtensionRuntimeLaunchResult {
+  launched: boolean;
+  slotId?: string;
+  cdpPort: number;
+  runtimeDir?: string;
+  stdout?: string;
+}
+
+export interface ExtensionRuntimeHealthReport {
+  status: 'PASS' | 'FAIL';
+  cdpPort: number;
+  targetUrl?: string;
+  extensionId?: string;
+  extensionPageTargets: number;
+  findings: string[];
+  details: Record<string, unknown>;
+}
+
+interface CdpTarget {
+  id?: string;
+  type?: string;
+  title?: string;
+  url?: string;
+  webSocketDebuggerUrl?: string;
+}
+
+export async function prepareExtensionRuntime(
+  options: ExtensionRuntimeOptions,
+): Promise<{ launch: ExtensionRuntimeLaunchResult | null; health: ExtensionRuntimeHealthReport }> {
+  const projectRoot = path.resolve(options.projectRoot);
+  const slot = resolveExtensionSlot(projectRoot, options.slot);
+  const cdpPort = resolveCdpPort(options.cdpPort, slot);
+  let launch: ExtensionRuntimeLaunchResult | null = null;
+  if (options.launchExistingDist) {
+    if (!slot) {
+      throw new Error(
+        `Cannot launch host-managed Extension runtime for ${projectRoot}: no configured slot maps to this repo. ` +
+          'Pass --slot <slot-id> or add the checkout to pool/*.json.',
+      );
+    }
+    launch = await launchHostValidationBrowser({
+      projectRoot,
+      cdpPort,
+      slotId: slot.id,
+      validationRuntimeDir:
+        options.validationRuntimeDir ?? `${recipeRuntimeDir()}/validation-${cdpPort}`,
+    });
+  }
+  const health = await assertHealthyExtensionRuntime({
+    projectRoot,
+    cdpPort,
+    timeoutMs: options.healthTimeoutMs,
+  });
+  return { launch, health };
+}
+
+export async function assertHealthyExtensionRuntime(options: {
+  projectRoot: string;
+  cdpPort: number;
+  timeoutMs?: number;
+}): Promise<ExtensionRuntimeHealthReport> {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const deadline = Date.now() + timeoutMs;
+  let lastReport: ExtensionRuntimeHealthReport | null = null;
+  while (Date.now() <= deadline) {
+    lastReport = await checkExtensionRuntimeHealth(options.projectRoot, options.cdpPort);
+    if (lastReport.status === 'PASS') return lastReport;
+    await sleep(500);
+  }
+  const report = lastReport ?? failReport(options.cdpPort, ['CDP runtime was not probed.'], {});
+  throw new Error(formatHealthFailure(report, options.projectRoot));
+}
+
+export async function checkExtensionRuntimeHealth(
+  projectRoot: string,
+  cdpPort: number,
+): Promise<ExtensionRuntimeHealthReport> {
+  const findings: string[] = [];
+  let targets: CdpTarget[] = [];
+  try {
+    await jsonGet(`http://127.0.0.1:${cdpPort}/json/version`);
+    const rawTargets = await jsonGet(`http://127.0.0.1:${cdpPort}/json/list`);
+    targets = Array.isArray(rawTargets) ? rawTargets as CdpTarget[] : [];
+  } catch (error) {
+    return failReport(cdpPort, [`CDP is not reachable on port ${cdpPort}: ${messageOf(error)}`], {});
+  }
+
+  const extensionTargets = targets.filter((target) =>
+    target.type === 'page' &&
+    String(target.url ?? '').startsWith('chrome-extension://') &&
+    String(target.url ?? '').includes('/home.html') &&
+    Boolean(target.webSocketDebuggerUrl),
+  );
+  if (extensionTargets.length !== 1) {
+    findings.push(`Expected exactly one MetaMask extension home page target, found ${extensionTargets.length}.`);
+  }
+  const target = extensionTargets[0];
+  if (!target?.webSocketDebuggerUrl) {
+    return failReport(cdpPort, findings, {
+      targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+    });
+  }
+  if (String(target.url ?? '').startsWith('chrome-error://')) {
+    findings.push(`Extension target resolved to chrome-error page: ${target.url}`);
+  }
+
+  const session = await CdpSession.connect(target.webSocketDebuggerUrl);
+  try {
+    await session.call('Runtime.enable');
+    await session.call('Page.enable');
+    const runtime = await evaluateHealth(session);
+    if (runtime.href && !String(runtime.href).startsWith('chrome-extension://')) {
+      findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
+    }
+    if (runtime.backgroundUnresponsive === true) {
+      findings.push('Extension UI reports background connection unresponsive.');
+    }
+    if (runtime.hasSubmitRequest !== true) {
+      findings.push('stateHooks.submitRequestToBackground is unavailable.');
+    }
+    if (runtime.hasStore !== true) {
+      findings.push('stateHooks.store is unavailable.');
+    }
+    if (runtime.hasPerpsStreamManager !== true) {
+      findings.push('stateHooks.getPerpsStreamManager is unavailable.');
+    }
+    if (runtime.backgroundProbeOk !== true) {
+      findings.push(`Perps background read probe failed: ${runtime.backgroundProbeError ?? 'unknown error'}.`);
+    }
+    const extensionId = safeExtensionId(target);
+    return {
+      status: findings.length === 0 ? 'PASS' : 'FAIL',
+      cdpPort,
+      targetUrl: target.url,
+      extensionId,
+      extensionPageTargets: extensionTargets.length,
+      findings,
+      details: {
+        projectRoot,
+        targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+        runtime,
+      },
+    };
+  } finally {
+    session.close();
+  }
+}
+
+function failReport(
+  cdpPort: number,
+  findings: string[],
+  details: Record<string, unknown>,
+): ExtensionRuntimeHealthReport {
+  return {
+    status: 'FAIL',
+    cdpPort,
+    extensionPageTargets: 0,
+    findings,
+    details,
+  };
+}
+
+async function evaluateHealth(session: any): Promise<Record<string, unknown>> {
+  const result = await session.call('Runtime.evaluate', {
+    expression: `(() => {
+      const hooks = globalThis.stateHooks || {};
+      const bodyText = document.body?.innerText || '';
+      const storeState = hooks.store?.getState?.() || {};
+      const manager = hooks.getPerpsStreamManager?.();
+      const accountCache = manager?.account?.cache;
+      return Promise.race([
+        (async () => {
+          let backgroundProbeOk = false;
+          let backgroundProbeError = null;
+          if (typeof hooks.submitRequestToBackground === 'function') {
+            try {
+              const accountState = await hooks.submitRequestToBackground('perpsGetAccountState', []);
+              backgroundProbeOk = Boolean(accountState && typeof accountState === 'object');
+              if (!backgroundProbeOk) backgroundProbeError = 'perpsGetAccountState returned an empty result';
+            } catch (error) {
+              backgroundProbeError = String(error?.message || error);
+            }
+          } else {
+            backgroundProbeError = 'submitRequestToBackground is not a function';
+          }
+          return {
+            href: location.href,
+            title: document.title,
+            hookKeys: Object.keys(hooks),
+            hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
+            hasStore: Boolean(hooks.store),
+            hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
+            backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+            activeProvider: storeState.metamask?.activeProvider || null,
+            isTestnet: Boolean(storeState.metamask?.isTestnet),
+            perpsManagerInitialized: Boolean(manager?.isInitialized?.()),
+            positionsCacheIsArray: Array.isArray(manager?.positions?.cache),
+            ordersCacheIsArray: Array.isArray(manager?.orders?.cache),
+            accountCachePresent: Boolean(accountCache && typeof accountCache === 'object'),
+            backgroundProbeOk,
+            backgroundProbeError,
+          };
+        })(),
+        new Promise((resolve) => setTimeout(() => resolve({
+          href: location.href,
+          title: document.title,
+          hookKeys: Object.keys(hooks),
+          hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
+          hasStore: Boolean(hooks.store),
+          hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
+          backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+          backgroundProbeOk: false,
+          backgroundProbeError: 'perpsGetAccountState timed out after 5000ms',
+        }), 5000)),
+      ]);
+    })()`,
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  if (result.exceptionDetails) {
+    throw new Error(
+      result.exceptionDetails.exception?.description ??
+        result.exceptionDetails.text ??
+        'Extension runtime health evaluation failed.',
+    );
+  }
+  return result.result?.value ?? {};
+}
+
+export function formatHealthFailure(report: ExtensionRuntimeHealthReport, projectRoot: string): string {
+  return [
+    `Extension runtime health check failed for ${projectRoot} on CDP port ${report.cdpPort}.`,
+    ...report.findings.map((finding) => `- ${finding}`),
+    'Use the host-managed validation launcher, for example:',
+    `  mm-harness run <recipe.json> --adapter extension --target ${projectRoot} --slot <slot-id> --cdp-port ${report.cdpPort} --launch-existing-dist --artifacts-dir <artifacts-dir>`,
+    `Health details: ${JSON.stringify(report.details)}`,
+  ].join('\n');
+}
+
+function resolveCdpPort(rawPort: string | number | undefined, slot: ResolvedSlot | null): number {
+  const raw = rawPort ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT ?? slot?.cdpPort;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error('Extension runtime requires --cdp-port, CDP_PORT, RECIPE_CDP_PORT, or a configured slot with resources.browser.cdp_port.');
+  }
+  return port;
+}
+
+interface ResolvedSlot {
+  id: string;
+  repo: string;
+  cdpPort?: number;
+}
+
+function resolveExtensionSlot(projectRoot: string, requestedSlot?: string): ResolvedSlot | null {
+  const protocolRoot = resolveLocalProtocolRoot();
+  if (!protocolRoot) {
+    if (requestedSlot) throw new Error('Extension slot lookup requires a local host checkout when --slot is provided.');
+    return null;
+  }
+  const poolsDir = path.join(protocolRoot, 'pool');
+  if (!fs.existsSync(poolsDir)) return null;
+  for (const file of fs.readdirSync(poolsDir)) {
+    // Only canonical pool files: skip backups (`*.json.bak.*`) and any non-.json,
+    // so a stale backup can't resolve a slot the live pool no longer defines.
+    if (!file.endsWith('.json') || file.includes('.bak')) continue;
+    const pool = JSON.parse(fs.readFileSync(path.join(poolsDir, file), 'utf8')) as { slots?: unknown[] };
+    for (const rawSlot of pool.slots ?? []) {
+      if (!rawSlot || typeof rawSlot !== 'object') continue;
+      const slot = rawSlot as Record<string, any>;
+      if (requestedSlot && slot.id !== requestedSlot) continue;
+      if (!requestedSlot) {
+        // Auto-match by repo requires an ABSOLUTE repo path. A relative entry —
+        // e.g. demo pools' "repo": "." — resolves to the runner's CWD and would
+        // spuriously shadow the real slot for whatever repo it runs in.
+        const repo = String(slot.repo ?? '');
+        if (!path.isAbsolute(repo) || path.resolve(repo) !== projectRoot) continue;
+      }
+      return {
+        id: String(slot.id),
+        repo: path.resolve(String(slot.repo)),
+        cdpPort: Number(slot.resources?.browser?.cdp_port || slot.resources?.browser?.cdpPort || undefined) || undefined,
+      };
+    }
+  }
+  return null;
+}
+
+async function launchHostValidationBrowser(options: {
+  projectRoot: string;
+  cdpPort: number;
+  slotId: string;
+  validationRuntimeDir: string;
+}): Promise<ExtensionRuntimeLaunchResult> {
+  const protocolRoot = resolveRequiredLocalProtocolRoot('Extension validation browser launch');
+  const script = path.join(protocolRoot, 'projects/metamask-extension-farm/setup/launch-validation-browser.sh');
+  if (!fs.existsSync(script)) {
+    throw new Error(`Extension validation launcher not found: ${script}`);
+  }
+  await killCdpPort(options.cdpPort);
+  const result = await runProcess('bash', [
+    script,
+    options.slotId,
+    '--cdp-port',
+    String(options.cdpPort),
+    '--runtime-dir',
+    options.validationRuntimeDir,
+    '--no-landing',
+  ], {
+    cwd: protocolRoot,
+    env: process.env,
+    timeoutMs: 180_000,
+  });
+  if (result.timedOut) {
+    throw new Error(`Extension validation launcher timed out after 180000ms.\n${result.stdout}\n${result.stderr}`);
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(`Extension validation launcher failed with exit ${result.exitCode}.\n${result.stdout}\n${result.stderr}`);
+  }
+  return {
+    launched: true,
+    slotId: options.slotId,
+    cdpPort: options.cdpPort,
+    runtimeDir: options.validationRuntimeDir,
+    stdout: result.stdout,
+  };
+}
+
+function runProcess(command: string, args: string[], options: { cwd: string; env: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<{ exitCode: number | null; stdout: string; stderr: string; timedOut: boolean }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timeout = options.timeoutMs
+      ? setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          child.kill('SIGTERM');
+          setTimeout(() => {
+            if (!child.killed) child.kill('SIGKILL');
+          }, 1000);
+          resolve({ exitCode: null, stdout, stderr, timedOut: true });
+        }, options.timeoutMs)
+      : undefined;
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      reject(error);
+    });
+    child.on('close', (exitCode) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      resolve({ exitCode, stdout, stderr, timedOut: false });
+    });
+  });
+}
+
+async function killCdpPort(cdpPort: number): Promise<void> {
+  if (process.platform !== 'darwin' && process.platform !== 'linux') return;
+  await runProcess('bash', ['-lc', `lsof -ti tcp:${cdpPort} -sTCP:LISTEN | xargs -r kill -TERM || true; sleep 1; lsof -ti tcp:${cdpPort} -sTCP:LISTEN | xargs -r kill -KILL || true`], {
+    cwd: runnerDir,
+    env: process.env,
+    timeoutMs: 10_000,
+  });
+}
+
+function safeExtensionId(target: CdpTarget): string | undefined {
+  try {
+    return extensionIdFromTarget(target);
+  } catch (_error) {
+    // Non-extension CDP targets are expected while scanning all browser tabs.
+    // Treat them as unmatched targets instead of failing runtime discovery.
+    return undefined;
+  }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/orchestration/extension/seed-fixture.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# seed-fixture.sh — wallet fixture resolution chain + generate/prefill/seed
+# prepare_parts mega-string in scripts/extension/live.sh)
+#
+# Purpose:
+#   Resolves which wallet fixture a slot run should use (env override then
+#   runtime-dir/legacy/port-scoped candidates) and drives the recipe-tree
+#   wallet-fixture-state.cjs phases around the browser launch.
+#
+# Subcommands (flags):
+#   resolve   --target <repo> --cdp-port <port> [--source-out <file>]
+#             Prints the fixture path (empty if none). Chain:
+#             RECIPE_WALLET_FIXTURE env > <runtime-dir>/wallet-fixture.json >
+#             temp/runtime/ > temp/.recipe-validation-<port>/ >
+#             temp/.agent-validation/.
+#   prefill   --fixture <json> --target <repo> --state <file> --profile <dir>
+#             --extension-dir <dist> --extension-id-file <file>
+#             Runs fixture-state generate then prefill-profile (pre-launch).
+#   seed-cdp  --fixture <json> --target <repo> --state <file> --cdp-port <p>
+#             --extension-dir <dist> --extension-id-file <file> --out <file>
+#             Runs fixture-state seed-cdp (post-launch).
+#   Common: [--fixture-script <path>] [--summary <file>]
+#
+# Outputs:
+#   resolve: fixture path on stdout, optional --source-out provenance JSON;
+#   prefill/seed-cdp: whatever wallet-fixture-state.cjs writes (--state/--out).
+#   Optional --summary file {feature,status,inputs,outputs,generatedAt}.
+#   Exit 0 — ok (resolve: also when no fixture found); 1 — env fixture not a
+#   file or fixture-state phase failed; 2 — bad args.
+#
+# Never touches: product source files; the fixture file (read-only).
+set -euo pipefail
+
+SUBCOMMAND="${1:-}"
+case "$SUBCOMMAND" in
+  resolve|prefill|seed-cdp) shift ;;
+  -h|--help)
+    echo "Usage: seed-fixture.sh <resolve|prefill|seed-cdp> [flags] (see header)"
+    exit 0
+    ;;
+  *) echo "Unknown subcommand: ${SUBCOMMAND:-<none>} (want resolve|prefill|seed-cdp)" >&2; exit 2 ;;
+esac
+
+TARGET="$PWD"
+CDP_PORT=""
+FIXTURE=""
+STATE=""
+PROFILE=""
+EXTENSION_DIR=""
+EXTENSION_ID_FILE=""
+OUT=""
+SOURCE_OUT=""
+FIXTURE_SCRIPT=""
+SUMMARY=""
+require_value() { [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; }
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) require_value "$@"; TARGET="$2"; shift 2 ;;
+    --cdp-port) require_value "$@"; CDP_PORT="$2"; shift 2 ;;
+    --fixture) require_value "$@"; FIXTURE="$2"; shift 2 ;;
+    --state) require_value "$@"; STATE="$2"; shift 2 ;;
+    --profile) require_value "$@"; PROFILE="$2"; shift 2 ;;
+    --extension-dir) require_value "$@"; EXTENSION_DIR="$2"; shift 2 ;;
+    --extension-id-file) require_value "$@"; EXTENSION_ID_FILE="$2"; shift 2 ;;
+    --out) require_value "$@"; OUT="$2"; shift 2 ;;
+    --source-out) require_value "$@"; SOURCE_OUT="$2"; shift 2 ;;
+    --fixture-script) require_value "$@"; FIXTURE_SCRIPT="$2"; shift 2 ;;
+    --summary) require_value "$@"; SUMMARY="$2"; shift 2 ;;
+    -h|--help)
+      echo "Usage: seed-fixture.sh <resolve|prefill|seed-cdp> [flags] (see header)"
+      exit 0
+      ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+status=fail
+finish() {
+  if [ -n "$SUMMARY" ]; then
+    mkdir -p "$(dirname "$SUMMARY")"
+    STATUS_FOR_SUMMARY="$status" SUB_FOR_SUMMARY="$SUBCOMMAND" TARGET_FOR_SUMMARY="$TARGET" FIXTURE_FOR_SUMMARY="$FIXTURE" STATE_FOR_SUMMARY="$STATE" OUT_FOR_SUMMARY="$OUT" SUMMARY_PATH="$SUMMARY" node <<'NODE' || true
+const fs = require('fs');
+fs.writeFileSync(process.env.SUMMARY_PATH, `${JSON.stringify({
+  feature: 'extension/seed-fixture',
+  status: process.env.STATUS_FOR_SUMMARY,
+  inputs: {
+    subcommand: process.env.SUB_FOR_SUMMARY,
+    target: process.env.TARGET_FOR_SUMMARY,
+    fixture: process.env.FIXTURE_FOR_SUMMARY || null,
+  },
+  outputs: { state: process.env.STATE_FOR_SUMMARY || null, out: process.env.OUT_FOR_SUMMARY || null },
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+  fi
+}
+trap finish EXIT
+
+resolve_fixture_script() {
+  if [ -n "$FIXTURE_SCRIPT" ]; then
+    [ -f "$FIXTURE_SCRIPT" ] || { echo "seed-fixture: --fixture-script not found: $FIXTURE_SCRIPT" >&2; exit 2; }
+    printf '%s' "$FIXTURE_SCRIPT"
+    return 0
+  fi
+  if [ -f "$SCRIPT_DIR/wallet-fixture-state.cjs" ]; then
+    printf '%s' "$SCRIPT_DIR/wallet-fixture-state.cjs"
+    return 0
+  fi
+  echo "seed-fixture: wallet-fixture-state.cjs not found next to $SCRIPT_DIR; reinstall the runner." >&2
+  exit 1
+}
+
+if [ "$SUBCOMMAND" = resolve ]; then
+  RUNTIME_DIR=""
+  # shellcheck disable=SC1091
+  for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+    [ -f "$_hp" ] && { . "$_hp"; break; }
+  done
+  unset _hp
+  if command -v recipe_runtime_dir >/dev/null 2>&1; then
+    RUNTIME_DIR="$(recipe_runtime_dir)"
+  fi
+  resolved=""
+  resolve_status=found
+  if [ -n "${RECIPE_WALLET_FIXTURE:-}" ]; then
+    if [ ! -f "$RECIPE_WALLET_FIXTURE" ]; then
+      echo "[recipe-harness] RECIPE_WALLET_FIXTURE is not a file: $RECIPE_WALLET_FIXTURE" >&2
+      exit 1
+    fi
+    resolved="$RECIPE_WALLET_FIXTURE"
+  else
+    for candidate in \
+      ${RUNTIME_DIR:+"$TARGET/$RUNTIME_DIR/wallet-fixture.json"} \
+      "$TARGET/temp/runtime/wallet-fixture.json" \
+      ${CDP_PORT:+"$TARGET/temp/.recipe-validation-${CDP_PORT}/wallet-fixture.json"} \
+      "$TARGET/temp/.agent-validation/wallet-fixture.json"
+    do
+      [ -f "$candidate" ] && { resolved="$candidate"; break; }
+    done
+  fi
+  [ -n "$resolved" ] || resolve_status=missing
+  if [ -n "$SOURCE_OUT" ]; then
+    node - "$SOURCE_OUT" "$resolved" <<'NODE'
+const fs = require('fs');
+const [out, fixture] = process.argv.slice(2);
+fs.mkdirSync(require('path').dirname(out), { recursive: true });
+fs.writeFileSync(out, `${JSON.stringify({
+  status: fixture ? 'present' : 'missing',
+  fixturePath: fixture || null,
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+  fi
+  [ -n "$resolved" ] && printf '%s\n' "$resolved"
+  status=pass
+  exit 0
+fi
+
+# prefill / seed-cdp phases
+[ -n "$FIXTURE" ] || { echo "Missing --fixture" >&2; exit 2; }
+[ -n "$STATE" ] || { echo "Missing --state" >&2; exit 2; }
+[ -n "$EXTENSION_DIR" ] || { echo "Missing --extension-dir" >&2; exit 2; }
+[ -n "$EXTENSION_ID_FILE" ] || { echo "Missing --extension-id-file" >&2; exit 2; }
+FS_SCRIPT="$(resolve_fixture_script)"
+
+if [ "$SUBCOMMAND" = prefill ]; then
+  [ -n "$PROFILE" ] || { echo "Missing --profile" >&2; exit 2; }
+  node "$FS_SCRIPT" generate --target "$TARGET" --fixture "$FIXTURE" --out "$STATE" || exit 1
+  node "$FS_SCRIPT" prefill-profile --target "$TARGET" --state "$STATE" --profile "$PROFILE" --extension-dir "$EXTENSION_DIR" --extension-id-file "$EXTENSION_ID_FILE" || exit 1
+else
+  [ -n "$CDP_PORT" ] || { echo "Missing --cdp-port" >&2; exit 2; }
+  [ -n "$OUT" ] || { echo "Missing --out" >&2; exit 2; }
+  node "$FS_SCRIPT" seed-cdp --target "$TARGET" --fixture "$FIXTURE" --state "$STATE" --cdp-port "$CDP_PORT" --extension-dir "$EXTENSION_DIR" --extension-id-file "$EXTENSION_ID_FILE" --out "$OUT" || exit 1
+fi
+status=pass