@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/scripts/write-node-launcher.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+is_managed_launcher() {
+  local candidate="$1"
+
+  grep -Fqx '# Generated by Build scripts/write-node-launcher.sh' "$candidate" 2>/dev/null \
+    || {
+      grep -Fq 'node_bin="${BUILD_NODE_BIN:-$default_node}"' "$candidate" 2>/dev/null \
+        && grep -Fq 'exec "$node_bin" "$entry_js" "$@"' "$candidate" 2>/dev/null
+    }
+}
+
+prepare_link() {
+  local candidate="$1"
+
+  if [[ -L "$candidate" && ! -e "$candidate" ]]; then
+    rm -f -- "$candidate"
+    return 0
+  fi
+  if [[ ! -e "$candidate" || -L "$candidate" ]]; then
+    return 0
+  fi
+  if [[ -f "$candidate" ]] && is_managed_launcher "$candidate"; then
+    rm -f -- "$candidate"
+    return 0
+  fi
+
+  echo "Error: Refusing to replace unmanaged file: $candidate" >&2
+  return 1
+}
+
+if [[ "$#" -eq 2 && "$1" == "--prepare-link" ]]; then
+  prepare_link "$2"
+  exit 0
+fi
+
+# Exit status only; lets callers decide whether an existing launcher is theirs to
+# overwrite without duplicating the detection heuristic.
+if [[ "$#" -eq 2 && "$1" == "--is-managed" ]]; then
+  if is_managed_launcher "$2"; then
+    exit 0
+  fi
+  exit 1
+fi
+
+if [[ "$#" -ne 3 ]]; then
+  echo "Usage: $0 <launcher-path> <node-bin> <entry-js>" >&2
+  echo "       $0 --prepare-link <launcher-path>" >&2
+  echo "       $0 --is-managed <launcher-path>" >&2
+  exit 2
+fi
+
+# Homebrew's opt symlink survives patch upgrades; the versioned Cellar keg that
+# process.execPath reports is removed by `brew cleanup`.
+stable_node_path() {
+  local candidate="$1"
+  local cellar_pattern='^(.+)/Cellar/([^/]+)/[^/]+/bin/node$'
+  if [[ "$candidate" =~ $cellar_pattern ]]; then
+    local opt_node="${BASH_REMATCH[1]}/opt/${BASH_REMATCH[2]}/bin/node"
+    if [[ -x "$opt_node" && "$opt_node" -ef "$candidate" ]]; then
+      printf '%s\n' "$opt_node"
+      return 0
+    fi
+  fi
+  printf '%s\n' "$candidate"
+}
+
+launcher_path="$1"
+# Resolve version-manager shims to the runtime they actually selected. Preserve
+# an equivalent Homebrew opt path so patch upgrades remain stable.
+selected_node="$2"
+resolved_node="$("$selected_node" -p 'process.execPath')"
+node_bin="$(stable_node_path "$selected_node")"
+if [[ "$node_bin" == "$selected_node" ]]; then
+  node_bin="$(stable_node_path "$resolved_node")"
+fi
+entry_js="$3"
+
+if [[ ! -x "$node_bin" ]]; then
+  echo "Error: Node executable is not runnable: $node_bin" >&2
+  exit 1
+fi
+if [[ ! -f "$entry_js" ]]; then
+  echo "Error: Build entrypoint not found: $entry_js" >&2
+  exit 1
+fi
+
+# Supported Node majors; both case patterns below are pinned to
+# SUPPORTED_NODE_MAJORS by tests/unit/scripts/node-runtime-automation.test.ts.
+node_version="$("$node_bin" -p 'process.versions.node')"
+case "${node_version%%.*}" in
+  24|26) ;;
+  *)
+    echo "Error: Node 24.x or 26.x is required to generate the Build launcher (found: v${node_version})." >&2
+    exit 1
+    ;;
+esac
+
+mkdir -p "$(dirname "$launcher_path")"
+temporary="$(mktemp "${launcher_path}.tmp.XXXXXX")"
+trap 'rm -f "$temporary"' EXIT
+
+{
+  echo '#!/usr/bin/env bash'
+  echo '# Generated by Build scripts/write-node-launcher.sh'
+  echo 'set -euo pipefail'
+  printf 'default_node=%q\n' "$node_bin"
+  printf 'entry_js=%q\n' "$entry_js"
+  cat <<'EOF'
+node_bin="${BUILD_NODE_BIN:-$default_node}"
+if [[ ! -x "$node_bin" ]]; then
+  echo "build: configured Node executable is unavailable: $node_bin" >&2
+  echo "Re-run the Build installer/build or set BUILD_NODE_BIN to Node 24 or 26." >&2
+  exit 1
+fi
+node_version="$("$node_bin" -p 'process.versions.node' 2>/dev/null || true)"
+case "${node_version%%.*}" in
+  24|26) ;;
+  *)
+    echo "build: Node 24.x or 26.x is required (configured runtime: ${node_version:-unknown})." >&2
+    exit 1
+    ;;
+esac
+if [[ ! -f "$entry_js" ]]; then
+  echo "build: entrypoint is unavailable: $entry_js" >&2
+  echo "Re-run the Build installer/build." >&2
+  exit 1
+fi
+# Lets `build upgrade` preserve the selected runtime on rewrite.
+export BUILD_LAUNCHER_NODE="$node_bin"
+exec "$node_bin" "$entry_js" "$@"
+EOF
+} >"$temporary"
+
+chmod 755 "$temporary"
+mv "$temporary" "$launcher_path"
+trap - EXIT

