mobile-automator 0.25.0 → 0.26.0

package/src/observe/settings.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Resolves the observability control surface from the environment.
+//
+// Defaults are asymmetric on purpose: stderr is a HUMAN's channel during an
+// interactive run, so it stays quiet at `warn`; the file is a forensic record
+// nobody reads unless something broke, so it keeps `info`. One MAUTO_LOG_LEVEL
+// overrides both, because a user debugging wants the same detail in both
+// places and a second env var to remember is a worse interface.
+
+const { LEVELS } = require('./event');
+
+const DEFAULT_STDERR_LEVEL = 'warn';
+const DEFAULT_FILE_LEVEL = 'info';
+
+function resolveLevels(env = process.env) {
+  const raw = String((env && env.MAUTO_LOG_LEVEL) || '').toLowerCase();
+  if (raw === 'silent') return { stderr: null, file: null };
+  if (LEVELS.includes(raw)) return { stderr: raw, file: raw };
+  // Unrecognised values fall back rather than throw: a typo in an env var must
+  // never break `mauto tap`.
+  return { stderr: DEFAULT_STDERR_LEVEL, file: DEFAULT_FILE_LEVEL };
+}
+
+// True when `level` is at or above `threshold`. A null threshold means the
+// sink is off, so nothing passes.
+function atLeast(level, threshold) {
+  if (!threshold) return false;
+  const a = LEVELS.indexOf(level);
+  const b = LEVELS.indexOf(threshold);
+  if (a === -1 || b === -1) return false;
+  return a >= b;
+}
+
+// MAUTO_RUN_ID is the ONLY correlation input for device verbs — deliberately no
+// --run-id flag on the twelve of them. The agent exports it once per run; a
+// value that cannot change inside a run does not want twelve flags, each of
+// which is another place to forget it. The three `result` verbs correlate
+// through the --run-id they already require, which cli.js prefers over this.
+//
+// This answers "is there a run id", not "is it usable as a filename" — that is
+// runTracePath's job, and keeping it there means one gate rather than two that
+// can drift apart.
+function resolveRunId(env = process.env) {
+  const raw = env && env.MAUTO_RUN_ID;
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  return trimmed === '' ? null : trimmed;
+}
+
+module.exports = { DEFAULT_STDERR_LEVEL, DEFAULT_FILE_LEVEL, resolveLevels, atLeast, resolveRunId };

