@aarwitz/tapp 0.17.1 → 0.17.2

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

package/AGENTS.md

@@ -7,10 +7,9 @@ repository-connected deterministic gate.
 ## No MCP connected? Just run the CLI
 
 The core inspect, explore, replay, and gate capabilities work as plain commands — no Tapp account,
-server, or global install. `[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 (web) an http(s) URL. You never need to know a bundle id up front.
+server, or global install. `[target]` is optional: with a repository/model, Tapp selects and prepares
+one conclusive web, iOS, or Android target; it also accepts a repo dir, `path/to/App.app`, bundle id,
+APK plus app id, or an owned HTTP(S) URL. You never need to know an iOS bundle id up front.
 
 ```bash
 npx -y @aarwitz/tapp@latest explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
@@ -77,6 +76,7 @@ wander blindly or invent a route. URL-only targets correctly have no source adva
 
 ```
 tapp_session_start { appBundleId: "com.acme.app", focus: "Save storefront settings visible above keyboard", projectDir: "." }
+tapp_session_start { focus: "Storefront Settings", projectDir: "." } → managed web target from the workspace
 tapp_focus         { query: "Save storefront settings visible above keyboard" } → one-call shortest observed route
 tapp_session_act   { action: "login", email: "qa@x.com", password: "…" } → atomic fill + submit + verify
 tapp_session_act   { action: "tap",  id: "Email" }      → tap by a11y id OR visible label
@@ -153,7 +153,8 @@ without a coding agent, model, subscription, or API key. AI generation and `asse
 ## 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.
+  emulator/device; source builds also need JDK 17, while prebuilt APK testing does not. Web needs
+  Playwright + Chromium. `tapp doctor` reports each capability separately.
 - 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

package/README.md

@@ -84,7 +84,8 @@ agent:  "Done — and here it is working on the simulator: [screenshot]"
 ## npm CLI quickstart
 
 Requirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected
-emulator/device; web needs Playwright + Chromium.
+emulator/device (and JDK 17 when Tapp builds source rather than installing an existing APK); web
+needs Playwright + Chromium. `tapp doctor` reports these separately.
 
 From the app repository, ground Tapp once, then use the smallest operation for later checks:
 
@@ -337,7 +338,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@v0.17.1 # or pin the reviewed release commit SHA
+      - uses: aarwitz/tapp@v0.17.2 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -387,7 +388,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.1 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.2 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app

package/bin/tapp.js

