claude-devkit-cli 1.0.0

package/templates/.claude/hooks/sensitive-guard.sh

@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+# sensitive-guard.sh — PreToolUse hook for Claude Code
+#
+# Blocks access to sensitive files: .env, private keys, credentials, tokens.
+# Supports .agentignore for project-specific patterns.
+#
+# Exit codes:
+#   0 — access allowed
+#   2 — access blocked (sensitive file)
+#
+# Environment:
+#   SENSITIVE_GUARD_EXTRA — additional pipe-separated filename patterns to block
+
+set -euo pipefail
+
+# ─── Read hook payload from stdin ───────────────────────────────────
+
+INPUT=$(cat)
+[[ -z "$INPUT" ]] && exit 0
+
+# Check Node.js availability — security hook should warn loudly if disabled
+if ! command -v node &>/dev/null; then
+    echo "WARNING: sensitive-guard disabled — Node.js not found. Sensitive files are NOT protected." >&2
+    exit 0
+fi
+
+# Extract file path and/or command using inline Node.js
+PARSED=$(printf '%s' "$INPUT" | node -e "
+  try {
+    const d = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+    const fp = d.tool_input?.file_path || d.tool_input?.path || '';
+    const cmd = d.tool_input?.command || '';
+    const pat = d.tool_input?.pattern || '';
+    process.stdout.write(fp + '\n' + cmd + '\n' + pat);
+  } catch { process.exit(0); }
+" 2>/dev/null) || exit 0
+
+FILE_PATH=$(printf '%s' "$PARSED" | sed -n '1p')
+COMMAND=$(printf '%s' "$PARSED" | sed -n '2p')
+PATTERN=$(printf '%s' "$PARSED" | sed -n '3p')
+
+# ─── Sensitive filename patterns ────────────────────────────────────
+
+# Returns 0 (true) if the path matches a sensitive pattern
+is_sensitive() {
+    local filepath="$1"
+    local basename
+    basename=$(basename "$filepath" 2>/dev/null) || return 1
+
+    # Exact filenames (basename match)
+    case "$basename" in
+        .env|.env.local|.env.development|.env.production|.env.staging|.env.test)
+            return 0 ;;
+        .npmrc|.pypirc|.netrc)
+            return 0 ;;
+        id_rsa|id_ecdsa|id_ed25519|id_dsa)
+            return 0 ;;
+        serviceAccountKey.json|service-account*.json)
+            return 0 ;;
+        .mcp.json|config.json)
+            # config.json only sensitive inside .docker/ — check full path
+            if [[ "$basename" == "config.json" ]]; then
+                [[ "$filepath" == *".docker/config.json"* ]] && return 0
+            else
+                return 0
+            fi
+            ;;
+    esac
+
+    # Extension patterns
+    case "$basename" in
+        *.pem|*.key|*.p12|*.pfx|*.jks|*.keystore|*.truststore)
+            return 0 ;;
+        *_rsa|*_ecdsa|*_ed25519|*_dsa)
+            return 0 ;;
+    esac
+
+    # Substring patterns (case-insensitive via bash)
+    local lower
+    lower=$(echo "$basename" | tr '[:upper:]' '[:lower:]')
+    case "$lower" in
+        *credential*|*secret*|*private_key*|*privatekey*)
+            return 0 ;;
+        firebase-adminsdk*)
+            return 0 ;;
+    esac
+
+    # .env.* but NOT .env.example or .env.sample or .env.template
+    if [[ "$basename" =~ ^\.env\. ]]; then
+        case "$basename" in
+            .env.example|.env.sample|.env.template) return 1 ;;
+            *) return 0 ;;
+        esac
+    fi
+
+    # Extra patterns from env var
+    if [[ -n "${SENSITIVE_GUARD_EXTRA:-}" ]]; then
+        if printf '%s\n' "$filepath" | grep -qE "$SENSITIVE_GUARD_EXTRA"; then
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+# ─── Check .agentignore ────────────────────────────────────────────
+
+check_agentignore() {
+    local filepath="$1"
+    local ignorefile=""
+
+    # Look for ignore files in project root
+    for candidate in .agentignore .aiignore .cursorignore; do
+        if [[ -f "$candidate" ]]; then
+            ignorefile="$candidate"
+            break
+        fi
+    done
+
+    [[ -z "$ignorefile" ]] && return 1
+
+    # Simple line-by-line match (not full gitignore glob, but covers common cases)
+    local relpath
+    relpath=$(echo "$filepath" | sed "s|^$(pwd)/||") 2>/dev/null || relpath="$filepath"
+
+    while IFS= read -r pattern || [[ -n "$pattern" ]]; do
+        # Skip comments and empty lines
+        [[ -z "$pattern" || "$pattern" == \#* ]] && continue
+        # Simple glob match
+        if [[ "$relpath" == $pattern ]] || [[ "$(basename "$relpath")" == $pattern ]]; then
+            return 0
+        fi
+    done < "$ignorefile"
+
+    return 1
+}
+
+# ─── Check file path access ────────────────────────────────────────
+
+block_with_message() {
+    local filepath="$1"
+    echo "Blocked: '$filepath' is a sensitive file (secrets, keys, or credentials). Access denied to protect sensitive data. Use .env.example for templates instead." >&2
+    exit 2
+}
+
+warn_with_message() {
+    local filepath="$1"
+    echo "Warning: '$filepath' is a sensitive file. If the user approved this access, proceed. Otherwise, ask the user for permission first via AskUserQuestion before reading sensitive files." >&2
+    # Warn only — exit 0 allows the command to proceed
+    # This enables the flow: Block Read → Claude asks user → User approves → Claude uses bash cat
+    exit 0
+}
+
+# ─── Check direct file access (Read/Write/Edit) → BLOCK ────────────
+
+if [[ -n "$FILE_PATH" ]]; then
+    if is_sensitive "$FILE_PATH" || check_agentignore "$FILE_PATH"; then
+        block_with_message "$FILE_PATH"
+    fi
+fi
+
+# ─── Check bash commands → WARN only (allows approved access) ──────
+
+if [[ -n "$COMMAND" ]]; then
+    # Extract .env file references from commands
+    SENSITIVE_IN_CMD=$(printf '%s\n' "$COMMAND" | grep -oE '[\./[:alnum:]_-]*\.env[\.[:alnum:]_-]*' | head -5) || true
+
+    if [[ -n "$SENSITIVE_IN_CMD" ]]; then
+        while IFS= read -r match; do
+            case "$match" in
+                *.example|*.sample|*.template) continue ;;
+            esac
+            if is_sensitive "$match"; then
+                warn_with_message "$match"
+            fi
+        done <<< "$SENSITIVE_IN_CMD"
+    fi
+
+    # Check for key/cert file references in commands → also warn only
+    KEY_IN_CMD=$(printf '%s\n' "$COMMAND" | grep -oE '[[:alnum:]_./-]*\.(pem|key|p12|pfx|jks|keystore)' | head -3) || true
+    if [[ -n "$KEY_IN_CMD" ]]; then
+        while IFS= read -r match; do
+            warn_with_message "$match"
+        done <<< "$KEY_IN_CMD"
+    fi
+
+    # Check for SSH keys, credentials, service accounts in commands
+    SENSITIVE_NAMES=$(printf '%s\n' "$COMMAND" | grep -oiE '(id_rsa|id_ecdsa|id_ed25519|id_dsa|serviceAccountKey\.json|service-account[[:alnum:]_-]*\.json|\.npmrc|\.pypirc|\.netrc)' | head -3) || true
+    if [[ -n "$SENSITIVE_NAMES" ]]; then
+        while IFS= read -r match; do
+            warn_with_message "$match"
+        done <<< "$SENSITIVE_NAMES"
+    fi
+
+    # Check for credential/secret keywords in file arguments
+    CRED_FILES=$(printf '%s\n' "$COMMAND" | grep -oiE '[[:alnum:]_./-]*(credential|secret|private_key|privatekey)[[:alnum:]_./-]*' | head -3) || true
+    if [[ -n "$CRED_FILES" ]]; then
+        while IFS= read -r match; do
+            warn_with_message "$match"
+        done <<< "$CRED_FILES"
+    fi
+fi
+
+# ─── Check Grep pattern for sensitive file paths ───────────────────
+
+if [[ -n "$PATTERN" ]]; then
+    if is_sensitive "$PATTERN"; then
+        block_with_message "$PATTERN"
+    fi
+fi
+
+# ─── All checks passed ─────────────────────────────────────────────
+
+exit 0

package/templates/.claude/settings.json

@@ -0,0 +1,68 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/path-guard.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sensitive-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Write|Edit|MultiEdit|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sensitive-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/comment-guard.js"
+          }
+        ]
+      },
+      {
+        "matcher": "Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/glob-guard.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/file-guard.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/self-review.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/docs/WORKFLOW.md

@@ -0,0 +1,231 @@
+# Development Workflow Reference
+
+> Spec-first development: every change follows SPEC → TEST PLAN → CODE + TESTS → BUILD PASS.
+
+---
+
+## 1. Four Workflow Types
+
+### New Feature
+
+When: Building something that doesn't exist yet (no code, no spec).
+
+```
+Step 1 → /plan "description of feature"
+          Generates: docs/specs/<feature>.md (spec)
+                     docs/test-plans/<feature>.md (test plan)
+          Answers validation questions about assumptions.
+          Review both before proceeding.
+
+Step 2 → (Optional) /challenge docs/test-plans/<feature>.md
+          Adversarial review: spawns hostile reviewers to find flaws.
+          Recommended for complex features, auth, data pipelines.
+          Skip for simple CRUD or small features.
+
+Step 3 → Implement in chunks. After each chunk:
+          /test
+          Repeat until chunk is green.
+
+Step 4 → /review (before merge)
+
+Step 5 → /commit
+```
+
+### Update Existing Feature
+
+When: Changing behavior, adding options, refactoring logic.
+
+```
+Step 1 → Update spec FIRST: docs/specs/<feature>.md
+          Describe what's changing and why.
+
+Step 2 → /plan docs/specs/<feature>.md
+          Updates the test plan with new/modified/removed test cases.
+
+Step 3 → Implement code changes.
+          /test
+          Fix until green.
+
+Step 4 → /review → /commit
+```
+
+### Bug Fix
+
+When: Something is broken and needs fixing.
+
+```
+Step 1 → /fix "description of the bug"
+          Writes failing test → fixes code → confirms green → runs full suite.
+
+Step 2 → /commit
+
+Optional → If the bug reveals an undocumented edge case, update the spec.
+```
+
+### Remove Feature
+
+When: Deleting a feature, removing deprecated code.
+
+```
+Step 1 → Mark spec sections as removed in docs/specs/<feature>.md
+          (Or archive the entire file if the feature is fully removed.)
+
+Step 2 → Delete production code and related test code.
+
+Step 3 → Run full test suite: bash scripts/build-test.sh
+          Fix any cascading breakage.
+
+Step 4 → /commit
+```
+
+---
+
+## 2. Decision Tree
+
+Use this to decide which workflow to follow:
+
+```
+Is this a brand new feature (no existing spec or code)?
+├─ Yes → New Feature workflow. Start with /plan.
+│   └─ Is the feature complex (auth, data pipeline, multi-service)?
+│       ├─ Yes → Run /challenge after /plan, before coding.
+│       └─ No → Skip /challenge, go straight to implementation.
+└─ No
+    ├─ Is this a bug fix?
+    │   ├─ Yes → Bug Fix workflow. Start with /fix.
+    │   └─ No
+    │       ├─ Are you removing/deprecating code?
+    │       │   ├─ Yes → Remove Feature workflow.
+    │       │   └─ No → Update Feature workflow. Start by editing the spec.
+    │       │
+    │       └─ Is the change very small (< 5 lines, behavior unchanged)?
+    │           └─ Yes → Skip spec update. Just /test and /commit.
+```
+
+---
+
+## 3. Prompt Templates
+
+Copy-paste these when working with Claude Code.
+
+### Template A — Implement + Test Together
+
+```
+I just implemented [brief description].
+Files changed: [list files]
+
+Based on:
+- Spec: docs/specs/<feature>.md (section §X)
+- Test plan: docs/test-plans/<feature>.md
+
+Write tests for the part I just implemented.
+Only tests related to this change — not the entire feature.
+Build and run until all pass.
+If the spec seems incomplete, note what's missing but don't change it.
+```
+
+### Template B — Update Feature + Tests
+
+```
+I'm about to change [description of change].
+Affected files: [list]
+
+1. Update the spec: docs/specs/<feature>.md
+2. Update the test plan: docs/test-plans/<feature>.md (only affected test cases)
+3. Implement the code change
+4. Update tests to match
+5. Build and run → fix until green
+```
+
+### Template C — Test-First Bug Fix
+
+```
+Bug: [description]
+Steps to reproduce: [steps]
+Expected: [correct behavior]
+Actual: [broken behavior]
+
+1. Write a test that reproduces this bug (must fail currently)
+2. Fix the production code to make the test pass
+3. Run the full test suite — nothing else should break
+4. Update the spec if this is an undocumented edge case
+```
+
+### Template D — Remove Feature
+
+```
+Removing: [feature name]
+Files to delete: [list]
+
+1. Mark relevant spec sections as removed
+2. Mark related test plan entries as removed
+3. Delete production code
+4. Delete test code
+5. Run full test suite → fix cascading breaks
+```
+
+---
+
+## 4. Token Cost Guide
+
+| Workflow | Estimated Tokens | When |
+|----------|-----------------|------|
+| `/test` (incremental) | 5–10k | Daily, after each code chunk |
+| `/fix` (single bug) | 3–5k | As bugs arise |
+| `/commit` | 2–4k | Each commit |
+| `/review` (diff-based) | 10–20k | Before merge |
+| `/plan` (new feature) | 20–40k | Start of new feature |
+| `/challenge` (adversarial) | 15–30k | After /plan, for complex features |
+| Full audit (manual) | 100k+ | Before release, quarterly |
+
+**Rule of thumb:** Daily work uses templates + `/test` → low token cost.
+Save `/plan` and full audits for significant milestones.
+
+---
+
+## 5. CI Integration Checklist
+
+Use this as a PR review checklist (enforce manually or via CI):
+
+- [ ] **Spec updated?** If production behavior changed, `docs/specs/` should have changes.
+- [ ] **Test plan updated?** If spec changed, `docs/test-plans/` should have changes.
+- [ ] **Tests pass?** `bash scripts/build-test.sh` exits 0.
+- [ ] **No dead tests?** Removed production code → removed corresponding tests.
+- [ ] **Coverage not decreased?** (Optional, per-team decision.)
+- [ ] **No secrets in diff?** No API keys, tokens, passwords in committed code.
+- [ ] **Commit messages conventional?** `type(scope): description` format.
+
+---
+
+## 6. Spec-Test-Code Sync Rules
+
+| Change | Must Also Update |
+|--------|-----------------|
+| Production code behavior changed | Spec + test plan + tests |
+| Spec updated | Test plan + tests (if behavior changed) |
+| Test plan updated | Tests (implement new/modified test cases) |
+| Code removed | Remove related tests. Mark spec as removed. |
+| Bug fix | Add test. Update spec if edge case was undocumented. |
+
+**Never acceptable:**
+- Code changed, spec not updated (spec drift)
+- Code changed, tests not updated (untested code)
+- Spec changed, tests not updated (plan drift)
+- Code removed, dead tests remain (orphaned tests)
+
+**Acceptable shortcut** for changes under 5 lines with no behavior change:
+- Code + tests together, skip spec update (same PR).
+
+---
+
+## 7. Common Pitfalls
+
+| Pitfall | Symptom | Prevention |
+|---------|---------|------------|
+| **Spec drift** | Code does X, spec says Y | Always update spec before coding |
+| **Dead tests** | Tests pass but test removed functionality | Delete tests when removing features |
+| **Over-testing** | 50 tests for simple CRUD, slow suite | Focus on behavior, not implementation details |
+| **Mock abuse** | Tests pass with mocks, fail in production | Use real implementations; mock only external services |
+| **Big-bang testing** | All tests written after all code is done | Test incrementally after each chunk |
+| **Ignoring flaky tests** | Tests pass sometimes, fail sometimes | Fix immediately — flaky tests erode trust |
+| **Testing private methods** | Tests break on refactor | Test public API and behavior only |