mobile-automator 0.23.8

package/src/mcp/prompts.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// MCP prompt handlers for the `mauto mcp` server.
+//
+// The workflows are exposed as USER-CONTROLLED MCP prompts (not tools — the
+// device stays behind CLI verbs). Each prompt injects the version-matched
+// `mauto guide <topic>` content as a single user message, so an agent that
+// selects e.g. the `generate` prompt receives the exact same guidance a human
+// would get from `mauto guide generate`.
+//
+// Naming scheme: prompts are named by the BARE topic (`generate`, `execute`,
+// `setup`) — identical to the `mauto guide <topic>` argument, so the
+// two surfaces stay one-to-one and self-documenting.
+
+const guideEmitter = require('../guide/emitter');
+const configManager = require('../config/manager');
+
+const PROMPT_TOPICS = ['generate', 'execute', 'setup'];
+
+const DESCRIPTIONS = {
+  generate: 'Author a mobile test scenario by exploring the app with mauto verbs.',
+  execute: 'Replay a scenario step-by-step and record the run results.',
+  setup: 'Initialise the mobile-automator workspace and config.',
+};
+
+// Build the { listPrompts, getPrompt } pair. emitGuide + config are injectable
+// so the handlers can be unit-tested without touching the real guide files.
+function buildPromptHandlers({ projectRoot, emitGuide, config = configManager } = {}) {
+  const emit = emitGuide || guideEmitter.emitGuide;
+
+  function listPrompts() {
+    return PROMPT_TOPICS.map((topic) => ({
+      name: topic,
+      description: DESCRIPTIONS[topic],
+      arguments: [],
+    }));
+  }
+
+  function getPrompt(name) {
+    if (!PROMPT_TOPICS.includes(name)) {
+      throw new Error(`unknown prompt: ${name}`);
+    }
+    const cfg = config.load(projectRoot);
+    const mode = config.resolveMode(cfg);
+    const text = emit(name, { mode, projectRoot });
+    return {
+      description: DESCRIPTIONS[name],
+      messages: [{ role: 'user', content: { type: 'text', text } }],
+    };
+  }
+
+  return { listPrompts, getPrompt };
+}
+
+module.exports = { buildPromptHandlers, PROMPT_TOPICS };

