@soulbatical/tetra-dev-toolkit 1.3.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/lib/checks/health/index.js

@@ -1,5 +1,5 @@
 /**
- * Health Checks — All 15 project health checks
+ * Health Checks — All 16 project health checks
  *
  * Main entry: scanProjectHealth(projectPath, projectName, options?)
  * Individual checks available via named imports.
@@ -25,3 +25,4 @@ export { check as checkClaudeMd } from './claude-md.js'
 export { check as checkDopplerCompliance } from './doppler-compliance.js'
 export { check as checkInfrastructureYml } from './infrastructure-yml.js'
 export { check as checkFileOrganization } from './file-organization.js'
+export { check as checkRpcParamMismatch } from './rpc-param-mismatch.js'

package/lib/checks/health/rpc-param-mismatch.js

@@ -0,0 +1,92 @@
+/**
+ * Health Check: RPC Parameter Mismatch
+ *
+ * Compares .rpc() calls in TypeScript with SQL function definitions
+ * to detect parameter name mismatches that cause PGRST202 runtime errors.
+ *
+ * Score: 3 (full) with deductions:
+ *   - Critical mismatch (extra param in TS): -1.5 per finding (max -3)
+ *   - Low (missing params): -0.25 per finding (max -1)
+ */
+
+import { createCheck } from './types.js'
+import { run as runAuditCheck } from '../supabase/rpc-param-mismatch.js'
+
+export async function check(projectPath) {
+  const result = createCheck('rpc-param-mismatch', 3, {
+    sqlFunctionsFound: 0,
+    rpcCallsFound: 0,
+    rpcCallsChecked: 0,
+    criticalMismatches: [],
+    missingParams: [],
+    message: ''
+  })
+  result.score = 3 // Start full, deduct for issues
+
+  // Re-use the audit check with default config paths
+  const config = {
+    paths: {
+      backend: ['backend/src', 'src'],
+      migrations: ['supabase/migrations', 'backend/supabase/migrations', 'migrations']
+    }
+  }
+
+  let auditResult
+  try {
+    auditResult = await runAuditCheck(config, projectPath)
+  } catch {
+    result.details.message = 'Failed to run RPC param mismatch check'
+    return result
+  }
+
+  if (auditResult.skipped) {
+    result.score = 3
+    result.details.message = auditResult.skipReason || 'Skipped'
+    return result
+  }
+
+  result.details.sqlFunctionsFound = auditResult.details.sqlFunctionsFound
+  result.details.rpcCallsFound = auditResult.details.rpcCallsFound
+  result.details.rpcCallsChecked = auditResult.details.rpcCallsChecked
+
+  // Process findings
+  const criticals = auditResult.findings.filter(f => f.severity === 'critical')
+  const lows = auditResult.findings.filter(f => f.severity === 'low')
+
+  result.details.criticalMismatches = criticals.map(f => ({
+    file: f.file,
+    line: f.line,
+    function: f.rpcFunction,
+    extraParams: f.extraInTs,
+    expectedParams: f.sqlParams
+  }))
+
+  result.details.missingParams = lows.map(f => ({
+    file: f.file,
+    line: f.line,
+    function: f.rpcFunction,
+    tsParamCount: f.tsParams?.length,
+    sqlParamCount: f.sqlParams?.length
+  }))
+
+  // Score deductions
+  if (criticals.length > 0) {
+    const deduction = Math.min(3, criticals.length * 1.5)
+    result.score -= deduction
+    result.status = 'error'
+    result.details.message = `${criticals.length} RPC parameter mismatch(es) — will cause PGRST202 runtime errors`
+  }
+
+  if (lows.length > 0 && result.status === 'ok') {
+    const deduction = Math.min(1, lows.length * 0.25)
+    result.score -= deduction
+    if (result.status === 'ok' && lows.length > 5) result.status = 'warning'
+  }
+
+  if (result.status === 'ok') {
+    result.details.message = `${auditResult.details.rpcCallsChecked} RPC calls verified against SQL definitions`
+  }
+
+  result.score = Math.max(0, result.score)
+  return result
+}

package/lib/checks/health/scanner.js

@@ -1,7 +1,7 @@
 /**
  * Project Health Scanner
  *
- * Orchestrates all 15 health checks and produces a HealthReport.
+ * Orchestrates all 16 health checks and produces a HealthReport.
  * This is the main entry point — consumers call scanProjectHealth().
  */
 
@@ -21,6 +21,7 @@ import { check as checkClaudeMd } from './claude-md.js'
 import { check as checkDopplerCompliance } from './doppler-compliance.js'
 import { check as checkInfrastructureYml } from './infrastructure-yml.js'
 import { check as checkFileOrganization } from './file-organization.js'
+import { check as checkRpcParamMismatch } from './rpc-param-mismatch.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -50,7 +51,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkClaudeMd(projectPath),
     checkDopplerCompliance(projectPath),
     checkInfrastructureYml(projectPath),
-    checkFileOrganization(projectPath)
+    checkFileOrganization(projectPath),
+    checkRpcParamMismatch(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/health/types.js

@@ -5,7 +5,7 @@
  */
 
 /**
- * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'} HealthCheckType
+ * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'rpc-param-mismatch'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *
@@ -66,7 +66,7 @@ export function calculateHealthStatus(checks) {
 
   // Critical checks override percentage
   if (checks.some(c =>
-    (c.type === 'secrets' || c.type === 'rls-audit' || c.type === 'repo-visibility') && c.status === 'error'
+    (c.type === 'secrets' || c.type === 'rls-audit' || c.type === 'rpc-param-mismatch' || c.type === 'repo-visibility') && c.status === 'error'
   )) {
     return 'unhealthy'
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "publishConfig": {
     "access": "restricted"
   },