@aarwitz/tapp 0.17.0-rc.9 → 0.17.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "name": "tapp",
+  "description": "The official Tapp plugin: the agent skill and MCP tools for testing real iOS, Android, and web app surfaces.",
+  "owner": {
+    "name": "Aaron Horowitz",
+    "url": "https://github.com/aarwitz"
+  },
+  "plugins": [
+    {
+      "name": "tapp",
+      "source": {
+        "source": "npm",
+        "package": "@aarwitz/tapp"
+      },
+      "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
+      "author": {
+        "name": "Aaron Horowitz",
+        "url": "https://github.com/aarwitz"
+      },
+      "homepage": "https://runtapp.com/",
+      "license": "MIT",
+      "keywords": [
+        "ios",
+        "simulator",
+        "testing",
+        "qa",
+        "xcuitest",
+        "mcp",
+        "agent-skill",
+        "copilot"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "tapp",
+  "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
+  "version": "0.17.1",
+  "author": {
+    "name": "Aaron Horowitz",
+    "url": "https://github.com/aarwitz"
+  },
+  "homepage": "https://runtapp.com/",
+  "repository": "https://github.com/aarwitz/tapp",
+  "license": "MIT",
+  "keywords": [
+    "ios",
+    "simulator",
+    "testing",
+    "qa",
+    "xcuitest",
+    "mcp",
+    "agent-skill",
+    "copilot"
+  ],
+  "mcpServers": {
+    "tapp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@aarwitz/tapp@0.17.1",
+        "mcp"
+      ],
+      "cwd": "${CLAUDE_PROJECT_DIR}"
+    }
+  }
+}

package/AGENTS.md

@@ -1,26 +1,41 @@
 # Tapp agent playbook
 
-You (the agent) have Tapp: hands, eyes, and judgment on real app surfaces — iOS simulators,
-Android emulators/devices, plus (beta) web apps in a real browser.
+You (the agent) have Tapp: hands and eyes on real app surfaces — iOS simulators, Android
+emulators/devices, plus (beta) web apps in a real browser. Release judgment belongs only to Tapp's
+repository-connected deterministic gate.
 
 ## No MCP connected? Just run the CLI
 
-Every core capability works as a plain command — no server, no config. `[target]` is
+The core inspect, explore, replay, and gate capabilities work as plain commands — no Tapp account,
+server, or global install. `[target]` is
 optional: with nothing, tapp finds + builds the Xcode project in the cwd (or falls back to
 the app already on the simulator); it also accepts a repo dir, a `path/to/App.app`, a
 bundle id, or (web) an http(s) URL. You never need to know a bundle id up front.
 
 ```bash
-npx -y @aarwitz/tapp explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
-npx -y @aarwitz/tapp open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
-npx -y @aarwitz/tapp tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
-npx -y @aarwitz/tapp shot            # screenshot the booted sim → file path (≈ tapp_screenshot)
-npx -y @aarwitz/tapp apps            # what's installed on the simulator, with bundle ids
-npx -y @aarwitz/tapp build [dir]     # build the app in an Xcode repo + install it (≈ tapp_build)
-npx -y @aarwitz/tapp explore app.apk --platform android --app-id com.acme.app
-npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
+npx -y @aarwitz/tapp@latest explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
+npx -y @aarwitz/tapp@latest focus "SCREEN OR CONTROL" [target] # source-locate + shortest observed route + screenshot
+npx -y @aarwitz/tapp@latest explore https://your-app.example --watch  # web: visibly follow the same exploration
+npx -y @aarwitz/tapp@latest open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
+npx -y @aarwitz/tapp@latest tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
+npx -y @aarwitz/tapp@latest shot            # screenshot the booted sim → file path (≈ tapp_screenshot)
+npx -y @aarwitz/tapp@latest apps            # what's installed on the simulator, with bundle ids
+npx -y @aarwitz/tapp@latest build [dir]     # build the app in an Xcode repo + install it (≈ tapp_build)
+npx -y @aarwitz/tapp@latest explore app.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
+If repository onboarding detects multiple application targets, target detection is deterministic but
+the choice is the user's. Explicit `init --explore` asks even when the model has a saved default; a
+later bare `explore` may consume that default. In a human TTY, Tapp displays a numbered selector and
+continues in the same command. A non-interactive CLI prints the exact choices and exits before
+building. MCP returns
+`reason: "target-selection-required"` with structured `choices[]` (`platform`, `name`, `sourcePath`,
+`selector`, and exact `command`). **Do not pick one yourself.** Present those choices to the user
+with the client's native multiple-choice question UI when available, then rerun using the selected
+`--platform` and `--target`. Plain chat can list the same choices when the client has no question
+widget.
+
 For focused web evidence, `open` and `tree` accept one semantic interaction plus an async content
 wait: `tapp open https://example.com --tap "Not now" --wait-for "Dashboard"`. Tapp waits for the
 page to stabilize before capturing it and warns honestly if the bounded wait ends while it is still
