@aarwitz/tapp 0.17.0-rc.9 → 0.17.1

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

@@ -305,14 +305,25 @@ export class AndroidDriver {
     return r.stdout;
   }
 
-  async settle(timeoutMs = 2200) {
+  async settle(timeoutMs = 2200, previousSnapshot = null) {
     const deadline = Date.now() + timeoutMs;
+    const fingerprintOf = (snapshot) => (snapshot?.elements || [])
+      .map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
+    const previousScreen = String(previousSnapshot?.screenTitle || "");
+    const previousFingerprint = fingerprintOf(previousSnapshot);
     let previous = "";
     let stable = 0;
     let latest;
     while (Date.now() < deadline) {
       latest = await this.snapshot();
-      const fingerprint = latest.elements.map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
+      const fingerprint = fingerprintOf(latest);
+      // UIAutomator's dump command itself waits for the UI to become idle. If its first complete
+      // snapshot proves that the requested interaction changed the screen, a second identical
+      // dump adds roughly two seconds without adding evidence. Preserve the two-snapshot stability
+      // requirement when nothing changed (including delayed navigation and no-op controls).
+      if (previousSnapshot && fingerprint && (
+        String(latest.screenTitle || "") !== previousScreen || fingerprint !== previousFingerprint
+      )) return latest;
       if (fingerprint === previous) stable += 1; else stable = 0;
       if (stable >= 1) return latest;
       previous = fingerprint;

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

@@ -74,6 +74,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   const visited = new Map();
   let issues = 0;
   let actions = 0;
+  let loginTried = false;
   const crashExitBaseline = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
   let snap = await d.launch({ clearData });
   let crashReported = false;
@@ -210,6 +211,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     if (candidate) {
       const target = controlLabel(candidate);
       const loginSubmit = inputs.some((input) => input.secure) && isAndroidAuthSubmit(candidate);
+      if (loginSubmit) loginTried = true;
       tried.add(`${hash}|tap|${target}`);
       const before = hash;
       const r = await d.tap(target, snap);
@@ -260,7 +262,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   }
 
   const timedOut = Date.now() >= deadline;
-  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete", timedOut, ...(timedOut ? { timeoutSeconds: timeoutSec } : {}) });
+  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete", timedOut, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried, ...(timedOut ? { timeoutSeconds: timeoutSec } : {}) });
   onProgress({ action: actions, max: maxActions, states: visited.size });
   return { markersPath, outDir, actions, states: visited.size, issues, timedOut, seedTargets: normalizedTargets };
 }

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

@@ -43,6 +43,23 @@ export async function runAndroidFlow({ flow, appId, apkPath, serial, logPath, sc
       } else if (action === "type") {
         const r = await d.type(target, value, snap);
         if (r.status !== "ok") throw new Error(r.detail || `no field ‘${target}’ to type into`);
+      } else if (action === "login") {
+        const fields = snap.elements.filter((element) => /EditText/i.test(element.type));
+        const emailField = fields.find((element) => /email|user/i.test(`${element.id} ${element.label}`)) || fields.find((element) => !element.secure);
+        const passwordField = fields.find((element) => element.secure || /password|passcode/i.test(`${element.id} ${element.label}`));
+        if (!emailField || !passwordField) throw new Error("could not identify email and password fields");
+        const emailValue = substituteFlowValue(raw.params.email || "$TEST_EMAIL", vars);
+        const passwordValue = substituteFlowValue(raw.params.password || "$TEST_PASSWORD", vars);
+        const emailResult = await d.type(emailField.id || emailField.label, emailValue, snap);
+        if (emailResult.status !== "ok") throw new Error(emailResult.detail || "could not fill the email field");
+        snap = await d.settle();
+        const passwordResult = await d.type(passwordField.id || passwordField.label, passwordValue, snap);
+        if (passwordResult.status !== "ok") throw new Error(passwordResult.detail || "could not fill the password field");
+        snap = await d.settle();
+        const submit = snap.elements.find((element) => element.clickable && /sign in|log in|login|continue|submit/i.test(`${element.text} ${element.label} ${element.id}`));
+        if (!submit) throw new Error("could not identify a sign-in control");
+        const submitResult = await d.tap(submit.id || submit.description || submit.text, snap);
+        if (submitResult.status !== "ok") throw new Error(submitResult.detail || "could not submit the login form");
       } else if (action === "swipe") {
         await d.swipe(target || "up");
       } else if (action === "back") {
@@ -81,7 +98,7 @@ export async function runAndroidFlow({ flow, appId, apkPath, serial, logPath, sc
       detail = error.message || String(error);
       if (screenshotDir) await d.screenshot(path.join(screenshotDir, `flow-failure-${i + 1}.png`)).catch(() => {});
     }
-    log.step({ index: i + 1, action, target: target || value, status, detail, task: raw.task });
+    log.step({ index: i + 1, action, target: action === "login" ? "sign-in form" : target || value, status, detail, task: raw.task });
     if (status === "fail" && !flow.continueOnFailure) break;
   }
   if (screenshotDir) await d.screenshot(path.join(screenshotDir, "flow-final.png")).catch(() => {});

package/mcp-server/src/application-model.js

@@ -90,6 +90,7 @@ function applyRuntimeTargetValidation(root, targets, validation) {
   const bundleId = String(validation.target || validation.resolution.bundleId || "").trim();
   if (!container || !scheme || !bundleId) return targets;
   const captureId = String(validation.evidence?.captureId || "").trim();
+  const explored = !!captureId;
   return targets.map((target) => {
     if (target.platform !== "ios" || posix(target.sourcePath) !== container) return target;
     return {
@@ -109,7 +110,7 @@ function applyRuntimeTargetValidation(root, targets, validation) {
       runtimeValidation: {
         status: "validated",
         basis: "runtime-observed",
-        operation: "xcode-build-install-explore",
+        operation: explored ? "xcode-build-install-explore" : "xcode-build-install",
         target: bundleId,
         build: { container, scheme, configuration },
         evidence: {
@@ -118,7 +119,9 @@ function applyRuntimeTargetValidation(root, targets, validation) {
           findingCount: Number(validation.evidence?.findingCount || 0),
           ...(validation.evidence?.observedAt ? { observedAt: String(validation.evidence.observedAt) } : {}),
         },
-        detail: "Tapp built this repository target with the recorded scheme, installed it, launched it, and produced UI Map evidence.",
+        detail: explored
+          ? "Tapp built this repository target with the recorded scheme, installed it, launched it, and produced UI Map evidence."
+          : "Tapp built this repository target with the recorded scheme and installed it on an iOS simulator.",
       },
     };
   });
@@ -133,7 +136,7 @@ function persistedTargetValidations(root, outDir) {
   if (prior?.schemaVersion !== 1 || prior.kind !== "tapp-application-model" || !Array.isArray(prior.targets)) return [];
   return prior.targets.flatMap((target) => {
     const validation = target?.runtimeValidation;
-    if (target?.platform !== "ios" || validation?.status !== "validated" || validation?.basis !== "runtime-observed" || validation?.operation !== "xcode-build-install-explore") return [];
+    if (target?.platform !== "ios" || validation?.status !== "validated" || validation?.basis !== "runtime-observed" || !["xcode-build-install", "xcode-build-install-explore"].includes(validation?.operation)) return [];
     const capture = String(validation.evidence?.capture || "");
     return [{
       platform: "ios",
@@ -307,6 +310,31 @@ function loadTargetUiMaps(root, targets) {
     const scopeRoot = path.join(root, scope === "." ? "" : scope);
     const expectedPath = posix(path.join(scope === "." ? "" : scope, projectArtifactDirectory(scopeRoot), "ui-map.json"));
     let loaded = expectedPath === rootMap.summary.path ? rootMap : loadUiMapAt(root, expectedPath);
+    // Multiple targets can legitimately share an artifact directory (for example, a root Xcode
+    // project beside a root Vite app). A file being at the target's expected path does not prove
+    // it describes that target. Never attach a web-only map to iOS merely because both resolve to
+    // `.tapp/ui-map.json`; that duplicates proposals and, worse, claims runtime evidence for the
+    // wrong application surface.
+    if (loaded.map && targets.length > 1 && !uiMapTargetsTarget(loaded.map, target, targets)) {
+      loaded = {
+        map: null,
+        summary: {
+          path: expectedPath,
+          status: "missing",
+          nodeCount: 0,
+          edgeCount: 0,
+          controlCount: 0,
+          uncoveredNodeIds: [],
+          uncoveredEdgeIds: [],
+          platforms: [],
+          rejectedArtifact: {
+            path: loaded.summary.path,
+            platforms: loaded.summary.platforms || [],
+            reason: "artifact metadata does not identify this target",
+          },
+        },
+      };
+    }
     if (!loaded.map && rootMap.map && (targets.length === 1 || uiMapTargetsTarget(rootMap.map, target, targets))) loaded = rootMap;
     return {
       targetId: target.id,
@@ -424,7 +452,7 @@ function applicationName(root, targets) {
   return pkg?.name || (targets.length === 1 ? targets[0].name : path.basename(root));
 }
 
-export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, outDir = ".tapp" } = {}) {
+export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, defaultTargetId = "", outDir = ".tapp" } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   const inventory = walk(root);
   let targets = [
@@ -541,10 +569,10 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
   const requirements = [];
   if (!targets.length) requirements.push({ id: "target", severity: "blocking", status: "missing", message: "No iOS application project, Android application module, or browser application target was detected.", remediation: "Pass the representative target explicitly or add its unavoidable build/runtime configuration." });
   for (const target of targets) {
-    if (target.platform === "ios" && target.status !== "configured") requirements.push({ id: `${target.id}:scheme`, severity: "blocking", status: "needs-confirmation", message: `Confirm a shared build scheme for ${target.name}.`, remediation: `Run tapp build ${target.sourcePath} or provide the scheme during init/build.` });
+    if (target.platform === "ios" && target.status !== "configured") requirements.push({ id: `${target.id}:scheme`, severity: "blocking", status: "needs-confirmation", message: `Confirm a shared build scheme for ${target.name}.`, remediation: `Run npx -y @aarwitz/tapp@latest build ${target.sourcePath} or provide the scheme during init/build.` });
     if (target.platform === "android" && !target.runtime.applicationId) requirements.push({ id: `${target.id}:application-id`, severity: "blocking", status: "missing", message: `Android application id was not statically detected for ${target.name}.`, remediation: "Provide --app-id or expose applicationId in the application module." });
-    if (target.platform === "web" && !target.runtime.ownedUrl && target.runtime.management !== "tapp-managed") requirements.push({ id: `${target.id}:owned-url`, severity: "blocking", status: "missing", message: `No safe managed runtime or owned URL is available for ${target.name}.`, remediation: "Add a deterministic start/static target or start the app and rerun tapp init with --url http://127.0.0.1:<port>." });
-    if (target.platform === "web" && target.build.dependencyStatus === "missing-lockfile") requirements.push({ id: `${target.id}:dependency-lock`, severity: "blocking", status: "missing", message: `${target.name} declares browser dependencies without an observed dependency lockfile.`, remediation: "Commit the package-manager lockfile so Tapp can install dependencies reproducibly, then rerun tapp init." });
+    if (target.platform === "web" && !target.runtime.ownedUrl && target.runtime.management !== "tapp-managed") requirements.push({ id: `${target.id}:owned-url`, severity: "blocking", status: "missing", message: `No safe managed runtime or owned URL is available for ${target.name}.`, remediation: "Add a deterministic start/static target or start the app and rerun npx -y @aarwitz/tapp@latest init with --url http://127.0.0.1:<port>." });
+    if (target.platform === "web" && target.build.dependencyStatus === "missing-lockfile") requirements.push({ id: `${target.id}:dependency-lock`, severity: "blocking", status: "missing", message: `${target.name} declares browser dependencies without an observed dependency lockfile.`, remediation: "Commit the package-manager lockfile so Tapp can install dependencies reproducibly, then rerun npx -y @aarwitz/tapp@latest init." });
   }
   const incompleteMaps = uiMaps.filter((record) => record.summary.status !== "observed");
   for (const record of incompleteMaps.length ? incompleteMaps : (!targets.length && uiMap.status !== "observed" ? [{ summary: uiMap }] : [])) {
@@ -553,7 +581,7 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
     requirements.push({
       id: targets.length <= 1 ? "ui-map" : `${target.id}:ui-map`, severity: "blocking", status: summary.status === "inconclusive" ? "inconclusive" : "missing",
       message: target ? (summary.status === "inconclusive" ? `The UI Map for ${target.name} is inconclusive.` : `No grounded UI Map exists for ${target.name}.`) : "No repository UI Map has been grounded in a real run.",
-      remediation: target ? `Build/launch ${target.name}, explore the real target, and retain its map at ${summary.expectedPath || summary.path}.` : "Build/launch the target and run tapp init --explore so real exploration evidence is merged into .tapp/ui-map.json.",
+      remediation: target ? `Build/launch ${target.name}, explore the real target, and retain its map at ${summary.expectedPath || summary.path}.` : "Build/launch the target and run npx -y @aarwitz/tapp@latest init --explore so real exploration evidence is merged into .tapp/ui-map.json.",
     });
   }
   if (!contracts.length) requirements.push({ id: "contracts", severity: "warning", status: "missing", message: "No reviewed release contracts exist yet.", remediation: "Review the proposed release plan, then generate and validate a compact set of contracts." });
@@ -561,17 +589,20 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
   for (const error of projectConfiguration.errors) requirements.push({ id: stableId("project-config-error", error), severity: "blocking", status: "invalid", message: error, remediation: `Fix ${projectConfiguration.relativePath}; actor configuration must contain environment-variable bindings, never credential values.` });
   for (const actor of actors) {
     const missingBindings = actor.credentialRequirements.filter((credential) => !actor.credentialBindings[credential]);
-    if (missingBindings.length) requirements.push({ id: `actor:${actor.name}:credential-bindings`, severity: "blocking", status: "missing", message: `Actor '${actor.name}' has unbound credential requirements: ${missingBindings.join(", ")}.`, remediation: `Run tapp actor set ${actor.name} --credential <name>=<ENV_NAME> for each credential, then replace any literal contract credentials with $ENV_NAME placeholders.` });
+    if (missingBindings.length) requirements.push({ id: `actor:${actor.name}:credential-bindings`, severity: "blocking", status: "missing", message: `Actor '${actor.name}' has unbound credential requirements: ${missingBindings.join(", ")}.`, remediation: `Run npx -y @aarwitz/tapp@latest actor set ${actor.name} --credential <name>=<ENV_NAME> for each credential, then replace any literal contract credentials with $ENV_NAME placeholders.` });
     if (actor.bindingConflicts.length) requirements.push({ id: `actor:${actor.name}:credential-conflicts`, severity: "blocking", status: "conflict", message: `Actor '${actor.name}' has conflicting credential environment bindings.`, remediation: `Align ${projectConfiguration.relativePath} and reviewed contracts; Tapp will not guess which secret binding is correct.` });
   }
   for (const error of taskErrors) requirements.push({ id: stableId("task-error", error.path), severity: "blocking", status: "invalid", message: error.error, remediation: `Fix ${error.path} before generation.` });
   for (const error of contractErrors) requirements.push({ id: stableId("contract-error", error.path), severity: "blocking", status: "invalid", message: error.error, remediation: `Fix ${error.path} before trusting the release plan.` });
 
+  const recordedDefaultTargetId = targets.some((target) => target.id === defaultTargetId)
+    ? defaultTargetId
+    : targets.length === 1 ? targets[0].id : "";
   const model = {
     schemaVersion: 1, kind: "tapp-application-model",
-    // defaultTargetId: which target a bare `tapp explore` prepares when the repo has several (ADR-0005
-    // §5 resolution ladder). First detected; an explicit --target/--platform always overrides it.
-    application: { name: applicationName(root, targets), repositoryRoot: ".", platforms: [...new Set(targets.map((target) => target.platform))].sort(), targetIds: targets.map((target) => target.id), defaultTargetId: targets[0]?.id || "" },
+    // defaultTargetId is recorded only when selection is unambiguous or the user explicitly chose
+    // a target during source-connected exploration. Detection order is not user intent.
+    application: { name: applicationName(root, targets), repositoryRoot: ".", platforms: [...new Set(targets.map((target) => target.platform))].sort(), targetIds: targets.map((target) => target.id), defaultTargetId: recordedDefaultTargetId },
     targets,
     actors,
     entities,
@@ -956,6 +987,45 @@ export function writeInitArtifacts({ root, model, plan, outDir = ".tapp", refres
   return { modelPath, planPath, plan: mergedPlan };
 }
 
+export function findApplicationModelRoot(startPath) {
+  let current = path.resolve(startPath || process.cwd());
+  try {
+    if (!fs.statSync(current).isDirectory() || /\.(?:xcodeproj|xcworkspace)$/.test(current)) current = path.dirname(current);
+  } catch {
+    current = path.dirname(current);
+  }
+  while (true) {
+    const modelPath = path.join(current, projectArtifactDirectory(current), "application-model.json");
+    if (fs.existsSync(modelPath)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+// A successful standalone `tapp build` is runtime evidence that a proposed Xcode scheme is real.
+// Refresh an existing model immediately so a later `tapp init --refresh` does not forget it. This
+// deliberately does nothing before init: build remains a build command and does not mint a product
+// model unless the repository already opted into one.
+export async function persistIosBuildValidation({ projectDir, bundleId, container, scheme, configuration = "Debug" } = {}) {
+  return refreshExistingInitArtifacts({
+    projectDir: container || projectDir,
+    targetValidation: {
+      platform: "ios",
+      target: bundleId,
+      resolution: { kind: "xcode-build-installed", bundleId, build: { container, scheme, configuration } },
+      evidence: { observedAt: new Date().toISOString() },
+    },
+  });
+}
+
+export async function refreshExistingInitArtifacts({ projectDir, ...options } = {}) {
+  const root = findApplicationModelRoot(projectDir);
+  if (!root) return null;
+  const built = await buildInitArtifacts({ projectDir: root, ...options });
+  return { root, ...writeInitArtifacts({ ...built, refresh: true }) };
+}
+
 export function reviewReleasePlan(plan, { approve = [], reject = [], defer = [] } = {}) {
   const choices = new Map();
   for (const [decision, values] of Object.entries({ approved: approve, rejected: reject, deferred: defer })) {
@@ -994,7 +1064,7 @@ function edgeSupportsPlatform(edge, nodes, platform) {
 function shortestObservedPath(map, platform, targetId, { startNodeId } = {}) {
   const nodes = new Map((map.nodes || []).map((node) => [node.id, node]));
   const entryId = startNodeId || map.app?.navigationRoots?.[platform] || map.app?.entryNodes?.[platform];
-  if (!entryId || !nodes.has(entryId)) throw new Error(`UI Map has no observed ${platform} navigation root; rerun tapp init --refresh --explore before generating Tasks`);
+  if (!entryId || !nodes.has(entryId)) throw new Error(`UI Map has no observed ${platform} navigation root; rerun npx -y @aarwitz/tapp@latest init --refresh --explore before generating Tasks`);
   if (!nodes.has(targetId)) throw new Error(`UI Map proposal target '${targetId}' is no longer present`);
   if (entryId === targetId) return [];
   const outgoing = new Map();

package/mcp-server/src/ci-report.js

@@ -422,10 +422,10 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
         ? ` at \`${target.navigation.route}\``
         : target.navigation?.mode === "ui-map-path" ? ` through ${(target.navigation.steps || []).length} observed map edge(s)` : "";
       lines.push(`- ${icon} PR exploration **${target.node?.name || target.id}** — ${target.execution?.status || target.status}${navigation}`);
-      if (target.coverageProposal?.status === "awaiting-explicit-adoption") lines.push(`  - Reviewable coverage proposal ready; never auto-applied. Next: \`tapp pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
+      if (target.coverageProposal?.status === "awaiting-explicit-adoption") lines.push(`  - Reviewable coverage proposal ready; never auto-applied. Next: \`npx -y @aarwitz/tapp@latest pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
       if (target.existingReleasePlanItem) {
         lines.push(`  - Existing release-plan item \`${target.existingReleasePlanItem.name}\` remains ${target.existingReleasePlanItem.decision}; no duplicate or decision change was made.`);
-        lines.push(`  - Optional explicit evidence reconciliation: \`tapp pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
+        lines.push(`  - Optional explicit evidence reconciliation: \`npx -y @aarwitz/tapp@latest pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
       }
     }
     for (const candidate of prPlan.maintenanceCandidates || []) {

package/mcp-server/src/ci-setup.js

@@ -17,7 +17,7 @@ export function targetSlug(value) {
 
 export function selectApplicationTarget(model, { platform = "", target = "", useDefault = false } = {}) {
   if (model?.kind !== "tapp-application-model" || !Array.isArray(model.targets)) {
-    throw new Error("Expected a Tapp application model; run tapp init first");
+    throw new Error("Expected a Tapp application model; run npx -y @aarwitz/tapp@latest init first");
   }
   const selectedPlatform = String(platform || "").toLowerCase();
   let candidates = model.targets.filter((item) => !selectedPlatform || item.platform === selectedPlatform);
@@ -215,7 +215,7 @@ function credentialConfiguration(model, targetContracts = []) {
     if (requirements.has("email")) bindings.add("TAPP_TEST_EMAIL");
     if (requirements.has("password")) bindings.add("TAPP_TEST_PASSWORD");
   }
-  for (const name of bindings) if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(String(name))) throw new Error(`Actor credential binding '${name}' is not a safe environment-variable name; rerun tapp init from valid .tapp/project.json`);
+  for (const name of bindings) if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(String(name))) throw new Error(`Actor credential binding '${name}' is not a safe environment-variable name; rerun npx -y @aarwitz/tapp@latest init from valid .tapp/project.json`);
   const inputs = {};
   const primaryEmail = primary.credentialBindings?.email || (!primary.credentialBindings && requirements.has("email") ? "TAPP_TEST_EMAIL" : "");
   const primaryPassword = primary.credentialBindings?.password || (!primary.credentialBindings && requirements.has("password") ? "TAPP_TEST_PASSWORD" : "");
@@ -241,7 +241,7 @@ function targetInputs(root, model, target) {
     const androidProjectPath = path.resolve(root, androidProject);
     const androidProjectRelative = path.relative(root, androidProjectPath);
     if (path.isAbsolute(androidProjectRelative) || androidProjectRelative === ".." || androidProjectRelative.startsWith(`..${path.sep}`)) unresolved.push("Android Gradle project resolves outside the repository");
-    else if (!fs.existsSync(path.join(androidProjectPath, "gradlew"))) unresolved.push(`Gradle wrapper is missing from ${androidProject}; commit gradlew or rerun tapp init from the Gradle repository root`);
+    else if (!fs.existsSync(path.join(androidProjectPath, "gradlew"))) unresolved.push(`Gradle wrapper is missing from ${androidProject}; commit gradlew or rerun npx -y @aarwitz/tapp@latest init from the Gradle repository root`);
     inputs["android-project"] = androidProject;
     inputs["android-task"] = target.build?.task || "assembleDebug";
     if (target.runtime?.applicationId) inputs["android-app-id"] = target.runtime.applicationId;
@@ -282,7 +282,7 @@ export function renderGithubWorkflow({ projectDir, model, actionRef, defaultBran
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+@[A-Za-z0-9_.-]+$/.test(String(actionRef || ""))) throw new Error("--action-ref must be owner/repository@release-tag-or-sha");
   if (!/^[A-Za-z0-9._\/-]+$/.test(defaultBranch) || defaultBranch.startsWith("/")) throw new Error("--default-branch contains unsupported characters");
-  if (model?.kind !== "tapp-application-model" || !Array.isArray(model.targets) || !model.targets.length) throw new Error("Application model has no targets; run tapp init first");
+  if (model?.kind !== "tapp-application-model" || !Array.isArray(model.targets) || !model.targets.length) throw new Error("Application model has no targets; run npx -y @aarwitz/tapp@latest init first");
   const occupied = new Set();
   const jobs = [];
   const manifestTargets = [];

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

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const STORAGE_BLOCK_BYTES = 256 * 1024 * 1024;
+export const STORAGE_WARN_BYTES = 5 * 1024 * 1024 * 1024;
+
+function existingAncestor(candidate) {
+  let current = path.resolve(candidate || process.cwd());
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return current;
+}
+
+export function formatStorage(bytes) {
+  const gib = Number(bytes || 0) / (1024 ** 3);
+  return gib >= 1 ? `${gib.toFixed(gib >= 10 ? 0 : 1)} GiB` : `${Math.round(Number(bytes || 0) / (1024 ** 2))} MiB`;
+}
+
+export function storagePreflight(candidate, { statfs = fs.statfsSync, blockBytes = STORAGE_BLOCK_BYTES, warnBytes = STORAGE_WARN_BYTES } = {}) {
+  const checkedPath = existingAncestor(candidate);
+  if (!checkedPath || typeof statfs !== "function") return { ok: true, level: "unknown", path: checkedPath || path.resolve(candidate || process.cwd()), freeBytes: null };
+  try {
+    const stats = statfs(checkedPath);
+    const freeBytes = Number(stats.bavail ?? stats.bfree ?? 0) * Number(stats.bsize ?? 0);
+    const level = freeBytes < blockBytes ? "blocked" : freeBytes < warnBytes ? "warning" : "ok";
+    return {
+      ok: level !== "blocked",
+      level,
+      path: checkedPath,
+      freeBytes,
+      message: level === "blocked"
+        ? `Only ${formatStorage(freeBytes)} is free where Tapp writes evidence. Free disk space before testing; the run was not started and no app-crash finding was created.`
+        : level === "warning"
+          ? `Only ${formatStorage(freeBytes)} is free where Tapp writes builds and evidence; iOS builds can require several GiB.`
+          : `${formatStorage(freeBytes)} free for Tapp builds and evidence`,
+    };
+  } catch (error) {
+    return { ok: true, level: "unknown", path: checkedPath, freeBytes: null, message: `Free disk space could not be checked: ${error.message || String(error)}` };
+  }
+}