@aarwitz/tapp 0.17.0-rc.8 → 0.17.0

package/skills/tapp/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: tapp
+description: Use Tapp to see, drive, explore, and verify real application surfaces on iOS simulators, Android emulators/devices, or the web. Use when a user asks an agent to test an app or UI change, find bugs, inspect or screenshot a screen, exercise a journey, create a replayable flow, gather release evidence, or run the deterministic Tapp gate. Also use when the user mentions Tapp, @aarwitz/tapp, tapp_* tools, .tapp artifacts, or asks whether agent-authored UI actually works.
+---
+
+# Tapp
+
+Use Tapp as the app's hands and eyes. Work on the real UI surface and show evidence; do not claim a
+screen or journey works from source inspection alone.
+
+## Choose the smallest operation
+
+| Intent | Operation |
+|---|---|
+| See or screenshot one screen | `open` / `tapp_open_app` |
+| Inspect controls on the current screen | `tree` / `tapp_ui_tree` |
+| Drive a specific journey | MCP session start → act → end |
+| Find bugs autonomously | `explore` / `tapp_explore` |
+| Preserve a journey | record and save a Flow; replay it deterministically |
+| Decide whether a merge passes policy | `ci`; exploration never decides this |
+
+Prefer connected `tapp_*` MCP tools when available: they keep interactive sessions alive and return
+screenshots inline. Otherwise run `npx -y @aarwitz/tapp@latest` from the app repository. Do not require MCP,
+an account, an API key, or a global install for the core workflow.
+
+## Start source-connected
+
+When the user asks for a general first test of a repository:
+
+1. If `.tapp/application-model.json` exists, run `npx -y @aarwitz/tapp@latest explore`.
+2. Otherwise run `npx -y @aarwitz/tapp@latest init . --explore` or call `tapp_init` with
+   `{operation:"explore", projectDir:"."}`.
+3. If Tapp returns `target-selection-required`, present its actual choices and ask the user to pick.
+   Never guess among multiple targets. Re-run with the selected platform/target exactly as Tapp
+   instructs.
+4. If a prerequisite is missing, call `tapp_health` when MCP is connected or run
+   `npx -y @aarwitz/tapp@latest doctor`, apply only the stated remediation that is in scope, and
+   retry once.
+
+For a focused request, use the requested target directly rather than forcing repository onboarding.
+Targets may be a repository path, Xcode container, `.app`, iOS bundle id, APK plus Android app id,
+or owned HTTP(S) URL. Never explore a third-party web property without authorization: exploration
+clicks and types.
+
+## Observe honestly
+
+Exploration returns findings, coverage, evidence, and `inconclusive`; it does not return a score or
+ship verdict. Report:
+
+- target and platform;
+- screens/actions and whether coverage was conclusive;
+- deterministic versus advisory finding counts;
+- each important finding and its evidence/report path;
+- what Tapp explicitly did not check.
+
+If `inconclusive: true`, explain the blocker. A login wall or missing test data is not a pass. Ask for
+credentials or launch configuration instead of rerunning blindly. Do not infer content accuracy,
+privacy, brand consistency, or business guarantees from a generic crawl; those require a reviewed
+Flow, Scenario, contract, verifier, or human review.
+
+When a screenshot path is printed, open it with the client's image-reading tool before describing
+the screen. For web, use `--watch` when the human wants to follow Tapp's controlled browser. For iOS,
+point the human to the report's exploration recording when available.
+
+## Drive safely
+
+For an interactive MCP session, read returned `elements[]` before every action, target accessibility
+ids or visible labels, check `hittable`, tap a field before typing, and wait for navigation or async
+content. Use coordinates only as a last resort. End the session when finished.
+
+Do not edit the app merely because testing found a defect unless the user also asked for a fix. State
+what the evidence proves and what remains untested.
+
+Read [references/commands.md](references/commands.md) only when exact CLI/MCP syntax, Flow replay,
+credentials, or platform prerequisites are needed.

package/skills/tapp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Tapp"
+  short_description: "Test real iOS, Android, and web apps"
+  default_prompt: "Use $tapp to test this app on its real UI surface and report evidence-backed findings."

package/skills/tapp/references/commands.md

