mobile-automator 0.25.0 → 0.26.0

package/src/schemas/result_schema.json

@@ -203,6 +203,61 @@
       },
       "description": "Observations from observer traits (regression spotter, flakiness detector, state detective)"
     },
+    "measurements": {
+      "type": "object",
+      "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.",
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["trace", "reported", "none"],
+          "description": "Where duration_seconds came from: measured from the trace, taken from --duration, or neither."
+        },
+        "reported_duration_seconds": {
+          "type": ["number", "null"],
+          "description": "What --duration claimed, retained even when the measured value was written to duration_seconds instead."
+        },
+        "duration_disagreement": {
+          "type": "boolean",
+          "description": "True when the reported and measured durations differ by more than the tolerance. The disagreement is itself a signal and is recorded rather than silently resolved."
+        },
+        "trace_events": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of events in the run trace."
+        },
+        "device_failures": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Device-kind and timeout-kind verb failures recorded during the run. Every one is an attempt that did not take."
+        },
+        "trace_truncated": {
+          "type": "boolean",
+          "description": "True when the trace reached its size cap, so the measured duration is a lower bound rather than the run's full span."
+        },
+        "failure_screenshots": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Screenshots captured automatically at device failures during this run."
+        }
+      }
+    },
+    "crashes": {
+      "type": "array",
+      "description": "App crash reports observed during this run. Present only when at least one was observed, so a clean run's file is unchanged. Populated by `mauto result add-crash`, typically from `mauto crash list`.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "crash_id": { "type": "string", "description": "Device-local report id; pass to `mauto crash get` for the full report" },
+          "process": { "type": ["string", "null"], "description": "Package/bundle identifier of the process that died" },
+          "timestamp": { "type": ["string", "null"], "description": "The device's own time for the report, when it reports one" },
+          "detected_at": { "type": "string", "description": "ISO time at which mauto observed the report" },
+          "step_id": { "type": ["string", "null"], "description": "Step in flight when the crash was observed" },
+          "excerpt": { "type": ["string", "null"], "description": "Bounded head of the crash report (max 2000 chars); the full report lives at report_path" },
+          "report_path": { "type": ["string", "null"], "description": "Path to the full report written by `mauto crash get --out`" }
+        },
+        "required": ["crash_id", "detected_at"]
+      }
+    },
     "summary": {
       "type": "string",
       "description": "Human-readable overall summary"

package/src/setup/scaffold.js

@@ -13,6 +13,21 @@ const manager = require('../config/manager');
 
 const SUBDIRS = ['scenarios', 'screenshots', 'results', 'memory'];
 
+// Runtime artifacts that must never reach a user's git history. `.session/`
+// has held a socket, pidfile and handle since the CLI landed; since #163 it
+// also holds daemon.log, which carries device serials, adb/simctl output and
+// stack traces. `.logs/` holds the structured event stream. Neither is
+// reproducible input and both are noise in a diff.
+//
+// Written only when absent: a user who edits this file owns it thereafter.
+const GITIGNORE_BODY = [
+  '# Managed by `mauto setup`. Runtime artifacts — not source.',
+  '.session/',
+  '.logs/',
+  'screenshots/',
+  '',
+].join('\n');
+
 function scaffold(projectRoot, { mode } = {}) {
   const created = [];
 
@@ -22,6 +37,12 @@ function scaffold(projectRoot, { mode } = {}) {
     ensureDir(path.join(baseDir, sub), created);
   }
 
+  const gitignorePath = path.join(baseDir, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, GITIGNORE_BODY);
+    created.push(gitignorePath);
+  }
+
   const cfgPath = manager.configPath(projectRoot);
   let configWritten = false;
   if (!fs.existsSync(cfgPath)) {
@@ -31,6 +52,12 @@ function scaffold(projectRoot, { mode } = {}) {
       project_name: null,
       environments: [],
       default_environment: null,
+      // Written as a LITERAL false rather than omitted. An absent key that
+      // happens to default off is not discoverable; a visible false is, and
+      // discoverability is part of consent. The `else` branch below never
+      // touches this key: re-running setup must not silently revoke — or
+      // silently grant — a choice the project owner already made.
+      telemetry: { enabled: false },
     };
     fs.writeFileSync(cfgPath, JSON.stringify(skeleton, null, 2) + '\n');
     created.push(cfgPath);

package/src/util/log-rotate.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// The codebase's ONE log rotation policy, in one place.
+//
+// mauto keeps two log artifacts with different consumers — the daemon's raw
+// stdio at mobile-automator/.session/daemon.log (#176) and the structured
+// NDJSON event stream at mobile-automator/.logs/ — but they want identical
+// disk hygiene, and the design says so explicitly. This module is what makes
+// that true rather than asserted: previously each file implemented rotation
+// itself, and the two copies had drifted in their failure semantics.
+//
+// Policy: at or above the cap, rename to `<log>.1`, clobbering whatever `.1`
+// was there. A single generation is the intended bound — enough to survive a
+// crash loop that overwrites the interesting part of the live log, cheap to
+// reason about, and it cannot grow without limit.
+
+const realFs = require('fs');
+
+const MAX_LOG_BYTES = 1024 * 1024;
+
+// Best effort, and that is the contract, not a shortcut. Every failure here is
+// survivable — no log yet (ENOENT on stat), a concurrent writer that already
+// rotated (ENOENT on rename), an unwritable directory (EACCES) — while the
+// caller's actual job (opening the daemon log, appending an event) is not.
+// An oversized log beats no log, so a rotation that cannot run is swallowed.
+function rotateIfLarge(logPath, { maxBytes = MAX_LOG_BYTES, fs = realFs } = {}) {
+  try {
+    if (fs.statSync(logPath).size >= maxBytes) fs.renameSync(logPath, `${logPath}.1`);
+  } catch (_) {
+    /* nothing to rotate, or someone beat us to it */
+  }
+}
+
+module.exports = { MAX_LOG_BYTES, rotateIfLarge };

package/src/workspace/discover.js

@@ -0,0 +1,69 @@
+'use strict';
+
+// Upward workspace discovery (#188).
+//
+// Every neighbouring tool a developer runs inside a repo — git, npm, cargo —
+// walks up from cwd to find its root. mauto used to join `<cwd>/mobile-automator`
+// and stop, so from any subdirectory it reported a confident, well-formed answer
+// about an empty workspace (`config get` with the value silently absent, an
+// empty memory store). This module is the walk; src/cli.js decides what each
+// verb does with its answer.
+//
+// Pure apart from `fs.existsSync`, which is injectable so the walk's
+// termination can be tested without a real filesystem root.
+
+const path = require('path');
+
+const { fail } = require('../output/envelope');
+
+const WORKSPACE_DIRNAME = 'mobile-automator';
+
+// The MARKER is `mobile-automator/config.json`, not a bare `mobile-automator/`
+// directory. This repository is itself usually cloned into a folder named
+// `mobile-automator`, so a bare-directory check would make every checkout's
+// parent look like a workspace. `mauto setup` always writes config.json, so a
+// real workspace always carries it.
+function markerPath(dir) {
+  return path.join(dir, WORKSPACE_DIRNAME, 'config.json');
+}
+
+// Walk up from `startDir` and return the NEAREST directory holding a workspace.
+// `searched` lists every directory checked, in order, so a caller that finds
+// nothing can tell the user exactly where it looked.
+//
+// The walk stops AFTER checking a directory that contains `.git` (a directory,
+// or a file — worktrees and submodules have a `.git` file). A workspace belongs
+// to a project, and a project does not extend past its repository: without the
+// boundary, a nested checkout with no workspace of its own would silently
+// adopt whichever unrelated workspace happens to sit above it. The check is
+// inclusive — a workspace at the repository root is the common case.
+function findWorkspaceRoot(startDir, { fs = require('fs') } = {}) {
+  const searched = [];
+  let dir = path.resolve(startDir);
+  for (;;) {
+    searched.push(dir);
+    if (fs.existsSync(markerPath(dir))) return { root: dir, searched };
+    if (fs.existsSync(path.join(dir, '.git'))) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  return { root: null, searched };
+}
+
+// The honest answer when discovery found nothing, for a verb that cannot work
+// without a workspace. `environment` (exit 5), matching the CLI's other
+// fixable-by-the-caller faults: an agent reading `ok:true` with a missing value
+// cannot tell "unset" from "wrong directory", so this must not be a success.
+function noWorkspaceFailure(searched) {
+  return {
+    envelope: fail(
+      'environment',
+      `no ${WORKSPACE_DIRNAME}/ workspace found (looked for ${WORKSPACE_DIRNAME}/config.json)`,
+      `Searched: ${searched.join(', ')}. Run \`mauto setup\` from your project root, or cd into the project that has one.`
+    ),
+    exitKind: 'environment',
+  };
+}
+
+module.exports = { findWorkspaceRoot, noWorkspaceFailure, markerPath, WORKSPACE_DIRNAME };