mobile-automator 0.24.0 → 0.26.0

package/README.md

@@ -8,24 +8,36 @@ Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents all have one-
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20CMP-green.svg)](#)
-[![Node](https://img.shields.io/badge/Node-%E2%89%A518-brightgreen.svg)](#)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A520-brightgreen.svg)](#)
 
 ---
 
 ## ⏱️ Quick start (5 minutes)
 
-**You need:** Node ≥ 18 · an AI coding agent · a running emulator/simulator or a connected device.
+**You need:** Node ≥ 20 · an AI coding agent · a running emulator/simulator or a connected device.
 
 > This quick start uses **Claude Code** as the example agent. For Cursor, swap `--agent claude` → `--agent cursor`. For any other agent, see [Using another agent](#-using-another-agent).
 
-**1. Install `mauto`** (from source — not yet on npm):
+**1. Install `mauto`:**
 
 ```bash
+npm i -g mobile-automator      # exposes `mauto` globally
+```
+
+<details>
+<summary>Or run it without installing / build from source</summary>
+
+```bash
+npx mobile-automator <verb>    # no global install
+
+# from source, to run unreleased changes:
 git clone https://github.com/sh3lan93/mobile-automator
 cd mobile-automator
-npm install && npm link        # exposes `mauto` globally
+npm install && npm link
 ```
 
+</details>
+
 **2. Wire it into your project and agent:**
 
 ```bash
@@ -102,6 +114,17 @@ In agnostic mode, OS-shaped gestures become four semantic actions — `press_bac
 
 ---
 
+### Telemetry
+
+`mauto` collects nothing by default. Anonymous usage telemetry is opt-in via
+`mauto telemetry enable`, sends no free text of any kind, and carries no
+per-machine identifier.
+`MAUTO_TELEMETRY=0` and `DO_NOT_TRACK=1` force it off. Run `mauto telemetry
+status` for the exact field list, or read
+[Telemetry & Privacy](https://sh3lan93.github.io/mobile-automator/reference/telemetry/).
+
+---
+
 ## 📋 Command reference
 
 Most low-level verbs are called **by the agent**, not by you. The ones you'll run directly are at the top.

package/bin/mauto-session-daemon.js

@@ -12,6 +12,9 @@ const fs = require('fs');
 
 const { startDaemon } = require('../src/device/session-daemon');
 const paths = require('../src/device/session-paths');
+const { boundRecorder } = require('../src/observe/recorder');
+const { daemonEventLogPath } = require('../src/observe/paths');
+const { makeFlusher } = require('../src/observe/flush');
 
 // Best-effort synchronous unlink — never throws. Used by the crash guards so a
 // hard failure can't leave a stale lock/socket/pidfile wedging the next spawn.
@@ -64,6 +67,39 @@ async function main() {
   const idleRaw = process.env.MAUTO_SESSION_IDLE_MS;
   const idleMs = idleRaw ? Number(idleRaw) : undefined;
 
+  // Where this process's events go: its own log file (daemon.ndjson, not the
+  // CLI's mauto.ndjson — see observe/paths.js). `env` is read once and the log
+  // path derived from that same object, so the sinks and the path can never
+  // disagree about MAUTO_LOG_DIR. See boundRecorder for why record()'s defaults
+  // are wrong for a detached process, and for why a construction failure
+  // degrades rather than throwing.
+  //
+  // The stderr sink is deliberately left in place: the daemon's stderr IS
+  // mobile-automator/.session/daemon.log (PR #176), not a terminal, which
+  // inverts cli.js finish()'s calculus — a warn line here costs a human no
+  // terminal noise and lands next to the adb/simctl output that explains it.
+  //
+  // A FACTORY, not a recorder. session_id belongs to startDaemon — it mints the
+  // id, writes it to the handle and binds it — so this file cannot build a
+  // session-bound recorder, and must not try: an id minted here and one written
+  // there are two owners that nothing forces to agree. This file owns WHERE the
+  // events go; startDaemon owns WHOSE they are.
+  const env = process.env;
+  const logPath = daemonEventLogPath(projectRoot, env);
+  const recorderFor = (fields) => boundRecorder({ projectRoot, env, logPath, fields });
+
+  // Two bindings of that one factory, because the crash guards outlive the
+  // question "is there a session yet?".
+  //
+  // Until startDaemon resolves there is no session to name, so this one carries
+  // the process identity alone. Nothing is lost by that: a crash before
+  // startDaemon resolves is by definition a daemon that never wrote a handle,
+  // so a session id would name nothing a reader could join against, and `pid`
+  // already groups those events. The moment the daemon exists we adopt ITS
+  // recorder (below), so every later crash — the common case — is stamped with
+  // the session whose handle is on disk.
+  let observe = recorderFor({ src: 'daemon', pid: process.pid });
+
   let daemon = null;
 
   // Crash guards: this is the real, single-daemon process, so a best-effort
@@ -74,26 +110,59 @@ async function main() {
   // the next spawn isn't wedged by leftovers from this process.
   const onExit = () => cleanupWorkspaceIfOwned(projectRoot);
   process.on('exit', onExit);
-  process.on('uncaughtException', (err) => {
-    process.stderr.write(`mauto-session-daemon: uncaught ${err && err.stack ? err.stack : err}\n`);
-    // Tear the daemon down (closes the mobile-mcp child) then let 'exit' clean
-    // the files.
-    if (daemon && typeof daemon.stop === 'function') {
-      daemon.stop().catch(() => {});
-    }
-    process.exit(1);
-  });
-  process.on('unhandledRejection', (err) => {
-    process.stderr.write(`mauto-session-daemon: unhandled rejection ${err && err.stack ? err.stack : err}\n`);
-    // Same teardown as uncaughtException: a rejected promise must not leave a
-    // leaked mobile-mcp child / stale files wedging the next spawn.
+  // One fatal handler, two registrations. The two crashes differ by exactly two
+  // strings; everything else about them is load-bearing and identical, so they
+  // are built from one function rather than kept in sync by hand.
+  //
+  // Recorded FIRST, before the stderr write and before teardown: these are the
+  // invisible deaths #156 is about, and process.exit(1) below is immediate. The
+  // file sink appends synchronously, so the line is on disk by the time the
+  // process is gone — a buffered sink would lose exactly this event.
+  //
+  // Two writes on purpose, to two different readers. The structured event
+  // carries the classification (and stays one line); the raw stderr write is
+  // #176's contract — the full stack, unchanged, in .session/daemon.log.
+  //
+  // Then tear the daemon down (closing the mobile-mcp child) and let 'exit'
+  // clean the files. Recording must not delay or displace the teardown that
+  // frees the lock/socket/pidfile, and `daemon` may still be null — a crash can
+  // beat startDaemon to it.
+  const onFatal = (kind, label) => (err) => {
+    observe({
+      level: 'error',
+      event: 'daemon.crash',
+      error_code: err && err.code,
+      message: `${kind}: ${err && err.message ? err.message : err}`,
+    });
+    process.stderr.write(`mauto-session-daemon: ${label} ${err && err.stack ? err.stack : err}\n`);
     if (daemon && typeof daemon.stop === 'function') {
-      daemon.stop().catch(() => {});
+      daemon.stop('crash').catch(() => {});
     }
     process.exit(1);
-  });
+  };
+  process.on('uncaughtException', onFatal('uncaughtException', 'uncaught'));
+  process.on('unhandledRejection', onFatal('unhandledRejection', 'unhandled rejection'));
 
-  daemon = await startDaemon({ projectRoot, device, idleMs });
+  daemon = await startDaemon({
+    projectRoot,
+    device,
+    idleMs,
+    recorderFor,
+    // Same defensive shape as recorderFor's own construction guarantee: a
+    // telemetry fault must never be the reason a daemon fails to start.
+    flushFor: ({ observe: sessionObserve }) => {
+      try {
+        return makeFlusher({ projectRoot, env: process.env, observe: sessionObserve });
+      } catch (_) {
+        return null;
+      }
+    },
+  });
+  // Adopt the daemon's own recorder: same log file, now bound to the session id
+  // it minted and wrote into the handle. onFatal reads `observe` when it fires,
+  // not when it was built, so every crash from here on is joinable to that
+  // handle. This is a READ of startDaemon's id, never a second mint of one.
+  observe = daemon.observe;
   // Keep the event loop alive until the daemon stops (idle reap / signal /
   // shutdown frame), then exit cleanly.
   await daemon.whenStopped;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
   "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
   "repository": {
@@ -26,7 +26,7 @@
     "prepublishOnly": "npm test",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
-    "lint:guides": "jest tests/lint/guide-no-mcp-tool-leak.test.js tests/lint/guide-no-placeholder-leak.test.js tests/lint/guide-agnostic-no-os.test.js tests/lint/guide-artifact-reuse.test.js tests/lint/skill-invariants.test.js tests/lint/skill-no-placeholder-leak.test.js tests/lint/skill-frontmatter-valid.test.js tests/lint/config-schema.test.js tests/lint/result-coverage.test.js",
+    "lint:guides": "jest tests/lint",
     "lint:schema-additive": "jest tests/lint/schema-additive.test.js",
     "test:unit": "jest tests/unit",
     "test:integration": "jest tests/integration",
@@ -41,9 +41,10 @@
   "devDependencies": {
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "js-yaml": "^4.3.2",
     "toml": "^3.0.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }