@smartsoft001/pro-claude-plugins 0.2.0

package/plugins/smart-pro/hooks/CONFIG.md

@@ -0,0 +1,198 @@
+# Hooks Configuration Guide
+
+This guide explains how to configure and customize the hooks system.
+
+## Hook Configuration
+
+All hooks are defined in `hooks.json` in this directory:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "_description": "Safety gate: blocks destructive bash commands",
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./safety_validator.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Hook commands use relative paths (e.g., `./safety_validator.py`) resolved from the `hooks/` directory.
+
+---
+
+## Hook Customization
+
+### safety_validator.py
+
+**Add blocked patterns** by editing the script:
+
+```python
+DANGEROUS_PATTERNS = [
+    r"rm\s+-rf\s+/",
+    r"rm\s+-rf\s+~",
+    # Add your patterns here
+]
+
+SENSITIVE_FILES = [
+    ".env",
+    "id_rsa",
+    # Add your patterns here
+]
+```
+
+---
+
+### sensitive_file_blocker.py
+
+**Add blocked file patterns** by editing:
+
+```python
+SENSITIVE_PATTERNS = [
+    r"\.env(?:\.|$)",
+    r"secrets",
+    r"credentials",
+    # Add your patterns here
+]
+```
+
+---
+
+### audit_logger.py
+
+**Change log location:**
+
+```python
+# Default: .claude/audit_logs/YYYYMMDD_audit.jsonl
+LOG_DIR = Path(__file__).resolve().parent.parent / "audit_logs"
+
+# Custom location:
+LOG_DIR = Path("/var/log/claude-audit")
+```
+
+---
+
+### auto_format.sh
+
+**Change format command:**
+
+```bash
+# Default:
+source ~/.nvm/nvm.sh && nvm use 24 && npm run format
+
+# Custom (e.g., without nvm):
+npm run format
+```
+
+---
+
+## Environment Variables
+
+| Variable             | Purpose                | Default       |
+| -------------------- | ---------------------- | ------------- |
+| `CLAUDE_HOOK_EVENT`  | Hook event type        | Set by Claude |
+| `CLAUDE_SESSION_ID`  | Session identifier     | Set by Claude |
+| `CLAUDE_PROJECT_DIR` | Project root directory | Auto-detected |
+| `SKIP_AUDIT_LOG`     | Disable audit logging  | Not set       |
+
+---
+
+## Hook Execution Order
+
+Hooks run in the order specified in `hooks.json`:
+
+**PreToolUse order:**
+
+1. safety_validator.py (can block)
+2. sensitive_file_blocker.py (can block)
+3. audit_logger.py (logs)
+4. skill_validator.py (warns)
+
+**PostToolUse order:**
+
+1. auto_format.sh (formats)
+2. audit_logger.py (logs)
+
+---
+
+## Selective Hook Enabling
+
+To use only specific hooks, edit `hooks.json` and remove unwanted entries.
+
+### Safety Only (No Formatting)
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "_description": "Safety gate",
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./safety_validator.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Adding New Hooks
+
+### Python Hook Template
+
+```python
+#!/usr/bin/env python3
+"""My custom hook."""
+
+import json
+import sys
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    # Your logic here
+    tool_name = data.get("tool_name", "")
+    tool_input = data.get("tool_input", {})
+
+    # Exit 0 = allow, Exit 2 = block
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()
+```
+
+### Shell Hook Template
+
+```bash
+#!/bin/bash
+set -e
+
+# Read JSON input
+INPUT=$(cat)
+
+# Parse with jq
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Your logic here
+
+# Exit 0 = allow, Exit 2 = block
+exit 0
+```

package/plugins/smart-pro/hooks/README.md

