mobile-automator 0.23.8

package/src/result/capability-catalog.js

@@ -0,0 +1,144 @@
+'use strict';
+
+// Single source of truth binding every FACT a result file can carry to the
+// three things that must agree and never drift: the result schema (does the
+// file have a home for it), the ResultStore (does a method write it), and the
+// `mauto result` verb surface (can an agent actually supply it).
+//
+// tests/lint/result-coverage.test.js derives its assertions from this map, so
+// a capability that loses its CLI reach fails the build instead of silently
+// producing an empty field — which is exactly how #140 went unnoticed. This
+// mirrors src/device/action-catalog.js, whose guard (#117) covers device
+// ACTIONS and has no jurisdiction over the result verbs.
+//
+// `writeCheck` declares how the guard proves the ResultStore method actually
+// writes the field, because a plain `store.js.includes(writes)` check is only
+// trustworthy when `writes` names a token unique to that write site:
+//   'substring'  — `writes` is a call/assignment-shaped token (e.g.
+//                  `this._assertions.push(entry)`) that occurs nowhere else in
+//                  store.js, so deleting the real write makes it disappear.
+//   'behavioral' — the field is a bare scalar (e.g. `screenshot`) that also
+//                  appears as a destructured parameter name or elsewhere in
+//                  store.js, so no substring can distinguish "written" from
+//                  "merely accepted". These are instead proven by a live
+//                  ResultStore run in tests/lint/result-coverage.test.js.
+const RESULT_CAPABILITIES = {
+  screenshot: {
+    verb: 'add-step',
+    flags: ['--screenshot'],
+    store: 'addStep',
+    writes: 'screenshot',
+    writeCheck: 'behavioral',
+    schemaPointer: '/properties/steps_executed/items/properties/screenshot',
+  },
+  error_message: {
+    verb: 'add-step',
+    flags: ['--error-message'],
+    store: 'addStep',
+    writes: 'error_message',
+    writeCheck: 'behavioral',
+    schemaPointer: '/properties/steps_executed/items/properties/error_message',
+  },
+  step_status: {
+    verb: 'add-step',
+    flags: ['--status'],
+    store: 'addStep',
+    writes: 'status: normalized',
+    writeCheck: 'substring',
+    schemaPointer: '/properties/steps_executed/items/properties/status',
+  },
+  flakiness_observation: {
+    verb: 'add-step',
+    flags: ['--attempts'],
+    store: 'addStep',
+    // `--attempts` carries no field of its own; it drives the retry-derived
+    // flakiness observation store.js pushes onto the run-level `observations`
+    // array (see ResultStore#addStep), so it is bound to that schema node.
+    writes: "type: 'flakiness'",
+    writeCheck: 'substring',
+    schemaPointer: '/properties/observations',
+  },
+  observation: {
+    verb: 'add-step',
+    flags: ['--observation'],
+    store: 'addObservation',
+    writes: 'this._observations.push(entry)',
+    writeCheck: 'substring',
+    schemaPointer: '/properties/observations',
+  },
+  captured_variable: {
+    verb: 'add-step',
+    flags: ['--capture'],
+    store: 'captureVariable',
+    writes: 'this._capturedVariables[name] = value',
+    writeCheck: 'substring',
+    schemaPointer: '/properties/captured_variables',
+  },
+  assertion_verdict: {
+    verb: 'add-assertion',
+    flags: ['--type', '--pass', '--assertion-id', '--message', '--expected', '--actual'],
+    store: 'addAssertion',
+    writes: 'this._assertions.push(entry)',
+    writeCheck: 'substring',
+    schemaPointer: '/properties/assertion_results',
+  },
+  run_status: {
+    verb: 'finalize',
+    flags: ['--status'],
+    store: 'finalize',
+    writes: 'status: resolvedStatus',
+    writeCheck: 'substring',
+    schemaPointer: '/properties/status',
+  },
+  duration: {
+    verb: 'finalize',
+    flags: ['--duration'],
+    store: 'finalize',
+    writes: 'duration_seconds: Number(durationSeconds) || 0',
+    writeCheck: 'substring',
+    schemaPointer: '/properties/duration_seconds',
+  },
+  run_metadata: {
+    verb: 'finalize',
+    flags: ['--app-version', '--device-model', '--api-level', '--environment'],
+    store: 'finalize',
+    writes: 'metadata',
+    writeCheck: 'behavioral',
+    schemaPointer: '/properties/metadata',
+  },
+  summary: {
+    verb: 'finalize',
+    flags: ['--summary'],
+    store: 'finalize',
+    writes: 'summary',
+    writeCheck: 'behavioral',
+    schemaPointer: '/properties/summary',
+  },
+};
+
+// Flags that identify WHICH run/step is being recorded, rather than carrying
+// a result fact of their own. Excluded from the no-orphan check. `--status`,
+// `--duration` and `--attempts` are deliberately NOT here — each carries a
+// fact of its own (step/run verdict, run duration, retry-derived flakiness)
+// and has its own RESULT_CAPABILITIES entry above.
+const IDENTITY_FLAGS = new Set([
+  '--run-id',
+  '--scenario-id',
+  '--step-id',
+]);
+
+// Top-level result-schema properties that legitimately have no capability
+// entry: no `mauto result` flag should ever set them directly. Each entry
+// names why, so growing this list always carries its own justification
+// instead of becoming a silent escape hatch from the completeness guard in
+// tests/lint/result-coverage.test.js.
+const NO_FLAG_ALLOWLIST = {
+  run_id: 'supplied via the --run-id identity flag on every result verb, not a capability-carried fact',
+  scenario_id: 'supplied via the --scenario-id identity flag, not a capability-carried fact',
+  schema_version: 'constant emitted by ResultStore (SCHEMA_VERSION); never agent-supplied',
+  total_assertions: 'derived by ResultStore.finalize by counting assertion_results; no independent flag by design',
+  passed_assertions: 'derived by ResultStore.finalize by counting assertion_results; no independent flag by design',
+  failed_assertions: 'derived by ResultStore.finalize by counting assertion_results; no independent flag by design',
+};
+
+module.exports = { RESULT_CAPABILITIES, IDENTITY_FLAGS, NO_FLAG_ALLOWLIST };

