@aarwitz/tapp 0.15.0

package/AGENTS.md

@@ -0,0 +1,123 @@
+# 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.
+
+## No MCP connected? Just run the CLI
+
+Every core capability works as a plain command — no server, no config. `[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 (qa only) an http(s) URL. You never need to know a bundle id up front.
+
+```bash
+npx -y @aarwitz/tapp qa [target]     # autonomous QA → ship/no-ship verdict + findings (≈ tapp_run_qa)
+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 qa app.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp flow run .autotap/flows/smoke.yml  # committed, keyless E2E replay
+```
+
+**Seeing the screen, per client:** if you can read image files into your context (Claude
+Code's Read tool, Codex's view-image), open the saved screenshot path the CLI prints —
+that IS the screen. If you cannot (Cursor, VS Code Copilot), connect the MCP server
+instead: its tool results carry the screenshot inline. Screen *recordings* are for the
+human: `tapp qa` records the full exploration and embeds it in the report.html evidence
+page — tell the user the report path so they can watch it.
+
+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
+MCP, the no-bundle-id path is: `tapp_build {projectDir}` (auto-detects + builds +
+installs, returns the bundle id) → `tapp_run_qa {appBundleId}`.
+
+## Pick the right tool for the job
+
+| The user wants… | Use | NOT |
+|---|---|---|
+| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_run_qa` (a full multi-minute QA exploration) |
+| "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? Is it ship-ready? Find bugs" | `tapp_run_qa` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps | a manual session (QA 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 |
+| "What's on screen right now?" | `tapp_screenshot` / `tapp_ui_tree` | relaunching the app |
+
+## Session driving (the Playwright loop)
+
+```
+tapp_session_start { appBundleId: "com.acme.app" }     → fresh launch + initial tree
+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" }
+tapp_session_act   { action: "wait", text: "Home", timeoutMs: 10000 }  → block until it appears
+tapp_screenshot                                          → see it
+tapp_session_end
+```
+
+Android uses the same loop with `tapp_session_start { androidAppId: "com.acme.app", apkPath:
+"path/to/app.apk" }`. Android selectors prefer resource id, then content description, exact text,
+and text contains. The APK/app id replace the iOS bundle/simulator build inputs.
+
+Rules that prevent 90% of failures:
+
+1. **Read `elements[]` from the previous result before tapping.** Ids and labels shift between
+   builds — never tap from memory. `tap` matches accessibility id, exact label, or a forgiving
+   case-insensitive contains; `{x, y}` coordinates are the last resort.
+2. **Check `hittable`.** A disabled control shows `hittable: false` — a Submit button that won't
+   tap usually means the form isn't validly filled, not that the button is missing. Fill the
+   fields first.
+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.
+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.
+
+## Autonomous QA (`tapp_run_qa`)
+
+Returns `{verdict, confidence, headline, screensExplored, actionsPerformed, findings[]}`.
+
+- `verdict`: `ready` | `caution` | `blocked`. **Trust it — it's deterministic.** Report it to the
+  user as-is; never soften a `blocked` or inflate a `caution`.
+- `inconclusive: true` means the run couldn't see enough (crash on launch, login wall). That is
+  **not a pass** — tell the user what blocked exploration and what would unblock it.
+- Login walls: pass `testEmail`/`testPassword` (auto-typed into login forms), `appLaunchArgs`
+  (e.g. `["--uitesting"]` if the app has a test bypass), and/or `appLaunchEnv` (e.g. a staging
+  backend URL). If the result shows `inputFieldsEncountered` and you have no credentials, **ask
+  the user** for them rather than re-running blind.
+- Diff two runs: pass the previous run's `findings` as `baselineFindings` → you get a
+  `regression` block (`new` / `persisting` / `resolved`, plus a CI `gate` signal).
+
+## Flows (deterministic E2E tests)
+
+Flow YAML is repository-native test code. Commit it under `.autotap/flows/`; CI can replay it
+without a coding agent, model, subscription, or API key. AI generation and `assert_ai` are optional.
+
+- **Record:** every successful `session_act` is recorded. After driving a flow, call
+  `tapp_flow_save { name: "checkout" }` → writes `.autotap/flows/checkout.yml` with waits and
+  a final screen assertion auto-inserted; typed credentials are templated to `$TEST_EMAIL`/`$TEST_PASSWORD`.
+- **Replay:** `tapp_flow_run { flowPath: ".autotap/flows/checkout.yml" }` — exact steps,
+  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.
+
+## Setup facts (tell the user when relevant)
+
+- iOS runs locally on a Mac with Xcode + a simulator. Android needs `adb` and a connected
+  emulator/device. Web needs Playwright + Chromium. `tapp doctor` reports each capability.
+- First tool call builds the test harness once (~2 min, cached in `~/.tapp`). `tapp install`
+  prebuilds it. Switching simulators triggers an automatic rebuild.
+- The app under test must be **installed on the booted simulator** (`tapp_install_app` builds
+  and installs from an Xcode project/workspace; or the user's normal build).
+- A simulator must be booted (`tapp_list_simulators` → `tapp_boot_simulator`).
+- Screenshots/captures land in `~/.tapp/captures/`.
+
+## Honesty rules
+
+- Never claim a screen/flow works without having actually driven or seen it via these tools.
+- If a tool call fails twice for the same reason, stop and tell the user what's failing instead
+  of retrying variations.
+- When you show a screenshot as proof, say what it proves and what it doesn't ("login works;
+  I haven't verified checkout").

package/Harness/OCQAHarness/AppDelegate.swift

@@ -0,0 +1,21 @@
+import UIKit
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    var window: UIWindow?
+    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        window = UIWindow(frame: UIScreen.main.bounds)
+        let vc = UIViewController()
+        vc.view.backgroundColor = .black
+        let label = UILabel()
+        label.text = "AutoTap Harness"
+        label.textColor = .white
+        label.textAlignment = .center
+        label.frame = vc.view.bounds
+        label.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        vc.view.addSubview(label)
+        window?.rootViewController = vc
+        window?.makeKeyAndVisible()
+        return true
+    }
+}

