mobile-automator 0.28.2 → 0.30.0

package/README.md

@@ -8,6 +8,7 @@ Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents all have one-
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20CMP-green.svg)](#)
+[![Host](https://img.shields.io/badge/Host-macOS%20%7C%20Linux-lightgrey.svg)](#)
 [![Node](https://img.shields.io/badge/Node-%E2%89%A522.12-brightgreen.svg)](#)
 
 ---
@@ -24,6 +25,8 @@ Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents all have one-
 npm i -g mobile-automator      # exposes `mauto` globally
 ```
 
+> **Supported hosts:** macOS and Linux. Windows is not supported natively (npm refuses the install) — run `mauto` inside WSL2. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#-mauto-refuses-to-run-on-windows).
+
 <details>
 <summary>Or run it without installing / build from source</summary>
 
@@ -140,7 +143,7 @@ Most low-level verbs are called **by the agent**, not by you. The ones you'll ru
 | `mauto memory show [--kind <k>] [--scenario <id>]` | Print cross-session memory (run history auto-harvested from results) as raw markdown for the agent to read at run start |
 | `mauto memory add <text> --kind <app-knowledge\|preferences>` | Record a durable agent-learned app fact or user preference (`[asserted]`, de-duped) |
 | `mauto memory forget --kind <k> --match <substr>` | Remove agent-authored memory entries matching a substring (the correction path) |
-| `mauto validate <file>` | Validate a scenario JSON against the schema |
+| `mauto validate <file> [--strict]` | Validate a scenario JSON against the schema; warns on actions that cannot replay (`--strict` fails) |
 | `mauto config get\|set <key> [value]` | Read / update workspace config |
 | **Agent-driven verbs** | `elements`, `tap`, `type`, `swipe`, `press`, `screenshot`, `assert`, `result`, `schema` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.28.2",
+  "version": "0.30.0",
   "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
   "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
   "repository": {
@@ -45,5 +45,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
-  }
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
 }

package/src/cli.js

@@ -11,6 +11,7 @@ const { DeviceBridge } = require('./device/bridge');
 const selectionStore = require('./device/selection');
 const { engineHint } = require('./device/engine-hints');
 const { ScenarioValidator } = require('./scenario/validator');
+const { findUnsupportedActions } = require('./scenario/replayability');
 const { evaluate, MECHANICAL_TYPES } = require('./assertion/evaluator');
 const { ResultStore } = require('./result/store');
 const { OBSERVATION_TYPES, parseObservation, parseCapture, parseBool } = require('./result/flags');
@@ -25,6 +26,7 @@ const guideEmitter = require('./guide/emitter');
 const { ADAPTERS } = require('./init/adapters');
 const { isSemanticAction, ACTION_METHOD, selectResolver } = require('./device/semantic-press');
 const connection = require('./device/connection');
+const { isSupportedHost, unsupportedHostError } = require('./device/host-support');
 const { record } = require('./observe/recorder');
 const { resolveRunId } = require('./observe/settings');
 const { runTracePath } = require('./observe/paths');
@@ -210,7 +212,7 @@ async function handleScreenshot({ deviceBridge, cwd = process.cwd() }, destPath)
   }
 }
 
-function handleValidate({ validator }, file) {
+function handleValidate({ validator }, file, opts = {}) {
   let raw;
   try {
     raw = fs.readFileSync(file, 'utf8');
@@ -241,7 +243,20 @@ function handleValidate({ validator }, file) {
 
   const result = validator.validate(scenario);
   if (result.valid) {
-    return { envelope: ok({ valid: true }), exitKind: 'ok' };
+    // Schema-valid is not the same as replayable: surface actions the catalog
+    // marks unsupported. A warning by default so existing scenarios keep
+    // validating; `--strict` makes it a failure (#166).
+    const warnings = findUnsupportedActions(scenario);
+    if (warnings.length === 0) {
+      return { envelope: ok({ valid: true }), exitKind: 'ok' };
+    }
+    const hint = `${warnings.length} action(s) cannot replay unattended — see data.warnings`;
+    if (opts.strict) {
+      const env = fail('invalid_input', 'scenario uses actions with no execution path', hint);
+      env.data = { valid: false, errors: [], warnings };
+      return { envelope: env, exitKind: 'invalid_input' };
+    }
+    return { envelope: ok({ valid: true, warnings }, hint), exitKind: 'ok' };
   }
 
   const env = fail(
@@ -253,6 +268,19 @@ function handleValidate({ validator }, file) {
   return { envelope: env, exitKind: 'invalid_input' };
 }
 
+// The unsupported-host gate (#165), shared by every site that reaches the
+// session layer: connectBridge (all device verbs) and the `session` verbs,
+// which talk to connection.* directly. Null on a supported host; otherwise an
+// `environment` failure (exit 5). Deliberately NOT routed through deviceFail —
+// a `device` kind is exactly the misdiagnosis this exists to prevent: on
+// Windows the session layer's Unix socket, `ps` and process-group kill fail in
+// ways that read as "no device connected".
+function hostGate(platform) {
+  if (isSupportedHost(platform)) return null;
+  const err = unsupportedHostError(platform);
+  return { envelope: fail(err.kind, err.message, err.hint), exitKind: err.kind };
+}
+
 function deviceFail(err) {
   // Respect a typed error's kind (e.g. the daemon's 'timeout') so the envelope
   // and exit code reflect the real failure class; anything else defaults to
@@ -1562,6 +1590,8 @@ function buildProgram(deps = {}) {
     emitters = makeEmitters({ projectRoot }),
     // Sink used to emit the rendered envelope + drive the exit code.
     emit = emitters.emit,
+    // Host OS, for the unsupported-host gate (#165). Overridable in tests.
+    platform = process.platform,
   } = deps;
 
   const program = new Command();
@@ -1658,6 +1688,18 @@ function buildProgram(deps = {}) {
     return action(...args);
   };
 
+  // Gate for verbs that reach the device session layer (#165). Runs before
+  // anything is spawned or connected; see hostGate. Emits and returns true when
+  // the host is unsupported, so a caller can bail out.
+  const refuseUnsupportedHost = () => {
+    const refusal = hostGate(platform);
+    if (!refusal) return false;
+    emit(refusal, humanFlag());
+    return true;
+  };
+  const requireSupportedHost = (action) => (...args) =>
+    (refuseUnsupportedHost() ? undefined : action(...args));
+
   // Resolve which device a verb targets: explicit --device wins, else the
   // persisted selection, else null (mobile-mcp auto-selects a single device).
   // Keeping the no-selection fast path returning null preserves zero-config use.
@@ -1673,6 +1715,9 @@ function buildProgram(deps = {}) {
   // (the single connection seam), so this keeps both the envelope boundary and
   // the acquire-seam refactor.
   const connectBridge = async (device, fn) => {
+    // Before the factory: on an unsupported host there is nothing to connect,
+    // and a connect failure would land below as a misleading `device` kind.
+    if (refuseUnsupportedHost()) return;
     let bridge;
     let close;
     try {
@@ -1754,8 +1799,9 @@ function buildProgram(deps = {}) {
   program
     .command('validate <file>')
     .description('Validate a scenario JSON file against the scenario schema')
-    .action(withEnvelope((file) => {
-      const r = handleValidate({ validator }, file);
+    .option('--strict', 'fail (instead of warn) when the scenario uses actions that cannot replay unattended')
+    .action(withEnvelope((file, opts) => {
+      const r = handleValidate({ validator }, file, { strict: Boolean(opts && opts.strict) });
       emit(r, humanFlag());
     }));
 
@@ -2091,26 +2137,26 @@ function buildProgram(deps = {}) {
     .description('Start the device session daemon (subsequent verbs reuse its connection)')
     .option('--device <id>', 'pin the daemon to a target device id')
     .option('--idle <ms>', 'idle timeout in milliseconds before the daemon self-reaps')
-    .action(withEnvelope(requireWorkspace(async (opts) => {
+    .action(withEnvelope(requireSupportedHost(requireWorkspace(async (opts) => {
       const r = await handleSessionStart({ projectRoot }, { device: opts.device, idle: opts.idle });
       emit(r, humanFlag());
-    })));
+    }))));
 
   session
     .command('status')
     .description('Report whether a device session daemon is running')
-    .action(withEnvelope(async () => {
+    .action(withEnvelope(requireSupportedHost(async () => {
       const r = await handleSessionStatus({ projectRoot });
       emit(r, humanFlag());
-    }));
+    })));
 
   session
     .command('end')
     .description('Stop the device session daemon and remove its socket/pidfile')
-    .action(withEnvelope(async () => {
+    .action(withEnvelope(requireSupportedHost(async () => {
       const r = await handleSessionEnd({ projectRoot });
       emit(r, humanFlag());
-    }));
+    })));
 
   // --- Issue #92: device discovery + persisted selection -------------------
 
@@ -2135,6 +2181,12 @@ function buildProgram(deps = {}) {
   devices
     .command('clear')
     .description('Remove the persisted device selection')
+    // Deliberately OUTSIDE the host gate (#165): its only session-layer probe,
+    // sessionClient.isAlive, is a socket ping — it never runs `ps` or signals a
+    // process, so it answers safely on an unsupported host too. That invariant
+    // is executable, not just prose: the canary in
+    // tests/unit/cli-host-support.test.js ("devices clear stays process-free")
+    // fails if this verb ever starts spawning child processes.
     .action(withEnvelope(async () => {
       const r = await handleDevicesClear({ projectRoot });
       emit(r, humanFlag());

package/src/device/host-support.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Which hosts can run the device session, and the error for the ones that
+// cannot (#165). The session daemon binds a Unix domain socket, and the
+// session layer identifies and reaps its daemon with `ps`, process-group kill
+// (`kill(-pid)`) and POSIX signals. None of that exists on Windows, where it
+// used to fail as a confusing `device` error — as if no phone were connected —
+// rather than saying the host itself is unsupported.
+//
+// package.json `os` is the single source of truth: npm refuses the install on
+// any other host, and this guard catches what slips past it (`--force`,
+// `npm link`, a vendored copy). Pure — no I/O; the caller decides how to emit.
+
+const pkg = require('../../package.json');
+
+const SUPPORTED_HOSTS = Object.freeze([...(pkg.os || [])]);
+
+// Human names for the error text — the ONE copy; the docs-agreement lint test
+// (tests/lint/host-support-agreement.test.js) consumes it rather than
+// restating it. Deliberately no fallback: a host added to package.json `os`
+// without a name here is a test failure and a crash at render time, not a raw
+// platform id leaking into the user-facing error.
+const HOST_NAMES = Object.freeze({ darwin: 'macOS', linux: 'Linux' });
+
+const TROUBLESHOOTING_REF = 'see TROUBLESHOOTING.md ("mauto refuses to run on Windows")';
+
+// Per-host guidance. Unknown hosts get the generic pointer instead of a
+// Windows-specific instruction — a freebsd user must not be told about WSL2.
+const HOST_HINTS = Object.freeze({
+  win32: `On Windows, install and run mauto inside WSL2 (a Linux distribution); ${TROUBLESHOOTING_REF}.`,
+});
+
+// For hosts with no specific hint: point at the troubleshooting entry without
+// naming an OS-specific route.
+const GENERIC_HINT = `See TROUBLESHOOTING.md for where mauto runs and how to get there.`;
+
+function isSupportedHost(platform = process.platform) {
+  return SUPPORTED_HOSTS.includes(platform);
+}
+
+function unsupportedHostError(platform = process.platform) {
+  const names = SUPPORTED_HOSTS.map((p) => HOST_NAMES[p]).join(' or ');
+  const err = new Error(
+    `mauto's device session needs a POSIX host (${names}); "${platform}" is not supported`
+  );
+  err.kind = 'environment';
+  err.hint = HOST_HINTS[platform] || GENERIC_HINT;
+  return err;
+}
+
+module.exports = { SUPPORTED_HOSTS, HOST_NAMES, isSupportedHost, unsupportedHostError };

package/src/guide/content/execute.agnostic.md

@@ -58,18 +58,19 @@ Record each observation with `mauto result add-step --observation <type>:<messag
 4. **App under test.**
    - If the user pointed you at a prebuilt app artifact, install it with `mauto install <path>`.
    - Otherwise verify the app is already installed; if it is not, halt and ask the user to install it. This guide never builds.
+   - **Fresh install.** If the scenario's `preconditions.app_state` is `fresh_install` and the user pointed you at a prebuilt app artifact, uninstall the app first with `mauto uninstall <appId>` (the app identifier from `mobile-automator/config.json` — `android_package` / `ios_bundle_id`) and only then install that artifact, so the run starts with no app data. Without an artifact, do not uninstall — you could not reinstall the app. Leave it in place and report that the app state was not reset, so a failure that depends on existing app data is not mistaken for a regression.
    - If the install fails because a different build is already on the device, uninstall it with `mauto uninstall <appId>` (the app identifier from `mobile-automator/config.json` — `android_package` / `ios_bundle_id`), install again, and report that app data was wiped — a scenario whose preconditions assume existing app state may now fail for that reason.
    - State which path you took before continuing.
 5. **Validate schema version:** read the `$schema_version` field; it must be `"2.1"`. If absent or unrecognized, report an error and halt.
-6. Validate the scenario with `mauto validate <path>` against `mauto schema scenario`.
+6. Validate the scenario with `mauto validate <path>` against `mauto schema scenario`. If the result lists `data.warnings`, each entry (its `path` names the step or precondition) uses an action that is unsupported on this run: report it as unsupported in the result (see "Not mechanically executable" under step execution) and do not substitute a gesture for it.
 
 **Precondition `device_actions`** (from the scenario's `preconditions`, run before step replay):
 
-| Device action | `mauto` verb |
-|---|---|
-| `install_app` | `mauto install <path>` |
-| `uninstall_app` | `mauto uninstall <appId>` |
-| `set_orientation` | `mauto orientation <portrait\|landscape>` |
+| Device action | `mauto` verb | Notes |
+|---|---|---|
+| `install_app` | `mauto install <path>` | `path` = the device action's `value` if set and the file exists, else the build artifact used in pre-flight. If neither is available, report this precondition as not executed |
+| `uninstall_app` | `mauto uninstall <appId>` | `appId` = the device action's `target_package` if set, else the app identifier from `mobile-automator/config.json` (`android_package` / `ios_bundle_id`) for the connected device's platform. If a later `install_app` in the same block has no resolvable path, skip this uninstall too and report both as not executed — never leave the device without the app under test |
+| `set_orientation` | `mauto orientation <portrait\|landscape>` | |
 
 The remaining precondition actions are not mechanically executable (see step execution): report them honestly or perform them out of band.
 

package/src/guide/content/execute.aware.md

@@ -56,18 +56,19 @@ Record each observation with `mauto result add-step --observation <type>:<messag
 - **App under test.** If the user pointed you at a prebuilt artifact, install it with `mauto install <path>` and do NOT build — reusing a ready artifact is the point.
 - If no artifact was named: check whether the app is already installed. If it is, say so and ask whether to rebuild before running the build command ({{build_command}}) — a previous run may have just built it. If it is not installed, build and install with the build command ({{build_command}}).
 - If that install fails because a different build of the app is already on the device, uninstall it — run `mauto uninstall` with the app package ({{app_package}}) — then install again, and report that app data was wiped — a scenario whose preconditions assume existing app state may now fail for that reason.
+- **Fresh install.** If the scenario's `preconditions.app_state` is `fresh_install` (read it from the scenario file now), uninstall the app first — `mauto uninstall` with the app package ({{app_package}}) — and only then install, so the run starts with no app data.
 - State which path you took — installed a supplied artifact, or built — before continuing.
 
 ### 2. Load Scenario
 
 - Read the JSON scenario file from `mobile-automator/scenarios/`.
 - **Validate schema version:** Read the `$schema_version` field. It must be `"2.1"`. If absent or unrecognized, report an error and halt.
-- Validate the scenario with `mauto validate <path>` against `mauto schema scenario`.
+- Validate the scenario with `mauto validate <path>` against `mauto schema scenario`. If the result lists `data.warnings`, each entry (its `path` names the step or precondition) uses an action that is unsupported on this run: report it as unsupported in the result, as described under "Not mechanically executable" below, and do not substitute a gesture for it.
 - Read the `metadata` to compare the recording environment against the current execution environment. Note any differences (different device, API level, environment).
 
 ### 3. Verify Preconditions
 
-- **Note:** preconditions like `app_uninstalled` and `fresh_install` are handled by the `execute` pre-flight before this workflow runs.
+- **Note:** an `app_state` of `fresh_install` is handled in pre-flight (uninstall before the install, see above), and precondition `device_actions` run per the table in step 4.
 - Review the scenario's `preconditions` array to understand the expected starting state.
 - If any preconditions are state-based (e.g., `"user_logged_out"`, `"no_network"`, `"dark_mode_enabled"`), verify or configure them now:
   - For app-state preconditions: launch the app and check/configure the state.
@@ -121,8 +122,8 @@ For each step in the scenario:
 
 | Device action | `mauto` verb | Notes |
 |---|---|---|
-| `install_app` | `mauto install <path>` | `path` = the build artifact to install |
-| `uninstall_app` | `mauto uninstall <appId>` | `appId` from config / scenario metadata |
+| `install_app` | `mauto install <path>` | `path` = the device action's `value` if set and the file exists, else the build artifact used in pre-flight. If neither is available, report this precondition as not executed |
+| `uninstall_app` | `mauto uninstall <appId>` | `appId` = the device action's `target_package` if set, else the app package ({{app_package}}). If a later `install_app` in the same block has no resolvable path, skip this uninstall too and report both as not executed — never leave the device without the app under test |
 | `set_orientation` | `mauto orientation <portrait\|landscape>` | `value` = target orientation |
 
 **Not mechanically executable** — these actions have no `mauto` verb and no underlying primitive. Do NOT improvise a gesture for them: report them honestly in the result (as unsupported on this run) and, if the run genuinely depends on them, perform them manually out of band before continuing.

package/src/guide/content/generate.agnostic.md

@@ -100,7 +100,7 @@ Translate user language to action types and `mauto` verbs:
 |---|---|---|---|
 | "open the app", "launch" | `launch_app` | `mauto press` / launch the app under test | |
 | "uninstall", "remove the app" | (precondition `device_action`) | uninstall before scenario | |
-| "clear app data", "fresh install" | `clear_app_data` | clear app data before scenario | Set `app_state: "fresh_install"` in preconditions |
+| "clear app data", "fresh install" | `uninstall_app` + `install_app` | reset app to a clean state before scenario | Set `app_state: "fresh_install"` in preconditions and add `device_actions`: `[{ "action": "uninstall_app" }, { "action": "install_app" }]`. Leave out `target_package` and `value`: a cross-platform scenario must not bake in one platform's app identifier or build path, and the executor fills both per platform from config and the pre-flight build |
 | "tap", "click", "press" | `tap` | `mauto tap --at <x,y>` | Resolve coords from `mauto elements` |
 | "long press", "hold" | `long_press` | `mauto tap --at <x,y>` (long-press variant) | Resolve coords from `mauto elements` |
 | "double tap", "double click" | `double_tap` | `mauto tap --at <x,y>` (double-tap variant) | Resolve coords from `mauto elements` |
@@ -202,7 +202,7 @@ After all steps are executed and recorded:
 2. Obtain the scenario schema by running `mauto schema scenario`, and assemble the JSON scenario to match it. Include the `tags` array.
 3. **Always include `"$schema_version": "2.1"` as the first field** in agnostic-mode scenarios.
 4. **Use named string IDs** for all steps and assertions (snake_case, e.g., `"id": "tap_login"`).
-5. Validate the assembled scenario with `mauto validate <path>` against `mauto schema scenario`.
+5. Validate the assembled scenario with `mauto validate <path>` against `mauto schema scenario`. If it returns `data.warnings`, revise the scenario to drop those steps, or tell the user the step needs manual handling.
 6. Save to `mobile-automator/scenarios/<scenario_id>.json`.
 7. Present summary:
    > "Scenario saved: `mobile-automator/scenarios/<scenario_id>.json`

package/src/guide/content/generate.aware.md

@@ -217,7 +217,7 @@ After all steps are executed and recorded:
    - `app_version` — from the installed app
    - `environment` — ask the user or use `default_environment` from `mobile-automator/config.json`
    - Do NOT include `device_model`, `api_level`, or `timestamp` in metadata — these belong in the result schema, not the scenario.
-7. Validate the assembled scenario with `mauto validate <path>` against `mauto schema scenario`.
+7. Validate the assembled scenario with `mauto validate <path>` against `mauto schema scenario`. If it returns `data.warnings`, revise the scenario to drop those steps, or tell the user the step needs manual handling.
 8. Save to `mobile-automator/scenarios/<scenario_id>.json`.
 9. Present summary:
    > "Scenario saved: `mobile-automator/scenarios/<scenario_id>.json`
@@ -232,7 +232,7 @@ Translate user language to `mauto` verbs and schema actions:
 |---|---|---|---|
 | "open the app", "launch" | `launch_app` | `mauto press` / launch the app under test | |
 | "uninstall", "remove the app" | (precondition device_action) | uninstall before scenario | Use `device_actions` in `preconditions` block |
-| "clear app data", "fresh install" | `clear_app_data` | clear app data before scenario | Also set `app_state: "fresh_install"` in preconditions |
+| "clear app data", "fresh install" | `uninstall_app` + `install_app` | reset app to a clean state before scenario | Set `app_state: "fresh_install"` in preconditions and add `device_actions`: `uninstall_app` then `install_app`. Both fields are optional: `target_package` defaults to the config app package ({{app_package}}) and `install_app` `value` defaults to the build installed in pre-flight; set them only to override those |
 | "tap", "click", "press" | `tap` | `mauto tap --at <x,y>` | Resolve `<x,y>` from `mauto elements` |
 | "long press", "hold" | `long_press` | `mauto tap --at <x,y>` (long-press variant) | Resolve coords from `mauto elements` |
 | "double tap", "double click" | `double_tap` | `mauto tap --at <x,y>` (double-tap variant) | Resolve coords from `mauto elements` |
@@ -268,7 +268,7 @@ Translate user language to `mauto` verbs and schema actions:
    - Create assertion step using mapped type from Pass 2b
    - Evaluate via `mauto assert <type> ...` and record with appropriate fields
 6. Combine steps and assertions into ordered scenario
-7. Generate scenario JSON, then `mauto validate <path>`
+7. Generate scenario JSON, then `mauto validate <path>` (if it returns `data.warnings`, revise the scenario to drop those steps, or tell the user the step needs manual handling)
 ```
 
 ### Detecting and Encoding Patterns

package/src/guide/content/generate.invariants.md

@@ -1,5 +1,5 @@
 - **You do NOT plan or suggest steps.** The user tells you exactly what to do; you execute, document, and verify — never add extra steps.
 - Capture a screenshot after every single step. No exceptions.
 - Drive the device **only** through `mauto` verbs; never assume resource-ids or OS-specific element IDs.
-- Assemble the scenario JSON to match `mauto schema scenario`: use named string IDs (snake_case, never integers), then validate with `mauto validate <path>` before finishing.
+- Assemble the scenario JSON to match `mauto schema scenario`: use named string IDs (snake_case, never integers), then validate with `mauto validate <path>` before finishing, and resolve any `data.warnings` it reports.
 - If this workspace has memory, read it first with `mauto memory show`; save durable app facts and user corrections with `mauto memory add`.

package/src/scenario/replayability.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// Replayability check for scenarios (#166). The scenario schema accepts every
+// action in its enum, but the action catalog marks some `unsupported`: mobile-mcp
+// exposes no primitive for them, so no `mauto` verb can run them and the step
+// can never replay unattended. Schema validity alone therefore overstates what
+// a scenario can do; this module reports the gap.
+//
+// The unsupported set is derived from the catalog, never restated here, so it
+// moves when an action gains (or loses) a device primitive.
+
+const { actionsByResolution } = require('../device/action-catalog');
+
+function finding(action, path, stepId) {
+  const f = {
+    code: 'unsupported_action',
+    action,
+    path,
+    message: `${action} has no execution path in mauto; this step cannot replay unattended`,
+  };
+  if (stepId !== undefined) f.step_id = stepId;
+  return f;
+}
+
+// Walks a step list depth-first in document order, descending into each
+// step's `sub_steps` (the schema types them as steps, so they nest freely).
+function scanSteps(steps, basePath, unsupported, findings) {
+  if (!Array.isArray(steps)) return;
+  steps.forEach((step, i) => {
+    if (!step) return;
+    const path = `${basePath}[${i}]`;
+    if (unsupported.has(step.action)) {
+      findings.push(finding(step.action, path, step.id));
+    }
+    scanSteps(step.sub_steps, `${path}.sub_steps`, unsupported, findings);
+  });
+}
+
+// Returns one finding per use of an unsupported action: steps first (including
+// nested sub_steps, depth-first in document order), then precondition device
+// actions in document order.
+function findUnsupportedActions(scenario) {
+  const unsupported = new Set(actionsByResolution('unsupported'));
+  const findings = [];
+
+  scanSteps(scenario && scenario.steps, 'steps', unsupported, findings);
+
+  const pre = scenario && scenario.preconditions;
+  const deviceActions = pre && Array.isArray(pre.device_actions) ? pre.device_actions : [];
+  deviceActions.forEach((da, i) => {
+    if (da && unsupported.has(da.action)) {
+      findings.push(finding(da.action, `preconditions.device_actions[${i}]`));
+    }
+  });
+
+  return findings;
+}
+
+module.exports = { findUnsupportedActions };

package/src/schemas/scenario_schema.json

@@ -140,15 +140,15 @@
                   "disable_wifi",
                   "set_orientation"
                 ],
-                "description": "The setup action to perform"
+                "description": "The setup action to perform. enable_wifi, disable_wifi and clear_app_data are accepted by the schema but are not mechanically executable (no device primitive), so they cannot replay unattended; mauto validate warns."
               },
               "target_package": {
                 "type": "string",
-                "description": "App package to target (for clear_app_data and uninstall_app)"
+                "description": "App package to target, for uninstall_app; defaults to the config app id"
               },
               "value": {
                 "type": "string",
-                "description": "Value parameter for the action (e.g., orientation value)"
+                "description": "Value parameter for the action: the orientation for set_orientation, or the build path for install_app (defaults to the pre-flight build)"
               },
               "description": {
                 "type": "string",
@@ -247,7 +247,7 @@
             "grant_permission",
             "deny_permission"
           ],
-          "description": "The automation action to perform. Supported types: wait_for_element, wait_for_element_gone, wait_for_loading_complete, capture_value, clear_app_data, long_press, double_tap, scroll_to_element, press_back, dismiss_keyboard, grant_permission, deny_permission."
+          "description": "The automation action to perform. Supported types: wait_for_element, wait_for_element_gone, wait_for_loading_complete, capture_value, long_press, double_tap, scroll_to_element, press_back, dismiss_keyboard, grant_permission, deny_permission. clear_app_data is accepted by the schema but is not mechanically executable: mobile-mcp exposes no primitive for it, so it cannot replay unattended (mauto validate warns)."
         },
         "description": {
           "type": "string",