package/src/result/flags.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// Pure parsers for the composite `result` flags (#140). Kept free of
+// commander and the filesystem so the fiddly cases — a message that itself
+// contains a colon, a captured value that contains '=' — are unit-testable
+// in isolation. Each parser returns { value } or { error }; callers turn
+// `error` into a fail('invalid_input', …) envelope so an unknown observation
+// type is rejected loudly instead of being silently dropped.
+
+// Mirrors the enum at /properties/observations/items/properties/type in
+// src/schemas/result_schema.json. tests/lint/result-coverage.test.js asserts
+// the two never drift.
+const OBSERVATION_TYPES = ['regression', 'flakiness', 'state_context'];
+
+function parseObservation(spec) {
+  const raw = String(spec);
+  const idx = raw.indexOf(':');
+  if (idx === -1) {
+    return { error: `--observation "${raw}" must be <type>:<message>` };
+  }
+  const type = raw.slice(0, idx).trim();
+  // Split on the FIRST colon only: observation messages routinely contain
+  // colons ("dark mode: reference was light").
+  const message = raw.slice(idx + 1).trim();
+  if (!OBSERVATION_TYPES.includes(type)) {
+    return {
+      error: `unknown observation type "${type}" (expected ${OBSERVATION_TYPES.join(' | ')})`,
+    };
+  }
+  if (!message) return { error: `--observation "${raw}" has an empty message` };
+  return { value: { type, message } };
+}
+
+function parseCapture(spec) {
+  const raw = String(spec);
+  const idx = raw.indexOf('=');
+  if (idx === -1) return { error: `--capture "${raw}" must be <name>=<value>` };
+  const name = raw.slice(0, idx).trim();
+  // NOT trimmed and NOT rejected when empty: a captured field can legitimately
+  // be the empty string, and trimming would corrupt a captured value.
+  const value = raw.slice(idx + 1);
+  if (!name) return { error: `--capture "${raw}" has an empty variable name` };
+  return { value: { name, value } };
+}
+
+function parseBool(raw, flagName) {
+  if (raw === 'true') return { value: true };
+  if (raw === 'false') return { value: false };
+  return { error: `${flagName} must be "true" or "false" (got "${raw}")` };
+}
+
+module.exports = { OBSERVATION_TYPES, parseObservation, parseCapture, parseBool };

package/src/result/store.js