package/src/mcp/server.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// `mauto mcp` — the MCP prompts server.
+//
+// Advertises the PROMPTS capability only. The four mobile-QA workflows are
+// surfaced as user-controlled prompts (see src/mcp/prompts.js); the device is
+// NOT exposed as MCP tools — it stays behind the `mauto` CLI verbs by design.
+//
+// The SDK exports CJS entry points under ./<sub>; the exact paths were
+// confirmed via require.resolve at build time:
+//   @modelcontextprotocol/sdk/server/index.js   -> Server
+//   @modelcontextprotocol/sdk/server/stdio.js   -> StdioServerTransport
+//   @modelcontextprotocol/sdk/types.js          -> ListPromptsRequestSchema, GetPromptRequestSchema
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const {
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+
+const { buildPromptHandlers } = require('./prompts');
+
+// Construct the Server, register the prompt request handlers, but DO NOT
+// connect a transport — separated so it can be exercised in tests without
+// hijacking stdio.
+function buildServer({ projectRoot } = {}) {
+  const handlers = buildPromptHandlers({ projectRoot });
+
+  const server = new Server(
+    { name: 'mauto', version: require('../../package.json').version },
+    { capabilities: { prompts: {} } }
+  );
+
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: handlers.listPrompts(),
+  }));
+
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    return handlers.getPrompt(request.params.name);
+  });
+
+  return { server, handlers };
+}
+
+// Long-lived: connect the stdio transport and keep serving. Never called in
+// the test suite (it would seize stdio).
+async function runServer({ projectRoot } = {}) {
+  const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+  const { server } = buildServer({ projectRoot });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+
+module.exports = { runServer, buildServer };

package/src/memory/entries.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { HEADERS } = require('./paths');
+
+// Pure model for the agent-authored memory files (app-knowledge.md,
+// preferences.md): a flat list of `- [YYYY-MM-DD][asserted] <text>` bullets
+// under a `# Header`. No I/O here. `[asserted]` marks agent-claimed facts the
+// reader should verify, distinct from run-history's `[observed]`.
+
+const MAX_ENTRY_LEN = 500;
+const ENTRY_RE = /^-\s+\[(\d{4}-\d{2}-\d{2})\]\[asserted\]\s+(.*)$/;
+
+function sanitizeEntryText(raw) {
+  return String(raw == null ? '' : raw)
+    .replace(/[\u0000-\u001F\u007F]+/g, ' ') // control chars / newlines / tabs -> space
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function validateEntryText(raw) {
+  const value = sanitizeEntryText(raw);
+  if (!value) return { ok: false, reason: 'empty' };
+  if (value.length > MAX_ENTRY_LEN) return { ok: false, reason: 'too_long' };
+  if (value.includes('{{')) return { ok: false, reason: 'placeholder' };
+  return { ok: true, value };
+}
+
+function parseEntries(md) {
+  const out = [];
+  if (!md) return out;
+  for (const line of md.split(/\r?\n/)) {
+    const m = line.match(ENTRY_RE);
+    if (m) out.push({ date: m[1], text: m[2] });
+  }
+  return out;
+}
+
+function renderEntries(kind, entries) {
+  const out = [
+    HEADERS[kind] || `# ${kind}`,
+    "<!-- Managed by `mauto memory`. Edit an entry's text or delete whole bullets freely;",
+    '     other lines are not preserved on the next write. [asserted] = agent-claimed; verify. -->',
+    '',
+  ];
+  for (const e of entries) out.push(`- [${e.date}][asserted] ${e.text}`);
+  return out.join('\n').replace(/\n+$/, '\n');
+}
+
+function hasText(entries, text) {
+  return entries.some((e) => e.text === text);
+}
+
+module.exports = {
+  MAX_ENTRY_LEN,
+  ENTRY_RE,
+  sanitizeEntryText,
+  validateEntryText,
+  parseEntries,
+  renderEntries,
+  hasText,
+};

package/src/memory/history.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// Pure model for run-history.md — a rolling per-scenario aggregate. Bounded by
+// scenario count (not run count): each scenario keeps its last MAX_RUNS pass/fail
+// letters and last MAX_NOTES observation bullets. No I/O here.
+
+const MAX_RUNS = 5;
+const MAX_NOTES = 10;
+
+const HEADER = '# Run History';
+const HEADER_COMMENT =
+  '<!-- Managed by `mauto memory`. Auto-harvested on `result finalize`. -->';
+
+// `## <scenarioId>  (last N runs: P F ...)`  — scenarioId is everything before
+// the two-space gap that precedes the "(last".
+const HEADING_RE = /^##\s+(.+?)\s+\(last \d+ runs:\s*([^)]*)\)\s*$/;
+const NOTE_RE = /^-\s+\[(\d{4}-\d{2}-\d{2})\]\[observed\]\s+(.*)$/;
+
+function emptyModel() {
+  return { order: [], byScenario: {} };
+}
+
+function ensure(model, scenarioId) {
+  if (!model.byScenario[scenarioId]) {
+    model.byScenario[scenarioId] = { runs: [], notes: [] };
+    model.order.push(scenarioId);
+  }
+  return model.byScenario[scenarioId];
+}
+
+function recordInModel(model, { scenarioId, statusLetter, notes = [] }) {
+  const entry = ensure(model, scenarioId);
+  entry.runs.push(statusLetter);
+  if (entry.runs.length > MAX_RUNS) entry.runs = entry.runs.slice(-MAX_RUNS);
+  for (const n of notes) entry.notes.push(n);
+  if (entry.notes.length > MAX_NOTES) entry.notes = entry.notes.slice(-MAX_NOTES);
+  return model;
+}
+
+function parseRunHistory(md) {
+  const model = emptyModel();
+  if (!md) return model;
+  let current = null;
+  for (const line of md.split(/\r?\n/)) {
+    const h = line.match(HEADING_RE);
+    if (h) {
+      const id = h[1].trim();
+      current = ensure(model, id);
+      const letters = h[2].trim();
+      current.runs = letters ? letters.split(/\s+/).filter(Boolean) : [];
+      continue;
+    }
+    const n = line.match(NOTE_RE);
+    if (n && current) {
+      current.notes.push({ date: n[1], text: n[2] });
+    }
+  }
+  return model;
+}
+
+function renderRunHistory(model) {
+  const out = [HEADER, HEADER_COMMENT, ''];
+  for (const id of model.order) {
+    const e = model.byScenario[id];
+    out.push(`## ${id}  (last ${MAX_RUNS} runs: ${e.runs.join(' ')})`);
+    for (const note of e.notes) {
+      out.push(`- [${note.date}][observed] ${note.text}`);
+    }
+    out.push('');
+  }
+  return out.join('\n').replace(/\n+$/, '\n');
+}
+
+function countEntries(model) {
+  return model.order.reduce((sum, id) => sum + model.byScenario[id].notes.length, 0);
+}
+
+module.exports = {
+  MAX_RUNS,
+  MAX_NOTES,
+  emptyModel,
+  parseRunHistory,
+  renderRunHistory,
+  recordInModel,
+  countEntries,
+};

package/src/memory/lock.js

@@ -0,0 +1,5 @@
+'use strict';
+
+// Re-export shim: the canonical advisory lock now lives in src/util/lock.js.
+// Kept so existing importers of src/memory/lock keep working.
+module.exports = require('../util/lock');

package/src/memory/paths.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const path = require('path');
+
+// Canonical on-disk names for the three memory files. Keys are the stable
+// `--kind` identifiers used across verbs; values are the markdown filenames.
+const FILES = {
+  'run-history': 'run-history.md',
+  'app-knowledge': 'app-knowledge.md',
+  preferences: 'preferences.md',
+};
+
+// The stable `--kind` identifiers, derived from FILES so there is a single
+// source of truth for "which memory kinds exist".
+const KINDS = Object.keys(FILES);
+
+// The two hand-authorable kinds. `run-history` is machine-owned (auto-harvested
+// on `result finalize`) and is NOT a valid `memory add`/`forget` target.
+const AGENT_KINDS = ['app-knowledge', 'preferences'];
+
+// Markdown headers per kind, colocated with FILES/KINDS since they're the
+// same per-kind metadata.
+const HEADERS = {
+  'run-history': '# Run History',
+  'app-knowledge': '# App Knowledge',
+  preferences: '# Preferences',
+};
+
+function memoryDir(projectRoot) {
+  return path.join(projectRoot, 'mobile-automator', 'memory');
+}
+
+function memoryFile(projectRoot, name) {
+  return path.join(memoryDir(projectRoot), FILES[name] || name);
+}
+
+function sessionDir(projectRoot) {
+  return path.join(projectRoot, 'mobile-automator', '.session');
+}
+
+// The advisory lock guarding read-modify-write of the shared memory files.
+// Lives in .session/ (already gitignored) alongside the device-session state.
+function lockPath(projectRoot) {
+  return path.join(sessionDir(projectRoot), 'memory.lock');
+}
+
+module.exports = { memoryDir, memoryFile, sessionDir, lockPath, FILES, KINDS, AGENT_KINDS, HEADERS };

package/src/memory/store.js

@@ -0,0 +1,230 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { memoryFile, lockPath, KINDS, HEADERS } = require('./paths');
+const { withLock } = require('../util/lock');
+const { parseRunHistory, renderRunHistory, recordInModel, countEntries } = require('./history');
+const { atomicWrite } = require('../util/atomic');
+const { parseEntries, renderEntries, hasText } = require('./entries');
+
+// Cross-session memory store. Mirrors ResultStore's one-shot-process,
+// load-mutate-atomic-write shape, but the memory files are SHARED across runs
+// (not keyed per-runId), so every read-modify-write goes through an advisory
+// lock (see ./lock.js) to avoid lost updates.
+
+function todayISO() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function statusLetter(status) {
+  return status === 'passed' || status === 'pass' ? 'P' : 'F';
+}
+
+// Fold a run's typed observations into dated note lines for the aggregate.
+function notesFromResult(result) {
+  const date = todayISO();
+  return (result.observations || []).map((o) => {
+    const where = o.step_id ? ` (${o.step_id})` : '';
+    return { date, text: `${o.type}${where}: ${o.message}` };
+  });
+}
+
+const DEFAULT_CAP = 8000;
+
+// Filter a run-history markdown body down to a single scenario's `##` section.
+// Keeps the top-of-file header lines (everything before the first `##`
+// heading) and, if present, the matching scenario's heading + its note lines;
+// drops every other scenario's section.
+//
+// This is DELIBERATELY a string-level line filter, not a re-serialization
+// from the parsed history model, mirroring the raw-preserving unfiltered
+// render path above. Re-serializing from the model would silently drop any
+// hand-edited line that doesn't fit the model's note shape — the files are
+// designed to be hand-editable, so that data loss would be a behavior
+// change, not a simplification. Do not "clean this up" into a model-based
+// render without re-checking that invariant.
+function filterScenario(md, scenario) {
+  const lines = md.split('\n');
+  const kept = [];
+  let sawHeading = false;
+  let inTarget = false;
+  // `scenario` is user-supplied (the CLI's --scenario flag); escape regex
+  // metacharacters so a value like "a(b" filters to zero matches instead of
+  // throwing an uncaught SyntaxError out of this read-only render path.
+  const safe = scenario.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const headingRe = new RegExp(`^##\\s+${safe}\\s+\\(last`);
+  for (const line of lines) {
+    const isHeading = /^##\s+/.test(line);
+    if (isHeading) {
+      sawHeading = true;
+      inTarget = headingRe.test(line);
+      if (!inTarget) continue;
+      kept.push(line);
+      continue;
+    }
+    if (!sawHeading) {
+      // top-of-file header lines, before any scenario heading
+      kept.push(line);
+      continue;
+    }
+    if (inTarget) kept.push(line);
+  }
+  return kept.join('\n');
+}
+
+// Counts bullets for any file, reusing the history model for run-history.
+function countEntriesFor(name, raw) {
+  if (!raw) return 0;
+  if (name === 'run-history') return countEntries(parseRunHistory(raw));
+  // app-knowledge / preferences: one bullet per entry.
+  return raw.split('\n').filter((l) => /^-\s+\[/.test(l)).length;
+}
+
+class MemoryStore {
+  constructor({ projectRoot } = {}) {
+    if (!projectRoot) throw new Error('MemoryStore requires a projectRoot');
+    this.projectRoot = projectRoot;
+    this.warnings = [];
+  }
+
+  _file(name) {
+    return memoryFile(this.projectRoot, name);
+  }
+
+  // Read a memory file's raw text, or '' if absent. A read failure other than
+  // ENOENT is preserved as a sidecar + warning (defensive parity with
+  // ResultStore) and treated as empty so a write never clobbers unread bytes.
+  _readRaw(name) {
+    const file = this._file(name);
+    try {
+      return fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') return '';
+      return this._preserveCorrupt(file, e);
+    }
+  }
+
+  _preserveCorrupt(file, err) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const sidecar = `${file}.corrupt.${ts}`;
+    let preserved = false;
+    try {
+      fs.renameSync(file, sidecar);
+      preserved = true;
+    } catch (_) {
+      /* best effort */
+    }
+    const where = preserved ? `preserved as ${path.basename(sidecar)}` : 'COULD NOT be preserved';
+    this.warnings.push(
+      `memory file ${file} was unreadable (${err.message}); ${where} and a fresh file was started`
+    );
+    return '';
+  }
+
+  // Delegates to the shared util (see src/util/atomic.js).
+  _atomicWrite(file, contents) {
+    atomicWrite(file, contents);
+  }
+
+  // Acquire the lock, read this kind's raw bytes, run the edit, and write ONLY when
+  // the edit produced new contents. Single owner of the "under lock + write-when-changed"
+  // invariant for every memory mutation.
+  _editUnderLock(kind, edit) {
+    return withLock(lockPath(this.projectRoot), () => {
+      const { contents, result } = edit(this._readRaw(kind));
+      if (contents != null) this._atomicWrite(this._file(kind), contents);
+      return result;
+    });
+  }
+
+  // Auto-harvest: fold a finalized result into the rolling run-history aggregate.
+  recordRun(result = {}) {
+    const scenarioId = result.scenario_id || 'unknown';
+    return this._editUnderLock('run-history', (raw) => {
+      const model = parseRunHistory(raw);
+      recordInModel(model, {
+        scenarioId,
+        statusLetter: statusLetter(result.status),
+        notes: notesFromResult(result),
+      });
+      return {
+        contents: renderRunHistory(model),
+        result: { scenarioId, runs: model.byScenario[scenarioId].runs.slice() },
+      };
+    });
+  }
+
+  // Agent-authored: append a durable [asserted] fact/preference under the lock.
+  // Exact-match de-dupe (same text already present → skip). Assumes `text` is
+  // already validated/sanitized by the verb handler.
+  add(kind, text) {
+    return this._editUnderLock(kind, (raw) => {
+      const entries = parseEntries(raw);
+      if (hasText(entries, text)) {
+        return { contents: undefined, result: { kind, added: false, deduped: true } };
+      }
+      entries.push({ date: todayISO(), text });
+      return { contents: renderEntries(kind, entries), result: { kind, added: true, deduped: false } };
+    });
+  }
+
+  // The correction path: remove entries whose text contains `match`.
+  forget(kind, match) {
+    return this._editUnderLock(kind, (raw) => {
+      const entries = parseEntries(raw);
+      const kept = entries.filter((e) => !e.text.includes(match));
+      const removed = entries.length - kept.length;
+      return { contents: removed > 0 ? renderEntries(kind, kept) : null, result: { kind, removed } };
+    });
+  }
+
+  // Render the raw markdown `mauto memory show` emits: a one-line summary
+  // comment (per-file entry counts + last-updated date) followed by the
+  // requested file bodies. Read-only — no lock needed.
+  render({ kind, scenario, cap = DEFAULT_CAP } = {}) {
+    const names = kind ? [kind] : KINDS;
+    const summary = [];
+    const sections = [];
+
+    for (const name of KINDS) {
+      const raw = this._safeRead(name);
+      const count = countEntriesFor(name, raw);
+      const updated = this._mtimeDate(name);
+      summary.push(`${name}: ${count} entrie(s)${updated ? `, updated ${updated}` : ''}`);
+    }
+
+    for (const name of names) {
+      let body = this._safeRead(name);
+      if (!body) body = `${HEADERS[name] || `# ${name}`}\n(no entries yet)\n`;
+      if (name === 'run-history' && scenario) body = filterScenario(body, scenario);
+      sections.push(body.trim());
+    }
+
+    let out = `<!-- mauto memory · ${summary.join(' · ')} -->\n\n${sections.join('\n\n')}\n`;
+    if (out.length > cap) {
+      out = `${out.slice(0, cap)}\n… (truncated at ${cap} chars — narrow with --kind/--scenario)\n`;
+    }
+    return out;
+  }
+
+  // Read without the corruption sidecar side effect (render is read-only).
+  _safeRead(name) {
+    try {
+      return fs.readFileSync(this._file(name), 'utf8');
+    } catch (_) {
+      return '';
+    }
+  }
+
+  _mtimeDate(name) {
+    try {
+      return fs.statSync(this._file(name)).mtime.toISOString().slice(0, 10);
+    } catch (_) {
+      return null;
+    }
+  }
+}
+
+module.exports = { MemoryStore, todayISO, statusLetter };

package/src/output/envelope.js

@@ -0,0 +1,106 @@
+'use strict';
+
+// Stable contract between the `mauto` CLI and any calling agent.
+// Every command prints exactly one envelope on stdout.
+
+const SCHEMA_VERSION = '2.1';
+
+const EXIT = {
+  OK: 0,
+  DEVICE: 2,
+  INVALID_INPUT: 3,
+  TARGET_NOT_FOUND: 4,
+  // Filesystem / workspace problem (perms, missing path, read-only FS, no
+  // disk) — an environment fault the caller can fix, distinct from exit 1
+  // ("the CLI itself broke"). Kept separate so agents/CI can branch on it.
+  ENVIRONMENT: 5,
+  CANCEL: 130,
+};
+
+// error.kind -> process exit code. `internal` (and anything unknown) -> 1.
+const KIND_TO_CODE = {
+  ok: EXIT.OK,
+  device: EXIT.DEVICE,
+  // A daemon per-call timeout is a device-class failure (the action may have
+  // partially executed on the device) — exit 2 keeps the contract unchanged for
+  // callers branching on 2, while the envelope's error.kind stays 'timeout' so
+  // agents can distinguish "no response" from a hard device error.
+  timeout: EXIT.DEVICE,
+  invalid_input: EXIT.INVALID_INPUT,
+  target_not_found: EXIT.TARGET_NOT_FOUND,
+  environment: EXIT.ENVIRONMENT,
+  cancel: EXIT.CANCEL,
+  internal: 1,
+  // `init --agent all` partial failure: some hosts wired, some failed. Non-zero
+  // so callers/CI treat it as a failure; the envelope's data.agents[] is honest.
+  partial: 1,
+};
+
+function ok(data, hint = null) {
+  const env = { ok: true, data, schema_version: SCHEMA_VERSION };
+  // A success can still carry an advisory hint (e.g. recovered corruption).
+  // The key is only present when there is something to say, so the common
+  // case stays the bare {ok,data,schema_version} envelope.
+  if (hint) env.hint = hint;
+  return env;
+}
+
+function fail(kind, message, hint = null, data = undefined) {
+  const env = {
+    ok: false,
+    error: { kind, message },
+    hint,
+    schema_version: SCHEMA_VERSION,
+  };
+  // Some failures carry actionable structured detail (e.g. a per-agent
+  // ok/failed map for `init --agent all`); include `data` only when given so
+  // the common fail shape is unchanged.
+  if (data !== undefined) env.data = data;
+  return env;
+}
+
+function exitCodeFor(kind) {
+  if (Object.prototype.hasOwnProperty.call(KIND_TO_CODE, kind)) {
+    return KIND_TO_CODE[kind];
+  }
+  return 1;
+}
+
+function render(envelope, { human = false } = {}) {
+  if (!human) {
+    return JSON.stringify(envelope);
+  }
+
+  if (envelope.ok) {
+    const data = envelope.data;
+    let line;
+    if (Array.isArray(data)) {
+      line = `ok: ${data.length} item(s)`;
+    } else if (data && typeof data === 'object') {
+      const keys = Object.keys(data);
+      line = `ok: ${keys.length ? keys.join(', ') : '(no data)'}`;
+    } else {
+      line = `ok: ${String(data)}`;
+    }
+    if (envelope.hint) {
+      line += `\nhint: ${envelope.hint}`;
+    }
+    return line;
+  }
+
+  const { kind, message } = envelope.error || {};
+  let out = `error [${kind}]: ${message}`;
+  if (envelope.hint) {
+    out += `\nhint: ${envelope.hint}`;
+  }
+  return out;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  EXIT,
+  ok,
+  fail,
+  exitCodeFor,
+  render,
+};