@soulbatical/tetra-dev-toolkit 1.20.0 → 1.20.5

package/bin/tetra-init-tests.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Init Tests — Scaffold golden standard E2E test structure.
+ *
+ * Creates:
+ *   tests/e2e/helpers/api-client.ts    (HTTP client with X-Test-Key bypass)
+ *   tests/e2e/helpers/test-users.ts    (Login + token caching)
+ *   tests/e2e/01-auth.test.ts          (Auth: login, session, refresh, logout)
+ *   tests/e2e/07-security.test.ts      (Auth walls + role access)
+ *   vitest.config.e2e.ts               (Vitest config for E2E)
+ *
+ * Usage:
+ *   tetra-init-tests                   # Interactive
+ *   tetra-init-tests --force           # Overwrite existing files
+ */
+
+import { program } from 'commander'
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const TEMPLATES_DIR = join(__dirname, '..', 'lib', 'templates', 'tests')
+
+function copyTemplate(templateName, destPath, force = false) {
+  if (existsSync(destPath) && !force) {
+    console.log(`  ⏩ ${destPath} (exists, use --force to overwrite)`)
+    return false
+  }
+
+  const templatePath = join(TEMPLATES_DIR, templateName)
+  if (!existsSync(templatePath)) {
+    console.log(`  ❌ Template not found: ${templateName}`)
+    return false
+  }
+
+  const content = readFileSync(templatePath, 'utf-8')
+  mkdirSync(dirname(destPath), { recursive: true })
+  writeFileSync(destPath, content)
+  console.log(`  ✅ ${destPath}`)
+  return true
+}
+
+function writeFile(destPath, content, force = false) {
+  if (existsSync(destPath) && !force) {
+    console.log(`  ⏩ ${destPath} (exists)`)
+    return false
+  }
+  mkdirSync(dirname(destPath), { recursive: true })
+  writeFileSync(destPath, content)
+  console.log(`  ✅ ${destPath}`)
+  return true
+}
+
+program
+  .name('tetra-init-tests')
+  .description('Scaffold Tetra golden standard E2E test structure')
+  .option('--force', 'Overwrite existing files')
+  .option('--dir <path>', 'Test directory (default: tests/e2e)', 'tests/e2e')
+  .action((options) => {
+    const root = process.cwd()
+    const testDir = join(root, options.dir)
+    const helpersDir = join(testDir, 'helpers')
+    const force = !!options.force
+
+    console.log('\n  Tetra Init Tests — Golden Standard E2E\n')
+
+    // 1. Helpers
+    console.log('  Helpers:')
+    copyTemplate('api-client.ts.tmpl', join(helpersDir, 'api-client.ts'), force)
+    copyTemplate('test-users.ts.tmpl', join(helpersDir, 'test-users.ts'), force)
+
+    // 2. Test files
+    console.log('\n  Test files:')
+    copyTemplate('01-auth.test.ts.tmpl', join(testDir, '01-auth.test.ts'), force)
+    copyTemplate('07-security.test.ts.tmpl', join(testDir, '07-security.test.ts'), force)
+
+    // 3. Vitest config
+    console.log('\n  Config:')
+    writeFile(join(root, 'vitest.config.e2e.ts'), `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['${options.dir}/**/*.test.ts'],
+    globalSetup: './${options.dir}/global-setup.ts',
+    testTimeout: 30000,
+    hookTimeout: 60000,
+    sequence: { concurrent: false },
+  },
+});
+`, force)
+
+    // 4. Global setup stub
+    writeFile(join(testDir, 'global-setup.ts'), `/**
+ * Global setup — creates test users via API before all tests.
+ * CUSTOMIZE: implement signup + invite flow for your project.
+ *
+ * Required env vars (set these in your test runner or CI):
+ *   E2E_BASE_URL          — Backend URL (e.g. http://localhost:3026)
+ *   RATE_LIMIT_BYPASS_KEY — X-Test-Key value (from .ralph/test-config.yml)
+ *
+ * This setup should:
+ * 1. Create an admin via signup
+ * 2. Create a shared resource (track/project/workspace)
+ * 3. Invite an elevated user (coach/manager)
+ * 4. Invite a basic user (client/member)
+ * 5. Store IDs/emails in process.env for test-users.ts
+ */
+
+const BASE_URL = process.env.E2E_BASE_URL!;
+const PASSWORD = 'TestPass1234';
+
+export async function setup() {
+  // TODO: Implement for your project
+  // See CoachHub's global-setup.ts as reference
+  console.log('\\n  ⚠️  global-setup.ts is a stub — implement for your project\\n');
+}
+
+export async function teardown() {
+  // Best-effort cleanup
+}
+`, force)
+
+    // Summary
+    console.log(`
+  Done! Next steps:
+
+  1. Implement global-setup.ts (create test users via your API)
+  2. Set E2E_BASE_URL and RATE_LIMIT_BYPASS_KEY in your env
+  3. Customize 07-security.test.ts with your protected routes
+  4. Add project-specific test files (02-*.test.ts, 03-*.test.ts, etc.)
+  5. Run: npx vitest run --config vitest.config.e2e.ts
+
+  Golden standard pattern:
+    01-auth         — login, session, refresh, logout (universal)
+    02-[resource]   — main resource CRUD + permissions
+    03-[nested]     — nested resources (messages, notes, etc.)
+    04-admin        — admin-only features
+    05-[feature]    — feature-specific tests
+    06-planner      — scheduling (if using Tetra Planner)
+    07-security     — auth walls + role access (universal)
+    08-permissions   — permission matrix (generatable)
+    09-isolation    — cross-role data isolation
+    10+             — additional features
+`)
+  })
+
+program.parse()