@@ -0,0 +1,102 @@
+# Tapp command reference
+
+## Plain CLI
+
+Run from the application repository. `[target]` is optional when Tapp can read the repository model
+or detect one unambiguous target.
+
+```bash
+npx -y @aarwitz/tapp@latest init . --explore
+npx -y @aarwitz/tapp@latest explore [target]
+npx -y @aarwitz/tapp@latest open [target]
+npx -y @aarwitz/tapp@latest tree [target] --json
+npx -y @aarwitz/tapp@latest shot
+npx -y @aarwitz/tapp@latest report latest
+npx -y @aarwitz/tapp@latest doctor
+```
+
+Platform examples:
+
+```bash
+# Web: Tapp may build/start/stop a source target; --watch is human-visible.
+npx -y @aarwitz/tapp@latest explore --platform web --target website --watch
+npx -y @aarwitz/tapp@latest explore https://staging.example.com
+
+# iOS: source repo, .app, or bundle id.
+npx -y @aarwitz/tapp@latest explore MyApp.xcodeproj --platform ios
+npx -y @aarwitz/tapp@latest open com.example.MyApp --platform ios
+
+# Android: app id is required; APK is optional if already installed.
+npx -y @aarwitz/tapp@latest explore app-debug.apk --platform android --app-id com.example.app
+```
+
+Focused web evidence can perform one semantic interaction and wait for async content:
+
+```bash
+npx -y @aarwitz/tapp@latest open https://example.com --tap "Not now" --wait-for "Dashboard"
+```
+
+## MCP mapping
+
+- `tapp_init`: inspect or initialize a source repository; `operation:"explore"` prepares and explores.
+- `tapp_build`: build and install an iOS app without needing its bundle id first.
+- `tapp_open_app`: launch and return a screen summary plus inline screenshot.
+- `tapp_ui_tree` / `tapp_screenshot`: inspect the current real surface.
+- `tapp_session_start` → `tapp_session_act` → `tapp_session_end`: drive one persistent journey.
+- `tapp_explore`: autonomous iOS, Android, or web exploration; observation only.
+- `tapp_flow_save` / `tapp_flow_run`: save a driven journey and replay it deterministically.
+- `tapp_release_contract`: validate, compile, or run a reviewed business guarantee.
+- `tapp_ci_setup`: create a target-scoped baseline or reviewable CI installation.
+
+An iOS no-bundle-id MCP path is `tapp_build {projectDir:"."}` followed by `tapp_explore` with the
+returned `bundleId`. Android uses `androidAppId` and optional `apkPath`; web uses `url` or
+source-connected `tapp_init`.
+
+## Interactive session loop
+
+```text
+tapp_session_start {appBundleId:"com.example.app"}
+tapp_session_act   {action:"tap", id:"Email"}
+tapp_session_act   {action:"type", text:"qa@example.com"}
+tapp_session_act   {action:"tap", id:"Password"}
+tapp_session_act   {action:"type", text:"..."}
+tapp_session_act   {action:"tap", id:"Sign In"}
+tapp_session_act   {action:"wait", text:"Home", timeoutMs:10000}
+tapp_screenshot
+tapp_session_end
+```
+
+Android sessions use `androidAppId`, optional `apkPath`, and the same action loop.
+
+## Credentials and test configuration
+
+For autonomous exploration, pass test-only values when authorized:
+
+- CLI: `--email`, `--password`, repeated `--launch-arg`, and JSON `--launch-env`.
+- MCP: `testEmail`, `testPassword`, `inputOverrides`, `appLaunchArgs`, `appLaunchEnv`, or explicit
+  `loginSteps`.
+
+Do not persist secrets in `.tapp/`. If the result reports input fields and no values were supplied,
+ask the user rather than pretending the explored surface was complete.
+
+## Replay and gating
+
+Flow YAML belongs under `.tapp/flows/` and can replay without a model or API key:
+
+```bash
+npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
+npx -y @aarwitz/tapp@latest ci
+```
+
+`tapp explore` observes. `tapp ci` applies versioned deterministic policy to evidence, selected
+Flows/Scenarios/contracts, coverage, and any target-scoped baseline. Its outcomes are `pass`, `fail`,
+or `inconclusive`; both `fail` and `inconclusive` block a merge.
+
+## Platform prerequisites
+
+- iOS: macOS, Xcode, and a booted simulator. First use builds a cached harness under `~/.tapp`.
+- Android: `adb` and a connected authorized emulator/device.
+- Web: Playwright and Chromium. If Tapp reports the browser missing, run
+  `npx playwright install chromium` and retry.
+
+Captures and screenshots are stored under `~/.tapp/captures/` and `~/.tapp/shots/`.