@aarwitz/tapp 0.17.9 → 0.17.10

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

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -1082,11 +1082,23 @@ class ExplorerTests: XCTestCase {
 
         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".
+        // Presence only: never print, persist, or expose credential values. Report rebuilding
+        // needs this durable marker to distinguish "not supplied" from "supplied but unused".
+        // Decided by what actually reached the run config, not by a separate flag the run config
+        // never carried (feedback #3: every iOS run reported credentialsProvided=false).
+        if resolve("OCQA_CREDENTIALS_EXPLICIT") == "1" || !testEmail.isEmpty || !testPassword.isEmpty {
             print("OCQA_STATE:credentials_supplied")
         }
+        // Capture conditions shared by every screenshot in this run, so a baseline diff across a
+        // different device/scale is visibly a layout comparison (feedback #5: iOS reports carried
+        // captureContext: null while the changelog promised it).
+        do {
+            let env = ProcessInfo.processInfo.environment
+            let device = env["SIMULATOR_DEVICE_NAME"] ?? env["SIMULATOR_MODEL_IDENTIFIER"] ?? "iOS Simulator"
+            let bounds = app.windows.firstMatch.exists ? app.windows.firstMatch.frame : app.frame
+            let scale = UIScreen.main.scale
+            print("OCQA_CONTEXT:{\"device\":\"\(escapeJSON(device))\",\"viewport\":{\"width\":\(Int(bounds.width.rounded())),\"height\":\(Int(bounds.height.rounded()))},\"deviceScaleFactor\":\(scale)}")
+        }
 
         // --- 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. ---

package/README.md

@@ -199,6 +199,7 @@ one by hand:
 
 ```bash
 npx -y @aarwitz/tapp@latest flow example
+npx -y @aarwitz/tapp@latest flow steps      # the step vocabulary: target semantics and pass condition per step
 npx -y @aarwitz/tapp@latest flow validate .tapp/flows/smoke.yml
 npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
 ```

package/bin/tapp.js

@@ -270,7 +270,7 @@ function safeCommandUsage(verb) {
     shot: "tapp shot [--out FILE]",
     apps: "tapp apps",
     build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
-    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]\n  Exit codes: 0 replay passed · 1 replay failed · 2 infrastructure/usage error",
+    flow: "tapp flow example\ntapp flow steps [--json]\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]\n  Exit codes: 0 replay passed · 1 replay failed · 2 infrastructure/usage error",
     task: "tapp task validate FILE [--platform PLATFORM] [--map FILE]\ntapp task compile FILE --platform PLATFORM [--inputs JSON] [--out FILE]\ntapp task run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]",
     contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]\n  Exit codes: 0 contract held · 1 contract failed · 2 infrastructure/usage error",
     scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]\n  Exit codes: 0 scenario passed · 1 scenario failed · 2 infrastructure/usage error",
@@ -1133,8 +1133,16 @@ switch (command) {
       console.log(`# Tapp Flow — deterministic, keyless replay\nname: sign-in-smoke\nplatform: web\nurl: https://example.test/login\nsteps:\n  - login:\n      email: $TEST_EMAIL\n      password: $TEST_PASSWORD\n  - wait_for: Dashboard\n  - assert_screen: Dashboard\n`);
       break;
     }
