forge-orkes 0.41.0 → 0.44.0

package/template/.claude/hooks/format-on-save.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Forge — runs the project's formatter after the agent edits a file.
+# PostToolUse hook for Edit|Write|MultiEdit. Always exits 0 — a formatting
+# failure must never block subsequent work.
+#
+# "Most specific project config wins". A formatter only runs when BOTH the tool
+# and the project's config for it are present, so this never fires against repos
+# that haven't opted in.
+
+set -uo pipefail
+
+# jq missing → silently skip. Never block work over formatting.
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+[ -z "$FILE_PATH" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+EXT="${FILE_PATH##*.}"
+EXT_LC=$(printf '%s' "$EXT" | tr '[:upper:]' '[:lower:]')
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+has_file() { [ -f "$REPO_ROOT/$1" ]; }
+has_any()  { for f in "$@"; do has_file "$f" && return 0; done; return 1; }
+pyproject_has() { has_file "pyproject.toml" && grep -q "^\[$1\]" "$REPO_ROOT/pyproject.toml" 2>/dev/null; }
+pkgjson_has_key() { has_file "package.json" && grep -q "\"$1\"" "$REPO_ROOT/package.json" 2>/dev/null; }
+
+run() {
+  printf 'format-on-save: %s\n' "$*" >&2
+  "$@" >/dev/null 2>&1 || true
+}
+
+case "$EXT_LC" in
+  # ── Python ────────────────────────────────────────────────────────────
+  py)
+    if command -v ruff >/dev/null 2>&1 \
+       && ( has_any "ruff.toml" ".ruff.toml" || pyproject_has "tool.ruff" ); then
+      run ruff format "$FILE_PATH"
+      run ruff check --fix "$FILE_PATH"
+    elif command -v black >/dev/null 2>&1 && pyproject_has "tool.black"; then
+      run black --quiet "$FILE_PATH"
+      command -v isort >/dev/null 2>&1 && run isort --quiet "$FILE_PATH"
+    fi
+    ;;
+  # ── PHP / Laravel ─────────────────────────────────────────────────────
+  php)
+    if [ -x "$REPO_ROOT/vendor/bin/pint" ]; then
+      run "$REPO_ROOT/vendor/bin/pint" "$FILE_PATH"
+    elif command -v php-cs-fixer >/dev/null 2>&1 && has_any ".php-cs-fixer.php" ".php-cs-fixer.dist.php"; then
+      run php-cs-fixer fix "$FILE_PATH"
+    fi
+    ;;
+  # ── JS / TS / Vue / CSS / HTML / JSON / MD / YAML ─────────────────────
+  js|jsx|ts|tsx|vue|mjs|cjs|css|scss|sass|less|html|json|jsonc|md|mdx|yml|yaml)
+    if has_any "biome.json" "biome.jsonc" && [ -x "$REPO_ROOT/node_modules/.bin/biome" ]; then
+      run "$REPO_ROOT/node_modules/.bin/biome" format --write "$FILE_PATH"
+      run "$REPO_ROOT/node_modules/.bin/biome" check --write "$FILE_PATH"
+    else
+      if [ -x "$REPO_ROOT/node_modules/.bin/prettier" ] \
+         && ( has_any ".prettierrc" ".prettierrc.json" ".prettierrc.js" ".prettierrc.cjs" ".prettierrc.mjs" ".prettierrc.yaml" ".prettierrc.yml" "prettier.config.js" "prettier.config.cjs" "prettier.config.mjs" \
+              || pkgjson_has_key "prettier" ); then
+        run "$REPO_ROOT/node_modules/.bin/prettier" --write --log-level=silent "$FILE_PATH"
+      fi
+      case "$EXT_LC" in
+        js|jsx|ts|tsx|vue|mjs|cjs)
+          if [ -x "$REPO_ROOT/node_modules/.bin/eslint" ] \
+             && ( has_any ".eslintrc" ".eslintrc.js" ".eslintrc.cjs" ".eslintrc.json" ".eslintrc.yml" ".eslintrc.yaml" "eslint.config.js" "eslint.config.mjs" "eslint.config.cjs" "eslint.config.ts" \
+                  || pkgjson_has_key "eslintConfig" ); then
+            run "$REPO_ROOT/node_modules/.bin/eslint" --fix "$FILE_PATH"
+          fi
+          ;;
+      esac
+    fi
+    ;;
+  # ── Rust ──────────────────────────────────────────────────────────────
+  rs)
+    command -v rustfmt >/dev/null 2>&1 && run rustfmt "$FILE_PATH"
+    ;;
+  # ── Go ────────────────────────────────────────────────────────────────
+  go)
+    if command -v goimports >/dev/null 2>&1; then
+      run goimports -w "$FILE_PATH"
+    elif command -v gofmt >/dev/null 2>&1; then
+      run gofmt -w "$FILE_PATH"
+    fi
+    ;;
+  # ── Shell ─────────────────────────────────────────────────────────────
+  sh|bash)
+    command -v shfmt >/dev/null 2>&1 && run shfmt -w "$FILE_PATH"
+    ;;
+esac
+
+exit 0

