mobile-automator 0.36.1 → 0.38.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +6 -6
  2. package/bin/mauto-session-daemon.js +1 -1
  3. package/package.json +2 -2
  4. package/src/cli.js +105 -27
  5. package/src/config/manager.js +6 -9
  6. package/src/device/action-catalog.js +2 -1
  7. package/src/device/connection.js +1 -1
  8. package/src/device/engine-hints.js +1 -1
  9. package/src/device/failure-probe.js +2 -0
  10. package/src/device/selection.js +2 -2
  11. package/src/device/session-daemon.js +1 -1
  12. package/src/device/session-handle.js +1 -1
  13. package/src/device/session-paths.js +3 -2
  14. package/src/device/session-salt.js +1 -1
  15. package/src/device/session-spawn.js +1 -1
  16. package/src/guide/content/execute.agnostic.md +9 -9
  17. package/src/guide/content/execute.aware.md +8 -8
  18. package/src/guide/content/generate.agnostic.md +6 -6
  19. package/src/guide/content/generate.aware.md +6 -6
  20. package/src/guide/content/setup.agnostic.md +1 -1
  21. package/src/guide/content/setup.aware.md +1 -1
  22. package/src/guide/emitter.js +1 -1
  23. package/src/init/skill-meta.js +1 -1
  24. package/src/mcp/prompts.js +1 -1
  25. package/src/memory/paths.js +3 -5
  26. package/src/observe/failure-capture.js +10 -8
  27. package/src/observe/paths.js +4 -12
  28. package/src/observe/sinks/file.js +4 -3
  29. package/src/observe/spool.js +3 -2
  30. package/src/output/envelope.js +10 -0
  31. package/src/result/flags.js +61 -1
  32. package/src/result/store.js +10 -11
  33. package/src/scenario/replayability.js +2 -2
  34. package/src/schemas/config_schema.json +1 -1
  35. package/src/schemas/result_schema.json +1 -1
  36. package/src/schemas/scenario_schema.json +3 -3
  37. package/src/setup/scaffold.js +3 -2
  38. package/src/util/log-rotate.js +2 -2
  39. package/src/workspace/discover.js +56 -9
  40. package/src/workspace/layout.js +26 -0
package/README.md CHANGED
@@ -46,10 +46,10 @@ npm install && npm link
46
46
  ```bash
47
47
  cd ~/projects/my-app
48
48
  mauto init --agent claude # or: cursor | gemini | copilot | agents | all
49
- mauto setup # scaffolds mobile-automator/ + config
49
+ mauto setup # scaffolds .mobile-automator/ + config
50
50
  ```
51
51
 
52
- `init` installs native Agent Skills into each host's skills directory and writes agent command files + MCP server entry (`.claude/commands/` + `.mcp.json` for Claude Code; `.cursor/` for Cursor). `setup` creates the `mobile-automator/` workspace. Add `--mode agnostic` to `setup` for cross-platform apps (Flutter/RN/KMP/CMP).
52
+ `init` installs native Agent Skills into each host's skills directory and writes agent command files + MCP server entry (`.claude/commands/` + `.mcp.json` for Claude Code; `.cursor/` for Cursor). `setup` creates the `.mobile-automator/` workspace. Add `--mode agnostic` to `setup` for cross-platform apps (Flutter/RN/KMP/CMP).
53
53
 
54
54
  **3. Check your device is visible:**
55
55
 
@@ -71,7 +71,7 @@ Open your agent in the project. In **Claude Code**, `init` installs slash comman
71
71
 
