swipium 1.3.0 → 1.5.0

package/dist/visual/ocr.js.map

@@ -1 +1 @@
-{"version":3,"file":"ocr.js","sourceRoot":"","sources":["../../src/visual/ocr.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ocr.js","sourceRoot":"","sources":["../../src/visual/ocr.ts"],"names":[],"mappings":"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"}

package/dist/visual/provider.js

@@ -5,14 +5,16 @@ import { loadProjectConfig } from '../cli/scan.js';
 import { resolveCommandTemplate } from '../lib/commandTemplate.js';
 import { assertNoGitScope, run } from '../lib/spawn.js';
 function isProviderObject(value) {
-    return !!value && typeof value === 'object' && !Array.isArray(value) && ('command' in value);
+    return !!value && typeof value === 'object' && !Array.isArray(value) && 'command' in value;
 }
 export function resolveVisualProvider(command, vars, defaultTimeoutMs) {
     const raw = isProviderObject(command) ? command.command : command;
     const resolved = resolveCommandTemplate(raw, vars);
     assertNoGitScope(resolved.command, resolved.args);
     const io = isProviderObject(command) && command.io === 'json' ? 'json' : 'argv';
-    const timeoutMs = isProviderObject(command) && Number.isFinite(command.timeoutMs) && command.timeoutMs > 0 ? Math.floor(command.timeoutMs) : defaultTimeoutMs;
+    const timeoutMs = isProviderObject(command) && Number.isFinite(command.timeoutMs) && command.timeoutMs > 0
+        ? Math.floor(command.timeoutMs)
+        : defaultTimeoutMs;
     return { ...resolved, io, timeoutMs };
 }
 export async function runVisualProvider(command, vars, payload, defaultTimeoutMs) {
@@ -52,7 +54,9 @@ export async function maskScreenshotForProvider(root, imagePath, context) {
         rmSync(outputPath, { force: true });
         throw new Error('visualMaskCommand did not produce a masked imagePath or output file');
     }
-    const masksApplied = Array.isArray(parsed.masksApplied) ? parsed.masksApplied.filter((v) => typeof v === 'string') : ['external_mask'];
+    const masksApplied = Array.isArray(parsed.masksApplied)
+        ? parsed.masksApplied.filter((v) => typeof v === 'string')
+        : ['external_mask'];
     return { imagePath: produced, tempPaths: produced === imagePath ? [] : [produced], masksApplied, providerConfigured: true };
 }
 export function boundedProviderObject(value, redact, maxChars = 8000) {

package/dist/visual/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/visual/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/visual/provider.ts"],"names":[],"mappings":"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"}

package/docs/mcp-server.md

@@ -6,15 +6,17 @@ Swipium runs as a local stdio MCP server. The MCP client starts the process and
 
 - Node.js 20 or newer.
 - A mobile app repository as the MCP `cwd`.
-- Android Studio for Android Emulator workflows.
-- Xcode for iOS Simulator workflows.
+- Android platform-tools with `adb` on your PATH, usually from Android Studio.
+- Android Emulator package plus at least one AVD for Android Emulator workflows.
+- Xcode with an iOS Simulator runtime and at least one simulator for iOS workflows.
+- WebDriverAgent for structured iOS UI-tree access, taps, typing, and swipes. Visual-only iOS checks can still use `simctl` without WDA.
 
 ## Server Command
 
 No global install:
 
 ```jsonc
-{s
+{
   "mcpServers": {
     "swipium": {
       "command": "npx",
@@ -41,6 +43,8 @@ Global install:
 }
 ```
 
+`npx -y swipium` is the canonical setup for npm users. From a source checkout, build with `npm run build` and use `node /absolute/path/to/swipium/dist/index.js` as the command instead.
+
 ## Claude Code
 
 ```bash
@@ -83,6 +87,42 @@ args = ["-y", "swipium"]
 cwd = "/absolute/path/to/your/mobile-app"
 ```
 
+Known caveat: Codex builds after ~0.120.0 have an open tool-injection regression (openai/codex#19425). Set `cwd` explicitly, and if `qa_*` tools do not appear after setup, switch `command` to an absolute path and restart Codex.
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`), then restart Claude Desktop:
+
+```jsonc
+{
+  "mcpServers": {
+    "swipium": {
+      "command": "npx",
+      "args": ["-y", "swipium"],
+      "cwd": "/absolute/path/to/your/mobile-app",
+      "timeout": 600000
+    }
+  }
+}
+```
+
+## Cursor
+
+Add to `.cursor/mcp.json` in the mobile app repository, or `~/.cursor/mcp.json` for all projects:
+
+```jsonc
+{
+  "mcpServers": {
+    "swipium": {
+      "command": "npx",
+      "args": ["-y", "swipium"],
+      "cwd": "/absolute/path/to/your/mobile-app",
+      "timeout": 600000
+    }
+  }
+}
+```
+
 ## Verification
 
 Run:
@@ -100,7 +140,7 @@ qa_capabilities
 
 Use `qa_doctor` with `platform:"android"`, `platform:"ios"`, or `platform:"both"` when checking platform-specific readiness.
 
-Expected tool count: 91.
+Expected tool count: 60.
 
 If the client lists fewer tools, restart the MCP client. MCP clients often keep an old server process alive after package upgrades.
 

package/docs/tools.md

@@ -1,6 +1,8 @@
 # Tool Reference
 
-Swipium exposes 91 public MCP tools. The intended default entry point is `qa_test_this`.
+Swipium 1.5.0 exposes 60 public MCP tools. The intended default entry point is `qa_test_this`.
+
+This is the production public surface. Lower-level visual, seeded-state, report-history, and issue-lifecycle helpers from earlier development builds were merged into canonical workflows or deferred from public MCP registration; use the grouped tools below as the supported entry points.
 
 ## Start
 
@@ -15,6 +17,7 @@ Use these tools to orient the agent, start autopilot work, poll jobs, handle blo
 | `qa_status` | Returns compact session status and recommended next action. | The agent needs to recover context during a session. |
 | `qa_explain_blocker` | Explains a typed blocker, likely owner, and recovery path. | A run stops with a blocker and the user needs a concise explanation. |
 | `qa_continue_from_blocker` | Resumes after user input and registers secret values for redaction. | A blocker asks for credentials, OTP, target choice, or approval data. |
+| `qa_next_best_action` | Returns the single best next tool to call (with args) and why, deterministically. | The agent wants the orchestration sequence decided for it. |
 | `qa_get_artifact` | Fetches artifact metadata or contents by `swipium://` URI. | A report, screenshot, dump, log, or generated file must be read. |
 | `qa_job_cancel` | Cancels a running job and aborts its spawned children. | A long-running job must be stopped early. |
 
@@ -35,14 +38,13 @@ Use these tools to verify the local environment, create sessions, and prepare si
 
 ## Build
 
-Use these tools to resolve a device and an installable artifact, or build one from source locally. `qa_build` is consent-gated; the others are side-effect free.
+Use these tools to resolve a device and an installable artifact, or build one from source locally. `qa_build` with `mode:"run"` is consent-gated; everything else is side-effect free.
 
 | Tool | What it does | Use when |
 | --- | --- | --- |
 | `qa_resolve_target` | Picks the best device or simulator (prefers online over needing a boot; honors a requested platform or device). | The agent needs to choose where to run. |
 | `qa_resolve_artifact` | Finds the best installable `.apk`/`.aab`/`.ipa`/`.app` and explains where it looked. | An artifact path is unknown or ambiguous. |
-| `qa_build_plan` | Proposes the exact build commands per framework and platform without running them. | The agent needs to know how the app would be built. |
-| `qa_build` | Builds from source as a consent-gated job, captures a build log, and re-resolves the artifact. | No reusable artifact exists and the project must be compiled. |
+| `qa_build` | `mode:"plan"` (default) proposes the exact build commands per framework and platform without running them; `mode:"run"` builds from source as a consent-gated job, captures a build log, and re-resolves the artifact. | The agent needs to know how the app would be built, or no reusable artifact exists and the project must be compiled. |
 | `qa_bundletool` | Converts an `.aab` to an installable APK: a universal `.apk` or a device-specific APK set. | Only an Android App Bundle is available. |
 
 ## Device
@@ -52,13 +54,11 @@ Use these tools to inspect and control the device and app environment without ra
 | Tool | What it does | Use when |
 | --- | --- | --- |
 | `qa_device_info` | Reports model, SDK, ABIs, locale, screen, orientation, and installed apps (read-only). | The agent needs device context before testing. |
-| `qa_permissions` | Lists, grants, or revokes runtime permissions. Revoke is consent-gated. | A flow needs a known permission state. |
 | `qa_orientation` | Sets portrait, landscape, or auto orientation. | A screen must be tested in a specific orientation. |
 | `qa_geolocation` | Spoofs a GPS location on the emulator. Consent-gated. | Testing map or location-aware screens. |
 | `qa_network` | Reports, sets offline/online, or restores airplane-mode state. Consent-gated and auto-restored. | Testing offline behavior or network errors. |
 | `qa_metro` | Reports, starts, stops, or diagnoses the RN/Expo Metro bundler with RedBox detection. | A debug RN/Expo build needs Metro. |
 | `qa_app_control` | Runs launch, foreground, background, force_stop, restart, clear_data, or fresh_start. Destructive actions are guarded. | The app lifecycle must be controlled directly. |
-| `qa_screen_info` | Reports screen width, height, density, orientation, mode, and coordinate landmarks. | Coordinate-space context is needed for visual work. |
 | `qa_screen_record` | Records a screen video to an mp4 artifact (start/stop). Consent-gated with sensitive-screen warnings. | A run needs a video of the reproduction. |
 
 ## Drive
@@ -68,29 +68,14 @@ Use these tools to observe the UI, act on it, collect evidence, and record resul
 | Tool | What it does | Use when |
 | --- | --- | --- |
 | `qa_snapshot` | Captures compact structured UI elements where the backend supports it. | The agent needs selectors, visible text, or UI state. |
+| `qa_inspect` | Returns the full attributes of a single `@eN` element from the latest snapshot. | One element's details are needed without dumping the whole tree. |
 | `qa_act` | Taps, types, clears, swipes, scrolls, presses keys, opens URLs, waits, and observes after action. | The agent needs to drive the app step by step. |
 | `qa_clear_overlay` | Attempts to dismiss common overlays blocking a target. | Popups, permissions, modals, or sheets block the next action. |
 | `qa_check_health` | Checks foreground app status, crash signals, ANR, error boundaries, and native health. | The agent needs to distinguish app bugs from environment issues. |
 | `qa_screenshot` | Captures a screenshot artifact with coordinate-space metadata. | Visual evidence is required. |
 | `qa_note` | Records a structured QA outcome in the session. | The agent needs to log pass, fail, blocked, skipped, or finding details. |
 | `qa_assert_visual` | Captures a visual assertion with evidence. | The agent needs to document that a visual condition is true or false. |
-| `qa_visual` | Runs local visual operations: baseline capture, regression diff, image-target matching with tappable coordinates, and optional OCR. | A screen is visual-only or needs pixel-level regression checks. |
-| `qa_visual_find_text` | Locates on-screen text with OCR and returns structured regions with coordinate-space conversion. | A target has visible text but no structured selector. |
-| `qa_locator_suggest` | Scores each element's locator durability and grades automation readiness. | The agent needs to know which controls need testIDs before generating automation. |
-| `qa_input_capabilities` | Reports backend text-entry limits: ASCII, Unicode, clipboard, and WDA typing frequency. | Typing fails or behaves oddly and the agent needs the backend's input limits. |
 | `qa_wait` | Waits without a shell for `device_online`, `metro_ready`, or `job_done`. | The agent needs to block on a condition without raw `adb`/`sleep`. |
-| `qa_idling_status` | Reads app-declared idling hooks or label-heuristic settling before automation. | The agent needs to know the app has settled before acting. |
-
-## State
-
-Use these tools to create and verify reproducible preconditions instead of only reporting them as missing. All mutating seed and state actions are consent-gated and recorded.
-
-| Tool | What it does | Use when |
-| --- | --- | --- |
-| `qa_seed` | Creates a declared precondition via a fixture seed using a deeplink, script, or API hook. Consent-gated. | A workflow is blocked by missing test data. |
-| `qa_state_prepare` | Prepares a reproducible state profile: reset, launch, seed, and verify a ledger. | A test needs a known starting state. |
-| `qa_state_verify` | Verifies a state profile without treating setup drift as an app bug. | The precondition must be confirmed before testing. |
-| `qa_state_teardown` | Runs state-profile teardown and restores declared environment state. | A run must leave the environment clean. |
 
 ## Run
 
@@ -101,8 +86,6 @@ Use these tools to run broader QA workflows and produce reports.
 | `qa_smoke` | Runs launch smoke, baseline health, screenshot evidence, and saved flows. | The app is prepared and the agent needs a deterministic smoke pass. |
 | `qa_explore` | Performs bounded guided exploration, builds a screen graph, and records evidence. | The agent needs to discover reachable workflows or collect runtime app-map data. |
 | `qa_report` | Generates a session report with findings, blockers, evidence, mutations, workarounds, next actions, and separate app and coverage verdicts. | A run should be summarized or exported. |
-| `qa_report_compare` | Compares the current `report.json` against a baseline report. | A run should be checked for regression against a known-good report. |
-| `qa_run_history` | Summarizes local run history with pass rate, failures, flaky flows, and confidence calibration. | The user wants trends across runs, not a single report. |
 
 ## App Map
 
@@ -113,8 +96,8 @@ Use these tools to build and read Swipium's durable app knowledge map.
 | `qa_app_map_build` | Builds or updates the app map from static analysis and runtime observations. | The project needs durable QA memory. |
 | `qa_app_map_read` | Reads compact app-map sections such as features, screens, auth, automation, or test suite. | The agent needs app context without flooding the transcript. |
 | `qa_app_map_query` | Searches features, screens, tests, and code links with ranked results. | The user asks about a feature, screen, or test surface. |
-| `qa_app_map_feature_scope` | Resolves a feature query or feature id into focused testing scope and recommended plan. | The agent needs to test a specific feature. |
-| `qa_app_map_validate` | Validates schema, provenance, links, duplicate ids, impossible states, and stale fingerprints. | The map must be trusted before feature-focused testing. |
+| `qa_app_map_feature_scope` | Resolves a feature id or free-text query into a focused testing scope: ranked candidates, code symbols, screens, existing tests, an objective model, and a recommended plan. Read-only; works before a map exists. | The user names a feature and the agent needs its scope. |
+| `qa_app_map_update` | Applies targeted, provenance-tracked updates (note, test cases, automation suite, environment, feature coverage) without a full rebuild. | The map needs a small correction or annotation. |
 
 ## Feature Testing
 
@@ -122,47 +105,38 @@ Use these tools to test a specific feature by name, backed by the app knowledge
 
 | Tool | What it does | Use when |
 | --- | --- | --- |
-| `qa_feature_scope` | Maps a natural-language feature ("weather analysis") to code, screens, routes, runtime, and tests, plus an objective and strategy. Read-only. | The user names a feature and the agent needs its scope. |
-| `qa_feature_test_plan` | Produces a feature test plan: scope, objective, generated cases, fixtures, automation readiness, and an execution plan. Read-only. | A feature needs a concrete test plan before running. |
-| `qa_test_feature` | Runs a focused feature test: scope, targeted exploration toward the feature, recorded cases, then updates the feature map and report. | The user asks to test a specific feature. |
+| `qa_test_feature` | Tests a named feature: `mode:"plan"` (default) returns the read-only test plan (scope, objective, generated cases, fixtures, execution plan); `mode:"execute"` runs targeted exploration toward the feature, records cases, then updates the feature map and report. | The user asks to plan or run a test of a specific feature. |
 
-## Flows and Suites
+## Flows
 
-Use these tools to create, validate, run, and compile reusable test assets.
+Use these tools to create, validate, run, compile, and repair reusable flows.
 
 | Tool | What it does | Use when |
 | --- | --- | --- |
-| `qa_flow_check` | Parses and statically validates a Swipium flow. | A flow file should be checked before execution. |
-| `qa_flow_plan` | Plans a flow against backend capabilities without executing it. | A flow should be checked for feasibility before a run. |
-| `qa_flow_run` | Executes a Swipium flow against a prepared simulator session. | A saved flow needs to run against the app. |
-| `qa_flow_generate` | Generates a flow from recorded actions. | A manual or exploratory run should become a reusable flow. |
+| `qa_flow_check` | Parses and statically validates a Swipium flow (static lint of the YAML). | A flow file should be checked before execution. |
+| `qa_flow_run` | `mode:"run"` (default) executes a Swipium flow against a prepared simulator session; `mode:"plan"` is a read-only execution preview against backend capabilities without touching a device. | A saved flow needs to run against the app, or its feasibility should be checked before a run. |
+| `qa_flow_compile` | Compiles a generated POM suite into runnable Flow V2 for `qa_flow_run` and `swipium ci`. | A generated suite needs executable flow output. |
 | `qa_flow_repair` | Suggests or patches a stronger locator for a failed flow step from the current screen. | A flow step fails on a brittle locator. |
-| `qa_suite_generate` | Generates a POM-style suite from recorded behavior. | The run should become a structured test suite. |
-| `qa_suite_compile` | Compiles a generated suite into runnable Swipium flows. | A generated suite needs executable flow output. |
-| `qa_suite_lint` | Lints generated page objects for brittle, coordinate-only, or dynamic locators. | A generated suite needs a durability check. |
-| `qa_pom_generate` | Generates page objects and a locator audit from recorded actions. | A run should produce reusable page objects. |
-| `qa_testcase_generate` | Generates test-case documentation from recorded behavior. | The run should produce human-readable test cases and steps. |
 
-## Persistent Test Suite
+## Generate
 
-Use these tools to grow and maintain a canonical test suite that persists across runs in `.swipium/test-suite.json`.
+Use `qa_generate` to turn a session's recorded actions into reusable, per-run test assets. Pick the output with `target`; `mode:"plan"` gives a read-only preview. For the durable repo-level test suite that grows across runs, use `qa_suite_generate` instead.
 
 | Tool | What it does | Use when |
 | --- | --- | --- |
-| `qa_test_suite_read` | Reads the canonical suite, filtered by functionality or status, as summary, json, or markdown. | The agent needs the durable suite without re-deriving it. |
-| `qa_test_suite_update` | Merges cases into the persistent suite, deduping by feature, objective, and steps. | A run produced cases to fold into the suite. |
-| `qa_test_suite_generate` | Generates or refreshes canonical cases from a recorded run and exploration. | The suite needs to be (re)built from observed behavior. |
-| `qa_test_suite_export` | Exports the persistent suite to markdown, a yaml directory, json, or junit. | The suite must be shared or fed to CI. |
-| `qa_test_suite_lint` | Validates the suite for missing expected/actual, stale map links, and duplicate ids. | The suite must be trusted before a release sign-off. |
+| `qa_generate` | Generates test assets from recorded actions: `target:"flow"` (repeatable Flow V2 YAML), `target:"pom"` (page objects + locator audit), `target:"suite"` (full per-run `.swipium/` POM suite with compile/replay gates), `target:"testcases"` (test-case catalog docs), or `target:"appium"` (runnable Appium POM code in JS/TS/Python, with bootstrap from `projectRoot`). `mode:"plan"` previews without writing; for `target:"appium"` it returns the full automation plan with blockers. | A manual or exploratory run should become a reusable flow, page objects, a structured suite, test-case docs, or automation code. |
 
-## Maestro Interop
+## Persistent Test Suite
 
-Use these tools to exchange flows with the Maestro ecosystem.
+Use these tools to grow and maintain a canonical test suite that persists across runs in `.swipium/test-suite.json`. This is the durable repo-level suite — distinct from the per-run assets `qa_generate` emits.
 
 | Tool | What it does | Use when |
 | --- | --- | --- |
-| `qa_maestro_import` | Imports supported Maestro YAML commands into a Swipium Flow V2. | An existing Maestro flow should run under Swipium. |
-| `qa_maestro_export` | Exports a Swipium Flow V2 to Maestro YAML with portability grades. | A Swipium flow should be shared as Maestro YAML. |
+| `qa_suite_read` | Reads the canonical suite, filtered by functionality or status, as summary, json, or markdown. | The agent needs the durable suite without re-deriving it. |
+| `qa_suite_update` | Merges cases into the persistent suite, deduping by feature, objective, and steps. | A run produced cases to fold into the suite. |
+| `qa_suite_generate` | Generates or refreshes canonical cases from a recorded run and exploration, merging into the durable suite (not per-run assets — use `qa_generate` for those). | The durable suite needs to be (re)built from observed behavior. |
+| `qa_suite_export` | Exports the persistent suite to markdown, a yaml directory, json, or junit. | The suite must be shared or fed to CI. |
+| `qa_suite_lint` | Validates the durable suite (missing expected/actual, stale map links, duplicate ids) and, when `.swipium/pages` exists, also lints generated page objects for brittle locators. | The suite and generated pages must be trusted before a release sign-off. |
 
 ## Issue Memory and Mobile Audit
 
@@ -171,79 +145,47 @@ Use these tools for a durable, per-project issue ledger and executable mobile-QA
 | Tool | What it does | Use when |
 | --- | --- | --- |
 | `qa_issue_log` | Lists the durable issue ledger with counts, recurrence candidates, and linked evidence. | The agent needs the project's known issues. |
-| `qa_issue_history` | Shows the append-only event trail for one issue. | An issue's lifecycle needs auditing. |
-| `qa_issue_mark_fixed` | Records a fix (date, commit, version, how-fixed) so future runs detect regressions. | A reported issue has been resolved. |
-| `qa_issue_triage` | Changes an issue's category, severity, or owner, or appends a note. | An issue needs reclassification. |
-| `qa_issue_suppress` | Suppresses known noise with a reason and expiration; it stays visible as known-noise. | A recurring non-bug should stop dominating reports. |
-| `qa_issue_verify_fixed` | Links passing test or audit evidence to a fixed issue. | A report should honestly claim an issue was verified this run. |
-| `qa_issue_metrics` | Summarizes issue trends: opened, fixed, reopened, verified, aging, and reopen rate. | The user wants issue quality trends. |
 | `qa_mobile_audit` | Plans or executes a named mobile-QA profile (smoke, account_cycle, store_compliance, resilience, release_gate). | A structured, repeatable audit is needed; execution records issues and evidence. |
 
 ## First Run
 
-Use these tools for login, account creation, onboarding, permissions, OTP, and paywall screens.
+Use this tool for login, account creation, onboarding, permissions, OTP, and paywall screens.
 
 | Tool | What it does | Use when |
 | --- | --- | --- |
-| `qa_first_run_plan` | Classifies the current first-run screen and creates a safe plan without acting. | The agent reaches login, signup, onboarding, permission, OTP, paywall, or home screens. |
-| `qa_first_run_continue` | Executes bounded first-run steps with safe generated data when allowed and stops at gates. | The plan can safely proceed in a test or staging environment. |
-
-## Automation
+| `qa_first_run` | `mode:"plan"` (default) classifies the current first-run screen and creates a safe plan without acting; `mode:"continue"` executes bounded first-run steps (`until: one_step`/`until_gate`/`until_home`) with safe generated data when allowed and stops at gates. | The agent reaches login, signup, onboarding, permission, OTP, paywall, or home screens. |
 
-Use these tools to generate and validate automation code from Swipium evidence.
+## Detailed Reference: Device, Build, and Feature Tools
 
-| Tool | What it does | Use when |
-| --- | --- | --- |
-| `qa_automation_plan` | Plans generated JS, TS, or Python Appium automation from project profile and recorded actions. | The user asks to automate the tested behavior. |
-| `qa_automation_generate` | Generates an Appium POM suite from recorded actions and validates it. | The run should produce automation code. |
-| `qa_automation_validate` | Validates generated automation code without a device. | Generated files need checks for secrets, durability, capabilities, syntax, and empty files. |
-
-## Detailed Reference: Device, Visual, State, History, Build, and Feature Tools
-
-Technical detail for the tools added alongside the device-parity, visual-intelligence, seeded-state, reporting, build, and feature-testing phases. Most take a `sessionId` from `qa_start_session`; the build, artifact, and read-only feature tools also accept a `projectRoot` so they work before a session exists. Mutating actions accept `consentId` + `approve` and are recorded in the report's mutation ledger.
+Technical detail for retained public device, build, feature, app-map, and agent-helper tools. Most take a `sessionId` from `qa_start_session`; the build, artifact, and read-only feature tools also accept a `projectRoot` so they work before a session exists. Mutating actions accept `consentId` + `approve` and are recorded in the report's mutation ledger.
 
 ### Device and app environment
 
 - **`qa_device_info`** — read-only Android introspection. *Inputs:* `listPackages?`, `packageFilter?`. *Outputs:* `props` (manufacturer, model, SDK, release, ABIs, locale, timezone), `screen` (`width`/`height`/`density`), `orientation`/`rotation`/`autoRotate`, `installedThirdPartyCount`, optional `packages[]`. No consent.
 - **`qa_orientation`** — set rotation. *Inputs:* `orientation: portrait | landscape | auto`. *Outputs:* resulting `orientation`/`rotation`/`autoRotate`. Non-destructive; logged as an environment change.
 - **`qa_geolocation`** — spoof GPS via `adb emu geo fix <lng> <lat>`. *Inputs:* `lat`, `lng` (decimal degrees). *Outputs:* `{ lat, lng, set }`. Consent-gated (medium). Emulator/`direct` backend only; iOS and real devices return `BACKEND_UNSUPPORTED`.
-- **`qa_permissions`** — runtime permission control. *Inputs:* `action: list | grant | revoke`, `package?` (default session `appId`), `permission?` (`android.permission.*`, required for grant/revoke). *Outputs:* `granted[]`/`denied[]` (list) or `{ package, permission, action }`. `list` is read-only; `grant` is consent-gated low (it can mask a permission-prompt bug); `revoke` is consent-gated medium (can break app state).
 - **`qa_network`** — offline/online via `cmd connectivity airplane-mode` (Android 11+). *Inputs:* `action: status | offline | online | restore`. *Outputs:* `network` (`online`/`offline`), `restoreAvailable`. `offline`/`online` consent-gated (medium); the original airplane state is recorded on first change and auto-restored at `qa_report`, on `restore`, and on server shutdown.
 - **`qa_metro`** — RN/Expo Metro lifecycle. *Inputs:* `action: status | diagnose | start | stop`. *Outputs:* `framework`, `metroListening`, `reverseSet`, `serving`, `ready`, `metroPid`, plus `redBox` + `recovery[]` (+ logcat artifact) for `diagnose`. `start` is consent-gated (low): it runs `adb reverse tcp:8081 tcp:8081` and spawns Metro (`npx expo start --dev-client` or `npx react-native start`) detached, logging to an artifact and tracking the PID; `stop` signals the whole process group.
 - **`qa_app_control`** — app lifecycle. *Inputs:* `action: launch | foreground | background | force_stop | restart | clear_data | fresh_start`, `acknowledgeBundleRisk?`. *Outputs:* `packageName`, `action`, `processKilled`, `foreground`, `foregroundIsApp`. `clear_data`/`fresh_start` are destructive → consent-gated (high); on debug RN/Expo builds they additionally require `acknowledgeBundleRisk:true` because a data wipe can remove the cached JS bundle.
-- **`qa_screen_info`** — coordinate-space metadata for visual-fallback work. *Outputs:* `screen` (`width`/`height`/`density`), `orientation`, session `mode`, `latestScreenshot`, named `landmarks` and `bands` (device pixels, origin top-left), `counters`, `budget`. Read-only.
 - **`qa_screen_record`** — screen video. *Inputs:* `action: start | status | stop`, `save?: always | on_failure`, `failed?`. *Outputs:* `recording`/`capturing`/`autoStopped`, `seconds`, and on stop a `uri` (mp4 artifact) + `bytes`. Consent-gated (medium); refused on sensitive sessions. Android uses `adb screenrecord --time-limit 180`; iOS uses `simctl io recordVideo`. One recording per session.
 
-### Visual intelligence (local-first)
-
-- **`qa_visual`** — deterministic visual ops + regression. *Inputs:* `action: baseline | diff | find_image | ocr`, `name?` (baseline/diff), `template?` (find_image PNG path), `threshold?` (diff, default 0.02), `minScore?` (find_image, default 0.85), `force?`. *Outputs:* always include `coordinateSpace` (screenshot↔device scale); `diff` adds `changedRatio`/`pass`/`changedBoxDevice`; `find_image` adds `devicePoint`. `baseline`/`diff`/`find_image` are local and need no consent; `ocr` is consent-gated and requires a configured `ocrCommand`. Withheld when a secure (password/OTP) field is on screen unless `force:true`.
-- **`qa_visual_find_text`** — OCR text locator. *Inputs:* `query`, `minConfidence?` (default 0.8). *Outputs:* `found`, matched `region` (text/confidence/bbox), `devicePoint`, `coordinateSpace`. Consent-gated (the screenshot is passed to the configured local OCR provider); requires `ocrCommand` returning JSON regions.
-
-### Seeded state
-
-- **`qa_seed`** — create a declared precondition. *Inputs:* `fixture` (must declare a `seed`: `deeplink | script | api`). *Outputs:* `{ fixture, type, seeded, warnings[] }`. Consent-gated; risk scales by type (`script` high, `api` medium, `deeplink` low). Git commands are refused (`GIT_SCOPE_FORBIDDEN`); a failed seed is reported as a SETUP failure (`missing_test_data`), never an app bug.
-- **`qa_state_prepare`** — apply a state profile as one transaction. *Inputs:* `profile` (`.swipium/state/<name>.yaml` or inline YAML). *Outputs:* a state `ledger` + `ledgerUri`. Consent-gated when it mutates (reset/launch/seed); refuses debug-bundle-loss resets unless acknowledged.
-- **`qa_state_verify`** — confirm a profile's declared checks (e.g. `assertVisible`). *Inputs:* `profile`. *Outputs:* verification `ledger`. Non-mutating; failures are setup/state blockers, not app-test failures.
-- **`qa_state_teardown`** — run profile teardown. *Inputs:* `profile`. *Outputs:* teardown `ledger`. Consent-gated when it mutates; restores declared state such as `networkOnline` and runs fixture cleanup hooks.
-
-### Report history
-
-- **`qa_report_compare`** — diff two reports. *Inputs:* `current`, `baseline` (paths to `report.json`), `trendRoot?`. *Outputs:* new/fixed failures, changed screenshots, outcome changes, runtime regression, optional flake status, and a `summary`. Filesystem-only — no session or device.
-- **`qa_run_history`** — local trend summary. *Inputs:* `sessionId?` or `projectRoot?`. *Outputs:* report count, per-flow `passRate`, median/average runtime, top failures, flaky flows, confidence calibration, and slowest steps. Reads `.swipium/runs/**/report.json` (and legacy `.swipium/ci/**`).
-
 ### Build and artifact resolution
 
 - **`qa_resolve_target`** — choose the best device or simulator, deterministically and side-effect free. *Inputs:* `sessionId?`, `projectRoot?`, `platform?` (`android`/`ios`), `device?` (name/serial/udid), `preferRealDevice?`. *Outputs:* `selection` (kind + id), a human `reason`, `alternatives[]`, `preconditions` (e.g. WDA/signing), and `willBoot`. Does not boot anything — `qa_prepare_target`/`qa_ios` do that.
-- **`qa_resolve_artifact`** — find the best installable artifact and explain the search. *Inputs:* `sessionId?`, `projectRoot?`, `platform?` (`android`/`ios`/`any`), `buildType?` (`debug`/`release`/`any`), `path?` (explicit artifact), `allowOutsideRoot?`, `requireInstallableOn?` (`android-emulator`/`android-real`/`ios-simulator`/`ios-real`). *Outputs:* the resolved `.apk`/`.aab`/`.ipa`/`.app` and its type; on failure, the exact globs searched plus a `qa_build_plan` → `qa_build` next step. Read-only.
-- **`qa_build_plan`** — propose exact build commands without running them. *Inputs:* `sessionId?`, `projectRoot?`, `platform` (`android`/`ios`), `variant?` (`debug`/`release`). *Outputs:* detected `framework`, the exact build commands, the expected artifact path, and a cost estimate. Returns a typed error when no supported framework (Expo, bare React Native, native Android/iOS, Flutter) is detected. Side-effect free.
-- **`qa_build`** — build from source as a consent-gated job. *Inputs:* `sessionId` (required), `platform` (`android`/`ios`), `variant?`, `timeoutMs?`, `consentId?`/`approve?`. *Outputs:* a `jobId` to poll with `qa_job_status`; on completion a build-log artifact and the re-resolved artifact path. Consent-gated (it compiles the app).
-- **`qa_bundletool`** — convert an Android App Bundle to an installable APK. *Inputs:* `sessionId` (required), `aab?` (default: the best `.aab` under the project), `force?`, `connectedDevice?` (device-specific APK set vs a universal APK), `install?` (also run `install-apks`), `deviceId?`, `consentId?`/`approve?`. *Outputs:* the generated APK or APK-set path. `install` is consent-gated because it installs app code on a device/emulator.
+- **`qa_resolve_artifact`** — find the best installable artifact and explain the search. *Inputs:* `sessionId?`, `projectRoot?`, `platform?` (`android`/`ios`/`any`), `buildType?` (`debug`/`release`/`any`), `path?` (explicit artifact), `allowOutsideRoot?`, `requireInstallableOn?` (`android-emulator`/`android-real`/`ios-simulator`/`ios-real`). *Outputs:* the resolved `.apk`/`.aab`/`.ipa`/`.app` and its type; on failure, the exact globs searched plus a `qa_build { mode:"plan" }` → `qa_build { mode:"run" }` next step. Read-only.
+- **`qa_build`** — plan or run a from-source build. *Inputs:* `mode?` (`plan` (default) / `run`), `platform` (`android`/`ios`), `variant?` (`debug`/`release`); `sessionId?`/`projectRoot?` for `mode:"plan"`; `sessionId` (required), `timeoutMs?`, `consentId?`/`approve?` for `mode:"run"`. *Outputs:* in `plan` mode the detected `framework`, the exact build commands, the expected artifact path, and a cost estimate — side-effect free, with a typed error when no supported framework (Expo, bare React Native, native Android/iOS, Flutter) is detected; in `run` mode a `jobId` to poll with `qa_job_status`, and on completion a build-log artifact and the re-resolved artifact path. `mode:"run"` is consent-gated (it compiles the app).
+- **`qa_bundletool`** — convert an Android App Bundle to an installable APK. *Inputs:* `sessionId` (required), `aab?` (default: the best `.aab` under the project), `force?`, `connectedDevice?` (device-specific APK set vs a universal APK), `install?` (also run `install-apks`), `device?` (adb serial), `consentId?`/`approve?`. *Outputs:* the generated APK or APK-set path. `install` is consent-gated because it installs app code on a device/emulator.
 
 ### Feature-focused testing
 
-- **`qa_feature_scope`** — map a natural-language feature to the app, read-only. *Inputs:* `feature` (required, e.g. "weather analysis"), `sessionId?` (adds runtime screen-graph evidence), `projectRoot?` (static code scope), `platform?`, `includeCode?` (default true), `limit?`. *Outputs:* ranked `candidates` each tagged by `source` (`code`/`screen`/`route`/`runtime`/`test`) with confidence, plus a test `objective` and `strategy`. No consent. Returns `found:false` with guidance when nothing matches.
-- **`qa_feature_test_plan`** — generate a full feature test plan, read-only. *Inputs:* `feature` (required), `sessionId?`/`projectRoot?`, `platform?`, `creativity?` (`conservative`=happy path; `standard` (default)=+validation/empty/error; `creative`=+boundary/offline/interruption; `adversarial`=+destructive), `allowAdversarial?`, `includeCode?`, `limit?`. *Outputs:* a `plan` with scope, objective, generated `cases`, `fixtures`, automation readiness, and an execution plan. Adversarial cases are consent-gated at execution time.
-- **`qa_test_feature`** — run a focused test toward a named feature. *Inputs:* `feature` (required), `sessionId` (required), `mode?` (`plan` (default) / `execute` (focused run as a job) / `interactive` (run until the first question)), `platform?`, `device?`, `creativity?`, `allowAdversarial?`, `maxScreens?`, `maxActions?`, `timeoutMs?`, `generateCases?`, `consentId?`/`approve?`. *Outputs:* in `plan` mode the scope + cases; in `execute` mode a `jobId` whose run performs targeted exploration toward the feature, records cases, updates the feature map, and emits a report. `execute`/`interactive` are consent-gated.
+- **`qa_app_map_feature_scope`** — map a feature to the app, read-only. *Inputs:* `query` (free text, e.g. "weather analysis") or `featureId` (exact map feature id), `sessionId?` (adds runtime screen-graph evidence), `projectRoot?` (static code scope), `platform?`, `includeCode?` (default true), `limit?`. *Outputs:* in query mode, ranked `candidates` each tagged by `source` (`code`/`screen`/`route`/`runtime`/`test`) with confidence, plus a test `objective` and `strategy`; in featureId mode, the map feature's source files, screens, coverage, blockers, and recommended plan. No consent. Query mode works before a map exists; returns `found:false` with guidance when nothing matches.
+- **`qa_test_feature`** — run a focused test toward a named feature. *Inputs:* `feature` (required), `sessionId` (required), `mode?` (`plan` (default) / `execute` (focused run as a job) / `interactive` (run until the first question)), `platform?`, `device?`, `creativity?`, `allowAdversarial?`, `maxScreens?`, `maxActions?`, `timeoutMs?`, `generateCases?`, `consentId?`/`approve?`. *Outputs:* in `plan` mode the read-only test plan (scope, objective, generated cases, fixtures, execution plan); in `execute` mode a `jobId` whose run performs targeted exploration toward the feature, records cases, updates the feature map, and emits a report. `execute`/`interactive` are consent-gated.
+
+### App-map maintenance and agent helpers
+
+- **`qa_inspect`** — full attributes of one element. *Inputs:* `sessionId`, `ref` (e.g. `@e3`). *Outputs:* `class`, `id`, `contentDesc`, `text`, `bounds`, the interaction flags (`clickable`/`scrollable`/`focused`/`enabled`/…), and the raw `attrs`. Secret values are redacted and a secure field's value is masked as `«secure»`. Read-only; refs come from the most recent `qa_snapshot` and invalidate after navigation.
+- **`qa_next_best_action`** — deterministic next-step recommendation. *Inputs:* `sessionId`, `goal?` (`smoke`/`explore`/`create_automation_suite`/`release_gate`/`test_login`/`reproduce_bug`). *Outputs:* `nextBestAction` (the `tool`, suggested `args`, and `why`). Read-only.
+- **`qa_app_map_update`** — targeted, provenance-tracked map edits. *Inputs:* `projectRoot?`/`sessionId?` plus any of `note`, `testCases[]`, `automationSuite`, `environment`, `featureCoverage`. *Outputs:* `applied[]` and the `appMapUri`. Recomputes confidence and coverage and persists. Requires an existing map (`qa_app_map_build` first).
 
 ## Recommended Entry Points
 
@@ -260,8 +202,8 @@ Technical detail for the tools added alongside the device-parity, visual-intelli
 | "Read app memory" | `qa_app_map_read` |
 | "Test the X feature" | `qa_test_feature` |
 | "Find/build an artifact" | `qa_resolve_artifact` / `qa_build` |
-| "Create a flow" | `qa_flow_generate` |
-| "Generate automation" | `qa_automation_plan` |
+| "Create a flow" | `qa_generate` with `target:"flow"` |
+| "Generate automation" | `qa_generate` with `target:"appium"` |
 
 ## Extension Pattern
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swipium",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "private": false,
   "description": "Swipium MCP server for simulator-based mobile QA workflows, evidence capture, app maps, and generated test suites.",
   "keywords": [
@@ -28,14 +28,15 @@
   "files": [
     "dist",
     "docs",
-    "THREAT_MODEL.md"
+    "THREAT_MODEL.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/geropalombo/swipium.git"
+    "url": "https://github.com/GeroPalombo/swipium"
   },
   "bugs": {
     "url": "https://github.com/geropalombo/swipium/issues"
@@ -45,14 +46,18 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc && chmod +x dist/index.js",
     "dev": "tsc -w",
     "start": "node dist/index.js",
     "verify": "npm run build && node dist/index.js verify",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "test": "vitest run",
     "audit:prod": "npm audit --omit=dev --audit-level=moderate",
-    "release:check": "npm run typecheck && npm test && npm run audit:prod && npm pack --dry-run",
+    "release:check": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run audit:prod && npm pack --dry-run",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "inspector": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js"
@@ -64,8 +69,12 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^22.10.2",
+    "eslint": "^10.6.0",
+    "prettier": "^3.9.4",
     "typescript": "^5.7.2",
+    "typescript-eslint": "^8.62.1",
     "vitest": "^4.1.7"
   }
 }

package/dist/appMap/diff.js

@@ -1,60 +0,0 @@
-// Map diff (SWIPIUM-REQ-01 qa_app_map_diff). Reports added/removed/changed screens, feature
-// coverage changes, stale test cases, locator-readiness changes, and new untested code areas
-// between two AppKnowledgeMap snapshots. Pure — the tool layer resolves which two maps to compare.
-function ids(arr) {
-    return new Set(arr.map((a) => a.id));
-}
-export function diffAppMaps(baseline, current) {
-    const baseStatic = ids(baseline.staticTopology.screens);
-    const curStatic = ids(current.staticTopology.screens);
-    const baseRuntime = ids(baseline.runtimeTopology.screens);
-    const curRuntime = ids(current.runtimeTopology.screens);
-    const staticAdded = [...curStatic].filter((id) => !baseStatic.has(id));
-    const staticRemoved = [...baseStatic].filter((id) => !curStatic.has(id));
-    const runtimeAdded = [...curRuntime].filter((id) => !baseRuntime.has(id));
-    const runtimeRemoved = [...baseRuntime].filter((id) => !curRuntime.has(id));
-    // changed runtime screens: visits / link / readiness drift
-    const changedScreens = [];
-    const locatorReadinessChanges = [];
-    for (const cur of current.runtimeTopology.screens) {
-        const prev = baseline.runtimeTopology.screens.find((s) => s.id === cur.id || s.signature === cur.signature);
-        if (!prev)
-            continue;
-        if (prev.linkedStaticScreenId !== cur.linkedStaticScreenId) {
-            changedScreens.push({ id: cur.id, field: 'linkedStaticScreenId', was: prev.linkedStaticScreenId ?? null, now: cur.linkedStaticScreenId ?? null });
-        }
-        if (prev.locatorReadiness !== cur.locatorReadiness) {
-            locatorReadinessChanges.push({ id: cur.id, was: prev.locatorReadiness, now: cur.locatorReadiness });
-        }
-    }
-    // feature coverage changes
-    const featureCoverageChanges = [];
-    for (const cur of current.features) {
-        const prev = baseline.features.find((f) => f.id === cur.id);
-        if (prev && prev.testCoverage !== cur.testCoverage) {
-            featureCoverageChanges.push({ featureId: cur.id, was: prev.testCoverage, now: cur.testCoverage });
-        }
-    }
-    // stale tests: cases whose feature/screen no longer exists in current
-    const curFeatureIds = ids(current.features);
-    const staleTests = current.testSuite.cases
-        .filter((c) => (c.featureId && !curFeatureIds.has(c.featureId)) || (c.screenId && !curStatic.has(c.screenId) && !curRuntime.has(c.screenId)) || c.stale)
-        .map((c) => c.id);
-    // new untested code areas: newly added static screens with no linked runtime screen
-    const linkedStatic = new Set(current.runtimeTopology.screens.map((r) => r.linkedStaticScreenId).filter(Boolean));
-    const newUntestedCodeAreas = staticAdded.filter((id) => !linkedStatic.has(id));
-    const summary = `+${staticAdded.length}/-${staticRemoved.length} static screens, +${runtimeAdded.length}/-${runtimeRemoved.length} runtime screens; ` +
-        `${featureCoverageChanges.length} coverage change(s), ${locatorReadinessChanges.length} locator-readiness change(s), ` +
-        `${staleTests.length} stale test(s), ${newUntestedCodeAreas.length} new untested area(s)`;
-    return {
-        staticScreens: { added: staticAdded, removed: staticRemoved },
-        runtimeScreens: { added: runtimeAdded, removed: runtimeRemoved },
-        changedScreens,
-        featureCoverageChanges,
-        locatorReadinessChanges,
-        staleTests,
-        newUntestedCodeAreas,
-        summary,
-    };
-}
-//# sourceMappingURL=diff.js.map

package/dist/appMap/diff.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/appMap/diff.ts"],"names":[],"mappings":"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"}