package/Harness/OCQAHarness/Info.plist

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleDevelopmentRegion</key>
+    <string>en</string>
+    <key>CFBundleExecutable</key>
+    <string>$(EXECUTABLE_NAME)</string>
+    <key>CFBundleIdentifier</key>
+    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>$(PRODUCT_NAME)</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>LSRequiresIPhoneOS</key>
+    <true/>
+    <key>UILaunchStoryboardName</key>
+    <string></string>
+</dict>
+</plist>

package/Harness/OCQAHarness.xcodeproj/project.pbxproj

@@ -0,0 +1,199 @@
+// !$*UTF8*$!
+{
+  archiveVersion = 1;
+  classes = {};
+  objectVersion = 56;
+  objects = {
+    5D7C13C377373C4980FC8162 /* Project object */ = {
+      isa = PBXProject;
+      buildConfigurationList = C03EC97124C7DA0EE83E045B;
+      compatibilityVersion = "Xcode 14.0";
+      developmentRegion = en;
+      hasScannedForEncodings = 0;
+      knownRegions = (en, Base);
+      mainGroup = 97B474EE87109F337A5EDB45;
+      productRefGroup = 9A2A24D8F8E06032696AC411;
+      projectDirPath = "";
+      projectRoot = "";
+      targets = (
+        EAC02A5E44291747D888CAF7,
+        8FD0002A75D948EE79C4FDEB,
+      );
+    };
+
+    /* Main Group */
+    97B474EE87109F337A5EDB45 = {
+      isa = PBXGroup;
+      children = (
+        D5E75DDC871BCC9FA4AEB33A,
+        F1804B339745969BC4D5BD0E,
+        9A2A24D8F8E06032696AC411,
+      );
+      sourceTree = "<group>";
+    };
+    9A2A24D8F8E06032696AC411 = {
+      isa = PBXGroup;
+      children = (
+        9CEBAC16BBBB2096CF6736B7,
+        4596C27A89AAB1291984CE15,
+      );
+      name = Products;
+      sourceTree = "<group>";
+    };
+    D5E75DDC871BCC9FA4AEB33A = {
+      isa = PBXGroup;
+      children = (
+        EC2E72351C49E8A03B62A7E4,
+        C4EFB6D8BCD48E1E7CF4723F,
+      );
+      path = OCQAHarness;
+      sourceTree = "<group>";
+    };
+    F1804B339745969BC4D5BD0E = {
+      isa = PBXGroup;
+      children = (
+        02DDFAC1CE151BA9E8F1F2B0,
+        6C52E22A95C5BC114BD89C1D,
+      );
+      path = OCQAHarnessUITests;
+      sourceTree = "<group>";
+    };
+
+    /* File References */
+    EC2E72351C49E8A03B62A7E4 = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AppDelegate.swift; sourceTree = "<group>";};
+    C4EFB6D8BCD48E1E7CF4723F = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>";};
+    02DDFAC1CE151BA9E8F1F2B0 = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ExplorerTests.swift; sourceTree = "<group>";};
+    6C52E22A95C5BC114BD89C1D = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>";};
+    9CEBAC16BBBB2096CF6736B7 = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = OCQAHarness.app; sourceTree = BUILT_PRODUCTS_DIR;};
+    4596C27A89AAB1291984CE15 = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = OCQAHarnessUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR;};
+
+    /* Build Files */
+    F58B8DB8FD10B48DA02F1FFE = {isa = PBXBuildFile; fileRef = EC2E72351C49E8A03B62A7E4;};
+    A66AE9116198ABFF81B3301F = {isa = PBXBuildFile; fileRef = 02DDFAC1CE151BA9E8F1F2B0;};
+
+    /* Source Build Phases */
+    3720DF3EB78B382E01A0C583 = {
+      isa = PBXSourcesBuildPhase;
+      buildActionMask = 2147483647;
+      files = (F58B8DB8FD10B48DA02F1FFE,);
+      runOnlyForDeploymentPostprocessing = 0;
+    };
+    40E8D5BE7C3857702461130C = {
+      isa = PBXSourcesBuildPhase;
+      buildActionMask = 2147483647;
+      files = (A66AE9116198ABFF81B3301F,);
+      runOnlyForDeploymentPostprocessing = 0;
+    };
+
+    /* Frameworks Build Phases */
+    6946B0A403DA0818C6E59688 = {isa = PBXFrameworksBuildPhase; buildActionMask = 2147483647; files = (); runOnlyForDeploymentPostprocessing = 0;};
+    EC7DD5037A711664C61227B4 = {isa = PBXFrameworksBuildPhase; buildActionMask = 2147483647; files = (); runOnlyForDeploymentPostprocessing = 0;};
+
+    /* App Target */
+    EAC02A5E44291747D888CAF7 = {
+      isa = PBXNativeTarget;
+      buildConfigurationList = 941C8F0B572C7E6F731288EB;
+      buildPhases = (3720DF3EB78B382E01A0C583, 6946B0A403DA0818C6E59688,);
+      buildRules = ();
+      dependencies = ();
+      name = OCQAHarness;
+      productName = OCQAHarness;
+      productReference = 9CEBAC16BBBB2096CF6736B7;
+      productType = "com.apple.product-type.application";
+    };
+
+    /* Test Target */
+    8FD0002A75D948EE79C4FDEB = {
+      isa = PBXNativeTarget;
+      buildConfigurationList = E7719FBBADD636B07F6C0F19;
+      buildPhases = (40E8D5BE7C3857702461130C, EC7DD5037A711664C61227B4,);
+      buildRules = ();
+      dependencies = (F61C75ED91EE51D617FF76C2,);
+      name = OCQAHarnessUITests;
+      productName = OCQAHarnessUITests;
+      productReference = 4596C27A89AAB1291984CE15;
+      productType = "com.apple.product-type.bundle.ui-testing";
+    };
+
+    /* Target Dependency */
+    F61C75ED91EE51D617FF76C2 = {
+      isa = PBXTargetDependency;
+      target = EAC02A5E44291747D888CAF7;
+      targetProxy = 7BC3CFD1F9B18D721886DD65;
+    };
+    7BC3CFD1F9B18D721886DD65 = {
+      isa = PBXContainerItemProxy;
+      containerPortal = 5D7C13C377373C4980FC8162;
+      proxyType = 1;
+      remoteGlobalIDString = EAC02A5E44291747D888CAF7;
+      remoteInfo = OCQAHarness;
+    };
+
+    /* Build Configurations */
+    C03EC97124C7DA0EE83E045B = {
+      isa = XCConfigurationList;
+      buildConfigurations = (1BF3C243D6F4582A4C00E8E6,);
+      defaultConfigurationIsVisible = 0;
+      defaultConfigurationName = Debug;
+    };
+    1BF3C243D6F4582A4C00E8E6 = {
+      isa = XCBuildConfiguration;
+      buildSettings = {
+        ALWAYS_SEARCH_USER_PATHS = NO;
+        CLANG_ENABLE_MODULES = YES;
+        CODE_SIGN_IDENTITY = "-";
+        CODE_SIGN_STYLE = Automatic;
+        DEVELOPMENT_TEAM = "";
+        ENABLE_TESTABILITY = YES;
+        IPHONEOS_DEPLOYMENT_TARGET = 16.0;
+        SDKROOT = iphoneos;
+        SWIFT_VERSION = 5.0;
+        TARGETED_DEVICE_FAMILY = "1,2";
+      };
+      name = Debug;
+    };
+    941C8F0B572C7E6F731288EB = {
+      isa = XCConfigurationList;
+      buildConfigurations = (426B4A04FEDF3507EE7B512F,);
+      defaultConfigurationIsVisible = 0;
+      defaultConfigurationName = Debug;
+    };
+    426B4A04FEDF3507EE7B512F = {
+      isa = XCBuildConfiguration;
+      buildSettings = {
+        ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+        CODE_SIGN_IDENTITY = "-";
+        CODE_SIGN_STYLE = Automatic;
+        DEVELOPMENT_TEAM = "";
+        INFOPLIST_FILE = OCQAHarness/Info.plist;
+        PRODUCT_BUNDLE_IDENTIFIER = ai.autotap.harness;
+        PRODUCT_NAME = "$(TARGET_NAME)";
+        SWIFT_VERSION = 5.0;
+        TARGETED_DEVICE_FAMILY = "1,2";
+      };
+      name = Debug;
+    };
+    E7719FBBADD636B07F6C0F19 = {
+      isa = XCConfigurationList;
+      buildConfigurations = (BF02330ED7194B20B63DC653,);
+      defaultConfigurationIsVisible = 0;
+      defaultConfigurationName = Debug;
+    };
+    BF02330ED7194B20B63DC653 = {
+      isa = XCBuildConfiguration;
+      buildSettings = {
+        CODE_SIGN_IDENTITY = "-";
+        CODE_SIGN_STYLE = Automatic;
+        DEVELOPMENT_TEAM = "";
+        INFOPLIST_FILE = OCQAHarnessUITests/Info.plist;
+        PRODUCT_BUNDLE_IDENTIFIER = ai.autotap.harness.uitests;
+        PRODUCT_NAME = "$(TARGET_NAME)";
+        SWIFT_VERSION = 5.0;
+        TARGETED_DEVICE_FAMILY = "1,2";
+        TEST_TARGET_NAME = OCQAHarness;
+      };
+      name = Debug;
+    };
+  };
+  rootObject = 5D7C13C377373C4980FC8162;
+}