@@ -0,0 +1,273 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { atomicWrite } = require('../util/atomic');
+const { withLock } = require('../util/lock');
+const { OBSERVATION_TYPES } = require('./flags');
+
+// Incremental result accumulator that persists to
+//   <projectRoot>/mobile-automator/results/<runId>.json
+//
+// The CLI runs one-shot: each `result add-step` / `result finalize` invocation
+// is a fresh process. To support that, the store loads any existing in-progress
+// file for the run on construction and appends to it, so state survives across
+// invocations until finalize writes the schema-conformant result.
+
+const SCHEMA_VERSION = '2.0';
+
+function defaultMetadata(overrides = {}) {
+  return {
+    app_version: overrides.app_version || 'unknown',
+    device_model: overrides.device_model || 'unknown',
+    api_level: overrides.api_level || 'unknown',
+    environment: overrides.environment || 'unknown',
+    timestamp: overrides.timestamp || new Date().toISOString(),
+  };
+}
+
+// Normalize the caller-friendly status ('pass'/'fail') to the schema enums.
+function stepStatus(status) {
+  if (status === 'pass' || status === 'passed') return 'passed';
+  if (status === 'fail' || status === 'failed') return 'failed';
+  if (status === 'skipped' || status === 'skip') return 'skipped';
+  return 'error';
+}
+
+function assertionStatus(pass) {
+  return pass ? 'passed' : 'failed';
+}
+
+class ResultStore {
+  constructor({ runId, scenarioId, projectRoot, metadata } = {}) {
+    if (!runId) throw new Error('ResultStore requires a runId');
+    if (!projectRoot) throw new Error('ResultStore requires a projectRoot');
+
+    this.runId = runId;
+    this.scenarioId = scenarioId || null;
+    this.projectRoot = projectRoot;
+    this._metadataOverrides = metadata || {};
+
+    this._dir = path.join(projectRoot, 'mobile-automator', 'results');
+    this._file = path.join(this._dir, `${runId}.json`);
+    // Per-runId advisory lock guarding every read-modify-write mutator. Lives
+    // in the same directory as the result file, so the lock is scoped to this
+    // run only — different runs never contend on it.
+    this._lock = path.join(this._dir, `${runId}.lock`);
+
+    // Honest-corruption channel: any recovery the load performs is recorded
+    // here so the CLI can thread it into the envelope `hint`. Must exist
+    // before `_load()` runs.
+    this.warnings = [];
+
+    this._refreshFromDisk();
+  }
+
+  // Re-load the on-disk accumulator and refresh the in-memory fields. The
+  // constructor eager-loads once (read-only paths and back-compat), but every
+  // persisting mutator re-runs this UNDER the per-runId lock so it operates on
+  // fresh-from-disk state — never the possibly-stale constructor snapshot.
+  // Without this, two concurrent processes would both cache the same stale
+  // snapshot and serialize only their writes, so the last rename would win and
+  // the other's mutation would be silently lost.
+  _refreshFromDisk() {
+    const loaded = this._load();
+    this._steps = loaded.steps_executed || [];
+    this._assertions = loaded.assertion_results || [];
+    this._observations = loaded.observations || [];
+    this._capturedVariables = loaded.captured_variables || {};
+    if (!this.scenarioId && loaded.scenario_id) this.scenarioId = loaded.scenario_id;
+  }
+
+  // Load an existing in-progress (or finalized) file if present; else empty.
+  //
+  // A missing file (ENOENT) is the legitimate first step → empty accumulator.
+  // A file that exists but does not parse is a crash artifact: we MUST NOT
+  // silently treat it as empty (that would let the next write O_TRUNC-clobber
+  // every previously recorded step). Instead we preserve the bytes as a
+  // `.corrupt.<ts>` sidecar, record a structured warning (surfaced via the
+  // envelope `hint`), and start a fresh accumulator.
+  _load() {
+    let raw;
+    try {
+      raw = fs.readFileSync(this._file, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') return {};
+      // Unexpected read failure (perms, I/O) — surface it honestly rather
+      // than masquerading as an empty run.
+      throw e;
+    }
+    try {
+      return JSON.parse(raw);
+    } catch (e) {
+      return this._preserveCorrupt(raw, e);
+    }
+  }
+
+  // Move a corrupt result file aside so its bytes are never lost, record a
+  // structured warning, and return an empty accumulator. The warning is the
+  // single source of truth for the recovery — the CLI threads `store.warnings`
+  // into the envelope `hint` (machine) which `render({human:true})` also shows
+  // (human), so the model stays print-free and trivially unit-testable. Sidecar
+  // write failures are themselves surfaced as warnings rather than aborting.
+  _preserveCorrupt(raw, err) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const sidecar = `${this._file}.corrupt.${ts}`;
+    let preserved = false;
+    try {
+      fs.renameSync(this._file, sidecar);
+      preserved = true;
+    } catch (_renameErr) {
+      // Cross-device or other rename failure — fall back to a copy.
+      try {
+        fs.writeFileSync(sidecar, raw);
+        preserved = true;
+      } catch (_writeErr) {
+        // ignore — reported below
+      }
+    }
+    const where = preserved ? `preserved as ${path.basename(sidecar)}` : 'COULD NOT be preserved';
+    const message =
+      `result file ${this._file} was corrupt (${err.message}); ` +
+      `${where} and a fresh accumulator was started so prior steps are not silently clobbered`;
+    this.warnings.push(message);
+    return {};
+  }
+
+  // Atomic write: delegates to the shared util (see src/util/atomic.js).
+  // `this._dir === path.dirname(this._file)` (results dir), so this is
+  // behavior-identical to the previous inline implementation.
+  _atomicWrite(contents) {
+    atomicWrite(this._file, contents);
+  }
+
+  _persistInProgress() {
+    const snapshot = {
+      run_id: this.runId,
+      scenario_id: this.scenarioId,
+      schema_version: SCHEMA_VERSION,
+      steps_executed: this._steps,
+      assertion_results: this._assertions,
+      observations: this._observations,
+      captured_variables: this._capturedVariables,
+      _in_progress: true,
+    };
+    this._atomicWrite(JSON.stringify(snapshot, null, 2));
+  }
+
+  addStep({ step_id, status, attempts = 1, screenshot = null, error_message = null, observations = null } = {}) {
+    return withLock(this._lock, () => {
+      this._refreshFromDisk();
+      const normalized = stepStatus(status);
+      const retryCount = Math.max(0, Number(attempts) - 1);
+      const step = {
+        step_id,
+        status: normalized,
+        screenshot,
+        error_message,
+        retried: retryCount > 0,
+        retry_count: retryCount,
+        observations,
+      };
+      this._steps.push(step);
+
+      // Flakiness bookkeeping: a step that ultimately PASSED but needed more than
+      // one attempt is flaky.
+      if (retryCount > 0 && normalized === 'passed') {
+        this._observations.push({
+          type: 'flakiness',
+          step_id,
+          message: `Step '${step_id}' passed only after ${attempts} attempts; possible flakiness.`,
+        });
+      }
+
+      this._persistInProgress();
+      return step;
+    });
+  }
+
+  // Append a TYPED observation to the run-level `observations` array — the one
+  // `finalize()` emits and `src/memory/store.js` harvests. Deliberately NOT
+  // routed through `addStep`: the step-level `observations` field is a legacy
+  // freeform string, so writing there would produce untyped text in the wrong
+  // shape (see #140 D2).
+  addObservation({ type, step_id = null, message } = {}) {
+    return withLock(this._lock, () => {
+      this._refreshFromDisk();
+      if (!OBSERVATION_TYPES.includes(type)) {
+        throw new Error(
+          `unknown observation type "${type}" (expected ${OBSERVATION_TYPES.join(' | ')})`
+        );
+      }
+      if (message == null || String(message).trim() === '') {
+        throw new Error(
+          'observation message is required and cannot be empty or whitespace-only'
+        );
+      }
+      const entry = { type, step_id: step_id == null ? null : String(step_id), message: String(message) };
+      this._observations.push(entry);
+      this._persistInProgress();
+      return entry;
+    });
+  }
+
+  addAssertion({ step_id, assertion_id, type, pass, message, expected = null, actual = null } = {}) {
+    return withLock(this._lock, () => {
+      this._refreshFromDisk();
+      const entry = {
+        assertion_id: assertion_id || `${step_id || 'assert'}_${type || 'unknown'}_${this._assertions.length + 1}`,
+        status: assertionStatus(pass),
+        expected: expected == null ? null : String(expected),
+        actual: actual == null ? null : String(actual),
+        message: message || '',
+      };
+      this._assertions.push(entry);
+      this._persistInProgress();
+      return entry;
+    });
+  }
+
+  captureVariable(name, value) {
+    return withLock(this._lock, () => {
+      this._refreshFromDisk();
+      this._capturedVariables[name] = value;
+      this._persistInProgress();
+    });
+  }
+
+  finalize({ status, durationSeconds = 0, summary, metadata } = {}) {
+    return withLock(this._lock, () => {
+      this._refreshFromDisk();
+      const passed = this._assertions.filter((a) => a.status === 'passed').length;
+      const failed = this._assertions.filter((a) => a.status === 'failed').length;
+      const total = this._assertions.length;
+
+      const resolvedStatus = status || (failed > 0 ? 'failed' : 'passed');
+
+      const result = {
+        run_id: this.runId,
+        scenario_id: this.scenarioId,
+        schema_version: SCHEMA_VERSION,
+        status: resolvedStatus,
+        metadata: defaultMetadata({ ...this._metadataOverrides, ...(metadata || {}) }),
+        total_assertions: total,
+        passed_assertions: passed,
+        failed_assertions: failed,
+        duration_seconds: Number(durationSeconds) || 0,
+        steps_executed: this._steps,
+        assertion_results: this._assertions,
+        observations: this._observations,
+        captured_variables: this._capturedVariables,
+        summary:
+          summary ||
+          `${resolvedStatus}: ${passed}/${total} assertion(s) passed across ${this._steps.length} step(s).`,
+      };
+
+      this._atomicWrite(JSON.stringify(result, null, 2));
+      return result;
+    });
+  }
+}
+
+module.exports = { ResultStore };

