create-merlin-brain 3.11.0 → 3.12.0

package/files/hook-templates/auto-test.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# Hook Template: auto-test.sh
+# Event: PostToolUse (Write, Edit)
+#
+# Automatically runs the test suite (or targeted test file) after code changes.
+# Detects the test framework and runs only tests related to the changed file.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/auto-test.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "PostToolUse": [
+#         {
+#           "matcher": "Write|Edit",
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/auto-test.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# REQUIREMENTS: A test runner (jest, vitest, pytest, go test) must be available.
+# BEHAVIOR: Advisory only — runs tests and echoes results to stderr. Never blocks.
+# NOTE: Keep test suites fast. Slow suites make this hook annoying.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Read tool input from stdin
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# Extract file path
+file_path=""
+if command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+fi
+
+[ -z "$file_path" ] || [ ! -f "$file_path" ] && { echo '{}'; exit 0; }
+
+# Skip test files themselves, node_modules, configs
+case "$file_path" in
+  *.test.*|*.spec.*|*__tests__*|*node_modules*|*dist/*|*build/*)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Only run for source code files
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.py|*.go|*.rb|*.java)
+    ;;
+  *)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+echo "auto-test: running tests for $file_path" >&2
+
+# Detect and run test framework
+if [ -f "package.json" ]; then
+  # Jest
+  if grep -q '"jest"' package.json 2>/dev/null || [ -f "jest.config.js" ] || [ -f "jest.config.ts" ]; then
+    RUNNER="node_modules/.bin/jest"
+    [ ! -f "$RUNNER" ] && RUNNER="jest"
+    if command -v "$RUNNER" >/dev/null 2>&1 || [ -f "$RUNNER" ]; then
+      # Try to run related tests only
+      $RUNNER --passWithNoTests --findRelatedTests "$file_path" --no-coverage 2>&1 | tail -5 >&2 || true
+      echo '{}'
+      exit 0
+    fi
+  fi
+
+  # Vitest
+  if grep -q '"vitest"' package.json 2>/dev/null || [ -f "vitest.config.ts" ] || [ -f "vitest.config.js" ]; then
+    RUNNER="node_modules/.bin/vitest"
+    [ ! -f "$RUNNER" ] && RUNNER="vitest"
+    if command -v "$RUNNER" >/dev/null 2>&1 || [ -f "$RUNNER" ]; then
+      $RUNNER run --reporter=verbose 2>&1 | tail -10 >&2 || true
+      echo '{}'
+      exit 0
+    fi
+  fi
+fi
+
+# Python: pytest
+if [ "${file_path##*.}" = "py" ] && command -v pytest >/dev/null 2>&1; then
+  # Derive test file path convention: src/foo.py -> tests/test_foo.py
+  base=$(basename "$file_path" .py)
+  test_file="tests/test_${base}.py"
+  if [ -f "$test_file" ]; then
+    pytest "$test_file" -q 2>&1 | tail -5 >&2 || true
+  else
+    pytest -q --co -q 2>&1 | tail -5 >&2 || true
+  fi
+  echo '{}'
+  exit 0
+fi
+
+# Go: go test
+if [ "${file_path##*.}" = "go" ] && command -v go >/dev/null 2>&1; then
+  pkg=$(dirname "$file_path")
+  go test "./${pkg}/..." 2>&1 | tail -5 >&2 || true
+  echo '{}'
+  exit 0
+fi
+
+echo "auto-test: no test runner detected for $file_path" >&2
+echo '{}'
+exit 0

package/files/hook-templates/branch-protection.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+#
+# Hook Template: branch-protection.sh
+# Event: PreToolUse (Bash)
+#
+# Prevents Claude from directly committing or pushing to protected branches
+# (main, master, production, release/*). Forces work onto feature branches.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/branch-protection.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "PreToolUse": [
+#         {
+#           "matcher": "Bash",
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/branch-protection.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# BEHAVIOR: Blocks git commit and git push when on a protected branch.
+#           Exit 2 + JSON decision:block to prevent the command.
+#
+# CUSTOMIZE: Edit PROTECTED_BRANCHES below to match your workflow.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Protected branch patterns (regex)
+PROTECTED_BRANCHES="^(main|master|production|staging|release/.*)$"
+
+# Read tool input from stdin
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# Extract the bash command being run
+command_str=""
+if command -v jq >/dev/null 2>&1; then
+  command_str=$(echo "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+fi
+
+[ -z "$command_str" ] && { echo '{}'; exit 0; }
+
+# Only check git commit and git push commands
+if ! echo "$command_str" | grep -qE 'git\s+(commit|push)'; then
+  echo '{}'
+  exit 0
+fi
+
+# Only run if we're in a git repo
+git rev-parse --git-dir >/dev/null 2>&1 || { echo '{}'; exit 0; }
+
+# Get current branch
+current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+
+[ -z "$current_branch" ] && { echo '{}'; exit 0; }
+
+# Check if current branch is protected
+if echo "$current_branch" | grep -qE "$PROTECTED_BRANCHES"; then
+  printf '{"decision":"block","reason":"Branch protection: direct commits to '\''%s'\'' are not allowed. Create a feature branch first: git checkout -b feat/your-change"}\n' "$current_branch"
+  exit 2
+fi
+
+echo '{}'
+exit 0

package/files/hook-templates/changelog-reminder.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# Hook Template: changelog-reminder.sh
+# Event: Stop
+#
+# At the end of a session, checks if source code was changed but CHANGELOG.md
+# was not updated. Injects a reminder as feedback if so.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/changelog-reminder.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "Stop": [
+#         {
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/changelog-reminder.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# BEHAVIOR: Advisory only. Reminds to update CHANGELOG.md when code changed.
+#           Checks git diff for source code changes vs changelog changes.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Only run if we're in a git repo
+git rev-parse --git-dir >/dev/null 2>&1 || { echo '{}'; exit 0; }
+
+# Check if CHANGELOG.md (or CHANGELOG) exists at all
+CHANGELOG=""
+for candidate in CHANGELOG.md CHANGELOG.rst CHANGELOG.txt CHANGES.md; do
+  if [ -f "$candidate" ]; then
+    CHANGELOG="$candidate"
+    break
+  fi
+done
+
+[ -z "$CHANGELOG" ] && { echo '{}'; exit 0; }
+
+# Get changed files since last commit (staged + unstaged)
+changed_files=$(git diff --name-only HEAD 2>/dev/null || true)
+staged_files=$(git diff --cached --name-only 2>/dev/null || true)
+all_changed="${changed_files}${staged_files}"
+
+[ -z "$all_changed" ] && { echo '{}'; exit 0; }
+
+# Check if any source code files changed
+source_changed=false
+while IFS= read -r file; do
+  case "$file" in
+    *.js|*.jsx|*.ts|*.tsx|*.mjs|*.py|*.go|*.java|*.rb|*.rs|*.swift|*.c|*.cpp|*.h)
+      source_changed=true
+      break
+      ;;
+  esac
+done <<< "$all_changed"
+
+"$source_changed" || { echo '{}'; exit 0; }
+
+# Check if CHANGELOG was also updated
+changelog_updated=false
+if echo "$all_changed" | grep -q "$CHANGELOG"; then
+  changelog_updated=true
+fi
+
+if ! "$changelog_updated"; then
+  echo "REMINDER: Source code was changed but ${CHANGELOG} was not updated. Consider adding an entry describing what changed." >&2
+  echo '{}'
+  exit 2
+fi
+
+echo '{}'
+exit 0

package/files/hook-templates/complexity-check.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+#
+# Hook Template: complexity-check.sh
+# Event: PostToolUse (Write, Edit)
+#
+# Warns when a file has too many functions — a proxy for high cognitive complexity.
+# Encourages splitting large files into smaller, focused modules.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/complexity-check.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "PostToolUse": [
+#         {
+#           "matcher": "Write|Edit",
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/complexity-check.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# BEHAVIOR: Advisory only. Warns via exit 2 feedback when function count is high.
+# CUSTOMIZE: Adjust MAX_FUNCTIONS and MAX_LINES below.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+MAX_FUNCTIONS=15   # Warn if file has more than this many functions
+MAX_LINES=400      # Warn if file exceeds this many lines
+
+# Read tool input from stdin
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# Extract file path
+file_path=""
+if command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+fi
+
+[ -z "$file_path" ] || [ ! -f "$file_path" ] && { echo '{}'; exit 0; }
+
+# Only check code files
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.py|*.go|*.java|*.rb|*.rs|*.swift)
+    ;;
+  *)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Skip generated/vendor files
+case "$file_path" in
+  *node_modules*|*dist/*|*build/*|*.min.js|*vendor/*)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Count lines
+line_count=$(wc -l < "$file_path" 2>/dev/null | tr -d ' ')
+
+# Count function definitions (language-aware patterns)
+func_count=0
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs)
+    func_count=$(grep -cE '^\s*(export\s+)?(async\s+)?function\s+\w+|^\s*(const|let|var)\s+\w+\s*=\s*(async\s+)?\(' "$file_path" 2>/dev/null || echo 0)
+    ;;
+  *.py)
+    func_count=$(grep -cE '^\s*def\s+\w+' "$file_path" 2>/dev/null || echo 0)
+    ;;
+  *.go)
+    func_count=$(grep -cE '^func\s+' "$file_path" 2>/dev/null || echo 0)
+    ;;
+  *.java)
+    func_count=$(grep -cE '^\s*(public|private|protected|static|final)\s+\w.*\(.*\)\s*\{' "$file_path" 2>/dev/null || echo 0)
+    ;;
+  *.rb)
+    func_count=$(grep -cE '^\s*def\s+' "$file_path" 2>/dev/null || echo 0)
+    ;;
+esac
+
+# Ensure numeric
+func_count=$(echo "$func_count" | tr -d ' ' | grep -E '^[0-9]+$' || echo 0)
+line_count=$(echo "$line_count" | tr -d ' ' | grep -E '^[0-9]+$' || echo 0)
+
+warn_parts=()
+
+if [ "$func_count" -gt "$MAX_FUNCTIONS" ] 2>/dev/null; then
+  warn_parts+=("${func_count} functions (threshold: ${MAX_FUNCTIONS})")
+fi
+
+if [ "$line_count" -gt "$MAX_LINES" ] 2>/dev/null; then
+  warn_parts+=("${line_count} lines (threshold: ${MAX_LINES})")
+fi
+
+if [ "${#warn_parts[@]}" -gt 0 ]; then
+  msg="COMPLEXITY WARNING: ${file_path} has $(IFS=', '; echo "${warn_parts[*]}"). Consider splitting into smaller modules."
+  echo "$msg" >&2
+  echo '{}'
+  exit 2
+fi
+
+echo '{}'
+exit 0

package/files/hook-templates/import-audit.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+#
+# Hook Template: import-audit.sh
+# Event: PostToolUse (Write, Edit)
+#
+# Flags potentially unused imports in JavaScript/TypeScript files after edits.
+# Uses a heuristic approach: checks if imported names appear elsewhere in the file.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/import-audit.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "PostToolUse": [
+#         {
+#           "matcher": "Write|Edit",
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/import-audit.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# BEHAVIOR: Advisory only. Warns about likely unused imports via stderr + exit 2.
+# NOTE: This is heuristic-based, not AST-based. False positives are possible.
+#       For production use, prefer ESLint's no-unused-vars / unused-imports rules.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Read tool input from stdin
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# Extract file path
+file_path=""
+if command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+fi
+
+[ -z "$file_path" ] || [ ! -f "$file_path" ] && { echo '{}'; exit 0; }
+
+# Only check JS/TS files
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs) ;;
+  *) echo '{}'; exit 0 ;;
+esac
+
+# Skip node_modules and generated files
+case "$file_path" in
+  *node_modules*|*dist/*|*build/*|*.min.js) echo '{}'; exit 0 ;;
+esac
+
+unused=()
+
+# Extract named imports: import { Foo, Bar } from '...'
+while IFS= read -r line; do
+  # Extract the imports section between { }
+  names=$(echo "$line" | grep -oE '\{[^}]+\}' | tr -d '{}' | tr ',' '\n' | sed 's/\s\+as\s\+[^ ]*//' | tr -d ' \t')
+  for name in $names; do
+    [ -z "$name" ] && continue
+    # Count occurrences outside the import line itself
+    count=$(grep -c "$name" "$file_path" 2>/dev/null || echo 0)
+    # Import line counts as 1, so if total <= 1, it's only in the import
+    if [ "$count" -le 1 ] 2>/dev/null; then
+      unused+=("$name")
+    fi
+  done
+done < <(grep -E '^import\s+\{' "$file_path" 2>/dev/null || true)
+
+if [ "${#unused[@]}" -gt 0 ]; then
+  echo "IMPORT AUDIT: ${file_path} may have unused imports: ${unused[*]}" >&2
+  echo "  Verify and remove if unused, or suppress with // eslint-disable-line" >&2
+  echo '{}'
+  exit 2
+fi
+
+echo '{}'
+exit 0

