@soulbatical/tetra-dev-toolkit 1.2.0 → 1.3.1

package/README.md

@@ -0,0 +1,198 @@
+# @soulbatical/tetra-dev-toolkit
+
+Quality, security, and hygiene checks for all Soulbatical projects.
+
+## Install
+
+```bash
+npm install --save-dev @soulbatical/tetra-dev-toolkit
+```
+
+## Setup (A-Z)
+
+One command installs everything — hooks, CI, config:
+
+```bash
+npx tetra-setup
+```
+
+This creates:
+- `.husky/pre-commit` — quick security checks before every commit
+- `.husky/pre-push` — hygiene check before every push (blocks clutter)
+- `.github/workflows/quality.yml` — full audit on PR/push to main
+- `.tetra-quality.json` — project config (override defaults)
+
+To install individual components:
+
+```bash
+npx tetra-setup hooks    # Husky hooks only
+npx tetra-setup ci       # GitHub Actions only
+npx tetra-setup config   # Config file only
+```
+
+Re-running `tetra-setup hooks` on an existing project adds missing hooks without overwriting existing ones.
+
+## Usage
+
+```bash
+npx tetra-audit              # Run all checks
+npx tetra-audit security     # Security checks only
+npx tetra-audit stability    # Stability checks only
+npx tetra-audit codeQuality  # Code quality checks only
+npx tetra-audit supabase     # Supabase checks only
+npx tetra-audit hygiene      # Repo hygiene checks only
+npx tetra-audit quick        # Quick critical checks (pre-commit)
+npx tetra-audit --ci         # CI mode (GitHub Actions annotations)
+npx tetra-audit --json       # JSON output
+npx tetra-audit --verbose    # Detailed output with fix suggestions
+```
+
+Exit codes: `0` = passed, `1` = failed, `2` = error.
+
+## Check Suites
+
+### Security (5 checks)
+
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| Hardcoded Secrets | critical | API keys, tokens, JWTs in source code |
+| Service Key Exposure | critical | Supabase service role keys in frontend |
+| Deprecated Supabase Admin | high | Legacy `createClient(serviceKey)` patterns |
+| SystemDB Whitelist | high | Unauthorized system database access |
+| Gitignore Validation | high | Missing .gitignore entries, tracked .env files |
+
+### Stability (3 checks)
+
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| Husky Hooks | medium | Missing pre-commit/pre-push hooks |
+| CI Pipeline | medium | Missing or incomplete GitHub Actions config |
+| NPM Audit | high | Known vulnerabilities in dependencies |
+
+### Code Quality (1 check)
+
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| API Response Format | medium | Non-standard `{ success, data }` response format |
+
+### Supabase (2 checks, auto-detected)
+
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| RLS Policy Audit | critical | Tables without Row Level Security |
+| RPC Param Mismatch | critical | TypeScript `.rpc()` calls with wrong parameter names vs SQL |
+
+### Hygiene (1 check)
+
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| File Organization | high | Stray .md, .sh, clutter in code dirs, root mess, nested docs/ |
+
+## Health Checks
+
+Separate from audit suites, health checks provide a scored assessment (0-N points) used by the Ralph Manager dashboard:
+
+| Check | Max | What it measures |
+|-------|-----|------------------|
+| File Organization | 6pt | Docs in /docs, scripts in /scripts, clean root & code dirs |
+| Git | 4pt | Clean working tree, branch hygiene, commit frequency |
+| Gitignore | 3pt | Critical entries present |
+| CLAUDE.md | 3pt | Project instructions for AI assistants |
+| Secrets | 3pt | No exposed secrets |
+| Tests | 4pt | Test framework, coverage, test files |
+| Naming Conventions | 5pt | File/dir naming consistency |
+| Infrastructure YML | 3pt | Railway/Docker config |
+| Doppler Compliance | 2pt | Secrets management via Doppler |
+| MCP Servers | 2pt | MCP configuration |
+| Stella Integration | 2pt | Stella package integration |
+| Quality Toolkit | 2pt | Tetra dev-toolkit installed |
+| Repo Visibility | 1pt | Private repo |
+| RLS Audit | 3pt | Row Level Security policies |
+| Plugins | 2pt | Claude Code plugin config |
+| VinciFox Widget | 1pt | Widget installation |
+
+## Auto-fix: Cleanup Script
+
+For hygiene issues, an auto-fix script is included:
+
+```bash
+# Dry run (shows what would change)
+bash node_modules/@soulbatical/tetra-dev-toolkit/bin/cleanup-repos.sh
+
+# Execute
+bash node_modules/@soulbatical/tetra-dev-toolkit/bin/cleanup-repos.sh --execute
+```
+
+What it does:
+- `.md` files in code dirs -> `docs/_moved/`
+- `.sh` scripts in code dirs -> `scripts/_moved/`
+- Root clutter (`.txt`, `.png`, `.csv`) -> `docs/_cleanup/`
+- Code dir clutter -> `docs/_cleanup/{dir}/`
+- `.env` secrets in code dirs -> deleted
+- `tmp/`, `logs/`, `data/` dirs -> added to `.gitignore`
+
+## Configuration
+
+Override defaults in `.tetra-quality.json` or `"tetra-quality"` key in `package.json`:
+
+```json
+{
+  "suites": {
+    "security": true,
+    "stability": true,
+    "codeQuality": true,
+    "supabase": "auto",
+    "hygiene": true
+  },
+  "supabase": {
+    "publicRpcFunctions": ["get_public_data"],
+    "publicTables": ["public_lookup"]
+  },
+  "stability": {
+    "allowedVulnerabilities": {
+      "critical": 0,
+      "high": 0,
+      "moderate": 10
+    }
+  }
+}
+```
+
+## CLI Tools
+
+| Command | Description |
+|---------|-------------|
+| `tetra-audit` | Run quality/security/hygiene checks |
+| `tetra-setup` | Install hooks, CI, and config |
+| `tetra-dev-token` | Generate development tokens |
+
+## Changelog
+
+### 1.3.0 (2025-02-21)
+
+**New: Hygiene suite**
+- Added `tetra-audit hygiene` — detects stray docs, scripts, clutter in code dirs, root mess
+- Added `cleanup-repos.sh` auto-fix script in `bin/`
+- `tetra-setup hooks` now creates pre-push hook with hygiene gate
+- Re-running `tetra-setup hooks` on existing repos adds hygiene check without overwriting
+
+**New: RPC Param Mismatch check**
+- Added `rpc-param-mismatch` check in supabase suite
+- Statically compares `.rpc()` calls in TypeScript with SQL function parameter names
+- Catches PGRST202 errors before they hit production
+
+**Improved: File Organization health check**
+- Extended from 5pt to 6pt — added root clutter detection
+- Root clutter: `.txt`, `.png`, `.csv`, `.pdf`, `.py` files and `tmp/`, `logs/`, `data/` dirs
+- Gitignored dirs no longer counted as clutter
+- `CLAUDE.md` allowed anywhere (not just root)
+
+### 1.2.0
+
+- Initial public version
+- Security suite: hardcoded secrets, service key exposure, deprecated admin, systemdb whitelist, gitignore
+- Stability suite: husky hooks, CI pipeline, npm audit
+- Code quality suite: API response format
+- Supabase suite: RLS policy audit
+- Health checks: 16 checks, max 37pt
+- CLI: `tetra-audit`, `tetra-setup`, `tetra-dev-token`