package/src/scenario/validator.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+
+const { formatError } = require('../schemas/format-error');
+
+// Path to the canonical scenario schema, bundled inside the package.
+// src/scenario/validator.js -> ../schemas/scenario_schema.json
+const DEFAULT_SCHEMA_PATH = path.resolve(__dirname, '../schemas/scenario_schema.json');
+
+class ScenarioValidator {
+  constructor({ schemaPath = DEFAULT_SCHEMA_PATH } = {}) {
+    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    this._validateFn = ajv.compile(schema);
+  }
+
+  validate(scenarioObject) {
+    const valid = this._validateFn(scenarioObject);
+    if (valid) {
+      return { valid: true, errors: [] };
+    }
+    const errors = (this._validateFn.errors || []).map(formatError);
+    return { valid: false, errors };
+  }
+}
+
+module.exports = { ScenarioValidator, DEFAULT_SCHEMA_PATH };

package/src/schemas/config_schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Mobile Automator Workspace Config",
+  "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.",
+  "type": "object",
+  "additionalProperties": true,
+  "definitions": {
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "A list of strings. `mauto config set` accepts either a JSON array or a comma-separated value and stores a list either way."
+    },
+    "nullableString": {
+      "type": ["string", "null"],
+      "description": "A string, or null when the value is not yet configured."
+    }
+  },
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["platform-aware", "platform-agnostic"],
+      "description": "Selected at setup. Configs predating this field are treated as platform-aware."
+    },
+    "project_name": { "$ref": "#/definitions/nullableString" },
+    "platform": { "type": "string", "description": "Detected platform (platform-aware mode)." },
+    "platform_details": { "type": "string" },
+    "build_system": { "type": "string" },
+    "build_command": { "type": "string" },
+    "architecture": { "type": "string" },
+    "business_domain": { "type": "string" },
+    "loading_indicators": { "type": "string" },
+    "automation_extras": { "type": "string" },
+    "additional_resources": { "type": "string" },
+    "android_package": { "type": "string" },
+    "ios_bundle_id": { "type": "string" },
+    "default_environment": { "$ref": "#/definitions/nullableString" },
+    "environments": { "$ref": "#/definitions/stringList" },
+    "protected_directories": { "$ref": "#/definitions/stringList" },
+    "business_critical_paths": { "$ref": "#/definitions/stringList" },
+    "app": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Legacy nested shape written by pre-CLI setup. Read by the placeholder resolver.",
+      "properties": {
+        "android_package": { "type": "string" },
+        "ios_bundle_id": { "$ref": "#/definitions/nullableString" }
+      }
+    },
+    "knowledge": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Legacy nested shape written by pre-CLI setup. Read by the placeholder resolver.",
+      "properties": {
+        "project_name": { "$ref": "#/definitions/nullableString" },
+        "architecture": { "type": "string" },
+        "platform_details": { "type": "string" },
+        "build_system": { "type": "string" },
+        "build_command": { "type": "string" },
+        "business_domain": { "type": "string" },
+        "loading_indicators": { "type": "string" },
+        "automation_extras": { "type": "string" },
+        "additional_resources": { "type": "string" },
+        "protected_directories": { "$ref": "#/definitions/stringList" },
+        "business_critical_paths": { "$ref": "#/definitions/stringList" }
+      }
+    }
+  }
+}

package/src/schemas/format-error.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// Ajv error -> one human-readable sentence. Shared by the scenario validator
+// (`mauto validate`) and the config validator (`mauto config set`) so a schema
+// violation reads the same wherever it surfaces.
+function formatError(err) {
+  const where = err.instancePath || '(root)';
+  let msg = `${where} ${err.message}`;
+  if (err.keyword === 'required' && err.params && err.params.missingProperty) {
+    msg = `${where} is missing required property '${err.params.missingProperty}'`;
+  } else if (err.keyword === 'enum' && err.params && Array.isArray(err.params.allowedValues)) {
+    msg = `${where} ${err.message}: ${err.params.allowedValues.join(', ')}`;
+  } else if (err.keyword === 'additionalProperties' && err.params) {
+    msg = `${where} has unexpected property '${err.params.additionalProperty}'`;
+  }
+  return msg;
+}
+
+module.exports = { formatError };