package/template/.claude/hooks/protect-files.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — blocks edits to sensitive or generated files.
+# PreToolUse hook for Edit|Write. Exit 2 = block. Exit 0 = allow.
+
+set -uo pipefail
+
+emit() {
+  # $1 = decision (deny|ask) ; $2 = reason
+  local decision="$1"
+  local reason="${2//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"%s","permissionDecisionReason":"%s"}}\n' "$decision" "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit deny "jq is required for file protection hooks but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+[ -z "$FILE_PATH" ] && exit 0
+
+BASENAME=$(basename -- "$FILE_PATH")
+BASENAME_LC=$(printf '%s' "$BASENAME" | tr '[:upper:]' '[:lower:]')
+PATH_LC=$(printf '%s' "$FILE_PATH" | tr '[:upper:]' '[:lower:]')
+
+# Allowlist: template/example env files are meant to be checked in and edited.
+case "$BASENAME_LC" in
+  .env.example|.env.sample|.env.dist|.env.template)
+    exit 0
+    ;;
+esac
+
+# Protected basename patterns (matched case-insensitively).
+PROTECTED_PATTERNS=(
+  ".env"
+  ".env.*"
+  "*.pem"
+  "*.key"
+  "*.crt"
+  "*.p12"
+  "*.pfx"
+  "id_rsa"
+  "id_ed25519"
+  "credentials.json"
+  ".npmrc"
+  ".pypirc"
+  ".composer-auth.json"
+  "auth.json"
+  # Lock files — update through the package manager, never by hand.
+  "package-lock.json"
+  "yarn.lock"
+  "pnpm-lock.yaml"
+  "composer.lock"
+  "uv.lock"
+  "poetry.lock"
+  "Gemfile.lock"
+  "Cargo.lock"
+  "go.sum"
+  # Generated / minified
+  "*.gen.ts"
+  "*.generated.*"
+  "*.min.js"
+  "*.min.css"
+)
+
+shopt -s nocasematch 2>/dev/null || true
+for pattern in "${PROTECTED_PATTERNS[@]}"; do
+  case "$BASENAME_LC" in
+    $pattern)
+      emit deny "Protected file: $BASENAME matches pattern '$pattern'. Edit via the package manager or the appropriate secret store."
+      ;;
+  esac
+done
+
+# Sensitive directories (lower-cased path for case-insensitive matches).
+case "$PATH_LC" in
+  .git/*|*/.git/*)
+    emit deny "Cannot edit files inside .git/" ;;
+  secrets/*|*/secrets/*)
+    emit deny "Cannot edit files inside secrets/" ;;
+  .secrets/*|*/.secrets/*)
+    emit deny "Cannot edit files inside .secrets/" ;;
+  .env|.env.*|*/.env|*/.env.*)
+    emit deny "Cannot edit .env files" ;;
+esac
+
+# Framework-authoring files. In a normal project these are re-synced via
+# /upgrading, never hand-edited — so we block hooks and prompt on settings.
+# FORGE_ALLOW_HOOK_EDITS=1 lifts both, set only in the Forge framework repo
+# itself (where authoring hooks and settings IS the work).
+if [ -z "${FORGE_ALLOW_HOOK_EDITS:-}" ]; then
+  case "$PATH_LC" in
+    .claude/hooks/*|*/.claude/hooks/*)
+      emit deny "Cannot edit hook scripts — these enforce safety boundaries. Update them in the framework repo and re-sync (/upgrading)." ;;
+    .claude/settings.json|*/.claude/settings.json|.claude/settings.local.json|*/.claude/settings.local.json)
+      emit ask "Editing settings.json — this controls permissions and hooks. Confirm this change." ;;
+  esac
+fi
+
+exit 0

