buildanything 1.7.1 → 2.0.0

package/bin/buildanything-runtime.ts

@@ -0,0 +1,328 @@
+#!/usr/bin/env tsx
+/*
+ * buildanything runtime — entrypoint loaded by Claude Code plugin
+ * when SDK mode is enabled.
+ */
+
+import process from "node:process";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import semver from "semver";
+
+interface PluginConfig {
+  config?: {
+    sdkStateFile?: string;
+    claudeCodeHostRange?: string;
+    sdkVersion?: string;
+    maxSupportedSchemaVersion?: number;
+  };
+}
+
+const RUNTIME_VERSION = "0.1.0";
+// Hardcoded fallback if plugin.json lacks maxSupportedSchemaVersion. Keep this
+// in sync with the `schema_version` table in protocols/state-schema.md.
+const MAX_SUPPORTED_SCHEMA_VERSION_FALLBACK = 2;
+// EX_CONFIG — configuration/state mismatch.
+const EXIT_SCHEMA_VERSION_REJECT = 78;
+const BUILD_STATE_PATH_REL = "docs/plans/.build-state.json";
+
+export interface SchemaVersionCheck {
+  accepted: boolean;
+  reason?: "too_new";
+  detected?: number;
+  max?: number;
+  message?: string;
+}
+
+// Pure: evaluate whether a parsed state file's schema_version is forward-
+// compatible with this runtime. Missing / non-numeric / ≤ max → accepted.
+// Only `> max` triggers a reject. Upgrade/migration for LOWER versions is
+// explicitly out of scope here (task 4.5.2 scope note).
+export function checkSchemaVersion(
+  state: unknown,
+  maxSupported: number,
+  stateFilePath: string,
+): SchemaVersionCheck {
+  if (!state || typeof state !== "object") return { accepted: true };
+  const raw = (state as Record<string, unknown>).schema_version;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return { accepted: true };
+  if (raw <= maxSupported) return { accepted: true };
+  return {
+    accepted: false,
+    reason: "too_new",
+    detected: raw,
+    max: maxSupported,
+    message:
+      `buildanything: state file schema_version=${raw} exceeds supported maximum ${maxSupported} ` +
+      `(${stateFilePath}). Upgrade plugin to >=v${raw} or delete the state file. ` +
+      `See docs/migration/sdk-host-compat.md.`,
+  };
+}
+
+async function loadPluginConfig(): Promise<PluginConfig> {
+  const scriptPath = process.argv[1] ?? "";
+  const here = scriptPath ? dirname(scriptPath) : process.cwd();
+  const pluginJsonPath = resolve(here, "..", ".claude-plugin", "plugin.json");
+  const raw = await readFile(pluginJsonPath, "utf8");
+  return JSON.parse(raw) as PluginConfig;
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const resumeRequested = argv.includes("--resume");
+
+  let pinned = "unknown";
+  let hostRange = "unknown";
+  let sdkStateFile = ".buildanything/sdk-state";
+  let maxSupportedSchemaVersion = MAX_SUPPORTED_SCHEMA_VERSION_FALLBACK;
+  try {
+    const plugin = await loadPluginConfig();
+    if (plugin.config?.sdkVersion) pinned = plugin.config.sdkVersion;
+    if (plugin.config?.claudeCodeHostRange) hostRange = plugin.config.claudeCodeHostRange;
+    if (plugin.config?.sdkStateFile) sdkStateFile = plugin.config.sdkStateFile;
+    if (
+      typeof plugin.config?.maxSupportedSchemaVersion === "number" &&
+      Number.isFinite(plugin.config.maxSupportedSchemaVersion)
+    ) {
+      maxSupportedSchemaVersion = plugin.config.maxSupportedSchemaVersion;
+    }
+    if (!plugin.config) {
+      console.warn("[buildanything-runtime] warning: plugin.json has no 'config' block; using unknown defaults");
+    }
+  } catch (err) {
+    console.warn(`[buildanything-runtime] warning: could not load plugin.json config (${(err as Error).message}); using unknown defaults`);
+  }
+
+  // [Task 4.5.2] Forward-reject state files with schema_version > max.
+  // Runs before any SDK/MCP wiring so an incompatible state file halts the
+  // whole session instead of silently stripping fields on next write.
+  const buildStatePath = resolve(process.cwd(), BUILD_STATE_PATH_REL);
+  try {
+    const raw = await readFile(buildStatePath, "utf8");
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      // Malformed JSON is NOT our concern here — other handlers surface it.
+      // Log for visibility and continue.
+      console.warn(
+        `[buildanything-runtime] warning: could not parse ${buildStatePath} for schema check (${(err as Error).message}); continuing`,
+      );
+      parsed = null;
+    }
+    const check = checkSchemaVersion(parsed, maxSupportedSchemaVersion, buildStatePath);
+    if (!check.accepted) {
+      process.stderr.write(`${check.message}\n`);
+      process.exit(EXIT_SCHEMA_VERSION_REJECT);
+    }
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      console.warn(
+        `[buildanything-runtime] warning: could not read ${buildStatePath} for schema check (${(err as Error).message}); continuing`,
+      );
+    }
+    // ENOENT → no state file yet (fresh project); nothing to reject.
+  }
+
+  console.log(`buildanything-runtime v${RUNTIME_VERSION} starting (sdk=${pinned}, hostRange=${hostRange})`);
+
+  if (resumeRequested) {
+    console.log("[buildanything-runtime] resume requested");
+    // [Task 4.3.4] --resume staleness decrement — clears a crashed
+    // backward edge (>60s old) by decrementing counters, so the retry
+    // isn't double-counted toward the escalate-to-user cap.
+    try {
+      const cycleCounter = await import("../src/orchestrator/mcp/cycle-counter.js");
+      const stateSaveModule = await import("../src/orchestrator/mcp/state-save.js");
+      let parsed: Record<string, unknown> | null = null;
+      try {
+        const raw = await readFile(buildStatePath, "utf8");
+        parsed = JSON.parse(raw) as Record<string, unknown>;
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === "ENOENT") {
+          process.stderr.write("buildanything: no active backward edge; --resume is a no-op.\n");
+        } else {
+          console.warn(
+            `[buildanything-runtime] warning: could not read ${buildStatePath} for --resume stale-edge check (${(err as Error).message}); continuing`,
+          );
+        }
+      }
+      if (parsed) {
+        if (!parsed.in_flight_backward_edge) {
+          process.stderr.write("buildanything: no active backward edge; --resume is a no-op.\n");
+        } else {
+          const cleared = cycleCounter.handleStaleEdge(parsed as unknown as import("../src/orchestrator/mcp/cycle-counter.js").CounterState);
+          if (cleared) {
+            stateSaveModule.stateSave(buildStatePath, parsed);
+            process.stderr.write(
+              "buildanything: cleared stale in_flight_backward_edge (>60s old); counters decremented. Resuming from last known good phase.\n",
+            );
+          } else {
+            process.stderr.write(
+              "buildanything: --resume requested but no stale edge detected; proceeding normally.\n",
+            );
+          }
+        }
+      }
+    } catch (err) {
+      console.warn(
+        `[buildanything-runtime] warning: --resume stale-edge check failed (${(err as Error).message}); continuing`,
+      );
+    }
+  }
+
+  const hostVersion = process.env.CLAUDE_CODE_VERSION;
+  let hostCompat = true;
+  if (!hostVersion) {
+    console.log("[buildanything-runtime] host version unavailable (CLAUDE_CODE_VERSION not set); skipping compat check");
+  } else if (semver.satisfies(hostVersion, hostRange)) {
+    console.log(`[buildanything-runtime] host version ${hostVersion} satisfies compat range ${hostRange}`);
+  } else {
+    hostCompat = false;
+  }
+
+  if (!hostCompat) {
+    console.warn(`[buildanything-runtime] host version ${hostVersion} outside compat range ${hostRange} — falling back to markdown mode.`);
+  }
+
+  const stateFilePath = resolve(process.cwd(), sdkStateFile);
+  let stateFileActive = false;
+  try {
+    const contents = (await readFile(stateFilePath, "utf8")).trim();
+    stateFileActive = contents === "on";
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      console.log(`[buildanything-runtime] debug: sdk state file missing at ${stateFilePath}; treating as off`);
+    } else {
+      console.warn(`[buildanything-runtime] warning: could not read sdk state file (${(err as Error).message}); treating as off`);
+    }
+  }
+  const sdkActive = stateFileActive && hostCompat;
+  console.log(`[buildanything-runtime] sdkActive=${sdkActive} (stateFile=${stateFileActive}, hostCompat=${hostCompat})`);
+
+  // [Task 1.2.4] scribe MCP registration
+  // [Task 2.3.4] write-lease MCP registration
+  // [Task 3.2.4] state-save MCP registration
+  // [Task 4.2.4] cycle-counter MCP registration
+  const mcpServers: Record<string, unknown> = {};
+  if (!sdkActive) {
+    console.log("[buildanything-runtime] sdk inactive — scribe + write-lease + state-save + cycle-counter MCP registration skipped (markdown mode)");
+  } else {
+    try {
+      const sdk = await import("@anthropic-ai/claude-agent-sdk");
+      const { buildScribeTool } = await import("./adapters/scribe-tool.js");
+      const scribeTool = buildScribeTool(sdk.tool, process.cwd());
+      mcpServers.scribe = sdk.createSdkMcpServer({
+        name: "scribe",
+        tools: [scribeTool],
+      });
+      console.log("[buildanything-runtime] scribe MCP server registered (tool: scribe_decision)");
+    } catch (err) {
+      console.warn(
+        `[buildanything-runtime] warning: scribe MCP registration failed (${(err as Error).message}); continuing in markdown mode`,
+      );
+    }
+
+    // Hydrate in-memory lease store from disk so it matches persisted state
+    // across runtime restarts. init() no-ops on missing file and swallows
+    // parse errors internally; we still guard so a surprise throw doesn't
+    // block MCP registration.
+    try {
+      const writeLeaseModule = await import("../src/orchestrator/mcp/write-lease.js");
+      writeLeaseModule.init(buildStatePath);
+    } catch (err) {
+      console.warn(
+        `[buildanything-runtime] warning: write-lease init failed (${(err as Error).message}); continuing with empty in-memory leases`,
+      );
+    }
+
+    try {
+      const sdk = await import("@anthropic-ai/claude-agent-sdk");
+      const {
+        buildAcquireWriteLeaseTool,
+        buildReleaseWriteLeaseTool,
+        buildListWriteLeasesTool,
+      } = await import("./adapters/write-lease-tool.js");
+      const acquireTool = buildAcquireWriteLeaseTool(sdk.tool);
+      const releaseTool = buildReleaseWriteLeaseTool(sdk.tool);
+      const listTool = buildListWriteLeasesTool(sdk.tool);
+      mcpServers.write_lease = sdk.createSdkMcpServer({
+        name: "write_lease",
+        tools: [acquireTool, releaseTool, listTool],
+      });
+      console.log(
+        "[buildanything-runtime] write-lease MCP server registered (tools: acquire_write_lease, release_write_lease, list_write_leases)",
+      );
+    } catch (err) {
+      console.warn(
+        `[buildanything-runtime] warning: write-lease MCP registration failed (${(err as Error).message}); continuing without lease enforcement`,
+      );
+    }
+
+    try {
+      const sdk = await import("@anthropic-ai/claude-agent-sdk");
+      const {
+        buildStateSaveTool,
+        buildStateReadTool,
+        buildVerifyIntegrityTool,
+      } = await import("./adapters/state-save-tool.js");
+      const saveTool = buildStateSaveTool(sdk.tool);
+      const readTool = buildStateReadTool(sdk.tool);
+      const verifyTool = buildVerifyIntegrityTool(sdk.tool);
+      mcpServers.state_save = sdk.createSdkMcpServer({
+        name: "state_save",
+        tools: [saveTool, readTool, verifyTool],
+      });
+      console.log(
+        "[buildanything-runtime] state-save MCP server registered (tools: state_save, state_read, verify_integrity)",
+      );
+    } catch (err) {
+      console.warn(
+        `[buildanything-runtime] warning: state-save MCP registration failed (${(err as Error).message}); continuing in markdown mode`,
+      );
+    }
+
+    try {
+      const sdk = await import("@anthropic-ai/claude-agent-sdk");
+      const {
+        buildCycleCounterCheckTool,
+        buildClearInFlightEdgeTool,
+        buildHandleStaleEdgeTool,
+      } = await import("./adapters/cycle-counter-tool.js");
+      const checkTool = buildCycleCounterCheckTool(sdk.tool);
+      const clearTool = buildClearInFlightEdgeTool(sdk.tool);
+      const staleTool = buildHandleStaleEdgeTool(sdk.tool);
+      mcpServers.cycle_counter = sdk.createSdkMcpServer({
+        name: "cycle_counter",
+        tools: [checkTool, clearTool, staleTool],
+      });
+      console.log(
+        "[buildanything-runtime] cycle-counter MCP server registered (tools: cycle_counter_check, clear_in_flight_edge, handle_stale_edge)",
+      );
+    } catch (err) {
+      console.warn(
+        `[buildanything-runtime] warning: cycle-counter MCP registration failed (${(err as Error).message}); continuing without cycle enforcement`,
+      );
+    }
+  }
+
+  void mcpServers;
+}
+
+function isCliEntry(): boolean {
+  // Run main() only when invoked as the CLI, not when imported by tests.
+  const entry = process.argv[1] ?? "";
+  return entry.endsWith("buildanything-runtime.ts") || entry.endsWith("buildanything-runtime.js");
+}
+
+if (isCliEntry()) {
+  main()
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error("[buildanything-runtime] fatal:", err instanceof Error ? err.stack ?? err.message : err);
+      process.exit(1);
+    });
+}