package/src/resources/gemini/slash-packs/default/plan.toml

@@ -0,0 +1,15 @@
+name = "plan"
+description = "Draft a concise implementation plan before writing code."
+prompt = """
+You are an experienced engineer working inside this repository.
+
+Task:
+{{input}}
+
+Produce:
+1. A numbered list of concrete steps (<= 8 items).
+2. Note any risks, unknowns, or follow-ups.
+
+Do not write code. Focus on sequencing the work so another engineer can execute it.
+"""
+

package/src/resources/gemini/slash-packs/default/summary.toml

@@ -0,0 +1,16 @@
+name = "summary"
+description = "Summarize changes ready for code review."
+prompt = """
+You are preparing a crisp hand-off summary for reviewers of this repository.
+
+Task or diff context:
+{{input}}
+
+Return:
+- A bullet list of meaningful changes grouped by area.
+- Any migrations, follow-up items, or verification steps (tests run, commands to execute).
+- Mention unresolved questions or TODOs if they exist.
+
+Keep the tone factual and concise. Avoid repeating code line-by-line.
+"""
+

package/src/resources/gemini/slash-packs/default/tests.toml

@@ -0,0 +1,16 @@
+name = "tests"
+description = "Outline the right test additions or updates for the current task."
+prompt = """
+You are responsible for developing a pragmatic testing strategy for this codebase.
+
+Task context:
+{{input}}
+
+Respond with:
+- The types of tests to add or update (unit, integration, e2e, etc.).
+- The key scenarios/assertions each test must cover.
+- Any tooling or setup steps required (mocks, fixtures, CLI commands).
+
+Keep the answer focused on test strategy. Do not generate code.
+"""
+

package/templates/.build-project/README.md

@@ -0,0 +1,41 @@
+# Build Project Directory
+
+This `.build-project/` directory contains project-local configuration and runtime artifacts for the Build CLI.
+
+## Directory Structure (High-Level)
+
+```text
+.build-project/
+ .artifacts/                      # Legacy/generated artifacts (gitignored)
+ config/
+    build.config.jsonc         # Project configuration
+    project-context.json        # Project detection output
+ telemetry/
+    state/                      # Per-run competition/variant state (repo-local; gitignored)
+    logs/                       # Flywheel workflow JSONL only (repo-local; gitignored)
+ state/                          # Runtime markers/locks (gitignored)
+ worktrees/                      # Temporary worktrees (gitignored)
+ .gitignore                      # Ignores runtime artifacts
+ README.md                       # This file
+```
+
+## Configuration
+
+- Provider settings for this project live in the `providers` block of `.build-project/config/build.config.jsonc`; `build config resolved` shows the effective values.
+- Registry-level overrides that should apply to every project on this machine (available models, per-provider defaults, timeouts) belong in `~/.build/config/providers.yaml`, not in this directory.
+- The same file holds advanced settings such as quality gates and execution tuning.
+
+Live SQLite databases (`variants.db`, `validations.db`, `invocations.db`) and the
+main JSONL log stream live under the Build data root (`~/.build/data/telemetry/`
+by default), not in this checkout. `build doctor --verbose` prints the resolved
+directory. Do not delete the whole `.build-project/telemetry/` tree: `state/` is still
+the live per-run store.
+
+## Useful Commands
+
+```bash
+build doctor
+build doctor --verbose
+build doctor --fix
+build config resolved
+```