package/lib/checks/security/config-rls-alignment.js

@@ -115,7 +115,7 @@ function parseMigrations(projectRoot) {
       const relFile = file.replace(projectRoot + '/', '')
 
       // Handle DROP POLICY — removes policy from earlier migration
-      const dropPolicyMatches = content.matchAll(/DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?"?([^";\s]+)"?\s+ON\s+(?:public\.)?(\w+)/gi)
+      const dropPolicyMatches = content.matchAll(/DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?"([^"]+)"\s+ON\s+(?:public\.)?(\w+)/gi)
       for (const m of dropPolicyMatches) {
         const policyName = m[1]
         const table = m[2]

package/lib/checks/security/rpc-security-mode.js

@@ -82,6 +82,9 @@ export async function run(config, projectRoot) {
   const userWhitelist = (config.supabase?.securityDefinerWhitelist || [])
   const whitelist = new Set([...BUILTIN_DEFINER_WHITELIST, ...userWhitelist])
 
+  // Sort files by name (timestamp order) so later migrations override earlier ones
+  sqlFiles.sort()
+
   // Track latest definition per function (migrations can override)
   const functions = new Map() // funcName → { securityMode, file, line, isDataQuery }
 
@@ -91,6 +94,22 @@ export async function run(config, projectRoot) {
 
     const relFile = file.replace(projectRoot + '/', '')
 
+    // Handle DROP FUNCTION — removes function from tracking
+    const dropFuncMatches = content.matchAll(/DROP\s+FUNCTION\s+(?:IF\s+EXISTS\s+)?(?:public\.)?(\w+)/gi)
+    for (const m of dropFuncMatches) {
+      functions.delete(m[1])
+    }
+
+    // Handle ALTER FUNCTION ... SECURITY INVOKER/DEFINER — overrides security mode
+    const alterFuncMatches = content.matchAll(/ALTER\s+FUNCTION\s+(?:public\.)?(\w+)(?:\s*\([^)]*\))?\s+SECURITY\s+(INVOKER|DEFINER)/gi)
+    for (const m of alterFuncMatches) {
+      const existing = functions.get(m[1])
+      if (existing) {
+        existing.securityMode = m[2].toUpperCase()
+        existing.file = relFile
+      }
+    }
+
     // Find all CREATE [OR REPLACE] FUNCTION statements
     const funcRegex = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?(\w+)\s*\(/gi
     let match

package/lib/templates/tests/01-auth.test.ts.tmpl

@@ -0,0 +1,127 @@
+/**
+ * Auth E2E tests — signup, login, session, refresh, logout.
+ * Tetra golden standard — works for any Tetra project.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { get, post } from './helpers/api-client';
+import { getTestContext, loginTestUser, type TestContext } from './helpers/test-users';
+
+let ctx: TestContext;
+
+beforeAll(async () => {
+  ctx = await getTestContext();
+});
+
+describe('Auth: Users created with correct roles', () => {
+  it('admin exists with valid token', () => {
+    expect(ctx.admin.id).toBeTruthy();
+    expect(ctx.admin.token).toBeTruthy();
+    expect(ctx.admin.role).toBe('admin');
+  });
+
+  it('elevated user exists with valid token', () => {
+    expect(ctx.elevated.id).toBeTruthy();
+    expect(ctx.elevated.token).toBeTruthy();
+  });
+
+  it('basic user exists with valid token', () => {
+    expect(ctx.basic.id).toBeTruthy();
+    expect(ctx.basic.token).toBeTruthy();
+  });
+});
+
+describe('Auth: Login', () => {
+  it('logs in admin', async () => {
+    const tokens = await loginTestUser(ctx.admin.email);
+    expect(tokens.token).toBeTruthy();
+    expect(tokens.refreshToken).toBeTruthy();
+  });
+
+  it('rejects wrong password', async () => {
+    const res = await post('/api/public/auth/login', {
+      email: ctx.admin.email,
+      password: 'WrongPassword9999',
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects nonexistent email', async () => {
+    const res = await post('/api/public/auth/login', {
+      email: 'nonexistent@test.dev',
+      password: 'TestPass1234',
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects missing fields', async () => {
+    const res = await post('/api/public/auth/login', {});
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('Auth: Session', () => {
+  it('validates a valid token', async () => {
+    const res = await get<any>('/api/public/auth/session', ctx.admin.token);
+    expect(res.status).toBe(200);
+  });
+
+  it('rejects invalid token', async () => {
+    const res = await get('/api/public/auth/session', 'invalid-token');
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects missing token', async () => {
+    const res = await get('/api/public/auth/session');
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('Auth: Refresh', () => {
+  it('refreshes a valid token', async () => {
+    const res = await post<any>('/api/public/auth/refresh', {
+      refresh_token: ctx.admin.refreshToken,
+    });
+    expect(res.status).toBe(200);
+    expect(res.data.data?.access_token).toBeTruthy();
+    ctx.admin.token = res.data.data.access_token;
+    ctx.admin.refreshToken = res.data.data.refresh_token;
+  });
+
+  it('rejects invalid refresh token', async () => {
+    const res = await post('/api/public/auth/refresh', {
+      refresh_token: 'invalid',
+    });
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('Auth: Me', () => {
+  it('returns admin profile', async () => {
+    const res = await get<any>('/api/public/auth/me', ctx.admin.token);
+    expect(res.status).toBe(200);
+    expect(res.data.data?.role).toBe('admin');
+  });
+});
+
+describe('Auth: Logout', () => {
+  it('logs out successfully', async () => {
+    const tokens = await loginTestUser(ctx.elevated.email);
+    const res = await post<any>('/api/public/auth/logout', {}, tokens.token);
+    expect(res.status).toBe(200);
+  });
+});
+
+describe('Auth: Error format', () => {
+  it('401 returns RFC 7807', async () => {
+    const res = await get<any>('/api/tracks');
+    expect(res.status).toBe(401);
+    expect(res.data.type).toBeTruthy();
+    expect(res.data.status).toBe(401);
+  });
+
+  it('404 returns RFC 7807', async () => {
+    const res = await get<any>('/api/nonexistent-e2e', ctx.admin.token);
+    expect(res.status).toBe(404);
+    expect(res.data.type).toBeTruthy();
+  });
+});

package/lib/templates/tests/07-security.test.ts.tmpl

@@ -0,0 +1,93 @@
+/**
+ * Security E2E tests — auth walls + role-based access.
+ * Tetra golden standard — auto-reads protected routes from project config.
+ *
+ * CUSTOMIZE: Update protectedRoutes and role access tests for your project.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { get, post, del, api } from './helpers/api-client';
+import { getTestContext, type TestContext } from './helpers/test-users';
+
+let ctx: TestContext;
+
+beforeAll(async () => {
+  ctx = await getTestContext();
+}, 60000);
+
+// ── Auth walls: all protected routes require token ────────────
+// CUSTOMIZE: add all your protected API routes here
+
+const protectedRoutes = [
+  '/api/tracks',
+  '/api/users',
+  '/api/admin/dashboard',
+  '/api/permissions/my',
+  // Add project-specific routes below:
+];
+
+describe('Security: Auth walls', () => {
+  for (const route of protectedRoutes) {
+    it(`${route} returns 401 without auth`, async () => {
+      const res = await get(route);
+      expect(res.status).toBe(401);
+    });
+  }
+});
+
+describe('Security: Invalid tokens', () => {
+  it('rejects malformed JWT', async () => {
+    const res = await get('/api/tracks', 'eyJhbGciOiJIUzI1NiJ9.fake.fake');
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects empty Authorization header', async () => {
+    const res = await api('/api/tracks', { headers: { 'Authorization': '' } });
+    expect(res.status).toBe(401);
+  });
+});
+
+// ── Role-based access ─────────────────────────────────────────
+// CUSTOMIZE: update for your project's roles and admin endpoints
+
+describe('Security: Basic user cannot access admin endpoints', () => {
+  it('basic CANNOT access /api/admin/dashboard', async () => {
+    const res = await get('/api/admin/dashboard', ctx.basic.token);
+    expect(res.status).toBe(403);
+  });
+
+  it('basic CANNOT list users', async () => {
+    const res = await get('/api/users', ctx.basic.token);
+    expect(res.status).toBe(403);
+  });
+
+  it('basic CANNOT delete another user', async () => {
+    const res = await del(`/api/users/${ctx.admin.id}`, ctx.basic.token);
+    expect(res.status).toBe(403);
+  });
+});
+
+describe('Security: Elevated user cannot access admin-only endpoints', () => {
+  it('elevated CANNOT access /api/admin/dashboard', async () => {
+    const res = await get('/api/admin/dashboard', ctx.elevated.token);
+    expect(res.status).toBe(403);
+  });
+
+  it('elevated CANNOT delete another user', async () => {
+    const res = await del(`/api/users/${ctx.admin.id}`, ctx.elevated.token);
+    expect(res.status).toBe(403);
+  });
+});
+
+// ── Public routes: accessible without auth ────────────────────
+
+describe('Security: Public routes', () => {
+  it('/api/health is public', async () => {
+    const res = await get('/api/health');
+    expect(res.status).toBe(200);
+  });
+
+  it('/api/version is public', async () => {
+    const res = await get('/api/version');
+    expect(res.status).toBe(200);
+  });
+});

package/lib/templates/tests/api-client.ts.tmpl

@@ -0,0 +1,75 @@
+/**
+ * Lightweight HTTP client for E2E tests.
+ * Tetra golden standard — generated by tetra init-tests.
+ *
+ * Features:
+ * - X-Test-Key header bypass for rate limiting
+ * - Simple get/post/put/del convenience methods
+ * - No dependencies — just fetch
+ */
+
+const BASE_URL = () => process.env.E2E_BASE_URL!;
+const TEST_KEY = () => process.env.RATE_LIMIT_BYPASS_KEY || '';
+
+interface RequestOptions {
+  method?: string;
+  body?: Record<string, unknown>;
+  token?: string;
+  headers?: Record<string, string>;
+}
+
+interface ApiResponse<T = unknown> {
+  status: number;
+  data: T;
+  raw: Response;
+}
+
+export async function api<T = unknown>(
+  path: string,
+  options: RequestOptions = {}
+): Promise<ApiResponse<T>> {
+  const { method = 'GET', body, token, headers: extraHeaders } = options;
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    ...extraHeaders,
+  };
+
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  // Bypass rate limiting in test runs
+  const testKey = TEST_KEY();
+  if (testKey) {
+    headers['X-Test-Key'] = testKey;
+  }
+
+  const url = `${BASE_URL()}${path}`;
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  let data: T;
+  try {
+    data = await res.json() as T;
+  } catch {
+    data = {} as T;
+  }
+
+  return { status: res.status, data, raw: res };
+}
+
+export const get = <T = unknown>(path: string, token?: string) =>
+  api<T>(path, { token });
+
+export const post = <T = unknown>(path: string, body: Record<string, unknown>, token?: string) =>
+  api<T>(path, { method: 'POST', body, token });
+
+export const put = <T = unknown>(path: string, body: Record<string, unknown>, token?: string) =>
+  api<T>(path, { method: 'PUT', body, token });
+
+export const del = <T = unknown>(path: string, token?: string) =>
+  api<T>(path, { method: 'DELETE', token });

package/lib/templates/tests/test-users.ts.tmpl

@@ -0,0 +1,86 @@
+/**
+ * Test user context — reads from env vars set by global-setup.
+ * Tetra golden standard — generated by tetra init-tests.
+ *
+ * Users are in the SAME organization with real roles:
+ * - admin: created via signup (org owner)
+ * - coach/manager: invited with elevated role
+ * - client/member: invited with basic role
+ */
+
+import { post } from './api-client';
+
+export interface TestUser {
+  id: string;
+  email: string;
+  name: string;
+  role: string;
+  token: string;
+  refreshToken: string;
+}
+
+export interface TestContext {
+  admin: TestUser;
+  elevated: TestUser;  // coach, manager, editor — depends on project
+  basic: TestUser;     // client, member, viewer — depends on project
+  trackId: string;     // shared resource ID (track, project, workspace, etc.)
+}
+
+let cachedContext: TestContext | null = null;
+
+async function login(email: string): Promise<{ token: string; refreshToken: string }> {
+  const res = await post<any>('/api/public/auth/login', {
+    email,
+    password: process.env.E2E_PASSWORD || 'TestPass1234',
+  });
+
+  if (res.status !== 200 || !res.data?.data?.access_token) {
+    throw new Error(`Login failed for ${email}: ${res.status} ${JSON.stringify(res.data)}`);
+  }
+
+  return {
+    token: res.data.data.access_token,
+    refreshToken: res.data.data.refresh_token,
+  };
+}
+
+export async function getTestContext(): Promise<TestContext> {
+  if (cachedContext) return cachedContext;
+
+  const [adminTokens, elevatedTokens, basicTokens] = await Promise.all([
+    login(process.env.E2E_ADMIN_EMAIL!),
+    login(process.env.E2E_ELEVATED_EMAIL!),
+    login(process.env.E2E_BASIC_EMAIL!),
+  ]);
+
+  cachedContext = {
+    admin: {
+      id: process.env.E2E_ADMIN_ID!,
+      email: process.env.E2E_ADMIN_EMAIL!,
+      name: 'E2E Admin',
+      role: 'admin',
+      ...adminTokens,
+    },
+    elevated: {
+      id: process.env.E2E_ELEVATED_ID!,
+      email: process.env.E2E_ELEVATED_EMAIL!,
+      name: 'E2E Elevated',
+      role: process.env.E2E_ELEVATED_ROLE || 'coach',
+      ...elevatedTokens,
+    },
+    basic: {
+      id: process.env.E2E_BASIC_ID!,
+      email: process.env.E2E_BASIC_EMAIL!,
+      name: 'E2E Basic',
+      role: process.env.E2E_BASIC_ROLE || 'client',
+      ...basicTokens,
+    },
+    trackId: process.env.E2E_TRACK_ID!,
+  };
+
+  return cachedContext;
+}
+
+export async function loginTestUser(email: string): Promise<{ token: string; refreshToken: string }> {
+  return login(email);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.20.0",
+  "version": "1.20.5",
   "publishConfig": {
     "access": "restricted"
   },
@@ -34,7 +34,8 @@
     "tetra-db-push": "./bin/tetra-db-push.js",
     "tetra-check-peers": "./bin/tetra-check-peers.js",
     "tetra-security-gate": "./bin/tetra-security-gate.js",
-    "tetra-smoke": "./bin/tetra-smoke.js"
+    "tetra-smoke": "./bin/tetra-smoke.js",
+    "tetra-init-tests": "./bin/tetra-init-tests.js"
   },
   "files": [
     "bin/",