package/bin/setup.js

@@ -15,6 +15,21 @@ const OFFICIAL_PLUGINS = [
   { name: "playwright", desc: "browser automation for design research and visual QA" },
 ];
 
+const IOS_MCPS = [
+  {
+    name: "xcodebuildmcp",
+    args: ["npx", "-y", "xcodebuildmcp@latest"],
+    desc: "Xcode build, simulator, and project management",
+  },
+  {
+    name: "apple-docs",
+    args: ["npx", "-y", "apple-docs-mcp@latest"],
+    desc: "Live Apple developer documentation lookup",
+  },
+];
+
+const isIos = process.argv.includes("--ios");
+
 function run(command, args) {
   try {
     return execFileSync(command, args, {
@@ -28,6 +43,7 @@ function run(command, args) {
 
 function main() {
   console.log("\n  buildanything — one command to build an entire product\n");
+  if (isIos) console.log("  iOS mode: will also install XcodeBuildMCP, apple-docs-mcp, and Maestro.\n");
 
   // Check claude is installed
   const version = run("claude", ["--version"]);
@@ -85,10 +101,26 @@ function main() {
     }
   }
 
+  // Install tsx — required by all plugin hooks (pre-tool-use, subagent-start/stop,
+  // compile-writer-owner-cache, record-mode-transitions). Hooks use
+  // `npx --no-install tsx` which silently degrades if tsx is missing.
+  console.log("\n  Installing tsx (TypeScript runner for plugin hooks)...");
+  const tsxCheck = run("which", ["tsx"]);
+  if (tsxCheck) {
+    console.log("    already installed");
+  } else {
+    process.stdout.write("    tsx... ");
+    const tsxResult = run("npm", ["install", "-g", "tsx"]);
+    if (tsxResult === null) {
+      console.log("failed (install manually: npm i -g tsx)");
+    } else {
+      console.log("installed");
+    }
+  }
+
   // Install agent-browser for behavioral verification
   console.log("\n  Installing agent-browser (behavioral testing)...");
 
-  // 1. Install the CLI globally
   process.stdout.write("    CLI... ");
   const abCheck = run("which", ["agent-browser"]);
   if (abCheck) {
@@ -102,7 +134,6 @@ function main() {
     }
   }
 
-  // 2. Download Chrome for Testing (first time only)
   process.stdout.write("    Chrome browser... ");
   const chromeResult = run("agent-browser", ["install"]);
   if (chromeResult === null) {
@@ -111,7 +142,6 @@ function main() {
     console.log("ready");
   }
 
-  // 3. Install the agent-browser skill for AI coding assistants
   process.stdout.write("    agent-browser skill... ");
   const skillResult = run("npx", ["skills", "add", "vercel-labs/agent-browser"]);
   if (skillResult === null) {
@@ -120,7 +150,6 @@ function main() {
     console.log("installed");
   }
 
-  // 4. Install dogfood skill for autonomous exploratory testing
   process.stdout.write("    dogfood skill... ");
   const dfResult = run("npx", ["skills", "add", "vercel-labs/agent-browser", "--skill", "dogfood"]);
   if (dfResult === null) {
@@ -129,11 +158,57 @@ function main() {
     console.log("installed");
   }
 
-  console.log(
-    "\n  Setup complete! Start Claude Code and use:\n" +
+  // iOS-specific deps — only when --ios flag is passed
+  if (isIos) {
+    console.log("\n  Installing iOS MCP servers...");
+    const existingMcps = run("claude", ["mcp", "list"]) ?? "";
+
+    for (const mcp of IOS_MCPS) {
+      process.stdout.write(`    ${mcp.name} (${mcp.desc})... `);
+      if (existingMcps.includes(mcp.name)) {
+        console.log("already configured");
+      } else {
+        const result = run("claude", ["mcp", "add", mcp.name, "--", ...mcp.args]);
+        if (result === null) {
+          console.log(`failed (add manually: claude mcp add ${mcp.name} -- ${mcp.args.join(" ")})`);
+        } else {
+          console.log("configured");
+        }
+      }
+    }
+
+    console.log("\n  Installing Maestro (iOS E2E test runner)...");
+    process.stdout.write("    maestro... ");
+    const maestroCheck = run("which", ["maestro"]);
+    if (maestroCheck) {
+      console.log("already installed");
+    } else {
+      const brewCheck = run("which", ["brew"]);
+      if (!brewCheck) {
+        console.log("skipped — Homebrew not found (install Homebrew first, then: brew install maestro)");
+      } else {
+        const maestroResult = run("brew", ["install", "maestro"]);
+        if (maestroResult === null) {
+          console.log("failed (install manually: brew install maestro)");
+        } else {
+          console.log("installed");
+        }
+      }
+    }
+  }
+
+  const completionMsg = isIos
+    ? "\n  Setup complete! Restart Claude Code so MCP servers load, then use:\n" +
+      "    /buildanything:build <your iOS app idea>  — full iOS pipeline\n"
+    : "\n  Setup complete! Start Claude Code and use:\n" +
       "    /buildanything:build <your idea>       — full product pipeline\n" +
-      "    /buildanything:idea-sweep <your idea>  — parallel research sweep\n"
-  );
+      "    /buildanything:idea-sweep <your idea>  — parallel research sweep\n";
+
+  console.log(completionMsg);
+
+  if (!isIos) {
+    console.log("  Building an iOS app? Re-run with: npx buildanything --ios\n");
+  }
 
   if (installed.length > 0) {
     console.log(`  Companion plugins installed: ${installed.join(", ")}`);

package/commands/add-feature.md

@@ -96,3 +96,5 @@ Evidence: [paths to screenshots/logs]
 ```
 
 If the feature expands the product scope, update `CLAUDE.md` to reflect the new capability.
+
+**After any CLAUDE.md update:** Run `wc -l < CLAUDE.md`. If the count exceeds 200 lines, trim it back to ≤200 lines — cut the least-critical content, not the new addition. CLAUDE.md is auto-loaded into every subagent; bloat here multiplies across all dispatches.