@aarwitz/tapp 0.17.0-rc.13 → 0.17.0-rc.15

package/mcp-server/src/index.js

@@ -335,6 +335,9 @@ export function findXcodeContainer(startDir) {
 }
 
 export async function buildAppForSim({ dir, container, scheme, configuration = "Debug" } = {}) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(path.join(tappHome || os.tmpdir(), "app-builds"));
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const target = container || findXcodeContainer(dir || process.cwd());
   if (!target) return { error: `No Xcode project or workspace found under ${dir || process.cwd()}` };
   const isWorkspace = target.endsWith(".xcworkspace");
@@ -715,6 +718,28 @@ function templateValue(text) {
   return text;
 }
 
+export function isStableFlowCheckpoint(value) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (!text || /^(loading|fetching|please wait|preparing|connecting|syncing|signing in)(?:[.…!]*|\s.*)$/i.test(text)) return false;
+  if (/^(?:mon|tues?|wed(?:nes)?|thu(?:rs)?|fri|sat(?:ur)?|sun)(?:day)?\b/i.test(text)) return false;
+  if (/^(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\s+\d{1,2}(?:,\s+\d{4})?$/i.test(text)) return false;
+  if (/^\d{4}-\d{2}-\d{2}(?:[ T].*)?$/.test(text)) return false;
+  return true;
+}
+
+export function semanticTargetAtPoint(elements, x, y) {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return "";
+  return (elements || [])
+    .filter((element) => {
+      const frame = element.frame || {};
+      return element.hittable !== false && Number.isFinite(frame.x) && Number.isFinite(frame.y) && Number.isFinite(frame.width) && Number.isFinite(frame.height)
+        && x >= frame.x && y >= frame.y && x <= frame.x + frame.width && y <= frame.y + frame.height
+        && String(element.id || element.identifier || element.label || "").trim();
+    })
+    .sort((a, b) => (a.frame.width * a.frame.height) - (b.frame.width * b.frame.height))
+    .map((element) => String(element.id || element.identifier || element.label || "").trim())[0] || "";
+}
+
 /** Append a Flow step for an act (record-by-doing). Inserts wait_for on screen change for
  *  deterministic replay. Inspection acts (tree/screenshot/wait) are not recorded. */
 function recordStep(cmd, result) {
@@ -725,7 +750,7 @@ function recordStep(cmd, result) {
     case "tap": {
       const target = cmd.id || cmd.label || (typeof cmd.x === "number" ? `${cmd.x},${cmd.y}` : "");
       if (target) activeSession.recording.push({ tap: target });
-      if (changed) activeSession.recording.push({ wait_for: newScreen });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
       break;
     }
     case "type": {
@@ -734,12 +759,16 @@ function recordStep(cmd, result) {
       activeSession.recording.push({ type: step });
       break;
     }
+    case "login":
+      activeSession.recording.push({ login: { email: "$TEST_EMAIL", password: "$TEST_PASSWORD" } });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
+      break;
     case "swipe":
       activeSession.recording.push({ swipe: cmd.direction || "up" });
       break;
     case "back":
       activeSession.recording.push({ back: true });
-      if (changed) activeSession.recording.push({ wait_for: newScreen });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
       break;
     default:
       break; // tree / screenshot / wait are inspection, not test steps
@@ -748,7 +777,17 @@ function recordStep(cmd, result) {
 }
 
 async function sessionAct(cmd) {
-  if (!activeSession || activeSession.ended) return { error: "No active session. Call tapp_session_start first." };
+  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." });
+  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);
+    if (coordinateResolvedTarget) {
+      const { x: _x, y: _y, ...semanticCommand } = cmd;
+      cmd = { ...semanticCommand, id: coordinateResolvedTarget };
+    }
+  }
   if (activeSession.platform === "web") {
     const session = activeSession;
     let status = "ok";
@@ -756,9 +795,13 @@ async function sessionAct(cmd) {
     let typedInto = null;
     try {
       if (cmd.action === "tap") {
-        const locator = await firstVisibleWebLocator(session.page, cmd.id || cmd.label || "");
-        if (!locator) { status = "not_found"; detail = "No visible web control matched the semantic target"; }
-        else await locator.click({ timeout:10_000 });
+        const target = cmd.id || cmd.label || "";
+        if (!target && Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) await session.page.mouse.click(cmd.x, cmd.y);
+        else {
+          const locator = await firstVisibleWebLocator(session.page, target);
+          if (!locator) { status = "not_found"; detail = "No visible web control matched the semantic target"; }
+          else await locator.click({ timeout:10_000 });
+        }
       } else if (cmd.action === "type") {
         const locator = await firstVisibleWebLocator(session.page, cmd.id || cmd.label || "", { input:true });
         if (!locator) { status = "not_found"; detail = "No visible web field matched the semantic target"; }
@@ -771,6 +814,28 @@ async function sessionAct(cmd) {
           if (!locator) await session.page.waitForTimeout(120);
         }
         if (!locator) { status = "timeout"; detail = `Timed out waiting for ${cmd.id || cmd.text || "target"}`; }
+      } else if (cmd.action === "login") {
+        const emailValue = cmd.email || session.creds.email || "";
+        const passwordValue = cmd.password || session.creds.password || "";
+        if (!emailValue || !passwordValue) { status = "missing_credentials"; detail = "Email and password are required"; }
+        else {
+          const email = await firstVisibleWebLocator(session.page, "Email", { input:true })
+            || session.page.locator("input[type=email], input[name*=mail i], input[name*=user i], input[id*=mail i], input[id*=user i]").first();
+          const password = session.page.locator("input[type=password]").first();
+          if (!(await email.isVisible().catch(() => false)) || !(await password.isVisible().catch(() => false))) {
+            status = "not_found"; detail = "Could not identify email and password fields";
+          } else {
+            await email.fill(emailValue);
+            await password.fill(passwordValue);
+            const submit = session.page.getByRole("button", { name:/sign in|log in|login|continue|submit/i }).first();
+            if (!(await submit.isVisible().catch(() => false))) { status = "not_found"; detail = "Could not identify a sign-in control"; }
+            else {
+              await submit.click();
+              await session.page.waitForTimeout(500);
+              if (await password.isVisible().catch(() => false)) { status = "still_on_login"; detail = "Submit left the app on the login screen"; }
+            }
+          }
+        }
       } else if (cmd.action === "back") {
         await session.page.goBack({ waitUntil:"domcontentloaded", timeout:10_000 }).catch(() => {});
       } else if (cmd.action === "swipe") {
@@ -789,7 +854,7 @@ async function sessionAct(cmd) {
     }
     const snapshot = treeSnapshot();
     if (status === "ok") recordStep(cmd, snapshot);
-    return { status, typedInto, detail, ...snapshot, recordedSteps:session.recording.length, url:session.latestTree?.url || "" };
+    return done({ status, typedInto, detail, ...snapshot, recordedSteps:session.recording.length, url:session.latestTree?.url || "", ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
   }
   if (activeSession.platform === "android") {
     const s = activeSession;
@@ -845,7 +910,7 @@ async function sessionAct(cmd) {
     s.treeVersion += 1;
     const snap = treeSnapshot();
     if (status === "ok") recordStep(cmd, snap);
-    return { status, typedInto, detail, ...snap, recordedSteps: s.recording.length };
+    return done({ status, typedInto, detail, ...snap, recordedSteps: s.recording.length, ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
   }
   activeSession.seq += 1;
   const seq = activeSession.seq;
@@ -874,7 +939,7 @@ async function sessionAct(cmd) {
   while (activeSession.treeVersion === beforeVer && Date.now() < td && !activeSession.ended) await sleep(150);
   const snap = treeSnapshot();
   if (status === "ok") recordStep(cmd, snap); // record only successful acts
-  return { status, typedInto, detail, ...snap, recordedSteps: activeSession ? activeSession.recording.length : 0 };
+  return done({ status, typedInto, detail, ...snap, recordedSteps: activeSession ? activeSession.recording.length : 0, ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
 }
 
 async function endSession() {
@@ -919,7 +984,7 @@ export async function saveInteractiveSessionFlow({ projectDir, name, addFinalAss
   if (!projectDir || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error("A valid repository root is required to save a Flow");
   const steps = [...(activeSession.recording || [])];
   if (steps.length === 0) throw new Error("Nothing recorded yet — perform some live-session actions first.");
-  if (addFinalAssertion && activeSession.lastScreen) {
+  if (addFinalAssertion && activeSession.lastScreen && isStableFlowCheckpoint(activeSession.lastScreen)) {
     const last = steps[steps.length - 1] || {};
     if (!("assert_screen" in last)) steps.push({ assert_screen: activeSession.lastScreen });
   }
@@ -1244,6 +1309,7 @@ export function explorationEnvFromArgs(args) {
   const env = {};
   if (isNonEmptyString(args.testEmail)) env.OCQA_TEST_EMAIL = args.testEmail;
   if (isNonEmptyString(args.testPassword)) env.OCQA_TEST_PASSWORD = args.testPassword;
+  if (isNonEmptyString(args.testEmail) || isNonEmptyString(args.testPassword)) env.OCQA_CREDENTIALS_EXPLICIT = "1";
   if (Array.isArray(args.appLaunchArgs)) {
     const a = args.appLaunchArgs.filter((s) => typeof s === "string" && s.length > 0);
     if (a.length) env.OCQA_APP_LAUNCH_ARGS_JSON = JSON.stringify(a);
@@ -1335,9 +1401,9 @@ function fmtDuration(ms) {
 export function qaNextSteps(report, surface = "mcp") {
   if (surface === "cli") {
     const next = [];
-    if (report?.findings?.length) next.push("inspect the evidence with `tapp report latest`");
-    next.push("re-run with `--baseline <report.json>` to compare a fix (then `tapp ci` to gate it)");
-    next.push("replay a committed journey with `tapp flow run <file>`");
+    if (report?.findings?.length) next.push("inspect the evidence with `npx -y @aarwitz/tapp@latest report latest`");
+    next.push("save this run with `--json <report.json>`, then re-run with `--baseline <report.json>` to compare a fix (`tapp ci` gates it)");
+    next.push("replay a committed journey with `npx -y @aarwitz/tapp@latest flow run <file>`");
     return next;
   }
   const next = [];
@@ -1359,6 +1425,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
   L.push(`### 🔭 Exploration complete — ${badge} · ${observationSummary(report)}${bundleId ? `\n\`${bundleId}\`` : ""}`);
   L.push("");
   L.push(report.headline);
+  if (report.credentialWarning) L.push("", `> ⚠️ ${report.credentialWarning}`);
   L.push("");
   L.push(`**Coverage** — ${report.screensExplored} screens · ${report.actionsPerformed} actions${timedOut ? " · ⏱️ hit time limit" : ""}`);
   if (report.platform === "web") {
@@ -1373,7 +1440,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     L.push("");
     L.push("**Findings**");
     for (const f of report.findings.slice(0, 12)) {
-      L.push(`- ${SEV[f.severity] || "•"} \`${f.severity}\` ${f.title}${f.screen ? ` — on *${f.screen}*` : ""}`);
+      L.push(`- ${SEV[f.severity] || "•"} \`${f.severity}\` ${f.title}${f.screen ? ` — on *${f.screen}*` : ""}${f.url ? ` — ${f.url}` : ""}`);
       if (f.aiAnalysis) L.push(`  - why: ${String(f.aiAnalysis).slice(0, 200)}`);
       if (f.suggestedFix) L.push(`  - fix: ${String(f.suggestedFix).slice(0, 200)}`);
     }
@@ -1390,7 +1457,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     // The merge decision is the gate's job (tapp ci), not exploration's (ADR-0005).
     L.push("");
     L.push(
-      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`tapp ci\` to gate)`
+      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`npx -y @aarwitz/tapp@latest ci\` to gate)`
     );
   }
   if (inputHint) {
@@ -1474,6 +1541,9 @@ export function formatScreen(screenTitle, elements) {
 // the surfaces can't drift.)
 
 export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], watch = false, surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "web-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1516,6 +1586,9 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
 }
 
 export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout, testEmail, testPassword, baselineFindings, clearData = true, seedTargets = [], surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "android-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1559,6 +1632,9 @@ export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout
 }
 
 export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const captureScript = path.join(scriptsDir, "quick-capture.sh");
   if (!fs.existsSync(captureScript)) return { error: "Capture script not found", details: { captureScript } };
 
@@ -1801,7 +1877,7 @@ export async function runExploreTarget({
 
   const modelPath = existingProjectArtifactPath(root, "application-model.json");
   if (!fs.existsSync(modelPath)) {
-    return { error: "No application model found — run `tapp init` first, or pass an explicit target (a bundle id, a path/to/App.app, a repo dir, --app-id/--apk, or an http(s) URL)." };
+    return { error: "No application model found — call `tapp_init` or run `npx -y @aarwitz/tapp@latest init` first, or pass an explicit target (a bundle id, a path/to/App.app, a repo dir, --app-id/--apk, or an http(s) URL)." };
   }
   let model;
   try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
@@ -1839,7 +1915,7 @@ export async function runExploreTarget({
 
   if (selectedPlatform === "android") {
     const appId = String(selected.runtime?.applicationId || "").trim();
-    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and rerun \`tapp init\`, or pass --app-id.` };
+    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and call \`tapp_init\` or rerun \`npx -y @aarwitz/tapp@latest init\`, or pass --app-id.` };
     const task = selected.build?.task || "assembleDebug";
     onStatus(`Building the Android APK (${task})…`);
     const built = await buildAndroidApp({
@@ -1877,6 +1953,22 @@ function openLocalPort() {
   });
 }
 
+function localPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
+  });
+}
+
+export function managedWebDefaultPort(dependencies = {}) {
+  if (dependencies.vite) return 5173;
+  if (dependencies.next) return 3000;
+  if (dependencies["react-scripts"]) return 3000;
+  return 0;
+}
+
 function managedInstallSpec(command) {
   const known = {
     "npm ci": ["npm", ["ci"]],
@@ -1961,7 +2053,9 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
   const pkg = (() => { try { return JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8")); } catch { return {}; } })();
   const dependencies = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
   const declaredPort = startMatch ? declaredPortFromStartScript(pkg.scripts?.[startMatch[1]]) : 0;
-  const port = declaredPort || await openLocalPort();
+  const frameworkPort = declaredPort ? 0 : managedWebDefaultPort(dependencies);
+  const port = declaredPort || (frameworkPort && await localPortAvailable(frameworkPort) ? frameworkPort : await openLocalPort());
+  const portBasis = declaredPort ? "repository-declared" : port === frameworkPort ? "framework-default" : "available-ephemeral";
   let command = "npm";
   let startArgs;
   let startDir = projectDir;
@@ -1988,13 +2082,13 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
   const append = (chunk) => fs.appendFileSync(logPath, String(chunk));
   child.stdout.on("data", append);
   child.stderr.on("data", append);
-  onStatus(`Managed web runtime: ${command === process.execPath ? "Tapp static server" : `npm ${startArgs.join(" ")}`} → http://127.0.0.1:${port}`);
+  onStatus(`Managed web runtime: ${command === process.execPath ? "Tapp static server" : `npm ${startArgs.join(" ")}`} → http://127.0.0.1:${port} (${portBasis} port)`);
   const ready = await waitForOwnedUrl(`http://127.0.0.1:${port}`, child, Math.min(budgetMs, 60_000), logPath);
   if (ready.error) {
     await stopManagedWebTarget({ child, detached: process.platform !== "win32" });
     return ready;
   }
-  return { child, detached: process.platform !== "win32", url: `http://127.0.0.1:${port}`, logPath, install, build, start: { command, args: startArgs, cwd: startDir } };
+  return { child, detached: process.platform !== "win32", url: `http://127.0.0.1:${port}`, logPath, install, build, start: { command, args: startArgs, cwd: startDir, portBasis } };
 }
 
 export async function stopManagedWebTarget(runtime) {
@@ -2322,7 +2416,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
               "Findings from a previous run (pass back the `findings` array a prior tapp_explore returned). " +
               "When provided, the result adds a `regression` COMPARISON {counts:{new,persisting,resolved}, " +
               "newFindings, resolved} vs. that baseline — an observation, not a gate signal. To gate a merge, " +
-              "run `tapp ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
+              "run `npx -y @aarwitz/tapp@latest ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
               "pass/fail/inconclusive outcome.",
           },
         },
@@ -2858,7 +2952,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const icon = c.ok ? "✅" : c.required ? "❌" : "⚪️";
       L.push(`- ${icon} **${c.check}** — ${String(c.value).split("\n")[0] || "—"}`);
     }
-    if (!ready) L.push("", "Run `tapp doctor` in the application repository for exact remediation.");
+    if (!ready) L.push("", "Run `npx -y @aarwitz/tapp@latest doctor` in the application repository for exact remediation.");
     return richResult(L.join("\n"), { ok: ready, workspaceRoot, checks, platforms: Object.fromEntries(platformChecks.map((check) => [check.check.toLowerCase(), check.ok])) });
   }
 
@@ -2878,11 +2972,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (inst.error) return errorResult(inst.error);
       bundleId = inst.bundleId;
     }
+    let modelRefresh = null;
+    let modelRefreshWarning = "";
+    if (bundleId) {
+      try {
+        const { persistIosBuildValidation } = await import("./application-model.js");
+        modelRefresh = await persistIosBuildValidation({ projectDir: dir, bundleId, container: built.container, scheme: built.scheme, configuration: built.configuration });
+      } catch (error) {
+        modelRefreshWarning = error.message || String(error);
+      }
+    }
     const text =
       `🔨 Built **${path.basename(built.appPath)}** (scheme \`${built.scheme}\`) in ${fmtDuration(Date.now() - startedAt)}` +
       (bundleId ? ` — installed on the simulator as \`${bundleId}\`` : "") +
       `\n\nNext: \`tapp_explore\` with \`appBundleId: "${bundleId || "<install it first>"}"\`.`;
-    return richResult(text, { ok: true, appPath: built.appPath, scheme: built.scheme, container: built.container, bundleId });
+    return richResult(text + (modelRefresh ? `\nApplication model refreshed: \`${modelRefresh.modelPath}\`.` : modelRefreshWarning ? `\n⚠️ Application model refresh failed: ${modelRefreshWarning}` : ""), { ok: true, appPath: built.appPath, scheme: built.scheme, container: built.container, bundleId, modelRefreshed: !!modelRefresh, ...(modelRefreshWarning ? { modelRefreshWarning } : {}) });
   }
 
   if (name === "tapp_capture") {
@@ -3201,7 +3305,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         credentials,
         replace: asBoolean(args.replace),
       });
-      return richResult(`✅ Actor '${args.name.trim()}' configured with ${Object.keys(result.actor.credentials).length} environment binding(s); no credential values were accepted or written`, { path: result.path, actor: result.actor, next: "Run tapp_init refresh to update the application model and release plan." });
+      const { refreshExistingInitArtifacts } = await import("./application-model.js");
+      let refreshed = null;
+      let refreshWarning = "";
+      try { refreshed = await refreshExistingInitArtifacts({ projectDir }); }
+      catch (error) { refreshWarning = error.message || String(error); }
+      return richResult(
+        `✅ Actor '${args.name.trim()}' configured with ${Object.keys(result.actor.credentials).length} environment binding(s); no credential values were accepted or written${refreshed ? " · application model refreshed" : ""}${refreshWarning ? `\n⚠️ Application model refresh failed: ${refreshWarning}` : ""}`,
+        { path: result.path, actor: result.actor, modelRefreshed: !!refreshed, ...(refreshed ? { modelPath: refreshed.modelPath, planPath: refreshed.planPath } : {}), ...(refreshWarning ? { refreshWarning } : {}) },
+      );
     } catch (error) { return errorResult("Actor not configured", { detail: error.message || String(error) }); }
   }
 
@@ -3969,7 +4081,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const detailNote = !ok && r.detail ? ` — ${r.detail}` : "";
     const head = `${did} — ${ok ? "ok" : `⚠️ ${r.status}${detailNote}`} → now on **${r.screenTitle || "Unknown"}**`;
     const rec = typeof r.recordedSteps === "number" ? `\n\n🔴 Recording — ${r.recordedSteps} step(s). \`tapp_flow_save\` to keep it as a test.` : "";
-    return richResult(head + "\n\n" + formatScreen(r.screenTitle, r.elements) + rec, r);
+    const result = richResult(head + "\n\n" + formatScreen(r.screenTitle, r.elements) + rec, r);
+    if (!ok) result.isError = true;
+    return result;
   }
 
   if (name === "tapp_flow_save") {

package/mcp-server/src/pr-selection.js

@@ -410,7 +410,7 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   if (!prPlanPath || !fs.existsSync(source)) throw new Error(`PR plan not found: ${source || "(missing path)"}`);
   const targetPath = releasePlanPath === ".tapp/release-plan.json" ? existingProjectArtifactPath(root, "release-plan.json") : path.resolve(root, releasePlanPath);
   if (!inside(root, targetPath)) throw new Error("Release plan path must stay inside the project directory");
-  if (!fs.existsSync(targetPath)) throw new Error(`Release plan not found: ${targetPath}; run tapp init first`);
+  if (!fs.existsSync(targetPath)) throw new Error(`Release plan not found: ${targetPath}; run npx -y @aarwitz/tapp@latest init first`);
   const prPlan = JSON.parse(fs.readFileSync(source, "utf8"));
   if (prPlan?.schemaVersion !== 1 || !Array.isArray(prPlan.explorationTargets)) throw new Error("PR plan must be an executed Tapp PR plan v1");
   const matches = prPlan.explorationTargets.filter((target) => target.id === item);
@@ -428,7 +428,7 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   if (!ground || !fs.existsSync(mapPath)) throw new Error("Coverage proposal requires the repository's persistent UI Map");
   const map = JSON.parse(fs.readFileSync(mapPath, "utf8"));
   const node = (map.nodes || []).find((candidate) => candidate.id === ground.id && candidate.status !== "proposed");
-  const refreshAdvice = "refresh the persistent UI Map with `tapp init --explore --refresh`, rerun `tapp pr gate`, then retry `tapp pr adopt`";
+  const refreshAdvice = "refresh the persistent UI Map with `npx -y @aarwitz/tapp@latest init --explore --refresh`, rerun `npx -y @aarwitz/tapp@latest pr gate`, then retry `npx -y @aarwitz/tapp@latest pr adopt`";
   if (!node) throw new Error(`Coverage proposal UI Map node is stale or missing: ${ground.id}; ${refreshAdvice}`);
   if (target.navigation?.route && !(node.routes || []).some((route) => route.platform === target.platform && route.path === target.navigation.route && route.replayable === true)) {
     throw new Error(`Coverage proposal route is stale in the persistent UI Map: ${target.navigation.route}; ${refreshAdvice}`);

package/mcp-server/src/product-operations.js

@@ -79,7 +79,7 @@ function initTargetChoices(model, platform = "") {
   const candidates = (model.targets || []).filter((target) => !platform || target.platform === platform);
   return candidates.map((target) => ({
     target,
-    command: `tapp init . --explore --platform ${target.platform} --target ${target.sourcePath === "." ? JSON.stringify(target.name) : JSON.stringify(target.sourcePath)}`,
+    command: `npx -y @aarwitz/tapp@latest init . --explore --platform ${target.platform} --target ${target.sourcePath === "." ? JSON.stringify(target.name) : JSON.stringify(target.sourcePath)}`,
   }));
 }
 

package/mcp-server/src/report.js

@@ -146,6 +146,7 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   const screenElementCounts = {}; // screen -> max elements observed (content-collapse detection)
   let anySecure = false;
   let loginAttempted = false;
+  let credentialsProvided = base.complete?.credentialsProvided === true;
   let actions = 0;
 
   for (const line of raw.split(/\r?\n/)) {
@@ -158,7 +159,8 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
         // `target` gives a finding its identity beyond type|screen — two dead buttons on the
         // same screen are two findings, and fixing one while breaking another is a regression.
         const target = (typeof o.control === "string" && o.control) || (typeof o.target === "string" && o.target) || null;
-        rawIssues.push({ type: o.type, severity: sev, title: o.title, screen: o.screen || null, target, step: o.step ?? null });
+        const url = typeof o.url === "string" && o.url.trim() ? o.url.trim() : null;
+        rawIssues.push({ type: o.type, severity: sev, title: o.title, screen: o.screen || null, target, url, step: o.step ?? null });
       } catch {
         /* ignore malformed */
       }
@@ -175,6 +177,8 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
       t === "OCQA_STATE:login_preamble_two_step_submitted"
     ) {
       loginAttempted = true;
+    } else if (t === "OCQA_STATE:credentials_supplied") {
+      credentialsProvided = true;
     } else if (t.startsWith("OCQA_STATE:{")) {
       try {
         const s = JSON.parse(t.slice("OCQA_STATE:".length));
@@ -273,9 +277,9 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   const coverageFloorMet = platform === "web"
     ? screensExplored >= 1 && actionsPerformed >= 1
     : screensExplored >= 2 && actionsPerformed >= 3;
-  const credentiallessLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
-  const inconclusive = !coverageFloorMet || credentiallessLoginWall || timeBudgetExhausted;
-  const stopReason = credentiallessLoginWall ? "login-wall-no-credentials"
+  const unexercisedLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
+  const inconclusive = !coverageFloorMet || unexercisedLoginWall || timeBudgetExhausted;
+  const stopReason = unexercisedLoginWall ? (credentialsProvided ? "login-wall-credentials-unused" : "login-wall-no-credentials")
     : timeBudgetExhausted ? "time-budget-exhausted"
     : coverageFloorMet ? "completed" : "coverage-floor-not-met";
 
@@ -338,7 +342,9 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   // "Failed sign-ins" is only a claim when credentials were actually submitted. Merely seeing a
   // password field proves that a login surface was reached, not that authentication was exercised.
   if (loginAttempted) checkedFor.splice(2, 0, "failed sign-ins");
+  else if (anySecure && credentialsProvided) notChecked.push("sign-in behavior (test credentials were supplied, but no sign-in attempt was observed)");
   else if (anySecure) notChecked.push("sign-in behavior (login form reached, no test credentials supplied)");
+  else if (credentialsProvided) conditionsNotReached.push("sign-in (test credentials were supplied but no login form was encountered, so they were not used)");
   else conditionsNotReached.push("sign-in (no login form encountered this run)");
   if (timeBudgetExhausted) notChecked.push("the full requested action budget (run reached its wall-clock timeout)");
 
@@ -385,6 +391,13 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     screenElementCounts,
     inputFieldsEncountered,
     loginEncountered: anySecure,
+    credentialsProvided,
+    credentialsUsed: loginAttempted,
+    credentialWarning: credentialsProvided && !loginAttempted
+      ? anySecure
+        ? "Test credentials were supplied, but this run did not submit the login form. Authentication was not exercised."
+        : "Test credentials were supplied, but this run did not encounter a login form. They were not used."
+      : null,
     complete: base.complete,
     relativeMarkersFilePath: base.relativeMarkersFilePath,
   };

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

@@ -544,7 +544,8 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   const issues = []; // emitted immediately; kept for counting only
   const issue = (type, severity, title, screen, target) => {
     issues.push(type);
-    emit("ISSUE", { type, severity, title, screen, ...(target ? { target } : {}) });
+    const pageUrl = page.url();
+    emit("ISSUE", { type, severity, title, screen, ...(target ? { target } : {}), ...(pageUrl && pageUrl !== "about:blank" ? { url: pageUrl } : {}) });
   };
 
   // Async defect listeners: attribute to whatever screen is current when they fire.
@@ -925,7 +926,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       progress();
     }
   } finally {
-    emit("COMPLETE", { actions, screens: screenCount });
+    emit("COMPLETE", { actions, screens: screenCount, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried });
     fs.closeSync(markersFd);
     await browser.close().catch(() => {});
   }

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

@@ -132,6 +132,22 @@ export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout
       const el = await locateWebElement(page, target);
       if (!el) throw new Error(`no field ‘${target}’ to type into`);
       await el.fill(value);
+    } else if (action === "login") {
+      const emailValue = substituteFlowValue(raw.params.email || "$TEST_EMAIL", vars);
+      const passwordValue = substituteFlowValue(raw.params.password || "$TEST_PASSWORD", vars);
+      const email = await firstVisible([
+        page.locator("input[type=email]"), page.locator("input[name*=mail i]"),
+        page.locator("input[name*=user i]"), page.getByLabel(/email|user/i),
+      ]);
+      const password = await firstVisible([page.locator("input[type=password]"), page.getByLabel(/password|passcode/i)]);
+      if (!email || !password) throw new Error("could not identify email and password fields");
+      await email.fill(emailValue);
+      await password.fill(passwordValue);
+      const submit = await firstVisible([page.getByRole("button", { name:/sign in|log in|login|continue|submit/i })]);
+      if (!submit) throw new Error("could not identify a sign-in control");
+      await submit.click();
+      await page.waitForTimeout(400);
+      if (await password.isVisible().catch(() => false)) throw new Error("submit left the app on the login screen");
     } else if (action === "swipe") {
       const dy = target.toLowerCase() === "down" ? -600 : 600;
       await page.evaluate((y) => window.scrollBy({ top: y, behavior: "instant" }), dy);
@@ -173,7 +189,7 @@ export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout
     status = "fail";
     detail = error.message || String(error);
   }
-  return { action, target: target || value, status, detail, task: raw.task };
+  return { action, target: action === "login" ? "sign-in form" : target || value, status, detail, task: raw.task };
 }
 
 export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright }) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.0-rc.13",
+  "version": "0.17.0-rc.15",
   "mcpName": "io.github.aarwitz/tapp",
-  "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
+  "description": "Agent-driven app testing for iOS, Android, and web—real screens, replayable flows, and deterministic CI gates.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -59,7 +59,7 @@
     "type": "git",
     "url": "git+https://github.com/aarwitz/tapp.git"
   },
-  "homepage": "https://github.com/aarwitz/tapp#readme",
+  "homepage": "https://runtapp.com/",
   "bugs": {
     "url": "https://github.com/aarwitz/tapp/issues"
   },
@@ -89,7 +89,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js vscode-extension/test/bridge.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js vscode-extension/test/bridge.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/scripts/flow_lib.py

@@ -102,7 +102,7 @@ def report(path, as_json=False):
         return 0 if passed else 1
 
     icon = {"pass": "✅", "fail": "❌", "skip": "⚪️"}
-    verb = {"tap": "👆 tap", "type": "⌨️  type", "swipe": "↔️  swipe", "back": "◀️  back",
+    verb = {"tap": "👆 tap", "type": "⌨️  type", "login": "🔐 sign in", "swipe": "↔️  swipe", "back": "◀️  back",
             "wait": "⏳ wait", "wait_for": "⏳ wait for", "assert_screen": "🔎 screen is",
             "assert_exists": "🔎 exists", "assert_absent": "🔎 absent", "assert_text": "🔎 text",
             "assert_ai": "🤖 ai"}

package/scripts/quick-capture.sh

@@ -23,9 +23,9 @@ TAPP_RUNTIME_HOME="${TAPP_HOME:-}"
 if [[ -n "${TAPP_CAPTURE_DIR:-}" ]]; then
   CAPTURE_DIR="$TAPP_CAPTURE_DIR"
 elif [[ -n "$TAPP_RUNTIME_HOME" ]]; then
-  CAPTURE_DIR="$TAPP_RUNTIME_HOME/captures/$(date +%Y%m%d-%H%M%S)"
+  CAPTURE_DIR="$TAPP_RUNTIME_HOME/captures/ios-$(date +%Y%m%d-%H%M%S)"
 else
-  CAPTURE_DIR="$PROJECT_ROOT/captures/$(date +%Y%m%d-%H%M%S)"
+  CAPTURE_DIR="$PROJECT_ROOT/captures/ios-$(date +%Y%m%d-%H%M%S)"
 fi
 if [[ -n "$TAPP_RUNTIME_HOME" ]]; then
   HARNESS_DERIVED="$TAPP_RUNTIME_HOME/harness-derived"

package/skills/tapp/SKILL.md

@@ -33,8 +33,9 @@ When the user asks for a general first test of a repository:
 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, run `tapp doctor`, apply only the stated remediation that is in
-   scope, and retry once.
+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,