buildanything 1.8.0 → 2.1.1

package/hooks/record-mode-transitions.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env tsx
+/*
+ * buildanything: record mode/flag transitions (task 4.7.1).
+ *
+ * Called from hooks/session-start after the writer-owner cache compile.
+ * Reads docs/plans/.build-state.json, compares the current buildanything
+ * flag values (passed via env vars) against the last recorded flag state
+ * under mode_transitions[], and APPENDs one row per changed flag.
+ *
+ * No-op when:
+ *   - docs/plans/.build-state.json does not exist (fresh project)
+ *   - mode_transitions[] is absent/empty (no prior state to diff against;
+ *     first-session capture is deferred to the first actual flip — the
+ *     safer choice per the task spec)
+ *   - no flags differ from the previous post_flags snapshot
+ *
+ * Writes atomically: JSON.stringify -> <state>.tmp -> rename().
+ *
+ * Fail-open: any error is written to stderr and we exit non-zero so the
+ * caller can fold it into DEPS_WARNING, but session-start never aborts.
+ *
+ * CJS-compatible (no import.meta). Invoked via `npx --no-install tsx`.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+
+const TRACKED_FLAGS = [
+  "BUILDANYTHING_SDK",
+  "BUILDANYTHING_SDK_SPRINT_CONTEXT",
+  "BUILDANYTHING_SDK_SPRINT_CONTEXT_IOS",
+  "BUILDANYTHING_ENFORCE_WRITER_OWNER",
+  "BUILDANYTHING_ENFORCE_WRITE_LEASE",
+  "BUILDANYTHING_SCRIBE_SINGLE_WRITER",
+  "BUILDANYTHING_ALLOW_RAW_STATE_WRITES",
+  "BUILDANYTHING_STRICT_TASK_ID",
+] as const;
+
+// Distinct unset sentinel — angle brackets make it un-shell-settable without
+// quoting, six chars, no sane operator uses this literal. Replaces the prior
+// colliding default of "false" which silently swallowed real operator opt-outs
+// like BUILDANYTHING_ENFORCE_WRITER_OWNER=false (warn-mode rollback).
+const UNSET_SENTINEL = "<unset>";
+
+type FlagName = (typeof TRACKED_FLAGS)[number];
+type FlagSnapshot = Record<FlagName, string>;
+
+interface ModeTransitionRow {
+  timestamp: string;
+  session_id: string | null;
+  flag: FlagName;
+  old_value: string;
+  new_value: string;
+  post_flags: FlagSnapshot;
+}
+
+interface BuildState {
+  mode_transitions?: ModeTransitionRow[];
+  [key: string]: unknown;
+}
+
+function defaultFor(_flag: FlagName): string {
+  // Unified sentinel for all tracked flags — collision-free with any plausible
+  // operator value. See UNSET_SENTINEL comment above.
+  return UNSET_SENTINEL;
+}
+
+// Legacy default the pre-fix recorder wrote to post_flags snapshots when a
+// tracked env var was unset. Only consulted during prev-vs-curr equivalence so
+// the first post-fix run does not spuriously record transitions against old
+// state files. Matches the old defaultFor() behavior exactly.
+function legacyDefaultFor(flag: FlagName): string {
+  return flag === "BUILDANYTHING_SDK" ? "on" : "false";
+}
+
+// True when the `prev` snapshot was written by the pre-fix recorder. Signal:
+// every tracked flag in the snapshot equals its legacy default ("on" for SDK,
+// "false" for everything else) and no `<unset>` appears anywhere. Once even a
+// single flag has been recorded as `<unset>` (or as any operator-set literal),
+// the snapshot is post-fix and legacy-compat does NOT apply — keeps real
+// "false" → `<unset>` transitions visible.
+function isLegacyDefaultOnlySnapshot(snap: FlagSnapshot): boolean {
+  for (const flag of TRACKED_FLAGS) {
+    if (snap[flag] !== legacyDefaultFor(flag)) return false;
+  }
+  return true;
+}
+
+// True when `prev` (from disk) and `curr` (from env this run) both represent
+// the "unset / default" state, so no real transition occurred. Handles:
+//   - exact match: prev == curr (any literal operator value)         → equivalent
+//   - new shape:   prev=<unset>, curr=<unset>                        → equivalent
+//   - legacy whole-snapshot: prev is pristine legacy defaults AND curr=<unset>
+//     for this flag → equivalent (suppresses spurious diff on first post-fix
+//     run against a state file written by the pre-fix recorder)
+// Any other mismatch — including the critical "false" → `<unset>` un-set after
+// a real operator flip — falls through to non-equivalent and records a diff.
+function flagValuesEquivalent(
+  flag: FlagName,
+  prev: string,
+  curr: string,
+  prevSnapshot: FlagSnapshot,
+): boolean {
+  if (prev === curr) return true;
+  if (prev === UNSET_SENTINEL && curr === UNSET_SENTINEL) return true;
+  if (
+    curr === UNSET_SENTINEL &&
+    prev === legacyDefaultFor(flag) &&
+    isLegacyDefaultOnlySnapshot(prevSnapshot)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function readCurrentFlags(): FlagSnapshot {
+  const out = {} as FlagSnapshot;
+  for (const flag of TRACKED_FLAGS) {
+    const raw = process.env[flag];
+    out[flag] = raw === undefined || raw === "" ? defaultFor(flag) : raw;
+  }
+  return out;
+}
+
+function lastRecordedFlags(state: BuildState): FlagSnapshot | null {
+  const rows = Array.isArray(state.mode_transitions) ? state.mode_transitions : [];
+  if (rows.length === 0) return null;
+  const last = rows[rows.length - 1];
+  const snap = last?.post_flags;
+  if (!snap || typeof snap !== "object") return null;
+  const out = {} as FlagSnapshot;
+  for (const flag of TRACKED_FLAGS) {
+    const v = (snap as Record<string, unknown>)[flag];
+    out[flag] = typeof v === "string" ? v : defaultFor(flag);
+  }
+  return out;
+}
+
+function diffFlags(prev: FlagSnapshot, curr: FlagSnapshot): FlagName[] {
+  const changed: FlagName[] = [];
+  for (const flag of TRACKED_FLAGS) {
+    if (!flagValuesEquivalent(flag, prev[flag], curr[flag], prev)) changed.push(flag);
+  }
+  return changed;
+}
+
+function atomicWriteJson(path: string, value: unknown): void {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  renameSync(tmp, path);
+}
+
+function formatTransitionLogLine(row: ModeTransitionRow): string {
+  const sessionId = row.session_id ?? "null";
+  return `[${row.timestamp}] mode_transition flag=${row.flag} old_value=${row.old_value} new_value=${row.new_value} session_id=${sessionId}`;
+}
+
+function appendTransitionsToBuildLog(rows: ModeTransitionRow[]): void {
+  const logPath = resolve(
+    process.env.BUILDANYTHING_BUILD_LOG_PATH ?? "docs/plans/build-log.md",
+  );
+  const dir = dirname(logPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const payload = `${rows.map(formatTransitionLogLine).join("\n")}\n`;
+  appendFileSync(logPath, payload, "utf8");
+}
+
+function main(): number {
+  const statePath = resolve(
+    process.env.BUILDANYTHING_STATE_PATH ?? "docs/plans/.build-state.json",
+  );
+  if (!existsSync(statePath)) return 0;
+
+  let state: BuildState;
+  try {
+    state = JSON.parse(readFileSync(statePath, "utf8")) as BuildState;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`record-mode-transitions: parse failed: ${msg}\n`);
+    return 1;
+  }
+
+  const curr = readCurrentFlags();
+  const prev = lastRecordedFlags(state);
+  if (prev === null) return 0; // no prior state to diff against; defer capture
+
+  const changed = diffFlags(prev, curr);
+  if (changed.length === 0) return 0;
+
+  const timestamp = new Date().toISOString();
+  const sessionId =
+    (typeof state.session_id === "string" && state.session_id) ||
+    process.env.CLAUDE_SESSION_ID ||
+    null;
+
+  const rows: ModeTransitionRow[] = changed.map((flag) => ({
+    timestamp,
+    session_id: sessionId,
+    flag,
+    old_value: prev[flag],
+    new_value: curr[flag],
+    post_flags: curr,
+  }));
+
+  const existing = Array.isArray(state.mode_transitions) ? state.mode_transitions : [];
+  const next: BuildState = { ...state, mode_transitions: [...existing, ...rows] };
+
+  try {
+    atomicWriteJson(statePath, next);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`record-mode-transitions: write failed: ${msg}\n`);
+    return 1;
+  }
+
+  // Best-effort: build-log is additive; state row is already persisted.
+  try {
+    appendTransitionsToBuildLog(rows);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`record-mode-transitions: build-log append failed: ${msg}\n`);
+  }
+
+  return 0;
+}
+
+process.exit(main());

package/hooks/session-start

@@ -2,16 +2,61 @@
 # buildanything: SessionStart hook
 # Re-injects orchestrator identity after context compaction, resume, or clear.
 
+# Cache the SessionStart hook stdin payload once — stdin is a pipe and reads
+# are destructive. Extract session_id and export as CLAUDE_SESSION_ID so the
+# mode-transition recorder (task 4.7.1) can tag rows. Tolerate empty/missing
+# stdin (e.g., when the shim is invoked outside the hook harness).
+if [ ! -t 0 ]; then
+  HOOK_STDIN=$(cat)
+  CLAUDE_SESSION_ID=$(printf '%s' "$HOOK_STDIN" | python3 -c 'import json,sys
+try:
+    print(json.loads(sys.stdin.read() or "{}").get("session_id","") or "")
+except Exception:
+    print("")' 2>/dev/null)
+  export CLAUDE_SESSION_ID
+fi
+
+# SDK install-and-probe: write on/off state to sdkStateFile for the runtime to read.
+SDK_WARN=""
+PLUGIN_ROOT_EARLY="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+SDK_STATE_FILE=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('config',{}).get('sdkStateFile',''))" "$PLUGIN_ROOT_EARLY/.claude-plugin/plugin.json" 2>/dev/null)
+if [ -n "$SDK_STATE_FILE" ]; then
+  export SDK_STATE_FILE
+  mkdir -p "$(dirname "$SDK_STATE_FILE")" 2>/dev/null
+  if [ "$BUILDANYTHING_SDK" = "off" ]; then
+    printf 'off' > "$SDK_STATE_FILE"
+  elif ! command -v npm >/dev/null 2>&1; then
+    printf 'off' > "$SDK_STATE_FILE"
+    SDK_WARN="buildanything: npm CLI not available; SDK disabled."
+  elif ! [ -f "$PLUGIN_ROOT_EARLY/package.json" ]; then
+    printf 'off' > "$SDK_STATE_FILE"
+    SDK_WARN="buildanything: plugin package.json missing; SDK disabled."
+  elif (cd "$PLUGIN_ROOT_EARLY" && npm install --silent --no-audit --no-fund >/dev/null 2>&1); then
+    printf 'on' > "$SDK_STATE_FILE"
+  else
+    printf 'off' > "$SDK_STATE_FILE"
+    SDK_WARN="buildanything: SDK install failed; falling back to markdown mode."
+  fi
+fi
+
 # Dep check: warn if plugin deps (installed via bin/setup.js) are missing.
 DEPS_WARNING=""
 MISSING=()
+command -v tsx >/dev/null 2>&1 || MISSING+=("tsx (plugin hooks need it — run: npm i -g tsx)")
 command -v agent-browser >/dev/null 2>&1 || MISSING+=("agent-browser CLI")
 { [ -e "$HOME/.claude/skills/agent-browser" ] || [ -e "$HOME/.claude/skills/agent-browser.md" ]; } || MISSING+=("agent-browser skill")
 { [ -e "$HOME/.claude/skills/dogfood" ] || [ -e "$HOME/.claude/skills/dogfood.md" ]; } || MISSING+=("dogfood skill")
+if [ "${BUILDANYTHING_PROJECT_TYPE:-}" = "ios" ]; then
+  claude mcp list 2>/dev/null | grep -q "apple-docs" || MISSING+=("apple-docs-mcp (iOS docs probe)")
+fi
 if [ ${#MISSING[@]} -gt 0 ]; then
   JOINED=$(IFS=,; echo "${MISSING[*]}"); JOINED=${JOINED//,/, }
   DEPS_WARNING="buildanything: missing deps (${JOINED}). Run /buildanything:setup to complete install."
 fi
+if [ -n "$SDK_WARN" ]; then
+  DEPS_WARNING="${DEPS_WARNING:+${DEPS_WARNING}
+}${SDK_WARN}"
+fi
 
 # Check if a build pipeline is active by looking for .build-state.md
 BUILD_STATE=""
@@ -93,7 +138,7 @@ ${DESIGN_WARNING}
 NEXT ACTIONS:
 1. Re-read commands/build.md to reload the full orchestrator process
 2. Re-read protocols/metric-loop.md if you are mid-loop
-3. Re-read protocols/design.md if you are in Phase 3 (Design & Visual Identity)
+3. Re-read protocols/web-phase-branches.md (or protocols/ios-phase-branches.md for iOS) if you are in Phase 3 (Design & Visual Identity)
 4. Re-read docs/plans/sprint-tasks.md for task list and acceptance criteria
 5. Re-read docs/plans/architecture.md for architecture context
 6. Re-read CLAUDE.md for build decisions
@@ -107,6 +152,31 @@ if [ -n "$DEPS_WARNING" ]; then
 ${CONTEXT}"
 fi
 
+# Compile writer-owner cache (task 2.1.2). Best-effort: if it fails for any
+# reason, log a warning and continue — the PreToolUse handler falls back to
+# a live YAML parse.
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+PHASE_GRAPH="$PLUGIN_ROOT/docs/migration/phase-graph.yaml"
+CACHE_DIR=".buildanything"
+CACHE_FILE="$CACHE_DIR/writer-owner.json"
+if [ -f "$PHASE_GRAPH" ]; then
+  mkdir -p "$CACHE_DIR" 2>/dev/null
+  if ! npx --no-install tsx "$PLUGIN_ROOT/hooks/compile-writer-owner-cache.ts" "$PHASE_GRAPH" "$CACHE_FILE" 2>/dev/null; then
+    echo "buildanything: writer-owner cache compile failed; handler will fall back to live YAML parse" >&2
+  fi
+else
+  echo "buildanything: phase-graph.yaml not found at $PHASE_GRAPH; writer-owner cache skipped" >&2
+fi
+
+# Record flag-flip mode transitions (task 4.7.1). Best-effort: if the TS
+# handler crashes, log to stderr and continue. No-op when .build-state.json
+# is absent (fresh project, pre-Phase-0).
+if [ -f "docs/plans/.build-state.json" ]; then
+  if ! npx --no-install tsx "$PLUGIN_ROOT/hooks/record-mode-transitions.ts"; then
+    echo "buildanything: mode-transition recorder failed; flag-flip not recorded this session" >&2
+  fi
+fi
+
 # Output as additional_context for Claude Code
 # JSON-escape the context
 ESCAPED=$(printf '%s' "$CONTEXT" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')

package/hooks/subagent-start

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# buildanything: SubagentStart staging hook (task 3.1.1)
+# Reads docs/plans/.build-state.json and stages the CONTEXT-header inputs
+# under .buildanything/subagent-start-cache/<id>.json for the 3.1.2 renderer
+# and 3.1.3 injector to consume. Purely observational — always exit 0.
+
+set -u
+
+HANDLER="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}/hooks/subagent-start.ts"
+
+if [ ! -f "$HANDLER" ]; then
+  # Handler missing — fail open so the hook never bricks the session.
+  echo "buildanything: subagent-start handler missing at $HANDLER — skipping" >&2
+  exit 0
+fi
+
+exec npx --no-install tsx "$HANDLER"