buildanything 1.8.0 → 2.1.1

package/docs/migration/sdk-host-compat.md

@@ -0,0 +1,18 @@
+# SDK / Host Compatibility Matrix
+
+Tracks validated Claude Code host version ranges for each SDK pin version.
+Used to gate SDK features and ensure runtime compatibility across migration stages.
+
+## Compatibility Table
+
+| SDK Version | Host Range (semver) | Validated Date | Notes |
+|-------------|---------------------|----------------|-------|
+| `0.1.0` | `>=1.5.0 <3.0.0` | 2026-04-18 | Initial pin — Stage 1 bootstrap |
+
+## Update Policy
+
+Updated per Stage release. Each row represents a tested SDK pin version with its validated Claude Code host range. The `claudeCodeHostRange` field in `.claude-plugin/plugin.json` must match the latest row.
+
+## Degradation Behavior
+
+If the host does not expose `CLAUDE_CODE_VERSION`, the version probe no-ops (logged, not errored). Fallback: markdown mode with user-visible warning.

package/hooks/compile-writer-owner-cache.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env tsx
+/*
+ * buildanything: compile writer-owner cache (tasks 2.1.2, 2.1.3).
+ *
+ * Called from hooks/session-start once per session. Reads the plugin's
+ * docs/migration/phase-graph.yaml, flattens the artifacts table into a
+ * JSON cache the PreToolUse handler can read without parsing YAML on every
+ * tool call.
+ *
+ * Task 2.1.3 additive: also encodes `phase_internal_scratch.path_glob` as
+ * `scratch_globs` so the handler can exempt scratch paths from default-deny
+ * without re-parsing YAML. Still version 1 — new field is additive.
+ *
+ * Usage: tsx hooks/compile-writer-owner-cache.ts <source-yaml> <output-json>
+ *
+ * Exits 0 on success. Exits 1 (with stderr) on any failure so session-start
+ * can log a warning and continue — the handler falls back to live YAML parse.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import { parse as parseYaml } from "yaml";
+
+interface RawArtifact {
+  path: string;
+  writer?: string;
+  writers?: string[];
+}
+
+interface RawScratch {
+  path_glob?: string;
+}
+
+interface PhaseGraph {
+  artifacts?: RawArtifact[];
+  phase_internal_scratch?: RawScratch;
+}
+
+interface CompiledArtifact {
+  path: string;
+  writers: string[];
+  is_glob: boolean;
+  regex?: string;
+}
+
+interface CompiledScratchGlob {
+  glob: string;
+  regex: string;
+}
+
+interface Cache {
+  version: 1;
+  source_sha: string;
+  source_mtime: number;
+  compiled_at: string;
+  artifacts: CompiledArtifact[];
+  // Additive v1 field (task 2.1.3): globs from `phase_internal_scratch` that
+  // must be exempt from default-deny. Writers: any phase.
+  scratch_globs: CompiledScratchGlob[];
+}
+
+const CACHE_VERSION = 1;
+
+function globToRegex(pattern: string): string {
+  let out = "";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        out += ".*";
+        i += 1;
+      } else {
+        out += "[^/]*";
+      }
+    } else if (ch === "{") {
+      // Brace expansion: {md,json} -> (md|json). Flat alternation only (no nesting).
+      const close = pattern.indexOf("}", i);
+      if (close === -1) {
+        out += "\\{";
+        continue;
+      }
+      const parts = pattern.slice(i + 1, close).split(",").map((p) =>
+        p.replace(/[.+?^${}()|[\]\\]/g, (m) => `\\${m}`),
+      );
+      out += `(?:${parts.join("|")})`;
+      i = close;
+    } else if (/[.+?^${}()|[\]\\]/.test(ch)) {
+      out += `\\${ch}`;
+    } else {
+      out += ch;
+    }
+  }
+  return `^${out}$`;
+}
+
+function compile(sourcePath: string): Cache {
+  const text = readFileSync(sourcePath, "utf8");
+  const stat = statSync(sourcePath);
+  const sha = createHash("sha256").update(text).digest("hex");
+  const doc = parseYaml(text) as PhaseGraph;
+  const rawArtifacts = Array.isArray(doc?.artifacts) ? doc.artifacts : [];
+
+  const compiled: CompiledArtifact[] = rawArtifacts.map((a) => {
+    const writers: string[] = [];
+    if (a.writer) writers.push(String(a.writer).trim());
+    if (Array.isArray(a.writers)) {
+      for (const w of a.writers) writers.push(String(w).trim());
+    }
+    const hasGlobChar = a.path.includes("*");
+    const hasBracketPlaceholder = /\[[^\]]+\]/.test(a.path);
+    const is_glob = hasGlobChar || hasBracketPlaceholder;
+    const entry: CompiledArtifact = {
+      path: a.path,
+      writers: writers.filter(Boolean),
+      is_glob,
+    };
+    if (is_glob) {
+      const normalized = a.path.replace(/\[[^\]]+\]/g, "*");
+      entry.regex = globToRegex(normalized);
+    }
+    return entry;
+  });
+
+  const scratchGlobs: CompiledScratchGlob[] = [];
+  const scratchGlob = doc?.phase_internal_scratch?.path_glob;
+  if (typeof scratchGlob === "string" && scratchGlob.trim()) {
+    scratchGlobs.push({ glob: scratchGlob, regex: globToRegex(scratchGlob) });
+  }
+
+  return {
+    version: CACHE_VERSION,
+    source_sha: sha,
+    source_mtime: Math.floor(stat.mtimeMs),
+    compiled_at: new Date().toISOString(),
+    artifacts: compiled,
+    scratch_globs: scratchGlobs,
+  };
+}
+
+function main(): number {
+  const [sourceArg, outputArg] = process.argv.slice(2);
+  if (!sourceArg || !outputArg) {
+    process.stderr.write(
+      "compile-writer-owner-cache: usage: <source-yaml> <output-json>\n",
+    );
+    return 1;
+  }
+  const source = resolve(sourceArg);
+  const output = resolve(outputArg);
+  let cache: Cache;
+  try {
+    cache = compile(source);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`compile-writer-owner-cache: ${msg}\n`);
+    return 1;
+  }
+  try {
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`compile-writer-owner-cache: write failed: ${msg}\n`);
+    return 1;
+  }
+  return 0;
+}
+
+process.exit(main());

package/hooks/design-md-lint

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -e
+cd "$(dirname "$0")/.."
+npx tsx hooks/design-md-lint.ts "$@"

package/hooks/design-md-lint.ts

@@ -0,0 +1,295 @@
+#!/usr/bin/env tsx
+/*
+ * buildanything: DESIGN.md lint runner (Phase 3 Step 3.8 gate).
+ *
+ * Runs the pinned @google/design.md linter (devDependency in package.json) via
+ * `npx --no-install` against the DESIGN.md at the current working directory.
+ * Auto-installs the pinned version on first use if the package is listed in
+ * package.json devDependencies but not yet in node_modules — runs plain
+ * `npm install` (no args) so package.json is not mutated. Classifies findings
+ * (broken-ref => error, everything else => warning per
+ * protocols/design-md-authoring.md §8),
+ * writes a JSON summary to .buildanything/graph/lint-status.json (consumed by
+ * src/graph/storage/index.ts queryDna lint_status field), and appends a
+ * one-line summary to docs/plans/build-log.md under
+ * `## Phase 3 Step 3.8 — DESIGN.md Lint`.
+ *
+ * Exit codes:
+ *   0 — pass (broken-refs == 0; warnings allowed)
+ *   2 — fail (broken-refs > 0; orchestrator routes back to Step 3.4)
+ *   3 — DESIGN.md missing
+ *
+ * Invocation:
+ *   npx tsx hooks/design-md-lint.ts          # run inside project root
+ *   hooks/design-md-lint                     # via bash wrapper
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync, renameSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import YAML from "yaml";
+
+interface LintFinding {
+  rule: string;
+  severity: "error" | "warning" | "info";
+  message: string;
+  line?: number;
+}
+
+interface LintSummary {
+  file_hash: string;
+  broken_refs: number;
+  warnings: LintFinding[];
+  errors: LintFinding[];
+  ran_at: string;
+  exit_code: number;
+  raw_stdout: string;
+  raw_stderr: string;
+}
+
+const BROKEN_REF_RULES = new Set(["broken-ref"]);
+
+function sha256(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function ensureDir(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// Atomic write — tmp + rename so a crash mid-write never leaves a partial
+// JSON that graph/storage queryDna would fail to parse.
+function atomicWrite(path: string, content: string): void {
+  ensureDir(path);
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+function parseFindings(stdout: string): LintFinding[] {
+  const findings: LintFinding[] = [];
+  for (const raw of stdout.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    const m = line.match(/^DESIGN\.md(?::(\d+))?\s+(error|warn|warning|info)\s+([\w-]+)\s+(.+)$/i);
+    if (!m) continue;
+    const sev = m[2].toLowerCase();
+    const severity: LintFinding["severity"] =
+      sev === "error" ? "error" : sev === "info" ? "info" : "warning";
+    findings.push({
+      rule: m[3],
+      severity,
+      message: m[4],
+      line: m[1] ? Number(m[1]) : undefined,
+    });
+  }
+  return findings;
+}
+
+interface PackageJson {
+  devDependencies?: Record<string, string>;
+  dependencies?: Record<string, string>;
+}
+
+/**
+ * Returns true if @google/design.md is pinned in package.json devDependencies
+ * (or dependencies) but is NOT installed under node_modules. This is the
+ * narrow window where auto-install is safe — the package is "ours" to install.
+ * Returns false in any other state (missing package.json, missing pin,
+ * already installed, parse error) so the caller falls through to existing
+ * behavior.
+ */
+function shouldAutoInstall(cwd: string): boolean {
+  const pkgPath = resolve(cwd, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  let pkg: PackageJson;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as PackageJson;
+  } catch {
+    return false;
+  }
+  const pinned =
+    pkg.devDependencies?.["@google/design.md"] ??
+    pkg.dependencies?.["@google/design.md"];
+  if (!pinned) return false;
+  // Installed if the package directory exists. We don't validate the
+  // version range here — npm install will reconcile against package-lock.
+  const installedPath = resolve(cwd, "node_modules", "@google", "design.md");
+  return !existsSync(installedPath);
+}
+
+function main(): number {
+  const cwd = process.cwd();
+  const designMd = resolve(cwd, "DESIGN.md");
+  if (!existsSync(designMd)) {
+    process.stderr.write(`design-md-lint: DESIGN.md not found at ${designMd}\n`);
+    return 3;
+  }
+
+  const fileContent = readFileSync(designMd, "utf8");
+  const fileHash = sha256(fileContent);
+
+  // First attempt: --no-install ensures we use the pinned version from
+  // package.json (devDependency). If the package isn't installed locally,
+  // we auto-install once below rather than silently fetching latest from
+  // npm — that's the whole point of pinning.
+  const runLint = () =>
+    spawnSync("npx", ["--no-install", "@google/design.md", "lint", "DESIGN.md"], {
+      cwd,
+      encoding: "utf8",
+    });
+
+  let lint = runLint();
+
+  // Auto-install fallback: only fires when the package is pinned in
+  // package.json but missing from node_modules. We run plain `npm install`
+  // (no args, no --save-dev) — that installs from the existing devDeps
+  // block and does NOT mutate package.json or package-lock.json beyond
+  // what npm already does for normal install resolution.
+  const linterNotInstalled = lint.error || (lint.status !== null && lint.status !== 0 && /could not determine|could not find/i.test(lint.stderr ?? ""));
+  if (linterNotInstalled && shouldAutoInstall(cwd)) {
+    process.stdout.write("design-md-lint: pinned linter not installed; running 'npm install' once (~5-15s)...\n");
+    const install = spawnSync("npm", ["install", "--silent"], {
+      cwd,
+      encoding: "utf8",
+    });
+    if (install.status === 0) {
+      lint = runLint();
+    } else {
+      process.stderr.write(`design-md-lint: auto-install failed (exit ${install.status}). Run 'npm install' from the plugin root manually.\n`);
+      if (install.stderr) process.stderr.write(install.stderr);
+      return 2;
+    }
+  }
+
+  const stdout = lint.stdout ?? "";
+  const stderr = lint.stderr ?? "";
+
+  if (lint.error) {
+    process.stderr.write(`design-md-lint: linter spawn failed: ${lint.error.message}\n`);
+    process.stderr.write(`design-md-lint: install pinned version with: npm install --save-dev @google/design.md\n`);
+    process.stderr.write(stderr);
+    return 2;
+  }
+
+  const findings = parseFindings(stdout);
+  const errors = findings.filter((f) => f.severity === "error" && BROKEN_REF_RULES.has(f.rule));
+  const warnings = findings.filter((f) => f.severity === "warning" || (f.severity === "error" && !BROKEN_REF_RULES.has(f.rule)));
+  const infos: LintFinding[] = [];
+
+  // §9.5 iOS-specific post-process checks (gated on project_type=ios).
+  const buildStatePath = resolve(cwd, "docs/plans/.build-state.json");
+  if (existsSync(buildStatePath)) {
+    try {
+      const bs = JSON.parse(readFileSync(buildStatePath, "utf8")) as Record<string, unknown>;
+      if (bs.project_type === "ios") {
+        // Parse YAML frontmatter for token inspection.
+        const fmMatch = fileContent.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        const fmYaml = fmMatch ? fmMatch[1] : "";
+        let fm: Record<string, unknown> = {};
+        try { fm = YAML.parse(fmYaml) ?? {}; } catch { /* skip if unparseable */ }
+
+        const colors = (typeof fm.colors === "object" && fm.colors !== null) ? fm.colors as Record<string, unknown> : {};
+        const typography = (typeof fm.typography === "object" && fm.typography !== null) ? fm.typography as Record<string, unknown> : {};
+        const components = (typeof fm.components === "object" && fm.components !== null) ? fm.components as Record<string, unknown> : {};
+
+        // 1. Dark-pair rule: every color token needs a -dark counterpart.
+        const colorKeys = Object.keys(colors);
+        for (const ck of colorKeys) {
+          if (ck.endsWith("-dark")) continue;
+          if (!colorKeys.includes(`${ck}-dark`)) {
+            warnings.push({ rule: "ios-dark-pair", severity: "warning", message: `colors.${ck} has no -dark pair for dark mode` });
+          }
+        }
+
+        // 2. Dynamic Type role check: typography tokens should match iOS roles.
+        const DYNAMIC_TYPE_ROLES = new Set(["largeTitle", "title", "title2", "title3", "headline", "body", "callout", "subheadline", "footnote", "caption", "caption2"]);
+        for (const tk of Object.keys(typography)) {
+          if (!DYNAMIC_TYPE_ROLES.has(tk)) {
+            warnings.push({ rule: "ios-dynamic-type", severity: "warning", message: `typography.${tk} is not a Dynamic Type role — fixed-size Font, breaks accessibility scaling` });
+          }
+        }
+
+        // 3. iOS 26 gating: Glassy material + iOS 26 → require card-glass/button-tinted.
+        const dnaMatch = fileContent.match(/###\s*Brand DNA[\s\S]*?(?=###|\n##\s|$)/);
+        const dnaBlock = dnaMatch ? dnaMatch[0] : "";
+        const materialMatch = dnaBlock.match(/Material\s*:\s*(.+)/i);
+        const material = materialMatch ? materialMatch[1].trim() : "";
+        const iosFeatures = Array.isArray(bs.ios_features) ? bs.ios_features as string[] : [];
+        const targetsIos26 = iosFeatures.some((f) => /ios\s*26|26\s*sdk/i.test(String(f)));
+        const isGlassy = /glassy/i.test(material);
+        const compKeys = Object.keys(components);
+
+        if (isGlassy && targetsIos26) {
+          if (!compKeys.includes("card-glass")) infos.push({ rule: "ios26-glassy-gate", severity: "info", message: "Material=Glassy + iOS 26 target but components.card-glass is missing" });
+          if (!compKeys.includes("button-tinted")) infos.push({ rule: "ios26-glassy-gate", severity: "info", message: "Material=Glassy + iOS 26 target but components.button-tinted is missing" });
+        } else if (!isGlassy) {
+          if (compKeys.includes("card-glass")) infos.push({ rule: "ios26-glassy-gate", severity: "info", message: "Material is not Glassy but components.card-glass is present — remove it" });
+          if (compKeys.includes("button-tinted")) infos.push({ rule: "ios26-glassy-gate", severity: "info", message: "Material is not Glassy but components.button-tinted is present — remove it" });
+        }
+      }
+    } catch { /* build-state unreadable — skip iOS checks */ }
+  }
+  const brokenRefs = errors.length;
+  const exitCode = brokenRefs > 0 ? 2 : 0;
+
+  const ranAt = new Date().toISOString();
+  const status: "pass" | "warn" | "fail" =
+    brokenRefs > 0 ? "fail" : (warnings.length > 0 || infos.length > 0) ? "warn" : "pass";
+
+  // Storage layer (src/graph/storage/index.ts queryDna) reads
+  // .buildanything/graph/lint-status.json and only consumes the `status`
+  // field. Extra diagnostic fields (broken_refs, warnings, errors, raw_*)
+  // are preserved here for human/tool inspection and are ignored by storage.
+  const summary: LintSummary & { status: "pass" | "warn" | "fail"; at: string; source: string } = {
+    status,
+    at: ranAt,
+    source: "DESIGN.md",
+    file_hash: fileHash,
+    broken_refs: brokenRefs,
+    warnings,
+    errors,
+    ran_at: ranAt,
+    exit_code: exitCode,
+    raw_stdout: stdout.slice(0, 8000),
+    raw_stderr: stderr.slice(0, 2000),
+    ...(infos.length > 0 ? { infos } : {}),
+  };
+
+  const summaryPath = resolve(cwd, ".buildanything/graph/lint-status.json");
+  atomicWrite(summaryPath, JSON.stringify(summary, null, 2));
+
+  const buildLogPath = resolve(cwd, "docs/plans/build-log.md");
+  if (existsSync(buildLogPath)) {
+    const shortHash = fileHash.slice(0, 12);
+    const oneLine = `${summary.ran_at} | broken-refs: ${brokenRefs} | warnings: ${warnings.length} | hash: ${shortHash}\n`;
+    let existing = readFileSync(buildLogPath, "utf8");
+    if (!/## Phase 3 Step 3\.8 — DESIGN\.md Lint/.test(existing)) {
+      existing += `\n## Phase 3 Step 3.8 — DESIGN.md Lint\n\n`;
+      writeFileSync(buildLogPath, existing);
+    }
+    appendFileSync(buildLogPath, oneLine);
+  }
+
+  if (brokenRefs > 0) {
+    process.stderr.write(`design-md-lint: ${brokenRefs} broken-ref error(s) — Phase 3.8 routes back to Step 3.4\n`);
+    for (const e of errors) {
+      process.stderr.write(`  ${e.rule}${e.line ? ` (line ${e.line})` : ""}: ${e.message}\n`);
+    }
+  }
+  if (warnings.length > 0) {
+    process.stdout.write(`design-md-lint: ${warnings.length} warning(s) (logged, non-blocking)\n`);
+  }
+  if (infos.length > 0) {
+    process.stdout.write(`design-md-lint: ${infos.length} info(s) (logged, non-blocking)\n`);
+  }
+
+  return exitCode;
+}
+
+if (process.argv[1]?.endsWith("design-md-lint.ts") || process.argv[1]?.endsWith("design-md-lint")) {
+  process.exit(main());
+}

package/hooks/hooks.json

@@ -12,6 +12,42 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use'",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start'",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop'",
+            "async": false
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "matcher": ".*",

package/hooks/pre-tool-use

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# buildanything: PreToolUse writer-owner hook (task 2.1.1)
+# Enforces the writer-owner table from docs/migration/phase-graph.yaml on
+# Write|Edit|MultiEdit tool calls. Shim delegates to Node via tsx.
+#
+# Claude Code hook protocol: exit 2 with stderr = deny. Exit 0 = allow.
+# Rollback: BUILDANYTHING_ENFORCE_WRITER_OWNER=false degrades deny to warn.
+
+set -u
+
+HANDLER="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}/hooks/pre-tool-use.ts"
+
+if [ ! -f "$HANDLER" ]; then
+  # Handler missing — fail open so the hook never bricks the session.
+  echo "buildanything: pre-tool-use handler missing at $HANDLER — allowing" >&2
+  exit 0
+fi
+
+exec npx --no-install tsx "$HANDLER"