package/templates/.build-project/agents/README.md

@@ -0,0 +1,50 @@
+# Agent personas
+
+This directory holds optional agent persona files for this project. `build init`
+creates the directory with this README only; the bundled example personas are
+installed when you pass `--agent-personas`.
+
+## How Build uses them
+
+Build's agent registry looks for `*.md` files in this order, with earlier
+directories taking precedence for the same name:
+
+1. `.build-project/agents/` in the project
+2. `~/.build/agents/`
+3. `~/.claude/agents/`
+
+Each file is Markdown with YAML frontmatter. Build reads two frontmatter
+fields, `name` and `description`, and ignores any others:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews a change for defects and missing tests. Use for code review.
+---
+The body is the persona's instructions.
+```
+
+The `description` drives routing: Build extracts task words (review, test,
+debug, design, document, and so on) and language names from it and scores each
+persona against a prompt. Build does not read the body; it is for the agents and
+tools that load these files.
+
+Routing hints are off by default. Turn them on for one run with
+`build run --agent-hints`, or for every run by setting
+`BUILD_AGENT_REGISTRY_HINTS=1` in the environment. When hints are off, the
+files in this directory have no effect on Build.
+
+## Bundled examples
+
+`build init --agent-personas` installs five short personas written for the kinds
+of work Build routes: `code-reviewer`, `debugger`, `test-automator`,
+`architect`, and `documenter`. Edit them freely; Build never overwrites a file
+that already exists here.
+
+## Writing your own
+
+Give each persona a `name` that matches its file name and a `description` that
+says what it does and when to use it, using the task words above so routing can
+match it. Keep the body focused on the output the persona should produce.
+Personas that should apply to every project on this machine belong in
+`~/.build/agents/`.

package/templates/.build-project/agents/architect.md

@@ -0,0 +1,10 @@
+---
+name: architect
+description: Designs module boundaries, interfaces, and data flow for a feature or a refactor, and plans the migration path. Use to design or architect a change before implementation.
+---
+
+You design a change before anyone implements it. Read the code the change touches and the constraints the project already states.
+
+Produce a short design: the components involved, the interfaces between them, what data moves where, and the order of steps to get from the current state to the target without a broken intermediate state. Name the alternatives you rejected and why.
+
+Do not implement. Report open questions that need a decision from the project owner.

package/templates/.build-project/agents/code-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: code-reviewer
+description: Reviews a change for defects, security problems, performance risks, and missing tests before it merges. Use for code review, audit, and pre-merge inspection.
+---
+
+You review a specific change. Read the diff and the code it touches; do not edit files.
+
+Report findings first, most severe first. For each finding give the file and line, what goes wrong, and a concrete input or state that triggers it. Separate defects from suggestions. If nothing is wrong, say so plainly.
+
+End with anything that blocked the review: files you could not read, tests you could not run, context you were missing.

package/templates/.build-project/agents/debugger.md

@@ -0,0 +1,10 @@
+---
+name: debugger
+description: Finds the cause of an error, failing test, or unexpected behavior and proposes the smallest fix. Use to debug, troubleshoot, and resolve regressions.
+---
+
+You are given a failure: an error message, a failing test, or behavior that does not match expectations.
+
+Reproduce it first. Then trace from the symptom to the cause and state the cause in one sentence before proposing a change. Prefer the smallest fix that addresses the cause; note any adjacent problems you saw but did not fix.
+
+Report: the reproduction steps, the cause, the fix, and how you confirmed the fix resolves the original failure.

package/templates/.build-project/agents/documenter.md

@@ -0,0 +1,10 @@
+---
+name: documenter
+description: Writes and updates documentation such as README files, API references, guides, and code comments that explain behavior. Use to document a feature or explain how something works.
+---
+
+You write documentation for behavior that already exists. Read the code before describing it; document what it does, not what it was meant to do.
+
+Match the project's existing documentation style and placement. Prefer updating an existing document over adding a new one. State prerequisites and limits plainly, and keep examples runnable.
+
+Report: the documents added or changed and any behavior you could not verify from the code.

package/templates/.build-project/agents/test-automator.md

@@ -0,0 +1,10 @@
+---
+name: test-automator
+description: Writes and repairs automated tests at the unit, integration, and end-to-end level. Use to test new behavior, validate a fix, or verify coverage of a change.
+---
+
+You add or repair tests for a specific behavior. Use the project's existing test framework, layout, and naming; do not introduce a new one.
+
+Write the narrowest test that proves the behavior, at the shallowest layer that can prove it. A test for a fix must fail without the fix. Never weaken an existing assertion to make a test pass.
+
+Report: the tests added or changed, the behavior each one proves, and the command that runs them.

package/templates/.build-project/config/build.config.jsonc

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://cdn.jsdelivr.net/npm/@ebrindley/build/schemas/build.config.schema.json",
+
+  // No project-level defaultProvider override: Build resolves the default
+  // from environment, user config, profiles, and the bundled provider registry.
+
+  // Provider enablement and model choices inherit your user configuration.
+  // Add project-specific overrides only when you want them here.
+
+  // Quality gates: automated validation for generated work where project
+  // capabilities or explicit verification config provide commands.
+  "quality": {
+    "coverage": {
+      "enabled": true,
+      "threshold": 80, // Minimum test coverage percentage
+    },
+    "lint": {
+      "enabled": true,
+      // Uses the target project's configured lint command when available.
+    },
+    "security": {
+      "enabled": true,
+      // Uses a dependency-audit command only when the target project supports one.
+    },
+  },
+
+  // Telemetry Configuration — variant performance tracking (all data stored locally)
+  // Databases live under the Build data root, outside this checkout, so deleting
+  // the checkout does not delete its execution history. The deprecated
+  // "database" key is an override for relocating them; leave it unset.
+  "telemetry": {
+    "enabled": true,
+    // All telemetry stored locally — no data sent externally
+  },
+
+  // Git attribution policy for agent-produced commits and pull requests.
+  // "allow" (default) leaves every provider CLI's own behavior alone.
+  // "human-only" makes attribution belong to the human author only: the Guard
+  // kit rejects agent identities, co-author trailers, and agent bylines, and
+  // `build guard sync` turns off each provider's own attribution where it can.
+  // Resolution: this project file, then the user file, then "allow".
+  // "git": {
+  //   "attribution": "human-only",
+  // },
+
+  // Variant Competition Settings — how competing variants are executed.
+  // Variants differ by provider, model, or reasoning effort; every variant runs
+  // the same execution contract.
+  "variants": {
+    // Maximum concurrent variant executions
+    "maxConcurrent": 3,
+  },
+
+  // Execution Settings — timeout, concurrency, and merge-time repair
+  "execution": {
+    // Default timeout for variant competition (minutes)
+    "defaultTimeout": 30,
+    // CPU-aware concurrency (cores × multiplier, max 5)
+    "concurrencyMultiplier": 2,
+
+    // Merge-time repair uses runtime defaults unless explicitly configured.
+    // Override via config or env: BUILD_BIOME_REPAIR_PROVIDER / BUILD_BIOME_REPAIR_MODEL
+  },
+}

package/templates/.build-project/config/project-context.template.json

@@ -0,0 +1,6 @@
+{
+  "projectName": "{{PROJECT_NAME}}",
+  "language": "{{LANGUAGE}}",
+  "framework": "{{FRAMEWORK}}",
+  "detectedAt": "{{DETECTED_AT}}"
+}

package/templates/.build-project/config/task-type-aliases.presets/kanban.yaml

@@ -0,0 +1,14 @@
+# OPT-IN preset: Kanban terminology -> registry task-type ids.
+#
+# EXAMPLE preset, NOT active by default. Copy into your repo's
+# `.build-project/config/task-type-aliases.yaml` to opt in. Values must match real
+# registry ids (`build task-type list`). Declared terms remain opaque to the
+# core and are recorded verbatim on the item.
+aliases:
+  feature: feature
+  enhancement: feature
+  bug: general
+  defect: general
+  task: general
+  research: analysis
+  documentation: doc

package/templates/.build-project/config/task-type-aliases.presets/scrum.yaml

@@ -0,0 +1,17 @@
+# OPT-IN preset: Scrum terminology -> Build registry task-type ids.
+#
+# This is an EXAMPLE preset, NOT active by default. To use it, copy its contents
+# into your repo's `.build-project/config/task-type-aliases.yaml` (or merge selected
+# entries). Values must match real registry ids (`build task-type list`); edit
+# them if your repo defines custom task types.
+#
+# Declared terms are opaque to Build's core: this file only maps them to a
+# canonical id for resolution convenience; the declared term is still recorded
+# verbatim on the work item.
+aliases:
+  epic: feature
+  story: feature
+  task: general
+  spike: analysis
+  bug: general
+  chore: general

package/templates/.build-project/config/task-type-aliases.presets/xp.yaml

@@ -0,0 +1,12 @@
+# OPT-IN preset: Extreme Programming (XP) terminology -> registry task-type ids.
+#
+# EXAMPLE preset, NOT active by default. Copy into your repo's
+# `.build-project/config/task-type-aliases.yaml` to opt in. Values must match real
+# registry ids (`build task-type list`). Declared terms remain opaque to the
+# core and are recorded verbatim on the item.
+aliases:
+  story: feature
+  user-story: feature
+  spike: analysis
+  refactoring: general
+  defect: general

package/templates/.build-project/config/task-type-aliases.yaml

@@ -0,0 +1,29 @@
+# Task-type alias map (declared work-item terminology -> registry task-type id)
+#
+# OPT-IN. Ships EMPTY by design. Out of the box, NO declared term is mapped to a
+# canonical task-type id: a declared term (from `build plan backlog add --type <term>`
+# or `--work-type <term>`) still round-trips verbatim and resolves to the default
+# task type (`general`). Prose inference runs only for items with NO declared
+# term: a typed item is never re-typed from its text. This file is convenience,
+# never a dependency.
+#
+# Build's core stays methodology-agnostic: methodology terms (epic/story/spike/
+# chore/rock/...) are OPAQUE data here, never branched on in code. To opt in to a
+# methodology mapping, either add entries below or copy one preset file from
+# `.build-project/config/task-type-aliases.presets/` over this file and edit to taste.
+#
+# Format (either a flat map or an `aliases:` wrapper works):
+#
+#   aliases:
+#     epic: feature
+#     story: feature
+#     spike: analysis
+#     chore: general
+#
+# Mapped values MUST be real registry task-type ids (see `build task-type list`).
+# A mapped id that does not exist in the registry is ignored (the item resolves
+# to the default type); `build task-type` validation will warn about it.
+#
+# Declared terms are recorded and matched VERBATIM (no lowercasing / inference).
+#
+# (intentionally empty)

package/templates/.build-project/gitignore.template

@@ -0,0 +1,70 @@
+# Build Artifacts
+# Generated files and runtime data - safe to ignore
+
+artifacts/
+.artifacts/
+
+# Runtime state (never commit)
+config/project-context.json
+state/
+telemetry/
+worktrees/
+cache/
+registry/
+repair-patches/
+autoloop/
+validation/
+xdg-state/
+runs/
+blocker-answers/
+merge-apply/
+provenance/
+reviews/
+codex-home/
+cursor/
+copilot/
+edits
+edits.jsonl
+implementations/
+labs/
+lifecycle/
+memory/
+provider-history/
+prompts/
+planning/indexes/
+analysis-synthesis/
+research/
+rate-limits/
+results/
+session/
+# Plan artifacts written by every planned build or `build plan` run; consumed by
+# `build plan approve`, never delivered. Anchored so authored `plans/` dirs elsewhere stay tracked.
+/plans/
+
+# Timestamped config backups written by `build config set`
+config/*.backup.*
+
+# Logs
+*.log
+/model-update.lock
+/sprint-*.lock
+planning/locks/
+*.md.lock
+*.jsonl
+# Intent context-injection telemetry (transient diagnostics: token usage,
+# selection metrics, timing). Written as `logs/injection/injection-<ts>.json`
+# by `build intent inject`; never durable, so keep it out of the tree.
+logs/injection/
+
+# Database files (SQLite + WAL)
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+
+# Temporary files
+temp/
+tmp/
+.cache/

package/templates/.build-project/task-types/analysis.yaml

@@ -0,0 +1,38 @@
+id: analysis
+version: 1
+match:
+  priority: 12
+  canonical:
+    category:
+      - analyze
+      - review
+    judgeTaskKind:
+      - analysis
+      - planning
+      - design
+  keywords:
+    - analyze
+    - investigate
+    - review
+    - audit
+    - assess
+    - evaluate
+    - root cause
+    - postmortem
+    - proposal
+    - design
+  regex:
+    - \b(analy[sz]e|investigat|diagnos|audit|assess|evaluate)\b
+    - \b(root\s*cause|post.?mortem|retro|proposal|design)\b
+policy:
+  executionIntent: analysis
+  # Verification commands are intentionally omitted in the portable template.
+  # Target projects resolve verification through project capabilities.
+  routing:
+    preferCompetition: false
+  decomposition:
+    guidance:
+      hints:
+        - Prefer read-only verification and concrete findings when the task is investigative.
+        - Avoid code edits unless the prompt explicitly asks for implementation.
+        - Do not create analysis artifacts or new files unless the goal explicitly requests a written deliverable.

package/templates/.build-project/task-types/architecture.yaml

@@ -0,0 +1,35 @@
+id: architecture
+version: 1
+extends: general
+match:
+  priority: 18
+  keywords:
+    - architecture
+    - architectural
+    - rearchitect
+    - plugin architecture
+    - plugin boundary
+    - orchestration layer
+    - api boundary
+  regex:
+    - \b(redesign|rearchitect|abstraction\s+layer|plugin\s+boundary)\b
+    - \b(define|design)\b.{0,40}\b(contract|interface|api\s+boundary|plugin\s+system|orchestration\s+layer)\b
+    - \b(plugin\s+architecture)\b
+    - \b(refactor|restructure)\b.{0,40}\b(core|execution|pipeline|orchestration)\b.{0,40}\b(model|layer|architecture|boundary)\b
+    - \b(refactor|restructure|redesign|rework|replace|decouple|extract|separate)\b(?:\s+\w+){0,2}\s+(execution\s+model|provider\s+adapters?|provider\s+execution|execution\s+orchestration)\b
+policy:
+  executionIntent: edit
+  routing:
+    preferCompetition: true
+  decomposition:
+    requiredStageTypes:
+      - verify
+    guidance:
+      hints:
+        - "Architectural stages should define clear contracts and interfaces before implementation"
+        - "Prefer competition for core design decisions with multiple valid approaches"
+      antiPatterns:
+        - "Do not over-architect simple feature additions"
+        - "Avoid creating new abstraction layers without clear justification"
+  allowlist:
+    requireNonEmpty: true

package/templates/.build-project/task-types/doc.yaml

@@ -0,0 +1,34 @@
+id: doc
+version: 1
+match:
+  priority: 6
+  # Suppress doc matching for prompts with strong code-only signals unless the
+  # prompt has a direct documentation deliverable intent (resolver reads this
+  # flag generically instead of hardcoding the 'doc' id).
+  suppressWhenCodeOnly: true
+  canonical:
+    category:
+      - execute
+    judgeTaskKind:
+      - documentation
+  keywords:
+    - doc
+    - docs
+    - documentation
+    - template
+    - claude.md
+    - agents.md
+    - readme
+    - guideline
+    - drift
+    - guide
+    - instructions
+    - specification
+    - spec
+  regex:
+    - \b(fix|create|update|add|write|generate)\b.{0,40}\b(doc|docs|documentation|template|readme|guideline|guide|instructions|specification|spec)\b
+    - \b(claude\.md|agents\.md|gemini\.md)\b
+policy:
+  executionIntent: edit
+  routing:
+    preferCompetition: false