@@ -217,6 +217,15 @@ function printEngineError(r) {
   if (r.details && Array.isArray(r.details.errors) && r.details.errors.length) {
     console.error(r.details.errors.map((e) => "  " + e.trim()).join("\n"));
   }
+  const choices = Array.isArray(r.details?.choices) ? r.details.choices : Array.isArray(r.details?.targets) ? r.details.targets : [];
+  if (choices.length) {
+    console.error("  Available targets:");
+    for (const choice of choices) {
+      const selector = choice.name || choice.id || choice.sourcePath;
+      console.error(`    ${choice.platform ? `${choice.platform} · ` : ""}${choice.name || choice.id}${choice.sourcePath ? ` (${choice.sourcePath})` : ""}${selector ? ` — use --target ${JSON.stringify(selector)}` : ""}`);
+    }
+  }
+  if (r.details?.remediation) console.error(`  Next: ${r.details.remediation}`);
 }
 
 async function promptForInitTarget(details) {
@@ -254,7 +263,7 @@ async function resolveTargetOrExit(engine, input) {
 function safeCommandUsage(verb) {
   const usage = {
     explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  Web: [--watch] opens Tapp's controlled browser and shows its actions\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
-    focus: "tapp focus \"SCREEN OR CONTROL\" [target] [--platform ios|android|web] [--project-dir REPO] [--map FILE] [--out FILE]",
+    focus: "tapp focus \"SCREEN OR CONTROL\" [target] [--platform ios|android|web] [--project-dir REPO] [--target NAME|PATH] [--map FILE] [--out FILE]",
     init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--watch] [--dry-run]",
     open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]",
     tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]",
@@ -544,33 +553,113 @@ switch (command) {
     const { flags, positionals } = parseVerbArgs(rest);
     const query = positionals[0] || "";
     if (!query) {
-      console.error('usage: tapp focus "SCREEN OR CONTROL" [target] [--platform ios|android|web] [--project-dir REPO] [--map FILE] [--out FILE]');
+      console.error('usage: tapp focus "SCREEN OR CONTROL" [target] [--platform ios|android|web] [--project-dir REPO] [--target NAME|PATH] [--map FILE] [--out FILE]');
       process.exit(2);
     }
     let projectDir;
     try { projectDir = fs.realpathSync(path.resolve(typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd())); }
     catch { console.error("❌ --project-dir must be an existing repository directory"); process.exit(2); }
     const target = positionals[1] || (typeof flags.url === "string" ? flags.url : "");
-    const platform = requestedPlatform(flags, target);
+    if (typeof flags["project-dir"] !== "string" && target && !/^https?:\/\//i.test(target)) {
+      try {
+        const targetPath = fs.realpathSync(path.resolve(target));
+        if (fs.statSync(targetPath).isDirectory()) projectDir = targetPath;
+      } catch { /* a bundle/application id is not a repository path */ }
+    }
+    let platform = requestedPlatform(flags, target);
+    let modeledTarget = null;
+    const directRuntimeTarget = /^https?:\/\//i.test(target) || /\.apk$/i.test(target)
+      || (target && !fs.existsSync(path.resolve(target)));
+    const modelPath = existingProjectArtifactPath(projectDir, "application-model.json");
+    if (!directRuntimeTarget && fs.existsSync(modelPath)) {
+      try {
+        const model = JSON.parse(fs.readFileSync(modelPath, "utf8"));
+        const { selectApplicationTarget } = await import(path.join(packageRoot, "mcp-server", "src", "ci-setup.js"));
+        modeledTarget = selectApplicationTarget(model, {
+          platform:typeof flags.platform === "string" ? flags.platform.toLowerCase() : "",
+          target:typeof flags.target === "string" ? flags.target.trim() : "",
+          useDefault:true,
+        });
+        platform = modeledTarget.platform;
+      } catch (error) {
+        let choices = [];
+        try {
+          const model = JSON.parse(fs.readFileSync(modelPath, "utf8"));
+          choices = (model.targets || []).filter((item) => typeof flags.platform !== "string" || item.platform === flags.platform.toLowerCase());
+        } catch { /* the primary parse/select error is printed below */ }
+        printEngineError({ error:error.message || String(error), details:{ targets:choices } });
+        process.exit(2);
+      }
+    }
     if (!["ios", "android", "web"].includes(platform)) { console.error("❌ --platform must be ios|android|web"); process.exit(2); }
     const engine = await engineImport();
     let started = null;
     try {
       if (platform === "ios") {
         requireMacFor("iOS focused navigation");
-        const sim = await engine.ensureBootedSim({ autoBoot:true });
-        if (sim.error) throw new Error(sim.error);
-        const bundleId = await resolveTargetOrExit(engine, target || projectDir);
+        let bundleId;
+        if (modeledTarget) {
+          const resolved = await engine.resolveAppTarget(path.resolve(projectDir, modeledTarget.sourcePath || "."), {
+            cwd:projectDir,
+            scheme:modeledTarget.build?.scheme || modeledTarget.build?.proposedScheme || "",
+            configuration:modeledTarget.build?.configuration || "Debug",
+            onStatus:(status) => console.error(`⏳ ${status}`),
+          });
+          if (resolved.error) {
+            printEngineError(resolved);
+            process.exitCode = 1;
+            break;
+          }
+          bundleId = resolved.bundleId;
+          if (resolved.via) console.error(`🎯 Target: ${bundleId} — ${resolved.via}`);
+        } else {
+          const sim = await engine.ensureBootedSim({ autoBoot:true });
+          if (sim.error) throw new Error(sim.error);
+          bundleId = await resolveTargetOrExit(engine, target || projectDir);
+        }
         const launch = iosLaunchOptions(flags, rest);
         started = await engine.startIosInteractiveSession(bundleId, engine.explorationEnvFromArgs({ testEmail:flags.email, testPassword:flags.password, ...launch }));
       } else if (platform === "android") {
-        const android = androidTarget(flags, target);
-        started = await engine.startAndroidInteractiveSession(android.appId, { serial:android.serial, apkPath:android.apkPath, clearData:flags["keep-data"] !== true });
+        const explicitAndroid = typeof flags["app-id"] === "string" || /\.apk$/i.test(target)
+          || (target && !fs.existsSync(path.resolve(target)));
+        if (explicitAndroid) {
+          const android = androidTarget(flags, target);
+          started = await engine.startAndroidInteractiveSession(android.appId, { serial:android.serial, apkPath:android.apkPath, clearData:flags["keep-data"] !== true });
+        } else {
+          const prepared = await engine.prepareAndroidInteractiveTarget({
+            projectDir,
+            target:typeof flags.target === "string" ? flags.target : modeledTarget?.id || "",
+            onStatus:(status) => console.error(`⏳ ${status}`),
+          });
+          if (prepared.error) {
+            printEngineError(prepared);
+            process.exitCode = 1;
+            break;
+          }
+          console.error(`🎯 Target: ${prepared.appId} — built ${prepared.selectedTarget.name} → ${prepared.apkPath}`);
+          started = await engine.startAndroidInteractiveSession(prepared.appId, {
+            serial:typeof flags.serial === "string" ? flags.serial : undefined,
+            apkPath:prepared.apkPath,
+            clearData:flags["keep-data"] !== true,
+          });
+        }
       } else {
-        if (!/^https?:\/\//i.test(target)) { console.error("❌ Web focus needs an http(s) target URL"); process.exit(2); }
-        started = await engine.startWebInteractiveSession(target);
+        started = /^https?:\/\//i.test(target)
+          ? await engine.startWebInteractiveSession(target)
+          : await engine.startManagedWebInteractiveSession({
+              projectDir,
+              requestedTarget:typeof flags.target === "string" ? flags.target : modeledTarget?.sourcePath || modeledTarget?.name || target,
+              timeout:flags.timeout,
+              testEmail:typeof flags.email === "string" ? flags.email : "",
+              testPassword:typeof flags.password === "string" ? flags.password : "",
+              onStatus:(status) => console.error(`⏳ ${status}`),
+            });
+      }
+      if (started.error) {
+        printEngineError(started);
+        process.exitCode = 1;
+        break;
       }
-      if (started.error) throw new Error(started.error);
       const focused = await engine.focusInteractiveSession({ projectDir, query, platform, mapPath:typeof flags.map === "string" ? flags.map : "" });
       const { focusedTargetSummary } = await import(path.join(packageRoot, "mcp-server", "src", "focused-navigation.js"));
       console.log(focusedTargetSummary(focused));
@@ -1338,7 +1427,7 @@ switch (command) {
       console.log(`  ⬜ iOS — requires macOS (this host: ${process.platform})`);
     }
 
-    const { resolveAdbPath } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
+    const { resolveAdbPath, resolveAndroidSdkRoot } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
     const adbPath = resolveAdbPath();
     const adb = adbPath ? run(adbPath, ["devices"]) : { code: 1, stdout: "" };
     if (adb.code === 0) {
@@ -1347,6 +1436,14 @@ switch (command) {
     } else {
       console.log("  ⬜ Android — adb not found (install Android SDK platform-tools)");
     }
+    const { resolveJavaRuntime } = await import(path.join(packageRoot, "mcp-server", "src", "environment-preflight.js"));
+    const java = resolveJavaRuntime();
+    const androidSdkRoot = resolveAndroidSdkRoot();
+    if (java && androidSdkRoot) ok("Android source builds", `${java.version || java.javaHome}; SDK ${androidSdkRoot}`);
+    else {
+      const missing = [!java ? "JDK 17" : "", !androidSdkRoot ? "Android SDK root" : ""].filter(Boolean).join(" and ");
+      console.log(`  ⬜ Android source builds — install/configure ${missing} (prebuilt APK testing still works)`);
+    }
 
     try {
       const { chromium } = await import("playwright");

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.1 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.2 # or pin the reviewed release commit SHA
   with:
     platform: web
     url: http://127.0.0.1:4180

package/mcp-server/src/android-driver.js

@@ -33,6 +33,13 @@ export function resolveAdbPath(env = process.env) {
   return executable("adb", env);
 }
 
+/** Resolve the SDK root from the same evidence used to find adb, including common unlinked
+ * Homebrew installations. Gradle needs this even when device automation already found adb. */
+export function resolveAndroidSdkRoot(env = process.env) {
+  const adbPath = resolveAdbPath(env);
+  return adbPath ? path.dirname(path.dirname(adbPath)) : null;
+}
+
 function runFile(command, args, { encoding = "utf8", timeout = 30_000, maxBuffer = 16 * 1024 * 1024 } = {}) {
   return new Promise((resolve) => {
     execFile(command, args, { encoding, timeout, maxBuffer }, (error, stdout, stderr) => {

package/mcp-server/src/environment-preflight.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 
 export const STORAGE_BLOCK_BYTES = 256 * 1024 * 1024;
 export const STORAGE_WARN_BYTES = 5 * 1024 * 1024 * 1024;
@@ -41,3 +42,37 @@ export function storagePreflight(candidate, { statfs = fs.statfsSync, blockBytes
     return { ok: true, level: "unknown", path: checkedPath, freeBytes: null, message: `Free disk space could not be checked: ${error.message || String(error)}` };
   }
 }
+
+/** Find a working Java runtime for repository-owned Android builds, including common unlinked
+ * Homebrew and Android Studio installations on macOS. APK/device testing itself does not need it. */
+export function resolveJavaRuntime(env = process.env, { probe = spawnSync, minimumMajor = 17 } = {}) {
+  const executable = process.platform === "win32" ? "java.exe" : "java";
+  const homes = [
+    env.JAVA_HOME,
+    process.platform === "darwin" ? "/Applications/Android Studio.app/Contents/jbr/Contents/Home" : "",
+    process.platform === "darwin" ? "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home" : "",
+    process.platform === "darwin" ? "/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home" : "",
+    process.platform === "darwin" ? "/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home" : "",
+    process.platform === "darwin" ? "/usr/local/opt/openjdk/libexec/openjdk.jdk/Contents/Home" : "",
+  ].filter(Boolean);
+  const candidates = [
+    ...homes.map((home) => ({ javaHome:home, javaPath:path.join(home, "bin", executable) })),
+    ...String(env.PATH || "").split(path.delimiter).filter(Boolean).map((dir) => ({ javaHome:"", javaPath:path.join(dir, executable) })),
+  ];
+  const seen = new Set();
+  for (const candidate of candidates) {
+    if (seen.has(candidate.javaPath) || !fs.existsSync(candidate.javaPath)) continue;
+    seen.add(candidate.javaPath);
+    const checked = probe(candidate.javaPath, ["-version"], { encoding:"utf8" });
+    if ((checked.status ?? 1) !== 0) continue;
+    const version = String(checked.stderr || checked.stdout || "").split(/\r?\n/)[0].trim();
+    const matched = version.match(/version\s+"(\d+)(?:\.(\d+))?/i);
+    const major = matched ? Number(matched[1] === "1" ? matched[2] : matched[1]) : 0;
+    if (!major || major < minimumMajor) continue;
+    let javaPath = candidate.javaPath;
+    try { javaPath = fs.realpathSync(javaPath); } catch { /* preserve the discovered path */ }
+    const javaHome = candidate.javaHome || path.dirname(path.dirname(javaPath));
+    return { javaPath, javaHome, version, major };
+  }
+  return null;
+}

package/mcp-server/src/index.js

@@ -418,9 +418,24 @@ export async function buildAndroidApp({ projectDir, gradleProjectDir, moduleDir,
   const wrapper = path.join(gradleRoot, process.platform === "win32" ? "gradlew.bat" : "gradlew");
   const command = fs.existsSync(wrapper) ? (process.platform === "win32" ? wrapper : "bash") : "gradle";
   const args = fs.existsSync(wrapper) && process.platform !== "win32" ? [wrapper, task, "--no-daemon"] : [task, "--no-daemon"];
-  const build = await runCommand(command, args, { cwd: gradleRoot, timeoutMs: 25 * 60 * 1000 });
+  const { resolveJavaRuntime } = await import("./environment-preflight.js");
+  const java = resolveJavaRuntime();
+  if (!java) return { error:"Android source builds need a working Java runtime. Install JDK 17 or set JAVA_HOME; an already-built APK can still be tested directly." };
+  const { resolveAndroidSdkRoot } = await import("./android-driver.js");
+  const androidSdkRoot = resolveAndroidSdkRoot();
+  if (!androidSdkRoot) return { error:"Android source builds need an Android SDK root. Install SDK platform-tools or set ANDROID_SDK_ROOT/ANDROID_HOME; an already-built APK can still be tested directly." };
+  const build = await runCommand(command, args, {
+    cwd:gradleRoot,
+    timeoutMs:25 * 60 * 1000,
+    env:{
+      JAVA_HOME:java.javaHome,
+      ANDROID_HOME:androidSdkRoot,
+      ANDROID_SDK_ROOT:androidSdkRoot,
+      PATH:`${path.dirname(java.javaPath)}${path.delimiter}${process.env.PATH || ""}`,
+    },
+  });
   if (build.code !== 0) {
-    const errors = `${build.stdout}\n${build.stderr}`.split("\n").filter((line) => /(?:error|failure|exception)/i.test(line)).slice(-10);
+    const errors = `${build.stdout}\n${build.stderr}`.split("\n").filter((line) => /(?:error|failure|exception|sdk location|could not|not found)/i.test(line)).slice(-10);
     return { error: `Android build failed (${task})${build.timedOut ? " — timed out" : ""}`, details: { errors, tail: (build.stderr || build.stdout || "").slice(-1800) } };
   }
   const apkPath = androidApkCandidates(moduleRoot)[0];
@@ -428,6 +443,34 @@ export async function buildAndroidApp({ projectDir, gradleProjectDir, moduleDir,
   return { apkPath, task, gradleProjectDir: gradleRoot, moduleDir: moduleRoot };
 }
 
+/** Resolve one reviewed Android target from the repository model and build its installable APK. */
+export async function prepareAndroidInteractiveTarget({ projectDir = process.cwd(), target = "", onStatus = () => {}, build = buildAndroidApp } = {}) {
+  let root;
+  try { root = fs.realpathSync(path.resolve(projectDir)); }
+  catch { return { error:`Repository directory not found: ${projectDir}` }; }
+  const modelPath = existingProjectArtifactPath(root, "application-model.json");
+  if (!fs.existsSync(modelPath)) return { error:"No application model found — run `npx -y @aarwitz/tapp@latest init . --explore --platform android` first." };
+  let model;
+  try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
+  catch (error) { return { error:`Application model is unreadable: ${error.message || String(error)}` }; }
+  const { selectApplicationTarget } = await import("./ci-setup.js");
+  let selected;
+  try { selected = selectApplicationTarget(model, { platform:"android", target, useDefault:true }); }
+  catch (error) { return { error:error.message || String(error), details:error.details || {} }; }
+  const appId = String(selected.runtime?.applicationId || "").trim();
+  if (!appId) return { error:`The Android target '${selected.name}' has no confirmed application id — rerun init or provide --app-id.` };
+  const task = selected.build?.task || "assembleDebug";
+  onStatus(`Building the Android APK for ${selected.name} (${task})…`);
+  const built = await build({
+    projectDir:root,
+    gradleProjectDir:path.resolve(root, selected.build?.projectDir || "."),
+    moduleDir:path.resolve(root, selected.sourcePath || "."),
+    task,
+  });
+  if (built.error) return built;
+  return { ...built, appId, selectedTarget:selected };
+}
+
 export async function installAppOnBootedSim(appPath, { cleanInstall = true } = {}) {
   const bid = await runCommand("/usr/libexec/PlistBuddy", ["-c", "Print CFBundleIdentifier", path.join(appPath, "Info.plist")], { timeoutMs: 30_000 });
   const bundleId = (bid.stdout || "").trim();
@@ -762,6 +805,32 @@ async function startWebSession(url, { testEmail = "", testPassword = "" } = {})
   }
 }
 
+/**
+ * Start a persistent web session from an owned repository target. The managed runtime belongs to
+ * the session and is stopped by endSession(), so MCP/CLI callers cannot strand a development
+ * server when focus succeeds, fails, or the client explicitly ends the session.
+ */
+export async function startManagedWebInteractiveSession({
+  projectDir = process.cwd(), requestedTarget = "", timeout,
+  testEmail = "", testPassword = "", onStatus = () => {},
+} = {}) {
+  let root;
+  try { root = fs.realpathSync(path.resolve(projectDir)); }
+  catch { return { error:`Repository directory not found: ${projectDir}` }; }
+  const runtime = await startManagedWebTarget({ root, requestedTarget, timeout, onStatus });
+  if (runtime.error) return runtime;
+  const session = await startWebSession(runtime.url, { testEmail, testPassword });
+  if (session.error) {
+    await stopManagedWebTarget(runtime);
+    return session;
+  }
+  if (activeSession?.platform === "web") activeSession.managedRuntime = runtime;
+  return {
+    ...session,
+    managedRuntime:{ url:runtime.url, logPath:runtime.logPath, start:runtime.start },
+  };
+}
+
 /** Turn a typed value into a shareable token: known creds become $TEST_EMAIL / $TEST_PASSWORD. */
 function templateValue(text) {
   const c = (activeSession && activeSession.creds) || {};
@@ -1001,6 +1070,7 @@ async function endSession() {
   if (s.platform === "web") {
     activeSession = null;
     await s.browser.close().catch(() => {});
+    if (s.managedRuntime) await stopManagedWebTarget(s.managedRuntime).catch(() => {});
     return { ok:true };
   }
   if (s.platform === "android") {
@@ -2964,7 +3034,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_session_start",
       title: "Start interactive session",
       description:
-        "Start a PERSISTENT interactive session against an installed iOS/Android app or a web URL. The app " +
+        "Start a PERSISTENT interactive session against an installed iOS/Android app, a web URL, or an " +
+        "unambiguous managed web target in the MCP workspace. The app " +
         "launches once and stays up, so you can drive a Playwright-style tap → inspect loop without a cold " +
         "launch per action. Returns the initial screen {screenTitle, elements[]}. Drive it with " +
         "tapp_focus for any named destination (source + shortest observed route), then tapp_session_act only for remaining actions; finish with tapp_session_end. " +
@@ -2978,7 +3049,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           appBundleId: { type: "string", description: "Bundle id of the installed app to drive" },
           androidAppId: { type: "string", description: "Android application id to drive (alternative to appBundleId)" },
-          url: { type: "string", description: "Owned http(s) web app URL to drive (alternative to appBundleId/androidAppId)" },
+          url: { type: "string", description: "Owned http(s) web app URL to drive (alternative to appBundleId/androidAppId); omit all three target identifiers to build/start an unambiguous owned web target from projectDir" },
+          target: { type: "string", description: "Optional managed-web target name/path when projectDir contains multiple browser applications" },
           apkPath: { type: "string", description: "Android APK to install before starting" },
           androidSerial: { type: "string", description: "Android adb device serial" },
           clearData: { type: "boolean", default: true, description: "Android: clear app data before launch" },
@@ -4100,7 +4172,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     const maxWidth = Math.max(200, Math.min(1400, asInteger(args.maxWidth, 700)));
     const r = await openApp(String(args.appBundleId).trim(), explorationEnvFromArgs(args), maxWidth);
-    if (r.error) return errorResult(r.error);
+    if (r.error) return errorResult(r.error, r.details || {});
     const content = [];
     content.push({ type: "text", text: `🚀 Launched \`${String(args.appBundleId).trim()}\`\n\n` + formatScreen(r.screenTitle, r.elements) });
     if (r.img && !r.img.error) content.push({ type: "image", data: r.img.data, mimeType: r.img.mimeType });
@@ -4201,10 +4273,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const ios = isNonEmptyString(args.appBundleId);
     const android = isNonEmptyString(args.androidAppId);
     const web = isNonEmptyString(args.url);
-    if ([ios, android, web].filter(Boolean).length !== 1) return errorResult("Provide exactly one of appBundleId, androidAppId, or url");
-    const target = ios ? args.appBundleId.trim() : android ? args.androidAppId.trim() : args.url.trim();
+    if ([ios, android, web].filter(Boolean).length > 1) return errorResult("Provide at most one of appBundleId, androidAppId, or url");
+    const managedWeb = !ios && !android && !web;
+    let target = ios ? args.appBundleId.trim() : android ? args.androidAppId.trim() : web ? args.url.trim() : "managed web target";
     let focusProjectDir = workspaceRoot;
-    if (isNonEmptyString(args.focus)) {
+    if (isNonEmptyString(args.focus) || managedWeb) {
       try { focusProjectDir = fs.realpathSync(path.resolve(workspaceRoot, isNonEmptyString(args.projectDir) ? args.projectDir.trim() : ".")); }
       catch { return errorResult("projectDir must be an existing directory inside the workspace"); }
       if (!isInsideDir(workspaceRoot, focusProjectDir) || !fs.statSync(focusProjectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the workspace");
@@ -4213,8 +4286,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       ? await startSession(target, explorationEnvFromArgs(args))
       : android
         ? await startAndroidSession(target, { serial: args.androidSerial, apkPath: args.apkPath, clearData: args.clearData !== false, testEmail: args.testEmail, testPassword: args.testPassword })
-        : await startWebSession(target, { testEmail:args.testEmail, testPassword:args.testPassword });
-    if (r.error) return errorResult(r.error);
+        : web
+          ? await startWebSession(target, { testEmail:args.testEmail, testPassword:args.testPassword })
+          : await startManagedWebInteractiveSession({
+              projectDir:focusProjectDir,
+              requestedTarget:isNonEmptyString(args.target) ? args.target.trim() : "",
+              testEmail:args.testEmail,
+              testPassword:args.testPassword,
+            });
+    if (r.error) return errorResult(r.error, r.details || {});
+    if (managedWeb) target = r.url || r.managedRuntime?.url || target;
     let focused = null;
     if (isNonEmptyString(args.focus)) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "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

@@ -38,7 +38,9 @@ When the user asks for a general first test of a repository:
    `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.
+For a focused request in an already-grounded repository, use the requested target directly rather
+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.
@@ -48,8 +50,10 @@ clicks and types.
 When the user names a screen, control, or UI condition, do not discover the app one screenshot at a
 time. Start from the repository source, then use Tapp's observed navigation evidence:
 
-1. With MCP, pass the exact request as `focus` to `tapp_session_start`, or call `tapp_focus` in an
-   active session. Without MCP, run `npx -y @aarwitz/tapp@latest focus "<exact request>" [target]`.
+1. In a source repository, run `npx -y @aarwitz/tapp@latest focus "<exact request>" [target]`; it
+   selects the reviewed model target and prepares web, iOS, or Android from source. In an active MCP
+   session call `tapp_focus`; for managed web, `tapp_session_start` can also take `projectDir` and
+   `focus` without retyping the URL.
 2. Tapp searches owned source, reconciles the likely surface with `.tapp/ui-map.json`, and executes
    the shortest runtime-observed route in one call. Read its final tree before visual assertions.
 3. If Tapp returns source evidence but no replayable route, inspect the cited file/line and relevant
@@ -91,5 +95,4 @@ 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.
+Read [references/commands.md](references/commands.md) only for exact CLI/MCP syntax, Flow replay, credentials, or platform prerequisites.

package/skills/tapp/references/commands.md

@@ -27,7 +27,10 @@ npx -y @aarwitz/tapp@latest explore https://staging.example.com
 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.
+# Android source: select a modeled target; Tapp builds, installs, and focuses it.
+npx -y @aarwitz/tapp@latest focus "About screen" . --target demoapp
+
+# Android black-box entry: 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
 ```
 
@@ -51,8 +54,9 @@ npx -y @aarwitz/tapp@latest open https://example.com --tap "Not now" --wait-for
 - `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`.
+returned `bundleId`. Android uses `androidAppId` and optional `apkPath`. Web can use an explicit
+owned `url`, or `tapp_session_start {projectDir:".", focus:"..."}` can build/start one unambiguous
+owned browser target and stop it with `tapp_session_end`.
 
 ## Interactive session loop
 
@@ -98,7 +102,8 @@ 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.
+- Android: `adb` and a connected authorized emulator/device; JDK 17 for source builds (not for a
+  prebuilt APK).
 - Web: Playwright and Chromium. If Tapp reports the browser missing, run
   `npx playwright install chromium` and retry.