@aarwitz/tapp 0.15.0

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

@@ -0,0 +1,526 @@
+// Tapp's customer-journey engine. Every user-facing adapter should be thin:
+// validate its transport, call one of these operations, and render the result.
+// This module owns repository artifact semantics and never imports a UI adapter.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildInitArtifacts,
+  generateApprovedContractProposals,
+  mergeGeneratedTaskProposalValidation,
+  promoteValidatedProposals,
+  recordContractProposalValidation,
+  recordGeneratedTaskProposalValidation,
+  reviewReleasePlan,
+  writeInitArtifacts,
+} from "./application-model.js";
+import { baselinePathForTarget, renderGithubWorkflow, selectApplicationTarget, writeCiInstallation, writeTargetBaseline } from "./ci-setup.js";
+import { executeReleaseContract, runProductProcess } from "./product-execution.js";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+const DEFAULT_ACTION_REF = `aarwitz/tapp@v${packageVersion}`;
+
+function realProject(projectDir) {
+  const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
+  if (!fs.statSync(root).isDirectory()) throw new Error(`Repository directory not found: ${root}`);
+  return root;
+}
+
+function inside(root, value) {
+  const candidate = path.resolve(value);
+  return candidate === root || candidate.startsWith(root + path.sep);
+}
+
+function readJson(file, { required = false } = {}) {
+  if (!fs.existsSync(file)) {
+    if (required) throw new Error(`Required artifact not found: ${file}`);
+    return null;
+  }
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (error) { throw new Error(`Invalid JSON in ${file}: ${error.message}`); }
+}
+
+function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(temporary, JSON.stringify(value, null, 2) + "\n");
+  fs.renameSync(temporary, file);
+}
+
+function artifactPaths(root, outDir = ".autotap") {
+  const dir = path.resolve(root, outDir);
+  if (!inside(root, dir)) throw new Error("Artifact directory must remain inside the repository");
+  return {
+    dir,
+    model: path.join(dir, "application-model.json"),
+    plan: path.join(dir, "release-plan.json"),
+    map: path.join(dir, "ui-map.json"),
+    ci: path.join(dir, "ci.json"),
+  };
+}
+
+function productRunRoot(root) {
+  const home = process.env.AUTOTAP_HOME || process.env.TAPP_HOME || path.join(os.homedir(), ".tapp");
+  const identity = crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
+  return path.join(home, "product-runs", identity);
+}
+
+function listProductRuns(root) {
+  const runsRoot = productRunRoot(root);
+  if (!fs.existsSync(runsRoot)) return [];
+  return fs.readdirSync(runsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const dir = path.join(runsRoot, entry.name);
+      const reportPath = path.join(dir, "gate-report.json");
+      const markdownPath = path.join(dir, "gate-report.md");
+      const report = readJson(reportPath);
+      return {
+        id: entry.name,
+        createdAt: fs.statSync(dir).birthtime.toISOString(),
+        status: report ? "completed" : "incomplete",
+        verdict: report?.verdict || null,
+        gate: report?.gate || null,
+        reportPath: fs.existsSync(reportPath) ? reportPath : null,
+        markdownPath: fs.existsSync(markdownPath) ? markdownPath : null,
+        report,
+      };
+    })
+    .sort((left, right) => right.id.localeCompare(left.id))
+    .slice(0, 20);
+}
+
+function listRepositoryFlows(root) {
+  const directory = path.join(root, ".autotap", "flows");
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes:true })
+    .filter((entry) => entry.isFile() && /\.(?:ya?ml|json)$/i.test(entry.name))
+    .map((entry) => {
+      const file = path.join(directory, entry.name);
+      const relativePath = path.relative(root, file).replaceAll(path.sep, "/");
+      let name = entry.name.replace(/\.(?:ya?ml|json)$/i, "");
+      let platform = "ios";
+      let steps = 0;
+      try {
+        const source = fs.readFileSync(file, "utf8");
+        if (entry.name.endsWith(".json")) {
+          const parsed = JSON.parse(source);
+          name = String(parsed.name || name);
+          platform = String(parsed.platform || (/^https?:\/\//i.test(parsed.url || parsed.app || "") ? "web" : "ios")).toLowerCase();
+          steps = Array.isArray(parsed.steps) ? parsed.steps.length : 0;
+        } else {
+          const scalar = (key) => {
+            const match = source.match(new RegExp(`^${key}:\\s*(.+?)\\s*$`, "m"));
+            return match ? match[1].replace(/^["']|["']$/g, "") : "";
+          };
+          name = scalar("name") || name;
+          platform = (scalar("platform") || (/^url:\s*https?:\/\//im.test(source) ? "web" : "ios")).toLowerCase();
+          const block = source.split(/^steps:\s*$/m)[1] || "";
+          steps = (block.match(/^\s{2}-\s/gm) || []).length;
+        }
+      } catch { /* Artifact remains inspectable; deterministic replay reports invalid syntax. */ }
+      return { id:`flow_${crypto.createHash("sha256").update(relativePath).digest("hex").slice(0, 16)}`, name, path:relativePath, platform, steps, status:"committed" };
+    })
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function readProductProject({ projectDir, outDir = ".autotap" } = {}) {
+  const root = realProject(projectDir);
+  const paths = artifactPaths(root, outDir);
+  const model = readJson(paths.model);
+  const plan = readJson(paths.plan);
+  const map = readJson(paths.map);
+  const ci = readJson(paths.ci);
+  const requirements = model?.requirements || [];
+  const planItems = plan?.items || [];
+  const baselines = (model?.targets || []).map((target) => {
+    const file = baselinePathForTarget(root, target);
+    return { targetId: target.id, platform: target.platform, path: file, relativePath: path.relative(root, file).replaceAll(path.sep, "/"), exists: fs.existsSync(file) };
+  });
+  return {
+    kind: "tapp-product-project",
+    schemaVersion: 1,
+    root,
+    application: model?.application || { name: path.basename(root), platforms: [], targetIds: [] },
+    targets: model?.targets || [],
+    actors: model?.actors || [],
+    capabilities: model?.capabilities || [],
+    requirements,
+    model,
+    map,
+    plan,
+    ci,
+    baselines,
+    flows: listRepositoryFlows(root),
+    evidence: listProductRuns(root),
+    state: {
+      inspected: !!model,
+      explored: map?.nodes?.length > 0 && model?.uiMap?.status === "observed",
+      reviewComplete: !!plan && !planItems.some((item) => item.decision === "pending"),
+      generated: planItems.some((item) => item.generation?.path),
+      validated: planItems.some((item) => item.generation?.trusted === true || item.generation?.status === "validated-draft"),
+      promoted: planItems.some((item) => item.decision === "accepted" || item.origin === "committed"),
+      ciPrepared: !!ci,
+      baselineReady: baselines.some((item) => item.exists),
+      blockingRequirements: requirements.filter((item) => item.severity === "blocking").length,
+    },
+    paths,
+  };
+}
+
+// Resolve and, when needed, build one canonical Application Model target. UI
+// adapters provide platform tool invocations; selection and runtime semantics
+// stay here so browser, CLI, MCP, and managed runners do not invent their own
+// target identity or configuration rules.
+export async function prepareProductTarget({
+  projectDir,
+  outDir = ".autotap",
+  platform = "",
+  target = "",
+  appPath = "",
+  apkPath = "",
+  bundleId = "",
+  appId = "",
+  scheme = "",
+  configuration = "",
+  buildIos,
+  installIos,
+  buildAndroid,
+  onProgress = () => {},
+} = {}) {
+  const root = realProject(projectDir);
+  const project = readProductProject({ projectDir: root, outDir });
+  if (!project.model) throw new Error("Application model not found; inspect the repository first");
+  const selectedTarget = selectApplicationTarget(project.model, { platform, target });
+  const runtime = { platform: selectedTarget.platform, target: selectedTarget.id };
+
+  if (selectedTarget.platform === "web") {
+    runtime.url = selectedTarget.runtime?.ownedUrl || "";
+    runtime.management = selectedTarget.runtime?.management || "unresolved";
+    return { operation: "prepare-target", selectedTarget, runtime };
+  }
+
+  if (selectedTarget.platform === "android") {
+    runtime.appId = String(appId || selectedTarget.runtime?.applicationId || "").trim();
+    if (!runtime.appId) throw new Error(`Android target '${selectedTarget.name}' needs an application id before it can run`);
+    let resolvedApk = String(apkPath || "").trim();
+    if (resolvedApk) {
+      resolvedApk = path.resolve(resolvedApk);
+      if (!fs.existsSync(resolvedApk)) throw new Error(`Android APK not found: ${resolvedApk}`);
+    } else {
+      if (typeof buildAndroid !== "function") throw new Error(`Android target '${selectedTarget.name}' needs a build-capable runner or a prebuilt APK`);
+      onProgress({ phase: "build", text: `Building Android target ${selectedTarget.name}` });
+      const built = await buildAndroid({
+        projectDir: root,
+        gradleProjectDir: path.resolve(root, selectedTarget.build?.projectDir || "."),
+        moduleDir: path.resolve(root, selectedTarget.sourcePath || "."),
+        task: selectedTarget.build?.task || "assembleDebug",
+        target: selectedTarget,
+      });
+      if (built?.error) throw Object.assign(new Error(built.error), { details: built.details || {} });
+      resolvedApk = built?.apkPath || "";
+      if (!resolvedApk || !fs.existsSync(resolvedApk)) throw new Error(`Android build for '${selectedTarget.name}' produced no readable APK`);
+      runtime.build = built;
+    }
+    runtime.apkPath = resolvedApk;
+    return { operation: "prepare-target", selectedTarget, runtime };
+  }
+
+  let resolvedApp = String(appPath || "").trim();
+  if (resolvedApp) {
+    resolvedApp = path.resolve(resolvedApp);
+    if (!resolvedApp.endsWith(".app") || !fs.existsSync(resolvedApp)) throw new Error(`iOS simulator app not found: ${resolvedApp}`);
+  } else {
+    if (typeof buildIos !== "function") throw new Error(`iOS target '${selectedTarget.name}' needs a macOS/Xcode runner or a prebuilt simulator .app`);
+    onProgress({ phase: "build", text: `Building iOS target ${selectedTarget.name}` });
+    const built = await buildIos({
+      container: path.resolve(root, selectedTarget.build?.container || selectedTarget.sourcePath || "."),
+      scheme: String(scheme || selectedTarget.build?.proposedScheme || ""),
+      configuration: String(configuration || selectedTarget.build?.configuration || "Debug"),
+      target: selectedTarget,
+    });
+    if (built?.error) throw Object.assign(new Error(built.error), { details: built.details || {} });
+    resolvedApp = built?.appPath || "";
+    if (!resolvedApp || !fs.existsSync(resolvedApp)) throw new Error(`iOS build for '${selectedTarget.name}' produced no readable simulator .app`);
+    runtime.build = built;
+  }
+  runtime.appPath = resolvedApp;
+  runtime.bundleId = String(bundleId || selectedTarget.runtime?.bundleId || "").trim();
+  if (typeof installIos === "function") {
+    onProgress({ phase: "runtime", text: `Installing ${path.basename(resolvedApp)} on the simulator` });
+    const installed = await installIos(resolvedApp);
+    if (installed?.error) throw Object.assign(new Error(installed.error), { details: installed.details || {} });
+    runtime.bundleId = installed?.bundleId || runtime.bundleId;
+    runtime.install = installed;
+  }
+  return { operation: "prepare-target", selectedTarget, runtime };
+}
+
+export async function initializeProductProject({
+  projectDir,
+  mode = "inspect",
+  outDir = ".autotap",
+  ownedUrl = "",
+  platform = "",
+  target = "",
+  bundleId = "",
+  appId = "",
+  apkPath,
+  serial,
+  scheme = "",
+  configuration = "Debug",
+  maxActions = 40,
+  timeout = 600,
+  maxContracts = 15,
+  testEmail,
+  testPassword,
+  runExploration,
+  onProgress = () => {},
+  onStatus = () => {},
+} = {}) {
+  const root = realProject(projectDir);
+  if (!["inspect", "write", "refresh", "explore"].includes(mode)) throw new Error("mode must be inspect|write|refresh|explore");
+  if (!Number.isInteger(Number(maxContracts)) || Number(maxContracts) < 1 || Number(maxContracts) > 50) throw new Error("maxContracts must be between 1 and 50");
+  const paths = artifactPaths(root, outDir);
+  let exploration = null;
+  if (mode === "explore") {
+    if (typeof runExploration !== "function") throw new Error("The selected adapter did not provide a platform exploration capability");
+    const selectedPlatform = String(platform || (ownedUrl ? "web" : appId || apkPath ? "android" : "ios")).toLowerCase();
+    exploration = await runExploration({
+      projectDir: root, platform: selectedPlatform, outDir, url: ownedUrl, target: target || root,
+      bundleId, appId, apkPath, serial, scheme, configuration, maxActions: Number(maxActions), timeout: Number(timeout),
+      testEmail, testPassword, onProgress, onStatus,
+    });
+    if (exploration?.error) throw Object.assign(new Error(exploration.error), { details: exploration.details || {} });
+  }
+  const built = await buildInitArtifacts({
+    projectDir: root,
+    ownedUrl: ownedUrl || (exploration?.platform === "web" && !exploration.managedRuntime ? exploration.target : ""),
+    platform: String(platform || "").toLowerCase(),
+    targetValidation: exploration?.targetValidation || null,
+    outDir,
+    maxContracts: Number(maxContracts),
+  });
+  let written = null;
+  if (mode !== "inspect") {
+    const existing = fs.existsSync(paths.model) || fs.existsSync(paths.plan);
+    written = writeInitArtifacts({
+      ...built,
+      root: built.root,
+      outDir,
+      refresh: mode === "refresh" || (mode === "explore" && existing),
+      invalidateValidation: mode === "explore",
+    });
+  }
+  return { operation: "initialize", mode, model: built.model, plan: written?.plan || built.plan, exploration, written, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+function resolvePlan(root, outDir, planPath = "") {
+  const paths = artifactPaths(root, outDir);
+  const candidate = path.resolve(root, planPath || path.relative(root, paths.plan));
+  const file = fs.existsSync(candidate) ? fs.realpathSync(candidate) : candidate;
+  if (!inside(root, file)) throw new Error("Release plan must remain inside the repository");
+  return { file, plan: readJson(file, { required: true }) };
+}
+
+export function reviewProductPlan({ projectDir, outDir = ".autotap", planPath = "", approve = [], reject = [], defer = [] } = {}) {
+  const root = realProject(projectDir);
+  const resolved = resolvePlan(root, outDir, planPath);
+  const plan = reviewReleasePlan(resolved.plan, { approve, reject, defer });
+  atomicJson(resolved.file, plan);
+  return { operation: "review-plan", plan, planPath: resolved.file, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+export async function generateProductPlan({ projectDir, outDir = ".autotap", planPath = "" } = {}) {
+  const root = realProject(projectDir);
+  const resolved = resolvePlan(root, outDir, planPath);
+  const result = await generateApprovedContractProposals(resolved.plan, { projectDir: root });
+  atomicJson(resolved.file, result.plan);
+  return { operation: "generate-plan", ...result, planPath: resolved.file, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+export async function validateProductPlan({
+  projectDir,
+  outDir = ".autotap",
+  planPath = "",
+  items = [],
+  platform = "",
+  url = "",
+  target = "",
+  bundleId = "",
+  appId = "",
+  apkPath = "",
+  serial = "",
+  timeout = 600,
+  testEmail,
+  testPassword,
+  startWebTarget,
+  stopWebTarget,
+  onProgress = () => {},
+} = {}) {
+  const root = realProject(projectDir);
+  const resolved = resolvePlan(root, outDir, planPath);
+  let plan = resolved.plan;
+  const requested = new Set((items || []).map(String));
+  const drafts = (plan.items || []).filter((item) => item.generation?.path && (!requested.size || requested.has(item.id) || requested.has(item.name)));
+  if (!drafts.length) throw new Error("No generated contract drafts matched validation");
+  const inferred = [...new Set(drafts.flatMap((item) => item.platforms || []))];
+  const selectedPlatform = String(platform || (url ? "web" : appId ? "android" : inferred.length === 1 ? inferred[0] : "")).toLowerCase();
+  if (!["ios", "android", "web"].includes(selectedPlatform)) throw new Error("A concrete ios|android|web platform is required");
+  const platformDrafts = drafts.filter((item) => (item.platforms || []).includes(selectedPlatform));
+  if (!platformDrafts.length) throw new Error(`No selected generated drafts apply to ${selectedPlatform}`);
+  if (selectedPlatform === "android" && !appId) throw new Error("Android draft validation requires an application id");
+  if (selectedPlatform === "ios" && !bundleId) throw new Error("iOS draft validation requires a bundle id");
+  let managed = null;
+  const results = [];
+  try {
+    if (selectedPlatform === "web" && !url) {
+      if (typeof startWebTarget !== "function") throw new Error("No managed web-target capability was provided");
+      managed = await startWebTarget({ root, requestedTarget: target, timeout, onStatus: (text) => onProgress({ phase: "runtime", text }) });
+      if (managed?.error) throw new Error(managed.error);
+      url = managed.url;
+    }
+    for (let index = 0; index < platformDrafts.length; index += 1) {
+      const item = platformDrafts[index];
+      onProgress({ phase: "validate", current: index + 1, total: platformDrafts.length, item: item.name, text: `Replaying ${item.title || item.name}` });
+      const contractPath = path.resolve(root, item.generation.path);
+      let execution;
+      if (!inside(root, contractPath) || !fs.existsSync(contractPath)) {
+        execution = { passed: false, stderr: "generated draft file missing", evidence: "" };
+      } else {
+        execution = await executeReleaseContract({ projectDir: root, contractPath, platform: selectedPlatform, url, bundleId, appId, apkPath, serial, timeout, testEmail, testPassword, onOutput: ({ text }) => onProgress({ phase: "execute", item: item.name, text: text.trim().slice(-500) }) });
+      }
+      let passed = execution.passed;
+      let detail = passed ? "deterministic replay passed" : String(execution.stderr || execution.stdout || "replay failed").trim().slice(-1000);
+      let taskUpdates = [];
+      if (passed) {
+        try { taskUpdates = recordGeneratedTaskProposalValidation({ projectDir: root, item, platform: selectedPlatform, evidence: execution.evidence, detail }); }
+        catch (error) { passed = false; detail = `Replay passed but Task validation evidence could not be persisted: ${error.message || String(error)}`; }
+      }
+      plan = recordContractProposalValidation(plan, { id: item.id, platform: selectedPlatform, passed, evidence: execution.evidence, detail });
+      if (taskUpdates.length) plan = mergeGeneratedTaskProposalValidation(plan, taskUpdates);
+      results.push({ item: item.name, passed, detail, execution });
+    }
+  } finally {
+    if (managed && typeof stopWebTarget === "function") await stopWebTarget(managed);
+  }
+  atomicJson(resolved.file, plan);
+  return { operation: "validate-plan", platform: selectedPlatform, passed: results.every((item) => item.passed), results, plan, planPath: resolved.file, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+export async function promoteProductPlan({ projectDir, outDir = ".autotap", planPath = "", items = [] } = {}) {
+  const root = realProject(projectDir);
+  const resolved = resolvePlan(root, outDir, planPath);
+  const result = await promoteValidatedProposals(resolved.plan, { projectDir: root, ids: items || [] });
+  atomicJson(resolved.file, result.plan);
+  // Promotion changes the authoritative Task/contract inventory and UI Map coverage. Refresh the
+  // derived application model immediately so no adapter can show a stale pre-promotion warning.
+  const refreshed = await buildInitArtifacts({ projectDir: root, outDir });
+  const written = writeInitArtifacts({ ...refreshed, root: refreshed.root, outDir, refresh: true });
+  return { operation: "promote-plan", ...result, plan: written.plan, planPath: written.planPath, modelPath: written.modelPath, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+export function prepareProductCi({ projectDir, outDir = ".autotap", modelPath = "", actionRef = DEFAULT_ACTION_REF, defaultBranch = "main" } = {}) {
+  const root = realProject(projectDir);
+  const modelFile = modelPath ? path.resolve(root, modelPath) : artifactPaths(root, outDir).model;
+  if (!inside(root, modelFile)) throw new Error("Application model must remain inside the repository");
+  const model = readJson(modelFile);
+  if (!model) throw new Error("Application model not found; initialize and explore the project first");
+  const rendered = renderGithubWorkflow({ projectDir: root, model, actionRef, defaultBranch });
+  return { operation: "prepare-ci", ...rendered, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+export function installProductCi({ projectDir, outDir = ".autotap", modelPath = "", actionRef = DEFAULT_ACTION_REF, defaultBranch = "main", workflowPath = ".github/workflows/tapp.yml", manifestPath = ".autotap/ci.json", replace = false, allowUnresolved = false } = {}) {
+  const root = realProject(projectDir);
+  const rendered = prepareProductCi({ projectDir: root, outDir, modelPath, actionRef, defaultBranch });
+  if (rendered.manifest.unresolved.length && !allowUnresolved) throw new Error(`CI installation is unresolved: ${rendered.manifest.unresolved.map((item) => `${item.platform}:${item.message}`).join("; ")}`);
+  const written = writeCiInstallation({ projectDir: root, workflow: rendered.workflow, manifest: rendered.manifest, workflowPath, manifestPath, replace });
+  return { operation: "install-ci", ...written, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+export async function runProductGate({
+  projectDir,
+  outDir = ".autotap",
+  platform = "web",
+  target = "",
+  url = "",
+  appPath = "",
+  bundleId = "",
+  appId = "",
+  apkPath = "",
+  serial = "",
+  device = "",
+  flows = "",
+  scenarios = "",
+  contracts = "",
+  actions = 40,
+  timeout = 600,
+  baseline = "",
+  failOn = "gate",
+  testEmail,
+  testPassword,
+  onProgress = () => {},
+} = {}) {
+  const root = realProject(projectDir);
+  const project = readProductProject({ projectDir: root, outDir });
+  if (!project.model) throw new Error("Application model not found; initialize and explore the project first");
+  const selected = selectApplicationTarget(project.model, { platform, target });
+  const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "");
+  const runDir = path.join(productRunRoot(root), `${stamp}-${crypto.randomBytes(3).toString("hex")}`);
+  fs.mkdirSync(runDir, { recursive: true });
+  const reportPath = path.join(runDir, "gate-report.json");
+  const markdownPath = path.join(runDir, "gate-report.md");
+  const args = [path.join(packageRoot, "scripts", "ci-gate.sh"), "--platform", selected.platform, "--project-dir", root, "--target-key", selected.id, "--actions", String(actions), "--timeout", String(timeout), "--fail-on", failOn, "--json-out", reportPath, "--md-out", markdownPath];
+  if (selected.platform === "web") {
+    if (url) args.push("--url", url);
+    else args.push("--web-target", selected.id);
+  } else if (selected.platform === "android") {
+    const selectedAppId = appId || selected.runtime?.applicationId || "";
+    if (!selectedAppId) throw new Error(`Android gate for ${selected.name} requires an application id`);
+    args.push("--app-id", selectedAppId);
+    if (apkPath) {
+      const absoluteApk = path.resolve(apkPath);
+      if (!fs.existsSync(absoluteApk)) throw new Error(`Android APK not found: ${absoluteApk}`);
+      args.push("--apk", absoluteApk);
+    }
+    if (serial) args.push("--serial", serial);
+  } else {
+    if (!appPath) throw new Error(`iOS gate for ${selected.name} requires a built simulator .app`);
+    const absoluteApp = path.resolve(appPath);
+    if (!fs.existsSync(absoluteApp)) throw new Error(`iOS simulator app not found: ${absoluteApp}`);
+    args.push("--app", absoluteApp);
+    if (bundleId) args.push("--bundle-id", bundleId);
+  }
+  if (device) args.push("--device", device);
+  for (const [flag, value] of [["flows", flows], ["scenarios", scenarios], ["contracts", contracts]]) if (value) args.push(`--${flag}`, value);
+  if (baseline) {
+    const baselinePath = path.resolve(root, baseline);
+    if (!inside(root, baselinePath) || !fs.existsSync(baselinePath)) throw new Error("Baseline must be an existing file inside the repository");
+    args.push("--baseline", baselinePath);
+  } else {
+    const targetBaseline = baselinePathForTarget(root, selected);
+    if (fs.existsSync(targetBaseline)) args.push("--baseline", targetBaseline);
+  }
+  onProgress({ phase: "gate", text: `Running ${selected.platform}:${selected.name} release gate` });
+  const env = {
+    ...process.env,
+    ...(typeof testEmail === "string" ? { OCQA_TEST_EMAIL: testEmail } : {}),
+    ...(typeof testPassword === "string" ? { OCQA_TEST_PASSWORD: testPassword } : {}),
+  };
+  const execution = await runProductProcess("bash", args, { cwd: root, env, timeoutMs: Math.max(30, Math.min(3600, Number(timeout) || 600)) * 1000 + 60_000, onOutput: ({ text }) => onProgress({ phase: "gate", text: text.trim().slice(-1000) }) });
+  const report = readJson(reportPath);
+  return { operation: "run-gate", passed: execution.code === 0, code: execution.code, stdout: execution.stdout, stderr: execution.stderr, selectedTarget: selected, report, reportPath, markdownPath, runDir, project: readProductProject({ projectDir: root, outDir }) };
+}
+
+export function createProductBaseline({ projectDir, outDir = ".autotap", reportPath, platform = "web", target = "", replace = false, baselinePath = "" } = {}) {
+  const root = realProject(projectDir);
+  const project = readProductProject({ projectDir: root, outDir });
+  const selected = selectApplicationTarget(project.model, { platform, target });
+  const source = path.resolve(reportPath || "");
+  const report = readJson(source, { required: true });
+  const written = writeTargetBaseline({ projectDir: root, target: selected, report, sourceReport: source, outPath: baselinePath ? path.resolve(root, baselinePath) : "", replace });
+  return { operation: "create-baseline", selectedTarget: selected, ...written, project: readProductProject({ projectDir: root, outDir }) };
+}

package/mcp-server/src/project-config.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const PROJECT_CONFIG_RELATIVE_PATH = ".autotap/project.json";
+
+const ACTOR_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
+const CREDENTIAL_NAME = /^[a-z][A-Za-z0-9_-]{0,63}$/;
+const SESSIONS = new Set(["default", "isolated"]);
+const PROVISIONING_MODES = new Set(["existing", "seeded", "api", "unknown"]);
+
+function cleanActor(actor) {
+  return {
+    ...(actor.role ? { role: actor.role } : {}),
+    session: actor.session || "default",
+    provisioning: actor.provisioning || "existing",
+    credentials: Object.fromEntries(Object.entries(actor.credentials || {}).sort(([a], [b]) => a.localeCompare(b)).map(([name, binding]) => [name, { env: binding.env }])),
+  };
+}
+
+export function validateProjectConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== "object" || Array.isArray(config)) return ["Project configuration must be an object"];
+  for (const key of Object.keys(config)) if (!["kind", "schemaVersion", "actors", "lifecycle", "provenance"].includes(key)) errors.push(`unsupported project configuration field '${key}'`);
+  if (config.kind !== "tapp-project-config") errors.push("kind must be 'tapp-project-config'");
+  if (config.schemaVersion !== 1) errors.push("schemaVersion must be 1");
+  if (config.actors !== undefined && (!config.actors || typeof config.actors !== "object" || Array.isArray(config.actors))) errors.push("actors must be an object");
+  for (const [name, actor] of Object.entries(config.actors || {})) {
+    if (!ACTOR_NAME.test(name)) errors.push(`actor '${name}' must match ${ACTOR_NAME}`);
+    if (!actor || typeof actor !== "object" || Array.isArray(actor)) { errors.push(`actor '${name}' must be an object`); continue; }
+    for (const key of Object.keys(actor)) if (!["role", "session", "provisioning", "credentials"].includes(key)) errors.push(`actor '${name}' has unsupported field '${key}'; credential values are forbidden`);
+    if (actor.role !== undefined && (typeof actor.role !== "string" || !actor.role.trim())) errors.push(`actor '${name}'.role must be a non-empty string`);
+    if (!SESSIONS.has(actor.session || "default")) errors.push(`actor '${name}'.session must be default|isolated`);
+    if (!PROVISIONING_MODES.has(actor.provisioning || "existing")) errors.push(`actor '${name}'.provisioning must be existing|seeded|api|unknown`);
+    if (actor.credentials !== undefined && (!actor.credentials || typeof actor.credentials !== "object" || Array.isArray(actor.credentials))) {
+      errors.push(`actor '${name}'.credentials must be an object of environment bindings`);
+      continue;
+    }
+    for (const [credential, binding] of Object.entries(actor.credentials || {})) {
+      if (!CREDENTIAL_NAME.test(credential)) errors.push(`actor '${name}' credential '${credential}' has an invalid name`);
+      if (!binding || typeof binding !== "object" || Array.isArray(binding) || !ENV_NAME.test(String(binding.env || ""))) errors.push(`actor '${name}' credential '${credential}' must define env with an uppercase environment-variable name`);
+      for (const key of Object.keys(binding || {})) if (key !== "env") errors.push(`actor '${name}' credential '${credential}' may contain only env; credential values are forbidden`);
+    }
+  }
+  if (config.lifecycle !== undefined && (!config.lifecycle || typeof config.lifecycle !== "object" || Array.isArray(config.lifecycle))) errors.push("lifecycle must be an object");
+  for (const key of Object.keys(config.lifecycle || {})) if (!["setup", "teardown"].includes(key)) errors.push(`lifecycle has unsupported phase '${key}'`);
+  if (config.provenance !== undefined && (!config.provenance || typeof config.provenance !== "object" || Array.isArray(config.provenance))) errors.push("provenance must be an object");
+  for (const key of Object.keys(config.provenance || {})) if (!["updatedAt", "updatedBy"].includes(key)) errors.push(`provenance has unsupported field '${key}'`);
+  for (const phase of ["setup", "teardown"]) {
+    if (config.lifecycle?.[phase] !== undefined && !Array.isArray(config.lifecycle[phase])) errors.push(`lifecycle.${phase} must be an array`);
+    for (const [index, step] of (config.lifecycle?.[phase] || []).entries()) {
+      if (!step?.request || typeof step.request !== "object") errors.push(`lifecycle.${phase}[${index}] must be a request step`);
+      else if (!/^\/(?!\/)/.test(String(step.request.path || ""))) errors.push(`lifecycle.${phase}[${index}].request.path must be same-origin and start with one /`);
+    }
+  }
+  return errors;
+}
+
+export function readProjectConfig(projectDir, { required = false } = {}) {
+  const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
+  const configPath = path.join(root, PROJECT_CONFIG_RELATIVE_PATH);
+  if (!fs.existsSync(configPath)) {
+    if (required) throw new Error(`Project configuration not found: ${configPath}`);
+    return { root, path: configPath, relativePath: PROJECT_CONFIG_RELATIVE_PATH, config: { kind: "tapp-project-config", schemaVersion: 1, actors: {} }, exists: false, errors: [] };
+  }
+  let config;
+  try { config = JSON.parse(fs.readFileSync(configPath, "utf8")); }
+  catch (error) { return { root, path: configPath, relativePath: PROJECT_CONFIG_RELATIVE_PATH, config: null, exists: true, errors: [`Invalid JSON: ${error.message}`] }; }
+  return { root, path: configPath, relativePath: PROJECT_CONFIG_RELATIVE_PATH, config, exists: true, errors: validateProjectConfig(config) };
+}
+
+export function configureActor(projectDir, { name, role = "", session = "default", provisioning = "existing", credentials = {}, replace = false } = {}) {
+  const loaded = readProjectConfig(projectDir);
+  if (loaded.errors.length) throw new Error(`Existing project configuration is invalid: ${loaded.errors.join("; ")}`);
+  if (!ACTOR_NAME.test(String(name || ""))) throw new Error("Actor name must start with a letter and contain only letters, numbers, underscore, or hyphen (max 64)");
+  if (loaded.config.actors?.[name] && !replace) throw new Error(`Actor '${name}' already exists; inspect it or pass --replace to update its non-secret bindings`);
+  const actor = cleanActor({ role: String(role || "").trim(), session, provisioning, credentials });
+  const next = {
+    ...loaded.config,
+    kind: "tapp-project-config",
+    schemaVersion: 1,
+    actors: { ...(loaded.config.actors || {}), [name]: actor },
+    provenance: { ...(loaded.config.provenance || {}), updatedAt: new Date().toISOString(), updatedBy: "explicit-human-configuration" },
+  };
+  const errors = validateProjectConfig(next);
+  if (errors.length) throw new Error(errors.join("; "));
+  fs.mkdirSync(path.dirname(loaded.path), { recursive: true });
+  const temporary = `${loaded.path}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(temporary, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(temporary, loaded.path);
+  return { path: loaded.path, relativePath: loaded.relativePath, config: next, actor: next.actors[name] };
+}
+
+export function credentialBindingsFromValue(credentials = {}) {
+  const out = {};
+  for (const [name, value] of Object.entries(credentials || {})) {
+    const match = /^\$([A-Z_][A-Z0-9_]*)$/.exec(String(value || ""));
+    if (match) out[name] = match[1];
+  }
+  return out;
+}