@soulbatical/tetra-dev-toolkit 1.5.1 → 1.6.1

package/bin/tetra-init.js

@@ -0,0 +1,623 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Dev Toolkit - Project Init CLI
+ *
+ * Initializes a Tetra project with all required config files:
+ * - .ralph/ directory (ports.json, INFRASTRUCTURE.yml, MARKETING.yml, config.sh, status.json)
+ * - .tetra-quality.json
+ * - Verifies doppler.yaml and CLAUDE.md existence
+ *
+ * Usage:
+ *   tetra-init                    # Interactive full init
+ *   tetra-init ralph              # Only .ralph/ config files
+ *   tetra-init check              # Verify project completeness (no changes)
+ *   tetra-init --name myproject   # Non-interactive with project name
+ */
+
+import { program } from 'commander'
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs'
+import { join, basename } from 'path'
+import { createInterface } from 'readline'
+
+const projectRoot = process.cwd()
+
+// ─── Helpers ────────────────────────────────────────────────────
+
+function ask(question, defaultValue) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const prompt = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close()
+      resolve(answer.trim() || defaultValue || '')
+    })
+  })
+}
+
+function writeIfMissing(filePath, content, options = {}) {
+  const relativePath = filePath.replace(projectRoot + '/', '')
+  if (existsSync(filePath) && !options.force) {
+    console.log(`   ⏭️  ${relativePath} already exists`)
+    return false
+  }
+  const dir = filePath.substring(0, filePath.lastIndexOf('/'))
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+  writeFileSync(filePath, content)
+  console.log(`   ✅ Created ${relativePath}`)
+  return true
+}
+
+function detectProjectName() {
+  const packagePath = join(projectRoot, 'package.json')
+  if (existsSync(packagePath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'))
+      return pkg.name?.replace(/^@[^/]+\//, '') || basename(projectRoot)
+    } catch { /* ignore */ }
+  }
+  return basename(projectRoot)
+}
+
+function detectPorts() {
+  // Try to find ports from doppler.yaml or package.json scripts
+  const packagePath = join(projectRoot, 'package.json')
+  if (existsSync(packagePath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'))
+      const scripts = pkg.scripts || {}
+      const allScripts = Object.values(scripts).join(' ')
+
+      // Try to extract backend port from scripts
+      const backendPortMatch = allScripts.match(/PORT[=:](\d+)/) ||
+        allScripts.match(/-p\s+(\d+).*backend/) ||
+        allScripts.match(/backend.*-p\s+(\d+)/)
+
+      // Try to extract frontend port from scripts
+      const frontendPortMatch = allScripts.match(/next\s+dev\s+-p\s+(\d+)/) ||
+        allScripts.match(/-p\s+(\d+)/)
+
+      return {
+        backend: backendPortMatch ? parseInt(backendPortMatch[1]) : null,
+        frontend: frontendPortMatch ? parseInt(frontendPortMatch[1]) : null
+      }
+    } catch { /* ignore */ }
+  }
+  return { backend: null, frontend: null }
+}
+
+function detectSupabaseProjectId() {
+  // Check doppler.yaml or existing env references
+  const dopplerPath = join(projectRoot, 'doppler.yaml')
+  if (existsSync(dopplerPath)) {
+    return 'check-doppler' // User needs to fill in from Doppler
+  }
+  return null
+}
+
+function hasWorkspace(name) {
+  return existsSync(join(projectRoot, name))
+}
+
+// ─── Templates ──────────────────────────────────────────────────
+
+function generateInfrastructureYml(config) {
+  return `# ${config.name} Infrastructure Configuration
+# Single source of truth for all external services and infrastructure
+# Machine-readable by ralph-manager health checks
+
+project:
+  name: ${config.name}
+  phase: development
+  description: "${config.description}"
+  repo: null
+
+hosting:
+  frontend:
+    type: null
+    site_name: null
+    url: null
+    branch: main
+  backend:
+    type: null
+    service_name: null
+    url: null
+    branch: main
+
+domains:
+  registrar: null
+  primary: null
+  aliases: []
+  dns_provider: null
+  ssl: auto
+
+database:
+  provider: supabase
+  region: eu-central-1
+  project_id: null
+
+secrets:
+  manager: doppler
+  configs: []
+
+email:
+  provider: null
+  type: null
+  addresses: []
+
+monitoring:
+  uptime: null
+  error_tracking: null
+  analytics: null
+
+services:
+  payment: null
+  email_delivery: null
+  cdn: null
+
+security:
+  rls_enabled: true
+  auth_provider: supabase
+  rate_limiting: true
+  repo_visibility: private
+  open_issues: []
+
+meta:
+  created_at: "${new Date().toISOString().split('T')[0]}"
+  updated_by: tetra-init
+  version: 1
+`
+}
+
+function generateMarketingYml(config) {
+  return `# ${config.name} Marketing Stack Configuration
+# Single source of truth for marketing infrastructure status
+# Machine-readable by ralph-manager
+
+project: ${config.name}
+updated_at: "${new Date().toISOString().split('T')[0]}"
+updated_by: tetra-init
+
+# ─── Meta (Facebook/Instagram) ───────────────────────────────
+
+meta:
+  business_portfolio: null
+  business_portfolio_id: null
+  ad_account:
+    name: null
+    id: null
+    status: not_configured
+    currency: EUR
+  pixel:
+    name: null
+    id: null
+    status: not_configured
+    consent_mode: true
+    events: []
+  pages: []
+
+# ─── Google ──────────────────────────────────────────────────
+
+google:
+  analytics:
+    measurement_id: null
+    stream_id: null
+    status: not_configured
+    consent_mode: true
+  ads:
+    customer_id: null
+    status: not_configured
+  search_console:
+    verified: false
+    status: not_configured
+  tag_manager:
+    container_id: null
+    status: not_configured
+
+# ─── Consent & Privacy ──────────────────────────────────────
+
+consent:
+  platform: null
+  cookie_banner: false
+  privacy_policy: false
+  terms_of_service: false
+  gdpr_compliant: false
+
+# ─── SEO ────────────────────────────────────────────────────
+
+seo:
+  sitemap: false
+  robots_txt: false
+  structured_data: false
+  canonical_urls: false
+  meta_tags: false
+
+# ─── Email Marketing ────────────────────────────────────────
+
+email_marketing:
+  provider: null
+  list_id: null
+  status: not_configured
+
+meta_info:
+  created_at: "${new Date().toISOString().split('T')[0]}"
+  updated_by: tetra-init
+  version: 1
+`
+}
+
+function generatePortsJson(config) {
+  const obj = {
+    backend_port: config.backendPort,
+    frontend_port: config.frontendPort,
+    api_url: `http://localhost:${config.backendPort}`,
+    synced_at: new Date().toISOString(),
+    source: 'tetra-init'
+  }
+  return JSON.stringify(obj, null, 2) + '\n'
+}
+
+function generateConfigSh(config) {
+  return `# ${config.name} project config overrides for Ralph
+# Allowed tools for autonomous Ralph sessions
+CLAUDE_ALLOWED_TOOLS="Write,Edit,Read,Bash,Glob,Grep,WebFetch,WebSearch"
+`
+}
+
+function generateStatusJson() {
+  return JSON.stringify({
+    last_session: null,
+    last_task: null,
+    updated_at: new Date().toISOString()
+  }, null, 2) + '\n'
+}
+
+function generateFixPlan(config) {
+  return `# ${config.name} — Fix Plan
+
+## Active Tasks
+
+- [ ] Project initialization — verify all config files are correct
+- [ ] First feature implementation
+
+## Completed
+
+(none yet)
+`
+}
+
+function generatePromptMd(config) {
+  return `# Ralph Development Instructions - ${config.name}
+
+## Context
+You are Ralph, an AUTONOMOUS AI development agent working on **${config.name}**.
+
+## KRITIEKE REGEL: NOOIT VRAGEN, ALTIJD DOEN
+
+\`\`\`
+VERBODEN:
+- "Wat wil je als eerste oppakken?"
+- "Waar wil je mee beginnen?"
+- "Wil je dat ik X doe?"
+- Elke vraag aan de gebruiker over wat je moet doen
+
+VERPLICHT:
+- Kies ZELF de eerste onafgeronde taak uit @fix_plan.md
+- Voer die taak UIT in dezelfde loop
+- Vraag alleen om hulp als iets technisch ONMOGELIJK is
+\`\`\`
+
+## Sessie Opstart (loop 1)
+
+1. \`Read .ralph/@fix_plan.md\` — vind eerste \`- [ ]\` taak
+2. **BEGIN DIRECT met die taak** — niet samenvatten, niet vragen, DOEN
+3. Na afronding: vink af met [x], ga naar volgende taak
+
+## Na elke taak
+
+1. Vink de taak af in @fix_plan.md
+2. Ga naar de volgende \`- [ ]\` taak
+3. Als alles af is: schrijf samenvatting en stop
+`
+}
+
+function generateProjectJson(config) {
+  return JSON.stringify({
+    ralph_id: null,
+    name: config.name,
+    created_at: new Date().toISOString()
+  }, null, 2) + '\n'
+}
+
+function generateTestConfigYml(config) {
+  return `# ${config.name} Test Configuration
+# Used by Ralph for automated testing
+
+test_suites:
+  unit:
+    command: "npm test"
+    timeout: 120
+  typecheck:
+    command: "npx tsc --noEmit"
+    timeout: 60
+  e2e:
+    command: "npx playwright test"
+    timeout: 300
+    enabled: false
+
+health_checks:
+  backend:
+    url: "http://localhost:${config.backendPort}/api/health"
+    timeout: 5
+  frontend:
+    url: "http://localhost:${config.frontendPort}"
+    timeout: 10
+`
+}
+
+function generateTetraQualityJson() {
+  return JSON.stringify({
+    "$schema": "https://tetra-tools.dev/schemas/quality-toolkit.json",
+    "suites": {
+      "security": true,
+      "stability": true,
+      "codeQuality": true,
+      "supabase": "auto",
+      "hygiene": true
+    },
+    "security": {
+      "checkHardcodedSecrets": true,
+      "checkServiceKeyExposure": true
+    },
+    "stability": {
+      "requireHusky": true,
+      "requireCiConfig": true,
+      "allowedVulnerabilities": {
+        "critical": 0,
+        "high": 0,
+        "moderate": 10
+      }
+    },
+    "ignore": [
+      "node_modules/**",
+      "dist/**",
+      "build/**",
+      ".next/**"
+    ]
+  }, null, 2) + '\n'
+}
+
+// ─── Commands ───────────────────────────────────────────────────
+
+async function initRalph(config, options) {
+  console.log('')
+  console.log('📁 Initializing .ralph/ directory...')
+
+  const ralphDir = join(projectRoot, '.ralph')
+  if (!existsSync(ralphDir)) {
+    mkdirSync(ralphDir, { recursive: true })
+    console.log('   ✅ Created .ralph/')
+  }
+
+  // Specs directory
+  const specsDir = join(ralphDir, 'specs')
+  if (!existsSync(specsDir)) {
+    mkdirSync(specsDir, { recursive: true })
+    console.log('   ✅ Created .ralph/specs/')
+  }
+
+  writeIfMissing(join(ralphDir, 'ports.json'), generatePortsJson(config), options)
+  writeIfMissing(join(ralphDir, 'INFRASTRUCTURE.yml'), generateInfrastructureYml(config), options)
+  writeIfMissing(join(ralphDir, 'MARKETING.yml'), generateMarketingYml(config), options)
+  writeIfMissing(join(ralphDir, 'config.sh'), generateConfigSh(config), options)
+  writeIfMissing(join(ralphDir, 'status.json'), generateStatusJson(), options)
+  writeIfMissing(join(ralphDir, '@fix_plan.md'), generateFixPlan(config), options)
+  writeIfMissing(join(ralphDir, 'PROMPT.md'), generatePromptMd(config), options)
+  writeIfMissing(join(ralphDir, 'project.json'), generateProjectJson(config), options)
+  writeIfMissing(join(ralphDir, 'test-config.yml'), generateTestConfigYml(config), options)
+}
+
+async function initQuality(config, options) {
+  console.log('')
+  console.log('🔍 Initializing quality config...')
+
+  writeIfMissing(
+    join(projectRoot, '.tetra-quality.json'),
+    generateTetraQualityJson(),
+    options
+  )
+}
+
+function checkCompleteness() {
+  console.log('')
+  console.log('🔎 Checking project completeness...')
+  console.log('═'.repeat(50))
+
+  const checks = [
+    // Root files
+    { path: 'package.json', category: 'root', required: true },
+    { path: 'doppler.yaml', category: 'root', required: true },
+    { path: 'CLAUDE.md', category: 'root', required: true },
+    { path: '.tetra-quality.json', category: 'root', required: false },
+    { path: '.gitignore', category: 'root', required: true },
+
+    // .ralph/ files
+    { path: '.ralph/ports.json', category: 'ralph', required: true },
+    { path: '.ralph/INFRASTRUCTURE.yml', category: 'ralph', required: true },
+    { path: '.ralph/MARKETING.yml', category: 'ralph', required: false },
+    { path: '.ralph/config.sh', category: 'ralph', required: false },
+    { path: '.ralph/status.json', category: 'ralph', required: false },
+    { path: '.ralph/@fix_plan.md', category: 'ralph', required: true },
+    { path: '.ralph/PROMPT.md', category: 'ralph', required: true },
+    { path: '.ralph/project.json', category: 'ralph', required: true },
+    { path: '.ralph/test-config.yml', category: 'ralph', required: false },
+    { path: '.ralph/specs', category: 'ralph', required: false },
+
+    // Backend
+    { path: 'backend/package.json', category: 'backend', required: true },
+    { path: 'backend/tsconfig.json', category: 'backend', required: true },
+    { path: 'backend/src/index.ts', category: 'backend', required: true },
+    { path: 'backend/src/auth-config.ts', category: 'backend', required: true },
+    { path: 'backend/src/core/Application.ts', category: 'backend', required: true },
+    { path: 'backend/src/core/RouteManager.ts', category: 'backend', required: true },
+
+    // Frontend
+    { path: 'frontend/package.json', category: 'frontend', required: true },
+    { path: 'frontend/next.config.ts', category: 'frontend', required: true },
+    { path: 'frontend/src/app/layout.tsx', category: 'frontend', required: true },
+
+    // Database
+    { path: 'supabase/migrations', category: 'database', required: false },
+  ]
+
+  let currentCategory = ''
+  let passed = 0
+  let failed = 0
+  let warnings = 0
+
+  for (const check of checks) {
+    if (check.category !== currentCategory) {
+      currentCategory = check.category
+      console.log('')
+      console.log(`  ${currentCategory.toUpperCase()}`)
+    }
+
+    const fullPath = join(projectRoot, check.path)
+    const exists = existsSync(fullPath)
+    const icon = exists ? '✅' : (check.required ? '❌' : '⚠️')
+
+    if (exists) {
+      passed++
+    } else if (check.required) {
+      failed++
+    } else {
+      warnings++
+    }
+
+    console.log(`    ${icon} ${check.path}`)
+  }
+
+  console.log('')
+  console.log('═'.repeat(50))
+  console.log(`  ✅ ${passed} present  ❌ ${failed} missing (required)  ⚠️  ${warnings} missing (optional)`)
+
+  if (failed > 0) {
+    console.log('')
+    console.log('  Run `tetra-init` to generate missing files.')
+  } else if (warnings > 0) {
+    console.log('')
+    console.log('  All required files present! Run `tetra-init` to generate optional files.')
+  } else {
+    console.log('')
+    console.log('  🎉 Project is fully initialized!')
+  }
+
+  console.log('')
+  return failed === 0
+}
+
+// ─── Main ───────────────────────────────────────────────────────
+
+program
+  .name('tetra-init')
+  .description('Initialize a Tetra project with all required config files')
+  .version('1.0.0')
+  .argument('[component]', 'Component to init: ralph, quality, check, or all (default)')
+  .option('-n, --name <name>', 'Project name (skips interactive prompt)')
+  .option('-d, --description <desc>', 'Project description')
+  .option('--backend-port <port>', 'Backend port number', parseInt)
+  .option('--frontend-port <port>', 'Frontend port number', parseInt)
+  .option('-f, --force', 'Overwrite existing files')
+  .option('-y, --yes', 'Accept all defaults (non-interactive)')
+  .action(async (component, options) => {
+    console.log('')
+    console.log('🚀 Tetra Project Init')
+    console.log('═'.repeat(50))
+
+    // Check-only mode
+    if (component === 'check') {
+      const ok = checkCompleteness()
+      process.exit(ok ? 0 : 1)
+    }
+
+    // Gather config
+    const detectedName = detectProjectName()
+    const detectedPorts = detectPorts()
+    const isInteractive = !options.yes && process.stdin.isTTY
+
+    let config = {
+      name: options.name || detectedName,
+      description: options.description || '',
+      backendPort: options.backendPort || detectedPorts.backend,
+      frontendPort: options.frontendPort || detectedPorts.frontend,
+    }
+
+    if (isInteractive) {
+      console.log('')
+      config.name = await ask('Project name', config.name)
+      config.description = await ask('Description', config.description || `${config.name} platform`)
+      config.backendPort = parseInt(await ask('Backend port', String(config.backendPort || 3000))) || 3000
+      config.frontendPort = parseInt(await ask('Frontend port', String(config.frontendPort || 3001))) || 3001
+    } else {
+      // Non-interactive defaults
+      config.description = config.description || `${config.name} platform`
+      config.backendPort = config.backendPort || 3000
+      config.frontendPort = config.frontendPort || 3001
+    }
+
+    console.log('')
+    console.log(`  Project: ${config.name}`)
+    console.log(`  Backend: localhost:${config.backendPort}`)
+    console.log(`  Frontend: localhost:${config.frontendPort}`)
+
+    const components = component === 'all' || !component
+      ? ['ralph', 'quality']
+      : [component]
+
+    for (const comp of components) {
+      switch (comp) {
+        case 'ralph':
+          await initRalph(config, options)
+          break
+        case 'quality':
+          await initQuality(config, options)
+          break
+        default:
+          console.log(`Unknown component: ${comp}`)
+          console.log('Available: ralph, quality, check, or all (default)')
+      }
+    }
+
+    // Verify essential root files
+    console.log('')
+    console.log('📋 Checking essential root files...')
+
+    const essentials = [
+      { path: 'doppler.yaml', hint: 'Create doppler.yaml with your Doppler project config' },
+      { path: 'CLAUDE.md', hint: 'Create CLAUDE.md with project instructions for Claude Code' },
+      { path: '.gitignore', hint: 'Create .gitignore (node_modules, .next, dist, etc.)' },
+    ]
+
+    for (const item of essentials) {
+      const fullPath = join(projectRoot, item.path)
+      if (existsSync(fullPath)) {
+        console.log(`   ✅ ${item.path}`)
+      } else {
+        console.log(`   ⚠️  ${item.path} — ${item.hint}`)
+      }
+    }
+
+    console.log('')
+    console.log('✅ Init complete!')
+    console.log('')
+    console.log('Next steps:')
+    console.log('  1. Review generated files in .ralph/')
+    console.log('  2. Fill in INFRASTRUCTURE.yml with hosting/domain info')
+    console.log('  3. Run `tetra-init check` to verify completeness')
+    console.log('  4. Run `tetra-setup` to add quality hooks')
+    console.log('')
+  })
+
+program.parse()

package/lib/checks/index.js

@@ -16,6 +16,7 @@ export * as npmAudit from './stability/npm-audit.js'
 // Supabase checks
 export * as rlsPolicyAudit from './supabase/rls-policy-audit.js'
 export * as rpcParamMismatch from './supabase/rpc-param-mismatch.js'
+export * as rpcGeneratorOrigin from './supabase/rpc-generator-origin.js'
 
 // Health checks (project ecosystem)
 export * as health from './health/index.js'

package/lib/checks/supabase/rpc-generator-origin.js

@@ -0,0 +1,217 @@
+/**
+ * RPC Generator Origin Check
+ *
+ * Ensures that filter/count RPC functions (get_*_results, get_*_counts) are
+ * ONLY created via the SQL Generator, never hand-written.
+ *
+ * Origin: February 2026, SparkBuddy. Hand-editing SQL caused 30+ minutes of
+ * debugging when security blocks didn't match, search_path broke, and
+ * DO blocks/regex replacements on production failed silently. The only
+ * reliable path is: fix the config → regenerate via SQL Generator → deploy.
+ *
+ * Modes:
+ * - Pre-commit (default): Only checks git-staged files matching the pattern.
+ *   This avoids false positives on legacy files.
+ * - Full audit (config.rpcGeneratorOrigin.checkAll = true): Checks ALL files.
+ *   Use for comprehensive audits.
+ *
+ * This prevents:
+ * - Hand-written RPCs with wrong security patterns (accessLevel mismatch)
+ * - Missing public. prefix in search_path="" functions
+ * - Security blocks that don't match the generator's output
+ * - Silent breakage when generator overwrites manual edits on next run
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { join, relative } from 'path'
+import { execSync } from 'child_process'
+
+export const meta = {
+  id: 'rpc-generator-origin',
+  name: 'RPC Generator Origin',
+  category: 'supabase',
+  severity: 'critical',
+  description: 'Ensures get_*_results and get_*_counts SQL files are generated by the SQL Generator, not hand-written'
+}
+
+/**
+ * Pattern for files that MUST come from the SQL Generator
+ */
+const GENERATED_FILE_PATTERN = /get_\w+_(results|counts)\.sql$/
+
+/**
+ * Required header that the SQL Generator always includes
+ */
+const GENERATOR_HEADER = '-- Generator: SQL Generator'
+
+/**
+ * Alternative headers from older generator versions
+ */
+const LEGACY_HEADERS = [
+  '-- Generated by SQL Generator',
+  '-- Auto-generated by RPCGenerator',
+  '-- Generator: RPC Generator'
+]
+
+/**
+ * Try to get git-staged files matching our pattern.
+ * Returns null if git is not available or not in a repo.
+ */
+function getStagedFiles(projectRoot) {
+  try {
+    const output = execSync('git diff --cached --name-only --diff-filter=ACM', {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      timeout: 5000
+    }).trim()
+
+    if (!output) return []
+
+    return output.split('\n')
+      .filter(f => GENERATED_FILE_PATTERN.test(f))
+      .map(f => join(projectRoot, f))
+  } catch {
+    return null // Not a git repo or git not available
+  }
+}
+
+/**
+ * Get ALL matching files from migration directories
+ */
+function getAllFiles(config, projectRoot) {
+  const migrationPaths = [
+    ...(config.paths?.migrations || ['supabase/migrations', 'migrations']),
+    'backend/supabase/migrations'
+  ]
+
+  const sqlFiles = []
+  for (const relPath of migrationPaths) {
+    const dir = join(projectRoot, relPath)
+    if (!existsSync(dir)) continue
+    try {
+      const files = readdirSync(dir)
+        .filter(f => GENERATED_FILE_PATTERN.test(f))
+        .sort()
+      for (const f of files) {
+        sqlFiles.push(join(dir, f))
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // De-duplicate: keep only latest per function name
+  const latestByFunction = new Map()
+  for (const filePath of sqlFiles) {
+    const fileName = filePath.split('/').pop()
+    const funcMatch = fileName.match(/\d+_(get_\w+(?:_results|_counts))\.sql$/)
+    if (!funcMatch) continue
+    latestByFunction.set(funcMatch[1], filePath)
+  }
+
+  return [...latestByFunction.values()]
+}
+
+/**
+ * Check a single file for the generator header
+ */
+function checkFile(filePath, projectRoot) {
+  const relPath = relative(projectRoot, filePath)
+
+  let content
+  try {
+    content = readFileSync(filePath, 'utf-8').substring(0, 500)
+  } catch {
+    return null // Can't read
+  }
+
+  const hasCurrentHeader = content.includes(GENERATOR_HEADER)
+  const hasLegacyHeader = LEGACY_HEADERS.some(h => content.includes(h))
+
+  if (hasCurrentHeader || hasLegacyHeader) {
+    return { ok: true, file: relPath }
+  }
+
+  return {
+    ok: false,
+    file: relPath,
+    finding: {
+      file: relPath,
+      line: 1,
+      type: 'Hand-written RPC function',
+      severity: 'critical',
+      message: `${relPath} — Missing "-- Generator: SQL Generator" header. ` +
+        `This file appears to be hand-written. ` +
+        `RPC filter/count functions MUST be generated via: npm run generate:rpc <feature>. ` +
+        `Fix the feature config instead, then regenerate.`,
+      fix: [
+        '1. Find the feature config: backend/src/features/<feature>/config/<feature>.config.ts',
+        '2. Fix the config (accessLevel, customWhereClause, etc.)',
+        '3. Regenerate: cd backend && npm run generate:rpc <feature>',
+        '4. NEVER edit SQL files directly — the generator will overwrite your changes'
+      ].join('\n')
+    }
+  }
+}
+
+export async function run(config, projectRoot) {
+  const checkAll = config.rpcGeneratorOrigin?.checkAll === true
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {
+      mode: checkAll ? 'full' : 'staged',
+      filesChecked: 0,
+      filesWithHeader: 0,
+      filesWithoutHeader: 0
+    }
+  }
+
+  let filesToCheck
+
+  if (checkAll) {
+    // Full audit mode: check all files
+    filesToCheck = getAllFiles(config, projectRoot)
+  } else {
+    // Pre-commit mode: only staged files
+    const stagedFiles = getStagedFiles(projectRoot)
+
+    if (stagedFiles === null) {
+      // Not in a git repo — fall back to all files
+      filesToCheck = getAllFiles(config, projectRoot)
+      results.details.mode = 'full (no git)'
+    } else if (stagedFiles.length === 0) {
+      // No staged RPC files — nothing to check
+      results.details.mode = 'staged (no matching files)'
+      return results
+    } else {
+      filesToCheck = stagedFiles
+    }
+  }
+
+  if (filesToCheck.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No get_*_results/counts SQL files found'
+    return results
+  }
+
+  for (const filePath of filesToCheck) {
+    const result = checkFile(filePath, projectRoot)
+    if (!result) continue
+
+    results.details.filesChecked++
+
+    if (result.ok) {
+      results.details.filesWithHeader++
+    } else {
+      results.details.filesWithoutHeader++
+      results.passed = false
+      results.findings.push(result.finding)
+      results.summary.critical++
+      results.summary.total++
+    }
+  }
+
+  return results
+}

package/lib/runner.js

@@ -18,6 +18,7 @@ import * as apiResponseFormat from './checks/codeQuality/api-response-format.js'
 import * as gitignoreValidation from './checks/security/gitignore-validation.js'
 import * as rlsPolicyAudit from './checks/supabase/rls-policy-audit.js'
 import * as rpcParamMismatch from './checks/supabase/rpc-param-mismatch.js'
+import * as rpcGeneratorOrigin from './checks/supabase/rpc-generator-origin.js'
 import * as fileOrganization from './checks/hygiene/file-organization.js'
 
 // Register all checks
@@ -39,7 +40,8 @@ const ALL_CHECKS = {
   ],
   supabase: [
     rlsPolicyAudit,
-    rpcParamMismatch
+    rpcParamMismatch,
+    rpcGeneratorOrigin
   ],
   hygiene: [
     fileOrganization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "publishConfig": {
     "access": "restricted"
   },
@@ -26,6 +26,7 @@
   "main": "lib/index.js",
   "bin": {
     "tetra-audit": "./bin/tetra-audit.js",
+    "tetra-init": "./bin/tetra-init.js",
     "tetra-setup": "./bin/tetra-setup.js",
     "tetra-dev-token": "./bin/tetra-dev-token.js"
   },