package/src/observe/sinks/file.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// NDJSON sink: one JSON object per line, append-only, so a log is greppable,
+// streamable, and parseable a line at a time even if the process died mid-file.
+//
+// Bounded by src/util/log-rotate.js — the codebase's one rotation policy, which
+// the daemon's raw stdio log binds to as well. This file used to say that while
+// forking the implementation; it now calls it.
+//
+// Every filesystem operation is guarded: a read-only workspace or a full disk
+// must degrade to "no logging", never to a failed `mauto tap`.
+
+const realFs = require('fs');
+const path = require('path');
+
+const { mainLogPath, workspaceDir } = require('../paths');
+const { MAX_LOG_BYTES, rotateIfLarge } = require('../../util/log-rotate');
+
+function format(event) {
+  return JSON.stringify(event) + '\n';
+}
+
+// No workspace, no file log.
+//
+// `mauto` is a CLI run from wherever the user is standing, and unconditional
+// mkdir meant every invocation in any directory silently created
+// mobile-automator/. That is litter, and worse than litter: `mauto setup`
+// writes mobile-automator/.gitignore, so a tree created by the SINK instead of
+// by setup is an un-ignored directory accumulating device serials in someone's
+// repo, ready for `git add -A`.
+//
+// The check is on the base dir, not on .logs/ — .logs/ legitimately does not
+// exist before the first event, so testing it would mean never logging at all.
+// MAUTO_LOG_DIR is exempt: pointing it somewhere is an explicit instruction to
+// log there, and it is how a user logs from an un-set-up directory on purpose.
+function allowed(projectRoot, env, fs) {
+  if (env && env.MAUTO_LOG_DIR) return true;
+  return fs.existsSync(workspaceDir(projectRoot));
+}
+
+// True when the file is at or past the cap, i.e. the next event would be
+// dropped. Exported because `result finalize` has to ask the same question
+// about a trace it is about to read, and a second copy of the comparison would
+// be a second policy that can drift from this one.
+function atCap(target, { fs = realFs, maxBytes = MAX_LOG_BYTES } = {}) {
+  try {
+    return fs.statSync(target).size >= maxBytes;
+  } catch (_) {
+    // No file yet, or unreadable: nothing has been dropped.
+    return false;
+  }
+}
+
+// How a log file is kept bounded. TWO modes, ONE constant — this is not a
+// second rotation policy, it is the same MAX_LOG_BYTES under a different
+// action.
+//
+// 'rotate' is the shared policy: at the cap, rename to `<log>.1` and start
+// fresh. Right for mauto.ndjson and daemon.ndjson, rolling diagnostics where
+// the recent past is the part worth keeping.
+//
+// 'cap' stops appending at the cap, and the difference is not a preference. A
+// per-run trace is not a rolling log: its whole CONTENT is a measurement, and
+// finalize derives the run duration from its FIRST and last events. Rotating it
+// renames the run's beginning out of the live file, so the next finalize would
+// compute the span of an arbitrary suffix and write a three-minute run down as
+// forty seconds — a number that looks measured, is reported as measured, and is
+// wrong, which is strictly worse than the self-report this slice replaces.
+// Dropping the NEWEST events instead keeps a contiguous prefix from the true
+// start, so a truncated trace still yields a duration with a stated meaning: a
+// lower bound, flagged as one via `trace_truncated`.
+function shouldAppend(target, bound, fs) {
+  if (bound !== 'cap') {
+    rotateIfLarge(target, { fs });
+    return true;
+  }
+  return !atCap(target, { fs });
+}
+
+// `logPath` lets a caller name the target file explicitly; without it the CLI's
+// mauto.ndjson is used. It does NOT bypass allowed(): which file to write is a
+// different question from whether this directory has opted into logging at all.
+//
+// `bound` picks the disk-hygiene policy: 'rotate' (default, unchanged) for
+// rolling diagnostics, 'cap' for a run trace. See shouldAppend for why the two
+// cannot share behaviour even though they share the one constant that bounds
+// them.
+function write(event, { projectRoot, env = process.env, fs = realFs, logPath, bound = 'rotate' } = {}) {
+  try {
+    if (!allowed(projectRoot, env, fs)) return;
+    const target = logPath || mainLogPath(projectRoot, env);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (!shouldAppend(target, bound, fs)) return;
+    fs.appendFileSync(target, format(event));
+  } catch (_) {
+    // Observability must never be load-bearing. Losing a log line is always
+    // preferable to failing the verb the user actually asked for.
+  }
+}
+
+module.exports = { format, write, atCap };

package/src/observe/sinks/stderr.js

@@ -0,0 +1,20 @@
+'use strict';
+
+// Human-facing sink for interactive debugging. STDERR ONLY — stdout is owned
+// exclusively by the verb's envelope (or its raw guide/schema output), and a
+// single stray stdout write silently breaks the contract every calling agent
+// depends on. The stream is injected so a test can prove that.
+
+const SKIP = new Set(['ts', 'v', 'mauto_version', 'node', 'os', 'level', 'event']);
+
+function write(event = {}, { stream = process.stderr } = {}) {
+  const parts = [`[${event.level || 'info'}]`, event.event || 'event'];
+  for (const [k, v] of Object.entries(event)) {
+    if (SKIP.has(k)) continue;
+    if (v === undefined || v === null) continue;
+    parts.push(`${k}=${v}`);
+  }
+  stream.write(parts.join(' ') + '\n');
+}
+
+module.exports = { write };

package/src/observe/spool.js

