@aarwitz/tapp 0.17.0-rc.8 → 0.17.0

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)}` };
+  }
+}

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

@@ -18,7 +18,7 @@ const VALID_PLATFORMS = new Set(["web", "android", "ios"]);
 
 // Recover a capture's platform when no in-memory report is available. Prefer the run's persisted
 // metadata (ui-map.json → app.platforms) — it is authoritative and survives a renamed folder — and
-// fall back to the capture-id prefix (web-*/android-*, ios unprefixed) only for legacy captures that
+// fall back to the capture-id prefix (ios-*/web-*/android-*, with unprefixed iOS as a legacy case) only for captures that
 // predate the map. Defaults to ios if nothing is resolvable, matching buildQaReport's own default.
 export function capturePlatform(captureDir) {
   try {
@@ -81,7 +81,7 @@ export function writeHtmlReport(captureDir, { report, label = "", recordingWarni
         .map(
           (f) => `<li>
   <span class="sev" style="background:${SEV_COLOR[f.severity] || "#57606a"}">${esc(f.severity)}</span>
-  ${esc(f.title)}${f.screen ? ` <span class="dim">— on ${esc(f.screen)}</span>` : ""}
+  ${esc(f.title)}${f.screen ? ` <span class="dim">— on ${esc(f.screen)}</span>` : ""}${f.url ? ` <span class="dim">— ${esc(f.url)}</span>` : ""}
   ${f.aiAnalysis ? `<div class="ai">why: ${esc(f.aiAnalysis)}</div>` : ""}
   ${f.suggestedFix ? `<div class="ai">fix: ${esc(f.suggestedFix)}</div>` : ""}
 </li>`
@@ -138,6 +138,7 @@ ${r.conditionsNotReached?.length ? `<div><h2>Conditions not reached</h2><ul>${sc
 <div class="meta">${esc(label)} · evidence page (observation, not a release decision)</div>
 ${r.platform === "web" ? `<div class="meta">Deterministic basis: ${r.deterministicFindingCounts?.total || 0} deterministic finding(s); ${r.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory.</div>` : ""}
 <div class="headline">${esc(r.headline)}</div>
+${r.credentialWarning ? `<div class="warning">${esc(r.credentialWarning)}</div>` : ""}
 ${scopeHtml}
 <h2>Findings</h2>
 <ul class="findings">