mobile-automator 0.36.0 → 0.37.0

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 (37) hide show
  1. package/README.md +6 -6
  2. package/bin/mauto-session-daemon.js +1 -1
  3. package/package.json +1 -1
  4. package/src/cli.js +36 -15
  5. package/src/config/manager.js +6 -9
  6. package/src/device/connection.js +1 -1
  7. package/src/device/engine-hints.js +1 -1
  8. package/src/device/process-identity.js +11 -5
  9. package/src/device/selection.js +2 -2
  10. package/src/device/session-daemon.js +1 -1
  11. package/src/device/session-end.js +43 -13
  12. package/src/device/session-handle.js +1 -1
  13. package/src/device/session-paths.js +17 -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 +8 -8
  17. package/src/guide/content/execute.aware.md +7 -7
  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 +7 -7
  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/result/store.js +3 -2
  31. package/src/schemas/config_schema.json +1 -1
  32. package/src/schemas/result_schema.json +1 -1
  33. package/src/schemas/scenario_schema.json +1 -1
  34. package/src/setup/scaffold.js +3 -2
  35. package/src/util/log-rotate.js +2 -2
  36. package/src/workspace/discover.js +56 -9
  37. 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.0",
3
+ "version": "0.37.0",
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": {
package/src/cli.js CHANGED
@@ -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.
@@ -873,7 +877,13 @@ function storeHint(store) {
873
877
  // still scaffolds in cwd — it is the one verb whose job is to create a
874
878
  // workspace where the user stands — but a nested workspace silently shadows
875
879
  // the ancestor for every later verb run below it, so say so.
876
- function handleSetup({ projectRoot, ancestorRoot = null }, opts = {}) {
880
+ //
881
+ // `legacyRoot` is the pre-rename workspace discovery found at or above cwd, if
882
+ // any (and no new workspace beside or above it). Discovery owns that walk, so
883
+ // setup honours the same answer every other verb does: checking only cwd let
884
+ // `mauto setup` from a subdirectory scaffold a nested workspace under a legacy
885
+ // project, the split state this refusal exists to prevent.
886
+ function handleSetup({ projectRoot, ancestorRoot = null, legacyRoot = null }, opts = {}) {
877
887
  const raw = opts.mode === undefined ? 'aware' : String(opts.mode);
878
888
  const mode = MODE_ALIASES[raw];
879
889
  if (!mode) {
@@ -882,6 +892,10 @@ function handleSetup({ projectRoot, ancestorRoot = null }, opts = {}) {
882
892
  exitKind: 'invalid_input',
883
893
  };
884
894
  }
895
+ // Scaffolding beside an un-migrated legacy workspace would fork the user's
896
+ // state into two directories. Discovery reports no legacy root once a new
897
+ // workspace exists, so a user mid-recovery gets through.
898
+ if (legacyRoot) return legacyWorkspaceFailure(legacyRoot);
885
899
  const r = scaffold(projectRoot, { mode });
886
900
  const hint = ancestorRoot
887
901
  ? `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.`
@@ -1411,14 +1425,18 @@ async function handleSessionStatus(
1411
1425
  }
1412
1426
 
1413
1427
  // endSession's failure outcomes (#156), each with the hint that is true for it.
1414
- // All three may leave a daemon alive and holding the workspace lock; what
1415
- // differs is WHY, and so what the user should do about it. One vague hint used
1416
- // to cover all three.
1428
+ // Every one of them may leave a daemon alive and holding the workspace lock;
1429
+ // what differs is WHY, and so what the user should do about it. One vague hint
1430
+ // used to cover them all.
1417
1431
  const SESSION_END_FAILURE_HINTS = {
1418
1432
  survived: (pid, pidFile) =>
1419
1433
  `It is still alive after SIGTERM and SIGKILL and may still hold the workspace lock. Check it with \`ps -p ${pid}\` and stop it with \`kill -9 ${pid}\` (pidfile: ${pidFile}).`,
1420
1434
  foreign: (pid, pidFile) =>
1421
- `It answered the shutdown, but its command line does not name this workspace (possibly started by mauto < 0.28), so it was not signalled. Check it with \`ps -p ${pid}\` and stop it manually (pidfile: ${pidFile}).`,
1435
+ `Something answered the shutdown, but this pid cannot be tied to this workspace, so it was not signalled: its command line names another workspace, or names none and the workspace lock does not name it. Check it with \`ps -p ${pid}\` and stop it manually (pidfile: ${pidFile}).`,
1436
+ // #237: a daemon started by mauto <= 0.27.x carries no workspace marker, and
1437
+ // without an ack nothing else proves it ours.
1438
+ unproven: (pid, pidFile) =>
1439
+ `It did not answer the shutdown and its command line carries no workspace marker (a daemon started by mauto < 0.28), so this workspace cannot prove it is its own and it was not signalled. It may still hold the workspace lock. Check it with \`ps -p ${pid}\` and stop it with \`kill -9 ${pid}\` if it is this workspace's daemon (pidfile: ${pidFile}).`,
1422
1440
  unverified: (pid, pidFile) =>
1423
1441
  `It could not be identified (\`ps\` failed), so it was not signalled. Check it with \`ps -p ${pid}\` and stop it manually if it is this workspace's mauto daemon (pidfile: ${pidFile}).`,
1424
1442
  };
@@ -1721,8 +1739,8 @@ function buildProgram(deps = {}) {
1721
1739
  workspace = deps.projectRoot !== undefined
1722
1740
  ? { root: deps.projectRoot, searched: [deps.projectRoot] }
1723
1741
  : findWorkspaceRoot(cwd),
1724
- // Project root used to resolve mobile-automator/results/ — and, through the
1725
- // emitters below, mobile-automator/.logs/. One root, one tree. The
1742
+ // Project root used to resolve .mobile-automator/results/ — and, through the
1743
+ // emitters below, .mobile-automator/.logs/. One root, one tree. The
1726
1744
  // discovered workspace when there is one; cwd otherwise, which is what the
1727
1745
  // tolerant verbs (guide, mcp, read-only device/session) have always used.
1728
1746
  projectRoot = workspace.root || cwd,
@@ -1823,7 +1841,7 @@ function buildProgram(deps = {}) {
1823
1841
  // (exit 5) naming where we looked, so the agent can recover.
1824
1842
  const requireWorkspace = (action) => (...args) => {
1825
1843
  if (!workspace.root) {
1826
- emit(noWorkspaceFailure(workspace.searched), humanFlag());
1844
+ emit(workspaceFailure(workspace), humanFlag());
1827
1845
  return undefined;
1828
1846
  }
1829
1847
  return action(...args);
@@ -1863,7 +1881,7 @@ function buildProgram(deps = {}) {
1863
1881
  let close;
1864
1882
  try {
1865
1883
  // autostart: the daemon is a per-workspace artifact — its .session/ tree
1866
- // and logs live under mobile-automator/. With no discovered workspace
1884
+ // and logs live under .mobile-automator/. With no discovered workspace
1867
1885
  // there is nowhere legitimate to put one, so never autostart: the verb
1868
1886
  // connects one-shot and creates nothing. `ok:true` plus a phantom
1869
1887
  // workspace is the exact #188 pathology.
@@ -2194,13 +2212,16 @@ function buildProgram(deps = {}) {
2194
2212
 
2195
2213
  program
2196
2214
  .command('setup')
2197
- .description('Scaffold the workspace (mobile-automator/) and write a config')
2215
+ .description('Scaffold the workspace (.mobile-automator/) and write a config')
2198
2216
  .option('--mode <mode>', 'aware (platform-aware, default) | agnostic (platform-agnostic)')
2199
2217
  .action(withEnvelope((opts) => {
2200
2218
  // cwd, not the discovered root: setup creates a workspace where the user
2201
2219
  // stands. A discovered root that is not cwd is an ancestor worth naming.
2202
2220
  const ancestorRoot = workspace.root && workspace.root !== cwd ? workspace.root : null;
2203
- const r = handleSetup({ projectRoot: cwd, ancestorRoot }, { mode: opts.mode });
2221
+ const r = handleSetup(
2222
+ { projectRoot: cwd, ancestorRoot, legacyRoot: workspace.legacy || null },
2223
+ { mode: opts.mode }
2224
+ );
2204
2225
  emit(r, humanFlag());
2205
2226
  }));
2206
2227
 
@@ -2384,12 +2405,12 @@ function buildProgram(deps = {}) {
2384
2405
  .description('Inspect and control anonymous usage telemetry (off by default)');
2385
2406
 
2386
2407
  // requireWorkspace, same as config get/set: telemetry status/enable/disable
2387
- // all read or write mobile-automator/config.json, and flush reads/claims
2388
- // mobile-automator/.logs/telemetry.spool, so all four have #188's exact
2408
+ // all read or write .mobile-automator/config.json, and flush reads/claims
2409
+ // .mobile-automator/.logs/telemetry.spool, so all four have #188's exact
2389
2410
  // failure mode without the gate — status would report the SAME
2390
2411
  // not_configured/no_token answer for "no workspace here" as for "a real,
2391
2412
  // just-unconfigured workspace", and enable/disable would create a stray
2392
- // mobile-automator/ wherever the caller happened to be standing.
2413
+ // .mobile-automator/ wherever the caller happened to be standing.
2393
2414
  telemetryCmd
2394
2415
  .command('status')
2395
2416
  .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 };
@@ -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 } = {}) {
@@ -66,10 +66,15 @@ function isZombie(
66
66
  // 'dead' - no such process (ESRCH or any non-EPERM kill error)
67
67
  // 'ours' - alive AND its command line contains `mauto-session-daemon`
68
68
  // (and, when `projectRoot` is given, names THAT workspace)
69
- // 'foreign' - only with `projectRoot`: alive and a mauto daemon, but its
70
- // command line does not name that workspace (#156) — another
71
- // workspace's daemon, one started before the workspace marker
72
- // existed, or an editor open on the bin. Never ours to signal.
69
+ // 'foreign' - only with `projectRoot`: alive and a mauto daemon whose
70
+ // command line carries a workspace marker naming ANOTHER
71
+ // workspace (#156) — or this one's under a salt we cannot read.
72
+ // Never ours to signal.
73
+ // 'unmarked'- only with `projectRoot`: alive and a mauto daemon whose command
74
+ // line carries no workspace marker at all (#237) — one started by
75
+ // mauto <= 0.27.x, or an editor open on the bin. Its line cannot
76
+ // prove whose it is either way; `session end` decides from the
77
+ // socket ack and the lock (src/device/session-end.js).
73
78
  // 'other' - alive AND its command line does NOT (recycled pid)
74
79
  // 'unknown' - alive but `ps` itself failed (e.g. no `ps` on the host) —
75
80
  // treated as 'ours' by cleanStale: never clean when unsure.
@@ -112,7 +117,8 @@ function pidIdentity(
112
117
  );
113
118
  if (!/mauto-session-daemon/.test(out)) return 'other';
114
119
  if (projectRoot == null) return 'ours';
115
- return paths.commandNamesWorkspace(out, projectRoot, readSalt(projectRoot)) ? 'ours' : 'foreign';
120
+ if (paths.commandNamesWorkspace(out, projectRoot, readSalt(projectRoot))) return 'ours';
121
+ return paths.commandHasWorkspaceMarker(out) ? 'foreign' : 'unmarked';
116
122
  } catch (_) {
117
123
  return 'unknown';
118
124
  }
@@ -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
@@ -31,11 +31,17 @@ const END_BUDGET_MS = sessionDaemon.DAEMON_CALL_TIMEOUT_MS + 10000;
31
31
  // 'already_stopped' - nothing acked and nothing of ours was running
32
32
  // 'forced' - ours, stuck in teardown, terminated by a group kill
33
33
  // 'survived' - ours, stuck, and still alive after SIGTERM + SIGKILL
34
- // 'foreign' - acked, but the live pid's command line does not name
35
- // this workspace, so it was reported, never signalled
34
+ // 'foreign' - acked, but the live pid cannot be tied to this
35
+ // workspace: its command line names another one, or it
36
+ // names none and the lock does not name the same pid —
37
+ // reported, never signalled
38
+ // 'unproven' - not acked, and the live pid is a mauto daemon whose
39
+ // command line names no workspace (mauto <= 0.27.x, #237):
40
+ // nothing proves it ours, so it was never signalled, and
41
+ // it may still hold this workspace's lock
36
42
  // 'unverified' - the pid could not be identified (`ps` failed), so it
37
43
  // was never signalled
38
- // The last three are failures: a daemon may still be alive.
44
+ // The last four are failures: a daemon may still be alive.
39
45
  async function endSession(
40
46
  projectRoot,
41
47
  {
@@ -45,12 +51,16 @@ async function endSession(
45
51
  // workspace's daemon through a copied or recycled pidfile.
46
52
  identify = (pid) => processIdentity.pidIdentity(pid, { projectRoot }),
47
53
  readPid = () => processIdentity.readPidFile(paths.pidFilePath(projectRoot)),
54
+ // The lock names the daemon that holds this workspace (#237). It is the
55
+ // second witness for a daemon whose command line carries no marker.
56
+ readLockPid = () => processIdentity.readPidFile(paths.lockPath(projectRoot)),
48
57
  budgetMs = END_BUDGET_MS,
49
58
  } = {}
50
59
  ) {
51
- // Read BEFORE asking: a daemon that exits cleanly removes its pidfile, and we
52
- // need to know whom to watch.
60
+ // Read BEFORE asking: a daemon that exits cleanly removes its pidfile and its
61
+ // lock, and we need to know whom to watch — and who held the lock.
53
62
  const pid = readPid();
63
+ const lockPid = readLockPid();
54
64
  const acked = await client.requestShutdown(projectRoot);
55
65
  const report = (outcome) => ({ outcome, pid: pid || null });
56
66
  // The daemon is gone: it stopped because we asked, or was never running.
@@ -69,13 +79,32 @@ async function endSession(
69
79
  case 'other': // the pid was recycled: our daemon is gone
70
80
  return gone();
71
81
  case 'foreign':
72
- // A mauto daemon whose command line does not name this workspace:
73
- // another workspace's, reached through a copied or recycled pidfile.
74
- // Never signalled. Without an ack nothing answered on OUR socket, so none
75
- // of ours was running. With an ack the daemon that answered is ours, but
76
- // its command line cannot prove it (one started before the workspace
77
- // marker), so it is reported rather than killed.
82
+ // A mauto daemon whose command line names ANOTHER workspace (or this
83
+ // one's under a salt we cannot read): reached through a copied or
84
+ // recycled pidfile. Never signalled. Without an ack nothing answered on
85
+ // OUR socket, so none of ours was running. With an ack something of ours
86
+ // answered, but this pid is provably not it, so it is reported rather
87
+ // than killed. (Marker-less daemons arrive as 'unmarked' below, #237.)
78
88
  return report(acked ? 'foreign' : 'already_stopped');
89
+ case 'unmarked':
90
+ // A mauto daemon whose command line names no workspace at all: one
91
+ // started by mauto <= 0.27.x (#237). Its line proves nothing, so two
92
+ // other witnesses must agree before it is signalled:
93
+ // - the ack: the socket lives inside this workspace's .session/ and a
94
+ // Unix socket only accepts on the inode the daemon bound, so a
95
+ // `cp -R`'d workspace can never make the original's daemon answer;
96
+ // - the lock naming this same pid, read before the ack, so the daemon
97
+ // that answered is the one we are about to kill.
98
+ // 0.27.x spawned it detached, so it leads its own process group and the
99
+ // group kill reaches its engine too.
100
+ if (acked && lockPid === pid) {
101
+ return report((await reaper.terminate(pid, { group: true })) === 'dead' ? 'forced' : 'survived');
102
+ }
103
+ // Acked, but the lock does not tie the answer to this pid: report it.
104
+ // Not acked: nothing proves it ours — but nor is it proven gone, and
105
+ // cleanStale (which asks without a root) still respects its lock, so
106
+ // 'already_stopped' would be a lie the next spawn trips over.
107
+ return report(acked ? 'foreign' : 'unproven');
79
108
  case 'ours':
80
109
  return report((await reaper.terminate(pid, { group: true })) === 'dead' ? 'forced' : 'survived');
81
110
  default: // 'unknown': never signal a process we cannot identify
@@ -84,8 +113,9 @@ async function endSession(
84
113
  }
85
114
 
86
115
  // Outcomes after which no daemon of ours is left holding the workspace.
87
- // Anything else ('survived', 'foreign', 'unverified') may leave the stale
88
- // daemon alive — spawning then would just find it answering pings. Lives beside
116
+ // Anything else ('survived', 'foreign', 'unproven', 'unverified') may leave
117
+ // the stale daemon alive — spawning then would just find it answering pings,
118
+ // or (for 'unproven') find its lock still held. Lives beside
89
119
  // the vocabulary it classifies so a new outcome can never drift from its
90
120
  // classification (#251's restart path, resolve-connection.js, reads it).
91
121
  const ENDED_OUTCOMES = new Set(['stopped', 'forced', 'already_stopped']);
@@ -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.
@@ -137,6 +138,19 @@ function commandNamesWorkspace(command, projectRoot, salt = null) {
137
138
  return line.endsWith(` ${LEGACY_DAEMON_ROOT_FLAG} ${path.resolve(projectRoot)}`);
138
139
  }
139
140
 
141
+ // Does a `ps -o command=` line carry a workspace marker of EITHER kind, whatever
142
+ // workspace it names (#237)? Daemons started by mauto <= 0.27.x carry none, and
143
+ // "names no workspace" is a different fact from "names another workspace": the
144
+ // first cannot be told apart by its command line at all, so `session end`
145
+ // falls back to the socket and the lock; the second is proof it is not ours.
146
+ // Matched as a whole argv token (whitespace or line edge on both sides), so a
147
+ // path that merely contains the flag's text is not a marker.
148
+ const MARKER_FLAG_TOKEN = new RegExp(`(?:^|\\s)(?:${DAEMON_WORKSPACE_FLAG}|${LEGACY_DAEMON_ROOT_FLAG})(?=\\s|$)`);
149
+
150
+ function commandHasWorkspaceMarker(command) {
151
+ return MARKER_FLAG_TOKEN.test(String(command || ''));
152
+ }
153
+
140
154
  // A path as it should appear in a child's argv (or an env var the child execs
141
155
  // by) (#236). `ps` shows every process's argv to every user on the host, and
142
156
  // when mobile-automator is installed inside the project (a devDependency, a
@@ -191,5 +205,6 @@ module.exports = {
191
205
  LEGACY_DAEMON_ROOT_FLAG,
192
206
  daemonArgv,
193
207
  commandNamesWorkspace,
208
+ commandHasWorkspaceMarker,
194
209
  argvPath,
195
210
  };
@@ -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
 
@@ -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. 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}}
@@ -61,7 +61,7 @@ Record each observation with `mauto result add-step --observation <type>:<messag
61
61
 
62
62
  ### 2. Load Scenario
63
63
 
64
- - Read the JSON scenario file from `mobile-automator/scenarios/`.
64
+ - Read the JSON scenario file from `.mobile-automator/scenarios/`.
65
65
  - **Validate schema version:** Read the `$schema_version` field. It must be `"2.1"`. If absent or unrecognized, report an error and halt.
66
66
  - 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, as described under "Not mechanically executable" below, 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>`).
67
67
  - Read the `metadata` to compare the recording environment against the current execution environment. Note any differences (different device, API level, environment).
@@ -95,7 +95,7 @@ For each step in the scenario:
95
95
  1. **Find the target:** Run `mauto elements` to locate the element described in `target`.
96
96
  - If `target_pattern` is set: use it as a regex to filter elements by their text content.
97
97
  2. **Execute the action** using the appropriate `mauto` verb (see the action mapping table below). Resolve coordinates for taps from the `mauto elements` output and pass them with `mauto tap --at <x,y>`.
98
- 3. **Capture screenshot:** Run `mauto screenshot mobile-automator/results/<run_id>/screenshots/step_<step_id>.png` (where `step_id` is the step's named string ID, e.g., `step_tap_login.png`).
98
+ 3. **Capture screenshot:** Run `mauto screenshot .mobile-automator/results/<run_id>/screenshots/step_<step_id>.png` (where `step_id` is the step's named string ID, e.g., `step_tap_login.png`).
99
99
  4. **Verify state:** Compare what you see against the step's `expected_state` description.
100
100
  5. **Record progress:** Append 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 comparing `expected_state` against what you observed — for Tier-2 verdicts it IS the evidence, so never omit it; add `--expected`/`--actual` whenever the assertion compares a specific value. Report:
101
101
  > "Step tap_login (4/12): Tapped 'Login' — login form displayed (passed)"
@@ -276,7 +276,7 @@ For all Tier 2 assertions: take a screenshot, visually analyze it, and report pa
276
276
 
277
277
  ### 6. Generate the Result Report
278
278
 
279
- 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 result carries typed `observations` (`regression`, `flakiness`, `state_context`) gathered by the Observer traits above. `--duration` is now a cross-check rather than the recorded value: when a run trace exists the duration is measured from it, your figure is kept as `measurements.reported_duration_seconds`, and a disagreement beyond the tolerance is recorded as a `state_context` observation. Report the duration you believe is right and let the two be compared; do not reverse-engineer a number to match.
279
+ 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 result carries typed `observations` (`regression`, `flakiness`, `state_context`) gathered by the Observer traits above. `--duration` is now a cross-check rather than the recorded value: when a run trace exists the duration is measured from it, your figure is kept as `measurements.reported_duration_seconds`, and a disagreement beyond the tolerance is recorded as a `state_context` observation. Report the duration you believe is right and let the two be compared; do not reverse-engineer a number to match.
280
280
 
281
281
  ### 7. Present the Summary
282
282
 
@@ -305,7 +305,7 @@ When asked to run multiple scenarios:
305
305
  - Execute them sequentially.
306
306
  - 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.
307
307
  - If the user says "run all smoke tests", filter scenarios by the `smoke` tag.
308
- - If the user says "run all", execute every scenario in `mobile-automator/scenarios/`.
308
+ - If the user says "run all", execute 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.
309
309
  - Present a combined summary at the end with a per-scenario breakdown.
310
310
 
311
311
  ## Operational Boundaries
@@ -330,9 +330,9 @@ When asked to run multiple scenarios:
330
330
 
331
331
  ## Resources
332
332
 
333
- - **mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
333
+ - **.mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
334
334
  - **`mauto schema scenario`**: JSON schema for test scenarios. Use it to validate scenarios with `mauto validate <path>`.
335
335
  - **`mauto schema result`**: JSON schema for execution results.
336
- - **mobile-automator/scenarios/**: Source scenario files.
337
- - **mobile-automator/screenshots/**: Reference screenshot baselines.
336
+ - **.mobile-automator/scenarios/**: Source scenario files.
337
+ - **.mobile-automator/screenshots/**: Reference screenshot baselines.
338
338
  {{additional_resources}}
@@ -54,7 +54,7 @@ While recording, you also **passively observe and report** (but never add extra
54
54
 
55
55
  - Verify a device is available with `mauto devices`.
56
56
  - **App under test.** If the user pointed you at a prebuilt app artifact, install it with `mauto install <path>`. Otherwise verify the app is installed on the device; if it is not, ask the user to install it manually before continuing. This guide never builds.
57
- - If that 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.
57
+ - If that 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.
58
58
  - State which path you took before continuing.
59
59
 
60
60
  ### 2. Receive Steps from User
@@ -86,7 +86,7 @@ For each step the user provided:
86
86
  1. **Find the target:** Run `mauto elements` to list the UI elements on screen and locate the target.
87
87
  2. **Execute the action:** Run the appropriate `mauto` verb. Resolve coordinates for taps from the `mauto elements` output and pass them with `mauto tap --at <x,y>`. For semantic actions (see Step Translation Guide), run `mauto press <action>` and let it resolve the action on the connected device.
88
88
  3. **Wait for stability:** Poll `mauto elements` until loading indicators ({{loading_indicators}}) have disappeared.
89
- 4. **Capture screenshot:** Run `mauto screenshot mobile-automator/screenshots/<scenario_id>/step_<step_id>.png`.
89
+ 4. **Capture screenshot:** Run `mauto screenshot .mobile-automator/screenshots/<scenario_id>/step_<step_id>.png`.
90
90
  5. **Report back:** Describe what you see on screen after the action.
91
91
  6. **Record the step** with: action type (semantic or standard), semantic target description, value used, and a rich `expected_state` description of the resulting screen.
92
92
 
@@ -204,11 +204,11 @@ After all steps are executed and recorded:
204
204
  3. **Always include `"$schema_version": "2.1"` as the first field** in agnostic-mode scenarios.
205
205
  4. **Use named string IDs** for all steps and assertions (snake_case, e.g., `"id": "tap_login"`).
206
206
  5. Validate the assembled scenario with `mauto validate <path>` against `mauto schema scenario`. If it returns `data.warnings`, revise the scenario to drop each `unsupported_action` step, or tell the user the step needs manual handling; for a `launch_cold_implicit` entry, set the step's `cold` explicitly (`false` when it means returning to the already-open app, `true` when it means a restart).
207
- 6. Save to `mobile-automator/scenarios/<scenario_id>.json`.
207
+ 6. Save to `.mobile-automator/scenarios/<scenario_id>.json`.
208
208
  7. Present summary:
209
- > "Scenario saved: `mobile-automator/scenarios/<scenario_id>.json`
209
+ > "Scenario saved: `.mobile-automator/scenarios/<scenario_id>.json`
210
210
  > - Steps: [N] | Checkpoints: [N] screenshots | Assertions: [N] | Tags: [tag1, tag2]
211
- > - Screenshots: `mobile-automator/screenshots/<scenario_id>/`"
211
+ > - Screenshots: `.mobile-automator/screenshots/<scenario_id>/`"
212
212
 
213
213
  ## Operational Boundaries
214
214
 
@@ -232,6 +232,6 @@ After all steps are executed and recorded:
232
232
 
233
233
  ## Resources
234
234
 
235
- - **mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
235
+ - **.mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
236
236
  - **`mauto schema scenario`**: JSON schema for test scenarios. Use this when generating new scenarios and validating them with `mauto validate <path>`.
237
237
  {{additional_resources}}
@@ -101,7 +101,7 @@ For each step the user provided:
101
101
  1. **Find the target:** Run `mauto elements` to list the UI elements on screen and locate the target.
102
102
  2. **Execute the action:** Run the appropriate `mauto` verb. Resolve coordinates for taps from the `mauto elements` output and pass them with `mauto tap --at <x,y>`.
103
103
  3. **Wait for stability:** Poll `mauto elements` until loading indicators ({{loading_indicators}}) have disappeared.
104
- 4. **Capture screenshot:** Run `mauto screenshot mobile-automator/screenshots/<scenario_id>/step_<step_id>.png` (where `step_id` is the step's named string ID, e.g., `step_tap_login.png`).
104
+ 4. **Capture screenshot:** Run `mauto screenshot .mobile-automator/screenshots/<scenario_id>/step_<step_id>.png` (where `step_id` is the step's named string ID, e.g., `step_tap_login.png`).
105
105
  5. **Report back:** Describe what you see on screen after the action.
106
106
  > "Step tap_login done: Tapped 'Login' — now showing the login form with email and password fields."
107
107
  6. **Record the step** with: action type, semantic target description, value used, and a rich `expected_state` description of the resulting screen.
@@ -215,14 +215,14 @@ After all steps are executed and recorded:
215
215
  5. **Assertions reference steps by name** (`"after_step": "tap_login"`) — never by number.
216
216
  6. Auto-populate metadata from the current session:
217
217
  - `app_version` — from the installed app
218
- - `environment` — ask the user or use `default_environment` from `mobile-automator/config.json`
218
+ - `environment` — ask the user or use `default_environment` from `.mobile-automator/config.json`
219
219
  - Do NOT include `device_model`, `api_level`, or `timestamp` in metadata — these belong in the result schema, not the scenario.
220
220
  7. Validate the assembled scenario with `mauto validate <path>` against `mauto schema scenario`. If it returns `data.warnings`, revise the scenario to drop each `unsupported_action` step, or tell the user the step needs manual handling; for a `launch_cold_implicit` entry, set the step's `cold` explicitly (`false` when it means returning to the already-open app, `true` when it means a restart).
221
- 8. Save to `mobile-automator/scenarios/<scenario_id>.json`.
221
+ 8. Save to `.mobile-automator/scenarios/<scenario_id>.json`.
222
222
  9. Present summary:
223
- > "Scenario saved: `mobile-automator/scenarios/<scenario_id>.json`
223
+ > "Scenario saved: `.mobile-automator/scenarios/<scenario_id>.json`
224
224
  > - Steps: [N] | Checkpoints: [N] screenshots | Assertions: [N] | Tags: [tag1, tag2]
225
- > - Screenshots: `mobile-automator/screenshots/<scenario_id>/`"
225
+ > - Screenshots: `.mobile-automator/screenshots/<scenario_id>/`"
226
226
 
227
227
  ## Step Translation Guide
228
228
 
@@ -323,6 +323,6 @@ Translate user language to `mauto` verbs and schema actions:
323
323
  - Ignore errors — report failures immediately and ask the user how to proceed.
324
324
 
325
325
  ## Resources
326
- - **mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
326
+ - **.mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
327
327
  - **`mauto schema scenario`**: JSON schema for test scenarios. Use this when generating new scenarios and validating them with `mauto validate <path>`.
328
328
  {{additional_resources}}
@@ -1,6 +1,6 @@
1
1
  # Guide: setup (platform-agnostic)
2
2
 
3
- You are configuring a mobile-QA workspace by **analyzing this project**. The mechanical part is already done: `mauto setup` has scaffolded the `mobile-automator/` tree (scenarios, screenshots, results) and written a starter `config.json`. **This guide completes the project analysis** — you inspect the codebase, infer each fact, confirm anything uncertain with the user, and PERSIST every finding with `mauto config set <key> <value>`. Read each value back with `mauto config get <key>` to confirm it landed.
3
+ You are configuring a mobile-QA workspace by **analyzing this project**. The mechanical part is already done: `mauto setup` has scaffolded the `.mobile-automator/` tree (scenarios, screenshots, results) and written a starter `config.json`. **This guide completes the project analysis** — you inspect the codebase, infer each fact, confirm anything uncertain with the user, and PERSIST every finding with `mauto config set <key> <value>`. Read each value back with `mauto config get <key>` to confirm it landed.
4
4
 
5
5
  In this mode the configuration is **portable**: facts are captured as plain-English, platform-neutral descriptions so a single config and the scenarios it drives run unchanged across both supported mobile platforms. You are doing LLM analysis work, not running a fixed script — read real project files, reason about what you find, and only ask the user when a value genuinely cannot be inferred.
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Guide: setup (platform-aware)
2
2
 
3
- You are configuring a mobile-QA workspace by **analyzing this project**. The mechanical part is already done: `mauto setup` has scaffolded the `mobile-automator/` tree (scenarios, screenshots, results) and written a starter `config.json`. **This guide completes the project analysis** — you inspect the codebase, infer each fact, confirm anything uncertain with the user, and PERSIST every finding with `mauto config set <key> <value>`. Read each value back with `mauto config get <key>` to confirm it landed.
3
+ You are configuring a mobile-QA workspace by **analyzing this project**. The mechanical part is already done: `mauto setup` has scaffolded the `.mobile-automator/` tree (scenarios, screenshots, results) and written a starter `config.json`. **This guide completes the project analysis** — you inspect the codebase, infer each fact, confirm anything uncertain with the user, and PERSIST every finding with `mauto config set <key> <value>`. Read each value back with `mauto config get <key>` to confirm it landed.
4
4
 
5
5
  You are doing LLM analysis work, not running a fixed script. Read real project files, reason about what you find, and only ask the user when a value genuinely cannot be inferred.
6
6
 
@@ -37,7 +37,7 @@ const TOPICS = {
37
37
  execute:
38
38
  'Run a scenario. The agent replays each step through `mauto` action verbs, evaluates checks with `mauto assert`, and records progress with `mauto result add-step` / `mauto result finalize`.',
39
39
  setup:
40
- 'Initialise the workspace. `mauto setup` scaffolds the mobile-automator tree and a config; `mauto config get/set` reads and updates it.',
40
+ 'Initialise the workspace. `mauto setup` scaffolds the .mobile-automator/ workspace and a config; `mauto config get/set` reads and updates it.',
41
41
  };
42
42
 
43
43
  const SEMANTIC_ACTIONS = ['press_back', 'dismiss_keyboard', 'grant_permission', 'deny_permission'];
@@ -22,7 +22,7 @@ const SKILL_META = {
22
22
  setup: {
23
23
  name: 'mobile-automator-setup',
24
24
  description:
25
- 'Initialise and configure a mobile-automator workspace by analysing the ' +
25
+ 'Initialise and configure a .mobile-automator/ workspace by analysing the ' +
26
26
  'project. Use when the user wants to set up, configure, or initialise ' +
27
27
  'mobile QA automation for this project.',
28
28
  },
@@ -20,7 +20,7 @@ const PROMPT_TOPICS = ['generate', 'execute', 'setup'];
20
20
  const DESCRIPTIONS = {
21
21
  generate: 'Author a mobile test scenario by exploring the app with mauto verbs.',
22
22
  execute: 'Replay a scenario step-by-step and record the run results.',
23
- setup: 'Initialise the mobile-automator workspace and config.',
23
+ setup: 'Initialise the .mobile-automator/ workspace and config.',
24
24
  };
25
25
 
26
26
  // Build the { listPrompts, getPrompt } pair. emitGuide + config are injectable
@@ -1,6 +1,8 @@
1
1
  'use strict';
2
2
 
3
3
  const path = require('path');
4
+ const { workspaceDir } = require('../workspace/layout');
5
+ const { sessionDir } = require('../device/session-paths');
4
6
 
5
7
  // Canonical on-disk names for the three memory files. Keys are the stable
6
8
  // `--kind` identifiers used across verbs; values are the markdown filenames.
@@ -27,17 +29,13 @@ const HEADERS = {
27
29
  };
28
30
 
29
31
  function memoryDir(projectRoot) {
30
- return path.join(projectRoot, 'mobile-automator', 'memory');
32
+ return path.join(workspaceDir(projectRoot), 'memory');
31
33
  }
32
34
 
33
35
  function memoryFile(projectRoot, name) {
34
36
  return path.join(memoryDir(projectRoot), FILES[name] || name);
35
37
  }
36
38
 
37
- function sessionDir(projectRoot) {
38
- return path.join(projectRoot, 'mobile-automator', '.session');
39
- }
40
-
41
39
  // The advisory lock guarding read-modify-write of the shared memory files.
42
40
  // Lives in .session/ (already gitignored) alongside the device-session state.
43
41
  function lockPath(projectRoot) {
@@ -20,15 +20,16 @@
20
20
  // to reference the file from and no finalize to collect it, so the PNG
21
21
  // would be litter in a directory the user did not ask us to fill — the
22
22
  // same argument the file sink already makes about creating
23
- // mobile-automator/. It also makes the run id the single switch for this
23
+ // .mobile-automator/. It also makes the run id the single switch for this
24
24
  // whole slice: export it and you get traces, measured durations and
25
25
  // failure evidence; leave it unset and 0.24.0's behaviour is unchanged.
26
26
 
27
27
  const realFs = require('fs');
28
28
  const path = require('path');
29
29
 
30
+ const { workspaceDir } = require('../workspace/layout');
30
31
  const { record } = require('./recorder');
31
- const { runTracePath, workspaceDir } = require('./paths');
32
+ const { runTracePath } = require('./paths');
32
33
 
33
34
  // The failure kinds worth a picture.
34
35
  //
@@ -67,18 +68,17 @@ function safeVerbToken(verb) {
67
68
  return typeof verb === 'string' && SAFE_VERB_TOKEN.test(verb) ? verb : 'device';
68
69
  }
69
70
 
70
- // mobile-automator/screenshots/<runId>/<verb>-<ts>.png.
71
+ // .mobile-automator/screenshots/<runId>/<verb>-<ts>.png.
71
72
  //
72
73
  // Under screenshots/, NOT results/<run_id>/screenshots/ which the execute guide
73
74
  // uses for agent-directed captures, because `mauto setup` writes
74
- // mobile-automator/.gitignore covering `screenshots/` and not the results tree.
75
+ // .mobile-automator/.gitignore covering `screenshots/` and not the results tree.
75
76
  // A photograph of a failing app is precisely the artifact that must not ride
76
77
  // into a user's commit on a `git add -A`.
77
78
  function failureShotPath(projectRoot, runId, verb) {
78
79
  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
79
80
  return path.join(
80
- projectRoot,
81
- 'mobile-automator',
81
+ workspaceDir(projectRoot),
82
82
  'screenshots',
83
83
  runId,
84
84
  `${safeVerbToken(verb)}-${stamp}.png`
@@ -105,7 +105,7 @@ async function captureOnFailure({
105
105
  if (!isCapturable(result)) return null;
106
106
  if (!tracePath) return null;
107
107
  // The same permission the file sink requires (see sinks/file.js): an
108
- // observability artifact may not create mobile-automator/ where no
108
+ // observability artifact may not create .mobile-automator/ where no
109
109
  // workspace exists. A valid run id is not consent to litter — without this
110
110
  // gate a failing verb would mkdir screenshots/ into an undiscoverable
111
111
  // tree, the #188 pathology.
@@ -5,10 +5,11 @@
5
5
  // src/device/session-paths.js.
6
6
  //
7
7
  // NOTE: this is NOT where the daemon's raw stdio goes. That lives at
8
- // mobile-automator/.session/daemon.log (session-paths.logFilePath, PR #176).
8
+ // .mobile-automator/.session/daemon.log (session-paths.logFilePath, PR #176).
9
9
  // Two artifacts, two homes: raw process output there, structured events here.
10
10
 
11
11
  const path = require('path');
12
+ const { workspaceDir } = require('../workspace/layout');
12
13
 
13
14
  const LOGS_DIRNAME = '.logs';
14
15
  const MAIN_LOG_NAME = 'mauto.ndjson';
@@ -16,17 +17,9 @@ const DAEMON_LOG_NAME = 'daemon.ndjson';
16
17
  const RUN_TRACE_PREFIX = 'run-';
17
18
  const SPOOL_NAME = 'telemetry.spool';
18
19
 
19
- // The workspace root `mauto setup` creates. The file sink treats its existence
20
- // as permission to log: mauto runs from whatever directory a user is standing
21
- // in, so creating this tree as a side effect of logging would litter unrelated
22
- // repos with a directory that has no .gitignore in it.
23
- function workspaceDir(projectRoot) {
24
- return path.join(projectRoot, 'mobile-automator');
25
- }
26
-
27
20
  function logsDir(projectRoot, env = process.env) {
28
21
  if (env && env.MAUTO_LOG_DIR) return path.resolve(env.MAUTO_LOG_DIR);
29
- return path.join(projectRoot, 'mobile-automator', LOGS_DIRNAME);
22
+ return path.join(workspaceDir(projectRoot), LOGS_DIRNAME);
30
23
  }
31
24
 
32
25
  function mainLogPath(projectRoot, env = process.env) {
@@ -63,7 +56,7 @@ function daemonEventLogPath(projectRoot, env = process.env) {
63
56
  }
64
57
 
65
58
  // The telemetry queue. Deliberately NOT a .ndjson name even though its content
66
- // is NDJSON: TROUBLESHOOTING.md documents `cat mobile-automator/.logs/*.ndjson`
59
+ // is NDJSON: TROUBLESHOOTING.md documents `cat .mobile-automator/.logs/*.ndjson`
67
60
  // as the merged CLI+daemon timeline, and the spool is not part of that timeline
68
61
  // — it is a queue that gets renamed out from under a reader mid-flush. The
69
62
  // extension is the interface that keeps the two apart.
@@ -115,7 +108,6 @@ module.exports = {
115
108
  DAEMON_LOG_NAME,
116
109
  RUN_TRACE_PREFIX,
117
110
  SPOOL_NAME,
118
- workspaceDir,
119
111
  logsDir,
120
112
  mainLogPath,
121
113
  daemonEventLogPath,
@@ -13,7 +13,8 @@
13
13
  const realFs = require('fs');
14
14
  const path = require('path');
15
15
 
16
- const { mainLogPath, workspaceDir } = require('../paths');
16
+ const { mainLogPath } = require('../paths');
17
+ const { workspaceDir } = require('../../workspace/layout');
17
18
  const { MAX_LOG_BYTES, rotateIfLarge } = require('../../util/log-rotate');
18
19
 
19
20
  function format(event) {
@@ -24,8 +25,8 @@ function format(event) {
24
25
  //
25
26
  // `mauto` is a CLI run from wherever the user is standing, and unconditional
26
27
  // mkdir meant every invocation in any directory silently created
27
- // mobile-automator/. That is litter, and worse than litter: `mauto setup`
28
- // writes mobile-automator/.gitignore, so a tree created by the SINK instead of
28
+ // .mobile-automator/. That is litter, and worse than litter: `mauto setup`
29
+ // writes .mobile-automator/.gitignore, so a tree created by the SINK instead of
29
30
  // by setup is an un-ignored directory accumulating device serials in someone's
30
31
  // repo, ready for `git add -A`.
31
32
  //
@@ -22,7 +22,8 @@ const realFs = require('fs');
22
22
  const crypto = require('crypto');
23
23
  const path = require('path');
24
24
 
25
- const { spoolPath, workspaceDir } = require('./paths');
25
+ const { spoolPath } = require('./paths');
26
+ const { workspaceDir } = require('../workspace/layout');
26
27
  const { telemetryPayload } = require('./event');
27
28
 
28
29
  // ~1000 lines at ~250 bytes. Not rotateIfLarge: that policy is for LOGS, and
@@ -58,7 +59,7 @@ function isSelfReferential(event) {
58
59
  return typeof event.event === 'string' && event.event.startsWith('telemetry.');
59
60
  }
60
61
 
61
- // Same gate as the file sink: no mobile-automator/ workspace, no artifacts.
62
+ // Same gate as the file sink: no .mobile-automator/ workspace, no artifacts.
62
63
  // mauto runs from wherever a user is standing, so creating this tree as a
63
64
  // side effect of logging would litter unrelated repos with a directory that
64
65
  // has no .gitignore in it.
@@ -6,9 +6,10 @@ const path = require('path');
6
6
  const { atomicWrite } = require('../util/atomic');
7
7
  const { withLock } = require('../util/lock');
8
8
  const { OBSERVATION_TYPES } = require('./flags');
9
+ const { workspaceDir } = require('../workspace/layout');
9
10
 
10
11
  // Incremental result accumulator that persists to
11
- // <projectRoot>/mobile-automator/results/<runId>.json
12
+ // <projectRoot>/.mobile-automator/results/<runId>.json
12
13
  //
13
14
  // The CLI runs one-shot: each `result add-step` / `result finalize` invocation
14
15
  // is a fresh process. To support that, the store loads any existing in-progress
@@ -54,7 +55,7 @@ class ResultStore {
54
55
  this.projectRoot = projectRoot;
55
56
  this._metadataOverrides = metadata || {};
56
57
 
57
- this._dir = path.join(projectRoot, 'mobile-automator', 'results');
58
+ this._dir = path.join(workspaceDir(projectRoot), 'results');
58
59
  this._file = path.join(this._dir, `${runId}.json`);
59
60
  // Per-runId advisory lock guarding every read-modify-write mutator. Lives
60
61
  // in the same directory as the result file, so the lock is scoped to this
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
3
  "title": "Mobile Automator Workspace Config",
4
- "description": "Schema for mobile-automator/config.json. Declares the type of every key `mauto config set` knows about. Unknown keys are permitted (additionalProperties: true) so agents can persist project knowledge this schema does not anticipate — the schema types keys, it does not gate them.",
4
+ "description": "Schema for .mobile-automator/config.json. Declares the type of every key `mauto config set` knows about. Unknown keys are permitted (additionalProperties: true) so agents can persist project knowledge this schema does not anticipate — the schema types keys, it does not gate them.",
5
5
  "type": "object",
6
6
  "additionalProperties": true,
7
7
  "definitions": {
@@ -205,7 +205,7 @@
205
205
  },
206
206
  "measurements": {
207
207
  "type": "object",
208
- "description": "Facts MEASURED from the run's event trace (mobile-automator/.logs/run-<run_id>.ndjson) rather than self-reported by the executing agent. Absent when no trace was available — MAUTO_RUN_ID unset, logging silenced, no workspace, or a run id that could not name a file.",
208
+ "description": "Facts MEASURED from the run's event trace (.mobile-automator/.logs/run-<run_id>.ndjson) rather than self-reported by the executing agent. Absent when no trace was available — MAUTO_RUN_ID unset, logging silenced, no workspace, or a run id that could not name a file.",
209
209
  "properties": {
210
210
  "source": {
211
211
  "type": "string",
@@ -271,7 +271,7 @@
271
271
  "checkpoint": {
272
272
  "type": "boolean",
273
273
  "default": false,
274
- "description": "Whether to capture a reference screenshot after this step. Screenshots are saved as mobile-automator/screenshots/<scenario_id>/step_<id>.png"
274
+ "description": "Whether to capture a reference screenshot after this step. Screenshots are saved as .mobile-automator/screenshots/<scenario_id>/step_<id>.png"
275
275
  },
276
276
  "expected_state": {
277
277
  "type": "string",
@@ -2,7 +2,7 @@
2
2
 
3
3
  // Workspace scaffolding for `mauto setup`.
4
4
  //
5
- // Creates the mobile-automator/{scenarios,screenshots,results} tree and a
5
+ // Creates the .mobile-automator/{scenarios,screenshots,results} tree and a
6
6
  // skeleton config.json. Idempotent: re-running never clobbers an existing
7
7
  // config's other fields — it only ensures the requested `mode` is set.
8
8
 
@@ -10,6 +10,7 @@ const fs = require('fs');
10
10
  const path = require('path');
11
11
 
12
12
  const manager = require('../config/manager');
13
+ const { workspaceDir } = require('../workspace/layout');
13
14
 
14
15
  const SUBDIRS = ['scenarios', 'screenshots', 'results', 'memory'];
15
16
 
@@ -31,7 +32,7 @@ const GITIGNORE_BODY = [
31
32
  function scaffold(projectRoot, { mode } = {}) {
32
33
  const created = [];
33
34
 
34
- const baseDir = path.join(projectRoot, 'mobile-automator');
35
+ const baseDir = workspaceDir(projectRoot);
35
36
  ensureDir(baseDir, created);
36
37
  for (const sub of SUBDIRS) {
37
38
  ensureDir(path.join(baseDir, sub), created);
@@ -3,8 +3,8 @@
3
3
  // The codebase's ONE log rotation policy, in one place.
4
4
  //
5
5
  // mauto keeps two log artifacts with different consumers — the daemon's raw
6
- // stdio at mobile-automator/.session/daemon.log (#176) and the structured
7
- // NDJSON event stream at mobile-automator/.logs/ — but they want identical
6
+ // stdio at .mobile-automator/.session/daemon.log (#176) and the structured
7
+ // NDJSON event stream at .mobile-automator/.logs/ — but they want identical
8
8
  // disk hygiene, and the design says so explicitly. This module is what makes
9
9
  // that true rather than asserted: previously each file implemented rotation
10
10
  // itself, and the two copies had drifted in their failure semantics.
@@ -16,17 +16,25 @@ const path = require('path');
16
16
 
17
17
  const { fail } = require('../output/envelope');
18
18
 
19
- const WORKSPACE_DIRNAME = 'mobile-automator';
19
+ const { WORKSPACE_DIRNAME, LEGACY_WORKSPACE_DIRNAME } = require('./layout');
20
20
 
21
- // The MARKER is `mobile-automator/config.json`, not a bare `mobile-automator/`
22
- // directory. This repository is itself usually cloned into a folder named
23
- // `mobile-automator`, so a bare-directory check would make every checkout's
24
- // parent look like a workspace. `mauto setup` always writes config.json, so a
25
- // real workspace always carries it.
21
+ // The MARKER is `.mobile-automator/config.json`, not a bare `.mobile-automator/`
22
+ // directory: `mauto setup` always writes config.json, so a real workspace
23
+ // always carries it, and an unrelated directory that merely shares the name
24
+ // does not count. (The marker used to also guard against this repository's own
25
+ // clone folder, `mobile-automator`; that collision cannot happen with a dotted
26
+ // name.)
26
27
  function markerPath(dir) {
27
28
  return path.join(dir, WORKSPACE_DIRNAME, 'config.json');
28
29
  }
29
30
 
31
+ // The pre-rename workspace marker. Only ever probed with existsSync: mauto
32
+ // never reads, moves or writes inside the legacy folder, it just tells the user
33
+ // where it is so they can `mv` it themselves.
34
+ function legacyMarkerPath(dir) {
35
+ return path.join(dir, LEGACY_WORKSPACE_DIRNAME, 'config.json');
36
+ }
37
+
30
38
  // Walk up from `startDir` and return the NEAREST directory holding a workspace.
31
39
  // `searched` lists every directory checked, in order, so a caller that finds
32
40
  // nothing can tell the user exactly where it looked.
@@ -37,18 +45,26 @@ function markerPath(dir) {
37
45
  // boundary, a nested checkout with no workspace of its own would silently
38
46
  // adopt whichever unrelated workspace happens to sit above it. The check is
39
47
  // inclusive — a workspace at the repository root is the common case.
48
+ //
49
+ // The walk stops at the first directory holding EITHER marker, so the nearest
50
+ // workspace wins whichever name it uses — as it did before the rename. In that
51
+ // directory the new marker wins over a legacy one beside it (the user is
52
+ // mid-recovery). A legacy-only directory ends the walk with `legacy` set and no
53
+ // root: carrying on to a new workspace further up would silently run every verb
54
+ // against the ancestor's state while the project's own is left behind.
40
55
  function findWorkspaceRoot(startDir, { fs = require('fs') } = {}) {
41
56
  const searched = [];
42
57
  let dir = path.resolve(startDir);
43
58
  for (;;) {
44
59
  searched.push(dir);
45
- if (fs.existsSync(markerPath(dir))) return { root: dir, searched };
60
+ if (fs.existsSync(markerPath(dir))) return { root: dir, searched, legacy: null };
61
+ if (fs.existsSync(legacyMarkerPath(dir))) return { root: null, searched, legacy: dir };
46
62
  if (fs.existsSync(path.join(dir, '.git'))) break;
47
63
  const parent = path.dirname(dir);
48
64
  if (parent === dir) break; // filesystem root
49
65
  dir = parent;
50
66
  }
51
- return { root: null, searched };
67
+ return { root: null, searched, legacy: null };
52
68
  }
53
69
 
54
70
  // The honest answer when discovery found nothing, for a verb that cannot work
@@ -66,4 +82,35 @@ function noWorkspaceFailure(searched) {
66
82
  };
67
83
  }
68
84
 
69
- module.exports = { findWorkspaceRoot, noWorkspaceFailure, markerPath, WORKSPACE_DIRNAME };
85
+ // The workspace directory was renamed to a hidden one. There is no migration
86
+ // code: the fix is a one-line `mv`, but the old daemon must be stopped first
87
+ // (`mauto session end` would itself look for the new directory and fail) and a
88
+ // stray new directory removed so `mv` renames instead of nesting.
89
+ function legacyWorkspaceFailure(dir) {
90
+ return {
91
+ envelope: fail(
92
+ 'environment',
93
+ `found legacy workspace ${dir}/${LEGACY_WORKSPACE_DIRNAME}/ — the workspace directory is now ${WORKSPACE_DIRNAME}/`,
94
+ `In ${dir}: stop any daemon the old version left running (pkill -f mauto-session-daemon), delete ${WORKSPACE_DIRNAME}/ if it already exists, then run mv ${LEGACY_WORKSPACE_DIRNAME} ${WORKSPACE_DIRNAME} — before any other mauto verb.`
95
+ ),
96
+ exitKind: 'environment',
97
+ };
98
+ }
99
+
100
+ // The failure for a `findWorkspaceRoot` result that has no workspace. Whether a
101
+ // pre-rename folder was passed on the walk is policy owned here, so callers
102
+ // hand over the whole result instead of choosing between the two failures.
103
+ function workspaceFailure(workspace) {
104
+ return workspace.legacy
105
+ ? legacyWorkspaceFailure(workspace.legacy)
106
+ : noWorkspaceFailure(workspace.searched);
107
+ }
108
+
109
+ module.exports = {
110
+ findWorkspaceRoot,
111
+ workspaceFailure,
112
+ legacyWorkspaceFailure,
113
+ // noWorkspaceFailure is exported for its own unit tests only; verbs go
114
+ // through workspaceFailure.
115
+ noWorkspaceFailure,
116
+ };
@@ -0,0 +1,26 @@
1
+ 'use strict';
2
+
3
+ // The one place the per-project workspace is named and located. The workspace
4
+ // is hidden (`.mobile-automator/`) so it stays out of the way in a project
5
+ // root; it used to be the visible `mobile-automator/`. Every path in the CLI is
6
+ // built from workspaceDir(), and tests/lint/workspace-dirname-single-source.test.js
7
+ // fails the build if any file outside src/workspace/ names the constants or
8
+ // spells either directory as a string literal.
9
+ //
10
+ // LEGACY_WORKSPACE_DIRNAME exists only so a pre-rename workspace can be
11
+ // recognised and reported; nothing writes to it.
12
+ //
13
+ // A leaf module (requires only `path`) so anything can import it without a cycle.
14
+
15
+ const path = require('path');
16
+
17
+ const WORKSPACE_DIRNAME = '.mobile-automator';
18
+ const LEGACY_WORKSPACE_DIRNAME = 'mobile-automator';
19
+
20
+ // The workspace root under a project root. Callers join their own subpath onto
21
+ // this rather than rebuilding it from the name.
22
+ function workspaceDir(projectRoot) {
23
+ return path.join(projectRoot, WORKSPACE_DIRNAME);
24
+ }
25
+
26
+ module.exports = { WORKSPACE_DIRNAME, LEGACY_WORKSPACE_DIRNAME, workspaceDir };