@@ -0,0 +1,199 @@
+'use strict';
+
+// The telemetry queue: the file every verb writes and no verb reads.
+//
+// A one-shot process cannot do network I/O. finish() calls process.exit() on
+// the line after record(), which tears down a pending socket mid-handshake —
+// so a fire-and-forget POST is not merely lossy, it is BIASED toward fast
+// machines and warm connections. Awaiting one instead adds a full RTT to every
+// `mauto tap`. So a verb appends to this file (tens of microseconds, completes
+// before the next statement) and something with an event loop — the daemon, or
+// `mauto telemetry flush` — does the network. An undelivered spool is not an
+// error state; it is a file the next daemon picks up.
+//
+// The line written here IS the network payload. Writing the full event and
+// redacting at flush time would put the redaction decision on the network path,
+// in a process that may be a different version of mauto than the one that wrote
+// the line. Redacting at SPOOL time means a device serial is never in the file
+// that gets uploaded, and makes the queue auditable: `cat` it and you have seen
+// everything that would be sent.
+
+const realFs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+
+const { spoolPath, workspaceDir } = require('./paths');
+const { telemetryPayload } = require('./event');
+
+// ~1000 lines at ~250 bytes. Not rotateIfLarge: that policy is for LOGS, and
+// renaming a queue to `.1` silently discards records that were pending
+// delivery, then clobbers that generation on the next rotation. A queue gets a
+// hard cap instead.
+const SPOOL_MAX_BYTES = 256 * 1024;
+
+// Fixed at `info`, independent of resolveLevels(), because telemetry has its
+// own separate control. Two halves, both deliberate:
+//   * `debug` never spools — 40x the volume, and debug-only fields are exactly
+//     the ones most likely to be newly added and thinly classified.
+//   * MAUTO_LOG_LEVEL=silent does not disable telemetry — silencing local logs
+//     is not withdrawal of consent, and consent has an explicit control of its
+//     own (`mauto telemetry disable`, MAUTO_TELEMETRY=0, DO_NOT_TRACK=1).
+const SPOOL_LEVEL = 'info';
+
+const CLAIM_SUFFIX = '.sending';
+
+// Zero-arity, CSPRNG, derived from NOTHING — the same property that makes
+// session_id's sends:true classification true rather than asserted. Generated
+// per EVENT and never reused, so it cannot correlate two events, let alone two
+// machines. It exists so that a re-sent batch (delivery is at-least-once)
+// deduplicates at ingestion.
+function newMessageId() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+// Events about telemetry itself never enter the queue. Without this rule an
+// offline machine appends one flush-failure event per flush attempt, forever,
+// and the queue that exists to be drained fills itself.
+function isSelfReferential(event) {
+  return typeof event.event === 'string' && event.event.startsWith('telemetry.');
+}
+
+// Same gate as the file sink: no mobile-automator/ workspace, no artifacts.
+// mauto runs from wherever a user is standing, so creating this tree as a
+// side effect of logging would litter unrelated repos with a directory that
+// has no .gitignore in it.
+function allowed(projectRoot, env, fs) {
+  if (env && env.MAUTO_LOG_DIR) return true;
+  return fs.existsSync(workspaceDir(projectRoot));
+}
+
+function write(event, { projectRoot, env = process.env, fs = realFs } = {}) {
+  try {
+    if (isSelfReferential(event)) return;
+    if (!allowed(projectRoot, env, fs)) return;
+
+    const target = spoolPath(projectRoot, env);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+
+    // One stat before the append. At the cap we drop the NEW line rather than
+    // evicting an old one: eviction means read-filter-rewrite on the hot path
+    // of every verb, and the older records are the ones already queued for
+    // delivery — evicting them loses more history than refusing one new line.
+    try {
+      if (fs.statSync(target).size >= SPOOL_MAX_BYTES) return;
+    } catch (_) {
+      /* no spool yet — proceed */
+    }
+
+    const payload = telemetryPayload({ ...event, msg_id: newMessageId() });
+    fs.appendFileSync(target, JSON.stringify(payload) + '\n');
+  } catch (_) {
+    // Observability is never load-bearing. Losing a telemetry line is always
+    // preferable to failing the verb the user actually asked for.
+  }
+}
+
+// Monotonic per-process claim stamp, seeded from wall-clock so listClaimed's
+// oldest-first sort (which parses this suffix as a number) still reflects
+// real ordering across process restarts. Date.now() ALONE is not unique
+// enough: a flush that finds a leftover batch and then claims a fresh one
+// back-to-back can complete both within the same millisecond, and a rename
+// onto an already-existing target SILENTLY REPLACES it on POSIX — destroying
+// whichever claim got there first rather than erroring. Falling back to
+// `lastClaimStamp + 1` when the clock hasn't advanced guarantees the target
+// is always new within this process; a different process can never collide
+// regardless, because its pid is already part of the filename.
+let lastClaimStamp = 0;
+function nextClaimStamp() {
+  const now = Date.now();
+  lastClaimStamp = now > lastClaimStamp ? now : lastClaimStamp + 1;
+  return lastClaimStamp;
+}
+
+// Atomic hand-off from "being appended to" to "being sent".
+//
+// renameSync within a directory is atomic, and it loses nothing: appendFileSync
+// opens by path and closes per call, so a verb that opened its fd BEFORE the
+// rename writes into the claimed inode (that line ships with this batch) and a
+// verb that opens AFTER creates a fresh spool. There is no window in which a
+// line lands nowhere, and no truncate that could clobber a concurrent writer.
+function claim({ projectRoot, env = process.env, fs = realFs } = {}) {
+  const source = spoolPath(projectRoot, env);
+  const target = `${source}${CLAIM_SUFFIX}.${process.pid}.${nextClaimStamp()}`;
+  try {
+    fs.renameSync(source, target);
+    return target;
+  } catch (_) {
+    return null; // nothing spooled, or another flusher beat us to it
+  }
+}
+
+// Oldest first: the suffix carries pid then epoch-ms, so a lexical sort on the
+// trailing number would misorder across digit widths. Sort on the parsed stamp.
+function listClaimed({ projectRoot, env = process.env, fs = realFs } = {}) {
+  const dir = path.dirname(spoolPath(projectRoot, env));
+  const prefix = `${path.basename(spoolPath(projectRoot, env))}${CLAIM_SUFFIX}.`;
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  return names
+    .filter((n) => n.startsWith(prefix))
+    .map((n) => ({ name: n, stamp: Number(n.slice(n.lastIndexOf('.') + 1)) || 0 }))
+    .sort((a, b) => a.stamp - b.stamp)
+    .map((e) => path.join(dir, e.name));
+}
+
+// One bad line must not discard the batch around it. A torn final write (the
+// daemon SIGKILLed mid-append) is exactly one unparseable line.
+function readBatch(file, { fs = realFs } = {}) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (_) {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch (_) {
+      /* skip */
+    }
+  }
+  return out;
+}
+
+// What `mauto telemetry status` shows a user deciding whether to opt in.
+function stats({ projectRoot, env = process.env, fs = realFs } = {}) {
+  const target = spoolPath(projectRoot, env);
+  let bytes = 0;
+  let events = 0;
+  try {
+    bytes = fs.statSync(target).size;
+    events = readBatch(target, { fs }).length;
+  } catch (_) {
+    /* nothing spooled */
+  }
+  return {
+    path: target,
+    bytes,
+    events,
+    pending_batches: listClaimed({ projectRoot, env, fs }).length,
+  };
+}
+
+module.exports = {
+  SPOOL_MAX_BYTES,
+  SPOOL_LEVEL,
+  CLAIM_SUFFIX,
+  newMessageId,
+  write,
+  claim,
+  listClaimed,
+  readBatch,
+  stats,
+};

