@deeeed/metamask-harness 0.14.0 → 0.14.1

package/dist/cli.js

@@ -19,6 +19,7 @@ import { handleDebug } from "./commands/debug.js";
 import { handleFixtures } from "./commands/fixtures.js";
 import { handleRecipeQuality } from "./commands/recipe-quality.js";
 import { handleStatus } from "./commands/status.js";
+import { handleCheck } from "./commands/check.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 import { runOneNode } from "./commands/run-engine.js";
 const COMMANDS = {
@@ -56,6 +57,8 @@ PROVE \u2014 run recipes and inspect capabilities:
                mm-harness flows list
   doctor     Readiness check for a checkout (no app launch).
                mm-harness doctor
+  check      Run bounded repo-local checks for an active diff.
+               mm-harness check diff --profile fast --artifacts-dir artifacts/validation
   actions    Describe the actions a manifest declares.
                mm-harness actions --adapter mobile
   manifest   Print/validate the action manifest for an adapter.
@@ -127,6 +130,7 @@ async function main(argv) {
   if (command === "debug") return handleDebug(argv.slice(1));
   if (command === "fixtures") return handleFixtures(argv.slice(1), { runOneNode });
   if (command === "recipe-quality") return handleRecipeQuality(argv.slice(1));
+  if (command === "check") return handleCheck(argv.slice(1));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);
   return handler(parseArgs(argv.slice(1), command));

package/dist/commands/call.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { loadActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
 import { recipeRunning } from "../heal-bounds.js";
+import { color } from "../cli-color.js";
 import { EXIT } from "./shared.js";
 import { describeManifestActions, fuzzyResolveActions } from "./manifest.js";
 import {
@@ -19,6 +20,7 @@ import {
 import { getAdapterSurface } from "../adapters/surface.js";
 import { handleListExecutables } from "./list-executables.js";
 import { applyDeviceTargeting } from "./device-target.js";
+import { coreDependencyBlock } from "./core-readiness.js";
 import {
   emitHealViolation,
   executeWithHealBounds,
@@ -96,6 +98,16 @@ async function handleCall(argv) {
     return EXIT.usage;
   }
   const resolvedAction = resolution.resolved;
+  const depsBlock = adapter === "core" && resolvedAction.startsWith("metamask.perps.") ? coreDependencyBlock(target) : null;
+  if (depsBlock) {
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, status: "fail", exitCode: EXIT.usage, error: depsBlock }, null, 2));
+    } else {
+      console.error(`\u2717 call: ${depsBlock.message}`);
+      console.error(`  Next: ${depsBlock.userAction}`);
+    }
+    return EXIT.usage;
+  }
   const recipe = synthesizeOneNodeRecipe(resolvedAction, args);
   const validation = await validateRecipeAdapterAware(recipe, manifest);
   if (validation.status === "invalid") {
@@ -157,8 +169,13 @@ async function handleCall(argv) {
     const rendered = callOutput !== void 0 ? `
 Result:
 ${formatCallOutput(callOutput)}` : "";
-    console.log(`call ${resolvedAction}: ${result.status}${rendered}
-Artifacts: ${result.artifactManifestPath}`);
+    const out = (style, text) => color(style, text, { stream: process.stdout });
+    console.log(
+      `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
+${out("label", "Result:")}
+${formatCallOutput(callOutput)}` : ""}
+${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
+    );
   }
   return result.status === "pass" ? EXIT.ok : EXIT.runtime;
 }

package/dist/commands/check.js

@@ -0,0 +1,326 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { detectAdapter } from "../harness.js";
+import { EXIT, usageOut } from "./shared.js";
+import { optionFlag, optionString, parseArgs } from "./parse-args.js";
+const USAGE = "mm-harness check diff [--target <repo>] [--adapter mobile|extension|core] [--base <ref>] [--profile fast|full] [--artifacts-dir <dir>] [--json]";
+const JS_TS_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$/u;
+const FORMAT_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$|\.json$|\.md$|\.css$|\.scss$|\.ya?ml$/u;
+const TEST_FILE_RE = /(?:^|[./_-])(?:test|spec)\.(?:c|m)?jsx?$|(?:^|[./_-])(?:test|spec)\.tsx?$/u;
+async function handleCheck(argv) {
+  const { positional, options } = parseArgs(argv, "check");
+  const action = positional[0];
+  const json = optionFlag(options, "json");
+  if (action !== "diff") {
+    const message = action ? `unknown action '${action}'` : "missing action";
+    return usageOut(json, "check", message, USAGE);
+  }
+  const target = path.resolve(optionString(options, "target") ?? optionString(options, "projectRoot") ?? process.cwd());
+  const explicitAdapter = optionString(options, "adapter") ?? optionString(options, "platform");
+  const detected = explicitAdapter ?? detectAdapter(target);
+  if (detected && !["mobile", "extension", "core"].includes(detected)) {
+    return usageOut(json, "check", `unsupported adapter '${detected}'`, USAGE);
+  }
+  const adapter = detected;
+  const profileInput = optionString(options, "profile");
+  if (profileInput && profileInput !== "fast" && profileInput !== "full") {
+    return usageOut(json, "check", "--profile must be fast or full", USAGE);
+  }
+  const profile = profileInput || "fast";
+  const explicitBaseRef = optionString(options, "base");
+  const base = explicitBaseRef ? { ref: explicitBaseRef, source: "flag" } : defaultBaseRef(target);
+  const baseRef = base.ref;
+  const artifactsDir = path.resolve(
+    optionString(options, "artifactsDir") ?? path.join(target, "temp", "recipe", "check-diff", timestampSlug())
+  );
+  fs.mkdirSync(artifactsDir, { recursive: true });
+  if (!isGitRepo(target)) {
+    return failEnvelope({
+      json,
+      adapter,
+      target,
+      profile,
+      baseRef,
+      artifactsDir,
+      message: `${target} is not a git checkout`,
+      code: "CHECK_DIFF_NOT_GIT"
+    });
+  }
+  const packageJson = readPackageJson(target);
+  const mergeBase = resolveMergeBase(target, baseRef);
+  const changedFiles = listChangedFiles(target, mergeBase, artifactsDir);
+  const existingChangedFiles = changedFiles.filter((file) => fs.existsSync(path.join(target, file)));
+  const checks = [];
+  checks.push(
+    runToolCheck({
+      id: "eslint",
+      label: "Changed-file ESLint",
+      target,
+      artifactsDir,
+      files: existingChangedFiles.filter((file) => JS_TS_EXT_RE.test(file)),
+      command: executable(target, "eslint"),
+      args: ["--cache", "--cache-location", path.join(artifactsDir, "eslintcache"), "--max-warnings=0", "--no-warn-ignored"]
+    })
+  );
+  checks.push(
+    runToolCheck({
+      id: "prettier",
+      label: "Changed-file Prettier",
+      target,
+      artifactsDir,
+      files: existingChangedFiles.filter((file) => FORMAT_EXT_RE.test(file)),
+      command: executable(target, "prettier"),
+      args: ["--check"]
+    })
+  );
+  checks.push(
+    runToolCheck({
+      id: "jest",
+      label: "Changed test files",
+      target,
+      artifactsDir,
+      files: existingChangedFiles.filter((file) => TEST_FILE_RE.test(file)),
+      command: executable(target, "jest"),
+      args: ["--no-coverage"]
+    })
+  );
+  if (profile === "full") {
+    checks.push(runTypecheck({ target, artifactsDir, packageJson }));
+  } else {
+    checks.push({
+      id: "typecheck",
+      label: "TypeScript project check",
+      status: "skip",
+      reason: "profile=fast; run with --profile full for repo-wide typecheck"
+    });
+  }
+  const status = checks.some((check) => check.status === "fail") ? "fail" : "pass";
+  const exitCode = status === "pass" ? EXIT.ok : EXIT.validation;
+  const summary = {
+    schemaVersion: 1,
+    command: "check",
+    action: "diff",
+    status,
+    exitCode,
+    adapter: adapter ?? null,
+    target,
+    profile,
+    baseRef,
+    baseSource: base.source,
+    baseLabel: base.label ?? null,
+    mergeBase,
+    changedFiles,
+    checks,
+    artifacts: {
+      dir: artifactsDir,
+      summaryJson: path.join(artifactsDir, "validation-summary.json"),
+      summaryMarkdown: path.join(artifactsDir, "validation-summary.md")
+    }
+  };
+  writeSummaryArtifacts(summary);
+  if (json) console.log(JSON.stringify(summary, null, 2));
+  else renderHuman(summary);
+  return exitCode;
+}
+function timestampSlug() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z");
+}
+function isGitRepo(target) {
+  return runCommand("git", ["rev-parse", "--is-inside-work-tree"], target).status === 0;
+}
+function defaultBaseRef(target) {
+  const prBase = githubPullRequestBase(target);
+  if (prBase) return prBase;
+  const remoteHead = runCommand("git", ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], target).stdout.trim();
+  if (remoteHead && verifyRef(target, remoteHead)) return { ref: remoteHead, source: "remote-head" };
+  for (const ref of ["origin/develop", "origin/main", "develop", "main", "HEAD"]) {
+    if (verifyRef(target, ref)) return { ref, source: "fallback" };
+  }
+  return { ref: "", source: "fallback" };
+}
+function githubPullRequestBase(target) {
+  const result = runCommand("gh", ["pr", "view", "--json", "baseRefName", "--jq", ".baseRefName"], target);
+  if (result.status !== 0) return null;
+  const baseName = result.stdout.trim();
+  if (!baseName) return null;
+  for (const ref of [`origin/${baseName}`, `upstream/${baseName}`, baseName]) {
+    if (verifyRef(target, ref)) return { ref, source: "github-pr", label: baseName };
+  }
+  return null;
+}
+function verifyRef(target, ref) {
+  return runCommand("git", ["rev-parse", "--verify", ref], target).status === 0;
+}
+function resolveMergeBase(target, baseRef) {
+  if (!baseRef) return null;
+  const result = runCommand("git", ["merge-base", "HEAD", baseRef], target);
+  if (result.status === 0) return result.stdout.trim() || null;
+  const verify = runCommand("git", ["rev-parse", "--verify", baseRef], target);
+  return verify.status === 0 ? verify.stdout.trim() || null : null;
+}
+function listChangedFiles(target, mergeBase, artifactsDir) {
+  const files = /* @__PURE__ */ new Set();
+  const addLines = (output) => {
+    for (const line of output.split("\n")) {
+      const file = line.trim();
+      if (file) files.add(file);
+    }
+  };
+  if (mergeBase) {
+    addLines(runCommand("git", ["diff", "--name-only", "--diff-filter=ACMR", `${mergeBase}...HEAD`], target).stdout);
+  }
+  addLines(runCommand("git", ["diff", "--name-only", "--diff-filter=ACMR", "HEAD"], target).stdout);
+  addLines(runCommand("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR"], target).stdout);
+  addLines(runCommand("git", ["ls-files", "--others", "--exclude-standard"], target).stdout);
+  return [...files].filter((file) => !isUnderArtifactsDir(target, artifactsDir, file)).sort();
+}
+function isUnderArtifactsDir(target, artifactsDir, file) {
+  const artifactRel = normalizeRelativePath(path.relative(path.resolve(target), path.resolve(artifactsDir)));
+  if (!artifactRel || artifactRel.startsWith("../") || artifactRel === "..") return false;
+  const normalized = normalizeRelativePath(file);
+  return normalized === artifactRel || normalized.startsWith(`${artifactRel}/`);
+}
+function normalizeRelativePath(value) {
+  return value.split(path.sep).join("/");
+}
+function executable(target, name) {
+  const local = path.join(target, "node_modules", ".bin", name);
+  return fs.existsSync(local) ? local : null;
+}
+function runToolCheck(input) {
+  if (input.files.length === 0) {
+    return { id: input.id, label: input.label, status: "skip", reason: "no changed matching files" };
+  }
+  if (!input.command) {
+    return { id: input.id, label: input.label, status: "skip", reason: `${input.id} binary not found in node_modules/.bin` };
+  }
+  return runCheckCommand(input.id, input.label, input.target, input.artifactsDir, input.command, [...input.args, ...input.files]);
+}
+function runTypecheck(input) {
+  const scripts = input.packageJson?.scripts && typeof input.packageJson.scripts === "object" ? input.packageJson.scripts : {};
+  if (typeof scripts["lint:tsc"] === "string") {
+    return runCheckCommand("typecheck", "TypeScript project check", input.target, input.artifactsDir, "yarn", ["lint:tsc"]);
+  }
+  const tsc = executable(input.target, "tsc");
+  if (tsc) {
+    return runCheckCommand("typecheck", "TypeScript project check", input.target, input.artifactsDir, tsc, ["--noEmit"]);
+  }
+  return { id: "typecheck", label: "TypeScript project check", status: "skip", reason: "no lint:tsc script or tsc binary found" };
+}
+function runCheckCommand(id, label, target, artifactsDir, command, args) {
+  const result = runCommand(command, args, target);
+  const logPath = path.join(artifactsDir, `${id}.log`);
+  fs.writeFileSync(logPath, renderCommandLog(command, args, result));
+  return {
+    id,
+    label,
+    status: result.status === 0 ? "pass" : "fail",
+    command: [command, ...args].join(" "),
+    exitCode: result.status,
+    logPath,
+    durationMs: result.durationMs
+  };
+}
+function runCommand(command, args, cwd) {
+  const started = Date.now();
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    env: process.env,
+    maxBuffer: 64 * 1024 * 1024
+  });
+  const status = result.error ? 127 : result.status ?? 1;
+  return {
+    status,
+    stdout: result.stdout ?? "",
+    stderr: result.error ? String(result.error) : result.stderr ?? "",
+    durationMs: Date.now() - started
+  };
+}
+function renderCommandLog(command, args, result) {
+  return [
+    `$ ${[command, ...args].join(" ")}`,
+    `exit: ${result.status}`,
+    `duration_ms: ${result.durationMs}`,
+    "",
+    "--- stdout ---",
+    result.stdout.trimEnd(),
+    "",
+    "--- stderr ---",
+    result.stderr.trimEnd(),
+    ""
+  ].join("\n");
+}
+function readPackageJson(target) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(target, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeSummaryArtifacts(summary) {
+  fs.writeFileSync(summary.artifacts.summaryJson, `${JSON.stringify(summary, null, 2)}
+`);
+  fs.writeFileSync(summary.artifacts.summaryMarkdown, renderMarkdown(summary));
+}
+function renderMarkdown(summary) {
+  const lines = [
+    "# mm-harness check diff",
+    "",
+    `Verdict: ${summary.status}`,
+    `Profile: ${summary.profile}`,
+    `Base: ${summary.baseRef || "(none)"} (${summary.baseSource || "unknown"}${summary.baseLabel ? `: ${summary.baseLabel}` : ""})`,
+    `Changed files: ${summary.changedFiles.length}`,
+    "",
+    "## Checks",
+    ""
+  ];
+  for (const check of summary.checks) {
+    lines.push(`- ${check.status.toUpperCase()} ${check.id}${check.reason ? ` \u2014 ${check.reason}` : ""}${check.logPath ? ` (${check.logPath})` : ""}`);
+  }
+  lines.push("", "## Changed Files", "");
+  for (const file of summary.changedFiles) lines.push(`- ${file}`);
+  return `${lines.join("\n")}
+`;
+}
+function renderHuman(summary) {
+  const mark = summary.status === "pass" ? "\u2713" : "\u2717";
+  const baseText = `${summary.baseRef || "(none)"}${summary.baseSource ? ` [${summary.baseSource}]` : ""}`;
+  console.log(`${mark} check diff: ${summary.status} \xB7 ${summary.changedFiles.length} changed file(s) \xB7 profile=${summary.profile} \xB7 base=${baseText}`);
+  if (summary.changedFiles.length > 0) {
+    console.log("Changed files:");
+    for (const file of summary.changedFiles.slice(0, 100)) console.log(`  - ${file}`);
+    if (summary.changedFiles.length > 100) console.log(`  ... ${summary.changedFiles.length - 100} more; full list in validation-summary.json`);
+  }
+  for (const check of summary.checks) {
+    const prefix = check.status === "pass" ? "\u2713" : check.status === "fail" ? "\u2717" : "-";
+    console.log(`  ${prefix} ${check.id}: ${check.status}${check.reason ? ` (${check.reason})` : ""}`);
+    if (check.status === "fail" && check.logPath) console.log(`    log: ${check.logPath}`);
+  }
+  console.log(`Artifacts: ${summary.artifacts.summaryJson}`);
+}
+function failEnvelope(input) {
+  const exitCode = EXIT.usage;
+  const body = {
+    schemaVersion: 1,
+    command: "check",
+    action: "diff",
+    status: "fail",
+    exitCode,
+    adapter: input.adapter ?? null,
+    target: input.target,
+    profile: input.profile,
+    baseRef: input.baseRef,
+    baseSource: "unknown",
+    artifacts: { dir: input.artifactsDir },
+    error: { code: input.code, message: input.message }
+  };
+  if (input.json) console.log(JSON.stringify(body, null, 2));
+  else console.error(`\u2717 check diff: ${input.message}
+  Next: ${USAGE}`);
+  return exitCode;
+}
+export {
+  handleCheck
+};

package/dist/commands/core-readiness.js

@@ -0,0 +1,75 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+const requireFromHarness = createRequire(import.meta.url);
+const CORE_RUNTIME_DEPS = ["immer"];
+function coreDependencyBlock(target) {
+  const resolved = path.resolve(target);
+  const nodeLinker = readYarnNodeLinker(resolved);
+  const installAction = `cd ${shellQuote(resolved)} && yarn install --immutable`;
+  if (nodeLinker === "pnp") {
+    if (!fs.existsSync(path.join(resolved, ".pnp.cjs"))) {
+      return {
+        code: "CORE_DEPS_MISSING",
+        message: "core dependencies are not installed for Yarn PnP (.pnp.cjs is missing).",
+        userAction: installAction
+      };
+    }
+    return null;
+  }
+  if (!fs.existsSync(path.join(resolved, "node_modules"))) {
+    return {
+      code: "CORE_DEPS_MISSING",
+      message: nodeLinker === "node-modules" ? "core dependencies are not installed (nodeLinker requires node_modules, but node_modules is missing)." : "core dependencies are not installed (node_modules is missing).",
+      userAction: installAction
+    };
+  }
+  if (!fs.existsSync(path.join(resolved, "node_modules/.bin/tsx"))) {
+    return {
+      code: "CORE_DEPS_INCOMPLETE",
+      message: "core dependencies are incomplete (node_modules/.bin/tsx is missing).",
+      userAction: installAction
+    };
+  }
+  for (const dependency of CORE_RUNTIME_DEPS) {
+    if (!canResolveFromTarget(dependency, resolved)) {
+      return {
+        code: "CORE_DEPS_INCOMPLETE",
+        message: `core dependencies are incomplete (cannot resolve ${dependency} from the target checkout).`,
+        userAction: installAction
+      };
+    }
+  }
+  return null;
+}
+function corePnpNodeOptions(target, current) {
+  if (readYarnNodeLinker(target) !== "pnp") return current;
+  const pnp = path.join(path.resolve(target), ".pnp.cjs");
+  if (!fs.existsSync(pnp)) return current;
+  const pnpOption = `--require ${pnp}`;
+  return current ? `${current} ${pnpOption}` : pnpOption;
+}
+function canResolveFromTarget(specifier, target) {
+  try {
+    requireFromHarness.resolve(specifier, { paths: [target] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readYarnNodeLinker(target) {
+  try {
+    const yarnrc = fs.readFileSync(path.join(target, ".yarnrc.yml"), "utf8");
+    const match = /^nodeLinker:\s*["']?([^"'\s#]+)["']?/mu.exec(yarnrc);
+    return match?.[1];
+  } catch {
+    return void 0;
+  }
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+export {
+  coreDependencyBlock,
+  corePnpNodeOptions
+};

package/dist/commands/device-target.js

@@ -49,7 +49,13 @@ function renderDeviceList(devices, out) {
 }
 function deviceSelected(device) {
   if (device.platform === "android") {
-    return process.env.ADB_SERIAL === device.id || process.env.ANDROID_SERIAL === device.id;
+    if (process.env.ADB_SERIAL === device.id || process.env.ANDROID_SERIAL === device.id) return true;
+    const pinName = process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ANDROID_DEVICE || "";
+    if (!pinName) return false;
+    if (pinName === device.id) return true;
+    const name = device.name ? normalizeDeviceName(device.name) : "";
+    const normalizedPin = normalizeDeviceName(pinName);
+    return Boolean(name && (normalizedPin === name || normalizedPin.startsWith(`${name} -`)));
   }
   return process.env.IOS_SIMULATOR === device.id || process.env.SIM_UDID === device.id || process.env.IOS_SIMULATOR === device.name;
 }
@@ -58,8 +64,20 @@ function isTargetable(device) {
   if (device.platform === "ios") return device.state === "Booted";
   return false;
 }
+function mobilePlatformPreference(options) {
+  const platform = optionString(options, "platform");
+  return platform === "ios" || platform === "android" ? platform : void 0;
+}
+function configuredPinForPlatform(platform) {
+  if (platform === "ios") return process.env.IOS_SIMULATOR || process.env.SIM_UDID || void 0;
+  return process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ANDROID_DEVICE || void 0;
+}
+function oppositePlatform(platform) {
+  return platform === "ios" ? "android" : "ios";
+}
 function applyDeviceTargeting(command, adapter, options, opts) {
   const device = optionString(options, "device");
+  const platformPreference = mobilePlatformPreference(options);
   if (adapter !== "mobile") {
     if (device !== void 0) {
       return {
@@ -73,15 +91,26 @@ function applyDeviceTargeting(command, adapter, options, opts) {
   }
   if (device !== void 0) {
     const connected2 = listConnectedDevices();
+    const setResolvedDevice = (matched) => {
+      if (platformPreference && matched.platform !== platformPreference) {
+        return {
+          ok: false,
+          code: "DEVICE_PLATFORM_CONFLICT",
+          message: `--device ${device} resolves to ${matched.platform}, but --platform ${platformPreference} was requested.
+  To use this device intentionally, drop --platform ${platformPreference} or choose a ${platformPreference} device.`
+        };
+      }
+      if (matched.platform === "android") setAndroidDeviceEnv(matched.id, matched.name);
+      else setIosDeviceEnv(matched.id, matched.name);
+      return { ok: true };
+    };
     const androidById = connected2.find((d) => d.platform === "android" && d.id === device);
     if (androidById) {
-      setAndroidDeviceEnv(device, androidById.name);
-      return { ok: true };
+      return setResolvedDevice(androidById);
     }
     const iosById = connected2.find((d) => d.platform === "ios" && d.id === device);
     if (iosById) {
-      setIosDeviceEnv(device, iosById.name);
-      return { ok: true };
+      return setResolvedDevice(iosById);
     }
     const normalizedDevice = normalizeDeviceName(device);
     const byName = connected2.filter((d) => {
@@ -90,10 +119,7 @@ function applyDeviceTargeting(command, adapter, options, opts) {
       return name === device || normalizedName === normalizedDevice || d.platform === "android" && normalizedDevice.startsWith(`${normalizedName} -`);
     });
     if (byName.length === 1) {
-      const matched = byName[0];
-      if (matched.platform === "android") setAndroidDeviceEnv(matched.id, matched.name);
-      else setIosDeviceEnv(matched.id, matched.name);
-      return { ok: true };
+      return setResolvedDevice(byName[0]);
     }
     if (byName.length > 1) {
       return {
@@ -113,6 +139,75 @@ ${formatConnectedDevices(connected2)}` : `  No devices are currently connected (
   }
   const connected = listConnectedDevices();
   const targetable = connected.filter(isTargetable);
+  if (platformPreference) {
+    const selectedTargetable2 = targetable.filter(deviceSelected);
+    const platformTargetable = targetable.filter((d) => d.platform === platformPreference);
+    const selectedPlatformTargetable = platformTargetable.filter(deviceSelected);
+    const configuredPin = configuredPinForPlatform(platformPreference);
+    const oppositePin = configuredPinForPlatform(oppositePlatform(platformPreference));
+    if (selectedPlatformTargetable.length === 1) {
+      const selected = selectedPlatformTargetable[0];
+      if (selected.platform === "android") setAndroidDeviceEnv(selected.id, selected.name);
+      else setIosDeviceEnv(selected.id, selected.name);
+      return { ok: true };
+    }
+    if (selectedTargetable2.length > 0) {
+      return {
+        ok: false,
+        code: "DEVICE_PLATFORM_CONFLICT",
+        message: `--platform ${platformPreference} conflicts with the current slot-selected device.
+  Selected devices:
+${formatConnectedDevices(selectedTargetable2)}
+  To use a different connected device intentionally, pass --device <id>.`
+      };
+    }
+    if (!configuredPin && oppositePin) {
+      return {
+        ok: false,
+        code: "DEVICE_PLATFORM_CONFLICT",
+        message: `--platform ${platformPreference} conflicts with the configured slot target.
+  Configured ${oppositePlatform(platformPreference)} target: ${oppositePin}
+  To use a different connected device intentionally, pass --device <id>.`
+      };
+    }
+    if (configuredPin) {
+      if (command === "launch" || !opts.gate) return { ok: true };
+      return {
+        ok: false,
+        code: "DEVICE_PLATFORM_PIN_NOT_READY",
+        message: `--platform ${platformPreference} matches the configured slot target, but that target is not ready.
+  Configured target: ${configuredPin}
+  Connected devices:
+${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}
+  Next: run mm-harness launch ${platformPreference}, or pass --device <id> to intentionally use another target.`
+      };
+    }
+    if (platformTargetable.length === 1) {
+      const selected = platformTargetable[0];
+      if (selected.platform === "android") setAndroidDeviceEnv(selected.id, selected.name);
+      else setIosDeviceEnv(selected.id, selected.name);
+      return { ok: true };
+    }
+    if (platformTargetable.length === 0) {
+      if (command === "launch" && platformPreference === "ios") return { ok: true };
+      return {
+        ok: false,
+        code: "DEVICE_PLATFORM_NOT_FOUND",
+        message: `--platform ${platformPreference} did not match any ready connected device.
+` + (connected.length > 0 ? `  Connected devices:
+${formatConnectedDevices(connected)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
+      };
+    }
+    return {
+      ok: false,
+      code: "DEVICE_PLATFORM_AMBIGUOUS",
+      message: `${platformTargetable.length} ${platformPreference} devices available \u2014 ${command} needs exactly one target.
+  Connected devices:
+${formatConnectedDevices(connected)}
+  Add --device <id> to disambiguate, e.g.:${platformTargetable.map((d) => `
+    --device ${d.id}`).join("")}`
+    };
+  }
   const selectedTargetable = targetable.filter(deviceSelected);
   if (selectedTargetable.length === 1) {
     const selected = selectedTargetable[0];
@@ -134,9 +229,17 @@ ${formatConnectedDevices(connected)}
   }
   return { ok: true };
 }
+function scopedDevices(devices, allDevices = false) {
+  const withSelection = devices.map((device) => ({ ...device, selected: deviceSelected(device) }));
+  if (allDevices) return withSelection;
+  const selected = withSelection.filter((device) => device.selected);
+  return selected.length > 0 ? selected : withSelection;
+}
 export {
   applyDeviceTargeting,
   deviceSelected,
   formatConnectedDevices,
-  renderDeviceList
+  mobilePlatformPreference,
+  renderDeviceList,
+  scopedDevices
 };