@swmansion/argent 0.25.1-next.20 → 0.25.1-next.22

package/dist/cli-cmds.mjs

@@ -21857,7 +21857,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.25.1-next.20";
+    return "0.25.1-next.22";
   }
   return "0.0.0";
 }
@@ -23211,7 +23211,8 @@ Subcommands:
 
 Options (run):
   --device <id>          Device id to run against (auto-detected when omitted)
-  --platform <p>         ios | android | chromium | vega \u2014 narrow auto-detection
+  --platform <p>         ios | android | chromium | vega | ios-remote \u2014 narrow
+                         auto-detection (ios never picks a remote simulator)
   --update-baselines     Write/refresh screenshot baselines instead of diffing
   --output <dir>         Also write failed snapshot images (baseline/current/diff)
                          under <dir>/<flow>/ \u2014 a stable path for CI artifact

package/dist/installer.mjs

@@ -16710,7 +16710,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.25.1-next.20";
+    return "0.25.1-next.22";
   }
   return "0.0.0";
 }

package/dist/tool-server.cjs

@@ -94704,7 +94704,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.25.1-next.20";
+    return "0.25.1-next.22";
   }
   return "0.0.0";
 }
@@ -146123,6 +146123,7 @@ function isIdleCondition(raw, kind) {
   return true;
 }
 var LAUNCH_PLATFORMS = ["ios", "android", "chromium", "vega"];
