@bookedsolid/rea 0.13.1 → 0.13.2

package/.husky/pre-push

@@ -37,40 +37,47 @@ fi
 # splitting; `/Users/jane/My Projects/repo` produced four argv tokens
 # instead of two). The `set --` form below preserves spaces verbatim.
 #
-# The pre-push stdin carries one line per refspec; `exec` inherits stdin
-# unchanged. $@ on entry carries git's <remote-name> <remote-url>; we
-# preserve those by appending "$@" inside each `set --` arm.
+# 0.13.2 fix: the dispatch + invocation runs inside a SUBSHELL so the
+# `set --` rewrite does NOT bleed into the parent's $@. Before 0.13.2,
+# the parent's $@ ended up as the rea-CLI argv (`node /path/dist/cli/index.js
+# hook push-gate <remote-name> <remote-url>`) and the extension-fragment
+# loop below passed that mangled argv to fragments instead of git's
+# original `<remote-name> <remote-url>`. The subshell scopes the rewrite
+# so fragments see git's argv unchanged.
+#
+# The pre-push stdin carries one line per refspec; the subshell inherits
+# stdin unchanged. $@ on entry carries git's <remote-name> <remote-url>;
+# the subshell sees those as its initial $@, appends them inside each
+# `set --` arm, and the parent's $@ is preserved.
 