@@ -0,0 +1,139 @@
+# Hooks
+
+Claude Code hooks for safety validation, sensitive file protection, formatting, and audit logging.
+
+---
+
+## What Are Hooks?
+
+Hooks are scripts that run at specific points in Claude's workflow:
+- **UserPromptSubmit**: When user submits a prompt
+- **PreToolUse**: Before a tool executes
+- **PostToolUse**: After a tool completes
+- **Stop**: When Claude stops responding
+
+**Key insight:** Hooks can modify prompts, block actions, and track state.
+
+---
+
+## Configuration
+
+All hooks are configured in `hooks.json` in this directory. Claude Code reads this file automatically when the plugin is installed.
+
+---
+
+## Current Hooks
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `safety_validator.py` | PreToolUse | Blocks destructive commands |
+| `sensitive_file_blocker.py` | PreToolUse | Blocks access to sensitive files |
+| `skill_validator.py` | PreToolUse | Validates skill file structure |
+| `auto_format.sh` | PostToolUse | Auto-formats after file changes |
+| `audit_logger.py` | All events | Logs all actions for audit trail |
+
+---
+
+## Hook Details
+
+### safety_validator.py (PreToolUse)
+
+**Purpose:** Blocks destructive bash commands and sensitive file modifications.
+
+**Matcher:** `Bash|Write|Edit`
+
+**Blocks:**
+- `rm -rf /`, `rm -rf ~`, `rm -rf *`
+- `dd` disk operations, `mkfs` formatting
+- Fork bombs
+- Bash access to `.env`, `id_rsa`, `credentials` files
+
+**Exit codes:**
+- `0` - Allow
+- `2` - Block with message
+
+---
+
+### sensitive_file_blocker.py (PreToolUse)
+
+**Purpose:** Blocks Read/Edit/Write access to sensitive files.
+
+**Matcher:** `Read|Edit|Write`
+
+**Blocked patterns:**
+- `.env` files (`.env`, `.env.local`, `.env.production`)
+- `secrets` in path
+- `credentials` in path
+
+**Exception:** Files ending with `.example` are allowed.
+
+**Exit codes:**
+- `0` - Allow
+- `2` - Block with message
+
+---
+
+### skill_validator.py (PreToolUse)
+
+**Purpose:** Validates skill files follow correct structure.
+
+**Matcher:** `Write|Edit`
+
+**Checks:**
+- YAML frontmatter (name, description)
+- Required sections (Purpose, When to Use)
+- File length limits
+- Resource file references
+
+**Enforcement:** Soft (warns but doesn't block)
+
+---
+
+### auto_format.sh (PostToolUse)
+
+**Purpose:** Auto-formats files after Write/Edit operations.
+
+**Matcher:** `Write|Edit`
+
+**Runs:** `source ~/.nvm/nvm.sh && nvm use 24 && npm run format`
+
+**Requires:** Node.js 24 via nvm
+
+---
+
+### audit_logger.py (All Events)
+
+**Purpose:** Logs all Claude actions for audit trail.
+
+**Log location:** `.claude/audit_logs/YYYYMMDD_audit.jsonl`
+
+**Logged events:**
+- PreToolUse (tool name, inputs)
+- PostToolUse (tool name, success/failure)
+- UserPromptSubmit (prompt text)
+- Stop (session end)
+
+---
+
+## Adding New Hooks
+
+1. Create script in this `hooks/` directory
+2. Make executable: `chmod +x script.py`
+3. Add to `hooks.json` under appropriate event
+4. Include `_description` for documentation
+
+Example entry in `hooks.json`:
+```json
+{
+  "_description": "My custom hook: does something useful",
+  "matcher": "Write|Edit",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "./my-hook.py"
+    }
+  ]
+}
+```
+
+See [CONFIG.md](./CONFIG.md) for customization options.

package/plugins/smart-pro/hooks/audit_logger.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Claude Code Audit Logger
+
+Comprehensive audit trail for all Claude Code hook events.
+Logs are stored in JSONL format with ISO timestamps for easy parsing and sorting.
+
+Features:
+- Daily log rotation with yyyymmdd_audit.jsonl naming format
+- ISO 8601 timestamps (UTC) for consistent sorting
+- Automatic cleanup of logs older than 90 days
+- Captures all hook events: PreToolUse, PostToolUse, Stop, UserPromptSubmit
+
+Log location: .claude/audit_logs/ (local to repository)
+Log format: JSONL (one JSON object per line)
+
+Each log entry contains:
+- timestamp: ISO 8601 UTC timestamp
+- event_type: The Claude hook event type
+- session_id: Unique session identifier
+- event_data: Full event payload from stdin
+
+Usage:
+    Configure in .claude/settings.json hooks section
+"""
+
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def get_log_directory() -> Path:
+    """Get or create the audit logs directory in the local .claude folder."""
+    # Get the directory where this script is located (.claude/hooks/)
+    script_dir = Path(__file__).resolve().parent
+    # Go up to .claude/ and then into audit_logs/
+    log_dir = script_dir.parent / "audit_logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+def get_iso_timestamp() -> str:
+    """Get current UTC timestamp in ISO 8601 format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def get_log_filename() -> str:
+    """Get log filename in yyyymmdd_audit.jsonl format."""
+    return datetime.now(timezone.utc).strftime("%Y%m%d") + "_audit.jsonl"
+
+
+def parse_event_data() -> dict:
+    """Parse event data from stdin."""
+    try:
+        return json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        return {"parse_error": str(e), "raw_input": "Could not read stdin"}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def rotate_old_logs(log_dir: Path, retention_days: int = 90) -> None:
+    """Remove log files older than retention period."""
+    cutoff_time = time.time() - (retention_days * 24 * 60 * 60)
+
+    for old_log in log_dir.glob("*_audit.jsonl"):
+        try:
+            if old_log.stat().st_mtime < cutoff_time:
+                old_log.unlink()
+        except OSError:
+            pass  # Ignore errors during cleanup
+
+
+def write_audit_entry(log_dir: Path, entry: dict) -> None:
+    """Write audit entry to daily log file."""
+    log_file = log_dir / get_log_filename()
+
+    with open(log_file, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False, separators=(",", ":")) + "\n")
+
+
+def main() -> None:
+    """Main entry point for audit logging."""
+    log_dir = get_log_directory()
+
+    # Build audit entry
+    audit_entry = {
+        "timestamp": get_iso_timestamp(),
+        "event_type": os.environ.get("CLAUDE_HOOK_EVENT", "unknown"),
+        "session_id": os.environ.get("CLAUDE_SESSION_ID", "unknown"),
+        "event_data": parse_event_data()
+    }
+
+    # Write to log file
+    write_audit_entry(log_dir, audit_entry)
+
+    # Rotate old logs (runs on each call, but fast due to glob)
+    rotate_old_logs(log_dir)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/plugins/smart-pro/hooks/auto_format.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Auto-format hook for Claude Code
+#
+# Runs the project's formatting pipeline (nx format + lint --fix)
+# after Write/Edit operations.
+#
+# Requires Node.js 24 via nvm.
+
+set -e
+
+source ~/.nvm/nvm.sh && nvm use 24 && npm run format