package/src/observe/telemetry.js

@@ -0,0 +1,143 @@
+'use strict';
+
+// Resolves whether telemetry is on, and owns the consent copy.
+//
+// Precedence, in this order and for these reasons:
+//
+//   1. MAUTO_TELEMETRY=0   a kill switch must win over everything, and it is
+//                          checked FIRST so it costs zero filesystem calls.
+//   2. DO_NOT_TRACK=1      the cross-tool convention, honoured.
+//   3. telemetry.enabled   the user's durable, explicit opt-in.
+//   4. a real token         a placeholder build cannot post even if enabled.
+//
+// MAUTO_TELEMETRY=1 deliberately does NOT enable. An off-switch is safe to
+// honour from the environment; an on-switch is a way to turn collection on for
+// a machine — a CI image, a shared shell profile, an inherited Dockerfile —
+// whose owner never consented. On-switches live in a file the project owner
+// edits.
+
+const configManager = require('../config/manager');
+const { EVENT_FIELDS, NEVER_SENDS } = require('./event');
+const { hasToken } = require('./transport');
+
+const REASONS = Object.freeze([
+  'kill_switch',
+  'do_not_track',
+  'not_configured',
+  'no_token',
+  'enabled',
+]);
+
+// The single home for the consent copy. `mauto telemetry status`, the setup
+// envelope and docs/reference/telemetry.md all render THIS string; three
+// hand-written copies would drift, and the one that drifts is the one a user
+// reads before deciding.
+//
+// It is a NOTICE, never a prompt. mauto verbs are invoked by an agent, not
+// typed by a human, so there is nobody at the keyboard to answer a question —
+// and an agent answering a consent question on a human's behalf is worse than
+// not asking.
+const CONSENT_NOTICE = [
+  'Telemetry is off by default and nothing is sent until you turn it on.',
+  '',
+  'When enabled, mauto records anonymous usage counts — which verb ran, whether',
+  'it succeeded, how long it took, and the mobile-mcp primitive behind it. It',
+  'sends no free text of any kind: no scenario ids, app package names, device',
+  'serials, element labels, typed input or filesystem paths. There is no',
+  'per-machine identifier; every event is anonymous and uncorrelated.',
+  '',
+  'Run `mauto telemetry status` to see the exact field list, read from the same',
+  'catalog the uploader uses. Run `mauto telemetry enable` to turn it on, or set',
+  'MAUTO_TELEMETRY=0 (or DO_NOT_TRACK=1) to force it off everywhere.',
+].join('\n');
+
+function envKillSwitch(env = process.env) {
+  if (String((env && env.MAUTO_TELEMETRY) || '') === '0') return 'kill_switch';
+  const dnt = String((env && env.DO_NOT_TRACK) || '').toLowerCase();
+  if (dnt === '1' || dnt === 'true') return 'do_not_track';
+  return null;
+}
+
+function resolveTelemetry({ env = process.env, config = null } = {}) {
+  const killed = envKillSwitch(env);
+  if (killed) return { enabled: false, reason: killed };
+  // A LITERAL true. A truthy string ("true", "1") means someone hand-edited
+  // the file into a shape `mauto config set` would never produce, and guessing
+  // at intent is not something a consent flag gets to do.
+  const configured = Boolean(config && config.telemetry && config.telemetry.enabled === true);
+  if (!configured) return { enabled: false, reason: 'not_configured' };
+  if (!hasToken(env)) return { enabled: false, reason: 'no_token' };
+  return { enabled: true, reason: 'enabled' };
+}
+
+// Memoised per project root. resolveLevels() is re-derived per record() call
+// because it reads only env; this one reads config.json, and a file read per
+// event is not acceptable on a path that runs on every verb.
+//
+// The pinning consequence is the same one slice 2 documented for the daemon's
+// MAUTO_LOG_LEVEL: for a one-shot verb this is once per process (correct by
+// construction), and for the daemon it is once per daemon lifetime. Editing
+// config.json while a daemon is running does not change that daemon's
+// behaviour; `mauto session end` then re-run is the remedy.
+const memo = new Map();
+
+function decideForProject(projectRoot, env = process.env) {
+  const key = String(projectRoot);
+  if (memo.has(key)) return memo.get(key);
+  let decision;
+  try {
+    // Checked before the read, not after: a kill switch must cost nothing.
+    decision = envKillSwitch(env)
+      ? resolveTelemetry({ env, config: null })
+      : resolveTelemetry({ env, config: configManager.load(projectRoot) });
+  } catch (_) {
+    // A corrupt or unreadable config resolves OFF. Failing closed is the only
+    // acceptable direction for a consent flag.
+    decision = { enabled: false, reason: 'not_configured' };
+  }
+  memo.set(key, decision);
+  return decision;
+}
+
+// A write through the module that owns the decision also invalidates it, so no
+// caller can forget a pairing it never sees. The delete is surgical — the
+// affected root's key only; other roots' memoised decisions survive.
+//
+// `config set` cannot route through this: its raw CLI strings need coerceValue
+// first, so that write stays in cli.js. That path does not invalidate, and
+// stays harmless for as long as nothing seeds the memo before a handler's own
+// report in a one-shot verb process.
+function setEnabled(projectRoot, value) {
+  configManager.set(projectRoot, 'telemetry.enabled', value);
+  memo.delete(String(projectRoot));
+}
+
+// Test isolation only: production writes go through setEnabled above. Kept
+// because a test process is long-lived where a verb process is not, and one
+// memo spans every workspace the suite builds.
+function _resetMemo() {
+  memo.clear();
+}
+
+// The disclosure is COMPUTED from the catalog, never restated. That is what
+// makes `mauto telemetry status` and docs/reference/telemetry.md incapable of
+// lying: they render the same source of truth telemetryPayload() iterates.
+function sentFields() {
+  return Object.keys(EVENT_FIELDS).filter((k) => EVENT_FIELDS[k].sends);
+}
+
+function neverSentFields() {
+  return [...NEVER_SENDS];
+}
+
+module.exports = {
+  CONSENT_NOTICE,
+  REASONS,
+  envKillSwitch,
+  resolveTelemetry,
+  decideForProject,
+  setEnabled,
+  _resetMemo,
+  sentFields,
+  neverSentFields,
+};