pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/infrastructure/shell/security/detect-secrets.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+set -euo pipefail
+
+REPO_ROOT=${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}
+BASELINE_PATH=${BASELINE_PATH:-"$REPO_ROOT/scripts/hooks-system/config/detect-secrets-baseline.json"}
+MODE="${1:-scan}"
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+PYTHON_SCRIPT="$SCRIPT_DIR/detect_secrets.py"
+
+PYTHON3=""
+if [[ -x "/opt/homebrew/bin/python3" ]]; then
+  PYTHON3="/opt/homebrew/bin/python3"
+elif command -v python3 >/dev/null 2>&1; then
+  PYTHON3="python3"
+else
+  echo "detect-secrets.sh: se requiere python3" >&2
+  exit 1
+fi
+
+if [[ ! -f "$PYTHON_SCRIPT" ]]; then
+  echo "detect-secrets.sh: no se encuentra $PYTHON_SCRIPT" >&2
+  exit 1
+fi
+
+exec "$PYTHON3" "$PYTHON_SCRIPT" "$MODE" "$REPO_ROOT" "$BASELINE_PATH"

package/scripts/hooks-system/infrastructure/shell/security/detect_secrets.py

@@ -0,0 +1,182 @@
+import argparse
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+import re
+import sys
+from typing import Dict, Iterable, List, Set
+
+INCLUDE_EXTENSIONS: Set[str] = {
+    ".ts", ".tsx", ".js", ".jsx", ".kt", ".kts", ".swift",
+    ".env", ".py", ".rb", ".php", ".json", ".java", ".cs",
+}
+
+EXCLUDE_DIRECTORIES: Set[str] = {
+    "node_modules", ".git", "dist", "build", ".next", "coverage",
+    ".turbo", ".idea", ".vscode", ".gradle", "DerivedData",
+    ".audit_tmp", ".audit-reports",
+}
+
+PATTERN = re.compile(r"(password|secret|api[_-]?key|token|bearer)\s*[:=]\s*[\"']?[^\"';\s]+", re.IGNORECASE)
+
+
+def get_staged_files(root: str) -> Set[str]:
+    import subprocess
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return {os.path.join(root, f.strip()) for f in result.stdout.splitlines() if f.strip()}
+    except subprocess.CalledProcessError:
+        return set()
+
+
+def iter_candidate_files(root: str, ignored_files: Set[str], staged_only: bool = True) -> Iterable[str]:
+    staged_files = get_staged_files(root) if staged_only else set()
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [
+            name for name in dirnames
+            if name not in EXCLUDE_DIRECTORIES and not name.startswith(".git")
+        ]
+        for filename in filenames:
+            extension = os.path.splitext(filename)[1].lower()
+            if extension not in INCLUDE_EXTENSIONS:
+                continue
+            path = os.path.join(dirpath, filename)
+            if os.path.abspath(path) in ignored_files:
+                continue
+            if staged_only and path not in staged_files:
+                continue
+            yield path
+
+
+def collect_matches(path: str) -> Iterable[Dict[str, str]]:
+    try:
+        with open(path, "r", encoding="utf-8", errors="ignore") as handle:
+            for index, line in enumerate(handle, start=1):
+                if PATTERN.search(line):
+                    snippet = line.rstrip()
+                    yield {
+                        "path": path,
+                        "line": index,
+                        "snippet": snippet,
+                    }
+    except (OSError, UnicodeDecodeError):
+        return
+
+
+def gather_matches(root: str, ignored_files: Set[str], staged_only: bool = True) -> List[Dict[str, str]]:
+    collected: List[Dict[str, str]] = []
+    for candidate in iter_candidate_files(root, ignored_files, staged_only):
+        for match in collect_matches(candidate):
+            collected.append(match)
+    return collected
+
+
+def fingerprint(item: Dict[str, str]) -> str:
+    base = f"{item['path']}:{item['line']}:{item['snippet'].strip()}"
+    return hashlib.sha256(base.encode()).hexdigest()
+
+
+def load_baseline(path: str) -> Dict[str, Dict[str, str]]:
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["git", "show", f":scripts/hooks-system/config/detect-secrets-baseline.json"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        payload = json.loads(result.stdout)
+        return {entry["fingerprint"]: entry for entry in payload.get("matches", [])}
+    except (subprocess.CalledProcessError, json.JSONDecodeError):
+        pass
+
+    if not os.path.exists(path):
+        return {}
+    with open(path, "r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+    return {entry["fingerprint"]: entry for entry in payload.get("matches", [])}
+
+
+def write_baseline(path: str, matches: List[Dict[str, str]]) -> None:
+    data = []
+    for item in matches:
+        rel_path = os.path.relpath(item["path"])
+        normalized_item = {
+            "path": rel_path,
+            "line": item["line"],
+            "snippet": item["snippet"],
+        }
+        data.append(
+            {
+                "path": rel_path,
+                "line": item["line"],
+                "fingerprint": fingerprint(normalized_item),
+            }
+        )
+    data.sort(key=lambda entry: (entry["path"], entry["line"], entry["fingerprint"]))
+    payload = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "matches": data,
+    }
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2, ensure_ascii=False)
+    print(f"Baseline actualizado con {len(data)} coincidencias -> {path}")
+
+
+def run_scan(root: str, baseline_path: str, ignored_files: Set[str]) -> int:
+    baseline = load_baseline(baseline_path)
+    findings = gather_matches(root, ignored_files, staged_only=True)
+
+    if not findings:
+        return 0
+
+    missing = []
+    for item in findings:
+        rel_path = os.path.relpath(item["path"], root)
+        normalized_item = {
+            "path": rel_path,
+            "line": item["line"],
+            "snippet": item["snippet"],
+        }
+        if fingerprint(normalized_item) not in baseline:
+            missing.append(normalized_item)
+
+    if not missing:
+        return 0
+
+    print("Nuevos posibles secretos detectados en archivos staged:")
+    for item in missing:
+        print(f" - {item['path']}:{item['line']} -> {item['snippet'].strip()}")
+    print("Actualiza el baseline si se trata de falsos positivos.")
+    return 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Detector simple de secretos con baseline")
+    parser.add_argument("mode", choices=["scan", "baseline"], help="Modo de ejecución")
+    parser.add_argument("root", help="Ruta del repositorio")
+    parser.add_argument("baseline", help="Ruta del archivo baseline")
+    args = parser.parse_args()
+
+    ignored_files = {os.path.abspath(args.baseline)}
+
+    if args.mode == "baseline":
+        collected = gather_matches(args.root, ignored_files, staged_only=False)
+        write_baseline(args.baseline, collected)
+        return 0
+
+    return run_scan(args.root, args.baseline, ignored_files)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/hooks-system/infrastructure/shell/validate-clean-architecture.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Clean Architecture Validator
+# =============================================================================
+# Purpose: Auto-validate file paths against Clean Architecture rules
+# Author: Carlos Merlos
+# =============================================================================
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+VIOLATIONS=0
+
+# =============================================================================
+# Frontend Rules (React/TypeScript/Next.js)
+# =============================================================================
+validate_frontend_file() {
+  local file="$1"
+  local filename=$(basename "$file")
+  local dir=$(dirname "$file")
+
+  # Hook files
+  if [[ "$filename" =~ ^use[A-Z].*\.(ts|tsx)$ ]]; then
+    if [[ ! "$dir" =~ presentation/hooks$ ]]; then
+      echo -e "${RED}❌ VIOLATION: Hook file in wrong location${NC}"
+      echo -e "   File: $file"
+      echo -e "   Rule: Custom hooks → ${GREEN}presentation/hooks/${NC}"
+      echo -e "   Found in: ${RED}$dir${NC}"
+      echo -e "   Fix: Move to presentation/hooks/"
+      ((VIOLATIONS++))
+      return 1
+    fi
+  fi
+
+  # Config files
+  if [[ "$filename" =~ \.config\.(ts|js)$ ]] || [[ "$filename" =~ ^(api|i18n|env)\.(ts|js)$ ]]; then
+    if [[ ! "$dir" =~ infrastructure/config$ ]]; then
+      echo -e "${RED}❌ VIOLATION: Config file in wrong location${NC}"
+      echo -e "   File: $file"
+      echo -e "   Rule: Configuration → ${GREEN}infrastructure/config/${NC}"
+      echo -e "   Found in: ${RED}$dir${NC}"
+      echo -e "   Fix: Move to infrastructure/config/"
+      ((VIOLATIONS++))
+      return 1
+    fi
+  fi
+
+  # Store files (Zustand/Redux)
+  if [[ "$filename" =~ Store\.(ts|tsx)$ ]] || [[ "$filename" =~ \.store\.(ts|tsx)$ ]]; then
+    if [[ ! "$dir" =~ presentation/stores$ ]]; then
+      echo -e "${RED}❌ VIOLATION: Store file in wrong location${NC}"
+      echo -e "   File: $file"
+      echo -e "   Rule: State stores → ${GREEN}presentation/stores/${NC}"
+      echo -e "   Found in: ${RED}$dir${NC}"
+      echo -e "   Fix: Move to presentation/stores/"
+      ((VIOLATIONS++))
+      return 1
+    fi
+  fi
+
+  # Use Case files
+  if [[ "$filename" =~ UseCase\.(ts|js)$ ]]; then
+    if [[ ! "$dir" =~ application/use-cases$ ]]; then
+      echo -e "${RED}❌ VIOLATION: Use Case in wrong location${NC}"
+      echo -e "   File: $file"
+      echo -e "   Rule: Use Cases → ${GREEN}application/use-cases/${NC}"
+      echo -e "   Found in: ${RED}$dir${NC}"
+      echo -e "   Fix: Move to application/use-cases/"
+      ((VIOLATIONS++))
+      return 1
+    fi
+  fi
+
+  # Repository implementations
+  if [[ "$filename" =~ Repository\.(ts|js)$ ]] && [[ ! "$filename" =~ ^I[A-Z] ]]; then
+    if [[ ! "$dir" =~ infrastructure/repositories$ ]]; then
+      echo -e "${RED}❌ VIOLATION: Repository implementation in wrong location${NC}"
+      echo -e "   File: $file"
+      echo -e "   Rule: Repository impl → ${GREEN}infrastructure/repositories/${NC}"
+      echo -e "   Found in: ${RED}$dir${NC}"
+      echo -e "   Fix: Move to infrastructure/repositories/"
+      ((VIOLATIONS++))
+      return 1
+    fi
+  fi
+
+  # Repository interfaces
+  if [[ "$filename" =~ ^I[A-Z].*Repository\.(ts|js)$ ]]; then
+    if [[ ! "$dir" =~ domain/repositories$ ]]; then
+      echo -e "${RED}❌ VIOLATION: Repository interface in wrong location${NC}"
+      echo -e "   File: $file"
+      echo -e "   Rule: Repository interface → ${GREEN}domain/repositories/${NC}"
+      echo -e "   Found in: ${RED}$dir${NC}"
+      echo -e "   Fix: Move to domain/repositories/"
+      ((VIOLATIONS++))
+      return 1
+    fi
+  fi
+
+  # FORBIDDEN DIRECTORIES
+  if [[ "$dir" =~ /lib/ ]] && [[ ! "$dir" =~ /node_modules/ ]]; then
+    echo -e "${RED}❌ VIOLATION: File in forbidden 'lib/' directory${NC}"
+    echo -e "   File: $file"
+    echo -e "   Rule: ${RED}NEVER use lib/${NC}"
+    echo -e "   Use instead:"
+    echo -e "     - infrastructure/ (for services, config)"
+    echo -e "     - presentation/ (for hooks, components)"
+    ((VIOLATIONS++))
+    return 1
+  fi
+
+  if [[ "$dir" =~ /utils/ ]] && [[ ! "$dir" =~ /node_modules/ ]]; then
+    echo -e "${RED}❌ VIOLATION: File in forbidden 'utils/' directory${NC}"
+    echo -e "   File: $file"
+    echo -e "   Rule: ${RED}NEVER use utils/${NC}"
+    echo -e "   Use instead:"
+    echo -e "     - application/ (for business logic)"
+    echo -e "     - domain/ (for domain logic)"
+    ((VIOLATIONS++))
+    return 1
+  fi
+
+  if [[ "$dir" =~ /helpers/ ]] && [[ ! "$dir" =~ /node_modules/ ]]; then
+    echo -e "${RED}❌ VIOLATION: File in forbidden 'helpers/' directory${NC}"
+    echo -e "   File: $file"
+    echo -e "   Rule: ${RED}NEVER use helpers/${NC}"
+    echo -e "   Use: ${GREEN}application/use-cases/${NC}"
+    ((VIOLATIONS++))
+    return 1
+  fi
+
+  return 0
+}
+
+# =============================================================================
+# Backend Rules (NestJS)
+# =============================================================================
+validate_backend_file() {
+  local file="$1"
+  local filename=$(basename "$file")
+  local dir=$(dirname "$file")
+
+  # Controller files
+  if [[ "$filename" =~ \.controller\.(ts|js)$ ]]; then
+    if [[ ! "$dir" =~ presentation/controllers$ ]] && [[ ! "$dir" =~ src/[^/]+$ ]]; then
+      echo -e "${YELLOW}⚠️  WARNING: Controller not in presentation/controllers${NC}"
+      echo -e "   File: $file"
+      echo -e "   Recommended: ${GREEN}presentation/controllers/${NC}"
+      echo -e "   Current: $dir"
+    fi
+  fi
+
+  # Guard files
+  if [[ "$filename" =~ \.guard\.(ts|js)$ ]]; then
+    if [[ ! "$dir" =~ presentation/guards$ ]] && [[ ! "$dir" =~ src/guards$ ]]; then
+      echo -e "${YELLOW}⚠️  WARNING: Guard not in presentation/guards${NC}"
+      echo -e "   File: $file"
+      echo -e "   Recommended: ${GREEN}presentation/guards/${NC}"
+    fi
+  fi
+
+  # Use Case files
+  if [[ "$filename" =~ UseCase\.(ts|js)$ ]] || [[ "$filename" =~ \.use-case\.(ts|js)$ ]]; then
+    if [[ ! "$dir" =~ application/use-cases$ ]]; then
+      echo -e "${RED}❌ VIOLATION: Use Case in wrong location${NC}"
+      echo -e "   File: $file"
+      echo -e "   Rule: Use Cases → ${GREEN}application/use-cases/${NC}"
+      echo -e "   Found in: ${RED}$dir${NC}"
+      ((VIOLATIONS++))
+      return 1
+    fi
+  fi
+
+  # DTO files
+  if [[ "$filename" =~ \.dto\.(ts|js)$ ]]; then
+    if [[ ! "$dir" =~ application/dtos$ ]] && [[ ! "$dir" =~ src/[^/]+/dto$ ]]; then
+      echo -e "${YELLOW}⚠️  WARNING: DTO not in application/dtos${NC}"
+      echo -e "   File: $file"
+      echo -e "   Recommended: ${GREEN}application/dtos/${NC}"
+    fi
+  fi
+
+  # FORBIDDEN DIRECTORIES (same as frontend)
+  if [[ "$dir" =~ /lib/ ]] && [[ ! "$dir" =~ /node_modules/ ]]; then
+    echo -e "${RED}❌ VIOLATION: File in forbidden 'lib/' directory${NC}"
+    echo -e "   File: $file"
+    echo -e "   Rule: ${RED}NEVER use lib/${NC} → Use ${GREEN}infrastructure/${NC}"
+    ((VIOLATIONS++))
+    return 1
+  fi
+
+  return 0
+}
+
+# =============================================================================
+# Main Validator
+# =============================================================================
+
+validate_staged_files() {
+  echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+  echo -e "${BLUE}🏗️  Clean Architecture Validator${NC}"
+  echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+  echo ""
+
+  local staged_files=$(git diff --cached --name-only --diff-filter=ACM)
+
+  if [[ -z "$staged_files" ]]; then
+    echo -e "${GREEN}✅ No files to validate${NC}"
+    return 0
+  fi
+
+  local file_count=$(echo "$staged_files" | wc -l | tr -d ' ')
+  echo "📁 Validating $file_count staged file(s)..."
+  echo ""
+
+  while IFS= read -r file; do
+    # Skip non-source files
+    [[ "$file" =~ \.(md|json|yml|yaml|txt|lock)$ ]] && continue
+    [[ "$file" =~ node_modules/ ]] && continue
+    [[ "$file" =~ \.git/ ]] && continue
+
+    # Detect platform and validate
+    if [[ "$file" =~ \.(ts|tsx|jsx)$ ]] && [[ "$file" =~ apps/(admin-dashboard|web)/ ]]; then
+      validate_frontend_file "$file"
+    elif [[ "$file" =~ \.(ts|js)$ ]] && [[ "$file" =~ apps/backend/ ]]; then
+      validate_backend_file "$file"
+    fi
+  done <<< "$staged_files"
+
+  echo ""
+  if [[ $VIOLATIONS -gt 0 ]]; then
+    echo -e "${RED}═══════════════════════════════════════════════════════════════${NC}"
+    echo -e "${RED}❌ CLEAN ARCHITECTURE VIOLATED: $VIOLATIONS violation(s)${NC}"
+    echo -e "${RED}═══════════════════════════════════════════════════════════════${NC}"
+    echo ""
+    echo -e "${YELLOW}Fix violations or move files to correct directories.${NC}"
+    echo ""
+    echo -e "${BLUE}Need help? Run:${NC}"
+    echo -e "  ${GREEN}cat .cursorrules${NC}  # See structure rules"
+    echo ""
+    return 1
+  else
+    echo -e "${GREEN}✅ Clean Architecture: All files in correct locations${NC}"
+    return 0
+  fi
+}
+
+# Run validation
+validate_staged_files