package/bin/cleanup-repos.sh

@@ -0,0 +1,287 @@
+#!/bin/bash
+# =============================================================================
+# Repo Cleanup Script — Verplaats alles naar de juiste plek
+#
+# Wat het doet:
+# 1. Stray .md files → /docs/_moved/{oorspronkelijk-pad}/
+# 2. Stray .sh scripts → /scripts/_moved/{oorspronkelijk-pad}/
+# 3. Nested docs/ (frontend/docs/, backend/docs/) → /docs/{subdir-naam}/
+# 4. Root clutter files (.txt, .png, .csv, .py) → /docs/_cleanup/
+# 5. Code dir clutter (.txt, .log, .env) → /docs/_cleanup/{code-dir}/
+# 6. Clutter dirs (tmp/, logs/, data/, etc.) → .gitignore
+# 7. .env/.env.local in code dirs → verwijder (secrets horen niet in git)
+#
+# DRY RUN: standaard toont het alleen wat het zou doen.
+# EXECUTE: ./cleanup-repos.sh --execute
+# =============================================================================
+
+set -euo pipefail
+
+DRY_RUN=true
+[[ "${1:-}" == "--execute" ]] && DRY_RUN=false
+
+BASE="$HOME/projecten"
+PROJECTS=(sparkbuddy-live agentrook ralph-manager vincifox snelstart-mcp web-mcp)
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Counters
+TOTAL_MOVED=0
+TOTAL_GITIGNORED=0
+TOTAL_DELETED=0
+
+lower() { echo "$1" | tr '[:upper:]' '[:lower:]'; }
+
+log() { echo -e "${BLUE}[INFO]${NC} $1"; }
+warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+action() { echo -e "${GREEN}[MOVE]${NC} $1"; }
+danger() { echo -e "${RED}[DEL]${NC} $1"; }
+
+safe_move() {
+  local src="$1" dst="$2"
+
+  if $DRY_RUN; then
+    action "$src → $dst"
+  else
+    mkdir -p "$(dirname "$PROJECT_PATH/$dst")"
+    mv "$PROJECT_PATH/$src" "$PROJECT_PATH/$dst"
+  fi
+  TOTAL_MOVED=$((TOTAL_MOVED + 1))
+}
+
+safe_delete() {
+  local target="$1"
+  if $DRY_RUN; then
+    danger "DELETE $target"
+  else
+    rm -f "$target"
+  fi
+  TOTAL_DELETED=$((TOTAL_DELETED + 1))
+}
+
+add_gitignore() {
+  local project_path="$1" entry="$2"
+  local gitignore="$project_path/.gitignore"
+
+  if [ -f "$gitignore" ] && grep -qF "$entry" "$gitignore" 2>/dev/null; then
+    return
+  fi
+
+  if $DRY_RUN; then
+    log "Add to .gitignore: $entry"
+  else
+    echo "$entry" >> "$gitignore"
+  fi
+  TOTAL_GITIGNORED=$((TOTAL_GITIGNORED + 1))
+}
+
+is_allowed_root_md() {
+  local name_lc
+  name_lc=$(lower "$1")
+  case "$name_lc" in
+    readme.md|claude.md|changelog.md|license.md|prompt.md|plan.md|contributing.md|code_of_conduct.md)
+      return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# =============================================================================
+# Main cleanup per project
+# =============================================================================
+
+for PROJECT in "${PROJECTS[@]}"; do
+  PROJECT_PATH="$BASE/$PROJECT"
+  [ -d "$PROJECT_PATH" ] || continue
+
+  echo ""
+  echo "================================================================"
+  echo -e "${BLUE}=== $PROJECT ===${NC}"
+  echo "================================================================"
+
+  # --- 1. Nested docs/ → merge into /docs/{subdir-naam}/ (FIRST, before stray .md scan) ---
+  log "Checking nested docs/ directories..."
+  for subdir in frontend backend backend-mcp backend-pdf mcp shell; do
+    nested_docs="$PROJECT_PATH/$subdir/docs"
+    [ -d "$nested_docs" ] || continue
+
+    file_count=$(find "$nested_docs" -type f 2>/dev/null | wc -l | tr -d ' ')
+    [[ "$file_count" == "0" ]] && continue
+
+    log "Moving $subdir/docs/ ($file_count files) → docs/$subdir/"
+    while IFS= read -r -d '' file; do
+      rel_from_nested="${file#$nested_docs/}"
+      safe_move "$subdir/docs/$rel_from_nested" "docs/$subdir/$rel_from_nested"
+    done < <(find "$nested_docs" -type f -print0 2>/dev/null)
+  done
+
+  # --- 2. Stray .md files → /docs/_moved/ ---
+  log "Checking stray .md files..."
+  while IFS= read -r -d '' file; do
+    rel="${file#$PROJECT_PATH/}"
+    name=$(basename "$file")
+    name_lc=$(lower "$name")
+    top_dir="${rel%%/*}"
+
+    # Skip README.md and CLAUDE.md anywhere (standard practice)
+    case "$name_lc" in
+      readme.md|claude.md) continue ;;
+    esac
+
+    # Skip root allowed .md files
+    [[ "$rel" == "$name" ]] && is_allowed_root_md "$name" && continue
+
+    # Skip /docs/, .ralph/, .claude/, .agents/, e2e/
+    case "$top_dir" in
+      docs|.ralph|.claude|.agents|e2e) continue ;;
+    esac
+
+    # Skip shell/templates/
+    [[ "$rel" == shell/templates/* ]] && continue
+
+    # Skip files already handled by nested docs merge (avoid double-move)
+    [[ "$rel" == */docs/* ]] && continue
+
+    safe_move "$rel" "docs/_moved/$rel"
+  done < <(find "$PROJECT_PATH" -maxdepth 5 -name "*.md" -type f \
+    -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" \
+    -not -path "*/.next/*" -not -path "*/coverage/*" -print0 2>/dev/null)
+
+  # --- 3. Stray .sh scripts → /scripts/_moved/ ---
+  log "Checking stray .sh scripts..."
+  while IFS= read -r -d '' file; do
+    rel="${file#$PROJECT_PATH/}"
+    top_dir="${rel%%/*}"
+
+    # Skip root-level scripts
+    [[ "$rel" != */* ]] && continue
+
+    # Skip allowed dirs
+    case "$top_dir" in
+      scripts|shell|hooks|.husky|.ralph|.claude) continue ;;
+    esac
+
+    safe_move "$rel" "scripts/_moved/$rel"
+  done < <(find "$PROJECT_PATH" -maxdepth 5 -name "*.sh" -type f \
+    -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" \
+    -print0 2>/dev/null)
+
+  # --- 4. Root clutter files → /docs/_cleanup/ ---
+  log "Checking root clutter..."
+  for file in "$PROJECT_PATH"/*; do
+    [ -f "$file" ] || continue
+    name=$(basename "$file")
+    name_lc=$(lower "$name")
+
+    # Skip dotfiles
+    [[ "$name" == .* ]] && continue
+
+    # Skip known config extensions and types handled by other checks
+    case "$name_lc" in
+      *.json|*.js|*.cjs|*.mjs|*.ts|*.toml|*.lock) continue ;;
+      *.md|*.sh|*.yml|*.yaml) continue ;;
+      dockerfile*|procfile) continue ;;
+    esac
+
+    # Check for clutter extensions
+    ext=".${name_lc##*.}"
+    case "$ext" in
+      .txt|.log|.pdf|.csv|.png|.jpg|.jpeg|.gif|.py|.bak|.tmp|.orig|.patch|.diff)
+        safe_move "$name" "docs/_cleanup/$name"
+        ;;
+    esac
+  done
+
+  # --- 5. Code dir clutter → /docs/_cleanup/{code-dir}/ ---
+  log "Checking code dir clutter..."
+  for codeDir in backend frontend backend-mcp backend-pdf mcp; do
+    code_path="$PROJECT_PATH/$codeDir"
+    [ -d "$code_path" ] || continue
+
+    while IFS= read -r -d '' file; do
+      name=$(basename "$file")
+      name_lc=$(lower "$name")
+      rel="${file#$PROJECT_PATH/}"
+      rel_from_code="${file#$code_path/}"
+      sub_top="${rel_from_code%%/*}"
+
+      # Skip allowed subdirs
+      case "$sub_top" in
+        public|static|assets|fixtures|supabase|migrations|prisma|test-fixtures) continue ;;
+      esac
+
+      # .env files → DELETE (secrets!)
+      case "$name_lc" in
+        .env|.env.local|.env.development|.env.production|.env.staging)
+          danger "SECRET: $rel"
+          safe_delete "$file"
+          continue
+          ;;
+      esac
+
+      # Skip templates
+      case "$name_lc" in
+        *.example|*.test) continue ;;
+      esac
+
+      # Skip standard web files
+      case "$name_lc" in
+        robots.txt|llms.txt|llms-full.txt|humans.txt|security.txt|ads.txt) continue ;;
+      esac
+
+      # Check for clutter extensions
+      ext=".${name_lc##*.}"
+      case "$ext" in
+        .txt|.log|.pdf|.csv|.bak|.tmp|.orig|.patch|.diff)
+          safe_move "$rel" "docs/_cleanup/$rel"
+          ;;
+      esac
+    done < <(find "$code_path" -maxdepth 4 -type f \
+      -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.next/*" \
+      -not -path "*/coverage/*" -not -path "*/.turbo/*" -not -path "*/test-results/*" \
+      \( -name "*.txt" -o -name "*.log" -o -name "*.pdf" -o -name "*.csv" \
+         -o -name "*.bak" -o -name "*.tmp" -o -name "*.orig" \
+         -o -name ".env" -o -name ".env.*" \) -print0 2>/dev/null)
+  done
+
+  # --- 6. Clutter dirs → .gitignore ---
+  log "Checking clutter directories..."
+  for dir_name in tmp temp logs log data venv .venv reports output out backup backups; do
+    if [ -d "$PROJECT_PATH/$dir_name" ]; then
+      add_gitignore "$PROJECT_PATH" "$dir_name/"
+      warn "Directory $dir_name/ → added to .gitignore"
+    fi
+  done
+
+done
+
+# =============================================================================
+# Summary
+# =============================================================================
+
+echo ""
+echo "================================================================"
+if $DRY_RUN; then
+  echo -e "${YELLOW}DRY RUN COMPLETE${NC}"
+  echo "  Files to move:      $TOTAL_MOVED"
+  echo "  Files to delete:    $TOTAL_DELETED"
+  echo "  Gitignore entries:  $TOTAL_GITIGNORED"
+  echo ""
+  echo "Run with --execute to apply changes:"
+  echo "  bash cleanup-repos.sh --execute"
+else
+  echo -e "${GREEN}CLEANUP COMPLETE${NC}"
+  echo "  Files moved:        $TOTAL_MOVED"
+  echo "  Files deleted:      $TOTAL_DELETED"
+  echo "  Gitignore entries:  $TOTAL_GITIGNORED"
+  echo ""
+  echo "Next steps:"
+  echo "  1. Review /docs/_moved/ and /docs/_cleanup/ per project"
+  echo "  2. Delete what you don't need, keep what's useful"
+  echo "  3. git add + commit per project"
+fi
+echo "================================================================"

package/bin/tetra-audit.js

@@ -7,13 +7,14 @@
  *   tetra-audit              # Run all checks
  *   tetra-audit security     # Run security checks only
  *   tetra-audit stability    # Run stability checks only
+ *   tetra-audit hygiene      # Run repo hygiene checks only
  *   tetra-audit quick        # Run quick critical checks
  *   tetra-audit --ci         # CI mode (GitHub Actions annotations)
  *   tetra-audit --json       # JSON output
  */
 
 import { program } from 'commander'
-import { runAllChecks, runSecurityChecks, runStabilityChecks, runCodeQualityChecks, runQuickCheck } from '../lib/runner.js'
+import { runAllChecks, runSecurityChecks, runStabilityChecks, runCodeQualityChecks, runHygieneChecks, runQuickCheck } from '../lib/runner.js'
 import { formatResults, formatGitHubActions } from '../lib/reporters/terminal.js'
 
 program
@@ -40,6 +41,9 @@ program
         case 'code-quality':
           results = await runCodeQualityChecks()
           break
+        case 'hygiene':
+          results = await runHygieneChecks()
+          break
         case 'quick':
           results = await runQuickCheck()
           break

package/bin/tetra-setup.js

@@ -120,6 +120,39 @@ echo "✅ Pre-commit checks passed"
     console.log('   ⏭️  .husky/pre-commit already exists (use --force to overwrite)')
   }
 
