@therocketcode/gsd-core 1.4.0

package/scripts/base64-scan.sh

@@ -0,0 +1,351 @@
+#!/usr/bin/env bash
+# base64-scan.sh — Detect base64-obfuscated prompt injection in source files
+#
+# Extracts base64 blobs >= 40 chars, decodes them, and checks decoded content
+# against the same injection patterns used by prompt-injection-scan.sh.
+#
+# Usage:
+#   scripts/base64-scan.sh --diff origin/main   # CI mode: scan changed files
+#   scripts/base64-scan.sh --file path/to/file   # Scan a single file
+#   scripts/base64-scan.sh --dir agents/          # Scan all files in a directory
+#
+# Exit codes:
+#   0 = clean
+#   1 = findings detected
+#   2 = usage error
+set -euo pipefail
+
+# ── Locale hardening (#116) ───────────────────────────────────────────────────
+# BSD tr (macOS) treats input bytes as multi-byte characters under any UTF-8
+# locale.  When the input to `tr -cd '[:print:]'` contains bytes that are not
+# valid UTF-8 start sequences (e.g. lone continuation bytes 0x80–0x9F), BSD tr
+# emits "Illegal byte sequence" to stderr and exits non-zero.  Setting LC_ALL=C
+# forces the C locale throughout the script so every byte 0x00–0xFF is a valid
+# character — no multi-byte interpretation, no illegal-byte errors.
+#
+# This is safe for our use-case: all injection patterns are ASCII; base64 -d
+# and grep -E POSIX classes ([:space:], [:print:]) behave correctly in C locale.
+#
+# Source: `man tr` on macOS 26.5 — ENVIRONMENT section states LC_ALL / LC_CTYPE
+# control character interpretation; BSD tr rejects invalid multi-byte sequences.
+# Empirically verified: `printf '\x80\x81hello' | LC_ALL=C tr -cd '[:print:]'`
+# exits 0 and strips the high bytes cleanly.
+export LC_ALL=C
+
+MIN_BLOB_LENGTH=40
+# Lines longer than this byte count are skipped with a partial-scan warning.
+# This prevents `grep -oE` from spending unbounded time on e.g. minified JS or
+# single-line binary blobs.  1 MiB is large enough for any realistic text file
+# line but small enough to bound blob-extraction cost.
+MAX_LINE_BYTES=1048576
+
+# -- Portable timeout wrapper (#116) ------------------------------------------
+# macOS does not ship GNU coreutils timeout.  We probe for it (or gtimeout
+# from homebrew coreutils), falling back to perl alarm(N)+exec.
+# Exit codes: GNU timeout uses 124 on timeout; perl SIGALRM produces 142.
+# Both are treated as timeout exits by is_timeout_exit() below.
+# Usage: run_with_timeout <seconds> <command> [args...]
+_TIMEOUT_CMD=""
+# shellcheck disable=SC2329  # intentionally defined for use by callers; not called in main loop
+_init_timeout_cmd() {
+  if [[ -n "$_TIMEOUT_CMD" ]]; then return; fi
+  if command -v timeout >/dev/null 2>&1; then
+    _TIMEOUT_CMD="timeout"
+  elif command -v gtimeout >/dev/null 2>&1; then
+    _TIMEOUT_CMD="gtimeout"
+  else
+    _TIMEOUT_CMD="perl_alarm"
+  fi
+}
+
+# shellcheck disable=SC2329  # intentionally defined for use by callers; not called in main loop
+run_with_timeout() {
+  local secs="$1"; shift
+  _init_timeout_cmd
+  case "$_TIMEOUT_CMD" in
+    timeout|gtimeout)
+      "$_TIMEOUT_CMD" "$secs" "$@"
+      ;;
+    perl_alarm)
+      # perl sets SIGALRM after N seconds, then exec()s the command.
+      # Exit 142 (SIGALRM) when timed out.
+      perl -e '
+        my $secs = shift @ARGV;
+        alarm($secs);
+        exec(@ARGV) or die "exec: $!\n";
+      ' -- "$secs" "$@"
+      ;;
+  esac
+}
+
+# is_timeout_exit: returns 0 (true) if rc indicates a timeout kill.
+# shellcheck disable=SC2329  # intentionally defined for use by callers; not called in main loop
+is_timeout_exit() { [[ "$1" -eq 124 || "$1" -eq 142 ]]; }
+
+
+# ─── Injection Patterns (decoded content) ────────────────────────────────────
+# Subset of patterns — if someone base64-encoded something, check for the
+# most common injection indicators.
+DECODED_PATTERNS=(
+  'ignore[[:space:]]+(all[[:space:]]+)?previous[[:space:]]+instructions'
+  'you[[:space:]]+are[[:space:]]+now[[:space:]]+'
+  'system[[:space:]]+prompt'
+  '</?system>'
+  '</?assistant>'
+  '\[SYSTEM\]'
+  '\[INST\]'
+  '<<SYS>>'
+  'override[[:space:]]+(system|safety|security)'
+  'pretend[[:space:]]+(you|to)[[:space:]]'
+  'act[[:space:]]+as[[:space:]]+(a|an|if)'
+  'jailbreak'
+  'bypass[[:space:]]+(safety|content|security)'
+  'eval[[:space:]]*\('
+  'exec[[:space:]]*\('
+  'rm[[:space:]]+-rf'
+  'curl[[:space:]].*\|[[:space:]]*sh'
+  'wget[[:space:]].*\|[[:space:]]*sh'
+)
+
+# ─── Ignorelist ──────────────────────────────────────────────────────────────
+
+IGNOREFILE=".base64scanignore"
+IGNORED_PATTERNS=()
+
+load_ignorelist() {
+  if [[ -f "$IGNOREFILE" ]]; then
+    while IFS= read -r line; do
+      # Skip comments and empty lines
+      [[ "$line" =~ ^[[:space:]]*# ]] && continue
+      [[ -z "${line// }" ]] && continue
+      IGNORED_PATTERNS+=("$line")
+    done < "$IGNOREFILE"
+  fi
+}
+
+is_ignored() {
+  local blob="$1"
+  if [[ ${#IGNORED_PATTERNS[@]} -eq 0 ]]; then
+    return 1
+  fi
+  for pattern in "${IGNORED_PATTERNS[@]}"; do
+    if [[ "$blob" == "$pattern" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# ─── Skip Rules ──────────────────────────────────────────────────────────────
+
+should_skip_file() {
+  local file="$1"
+  # Skip binary files
+  case "$file" in
+    *.png|*.jpg|*.jpeg|*.gif|*.ico|*.woff|*.woff2|*.ttf|*.eot|*.otf) return 0 ;;
+    *.zip|*.tar|*.gz|*.bz2|*.xz|*.7z) return 0 ;;
+    *.pdf|*.doc|*.docx|*.xls|*.xlsx) return 0 ;;
+  esac
+  # Skip lockfiles and node_modules
+  case "$file" in
+    */node_modules/*) return 0 ;;
+    */package-lock.json) return 0 ;;
+    */yarn.lock) return 0 ;;
+    */pnpm-lock.yaml) return 0 ;;
+  esac
+  # Skip the scan scripts themselves and test files
+  case "$file" in
+    */base64-scan.sh) return 0 ;;
+    */security-scan.test.cjs) return 0 ;;
+  esac
+  # Skip scanner fixture directories — they contain deliberate injection samples
+  case "$file" in
+    tests/fixtures/*) return 0 ;;
+  esac
+  return 1
+}
+
+is_data_uri() {
+  local context="$1"
+  # data:image/png;base64,... or data:application/font-woff;base64,...
+  echo "$context" | grep -qE 'data:[a-zA-Z]+/[a-zA-Z0-9.+-]+;base64,' 2>/dev/null
+}
+
+# ─── File Collection ─────────────────────────────────────────────────────────
+
+collect_files() {
+  local mode="$1"
+  shift
+
+  case "$mode" in
+    --diff)
+      local base="${1:-origin/main}"
+      git diff --name-only --diff-filter=ACMR "$base"...HEAD 2>/dev/null \
+        | grep -vE '\.(png|jpg|jpeg|gif|ico|woff|woff2|ttf|eot|otf|zip|tar|gz|pdf)$' || true
+      ;;
+    --file)
+      if [[ -f "$1" ]]; then
+        echo "$1"
+      else
+        echo "Error: file not found: $1" >&2
+        exit 2
+      fi
+      ;;
+    --dir)
+      local dir="$1"
+      if [[ ! -d "$dir" ]]; then
+        echo "Error: directory not found: $dir" >&2
+        exit 2
+      fi
+      find "$dir" -type f ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' \
+        ! -name '*.png' ! -name '*.jpg' ! -name '*.gif' ! -name '*.woff*' 2>/dev/null || true
+      ;;
+    --stdin)
+      cat
+      ;;
+    *)
+      echo "Usage: $0 --diff [base] | --file <path> | --dir <path> | --stdin" >&2
+      exit 2
+      ;;
+  esac
+}
+
+# ─── Scanner ─────────────────────────────────────────────────────────────────
+
+extract_and_check_blobs() {
+  local file="$1"
+  local found=0
+  local line_num=0
+
+  # Skip binary-by-content files (e.g. adversarial parser fixtures with embedded
+  # non-UTF8 / NUL bytes). They cannot meaningfully carry base64-obfuscated *text*,
+  # and feeding NUL bytes through the per-line scanner spawns thousands of bogus
+  # `base64 -d` subprocesses (the "ignored null byte" warnings) — slow enough to
+  # blow the job timeout on a large diff. `grep -Iq .` treats a binary file as
+  # non-matching, so this skips it with a coverage notice (collect_files already
+  # filters binary *extensions*; this catches binary *content* in text extensions).
+  if ! LC_ALL=C grep -Iq . "$file" 2>/dev/null; then
+    echo "SKIP: $file (binary content — base64 text scan not applicable)" >&2
+    return 0
+  fi
+
+  while IFS= read -r line; do
+    line_num=$((line_num + 1))
+
+    # Guard: skip lines that exceed MAX_LINE_BYTES.  Very long lines (e.g. a
+    # minified JS bundle stored as one line, or a binary file with no newlines)
+    # would cause `grep -oE` to spend unbounded time.  We emit a partial-scan
+    # warning to stderr so the caller can see coverage was reduced.
+    if [[ ${#line} -gt $MAX_LINE_BYTES ]]; then
+      echo "SKIP: $file line $line_num (${#line} bytes > ${MAX_LINE_BYTES} limit — partial scan)" >&2
+      continue
+    fi
+
+    # Skip data URIs — legitimate base64 usage
+    if is_data_uri "$line"; then
+      continue
+    fi
+
+    # Extract base64-like blobs (alphanumeric + / + = padding, >= MIN_BLOB_LENGTH)
+    local blobs
+    blobs=$(echo "$line" | grep -oE '[A-Za-z0-9+/]{'"$MIN_BLOB_LENGTH"',}={0,3}' 2>/dev/null || true)
+
+    if [[ -z "$blobs" ]]; then
+      continue
+    fi
+
+    while IFS= read -r blob; do
+      [[ -z "$blob" ]] && continue
+
+      # Check ignorelist
+      if [[ ${#IGNORED_PATTERNS[@]} -gt 0 ]] && is_ignored "$blob"; then
+        continue
+      fi
+
+      # Try to decode — if it fails, not valid base64
+      local decoded
+      decoded=$(echo "$blob" | base64 -d 2>/dev/null || echo "")
+
+      if [[ -z "$decoded" ]]; then
+        continue
+      fi
+
+      # Check if decoded content is mostly printable text (not random binary)
+      local total_chars=${#decoded}
+      if [[ $total_chars -eq 0 ]]; then
+        continue
+      fi
+
+      # Count printable ASCII characters
+      local printable_count
+      printable_count=$(echo -n "$decoded" | tr -cd '[:print:]' | wc -c | tr -d ' ')
+      # Skip if less than 70% printable (likely binary data, not obfuscated text)
+      if [[ $((printable_count * 100 / total_chars)) -lt 70 ]]; then
+        continue
+      fi
+
+      # Scan decoded content against injection patterns
+      for pattern in "${DECODED_PATTERNS[@]}"; do
+        if echo "$decoded" | grep -iqE "$pattern" 2>/dev/null; then
+          if [[ $found -eq 0 ]]; then
+            echo "FAIL: $file"
+            found=1
+          fi
+          echo "  line $line_num: base64 blob decodes to suspicious content"
+          echo "    blob: ${blob:0:60}..."
+          echo "    decoded: ${decoded:0:120}"
+          echo "    matched: $pattern"
+          break
+        fi
+      done
+    done <<< "$blobs"
+  done < "$file"
+
+  return $found
+}
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+main() {
+  if [[ $# -eq 0 ]]; then
+    echo "Usage: $0 --diff [base] | --file <path> | --dir <path>" >&2
+    exit 2
+  fi
+
+  load_ignorelist
+
+  local mode="$1"
+  shift
+
+  local files
+  files=$(collect_files "$mode" "$@")
+
+  if [[ -z "$files" ]]; then
+    echo "base64-scan: no files to scan"
+    exit 0
+  fi
+
+  local total=0
+  local failed=0
+
+  while IFS= read -r file; do
+    [[ -z "$file" ]] && continue
+    if should_skip_file "$file"; then
+      continue
+    fi
+    total=$((total + 1))
+    if ! extract_and_check_blobs "$file"; then
+      failed=$((failed + 1))
+    fi
+  done <<< "$files"
+
+  echo ""
+  echo "base64-scan: scanned $total files, $failed with findings"
+
+  if [[ $failed -gt 0 ]]; then
+    exit 1
+  fi
+  exit 0
+}
+
+main "$@"

package/scripts/build-hooks.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * Copy GSD hooks to dist for installation.
+ * Validates JavaScript syntax before copying to prevent shipping broken hooks.
+ * See #1107, #1109, #1125, #1161 — a duplicate const declaration shipped
+ * in dist and caused PostToolUse hook errors for all users.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const HOOKS_DIR = path.join(__dirname, '..', 'hooks');
+const DIST_DIR = path.join(HOOKS_DIR, 'dist');
+// Per-process staging directory for atomic writes. Using process.pid in the
+// name eliminates all contention between concurrent builders: each process
+// owns its own staging dir and never races with another builder's cleanup.
+// Lives under hooks/ so it shares a filesystem with DIST_DIR (POSIX
+// rename(2) is only atomic within the same filesystem) but is NOT inside
+// DIST_DIR — so readers that readdirSync(DIST_DIR) (e.g. bin/install.js,
+// install-hooks-copy tests) never observe a transient ".tmp" sibling.
+// The parent pattern hooks/.dist-staging-*/ is gitignored.
+const STAGE_DIR = path.join(HOOKS_DIR, `.dist-staging-${process.pid}`);
+
+// Hooks to copy (pure Node.js, no bundling needed)
+const HOOKS_TO_COPY = [
+  'gsd-check-update-worker.js',
+  'gsd-check-update.js',
+  // Required by gsd-check-update-worker.js at runtime — must ship alongside it
+  // so require('./managed-hooks-registry.cjs') resolves in the installed hooks/ dir.
+  'managed-hooks-registry.cjs',
+  'gsd-context-monitor.js',
+  // Cursor lifecycle hooks (issue #777): sessionStart context injection + postToolUse monitor
+  'gsd-cursor-session-start.js',
+  'gsd-cursor-post-tool.js',
+  // Claude Code FileChanged hook (#770) — hot-reloads gsd config when
+  // .planning/config.json changes mid-session. Must ship to dist so the
+  // installer can copy it to the target hooks/ dir and register FileChanged.
+  'gsd-config-reload.js',
+  'gsd-prompt-guard.js',
+  'gsd-read-guard.js',
+  'gsd-read-injection-scanner.js',
+  'gsd-statusline.js',
+  'gsd-update-banner.js',
+  'gsd-workflow-guard.js',
+  'gsd-worktree-path-guard.js',
+  // Community hooks (bash, opt-in via .planning/config.json hooks.community)
+  'gsd-session-state.sh',
+  'gsd-validate-commit.sh',
+  'gsd-phase-boundary.sh',
+  // Graphify auto-update hook (#3347 / PR #3557 / #3579). Opt-in via
+  // .planning/config.json graphify.auto_update; off by default.
+  'gsd-graphify-update.sh'
+];
+
+// Subdirectories under hooks/ whose contents must also ship to dist. Each
+// entry is copied as `hooks/<dir>/*` → `hooks/dist/<dir>/*` so detached
+// helpers (e.g. hooks/lib/gsd-graphify-rebuild.sh) resolve from the hook's
+// installed runtime path. See #3579.
+const HOOKS_SUBDIRS_TO_COPY = ['lib'];
+
+// Sync millisecond sleep using Atomics.wait on a throwaway SharedArrayBuffer.
+// Used between Windows rename retries; this script is sync end-to-end so
+// setTimeout would not work. Total worst-case backoff across MAX_ATTEMPTS
+// is bounded (~400ms) — acceptable for a one-shot build script.
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Atomic-replace via fs.renameSync, with Windows-only retry and fallback.
+ *
+ * POSIX rename(2) atomically replaces dest even when readers hold open
+ * handles on it. Windows MoveFileEx (which fs.renameSync uses with
+ * MOVEFILE_REPLACE_EXISTING) cannot — it throws EPERM/EBUSY when another
+ * process has the destination open. Concurrent install.js readers and
+ * antivirus scanners are the realistic triggers; both release handles
+ * within milliseconds, so a short backoff resolves the race. After
+ * retries are exhausted, fall back to copy-then-unlink (re-introduces
+ * the truncate-then-write race for this single file but keeps the build
+ * moving rather than crashing). If even copy fails because dest is hard-
+ * locked, log a non-fatal warning and leave the prior dest in place — a
+ * subsequent build invocation will retry from a fresh state.
+ */
+function renameAtomicWithRetry(stagedDest, dest, hook) {
+  if (process.platform !== 'win32') {
+    fs.renameSync(stagedDest, dest);
+    return;
+  }
+  const BACKOFFS_MS = [10, 30, 90, 270];
+  for (let attempt = 0; attempt <= BACKOFFS_MS.length; attempt++) {
+    try {
+      fs.renameSync(stagedDest, dest);
+      return;
+    } catch (e) {
+      const transient = e && (e.code === 'EPERM' || e.code === 'EBUSY');
+      if (!transient) throw e;
+      if (attempt < BACKOFFS_MS.length) {
+        sleepSync(BACKOFFS_MS[attempt]);
+        continue;
+      }
+      // Retries exhausted; fall back to copy-then-unlink.
+      try {
+        fs.copyFileSync(stagedDest, dest);
+        try { fs.unlinkSync(stagedDest); } catch (_) { /* tolerate */ }
+        console.warn(`\x1b[33m! ${hook}: rename failed (${e.code}) after ${BACKOFFS_MS.length} retries; used copy-fallback\x1b[0m`);
+        return;
+      } catch (fallbackErr) {
+        try { fs.unlinkSync(stagedDest); } catch (_) { /* tolerate */ }
+        console.warn(`\x1b[33m! ${hook}: rename + copy fallback both failed (${e.code} → ${fallbackErr.code || fallbackErr.message}); leaving prior dest in place\x1b[0m`);
+        return;
+      }
+    }
+  }
+}
+
+/**
+ * Validate JavaScript syntax without executing the file.
+ * Catches SyntaxError (duplicate const, missing brackets, etc.)
+ * before the hook gets shipped to users.
+ */
+function validateSyntax(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  try {
+    // Use vm.compileFunction to check syntax without executing
+    new vm.Script(content, { filename: path.basename(filePath) });
+    return null; // No error
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      return e.message;
+    }
+    throw e;
+  }
+}
+
+function build() {
+  // Ensure dist and staging directories exist (staging is a sibling of dist
+  // used to make writes atomic — see STAGE_DIR comment above).
+  if (!fs.existsSync(DIST_DIR)) {
+    fs.mkdirSync(DIST_DIR, { recursive: true });
+  }
+  if (!fs.existsSync(STAGE_DIR)) {
+    fs.mkdirSync(STAGE_DIR, { recursive: true });
+  }
+
+  let hasErrors = false;
+
+  // Copy hooks to dist with syntax validation
+  for (const hook of HOOKS_TO_COPY) {
+    const src = path.join(HOOKS_DIR, hook);
+    const dest = path.join(DIST_DIR, hook);
+
+    if (!fs.existsSync(src)) {
+      console.warn(`Warning: ${hook} not found, skipping`);
+      continue;
+    }
+
+    // Validate JS syntax before copying (.sh files skip — not Node.js)
+    if (hook.endsWith('.js')) {
+      const syntaxError = validateSyntax(src);
+      if (syntaxError) {
+        console.error(`\x1b[31m✗ ${hook}: SyntaxError — ${syntaxError}\x1b[0m`);
+        hasErrors = true;
+        continue;
+      }
+    }
+
+    console.log(`\x1b[32m✓\x1b[0m Copying ${hook}...`);
+    // Atomic write: copy to a per-process staging file in the per-PID sibling
+    // STAGE_DIR (same filesystem as DIST_DIR so rename(2) is atomic), then
+    // rename into place. Multiple test files invoke this script concurrently
+    // from their before() hooks; fs.copyFileSync truncates then writes the
+    // destination — readers (install.js subprocesses spawned by parallel
+    // install tests) can observe the dest empty or partial mid-write,
+    // producing flaky failures such as bug-2136 part 4 where installed .sh
+    // hooks lacked their "# gsd-hook-version:" header. POSIX rename(2)
+    // makes the swap atomic so readers see either the old file or the new
+    // file. The staging file lives outside DIST_DIR so readdirSync(DIST_DIR)
+    // (in install.js and tests) never observes a transient ".tmp" sibling.
+    // Each process uses its own STAGE_DIR (keyed by PID) so concurrent
+    // builders never race on staging-dir creation or cleanup.
+    const stagedDest = path.join(STAGE_DIR, `${hook}.${Date.now()}`);
+    fs.copyFileSync(src, stagedDest);
+    // Preserve executable bit for shell scripts before rename so the
+    // installed file is executable from the very first observation.
+    if (hook.endsWith('.sh')) {
+      try { fs.chmodSync(stagedDest, 0o755); } catch (e) { /* Windows */ }
+    }
+    renameAtomicWithRetry(stagedDest, dest, hook);
+  }
+
+  // Copy whitelisted hook subdirectories (e.g. hooks/lib/) into dist so the
+  // installer's readdir-and-isFile loop in bin/install.js sees them and
+  // detached hook helpers resolve from the installed runtime path (#3579).
+  for (const subdir of HOOKS_SUBDIRS_TO_COPY) {
+    const srcDir = path.join(HOOKS_DIR, subdir);
+    if (!fs.existsSync(srcDir)) continue;
+    const destDir = path.join(DIST_DIR, subdir);
+    fs.mkdirSync(destDir, { recursive: true });
+    const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+    for (const ent of entries) {
+      if (!ent.isFile()) continue;
+      const srcFile = path.join(srcDir, ent.name);
+      const destFile = path.join(destDir, ent.name);
+      if (ent.name.endsWith('.js')) {
+        const syntaxError = validateSyntax(srcFile);
+        if (syntaxError) {
+          console.error(`\x1b[31m✗ ${subdir}/${ent.name}: SyntaxError — ${syntaxError}\x1b[0m`);
+          hasErrors = true;
+          continue;
+        }
+      }
+      console.log(`\x1b[32m✓\x1b[0m Copying ${subdir}/${ent.name}...`);
+      const stagedDest = path.join(STAGE_DIR, `${subdir}__${ent.name}.${Date.now()}`);
+      fs.copyFileSync(srcFile, stagedDest);
+      if (ent.name.endsWith('.sh')) {
+        try { fs.chmodSync(stagedDest, 0o755); } catch (e) { /* Windows */ }
+      }
+      renameAtomicWithRetry(stagedDest, destFile, `${subdir}/${ent.name}`);
+    }
+  }
+
+  // Best-effort cleanup of this process's own staging dir. Since STAGE_DIR
+  // is per-PID (`.dist-staging-<pid>/`), no other builder touches it — so
+  // rmSync with recursive:true is safe and leaves no race window.
+  try {
+    fs.rmSync(STAGE_DIR, { recursive: true, force: true });
+  } catch (e) { /* tolerate ENOENT if the dir was never created (e.g. all hooks skipped) */ }
+
+  if (hasErrors) {
+    console.error('\n\x1b[31mBuild failed: fix syntax errors above before publishing.\x1b[0m');
+    process.exit(1);
+  }
+
+  console.log('\nBuild complete.');
+}
+
+// Export HOOKS_TO_COPY so tests can require() this file and assert against
+// the typed value instead of regex-parsing the source text (retires
+// pending-migration-to-typed-ir for orphaned-hooks.test.cjs, per #455).
+// Guard the build() call so requiring this file as a module does not trigger
+// a full build run (which copies files and writes to disk).
+if (require.main === module) {
+  build();
+}
+
+module.exports = { HOOKS_TO_COPY, HOOKS_SUBDIRS_TO_COPY };