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.
- package/README.md +6 -6
- package/bin/mauto-session-daemon.js +1 -1
- package/package.json +1 -1
- package/src/cli.js +36 -15
- package/src/config/manager.js +6 -9
- package/src/device/connection.js +1 -1
- package/src/device/engine-hints.js +1 -1
- package/src/device/process-identity.js +11 -5
- package/src/device/selection.js +2 -2
- package/src/device/session-daemon.js +1 -1
- package/src/device/session-end.js +43 -13
- package/src/device/session-handle.js +1 -1
- package/src/device/session-paths.js +17 -2
- package/src/device/session-salt.js +1 -1
- package/src/device/session-spawn.js +1 -1
- package/src/guide/content/execute.agnostic.md +8 -8
- package/src/guide/content/execute.aware.md +7 -7
- package/src/guide/content/generate.agnostic.md +6 -6
- package/src/guide/content/generate.aware.md +6 -6
- package/src/guide/content/setup.agnostic.md +1 -1
- package/src/guide/content/setup.aware.md +1 -1
- package/src/guide/emitter.js +1 -1
- package/src/init/skill-meta.js +1 -1
- package/src/mcp/prompts.js +1 -1
- package/src/memory/paths.js +3 -5
- package/src/observe/failure-capture.js +7 -7
- package/src/observe/paths.js +4 -12
- package/src/observe/sinks/file.js +4 -3
- package/src/observe/spool.js +3 -2
- package/src/result/store.js +3 -2
- package/src/schemas/config_schema.json +1 -1
- package/src/schemas/result_schema.json +1 -1
- package/src/schemas/scenario_schema.json +1 -1
- package/src/setup/scaffold.js +3 -2
- package/src/util/log-rotate.js +2 -2
- package/src/workspace/discover.js +56 -9
- 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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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 {
|
|
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
|
-
|
|
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
|
-
//
|
|
1415
|
-
// differs is WHY, and so what the user should do about it. One vague hint
|
|
1416
|
-
// to cover all
|
|
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
|
-
`
|
|
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(
|
|
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(
|
|
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')
|
package/src/config/manager.js
CHANGED
|
@@ -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(
|
|
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(
|
|
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
|
|
72
|
+
module.exports = { load, resolveMode, get, set, configPath };
|
package/src/device/connection.js
CHANGED
|
@@ -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
|
|
70
|
-
// command line
|
|
71
|
-
// workspace's
|
|
72
|
-
//
|
|
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
|
-
|
|
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
|
}
|
package/src/device/selection.js
CHANGED
|
@@ -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
|
|
35
|
-
//
|
|
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
|
|
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
|
|
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
|
|
73
|
-
//
|
|
74
|
-
// Never signalled. Without an ack nothing answered on
|
|
75
|
-
// of ours was running. With an ack
|
|
76
|
-
//
|
|
77
|
-
//
|
|
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
|
|
88
|
-
// daemon alive — spawning then would just find it answering pings
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
62
|
-
- If the install fails because a different build is already on the device, uninstall it with `mauto uninstall <appId>` (the app identifier from
|
|
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
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
337
|
-
-
|
|
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
|
|
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
|
|
207
|
+
6. Save to `.mobile-automator/scenarios/<scenario_id>.json`.
|
|
208
208
|
7. Present summary:
|
|
209
|
-
> "Scenario saved:
|
|
209
|
+
> "Scenario saved: `.mobile-automator/scenarios/<scenario_id>.json`
|
|
210
210
|
> - Steps: [N] | Checkpoints: [N] screenshots | Assertions: [N] | Tags: [tag1, tag2]
|
|
211
|
-
> - Screenshots:
|
|
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
|
-
-
|
|
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
|
|
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
|
|
221
|
+
8. Save to `.mobile-automator/scenarios/<scenario_id>.json`.
|
|
222
222
|
9. Present summary:
|
|
223
|
-
> "Scenario saved:
|
|
223
|
+
> "Scenario saved: `.mobile-automator/scenarios/<scenario_id>.json`
|
|
224
224
|
> - Steps: [N] | Checkpoints: [N] screenshots | Assertions: [N] | Tags: [tag1, tag2]
|
|
225
|
-
> - Screenshots:
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
package/src/guide/emitter.js
CHANGED
|
@@ -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
|
|
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'];
|
package/src/init/skill-meta.js
CHANGED
|
@@ -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
|
},
|
package/src/mcp/prompts.js
CHANGED
|
@@ -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
|
package/src/memory/paths.js
CHANGED
|
@@ -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, '
|
|
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
|
|
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.
|
package/src/observe/paths.js
CHANGED
|
@@ -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,
|
|
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
|
|
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
|
//
|
package/src/observe/spool.js
CHANGED
|
@@ -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
|
|
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.
|
package/src/result/store.js
CHANGED
|
@@ -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
|
|
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, '
|
|
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",
|
package/src/setup/scaffold.js
CHANGED
|
@@ -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 =
|
|
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);
|
package/src/util/log-rotate.js
CHANGED
|
@@ -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 = '
|
|
19
|
+
const { WORKSPACE_DIRNAME, LEGACY_WORKSPACE_DIRNAME } = require('./layout');
|
|
20
20
|
|
|
21
|
-
// The MARKER is
|
|
22
|
-
// directory
|
|
23
|
-
//
|
|
24
|
-
//
|
|
25
|
-
//
|
|
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
|
-
|
|
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 };
|