package/template/.claude/hooks/scan-secrets.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — scans file content for accidental secrets before writing.
+# PreToolUse hook for Edit|Write. Exit 2 = block (decision "ask" so the user can
+# override for genuine test fixtures). Exit 0 = allow.
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit_deny "jq is required for secret scanning but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+if [ "$TOOL_NAME" = "Write" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')
+elif [ "$TOOL_NAME" = "Edit" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty')
+else
+  exit 0
+fi
+
+[ -z "$CONTENT" ] && exit 0
+
+MATCHES=""
+
+# AWS Access Key IDs
+if echo "$CONTENT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
+  MATCHES="$MATCHES AWS access key (AKIA...);"
+fi
+# AWS Secret Access Keys (40 chars base64 after a key assignment)
+if echo "$CONTENT" | grep -qiE '(aws_secret_access_key|secret_key)[[:space:]]*[=:][[:space:]]*["\x27]?[A-Za-z0-9/+=]{40}'; then
+  MATCHES="$MATCHES AWS secret key;"
+fi
+# GitHub tokens (PAT, OAuth, App)
+if echo "$CONTENT" | grep -qE '(ghp_|gho_|ghs_|ghr_|github_pat_)[a-zA-Z0-9_]{20,}'; then
+  MATCHES="$MATCHES GitHub token;"
+fi
+# OpenAI / Anthropic / Stripe style keys (sk-...)
+if echo "$CONTENT" | grep -qE 'sk-[a-zA-Z0-9]{20,}'; then
+  MATCHES="$MATCHES API key (sk-...);"
+fi
+# Anthropic-specific keys
+if echo "$CONTENT" | grep -qE 'sk-ant-[a-zA-Z0-9_-]{20,}'; then
+  MATCHES="$MATCHES Anthropic API key;"
+fi
+# Slack tokens
+if echo "$CONTENT" | grep -qE 'xox[bpras]-[0-9a-zA-Z-]{10,}'; then
+  MATCHES="$MATCHES Slack token;"
+fi
+# Google API keys
+if echo "$CONTENT" | grep -qE 'AIza[0-9A-Za-z_-]{35}'; then
+  MATCHES="$MATCHES Google API key;"
+fi
+# Private key blocks
+if echo "$CONTENT" | grep -qE -- '-----BEGIN[[:space:]]+(RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----'; then
+  MATCHES="$MATCHES private key block;"
+fi
+# Connection strings with embedded credentials
+if echo "$CONTENT" | grep -qE '(mongodb|postgres|postgresql|mysql|redis|amqp|smtp|mssql)(\+[a-z]+)?://[^:[:space:]]+:[^@[:space:]]+@'; then
+  MATCHES="$MATCHES connection string with credentials;"
+fi
+# Laravel APP_KEY with a real base64 value (not a placeholder)
+if echo "$CONTENT" | grep -qE 'APP_KEY[[:space:]]*=[[:space:]]*base64:[A-Za-z0-9+/=]{40,}'; then
+  MATCHES="$MATCHES Laravel APP_KEY;"
+fi
+# Generic password/secret/token assignments with literal string values.
+# Excludes env var references (process.env, os.environ, getenv, ${...}, ENV[, env(, config()).
+if echo "$CONTENT" | grep -qiE '(password|secret|token|api_key|apikey|api_secret)[[:space:]]*[=:][[:space:]]*["\x27][^"\x27]{8,}["\x27]' && \
+   ! echo "$CONTENT" | grep -qiE '(password|secret|token|api_key|apikey|api_secret)[[:space:]]*[=:][[:space:]]*["\x27]?(process\.env|os\.environ|getenv|\$\{|ENV\[|env\(|config\()'; then
+  MATCHES="$MATCHES hardcoded credential;"
+fi
+
+if [ -n "$MATCHES" ]; then
+  # "ask" not "deny" — warn but let the user override (could be a fixture).
+  REASON="Possible secret detected in content:$MATCHES Review carefully before allowing."
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+  exit 2
+fi
+
+exit 0

package/template/.claude/hooks/tests/README.md

@@ -0,0 +1,76 @@
+# Hook tests
+
+Data-driven test harness for the Claude Code hooks in `.claude/hooks/`. Cases live in JSON files, the driver pipes each input to the hook and checks the exit code and stdout.
+
+## Running
+
+```bash
+# All hooks
+.claude/hooks/tests/run.sh
+
+# One hook
+.claude/hooks/tests/run.sh protect-files
+.claude/hooks/tests/run.sh block-dangerous-commands
+.claude/hooks/tests/run.sh warn-large-files
+```
+
+Requires `jq`. Install with `brew install jq` (macOS) or `apt install jq` (Linux).
+
+## Layout
+
+```
+tests/
+  run.sh                              # driver
+  cases/
+    <hook-name>.cases.json            # test cases for .claude/hooks/<hook-name>.sh
+```
+
+The driver matches cases to hook scripts by filename: `cases/protect-files.cases.json` runs against `.claude/hooks/protect-files.sh`. If the hook script is missing or not executable, the test file is skipped.
+
+## Case schema
+
+Each case file is a JSON array of objects:
+
+```json
+{
+  "name": "denies editing .env at repo root",
+  "input": { "tool_name": "Edit", "tool_input": { "file_path": ".env" } },
+  "expect_exit": 2,
+  "expect_stdout_contains": "\"permissionDecision\":\"deny\"",
+  "expect_stdout_not_contains": "allow"
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | Human-readable test label |
+| `input` | yes | JSON piped to the hook on stdin — matches Claude Code's hook input format |
+| `expect_exit` | no (default 0) | Expected process exit code. `2` = permission denied, `0` = allowed |
+| `expect_stdout_contains` | no | Substring that must appear in stdout (combined with stderr) |
+| `expect_stdout_not_contains` | no | Substring that must NOT appear |
+
+The driver combines stdout and stderr, so a hook that writes errors to stderr is still matched against `expect_stdout_contains`.
+
+## Adding a new case
+
+1. Pick the right case file (`cases/<hook>.cases.json`) — or create one if you are testing a new hook.
+2. Append a new object to the array. Keep the name as a sentence that reads like a spec: `"denies rm -rf $HOME"`, `"allows artisan migrate"`.
+3. Run the hook-specific filter to verify: `.claude/hooks/tests/run.sh <hook>`.
+
+## Adding a new hook
+
+1. Write the hook at `.claude/hooks/<hook-name>.sh` and `chmod +x` it.
+2. Create `cases/<hook-name>.cases.json` with at least one deny case, one allow case, and one no-op case (missing input field).
+3. Run `.claude/hooks/tests/run.sh <hook-name>`.
+
+## What good coverage looks like
+
+For a `deny`/`allow` style hook, every case file should include:
+
+- At least one **deny** per distinct rule the hook implements (so the hook script cannot be trivially gutted without turning tests red).
+- At least one **allow** that sits right next to a deny path (e.g. `git push origin main` denies, `git push origin feature/foo` allows) — proves the pattern is specific, not blanket.
+- One **no-op** case where the hook input does not match the shape the hook expects (e.g. `file_path` missing, `command` empty) — proves the hook fails open for irrelevant events.
+
+## Why this lives here
+
+Hooks run on every tool call the agent makes. If they regress silently, either the agent starts bypassing real protections, or innocent edits start getting blocked and the hooks get disabled in frustration. A small test harness catches both before they land.