package/files/hook-templates/license-header.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# Hook Template: license-header.sh
+# Event: PostToolUse (Write)
+#
+# Checks that newly created source files have a license header.
+# Only triggers on Write (new file creation), not Edit (modifications).
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/license-header.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "PostToolUse": [
+#         {
+#           "matcher": "Write",
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/license-header.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# CUSTOMIZE: Set LICENSE_KEYWORD below to match the text in your license header.
+#            Default: checks for "Copyright", "License", or "SPDX"
+#
+# BEHAVIOR: Advisory only. Warns when a new file lacks a license header.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Keywords that indicate a license header is present
+LICENSE_KEYWORD="Copyright|License|SPDX|MIT|Apache|GPL|BSD"
+
+# Read tool input from stdin
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# Extract file path and tool name
+file_path=""
+tool_name=""
+if command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+  tool_name=$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)
+fi
+
+[ -z "$file_path" ] || [ ! -f "$file_path" ] && { echo '{}'; exit 0; }
+
+# Only check on Write (new file creation), skip Edit
+[ "${tool_name:-}" = "Edit" ] && { echo '{}'; exit 0; }
+
+# Only check source code files
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.py|*.go|*.java|*.rb|*.rs|*.swift|*.c|*.cpp|*.h)
+    ;;
+  *)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Skip node_modules, dist, generated
+case "$file_path" in
+  *node_modules*|*dist/*|*build/*|*vendor/*|*__generated__*)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Check first 10 lines for license keyword
+first_lines=$(head -10 "$file_path" 2>/dev/null || true)
+
+if ! echo "$first_lines" | grep -qiE "$LICENSE_KEYWORD"; then
+  echo "LICENSE HEADER: ${file_path} is missing a license header. Add a copyright/license comment at the top of the file." >&2
+  echo '{}'
+  exit 2
+fi
+
+echo '{}'
+exit 0

package/files/hook-templates/pr-description.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+#
+# Hook Template: pr-description.sh
+# Event: Stop
+#
+# At the end of a session, generates a draft PR description from the git diff
+# and outputs it to a file. Surfaces a reminder with the file path.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/pr-description.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "Stop": [
+#         {
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/pr-description.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# BEHAVIOR: Advisory only. Writes a draft PR description to .claude/pr-draft.md
+#           and injects a reminder. Does not open PRs — that stays in your control.
+# REQUIRES: git
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Only run if we're in a git repo with changes
+git rev-parse --git-dir >/dev/null 2>&1 || { echo '{}'; exit 0; }
+
+# Check if there are commits ahead of the merge base (comparing to main/master)
+BASE_BRANCH=""
+for candidate in main master develop; do
+  if git show-ref --verify --quiet "refs/heads/${candidate}" 2>/dev/null || \
+     git show-ref --verify --quiet "refs/remotes/origin/${candidate}" 2>/dev/null; then
+    BASE_BRANCH="$candidate"
+    break
+  fi
+done
+
+[ -z "$BASE_BRANCH" ] && { echo '{}'; exit 0; }
+
+# Current branch
+CURRENT_BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+[ -z "$CURRENT_BRANCH" ] && { echo '{}'; exit 0; }
+
+# Skip if already on base branch
+[ "$CURRENT_BRANCH" = "$BASE_BRANCH" ] && { echo '{}'; exit 0; }
+
+# Get commits since diverging from base
+COMMITS=$(git log --oneline "${BASE_BRANCH}..HEAD" 2>/dev/null | head -20)
+[ -z "$COMMITS" ] && { echo '{}'; exit 0; }
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only "${BASE_BRANCH}...HEAD" 2>/dev/null | head -30)
+
+# Get summary stats
+FILES_COUNT=$(echo "$CHANGED_FILES" | grep -c . 2>/dev/null || echo 0)
+COMMIT_COUNT=$(echo "$COMMITS" | grep -c . 2>/dev/null || echo 0)
+INSERTIONS=$(git diff --stat "${BASE_BRANCH}...HEAD" 2>/dev/null | tail -1 | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo 0)
+DELETIONS=$(git diff --stat "${BASE_BRANCH}...HEAD" 2>/dev/null | tail -1 | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo 0)
+
+# Write draft PR description
+DRAFT_FILE=".claude/pr-draft.md"
+mkdir -p ".claude"
+
+cat > "$DRAFT_FILE" << PREOF
+## Summary
+
+<!-- Fill in: what does this PR do and why? -->
+
+### Changes
+$(echo "$COMMITS" | sed 's/^/- /')
+
+### Files Changed (${FILES_COUNT} files, +${INSERTIONS}/-${DELETIONS} lines)
+\`\`\`
+$(echo "$CHANGED_FILES")
+\`\`\`
+
+## Test Plan
+
+- [ ] Unit tests pass
+- [ ] Manual test: <!-- describe -->
+- [ ] No new linting errors
+
+## Notes
+
+<!-- Anything reviewers should know? Breaking changes? Dependencies updated? -->
+
+---
+*Draft generated by Merlin pr-description hook — branch: \`${CURRENT_BRANCH}\`, ${COMMIT_COUNT} commit(s)*
+PREOF
+
+echo "PR DESCRIPTION: Draft written to ${DRAFT_FILE}. Review and edit before opening your PR." >&2
+echo "  Run: gh pr create --body \"\$(cat ${DRAFT_FILE})\"" >&2
+
+echo '{}'
+exit 0