@@ -32,7 +47,9 @@ that IS the screen. If you cannot (Cursor, VS Code Copilot), connect the MCP ser
 instead: its tool results carry the screenshot inline. Screen *recordings* are for the
 human: on **iOS**, `tapp explore` records the full exploration and embeds it in the report.html
 evidence page (Android does not currently record video) — tell the user the report path so they can
-watch it.
+watch it. On **web**, explicit `--watch` opens the isolated Playwright Chromium window and overlays
+Tapp's current action and pointer; the overlay is omitted from evidence screenshots. It does not
+drive the person's existing/default browser profile.
 
 The interactive session/record loop is MCP-only (it needs a long-lived process). Flow replay is
 also available in the CLI. The rest of this playbook assumes the `tapp_*` MCP tools are connected. With
@@ -43,7 +60,8 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 | The user wants… | Use | NOT |
 |---|---|---|
-| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute QA exploration) |
+| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute exploration) |
+| "Find/reach this named screen or control" | `tapp_session_start` with `focus`, or `tapp_focus`; plain CLI: `tapp focus` | screenshot-by-screenshot wandering |
 | "Tap through / drive / fill a form / log in" | `tapp_session_start` → `session_act` loop | repeated `open_app` calls (cold relaunch each time) |
 | "Is my app broken? Find bugs" | `tapp_explore` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; returns an observation (findings + evidence), not a ship verdict — gate a merge with the CI gate (`tapp ci` CLI / the GitHub Action) + a contract | a manual session (exploration is autonomous) |
 | "Make this flow a repeatable test" | drive it in a session, then `tapp_flow_save`; replay with `tapp_flow_run` | re-driving it by hand every time |
@@ -51,8 +69,16 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 ## Session driving (the Playwright loop)
 
+After an initial grounding exploration, use the source-connected fast path for any named
+destination. Tapp searches the repository, matches the requested surface to `.tapp/ui-map.json`, and executes only the shortest
+runtime-observed route. Source tells Tapp where intent lives; observed UI evidence authorizes taps.
+If it returns source evidence without a route, inspect the cited file/navigation source—do not
+wander blindly or invent a route. URL-only targets correctly have no source advantage.
+
 ```
-tapp_session_start { appBundleId: "com.acme.app" }     → fresh launch + initial tree
+tapp_session_start { appBundleId: "com.acme.app", focus: "Save storefront settings visible above keyboard", projectDir: "." }
+tapp_focus         { query: "Save storefront settings visible above keyboard" } → one-call shortest observed route
+tapp_session_act   { action: "login", email: "qa@x.com", password: "…" } → atomic fill + submit + verify
 tapp_session_act   { action: "tap",  id: "Email" }      → tap by a11y id OR visible label
 tapp_session_act   { action: "type", text: "qa@x.com" } → types into the focused field
 tapp_session_act   { action: "tap",  id: "Sign In" }
@@ -76,7 +102,8 @@ Rules that prevent 90% of failures:
 3. **`wait` after anything async** (navigation, network loads): `{action: "wait", id|text, timeoutMs}`.
    Never assume the next screen is instantly there.
 4. **Tap the field before typing** — `type` goes to the focused field. Tap email → type email →
-   tap password → type password.
+   tap password → type password. For sign-in, prefer the atomic `login` action: it records a
+   secret-templated replay step and avoids native secure-field refocus behavior.
 5. Tap results: `ok` (landed), `not_hittable` (exists but disabled/covered — the harness
    auto-dismisses keyboards and retries), `not_found` (nothing matches — re-read the tree).
 6. One session at a time. `session_start` always begins from a fresh app launch.
@@ -120,6 +147,8 @@ without a coding agent, model, subscription, or API key. AI generation and `asse
   deterministic assertions, same result every time. A failed assertion is a finding.
 - **Generate:** `tapp_flow_generate { goal: "log in and add the first item to cart" }` —
   grounded in the app's actually-explored screens, so it can't invent steps.
+- **Discover the file format without MCP:** `npx -y @aarwitz/tapp@latest flow example` prints a
+  complete starter Flow; `tapp flow validate <file>` checks it without launching a target.
 
 ## Setup facts (tell the user when relevant)
 

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -82,6 +82,31 @@ class ExplorerTests: XCTestCase {
         return fallback
     }
 