package/plugins/smart-pro/hooks/hooks.json

@@ -0,0 +1,79 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "_description": "Safety gate: blocks destructive bash commands",
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./safety_validator.py"
+          }
+        ]
+      },
+      {
+        "_description": "Block sensitive files with detailed error message",
+        "matcher": "Read|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./sensitive_file_blocker.py"
+          }
+        ]
+      },
+      {
+        "_description": "Audit trail: logs all PreToolUse events",
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./audit_logger.py"
+          }
+        ]
+      },
+      {
+        "_description": "Skill validator: soft enforcement warnings for skill files",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./skill_validator.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "_description": "Auto-format files after Write/Edit",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./auto_format.sh"
+          }
+        ]
+      },
+      {
+        "_description": "Audit trail: logs all PostToolUse events",
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./audit_logger.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "_description": "Audit trail: logs all user prompt submissions",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./audit_logger.py"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/smart-pro/hooks/safety_validator.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+Safety Validator Hook for Claude Code
+======================================
+
+Purpose:
+    Pre-tool-use validation layer that blocks potentially destructive operations
+    before they execute. Acts as a safety gate for Bash, Read, Write, and Edit tools.
+
+Protected Against:
+    - Recursive deletion of root filesystem (rm -rf /)
+    - Recursive deletion of all files (rm -rf *)
+    - Recursive deletion of home directory (rm -rf ~)
+    - Disk wiping operations (dd if=/dev/zero)
+    - Access to environment files (.env, .env.local, .env.production, etc.)
+    - Access to secret files (.secret, .secret.local, etc.)
+    - Access to SSH private keys (id_rsa, id_ed25519, id_ecdsa)
+    - Access to credential files (.pem, credentials)
+    - Bash access to sensitive files (cat/head/tail/cp on .env, .secret, keys)
+
+Exceptions:
+    - Files ending with .example are allowed (safe template files)
+    - e.g., .env.example, .secret.example can be read for structure reference
+
+Exit Codes:
+    0 - Tool use permitted (validation passed)
+    2 - Tool use blocked (dangerous operation detected)
+
+Integration:
+    Configured as PreToolUse hook in .claude/settings.json
+    Receives tool call JSON via stdin from Claude Code
+"""
+
+import json
+import sys
+import re
+
+data = json.load(sys.stdin)
+tool_name = data.get("tool_name", "")
+tool_input = data.get("tool_input", {})
+
+# Block dangerous bash commands
+if tool_name == "Bash":
+    command = tool_input.get("command", "")
+
+    dangerous_patterns = [
+        # rm -rf variations: handles -rf, -r -f, --recursive --force, etc.
+        r"rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+-[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*\s+-[a-zA-Z]*r[a-zA-Z]*|-[a-zA-Z]*rf[a-zA-Z]*|-[a-zA-Z]*fr[a-zA-Z]*|--recursive\s+--force|--force\s+--recursive)\s+/\s*$",
+        # rm -rf /* or rm -rf *
+        r"rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+-[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*\s+-[a-zA-Z]*r[a-zA-Z]*|-[a-zA-Z]*rf[a-zA-Z]*|-[a-zA-Z]*fr[a-zA-Z]*|--recursive\s+--force|--force\s+--recursive)\s+(/\*)?\*",
+        # rm -rf ~ (home directory)
+        r"rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+-[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*\s+-[a-zA-Z]*r[a-zA-Z]*|-[a-zA-Z]*rf[a-zA-Z]*|-[a-zA-Z]*fr[a-zA-Z]*|--recursive\s+--force|--force\s+--recursive)\s+~",
+        # rm -rf $HOME
+        r"rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+-[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*\s+-[a-zA-Z]*r[a-zA-Z]*|-[a-zA-Z]*rf[a-zA-Z]*|-[a-zA-Z]*fr[a-zA-Z]*|--recursive\s+--force|--force\s+--recursive)\s+\$HOME",
+        # dd disk operations
+        r"dd\s+.*if=/dev/(zero|random|urandom).*of=/dev/",
+        r"dd\s+.*of=/dev/[a-z]+\s",
+    ]
+
+    for pattern in dangerous_patterns:
+        if re.search(pattern, command, re.IGNORECASE):
+            print("BLOCKED: Dangerous command pattern detected", file=sys.stderr)
+            sys.exit(2)
+
+    # Additional simple checks for common dangerous patterns
+    dangerous_simple = [
+        ("rm -rf /", "recursive delete root"),
+        ("rm -rf /*", "recursive delete root contents"),
+        ("rm -rf ~", "recursive delete home"),
+        ("rm -rf $HOME", "recursive delete home"),
+        ("> /dev/sda", "overwrite disk"),
+        ("mkfs.", "format filesystem"),
+        (":(){ :|:& };:", "fork bomb"),
+    ]
+
+    for pattern, description in dangerous_simple:
+        if pattern in command:
+            print(f"BLOCKED: {description}", file=sys.stderr)
+            sys.exit(2)
+
+    # Block Bash access to sensitive files (but allow .example files)
+    # First check if it's an .example file - those are safe
+    if not re.search(r"\.example\b", command, re.IGNORECASE):
+        sensitive_file_patterns = [
+            r"\bcat\s+.*\.env\b",
+            r"\bhead\s+.*\.env\b",
+            r"\btail\s+.*\.env\b",
+            r"\bcp\s+.*\.env\b",
+            r"\bcat\s+.*\.secret",
+            r"\bhead\s+.*\.secret",
+            r"\btail\s+.*\.secret",
+            r"\bcp\s+.*\.secret",
+            r"\bcat\s+.*id_rsa",
+            r"\bcat\s+.*id_ed25519",
+            r"\bcat\s+.*\.pem",
+            r"\bcat\s+.*credentials",
+        ]
+
+        for pattern in sensitive_file_patterns:
+            if re.search(pattern, command, re.IGNORECASE):
+                print("BLOCKED: Cannot access sensitive file via Bash", file=sys.stderr)
+                sys.exit(2)
+
+# Block access to sensitive files
+if tool_name in ["Read", "Write", "Edit"]:
+    file_path = tool_input.get("file_path", "")
+
+    # Allow .example files (they're safe templates without secrets)
+    if file_path.endswith(".example"):
+        sys.exit(0)
+
+    sensitive_patterns = [
+        ".env",
+        ".secret",
+        "id_rsa",
+        "id_ed25519",
+        "id_ecdsa",
+        ".pem",
+        "credentials",
+    ]
+
+    for blocked in sensitive_patterns:
+        if blocked in file_path:
+            print(
+                f"BLOCKED: Cannot modify sensitive file: {file_path}", file=sys.stderr
+            )
+            sys.exit(2)
+
+sys.exit(0)