+  // Create or extend pre-push hook with hygiene check
+  const prePushPath = join(huskyDir, 'pre-push')
+  const hygieneBlock = `
+# Tetra hygiene check — blocks push if repo contains clutter
+echo "🧹 Running repo hygiene check..."
+npx tetra-audit hygiene
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Repo hygiene issues found! Clean up before pushing."
+  echo "   Run 'npx tetra-audit hygiene --verbose' for details."
+  echo "   Run 'bash node_modules/@soulbatical/tetra-dev-toolkit/bin/cleanup-repos.sh' to auto-fix."
+  exit 1
+fi
+echo "✅ Repo hygiene passed"
+`
+
+  if (!existsSync(prePushPath)) {
+    // No pre-push hook yet — create one
+    const prePushContent = `#!/bin/sh\n${hygieneBlock}\n`
+    writeFileSync(prePushPath, prePushContent)
+    execSync(`chmod +x ${prePushPath}`)
+    console.log('   ✅ Created .husky/pre-push with hygiene check')
+  } else {
+    // Pre-push hook exists — add hygiene check if not already there
+    const existing = readFileSync(prePushPath, 'utf-8')
+    if (!existing.includes('tetra-audit hygiene')) {
+      writeFileSync(prePushPath, existing.trimEnd() + '\n' + hygieneBlock)
+      console.log('   ✅ Added hygiene check to existing .husky/pre-push')
+    } else {
+      console.log('   ⏭️  .husky/pre-push already has hygiene check')
+    }
+  }
+
   // Add prepare script to package.json
   if (!pkg.scripts?.prepare?.includes('husky')) {
     pkg.scripts = pkg.scripts || {}
@@ -194,7 +227,8 @@ async function setupConfig(options) {
         "security": true,
         "stability": true,
         "codeQuality": true,
-        "supabase": "auto"
+        "supabase": "auto",
+        "hygiene": true
       },
       "security": {
         "checkHardcodedSecrets": true,