mobile-automator 0.28.2 → 0.29.0

package/README.md

@@ -140,7 +140,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.29.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": {

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');
@@ -210,7 +211,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 +242,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(
@@ -1754,8 +1768,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());
     }));
 

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",