-if [ -x "${REA_ROOT}/node_modules/.bin/rea" ]; then
-  set -- "${REA_ROOT}/node_modules/.bin/rea" hook push-gate "$@"
-elif [ -f "${REA_ROOT}/dist/cli/index.js" ] && [ -f "${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "${REA_ROOT}/package.json" 2>/dev/null; then
-  # rea's own repo (dogfood) — the package is not installed under
-  # node_modules here because we ARE the package. The built CLI
-  # entry point lives at dist/cli/index.js; node runs it directly.
-  # Gate this branch on `package.json` declaring `@bookedsolid/rea` so a
-  # consumer repo that happens to ship its own `dist/cli/index.js` does
-  # not get this hook executing the consumer's unrelated build.
-  set -- node "${REA_ROOT}/dist/cli/index.js" hook push-gate "$@"
-elif command -v rea >/dev/null 2>&1; then
-  set -- rea hook push-gate "$@"
-elif command -v npx >/dev/null 2>&1; then
-  # Last resort: npx will resolve the package from npm or the cache.
-  # Pass `--no-install` so a rare cache-cold machine surfaces a clear
-  # error instead of silently downloading at push time.
-  set -- npx --no-install @bookedsolid/rea hook push-gate "$@"
+if (
+  if [ -x "${REA_ROOT}/node_modules/.bin/rea" ]; then
+    set -- "${REA_ROOT}/node_modules/.bin/rea" hook push-gate "$@"
+  elif [ -f "${REA_ROOT}/dist/cli/index.js" ] && [ -f "${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "${REA_ROOT}/package.json" 2>/dev/null; then
+    # rea's own repo (dogfood) — the package is not installed under
+    # node_modules here because we ARE the package. The built CLI
+    # entry point lives at dist/cli/index.js; node runs it directly.
+    # Gate this branch on `package.json` declaring `@bookedsolid/rea` so a
+    # consumer repo that happens to ship its own `dist/cli/index.js` does
+    # not get this hook executing the consumer's unrelated build.
+    set -- node "${REA_ROOT}/dist/cli/index.js" hook push-gate "$@"
+  elif command -v rea >/dev/null 2>&1; then
+    set -- rea hook push-gate "$@"
+  elif command -v npx >/dev/null 2>&1; then
+    # Last resort: npx will resolve the package from npm or the cache.
+    # Pass `--no-install` so a rare cache-cold machine surfaces a clear
+    # error instead of silently downloading at push time.
+    set -- npx --no-install @bookedsolid/rea hook push-gate "$@"
+  else
+    printf 'rea: cannot locate the rea CLI. Install locally (`pnpm add -D @bookedsolid/rea`) or globally (`npm i -g @bookedsolid/rea`).\n' >&2
+    exit 2
+  fi
+  exec "$@"
+); then
+  rea_status=0
 else
-  printf 'rea: cannot locate the rea CLI. Install locally (`pnpm add -D @bookedsolid/rea`) or globally (`npm i -g @bookedsolid/rea`).\n' >&2
-  exit 2
+  rea_status=$?
 fi
-
-# Run the rea push-gate FIRST. We capture its exit and explicitly propagate
-# instead of `exec`-ing — extension fragments must only run after rea's own
-# governance work succeeds. The fragments are user code; surfacing them
-# AFTER rea's body (HALT check, Codex review, audit write) preserves the
-# governance contract while letting consumers chain their own checks (e.g.
-# commitlint, branch-policy linters) without losing rea coverage.
-"$@"
-rea_status=$?
 if [ "$rea_status" -ne 0 ]; then
   exit "$rea_status"
 fi

package/dist/cli/doctor.js

@@ -374,14 +374,30 @@ function checkPrePushHook(state) {
     if (state.activeForeign) {
         // Executable file exists at the active path but neither carries a rea
         // marker nor invokes `rea hook push-gate` — the push-gate is silently
-        // bypassed. Always a hard fail.
+        // bypassed. Always a hard fail. When the foreign hook references a
+        // recognizable prior tool (commitlint, lint-staged, gitleaks, act-CI,
+        // …), surface the .d/ migration path explicitly so consumers know
+        // exactly how to keep their existing chain without losing rea coverage
+        // or having `rea upgrade` clobber them again.
+        const hints = state.activePath !== null
+            ? detectPriorToolHints(state.activePath)
+            : [];
+        let detail = `active pre-push at ${state.activePath} is present and executable but does NOT ` +
+            'invoke `rea hook push-gate` — the 0.11.0 push-gate is silently bypassed. ' +
+            'Either add `exec rea hook push-gate "$@"` to the existing hook, or ' +
+            'remove it and re-run `rea init` to install the fallback.';
+        if (hints.length > 0) {
+            detail +=
+                `\n      Detected prior tooling in the foreign hook: ${hints.join(', ')}. ` +
+                    'Recommended migration (rea 0.13.0+): move each chained command to ' +
+                    '`.husky/pre-push.d/<NN>-<name>` as a separate executable file; rea then ' +
+                    'runs them in lex order AFTER the push-gate, surviving `rea upgrade` ' +
+                    'unchanged. See `MIGRATING.md` for a worked example.';
+        }
         return {
             label: 'pre-push hook installed',
             status: 'fail',
-            detail: `active pre-push at ${state.activePath} is present and executable but does NOT ` +
-                'invoke `rea hook push-gate` — the 0.11.0 push-gate is silently bypassed. ' +
-                'Either add `exec rea hook push-gate "$@"` to the existing hook, or ' +
-                'remove it and re-run `rea init` to install the fallback.',
+            detail,
         };
     }
     const present = state.candidates
@@ -403,6 +419,47 @@ function checkPrePushHook(state) {
             'Run `rea init` to install the fallback.',
     };
 }
+/**
+ * Best-effort scan of a foreign hook body for references to recognizable
+ * consumer tooling. Each match returns a short label so doctor can render
+ * a precise migration recommendation without dumping the raw hook body.
+ *
+ * Patterns are intentionally narrow: a substring match in a non-comment line
+ * referencing a tool's CLI binary or a well-known wrapper. False positives
+ * here are cosmetic (extra hint) — the hard-fail decision still drives the
+ * doctor verdict.
+ *
+ * Read errors are swallowed (return []). Doctor's foreign-hook message is
+ * still useful without hints.
+ */
+function detectPriorToolHints(hookPath) {
+    let body;
+    try {
+        body = fs.readFileSync(hookPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const lines = body.split(/\r?\n/);
+    const found = new Set();
+    for (const raw of lines) {
+        if (/^\s*#/.test(raw))
+            continue; // skip comments
+        if (/\bcommitlint\b/.test(raw))
+            found.add('commitlint');
+        if (/\blint-staged\b/.test(raw))
+            found.add('lint-staged');
+        if (/\bgitleaks\b/.test(raw))
+            found.add('gitleaks');
+        if (/\bact[-_]ci\b/i.test(raw) || /\bact-CI\b/.test(raw))
+            found.add('act-CI');
+        if (/\bhusky\.sh\b/.test(raw))
+            found.add('legacy husky 4-8 wrapper');
+        if (/\bnpx\s+--no-install\s+commitlint/.test(raw))
+            found.add('commitlint');
+    }
+    return Array.from(found).sort();
+}
 /**
  * Detect and list extension-hook fragments under `.husky/commit-msg.d/` and
  * `.husky/pre-push.d/`. Informational only — fragments are an opt-in feature

package/dist/cli/install/pre-push.js

@@ -148,40 +148,47 @@ fi
 # splitting; \`/Users/jane/My Projects/repo\` produced four argv tokens
 # instead of two). The \`set --\` form below preserves spaces verbatim.
 #
-# The pre-push stdin carries one line per refspec; \`exec\` inherits stdin
-# unchanged. \$@ on entry carries git's <remote-name> <remote-url>; we
-# preserve those by appending "\$@" inside each \`set --\` arm.
+# 0.13.2 fix: the dispatch + invocation runs inside a SUBSHELL so the
+# \`set --\` rewrite does NOT bleed into the parent's \$@. Before 0.13.2,
+# the parent's \$@ ended up as the rea-CLI argv (\`node /path/dist/cli/index.js
+# hook push-gate <remote-name> <remote-url>\`) and the extension-fragment
+# loop below passed that mangled argv to fragments instead of git's
+# original \`<remote-name> <remote-url>\`. The subshell scopes the rewrite
+# so fragments see git's argv unchanged.
+#
+# The pre-push stdin carries one line per refspec; the subshell inherits
+# stdin unchanged. \$@ on entry carries git's <remote-name> <remote-url>;
+# the subshell sees those as its initial \$@, appends them inside each
+# \`set --\` arm, and the parent's \$@ is preserved.
 
-if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
-  set -- "\${REA_ROOT}/node_modules/.bin/rea" hook push-gate "\$@"
-elif [ -f "\${REA_ROOT}/dist/cli/index.js" ] && [ -f "\${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "\${REA_ROOT}/package.json" 2>/dev/null; then
-  # rea's own repo (dogfood) — the package is not installed under
-  # node_modules here because we ARE the package. The built CLI
-  # entry point lives at dist/cli/index.js; node runs it directly.
-  # Gate this branch on \`package.json\` declaring \`@bookedsolid/rea\` so a
-  # consumer repo that happens to ship its own \`dist/cli/index.js\` does
-  # not get this hook executing the consumer's unrelated build.
-  set -- node "\${REA_ROOT}/dist/cli/index.js" hook push-gate "\$@"
-elif command -v rea >/dev/null 2>&1; then
-  set -- rea hook push-gate "\$@"
-elif command -v npx >/dev/null 2>&1; then
-  # Last resort: npx will resolve the package from npm or the cache.
-  # Pass \`--no-install\` so a rare cache-cold machine surfaces a clear
-  # error instead of silently downloading at push time.
-  set -- npx --no-install @bookedsolid/rea hook push-gate "\$@"
+if (
+  if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
+    set -- "\${REA_ROOT}/node_modules/.bin/rea" hook push-gate "\$@"
+  elif [ -f "\${REA_ROOT}/dist/cli/index.js" ] && [ -f "\${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "\${REA_ROOT}/package.json" 2>/dev/null; then
+    # rea's own repo (dogfood) — the package is not installed under
+    # node_modules here because we ARE the package. The built CLI
+    # entry point lives at dist/cli/index.js; node runs it directly.
+    # Gate this branch on \`package.json\` declaring \`@bookedsolid/rea\` so a
+    # consumer repo that happens to ship its own \`dist/cli/index.js\` does
+    # not get this hook executing the consumer's unrelated build.
+    set -- node "\${REA_ROOT}/dist/cli/index.js" hook push-gate "\$@"
+  elif command -v rea >/dev/null 2>&1; then
+    set -- rea hook push-gate "\$@"
+  elif command -v npx >/dev/null 2>&1; then
+    # Last resort: npx will resolve the package from npm or the cache.
+    # Pass \`--no-install\` so a rare cache-cold machine surfaces a clear
+    # error instead of silently downloading at push time.
+    set -- npx --no-install @bookedsolid/rea hook push-gate "\$@"
+  else
+    printf 'rea: cannot locate the rea CLI. Install locally (\`pnpm add -D @bookedsolid/rea\`) or globally (\`npm i -g @bookedsolid/rea\`).\\n' >&2
+    exit 2
+  fi
+  exec "\$@"
+); then
+  rea_status=0
 else
-  printf 'rea: cannot locate the rea CLI. Install locally (\`pnpm add -D @bookedsolid/rea\`) or globally (\`npm i -g @bookedsolid/rea\`).\\n' >&2
-  exit 2
+  rea_status=\$?
 fi
-
-# Run the rea push-gate FIRST. We capture its exit and explicitly propagate
-# instead of \`exec\`-ing — extension fragments must only run after rea's own
-# governance work succeeds. The fragments are user code; surfacing them
-# AFTER rea's body (HALT check, Codex review, audit write) preserves the
-# governance contract while letting consumers chain their own checks (e.g.
-# commitlint, branch-policy linters) without losing rea coverage.
-"\$@"
-rea_status=\$?
 if [ "\$rea_status" -ne 0 ]; then
   exit "\$rea_status"
 fi

package/hooks/settings-protection.sh

@@ -130,6 +130,59 @@ if [[ "$raw_has_traversal" -eq 1 ]] || [[ "$norm_has_traversal" -eq 1 ]]; then
   exit 2
 fi
 
+# Compute lower-cased path early so the §5b allow-list (and §6/§6b matchers
+# below) all reference a single normalized variable.
+LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
+
+# ── 5b. Extension-surface allow-list ──────────────────────────────────────────
+# `.husky/commit-msg.d/*` and `.husky/pre-push.d/*` are the documented
+# consumer extension surface (Fix H / 0.13.0). Consumers — and the agents
+# that govern those consumers — are expected to write here freely so they
+# can layer commitlint, lint-staged, branch-policy, act-CI, etc. without
+# losing rea coverage on `rea upgrade`.
+#
+# The §6 PROTECTED_PATTERNS list below has `.husky/` as a prefix block,
+# which (correctly) keeps `.husky/pre-push`, `.husky/commit-msg`, and
+# the `.husky/_/*` runtime stubs out of agent reach. But the same prefix
+# also caught `.husky/pre-push.d/00-act-ci` and `.husky/commit-msg.d/*`
+# until 0.13.2 — the very directories advertised as the extension
+# surface. This early allow-list closes that contract gap.
+#
+# Anchored on the literal `.d/` segment (not `.d`) so `.husky/pre-push.d.bak/`
+# or `.husky/pre-push.dump` still hit the prefix block. Nested fragments
+# (e.g. `pre-push.d/sub/file`) are allowed so the surface composes naturally.
+#
+# SECURITY: runs AFTER §5a (path-traversal reject), so a clever
+# `.husky/pre-push.d/../pre-push` cannot bypass §6's protection of the
+# package-managed body — §5a kills it before this matcher runs.
+#
+# SECURITY (defense-in-depth): symlinks INSIDE the .d/ surface are
+# refused. A fragment is a short shell script authored in place;
+# consumers do not need symlinks here. Without this check, a sequence
+# like `ln -s ../pre-push .husky/pre-push.d/00-evil; write 00-evil`
+# would be allowed by §5b's path-string match and the downstream
+# Write/Edit tool would follow the symlink, overwriting the
+# package-managed `.husky/pre-push` body that §6 is meant to protect.
+# Costs near-zero (no legitimate use case for symlinked fragments);
+# closes the path-string→symlink bypass completely.
+case "$LOWER_NORM" in
+  .husky/commit-msg.d/*|.husky/pre-push.d/*)
+    if [ -L "$FILE_PATH" ]; then
+      {
+        printf 'SETTINGS PROTECTION: symlink in extension surface refused\n'
+        printf '\n'
+        printf '  File: %s\n' "$SAFE_FILE_PATH"
+        printf '  Rule: .husky/commit-msg.d/* and .husky/pre-push.d/* must be\n'
+        printf '        regular files (a symlink could resolve to a protected\n'
+        printf '        package-managed body and bypass §6 protection).\n'
+      } >&2
+      exit 2
+    fi
+    # Documented extension surface — agents can write here freely.
+    exit 0
+    ;;
+esac
+
 # ── 6. Protected path patterns ────────────────────────────────────────────────
 # §6 runs BEFORE the patch-session allowlist so hook-patch sessions cannot
 # reach .rea/policy.yaml, .rea/HALT, or .claude/settings.json via any glob
@@ -149,7 +202,7 @@ PATCH_SESSION_PATTERNS=(
   '.claude/hooks/'
 )
 
-LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
+# LOWER_NORM was computed in §5b above and is reused here.
 
 # Match $NORMALIZED against PROTECTED_PATTERNS (exact or prefix for patterns
 # ending in '/'). Sets $PROTECTED_MATCH to the matched pattern; exit 0 on hit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",