+    if (verb === "steps") {
+      const { FLOW_ACTIONS } = await import(path.join(packageRoot, "mcp-server", "src", "flow-runtime.js"));
+      if (flags.json === true) { console.log(JSON.stringify(FLOW_ACTIONS, null, 2)); break; }
+      console.log("Flow step vocabulary — identical on ios, android, and web. Anything else fails `tapp flow validate`.\n");
+      for (const a of FLOW_ACTIONS) console.log(`  ${a.action.padEnd(14)} target: ${a.target}\n  ${"".padEnd(14)} passes: ${a.passes}\n`);
+      console.log("Targets are labels / accessibility ids / visible text, never coordinates. `assert_screen` checks the detected screen TITLE; use `assert_exists` for \"this text is on screen\".");
+      break;
+    }
     if (!["run", "validate"].includes(verb) || !flowPath) {
-      console.error("usage: tapp flow example\n       tapp flow run <flow.yml> [--platform ios|android|web] [--actor NAME] [--email VALUE] [--password VALUE] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
+      console.error("usage: tapp flow example\n       tapp flow steps [--json]\n       tapp flow run <flow.yml> [--platform ios|android|web] [--actor NAME] [--email VALUE] [--password VALUE] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
       process.exit(2);
     }
     const absolute = path.resolve(flowPath);
@@ -1142,7 +1150,7 @@ switch (command) {
       console.error(`❌ Flow not found: ${absolute}`);
       process.exit(2);
     }
-    const { loadFlowFile } = await import(path.join(packageRoot, "mcp-server", "src", "flow-runtime.js"));
+    const { loadFlowFile, validateFlowSteps } = await import(path.join(packageRoot, "mcp-server", "src", "flow-runtime.js"));
     let flow;
     try { flow = loadFlowFile(absolute); } catch (error) {
       console.error(`❌ Invalid Flow: ${error.message}`);
@@ -1157,6 +1165,13 @@ switch (command) {
       console.error(`❌ Unsupported Flow platform: ${platform}`);
       process.exit(2);
     }
+    // Static step checks run before validate AND run: a Flow outside the vocabulary (or a
+    // coordinate tap) can never replay, so it must not reach a simulator (feedback #2).
+    const stepErrors = validateFlowSteps(flow, platform);
+    if (stepErrors.length) {
+      console.error(`❌ Invalid ${platform} Flow — ${flow.name || path.basename(absolute)}:\n${stepErrors.map((e) => `   • ${e}`).join("\n")}\n   Vocabulary: tapp flow steps`);
+      process.exit(2);
+    }
     if (verb === "validate") {
       const taskCount = Array.isArray(flow.taskPlan) ? flow.taskPlan.length : 0;
       console.log(`✅ Valid ${platform} Flow — ${flow.name} (${flow.steps.length} deterministic steps${taskCount ? ` compiled from ${taskCount} Task call${taskCount === 1 ? "" : "s"}` : ""})`);

package/docs/scenarios.md

@@ -74,7 +74,7 @@ tapp ci --platform web --url http://127.0.0.1:4180 \
 GitHub Action:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.9 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.10 # or pin the reviewed release commit SHA
   with:
     platform: web
     url: http://127.0.0.1:4180

package/mcp-server/src/feedback.js

@@ -86,12 +86,19 @@ export function ghStatus(ghBin = process.env.TAPP_GH_BIN || "gh") {
 }
 
 export function submitFeedbackViaGh(issue, ghBin = process.env.TAPP_GH_BIN || "gh") {
-  const r = spawnSync(ghBin, [
+  // Labels can only be set by accounts with triage rights on the repo. Anyone else (which is
+  // every real user) gets the issue filed without them; the footer already carries the kind
+  // and the maintainer applies labels on triage. Try with labels first, then without.
+  const attempt = (withLabels) => spawnSync(ghBin, [
     "issue", "create", "--repo", FEEDBACK_REPO,
-    "--title", issue.title, "--body-file", "-", "--label", issue.labels.join(","),
+    "--title", issue.title, "--body-file", "-",
+    ...(withLabels ? ["--label", issue.labels.join(",")] : []),
   ], { encoding: "utf8", input: issue.body });
+  let r = attempt(true);
+  let labelsApplied = r.status === 0;
+  if (r.status !== 0 && /label/i.test(`${r.stderr || ""}${r.stdout || ""}`)) { r = attempt(false); labelsApplied = false; }
   const out = (r.stdout || "").trim();
   const err = (r.stderr || "").trim();
   const url = (out.match(/https:\/\/github\.com\/\S+/) || [])[0] || null;
-  return { ok: r.status === 0 && Boolean(url), url, detail: r.status === 0 ? out : (err || out) };
+  return { ok: r.status === 0 && Boolean(url), url, labelsApplied, detail: r.status === 0 ? out : (err || out) };
 }

package/mcp-server/src/flow-runtime.js

@@ -36,6 +36,60 @@ export function normalizeFlowStep(raw) {
   return { action: key.toLowerCase(), target: body === true ? "" : String(body ?? ""), value: body === true ? "" : String(body ?? ""), params: {}, ...(raw.__tappTask?.name ? { task: raw.__tappTask.name } : {}) };
 }
 
+// The committed Flow step vocabulary. Every driver (XCUITest, Android, browser) implements exactly
+// this table; `tapp flow steps` prints it and `tapp flow validate` rejects anything outside it, so
+// a Flow that validates can actually replay (feedback #2: coordinate taps and `click:` used to
+// validate and then fail at runtime).
+export const FLOW_ACTIONS = Object.freeze([
+  { action: "tap", target: "a visible label / accessibility id", passes: "the control was found and tapped; coordinates are not accepted — use the session's tap-by-point to learn the label" },
+  { action: "type", target: "{field, value}", passes: "the field was found and now holds the value ($TEST_EMAIL/$TEST_PASSWORD substitute)" },
+  { action: "login", target: "{email, password} (defaults to $TEST_EMAIL/$TEST_PASSWORD)", passes: "credentials were entered and submitted and the login form went away" },
+  { action: "swipe", target: "up | down | left | right", passes: "the gesture was performed" },
+  { action: "back", target: "(none)", passes: "the platform back navigation was performed" },
+  { action: "wait", target: "milliseconds (fixed pause; prefer wait_for)", passes: "always" },
+  { action: "wait_for", target: "label / text (+ timeoutMs)", passes: "the element appeared before the timeout" },
+  { action: "assert_screen", target: "the detected SCREEN TITLE (navigation bar / heading), not arbitrary text", passes: "the current screen's title equals the target" },
+  { action: "assert_exists", target: "label / text", passes: "an element with that text or id is present" },
+  { action: "assert_absent", target: "label / text", passes: "no element with that text or id is present" },
+  { action: "assert_text", target: "{of, contains}", passes: "the element's text contains the substring" },
+  { action: "assert_ai", target: "a natural-language expectation", passes: "the vision judge agrees (needs ANTHROPIC_API_KEY; advisory)" },
+]);
+const FLOW_ACTION_NAMES = new Set(FLOW_ACTIONS.map((a) => a.action));
+const ALIASES = { click: "tap", press: "tap", fill: "type", input: "type", sleep: "wait", wait_for_text: "wait_for", assert_visible: "assert_exists", expect: "assert_exists" };
+
+// Static checks a Flow must pass before any runtime is launched. Returns human-readable errors;
+// an empty array means every step is in the vocabulary and shaped so a driver can execute it.
+export function validateFlowSteps(flow, platform = inferFlowPlatform(flow)) {
+  const errors = [];
+  const steps = Array.isArray(flow?.steps) ? flow.steps : [];
+  steps.forEach((raw, i) => {
+    const step = normalizeFlowStep(raw);
+    const n = i + 1;
+    if (step.action === "noop") { errors.push(`step ${n}: empty step`); return; }
+    if (!FLOW_ACTION_NAMES.has(step.action)) {
+      const alias = ALIASES[step.action];
+      errors.push(`step ${n}: unknown action '${step.action}'${alias ? ` — did you mean '${alias}'? (web flows use tap:, not click:)` : ""}; run \`tapp flow steps\` for the vocabulary`);
+      return;
+    }
+    if (step.action === "tap" && /^\s*-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?\s*$/.test(step.target)) {
+      errors.push(`step ${n}: tap target '${step.target.trim()}' is a coordinate; Flow taps are label-only on ${platform} (use tapp_session_act tap {x,y} to learn the label, then record it)`);
+    }
+    if (["tap", "wait_for", "assert_screen", "assert_exists", "assert_absent"].includes(step.action) && !step.target.trim()) {
+      errors.push(`step ${n}: ${step.action} needs a target`);
+    }
+    if (step.action === "type" && (!step.target.trim() || !("value" in (step.params || {})))) {
+      errors.push(`step ${n}: type needs {field, value}`);
+    }
+    if (step.action === "assert_text" && (!step.target.trim() || !step.value)) {
+      errors.push(`step ${n}: assert_text needs {of, contains}`);
+    }
+    if (step.action === "swipe" && step.target && !["up", "down", "left", "right"].includes(step.target.trim().toLowerCase())) {
+      errors.push(`step ${n}: swipe direction must be up|down|left|right`);
+    }
+  });
+  return errors;
+}
+
 export function flowVariables(flow, overrides = {}) {
   return {
     TEST_EMAIL: process.env.OCQA_TEST_EMAIL || "test@example.com",

package/mcp-server/src/index.js

@@ -907,10 +907,39 @@ function recordStep(cmd, result) {
   if (newScreen) activeSession.lastScreen = newScreen;
 }
 
+// Argument shapes tapp_session_act accepts, per action. A malformed call is answered here with
+// the accepted shape and never reaches the driver, so it can neither time out nor disturb the
+// session (feedback #7: `{action:"wait", seconds:3}` used to wait on an empty target).
+const SESSION_ACT_ARGS = Object.freeze({
+  tap: "{id: <label|accessibility id>} or {x, y} (points)",
+  type: "{id|label: <field>, text: <value>}",
+  wait: "{text|id: <label to wait for>, timeoutMs?: <default 5000, max 60000>} — there is no fixed sleep; wait for something",
+  login: "{email?, password?} (defaults to the session's credentials)",
+  swipe: "{direction: up|down|left|right}",
+  back: "{}",
+  tree: "{verbose?: true}",
+  screenshot: "{label?}",
+});
+export function sessionActUsageError(cmd = {}) {
+  const action = String(cmd.action || "");
+  if (!SESSION_ACT_ARGS[action]) return `Unknown action '${action || "(none)"}'. Accepted: ${Object.keys(SESSION_ACT_ARGS).join(", ")}.`;
+  const has = (k) => cmd[k] !== undefined && cmd[k] !== null && String(cmd[k]).trim() !== "";
+  const bad = (why) => `${why}. ${action} takes ${SESSION_ACT_ARGS[action]}.`;
+  if (action === "wait" && !has("text") && !has("id")) return bad(`wait needs a target${cmd.seconds !== undefined || cmd.ms !== undefined ? " (seconds/ms are not arguments)" : ""}`);
+  if (action === "wait" && cmd.timeoutMs !== undefined && !(Number.isFinite(Number(cmd.timeoutMs)) && Number(cmd.timeoutMs) > 0)) return bad("timeoutMs must be a positive number of milliseconds");
+  if (action === "tap" && !has("id") && !has("label") && !(Number.isFinite(cmd.x) && Number.isFinite(cmd.y))) return bad("tap needs an id/label or both x and y");
+  if (action === "type" && !has("id") && !has("label")) return bad("type needs the field's id/label");
+  if (action === "type" && cmd.text === undefined) return bad("type needs text");
+  if (action === "swipe" && cmd.direction !== undefined && !["up", "down", "left", "right"].includes(String(cmd.direction))) return bad("direction must be up|down|left|right");
+  return null;
+}
+
 async function sessionAct(cmd) {
   const startedAt = Date.now();
   const done = (result) => ({ ...result, durationMs: Date.now() - startedAt });
   if (!activeSession || activeSession.ended) return done({ error: "No active session. Call tapp_session_start first." });
+  const usage = sessionActUsageError(cmd);
+  if (usage) return done({ status: "usage", detail: usage, ...treeSnapshot(), recordedSteps: activeSession.recording.length });
   let coordinateResolvedTarget = "";
   if (cmd.action === "tap" && !cmd.id && Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) {
     coordinateResolvedTarget = semanticTargetAtPoint(activeSession.latestTree?.elements, cmd.x, cmd.y);

package/mcp-server/src/report.js

@@ -298,6 +298,7 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   // 40-action campaign. Drivers signal the real cause in COMPLETE.stop; captures from drivers
   // that predate the field keep the old inference.
   const driverStop = base.complete && typeof base.complete === "object" ? base.complete.stop : null;
+  const nativeOutcome = base.complete && typeof base.complete === "object" && typeof base.complete.outcome === "string" ? base.complete.outcome : null;
   const stopReason = unexercisedLoginWall ? (credentialsProvided ? "login-wall-credentials-unused" : "login-wall-no-credentials")
     : timeBudgetExhausted ? "time-budget-exhausted"
     : !coverageFloorMet ? "coverage-floor-not-met"
@@ -306,6 +307,11 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     // Any other driver-signalled cause (navigation-trap, app-crashed, stuck-no-progress …)
     // passes through verbatim: "completed" is ONLY the exhausted action budget.
     : driverStop && driverStop !== "action-budget" && driverStop !== "time-budget" ? String(driverStop)
+    // XCUITest predates COMPLETE.stop and signals the cause through COMPLETE.outcome instead
+    // (feedback #5: a run whose marker said limited_surface must not read as "completed").
+    : nativeOutcome === "limited_surface" ? "limited-surface"
+    : nativeOutcome === "timeout" ? "time-budget-exhausted"
+    : nativeOutcome && nativeOutcome.startsWith("crash") ? "app-crashed"
     : "completed";
 
   const headline = timeBudgetExhausted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.9",
+  "version": "0.17.10",
   "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/scripts/flow_lib.py

@@ -63,6 +63,29 @@ def raw_json(path):
     print(json.dumps(load_flow(path) or {}))
 
 
+ABORT_PATTERNS = [
+    r"Failed to synthesize event: [^\n]*",
+    r"Neither element nor any descendant has keyboard focus[^\n]*",
+    r"Test Case '[^']*' failed \([^)]*\)",
+    r"Error Domain=[^\n]*",
+    r"Unable to (?:find|launch|boot)[^\n]*",
+    r"App state is [^\n]*",
+    r"Timed out [^\n]*",
+    r"Testing failed:[^\n]*",
+    r"error: [^\n]*",
+    r"\*\* TEST (?:EXECUTE )?FAILED \*\*",
+]
+
+
+def harness_abort_reason(log):
+    """First XCTest/xcodebuild line that explains why a run ended before step 1."""
+    for pat in ABORT_PATTERNS:
+        m = re.search(pat, log)
+        if m:
+            return m.group(0).strip()[:300]
+    return None
+
+
 def report(path, as_json=False):
     log = open(path, encoding="utf-8", errors="replace").read()
     steps = []
@@ -97,8 +120,19 @@ def report(path, as_json=False):
     executed = (result or {}).get("executed", len(steps))
     passed_steps = sum(1 for s in steps if s.get("status") == "pass")
 
+    # A run that died before step 1 used to print `0 passed · 0 failed · 0/0 executed` and
+    # nothing else; the XCTest reason lived only in flow.log (feedback #1). Surface it as the
+    # failure of the first step so the scoreboard says why instead of looking like a crash.
+    abort_reason = None
+    if not steps and not passed:
+        abort_reason = harness_abort_reason(log)
+        steps.append({"index": 1, "action": "harness", "target": "", "status": "fail",
+                      "detail": abort_reason or "the harness exited before the first step; see flow.log"})
+        failed = max(failed, 1)
+
     if as_json:
-        print(json.dumps({"name": name, "kind": kind, "passed": passed, "total": total, "executed": executed, "failed": failed, "steps": steps}))
+        print(json.dumps({"name": name, "kind": kind, "passed": passed, "total": total, "executed": executed, "failed": failed,
+                          **({"abortReason": abort_reason} if abort_reason else {}), "steps": steps}))
         return 0 if passed else 1
 
     icon = {"pass": "✅", "fail": "❌", "skip": "⚪️"}

package/scripts/quick-capture.sh

@@ -184,7 +184,8 @@ run_harness_test() {
   "OCQA_MAX_ACTIONS": "$max_actions",
   "OCQA_TIMEOUT_SECONDS": "$timeout_secs",
   "OCQA_TEST_EMAIL": "${OCQA_TEST_EMAIL:-}",
-  "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-}"$interactive_line$overrides_line$launch_args_line$launch_env_line$login_steps_line$pr_target_line$visual_ready_line$recording_started_line
+  "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-}",
+  "OCQA_CREDENTIALS_EXPLICIT": "${OCQA_CREDENTIALS_EXPLICIT:-}"$interactive_line$overrides_line$launch_args_line$launch_env_line$login_steps_line$pr_target_line$visual_ready_line$recording_started_line
 }
 CONF
 

package/skills/tapp/references/commands.md

@@ -101,6 +101,8 @@ ask the user rather than pretending the explored surface was complete.
 Flow YAML belongs under `.tapp/flows/` and can replay without a model or API key:
 
 ```bash
+npx -y @aarwitz/tapp@latest flow steps     # vocabulary: assert_screen = screen TITLE, assert_exists = text present; taps are label-only
+npx -y @aarwitz/tapp@latest flow validate .tapp/flows/smoke.yml
 npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
 npx -y @aarwitz/tapp@latest ci
 ```