+    /// Opens the visual-evidence boundary only after the target app is foregrounded and its first
+    /// UI has settled. The host starts simulator recording (and clients may reveal a live preview)
+    /// at this point, then acknowledges it. The wait is deliberately bounded: video/preview
+    /// failure must never prevent the actual exploration from running.
+    private func signalSettledVisualReady() {
+        let readyPath = resolve("OCQA_VISUAL_READY_PATH")
+        guard !readyPath.isEmpty else { return }
+        let readyURL = URL(fileURLWithPath: readyPath)
+        try? FileManager.default.createDirectory(at: readyURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+        try? Data("ready\n".utf8).write(to: readyURL, options: .atomic)
+        print("OCQA_STATE:visual_ready")
+
+        let startedPath = resolve("OCQA_RECORDING_STARTED_PATH")
+        guard !startedPath.isEmpty else { return }
+        let deadline = Date().addingTimeInterval(5.0)
+        while Date() < deadline && !FileManager.default.fileExists(atPath: startedPath) {
+            Thread.sleep(forTimeInterval: 0.05)
+        }
+        if FileManager.default.fileExists(atPath: startedPath) {
+            print("OCQA_STATE:visual_capture_started")
+        } else {
+            print("OCQA_STATE:visual_capture_ack_timeout")
+        }
+    }
+
     private func loadConfig() {
         // OCQA_CONFIG_PATH (forwarded from the host via TEST_RUNNER_OCQA_CONFIG_PATH) is
         // authoritative and per-run — checked FIRST so each device reads its own config and
@@ -585,14 +610,34 @@ class ExplorerTests: XCTestCase {
     /// the password it just typed.
     private func sessionLogin(email: String, password: String) -> (status: String, detail: String) {
         waitForUIStability(timeout: 2.0)
-        let textFields = app.textFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
-        let secureFields = app.secureTextFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
-        let emailField = textFields.first { f in
-            let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
-            return hint.contains("email") || hint.contains("e-mail") || hint.contains("user")
-        } ?? (secureFields.isEmpty ? nil : textFields.first)
+        // A recorded Flow invokes login immediately after a cold launch, while a human-driven
+        // session naturally invokes it after inspecting the first tree. Poll the SAME finder for
+        // a bounded interval so those two entry paths behave identically when login fields appear
+        // after an asynchronous launch transition.
+        var textFields: [XCUIElement] = []
+        var secureFields: [XCUIElement] = []
+        var emailField: XCUIElement?
+        var passwordField: XCUIElement?
+        let fieldsDeadline = Date().addingTimeInterval(8.0)
+        repeat {
+            textFields = app.textFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
+            secureFields = app.secureTextFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
+            let plainPasswordIndex = textFields.firstIndex { f in
+                let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
+                return hint.contains("password") || hint.contains("passcode")
+            }
+            passwordField = secureFields.first ?? plainPasswordIndex.map { textFields[$0] }
+            emailField = textFields.first { f in
+                let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
+                return hint.contains("email") || hint.contains("e-mail") || hint.contains("user")
+            } ?? textFields.enumerated().first(where: { index, _ in
+                passwordField != nil && (plainPasswordIndex.map { index != $0 } ?? true)
+            })?.element
+            if emailField != nil && passwordField != nil { break }
+            Thread.sleep(forTimeInterval: 0.25)
+        } while Date() < fieldsDeadline
         guard let emailF = emailField else { return ("no_login_form", "no email/username field visible") }
-        guard let passF = secureFields.first else { return ("no_login_form", "no password (secure) field visible") }
+        guard let passF = passwordField else { return ("no_login_form", "no password field visible") }
 
         replaceText(on: emailF, with: email)
         replaceText(on: passF, with: password)
@@ -765,6 +810,12 @@ class ExplorerTests: XCTestCase {
             case "type":
                 status = sessionType(value, id: target.isEmpty ? nil : target) ? "pass" : "fail"
                 if status == "fail" { detail = "no field ‘\(target)’ to type into" }
+            case "login":
+                let email = subst((step["email"] as? String) ?? "$TEST_EMAIL")
+                let password = subst((step["password"] as? String) ?? "$TEST_PASSWORD")
+                let result = sessionLogin(email: email, password: password)
+                status = result.status == "ok" ? "pass" : "fail"
+                if status == "fail" { detail = result.detail.isEmpty ? result.status : result.detail }
             case "swipe":
                 switch target.lowercased() { case "down": app.swipeDown(); case "left": app.swipeLeft(); case "right": app.swipeRight(); default: app.swipeUp() }
             case "back":
@@ -1025,10 +1076,17 @@ class ExplorerTests: XCTestCase {
         _ = app.descendants(matching: .any).firstMatch.waitForExistence(timeout: 3)
         _ = waitForUIStability(timeout: 2.0)
 
+        signalSettledVisualReady()
+
         print("OCQA_STATE:exploration_started max_actions=\(maxActions)")
 
         let testEmail = resolve("OCQA_TEST_EMAIL")
         let testPassword = resolve("OCQA_TEST_PASSWORD")
+        if resolve("OCQA_CREDENTIALS_EXPLICIT") == "1" {
+            // Presence only: never print, persist, or expose credential values. Report rebuilding
+            // needs this durable marker to distinguish "not supplied" from "supplied but unused".
+            print("OCQA_STATE:credentials_supplied")
+        }
 
         // --- Explicit login replay (config-driven): a recorded type/tap/wait sequence for custom
         // login UIs the heuristic preamble below can't parse. When configured it takes precedence. ---