72
72
  In **Cursor**, `init` installs a project rule instead — just ask the agent in plain language (e.g. *"generate a login test"* / *"execute the login scenario"*) and it follows the same workflow. **Any other agent:** see [Using another agent](#-using-another-agent) below.
73
73
 
74
- That's it. Scenarios land in `mobile-automator/scenarios/`, results in `mobile-automator/results/`.
74
+ That's it. Scenarios land in `.mobile-automator/scenarios/`, results in `.mobile-automator/results/`.
75
75
 
76
76
  **Upgrading:** after `npm i -g mobile-automator@latest`, re-run `mauto init --agent <host>` in each project to refresh the skills, rules and commands it installed. Until you do, `mauto guide` starts with a notice that the host integration is out of date, and `mauto doctor` reports which hosts need refreshing.
77
77
 
@@ -108,7 +108,7 @@ Either way the workspace, scenarios, and schemas are identical — the agent is
108
108
 
109
109
  ## 🔀 Platform modes
110
110
 
111
- Chosen at `mauto setup` (stored in `mobile-automator/config.json`):
111
+ Chosen at `mauto setup` (stored in `.mobile-automator/config.json`):
112
112
 
113
113
  | Mode | Best for | Enable |
114
114
  |------|----------|--------|
@@ -140,7 +140,7 @@ Most low-level verbs are called **by the agent**, not by you. The ones you'll ru
140
140
  |---------|--------------|
141
141
  | `mauto init --agent <claude\|cursor\|gemini\|copilot\|agents\|all>` | Install native Agent Skills into each host's skills directory; also writes slash-commands/rules + MCP entry for claude/cursor |
142
142
  | `mauto doctor` | Report whether the integration `init` installed is missing or out of date, and the `init` command that refreshes it |
143
- | `mauto setup [--mode aware\|agnostic]` | Scaffold the `mobile-automator/` workspace + config |
143
+ | `mauto setup [--mode aware\|agnostic]` | Scaffold the `.mobile-automator/` workspace + config |
144
144
  | `mauto devices` · `devices use <id>` · `devices clear` | List / pin / unpin the target device |
145
145
  | `mauto guide <generate\|execute\|setup>` | Print the workflow guidance for a topic |
146
146
  | `mauto mcp` | Run the MCP prompts server (for any MCP-capable agent) |
@@ -161,7 +161,7 @@ Run `mauto <command> --help` for full flags.
161
161
  After `mauto setup`:
162
162
 
163
163
  ```
164
- mobile-automator/
164
+ .mobile-automator/
165
165
  ├── config.json # mode, environments, project config
166
166
  ├── scenarios/ # test scenarios (JSON, schema 2.1)
167
167
  ├── screenshots/ # reference screenshots
@@ -79,7 +79,7 @@ async function main() {
79
79
  // degrades rather than throwing.
80
80
  //
81
81
  // The stderr sink is deliberately left in place: the daemon's stderr IS
82
- // mobile-automator/.session/daemon.log (PR #176), not a terminal, which
82
+ // .mobile-automator/.session/daemon.log (PR #176), not a terminal, which
83
83
  // inverts cli.js finish()'s calculus — a warn line here costs a human no
84
84
  // terminal noise and lands next to the adb/simctl output that explains it.
85
85
  //
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mobile-automator",
3
- "version": "0.36.1",
3
+ "version": "0.38.1",
4
4
  "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
5
5
  "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
6
6
  "repository": {
@@ -34,7 +34,7 @@
34
34
  "test:all": "jest"
35
35
  },
36
36
  "dependencies": {
37
- "@mobilenext/mobile-mcp": "1.0.13",
37
+ "@mobilenext/mobile-mcp": "1.0.15",
38
38
  "@modelcontextprotocol/sdk": "^1.29.0",
39
39
  "ajv": "^8.20.0",
40
40
  "commander": "^12.1.0"
package/src/cli.js CHANGED
@@ -13,7 +13,7 @@ const { ScenarioValidator } = require('./scenario/validator');
13
13
  const { findReplayWarnings, summarize } = require('./scenario/replayability');
14
14
  const { evaluate, MECHANICAL_TYPES } = require('./assertion/evaluator');
15
15
  const { ResultStore } = require('./result/store');
16
- const { OBSERVATION_TYPES, parseObservation, parseCapture, parseBool } = require('./result/flags');
16
+ const { OBSERVATION_TYPES, parseObservation, parseCapture, parseBool, parseRunStatus, parseStepStatus } = require('./result/flags');
17
17
  const { MemoryStore } = require('./memory/store');
18
18
  const { FILES: MEMORY_FILES, AGENT_KINDS } = require('./memory/paths');
19
19
  const { validateEntryText, MAX_ENTRY_LEN } = require('./memory/entries');
@@ -41,7 +41,11 @@ const observeTelemetry = require('./observe/telemetry');
41
41
  const observeSpool = require('./observe/spool');
42
42
  const observeTransport = require('./observe/transport');
43
43
  const { makeFlusher } = require('./observe/flush');
44
- const { findWorkspaceRoot, noWorkspaceFailure } = require('./workspace/discover');
44
+ const {
45
+ findWorkspaceRoot,
46
+ workspaceFailure,
47
+ legacyWorkspaceFailure,
48
+ } = require('./workspace/discover');
45
49
 
46
50
  // Commander throws (via exitOverride) for two very different reasons, and the
47
51
  // split below is the ONLY thing that tells them apart.
@@ -562,8 +566,11 @@ async function handlePress({ deviceBridge }, button) {
562
566
  }
563
567
 
564
568
  // Build an assertion object from CLI flags, fetch the current element list,
565
- // and run the pure evaluator. A failed assertion is a valid RESULT (exit 0);
566
- // only an unknown assertion type is a structural (invalid_input) error.
569
+ // and run the pure evaluator. A decided failure is a test outcome, not a tool
570
+ // fault: it exits 6 (`test_failed`, #273) so CI sees red without parsing JSON,
571
+ // with the verdict still in `data`. A pass and an undecided Tier-2 verdict
572
+ // (`needs_agent`) stay ok / exit 0. Only an unknown assertion type is a
573
+ // structural (invalid_input) error.
567
574
  async function handleAssert({ deviceBridge }, type, flags = {}) {
568
575
  if (!KNOWN_ASSERTION_TYPES.has(type)) {
569
576
  return {
@@ -596,19 +603,24 @@ async function handleAssert({ deviceBridge }, type, flags = {}) {
596
603
  `Record it: mauto result add-assertion --run-id <run_id> --step-id <step_id> ` +
597
604
  `--type ${r.type} --pass ${verdict} --message "<why>"`;
598
605
 
599
- return {
600
- envelope: ok(
601
- {
602
- type: r.type,
603
- mechanical: r.mechanical,
604
- pass: r.pass,
605
- needs_agent: r.needs_agent,
606
- message: r.message,
607
- },
608
- hint
609
- ),
610
- exitKind: 'ok',
606
+ const verdictData = {
607
+ type: r.type,
608
+ mechanical: r.mechanical,
609
+ pass: r.pass,
610
+ needs_agent: r.needs_agent,
611
+ message: r.message,
611
612
  };
613
+
614
+ // Same data, same hint on both paths: an agent that reads `data` and copies
615
+ // the hint keeps working; only the exit code and `ok` change on a failure.
616
+ if (!r.needs_agent && r.pass === false) {
617
+ return {
618
+ envelope: fail('test_failed', `assertion failed: ${r.message}`, hint, verdictData),
619
+ exitKind: 'test_failed',
620
+ };
621
+ }
622
+
623
+ return { envelope: ok(verdictData, hint), exitKind: 'ok' };
612
624
  }
613
625
 
614
626
  // Collect a repeatable flag's values into an array (commander's collector).
@@ -623,6 +635,19 @@ function handleResultAddStep({ resultStoreFactory, projectRoot }, opts) {
623
635
  };
624
636
  }
625
637
 
638
+ // The status flag is a schema enum, not free text: an unknown value used to
639
+ // be silently recorded as 'error' — a mislabelled step with a green exit —
640
+ // because 'error' was the catch-all of the normalizer rather than an explicit
641
+ // acceptance (#286 review). Same all-or-nothing rule as the composite flags
642
+ // below: reject BEFORE the store is touched, so nothing is half-recorded.
643
+ const parsedStatus = parseStepStatus(status);
644
+ if (parsedStatus.error) {
645
+ return {
646
+ envelope: fail('invalid_input', parsedStatus.error, 'Valid values: pass | fail | skipped | error.'),
647
+ exitKind: 'invalid_input',
648
+ };
649
+ }
650
+
626
651
  // Parse every composite flag BEFORE touching the store: a half-recorded step
627
652
  // (screenshot persisted, observation rejected) leaves the agent unable to
628
653
  // tell which half landed, so validation is all-or-nothing.
@@ -653,7 +678,9 @@ function handleResultAddStep({ resultStoreFactory, projectRoot }, opts) {
653
678
  const store = resultStoreFactory({ runId, scenarioId, projectRoot });
654
679
  const step = store.addStep({
655
680
  step_id: stepId,
656
- status,
681
+ // The VALIDATED status: validated AND normalized at the boundary, so the
682
+ // store only ever records schema values.
683
+ status: parsedStatus.value,
657
684
  attempts: attempts === undefined ? 1 : Number(attempts),
658
685
  screenshot: screenshot === undefined ? null : screenshot,
659
686
  error_message: errorMessage === undefined ? null : errorMessage,
@@ -797,6 +824,26 @@ function handleResultFinalize({ resultStoreFactory, memoryStoreFactory, projectR
797
824
  };
798
825
  }
799
826
 
827
+ // The status flag is a schema enum, not free text: an unlisted value (a case
828
+ // variant of a documented word, a typo) used to be persisted verbatim — a
829
+ // schema-invalid result file with ok:true and exit 0 — directly under the
830
+ // exit-6 contract keyed on that status (#286 review). Reject before anything
831
+ // is written. A provided-but-empty value is NOT an omitted one: only absence
832
+ // derives the status from the recorded assertions.
833
+ if (status !== undefined) {
834
+ const parsed = parseRunStatus(status);
835
+ if (parsed.error) {
836
+ return {
837
+ envelope: fail(
838
+ 'invalid_input',
839
+ parsed.error,
840
+ 'Valid values: passed | failed | error, or omit --status to derive it from the recorded assertions.'
841
+ ),
842
+ exitKind: 'invalid_input',
843
+ };
844
+ }
845
+ }
846
+
800
847
  // Only provided keys: `defaultMetadata` fills the rest with 'unknown', and
801
848
  // the result schema requires all five fields to be strings, so threading
802
849
  // `undefined` through would break conformance.
@@ -850,6 +897,24 @@ function handleResultFinalize({ resultStoreFactory, memoryStoreFactory, projectR
850
897
  if (memHint) hints.push(memHint);
851
898
  }
852
899
 
900
+ // The exit code is keyed on the FINALIZED status, not the --status flag:
901
+ // with the flag omitted, the store derives 'failed' from a failed assertion,
902
+ // and the exit code must agree with the file either way (#273). 'error' takes
903
+ // the same path — a run that errored is not a pass for CI either; data.status
904
+ // tells the two apart. Everything above (write, retention, harvest) has
905
+ // already run: exit 6 is a verdict about the app, not a reason to lose the
906
+ // record of it.
907
+ if (result.status === 'failed' || result.status === 'error') {
908
+ const hint = hints.length
909
+ ? hints.join(' ')
910
+ : 'See data.steps_executed and data.assertion_results for what failed; ' +
911
+ `the result is saved to ${path.relative(projectRoot, store.file)}.`;
912
+ return {
913
+ envelope: fail('test_failed', `run ${runId} ${result.status}`, hint, result),
914
+ exitKind: 'test_failed',
915
+ };
916
+ }
917
+
853
918
  return { envelope: ok(result, hints.length ? hints.join(' ') : null), exitKind: 'ok' };
854
919
  }
855
920
 
@@ -873,7 +938,13 @@ function storeHint(store) {
873
938
  // still scaffolds in cwd — it is the one verb whose job is to create a
874
939
  // workspace where the user stands — but a nested workspace silently shadows
875
940
  // the ancestor for every later verb run below it, so say so.
876
- function handleSetup({ projectRoot, ancestorRoot = null }, opts = {}) {
941
+ //
942
+ // `legacyRoot` is the pre-rename workspace discovery found at or above cwd, if
943
+ // any (and no new workspace beside or above it). Discovery owns that walk, so
944
+ // setup honours the same answer every other verb does: checking only cwd let
945
+ // `mauto setup` from a subdirectory scaffold a nested workspace under a legacy
946
+ // project, the split state this refusal exists to prevent.
947
+ function handleSetup({ projectRoot, ancestorRoot = null, legacyRoot = null }, opts = {}) {
877
948
  const raw = opts.mode === undefined ? 'aware' : String(opts.mode);
878
949
  const mode = MODE_ALIASES[raw];
879
950
  if (!mode) {
@@ -882,6 +953,10 @@ function handleSetup({ projectRoot, ancestorRoot = null }, opts = {}) {
882
953
  exitKind: 'invalid_input',
883
954
  };
884
955
  }
956
+ // Scaffolding beside an un-migrated legacy workspace would fork the user's
957
+ // state into two directories. Discovery reports no legacy root once a new
958
+ // workspace exists, so a user mid-recovery gets through.
959
+ if (legacyRoot) return legacyWorkspaceFailure(legacyRoot);
885
960
  const r = scaffold(projectRoot, { mode });
886
961
  const hint = ancestorRoot
887
962
  ? `An existing workspace was found in an ancestor directory (${ancestorRoot}). This new workspace in ${projectRoot} shadows it for every mauto verb run from here or below; remove it if you meant to use the ancestor's.`
@@ -1725,8 +1800,8 @@ function buildProgram(deps = {}) {
1725
1800
  workspace = deps.projectRoot !== undefined
1726
1801
  ? { root: deps.projectRoot, searched: [deps.projectRoot] }
1727
1802
  : findWorkspaceRoot(cwd),
1728
- // Project root used to resolve mobile-automator/results/ — and, through the
1729
- // emitters below, mobile-automator/.logs/. One root, one tree. The
1803
+ // Project root used to resolve .mobile-automator/results/ — and, through the
1804
+ // emitters below, .mobile-automator/.logs/. One root, one tree. The
1730
1805
  // discovered workspace when there is one; cwd otherwise, which is what the
1731
1806
  // tolerant verbs (guide, mcp, read-only device/session) have always used.
1732
1807
  projectRoot = workspace.root || cwd,
@@ -1827,7 +1902,7 @@ function buildProgram(deps = {}) {
1827
1902
  // (exit 5) naming where we looked, so the agent can recover.
1828
1903
  const requireWorkspace = (action) => (...args) => {
1829
1904
  if (!workspace.root) {
1830
- emit(noWorkspaceFailure(workspace.searched), humanFlag());
1905
+ emit(workspaceFailure(workspace), humanFlag());
1831
1906
  return undefined;
1832
1907
  }
1833
1908
  return action(...args);
@@ -1867,7 +1942,7 @@ function buildProgram(deps = {}) {
1867
1942
  let close;
1868
1943
  try {
1869
1944
  // autostart: the daemon is a per-workspace artifact — its .session/ tree
1870
- // and logs live under mobile-automator/. With no discovered workspace
1945
+ // and logs live under .mobile-automator/. With no discovered workspace
1871
1946
  // there is nowhere legitimate to put one, so never autostart: the verb
1872
1947
  // connects one-shot and creates nothing. `ok:true` plus a phantom
1873
1948
  // workspace is the exact #188 pathology.
@@ -2198,13 +2273,16 @@ function buildProgram(deps = {}) {
2198
2273
 
2199
2274
  program
2200
2275
  .command('setup')
2201
- .description('Scaffold the workspace (mobile-automator/) and write a config')
2276
+ .description('Scaffold the workspace (.mobile-automator/) and write a config')
2202
2277
  .option('--mode <mode>', 'aware (platform-aware, default) | agnostic (platform-agnostic)')
2203
2278
  .action(withEnvelope((opts) => {
2204
2279
  // cwd, not the discovered root: setup creates a workspace where the user
2205
2280
  // stands. A discovered root that is not cwd is an ancestor worth naming.
2206
2281
  const ancestorRoot = workspace.root && workspace.root !== cwd ? workspace.root : null;
2207
- const r = handleSetup({ projectRoot: cwd, ancestorRoot }, { mode: opts.mode });
2282
+ const r = handleSetup(
2283
+ { projectRoot: cwd, ancestorRoot, legacyRoot: workspace.legacy || null },
2284
+ { mode: opts.mode }
2285
+ );
2208
2286
  emit(r, humanFlag());
2209
2287
  }));
2210
2288
 
@@ -2388,12 +2466,12 @@ function buildProgram(deps = {}) {
2388
2466
  .description('Inspect and control anonymous usage telemetry (off by default)');
2389
2467
 
2390
2468
  // requireWorkspace, same as config get/set: telemetry status/enable/disable
2391
- // all read or write mobile-automator/config.json, and flush reads/claims
2392
- // mobile-automator/.logs/telemetry.spool, so all four have #188's exact
2469
+ // all read or write .mobile-automator/config.json, and flush reads/claims
2470
+ // .mobile-automator/.logs/telemetry.spool, so all four have #188's exact
2393
2471
  // failure mode without the gate — status would report the SAME
2394
2472
  // not_configured/no_token answer for "no workspace here" as for "a real,
2395
2473
  // just-unconfigured workspace", and enable/disable would create a stray
2396
- // mobile-automator/ wherever the caller happened to be standing.
2474
+ // .mobile-automator/ wherever the caller happened to be standing.
2397
2475
  telemetryCmd
2398
2476
  .command('status')
2399
2477
  .description('Report whether telemetry is on, what would be sent, and what is queued')
@@ -2,19 +2,16 @@
2
2
 
3
3
  // Workspace config manager for the `mauto` CLI.
4
4
  //
5
- // Reads/writes mobile-automator/config.json under a project root.
5
+ // Reads/writes .mobile-automator/config.json under a project root.
6
6
  // A config without an explicit `mode` is treated as `platform-aware`.
7
7
 
8
8
  const fs = require('fs');
9
9
  const path = require('path');
10
10
  const { normalizeConfig } = require('./coerce');
11
-
12
- function configDir(projectRoot) {
13
- return path.join(projectRoot, 'mobile-automator');
14
- }
11
+ const { workspaceDir } = require('../workspace/layout');
15
12
 
16
13
  function configPath(projectRoot) {
17
- return path.join(configDir(projectRoot), 'config.json');
14
+ return path.join(workspaceDir(projectRoot), 'config.json');
18
15
  }
19
16
 
20
17
  // Parsed config object, or null when the file is absent. Values written before
@@ -40,11 +37,11 @@ function get(projectRoot, key) {
40
37
  }
41
38
 
42
39
  // Load-or-{}, set the dotted path, write back preserving every other field as
43
- // pretty 2-space JSON. Creates mobile-automator/ if needed.
40
+ // pretty 2-space JSON. Creates .mobile-automator/ if needed.
44
41
  function set(projectRoot, key, value) {
45
42
  const cfg = load(projectRoot) || {};
46
43
  setPath(cfg, key, value);
47
- fs.mkdirSync(configDir(projectRoot), { recursive: true });
44
+ fs.mkdirSync(workspaceDir(projectRoot), { recursive: true });
48
45
  fs.writeFileSync(configPath(projectRoot), JSON.stringify(cfg, null, 2) + '\n');
49
46
  return cfg;
50
47
  }
@@ -72,4 +69,4 @@ function setPath(obj, key, value) {
72
69
  cur[parts[parts.length - 1]] = value;
73
70
  }
74
71
 
75
- module.exports = { load, resolveMode, get, set, configPath, configDir };
72
+ module.exports = { load, resolveMode, get, set, configPath };
@@ -18,7 +18,8 @@
18
18
  // 'composed' — no dedicated verb; the agent composes it from existing verbs
19
19
  // (e.g. poll `mauto elements`, repeat `mauto swipe`). The
20
20
  // execute guide documents the composition.
21
- // 'unsupported' — mobile-mcp 1.0.5 exposes no primitive for it. Not
21
+ // 'unsupported' — no `mauto` verb reaches it: the engine has no primitive, or
22
+ // (clear_app_data, since 1.0.15) mauto has not wired it. Not
22
23
  // mechanically executable; the guide must NOT promise a verb,
23
24
  // and the agent reports it honestly / handles it manually.
24
25
  //
@@ -31,7 +31,7 @@ const sessionSpawn = require('./session-spawn');
31
31
  // `autostart` (default true: the daemon is the normal connection path) is the
32
32
  // daemon-vs-oneshot policy. cli.js's connectBridge passes false when no
33
33
  // workspace was discovered (#188), so a workspace-less cwd gets a one-shot
34
- // bridge and no mobile-automator/.session/ tree. `resolve` is an internal test
34
+ // bridge and no .mobile-automator/.session/ tree. `resolve` is an internal test
35
35
  // seam only; verbs call acquireConnection with just
36
36
  // { device, projectRoot, autostart }.
37
37
  async function acquireConnection({
@@ -74,7 +74,7 @@ function deviceNotFoundHint(id) {
74
74
  // directory". The engine runs from the project root (the daemon is spawned
75
75
  // there), which is not necessarily the directory the user ran the verb from.
76
76
  const OUTSIDE_ALLOWED_DIRS_HINT =
77
- 'Screenshots must be saved under the project root (the directory containing mobile-automator/) ' +
77
+ 'Screenshots must be saved under the project root (the directory containing .mobile-automator/) ' +
78
78
  'or the system temp directory. Choose a path inside one of them and retry.';
79
79
 
80
80
  function engineHint(message, { mobilecliVersion = resolveMobilecliVersion } = {}) {
@@ -86,6 +86,8 @@ const PROBE_EXEMPT_VERBS = new Set(['devices', 'crash']);
86
86
  // Failure kinds that can plausibly mean "the app died". invalid_input is a bad
87
87
  // flag, target_not_found/environment/internal never reached (or never
88
88
  // involved) the device — none of them are worth a device round trip.
89
+ // test_failed/incomplete are outcomes: the device answered and the app failed;
90
+ // the evidence is the step screenshot, not a crash list.
89
91
  const PROBE_KINDS = new Set(['device', 'timeout']);
90
92
 
91
93
  function shouldProbe({ envelope, verb } = {}) {
@@ -4,7 +4,7 @@
4
4
  //
5
5
  // A chosen device id is remembered across separate one-shot verb invocations so
6
6
  // the agent does not have to re-pass --device every call. The selection lives in
7
- // #91's session layout (mobile-automator/.session/) as a small sidecar file,
7
+ // #91's session layout (.mobile-automator/.session/) as a small sidecar file,
8
8
  // SEPARATE from config.json (which is user-authored project config) and from the
9
9
  // live session handle (session.json, owned by the daemon lifecycle).
10
10
  //
@@ -36,7 +36,7 @@ function read(projectRoot) {
36
36
  }
37
37
  }
38
38
 
39
- // Persist a device id. Creates mobile-automator/.session/ if needed. Written
39
+ // Persist a device id. Creates .mobile-automator/.session/ if needed. Written
40
40
  // via atomicWrite (tmp + fsync + rename) so a concurrent reader or a crash
41
41
  // sees the old-complete or new-complete selection, never a torn one.
42
42
  function write(projectRoot, id) {
@@ -332,7 +332,7 @@ async function startDaemon({
332
332
  : (info) =>
333
333
  // Was a bespoke process.stderr.write with its own try/catch. It is
334
334
  // the same destination — the stderr sink writes to fd 2, which since
335
- // #176 IS mobile-automator/.session/daemon.log — but now structured,
335
+ // #176 IS .mobile-automator/.session/daemon.log — but now structured,
336
336
  // and safeObserve (plus record()'s own never-throw guarantee)
337
337
  // subsumes the hand-rolled guard. That guard mattered: this runs
338
338
  // inside reply(), on the socket's async data handler, so a throw here
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- // Read side of mobile-automator/.session/session.json — the ONLY one. The
3
+ // Read side of .mobile-automator/.session/session.json — the ONLY one. The
4
4
  // session id it carries is minted, and its shape defined, in session-id.js.
5
5
  // resolve-connection.js's readHandleDevice() is a projection onto the `device`
6
6
  // field and delegates here; it used to parse the file itself, which meant two
@@ -2,7 +2,7 @@
2
2
 
3
3
  // Pure path helpers for the per-workspace device session daemon.
4
4
  //
5
- // Everything lives under <projectRoot>/mobile-automator/.session/:
5
+ // Everything lives under <projectRoot>/.mobile-automator/.session/:
6
6
  // mauto.sock — Unix domain socket the daemon listens on
7
7
  // daemon.pid — pidfile written once the daemon is listening
8
8
  // session.json — handle describing the live session (device pin, socket, pid)
@@ -19,6 +19,7 @@ const fs = require('fs');
19
19
  const path = require('path');
20
20
  const os = require('os');
21
21
  const crypto = require('crypto');
22
+ const { workspaceDir } = require('../workspace/layout');
22
23
 
23
24
  const SESSION_DIRNAME = '.session';
24
25
  const SOCKET_NAME = 'mauto.sock';
@@ -37,7 +38,7 @@ const SALT_NAME = 'marker.salt';
37
38
  const SOCKET_PATH_LIMIT = 100;
38
39
 
39
40
  function sessionDir(projectRoot) {
40
- return path.join(projectRoot, 'mobile-automator', SESSION_DIRNAME);
41
+ return path.join(workspaceDir(projectRoot), SESSION_DIRNAME);
41
42
  }
42
43
 
43
44
  // The canonical in-workspace socket path. Used when short enough.
@@ -5,7 +5,7 @@
5
5
  // `ps` shows every process's argv to every user on the host, so the daemon's
6
6
  // command line carries HMAC(salt, root) (session-paths.daemonMarkerKey) rather
7
7
  // than a digest anyone could recompute from a guessed project path. The salt is
8
- // 32 random bytes as hex in <root>/mobile-automator/.session/marker.salt, mode
8
+ // 32 random bytes as hex in <root>/.mobile-automator/.session/marker.salt, mode
9
9
  // 0600 so only the workspace's owner can read it. It is created once and never
10
10
  // rotated: rotating it would orphan a running daemon's marker, and no teardown
11
11
  // deletes it (cleanStale, daemon stop and the bin's exit cleanup all unlink
@@ -2,7 +2,7 @@
2
2
 
3
3
  // Spawns the device session daemon as a DETACHED background process and waits
4
4
  // until it is reachable. The daemon's output is captured to the workspace log
5
- // (mobile-automator/.session/daemon.log) instead of /dev/null, so a crashing
5
+ // (.mobile-automator/.session/daemon.log) instead of /dev/null, so a crashing
6
6
  // engine leaves a readable trace behind. The spawn and openLog fns are
7
7
  // injectable so the spawn args, the log wiring and the readiness-poll contract
8
8
  // are all unit-testable without launching a real daemon or touching disk.
@@ -58,8 +58,8 @@ Record each observation with `mauto result add-step --observation <type>:<messag
58
58
  4. **App under test.**
59
59
  - If the user pointed you at a prebuilt app artifact, install it with `mauto install <path>`.
60
60
  - Otherwise verify the app is already installed; if it is not, halt and ask the user to install it. This guide never builds.
61
- - **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.
62
- - 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.
61
+ - **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.
62
+ - 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.
63
63
  - State which path you took before continuing.
64
64
  5. **Validate schema version:** read the `$schema_version` field; it must be `"2.1"`. If absent or unrecognized, report an error and halt.
65
65
  6. Validate the scenario with `mauto validate <path>` against `mauto schema scenario`. If the result lists `data.warnings`, branch on each entry's `code` (its `path` names the step or precondition): `unsupported_action` means it 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. `launch_cold_implicit` is advisory: replay that step exactly as written (a step that does not set `"cold": false` is a cold start, per the step table below) and do not substitute your own reading of what the author meant; record the warning's `message` as a `state_context` observation on that step (`mauto result add-step ... --observation state_context:<message>`).
@@ -69,7 +69,7 @@ Record each observation with `mauto result add-step --observation <type>:<messag
69
69
  | Device action | `mauto` verb | Notes |
70
70
  |---|---|---|
71
71
  | `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 |
72
- | `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 |
72
+ | `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 |
73
73
  | `set_orientation` | `mauto orientation <portrait\|landscape>` | |
74
74
 
75
75
  The remaining precondition actions are not mechanically executable (see step execution): report them honestly or perform them out of band.
@@ -104,7 +104,7 @@ For each step in the scenario:
104
104
  - `launch_app` restarts the app so the step starts on its initial screen; `--resume` instead brings a running app to the front in its current state. A plain launch resets the screen, not app data: `app_state: "fresh_install"` is still the data reset. It returns `{launched, cold}`; an app that is not running is simply started. If the app cannot be stopped, the launch fails with a device error and a hint to use `--resume` — record the step as failed rather than retrying blindly.
105
105
  - Semantic actions → run `mauto press <action>` and let the CLI resolve them for the connected device.
106
106
  - Not mechanically executable → `clear_app_data` (and the precondition device actions `enable_wifi` / `disable_wifi`) have no verb and no underlying primitive. Do NOT substitute a gesture: report them honestly as unsupported on this run, or perform them manually out of band if the run depends on them.
107
- 4. **Capture screenshot:** Run `mauto screenshot mobile-automator/screenshots/<scenario_id>/<run_id>/step_<step_id>.png`.
107
+ 4. **Capture screenshot:** Run `mauto screenshot .mobile-automator/screenshots/<scenario_id>/<run_id>/step_<step_id>.png`.
108
108
  5. **Evaluate assertions** attached to the step (see section 4).
109
109
  6. **Record** the step result with `mauto result add-step --step-id <id> --status <s> --screenshot <path> [--attempts <n>] [--error-message <text>] [--observation <type>:<message>] [--capture <name>=<value>]`, then record each assertion verdict with `mauto result add-assertion --step-id <id> --type <t> --pass <true|false> --message <text> [--expected <v> --actual <v>]`. `--message` carries the justification you already formed — for Tier-2 verdicts it IS the evidence, so never omit it; add `--expected`/`--actual` whenever the assertion compares a specific value.
110
110
 
@@ -176,7 +176,7 @@ switch the engine mid-run yourself.
176
176
 
177
177
  For each assertion, pick the type recorded in the scenario and evaluate it. The 27 types split into two tiers by **who decides pass/fail**:
178
178
 
179
- - **Tier 1 — mechanical (the CLI decides).** Deterministic checks over the on-screen element list (plus captured variables / a previous snapshot). Run `mauto elements`, then evaluate with `mauto assert <type> ...`; the CLI returns a JSON verdict (`{ mechanical: true, pass: true|false, message }`). You record that verdict — you do not re-judge it.
179
+ - **Tier 1 — mechanical (the CLI decides).** Deterministic checks over the on-screen element list (plus captured variables / a previous snapshot). Run `mauto elements`, then evaluate with `mauto assert <type> ...`; the CLI returns a JSON verdict (`{ mechanical: true, pass: true|false, message }`). A passing verdict arrives as a normal `ok: true` envelope. A failing one arrives as `ok: false` with `error.kind: "test_failed"` and exit code `6`, and the verdict (`pass: false`) is still in `data`. That is the test result, not a tool error: do not retry the verb or treat the run as broken. You record that verdict — you do not re-judge it.
180
180
  - **Tier 2 — visual / semantic (the agent decides).** These require judging pixels. `mauto assert <type> ...` reports them as `needs_agent` (with `pass: null`). For these you take a screenshot with `mauto screenshot <path>`, visually analyze it, and report pass/fail yourself with a clear justification.
181
181
 
182
182
  > One assertion type, `element_state`, names a Tier-1 intent but its per-attribute state inspection is not represented in the element model the CLI reads, so `mauto assert` returns it as `needs_agent` — judge it from the element list / screenshot like a Tier-2 check.
@@ -210,7 +210,7 @@ For each: take a screenshot, visually analyze it, and report pass/fail with a cl
210
210
 
211
211
  ### 5. Generate the Result Report
212
212
 
213
- Obtain the result schema by running `mauto schema result`, then finalize the run with `mauto result finalize` (writing to `mobile-automator/results/<run_id>.json`), passing the run metadata you already know (`--device-model`, `--api-level`, `--app-version`, `--environment`) — the timestamp is filled in for you, and omitted fields are recorded as `unknown`. You may supply your own narrative with `--summary <text>`; omitting it keeps the generated default summary line. The finalized result assembles what the earlier `add-step`/`add-assertion` calls already recorded:
213
+ Obtain the result schema by running `mauto schema result`, then finalize the run with `mauto result finalize` (writing to `.mobile-automator/results/<run_id>.json`), passing the run metadata you already know (`--device-model`, `--api-level`, `--app-version`, `--environment`) — the timestamp is filled in for you, and omitted fields are recorded as `unknown`. You may supply your own narrative with `--summary <text>`; omitting it keeps the generated default summary line. A run that finalizes as `failed` or `error` returns `ok: false` with `error.kind: "test_failed"` and exit code `6`. The result file is still written and the full result is in `data`, so present it as usual; the non-zero exit is what lets CI see a red run. The finalized result assembles what the earlier `add-step`/`add-assertion` calls already recorded:
214
214
 
215
215
  - `run_id`, `scenario_id`, `status`, `duration_seconds`.
216
216
  - `steps_executed[]`: per-step status, retry_count, screenshot, error_message.
@@ -231,7 +231,7 @@ When neither attempt succeeds, fail the step and add a detailed observation desc
231
231
  ## Multi-Scenario Execution
232
232
 
233
233
  - Execute scenarios sequentially. Each scenario's leading `launch_app` restarts the app (`mauto launch <appId>`), so a scenario never inherits the previous one's screen and needs no separate reset; use `app_state: "fresh_install"` only when app data must be wiped too.
234
- - "run all smoke tests" → filter by the `smoke` tag. "run all" → every scenario in `mobile-automator/scenarios/`.
234
+ - "run all smoke tests" → filter by the `smoke` tag. "run all" → every scenario in `.mobile-automator/scenarios/`. List `.mobile-automator/scenarios/` directly: the workspace folder is hidden, and recursive search tools (glob or grep style) skip hidden directories, so they will report it empty.
235
235
  - Present a combined summary with a per-scenario breakdown.
236
236
 
237
237
  ## Operational Boundaries
@@ -257,8 +257,8 @@ When neither attempt succeeds, fail the step and add a detailed observation desc
257
257
 
258
258
  ## Resources
259
259
 
260
- - **mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
260
+ - **.mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
261
261
  - **`mauto schema scenario`**: JSON schema for test scenarios. Use it to validate scenarios with `mauto validate <path>`.
262
262
  - **`mauto schema result`**: JSON schema for execution results.
263
- - **mobile-automator/scenarios/**: Source scenario files.
263
+ - **.mobile-automator/scenarios/**: Source scenario files.
264
264
  {{additional_resources}}