package/scripts/hooks-system/infrastructure/shell/validators/check-doc-structure.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(git rev-parse --show-toplevel)"
+EXIT_CODE=0
+
+# git diff --cached --name-status includes lines like:
+#  A  path/file
+#  R100    old/path    new/path
+# Use read with up to 3 columns to capture rename targets.
+
+while IFS=$'\t' read -r status path_a path_b; do
+  [[ -z "${status:-}" ]] && continue
+
+  case "$status" in
+    A*|C*)
+      target="$path_a"
+      ;;
+    R*)
+      target="$path_b"
+      ;;
+    *)
+      continue
+      ;;
+  esac
+
+  [[ "${target:-}" != *.md ]] && continue
+
+  if [[ "$target" == scripts/hooks-system/* ]]; then
+    echo "❌ Documentación nueva detectada en '$target'. Usa docs/technical/hook-system/ como ubicación." >&2
+    EXIT_CODE=1
+    continue
+  fi
+
+  if [[ "$status" == R* ]]; then
+    # Renames mantienen el contenido previo; sólo validamos ubicación prohibida.
+    continue
+  fi
+
+  if [[ "$target" == docs/technical/hook-system/* ]]; then
+    line1="$(sed -n '1p' "$ROOT_DIR/$target" | tr -d '\r')"
+    line2="$(sed -n '2p' "$ROOT_DIR/$target" | tr -d '\r')"
+    line3="$(sed -n '3p' "$ROOT_DIR/$target" | tr -d '\r')"
+
+    if [[ "$line1" != Location:* || "$line2" != Related\ to:* || "$line3" != Owner:* ]]; then
+      echo "❌ '$target' debe comenzar con cabecera de metadatos (Location, Related to, Owner). Usa docs/templates/HOOK_DOC_TEMPLATE.md." >&2
+      EXIT_CODE=1
+      continue
+    fi
+
+    # Validar que Location coincide con ruta real
+    expected="Location: $target"
+    if [[ "$line1" != "$expected" ]]; then
+      echo "❌ '$target' → el campo Location debe ser '$expected'." >&2
+      EXIT_CODE=1
+    fi
+  fi
+
+done < <(git diff --cached --name-status --diff-filter=ACR)
+
+exit $EXIT_CODE

package/scripts/hooks-system/infrastructure/shell/validators/ensure-critical-docs.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Protect critical documentation from accidental deletion
+
+set -euo pipefail
+
+# List of critical documents that must exist
+CRITICAL_DOCS=(
+  "docs/planning/ROADMAP.md"
+  "docs/planning/LIBRARY_FIVE_STARS_ROADMAP.md"
+  "docs/technical/hook-system/README.md"
+)
+
+# Check each critical document
+for TARGET in "${CRITICAL_DOCS[@]}"; do
+  if [[ ! -f "$TARGET" ]]; then
+    echo "❌ Required document '$TARGET' is missing."
+    exit 1
+  fi
+
+  if git diff --cached --name-only --diff-filter=D | grep -q "^${TARGET}$"; then
+    echo "❌ Cannot delete critical document '$TARGET'."
+    exit 1
+  fi
+done
+
+exit 0