package/Harness/OCQAHarness.xcodeproj/xcshareddata/xcschemes/OCQAHarnessUITests.xcscheme

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme LastUpgradeVersion = "1620" version = "1.7">
+   <BuildAction parallelizeBuildables = "YES" buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry buildForTesting = "YES" buildForRunning = "YES" buildForProfiling = "YES" buildForArchiving = "YES" buildForAnalyzing = "YES">
+            <BuildableReference BuildableIdentifier = "primary" BlueprintIdentifier = "8FD0002A75D948EE79C4FDEB" BuildableName = "OCQAHarnessUITests.xctest" BlueprintName = "OCQAHarnessUITests" ReferencedContainer = "container:OCQAHarness.xcodeproj"/>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction buildConfiguration = "Debug" selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB" selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB" shouldUseLaunchSchemeArgsEnv = "YES">
+      <Testables>
+         <TestableReference skipped = "NO">
+            <BuildableReference BuildableIdentifier = "primary" BlueprintIdentifier = "8FD0002A75D948EE79C4FDEB" BuildableName = "OCQAHarnessUITests.xctest" BlueprintName = "OCQAHarnessUITests" ReferencedContainer = "container:OCQAHarness.xcodeproj"/>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction buildConfiguration = "Debug" selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB" selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB" launchStyle = "0" useCustomWorkingDirectory = "NO" ignoresPersistentStateOnLaunch = "NO" debugDocumentVersioning = "YES" debugServiceExtension = "internal" allowLocationSimulation = "YES">
+      <BuildableProductRunnable runnableDebuggingMode = "0">
+         <BuildableReference BuildableIdentifier = "primary" BlueprintIdentifier = "EAC02A5E44291747D888CAF7" BuildableName = "OCQAHarness.app" BlueprintName = "OCQAHarness" ReferencedContainer = "container:OCQAHarness.xcodeproj"/>
+      </BuildableProductRunnable>
+   </LaunchAction>
+</Scheme>