@aarwitz/tapp 0.17.22 → 0.17.23

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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.22",
+  "version": "0.17.23",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.22",
+        "@aarwitz/tapp@0.17.23",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/AGENTS.md

@@ -68,6 +68,7 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 | "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) |
+| "Is this live site / production / a prospect's site broken?" | `tapp_audit` (CLI `tapp audit <url> --pages N`) — read-only: dead controls, broken images/links/assets, failed requests, JS errors, mixed content, overflow; writes a capture with evidence | `tapp_explore` (it clicks, types and submits) |
 | "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 |
 
@@ -209,3 +210,5 @@ without a coding agent, model, subscription, or API key. AI generation and `asse
   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").
+- A clean `tapp_audit` means the page is served without structural defects. It says nothing about
+  behaviour, because nothing was clicked; never report it as "the site works".

package/mcp-server/src/index.js

@@ -2512,6 +2512,19 @@ const server = new Server(
       prompts: {},
       tools: {},
     },
+    // Shown to the model by MCP clients at connect time: the routing rules that keep an agent from
+    // reaching for the wrong tool, in the order the mistakes actually happen.
+    instructions: [
+      "Tapp gives you hands and eyes on real iOS, Android and web app surfaces. Pick the smallest operation:",
+      "- see or screenshot one screen → tapp_open_app; what is on screen now → tapp_screenshot / tapp_ui_tree;",
+      "- reach a named screen or drive a journey → tapp_session_start (+ focus) then session_act;",
+      "- find bugs in an app or environment you own → tapp_explore (it clicks, types and submits; minutes);",
+      "- check production or a site you do not own → tapp_audit only (read-only: never clicks);",
+      "- a merge decision → the CI gate (tapp ci / GitHub Action), never exploration.",
+      "Results are observations with findings, coverage and evidence paths — never a score or ship verdict.",
+      "inconclusive:true is not a pass; say what blocked coverage. A clean audit says the page is served without structural defects, not that the product works.",
+      "Open returned screenshot paths with your image tool before describing a screen. Never claim a flow works that you did not drive or see.",
+    ].join("\n"),
   }
 );
 
@@ -2742,7 +2755,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "verdict/releaseScore. Web separates deterministic findings from advisory sampled control probes. " +
         "There is a coverage floor: if the app barely explored (crash on launch / sign-in wall) it reports " +
         "`inconclusive` — absence of findings is NEVER a pass. For iOS the app must already be installed on a booted simulator (use tapp_list_simulators / " +
-        "tapp_boot_simulator first). For web, only point it at an app/environment you own — it CLICKS things. " +
+        "tapp_boot_simulator first). For web, only point it at an app/environment you own — it CLICKS things; for production or a site you do not own use tapp_audit (read-only). " +
         "Tapp explores autonomously and does NOT pause to prompt for input — " +
         "it fills forms with safe defaults. The result includes `inputFieldsEncountered` (and `inputHint`): if " +
         "the app showed login/form fields and the user hasn't given you values, ASK THE USER what to enter (offer " +

package/mcp-server/src/web-explorer.js

@@ -668,7 +668,9 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   // phone run legitimately disagree about which nav links exist, and a baseline diff across
   // them must be able to say so instead of reporting "resolved".
   emit("CONTEXT", { ...(String(device || "").trim() ? { device: String(device).trim() } : {}), viewport: captureProfile.viewport, deviceScaleFactor: captureProfile.deviceScaleFactor ?? 1 });
-  const context = await browser.newContext(captureProfile);
+  // Playwright records natively (no ffmpeg transcode needed, unlike simctl's .mov output) —
+  // written to a Playwright-chosen filename in outDir, finalized only on context.close().
+  const context = await browser.newContext({ ...captureProfile, recordVideo: { dir: outDir, size: captureProfile.viewport } });
   await installWebListenerTracking(context);
   if (watch) await installWebWatchUi(context);
   const page = await context.newPage();
@@ -1127,7 +1129,10 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     outbound.total = outboundLinks.size;
     outbound.mailtos = mailtoLinks.size;
     if (outboundLinks.size) {
-      const auditPage = await context.newPage();
+      // A fresh, unrecorded context: outbound link checks navigate away to third-party sites and
+      // must not inherit the exploration context's recordVideo (noise, not exploration evidence).
+      const auditContext = await browser.newContext(captureProfile);
+      const auditPage = await auditContext.newPage();
       auditPage.setDefaultTimeout(8000);
       const targets = [...outboundLinks.entries()].slice(0, OUTBOUND_LINK_LIMIT);
       outbound.checked = targets.length;
@@ -1153,7 +1158,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         const phrase = webUnavailableShellPhrase(text);
         if (phrase) issue("outbound_unavailable", "medium", `Outbound link returns 200 but shows "${phrase}": ${href.slice(0, 100)}`, meta.screen, href, meta.sourceUrl);
       }
-      await auditPage.close().catch(() => {});
+      await auditContext.close().catch(() => {});
     }
     if (mailtoLinks.size) {
       if (process.env.TAPP_ENFORCE_PUBLIC_EGRESS === "1") {
@@ -1181,6 +1186,15 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       : "frontier-drained";
     emit("COMPLETE", { actions, screens: screenCount, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried, timedOut, stop, outbound });
     fs.closeSync(markersFd);
+    // Video finalizes on context.close(), before browser.close() tears down the recorder —
+    // same "exploration.<ext>" name summarizeCapture() and the website replay already look for.
+    const video = page.video();
+    await context.close().catch(() => {});
+    if (video) {
+      await video.path()
+        .then((p) => fs.renameSync(p, path.join(outDir, "exploration.webm")))
+        .catch(() => {});
+    }
     await browser.close().catch(() => {});
   }
   return { markersPath, outDir, actions, screens: screenCount, seedRoutes: normalizedSeeds, seedTargets: normalizedTargets };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.22",
+  "version": "0.17.23",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Let coding agents verify UI changes on real iOS, Android, and web surfaces, then enforce reviewed proof in deterministic CI.",
   "license": "MIT",

package/skills/tapp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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, run the deterministic Tapp gate, or check a live website, production, or a site they do not own without touching it (read-only audit). Also use when the user mentions Tapp, @aarwitz/tapp, tapp_* tools, .tapp artifacts, or asks whether agent-authored UI actually works.
 ---
 
 # Tapp
@@ -16,7 +16,8 @@ screen or journey works from source inspection alone.
 | Inspect controls on the current screen | `tree` / `tapp_ui_tree` |
 | Reach a named screen/control | `focus` / `tapp_focus` (source + observed UI Map fast path) |
 | Drive a specific journey | MCP session start → focus or act → end |
-| Find bugs autonomously | `explore` / `tapp_explore` |
+| Find bugs autonomously (owned app/environment; it clicks) | `explore` / `tapp_explore` |
+| Check production or a site you do not own (never clicks) | `audit` / `tapp_audit` |
 | Preserve a journey | record and save a Flow; replay it deterministically |
 | Decide whether a merge passes policy | `ci`; exploration never decides this |
 
@@ -42,8 +43,7 @@ For a focused request in an already-grounded repository, use the requested targe
 than starting another broad exploration. If `.tapp/ui-map.json` does not exist yet, ground it once
 with `init . --explore`; source alone can locate a surface but cannot authorize unobserved taps.
 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. For production or a site you do not own use `audit` / `tapp_audit` — read-only.
+or owned HTTP(S) URL. Never explore a third-party web property: exploration clicks and types.
 
 ## Navigate like a source-connected expert
 

package/skills/tapp/references/commands.md

@@ -11,7 +11,8 @@ npx -y @aarwitz/tapp@latest explore [target]
 npx -y @aarwitz/tapp@latest focus "Save storefront settings visible above keyboard" [target]
 npx -y @aarwitz/tapp@latest open [target]
 npx -y @aarwitz/tapp@latest tree [target] --json
-npx -y @aarwitz/tapp@latest audit https://example.com --json   # read-only: never clicks, safe against production
+npx -y @aarwitz/tapp@latest audit https://example.com --pages 5 --json   # read-only: never clicks; safe on production or third-party sites
+#   several URLs or --urls FILE batch sites · --device "iPhone 13" audits the mobile rendering · --json FILE writes the result · exit 1 = defects found
 npx -y @aarwitz/tapp@latest shot
 npx -y @aarwitz/tapp@latest report latest
 npx -y @aarwitz/tapp@latest doctor