+var SELECTABLE_PLATFORMS = [...LAUNCH_PLATFORMS, "ios-remote"];
 var LAUNCH_MAP_KEYS = ["native", ...LAUNCH_PLATFORMS];
 function parseChromiumLaunch(raw) {
   if (typeof raw === "string" && raw.length > 0) return raw;
@@ -147375,7 +147376,7 @@ var DEVICE_BIND_KEYS = ["udid", "device_id", "device"];
 var DEVICE_BIND_LIST_KEYS = ["devices"];
 var DEVICE_ARG_KEYS = DEVICE_BIND_KEYS;
 function deviceEntryId(d) {
-  if (d.platform === "ios") return d.udid;
+  if (d.platform === "ios" || d.platform === "ios-remote") return d.udid;
   if (d.platform === "chromium") return d.id;
   return d.serial;
 }
@@ -147383,6 +147384,8 @@ function isBooted(d) {
   switch (d.platform) {
     case "ios":
       return d.state === "Booted";
+    case "ios-remote":
+      return d.state === "Booted";
     case "android":
       return d.state === "device";
     case "vega":
@@ -147677,6 +147680,7 @@ function adaptFullHierarchy(raw) {
   });
   return screenW > 0 && screenH > 0 ? { tree, screen: { width: screenW, height: screenH } } : { tree };
 }
+var FLOW_TREE_MAX_DEPTH = 100;
 var FULL_HIERARCHY_FIELDS = [
   "className",
   "identifier",
@@ -147708,9 +147712,9 @@ async function queryFullHierarchyTree(registry2, device, target) {
     const ndRef = nativeDevtoolsRef(device);
     nativeApi = await registry2.resolveService(ndRef.urn, ndRef.options);
   } catch (err) {
-    throw new Error(
+    throw wrapPreservingFailure(
       `native devtools is unavailable (${errMsg2(err)}) \u2014 flows resolve selectors against the full view hierarchy it serves`,
-      { cause: err }
+      err
     );
   }
   let bundleId;
@@ -147779,7 +147783,7 @@ async function queryFullHierarchyTree(registry2, device, target) {
       resolved = await resolveNativeTargetApp(nativeApi, void 0);
     } catch (err) {
       const timedOut2 = getFailureSignal(err)?.error_code === FAILURE_CODES.NATIVE_DEVTOOLS_RPC_TIMEOUT;
-      if (!timedOut2 || !target) throw err;
+      if (!timedOut2 || !target) throw await explainTargetingFailure(err, nativeApi, device, target);
       if (!isInjectableBundleId(target.bundleId)) {
         throw new FailureError(
           systemAppFlowTargetRefusal(target.bundleId),
@@ -147792,13 +147796,15 @@ async function queryFullHierarchyTree(registry2, device, target) {
           err instanceof Error ? { cause: err } : void 0
         );
       }
-      if (!nativeApi.listConnectedBundleIds().includes(target.bundleId)) throw err;
+      if (!nativeApi.listConnectedBundleIds().includes(target.bundleId)) {
+        throw await explainTargetingFailure(err, nativeApi, device, target);
+      }
       let hintState;
       try {
         hintState = await nativeApi.getAppState(target.bundleId);
       } catch (probeErr) {
         if (getFailureSignal(probeErr)?.error_code === FAILURE_CODES.NATIVE_DEVTOOLS_RPC_TIMEOUT) {
-          throw err;
+          throw await explainTargetingFailure(err, nativeApi, device, target);
         }
         throw probeErr;
       }
@@ -147817,13 +147823,18 @@ async function queryFullHierarchyTree(registry2, device, target) {
       resolved = { bundleId: target.bundleId };
     }
     bundleId = resolved.bundleId;
+    if (!nativeApi.listConnectedBundleIds().includes(bundleId)) {
+      throw new Error(
+        `${bundleId} answered the target probe and then dropped its native-devtools connection before the view hierarchy could be read. It was instrumented, so a retry may ride this out; if the connection does not come back, relaunch with restart-app (or a flow \`launch\` step) \u2014 launch-app would only foreground the process that just lost it.`
+      );
+    }
   }
   const rawResult = await nativeApi.queryViewHierarchy(
     bundleId,
     "ViewHierarchy.getFullHierarchy",
     {
       fields: FULL_HIERARCHY_FIELDS,
-      maxDepth: 40
+      maxDepth: FLOW_TREE_MAX_DEPTH
     }
   );
   if (rawResult.error) {
@@ -147840,6 +147851,86 @@ async function queryFullHierarchyTree(registry2, device, target) {
 function errMsg2(err) {
   return err instanceof Error ? err.message : String(err);
 }
+async function explainTargetingFailure(err, nativeApi, device, launched) {
+  const failureCode = getFailureSignal(err)?.error_code;
+  if (failureCode === FAILURE_CODES.NATIVE_TARGET_MULTIPLE_APPS_AMBIGUOUS) {
+    const terminate = await terminateCommand(device);
+    const clearOthers = terminate ? `; clear the others with \`${terminate}\` (argent has no terminate tool, and restart-app would just bring that app back to the front).` : `.`;
+    return wrapPreservingFailure(
+      // Short header: the embedded diagnostic already says the set is
+      // ambiguous, and the per-app entries need those 90 characters.
+      `could not target an app to read the view hierarchy from:
+${cappedAppDiagnostic(withoutExplicitBundleIdAdvice(errMsg2(err)))}
+Flow selectors auto-target and cannot name a bundleId. Foreground the intended app with launch-app (it does not terminate), then retry${clearOthers}`,
+      err
+    );
+  }
+  if (failureCode === FAILURE_CODES.NATIVE_TARGET_SINGLE_APP_NOT_FOREGROUND) {
+    return wrapPreservingFailure(
+      `the only native-devtools-connected app is not foreground, so it cannot be auto-targeted:
+${withoutExplicitBundleIdAdvice(errMsg2(err))}
+Flow selector steps auto-target and cannot provide a bundleId. Bring that app to the foreground with launch-app (it does not terminate \u2014 the app is already instrumented, just not frontmost), then retry.`,
+      err
+    );
+  }
+  const stillConnected = nativeApi.listConnectedBundleIds();
+  if (stillConnected.length > 0) {
+    const launchedGone = launched !== void 0 && !stillConnected.includes(launched.bundleId);
+    const terminate = stillConnected.length > (launchedGone ? 0 : 1) ? await terminateCommand(device) : void 0;
+    const clearOthers = terminate ? ` To clear the others use \`${terminate}\` \u2014 argent exposes no terminate tool, and restart-app would bring the app you cleared back to the front instead.` : ``;
+    return wrapPreservingFailure(
+      `could not read the state of the native-devtools-connected apps, so none could be auto-targeted (${firstClause(err)}). Connected: ${cappedList(stillConnected)}. ` + (launchedGone ? `${launched.bundleId} \u2014 the app this flow launched \u2014 is NOT among them, so relaunch it with restart-app (or a flow \`launch\` step); launch-app does not terminate, so it would only foreground the same uninstrumented process.` : `They are instrumented \u2014 do not relaunch. A suspended app stops answering: foreground the app the flow drives with launch-app (it does not terminate), then retry.`) + clearOthers,
+      err
+    );
+  }
+  return wrapPreservingFailure(
+    `no app is connected to native devtools, so flow selectors have no instrumented process to read the view hierarchy from (${firstClause(err)}). Relaunch with restart-app (or a flow \`launch\` step): launch-app does not terminate, so on an app already running from Metro/Expo, Xcode, or its icon it only foregrounds that uninstrumented process. Argent treats an Apple system app (com.apple.*) as non-injectable \u2014 the native-devtools feature tools refuse it too \u2014 so if one never connects, drive it with raw point taps and tool: await-ui-element steps.`,
+    err
+  );
+}
+async function terminateCommand(device) {
+  try {
+    const { prefix } = await simctlTargetForUdid(device.id);
+    return `xcrun ${prefix.join(" ")} terminate <udid> <bundleId>`;
+  } catch {
+    return void 0;
+  }
+}
+function firstClause(err) {
+  const firstLine2 = errMsg2(err).split("\n", 1)[0];
+  const sentenceEnd = /\.(?=\s|$)/.exec(firstLine2);
+  return sentenceEnd === null ? firstLine2 : firstLine2.slice(0, sentenceEnd.index + 1);
+}
+var MAX_LISTED_APPS = 2;
+function cappedList(bundleIds) {
+  if (bundleIds.length <= MAX_LISTED_APPS) return bundleIds.join(", ");
+  const dropped = bundleIds.length - MAX_LISTED_APPS;
+  return `${bundleIds.slice(0, MAX_LISTED_APPS).join(", ")} (+${dropped} more)`;
+}
+function cappedAppDiagnostic(message) {
+  const lines = message.split("\n");
+  const isEntry = (line) => line.startsWith("- ");
+  const firstEntry = lines.findIndex(isEntry);
+  if (firstEntry === -1) return message;
+  const entries = lines.filter(isEntry);
+  if (entries.length <= MAX_LISTED_APPS) return message;
+  const kept = entries.slice(0, MAX_LISTED_APPS);
+  const dropped = entries.length - MAX_LISTED_APPS;
+  return [
+    ...lines.slice(0, firstEntry),
+    ...kept,
+    `- (+${dropped} more connected app${dropped === 1 ? "" : "s"})`,
+    ...lines.slice(firstEntry + entries.length).filter((line) => !isEntry(line))
+  ].join("\n");
+}
+function withoutExplicitBundleIdAdvice(message) {
+  return message.replace(/\nProvide bundleId explicitly[^\n]*$/, "");
+}
+function wrapPreservingFailure(message, err) {
+  const cause = err instanceof Error ? err : new Error(String(err));
+  const signal = getFailureSignal(err);
+  return signal ? new FailureError(message, signal, { cause }) : new Error(message, { cause });
+}
 function projectIosDeviceNode(node) {
   const onScreen = node.frame.width > 0 && node.frame.height > 0;
   return {
@@ -149496,7 +149587,7 @@ function unmetWaitWarningFor(cause) {
 }
 function indeterminateReasonCaveat(udid) {
   if (platformOf(udid) !== "ios") return "";
-  return ". That reason may tell you to pass `bundleId` \u2014 it is quoted from the shared native-target error, and it does not apply here: the probe predicts an `await:`/`assert:` directive, and no directive takes a bundleId, so neither this probe nor the runner accepts one (the `bundleId` on this step reached the live wait only). What the runner's iOS tree needs is an app with argent's instrumentation loaded \u2014 relaunch it with `launch-app` or a flow `launch:` step. An app that cannot load it at all, such as a `com.apple.*` system app, can never be probed or converted: keep the check as a raw `tool:` step";
+  return ". One thing that reason cannot see is this step: the probe predicts an `await:`/`assert:` directive, and no directive takes a bundleId, so neither this probe nor the runner accepts one (the `bundleId` on this step reached the live wait only)";
 }
 var CANCELLED_PROBE_WARNING = "recorded, but the re-probe against the tree the RUNNER reads was cancelled before it answered. The step itself ran and is written to the flow; only the verdict is missing, so whether it would convert to `await:`/`assert:` is UNKNOWN, not known-bad \u2014 record the wait again, uncancelled, before trusting the conversion";
 var PROBE_MAX_TREE_READ_MS = 2500;
@@ -149570,6 +149661,11 @@ async function probeAgainstRunnerTree(registry2, ctx, args) {
     (condition === "text" ? textTieClause(args.udid) : "") + " " + SPELLING_CLAUSE + ` ${treeDivergenceFor(args.udid, condition)} ${runnerSideReadClause(args.udid, condition)}`
   };
 }
+function roleOnlySelectorWarning(selector) {
+  if (selector.role === void 0 || selector.identifier !== void 0) return void 0;
+  if (selector.text !== void 0 || selector.textMatches !== void 0) return void 0;
+  return `selector ${describeSelector(selector)} matches by role alone (the tapped element has no id or visible text) \u2014 replay takes whichever element of that role ranks first, so re-record against a labelled element if that is not reliably this one`;
+}
 async function captureTapSelector(registry2, session, udid, point) {
   try {
     const device = resolveDevice(udid);
@@ -149595,7 +149691,11 @@ async function captureTapSelector(registry2, session, udid, point) {
         warning: `selector ${describeSelector(selector)} resolves to a different element on this screen; kept coordinates (brittle)`
       };
     }
-    return { selector, warning: fallbackSourceWarning(source, device.platform) };
+    const warnings = [
+      roleOnlySelectorWarning(selector),
+      fallbackSourceWarning(source, device.platform)
+    ].filter((w) => w !== void 0);
+    return { selector, ...warnings.length > 0 ? { warning: warnings.join("; ") } : {} };
   } catch (err) {
     return {
       warning: `selector capture failed (${err instanceof Error ? err.message : String(err)}); kept coordinates`
@@ -153964,8 +154064,8 @@ var zodSchema66 = external_exports.object({
   device: external_exports.string().optional().describe(
     "Device id to run against (iOS UDID, Android/Vega serial, Chromium id) \u2014 the id list-devices reports. Auto-detected when omitted, but only when exactly one booted device matches (optionally narrowed by `platform`); with several booted the run fails and lists them, so pass this explicitly whenever more than one device is up."
   ),
-  platform: external_exports.enum(LAUNCH_PLATFORMS).optional().describe(
-    "Restrict auto-detection to this platform when several devices are booted. `chromium` does more than filter: with no `device` it SELECTS the self-boot branch for an e2e flow - the runner boots an Electron instance from the `launch` step's chromium value and tears it down after the run (a single-key `launch: { chromium: \u2026 }` map selects it on its own, without this parameter). When it selects that branch it never falls back to device auto-detection (a fragment, or an e2e launch map with no `chromium` key, still does), and the launch value must be a real Electron app path on the tool-server host: a bare-string `launch:` - what the recorder writes - holds an installed-app bundle id, so passing `chromium` for one fails the whole run with `Electron boot: path does not exist`. Edit the launch to `{ chromium: <app path> }` first."
+  platform: external_exports.enum(SELECTABLE_PLATFORMS).optional().describe(
+    "Restrict auto-detection to this platform when several devices are booted. `ios` selects local simulators only \u2014 pass `ios-remote` to select a remote one. `chromium` does more than filter: with no `device` it SELECTS the self-boot branch for an e2e flow - the runner boots an Electron instance from the `launch` step's chromium value and tears it down after the run (a single-key `launch: { chromium: \u2026 }` map selects it on its own, without this parameter). When it selects that branch it never falls back to device auto-detection (a fragment, or an e2e launch map with no `chromium` key, still does), and the launch value must be a real Electron app path on the tool-server host: a bare-string `launch:` - what the recorder writes - holds an installed-app bundle id, so passing `chromium` for one fails the whole run with `Electron boot: path does not exist`. Edit the launch to `{ chromium: <app path> }` first."
   ),
   updateBaselines: external_exports.boolean().optional().describe(
     "Write/refresh screenshot baselines for `snapshot` steps instead of diffing against them."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.25.1-next.20",
+  "version": "0.25.1-next.22",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",