trinity-method-sdk 2.0.9 → 2.2.0

package/dist/templates/trinity/templates/documentation/configuration/env-example-generator.md.template

@@ -0,0 +1,387 @@
+# .env.example Generator Template
+
+**Purpose:** Rule-based engine for generating sensible .env.example values from discovered environment variables.
+
+**Usage:** APO-3 reads this template and applies rules to each environment variable key discovered in the codebase.
+
+---
+
+## Instructions for APO-3
+
+This template provides a **rule-based engine** for generating sensible .env.example values. You MUST apply these rules in priority order to each discovered environment variable.
+
+**Critical Requirements:**
+- Apply rules in the order listed (Rule 1 has highest priority)
+- Stop at the first matching rule for each variable
+- NEVER create empty values (KEY= with no value)
+- All values must be sensible examples or placeholders
+
+---
+
+## Rule Priority Order
+
+### Rule 1: Database URLs (Highest Priority)
+
+**Pattern Match:**
+- Key contains "DATABASE" AND "URL"
+- Key contains "DB_URL"
+- Key equals "DATABASE_URL"
+
+**Generation Logic:**
+
+```javascript
+if (original_value.includes("file:")) {
+  // SQLite detected
+  example_value = original_value; // Keep SQLite paths (not sensitive)
+}
+else if (original_value.includes("postgresql") || original_value.includes("postgres")) {
+  example_value = "postgresql://user:password@localhost:5432/{{PROJECT_NAME}}_db";
+}
+else if (original_value.includes("mongodb") || original_value.includes("mongo")) {
+  example_value = "mongodb://localhost:27017/{{PROJECT_NAME}}_db";
+}
+else if (original_value.includes("mysql")) {
+  example_value = "mysql://user:password@localhost:3306/{{PROJECT_NAME}}_db";
+}
+else if (original_value.includes("redis")) {
+  example_value = "redis://localhost:6379";
+}
+else {
+  // Generic database URL fallback
+  example_value = "file:./dev.db"; // Safe SQLite default
+}
+```
+
+**Examples:**
+- `DATABASE_URL=postgresql://prod@aws.com/db` → `postgresql://user:password@localhost:5432/myapp_db`
+- `DATABASE_URL=file:./dev.db` → `file:./dev.db` (kept as-is)
+
+---
+
+### Rule 2: Port Numbers
+
+**Pattern Match:**
+- Key equals "PORT"
+- Key ends with "_PORT"
+
+**Generation Logic:**
+
+```javascript
+if (/^\d+$/.test(original_value)) {
+  // Original value is numeric - keep it (ports aren't sensitive)
+  example_value = original_value;
+}
+else {
+  // Non-numeric or missing - use sensible default
+  example_value = "3001"; // Common backend port
+}
+```
+
+**Examples:**
+- `PORT=3000` → `3000` (kept as-is)
+- `API_PORT=8080` → `8080` (kept as-is)
+- `PORT=` → `3001` (default)
+
+---
+
+### Rule 3: Frontend/CORS URLs
+
+**Pattern Match:**
+- Key contains "FRONTEND"
+- Key contains "ORIGIN"
+- Key contains "CLIENT_URL"
+- Key contains "CORS"
+
+**Generation Logic:**
+
+```javascript
+// Check if Next.js project
+if ({{FRAMEWORK}} === "Next.js" || exists("next.config.js")) {
+  example_value = "http://localhost:3000"; // Next.js default
+}
+// Check if Vite project
+else if (exists("vite.config.ts") || exists("vite.config.js")) {
+  example_value = "http://localhost:5173"; // Vite default
+}
+// Check if Create React App
+else if (exists("react-scripts") in package.json) {
+  example_value = "http://localhost:3000"; // CRA default
+}
+else {
+  example_value = "http://localhost:5173"; // Modern default (Vite)
+}
+```
+
+**Examples:**
+- `FRONTEND_URL=https://prod.app.com` → `http://localhost:5173`
+- `CORS_ORIGIN=*` → `http://localhost:3000` (if Next.js detected)
+
+---
+
+### Rule 4: API Keys
+
+**Pattern Match:**
+- Key contains "API_KEY"
+- Key contains "APIKEY"
+- Key ends with "_KEY" (but not SECRET or JWT)
+
+**Generation Logic:**
+
+```javascript
+// Extract service name from key (first word before underscore)
+const service_name = key.split('_')[0].toLowerCase();
+example_value = `your_${service_name}_api_key_here`;
+```
+
+**Examples:**
+- `STRIPE_API_KEY=sk_live_xxx` → `your_stripe_api_key_here`
+- `OPENAI_API_KEY=sk-xxx` → `your_openai_api_key_here`
+- `GITHUB_APIKEY=ghp_xxx` → `your_github_api_key_here`
+
+---
+
+### Rule 5: Client IDs (OAuth)
+
+**Pattern Match:**
+- Key contains "CLIENT_ID"
+- Key contains "APP_ID"
+
+**Generation Logic:**
+
+```javascript
+// Extract service name from key
+const service_name = key.split('_')[0].toLowerCase();
+example_value = `your_${service_name}_client_id_here`;
+```
+
+**Examples:**
+- `GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com` → `your_google_client_id_here`
+- `GITHUB_CLIENT_ID=Iv1.xxx` → `your_github_client_id_here`
+
+---
+
+### Rule 6: Client Secrets (OAuth)
+
+**Pattern Match:**
+- Key contains "SECRET"
+- Key contains "CLIENT_SECRET"
+- Key ends with "_SECRET" (but not JWT_SECRET)
+
+**Generation Logic:**
+
+```javascript
+// Extract service name from key
+const service_name = key.split('_')[0].toLowerCase();
+example_value = `your_${service_name}_client_secret_here`;
+```
+
+**Examples:**
+- `GOOGLE_CLIENT_SECRET=GOCSPX-xxx` → `your_google_client_secret_here`
+- `AWS_SECRET_ACCESS_KEY=xxx` → `your_aws_secret_access_key_here`
+
+---
+
+### Rule 7: OAuth Redirect URIs
+
+**Pattern Match:**
+- Key contains "REDIRECT" AND "URI"
+- Key contains "CALLBACK" AND "URL"
+
+**Generation Logic:**
+
+```javascript
+// Extract service name from key
+const service_name = key.match(/^([A-Z]+)_/)?.[1]?.toLowerCase() || "oauth";
+
+// Check discovered endpoints for matching callback route
+const callback_endpoint = {{DISCOVERED_ENDPOINTS}}.find(ep =>
+  ep.path.includes(service_name) && ep.path.includes("callback")
+);
+
+if (callback_endpoint) {
+  example_value = `http://localhost:{{PORT}}${callback_endpoint.path}`;
+}
+else {
+  example_value = `http://localhost:{{PORT}}/api/${service_name}/callback`;
+}
+```
+
+**Examples:**
+- `GOOGLE_REDIRECT_URI=https://prod.com/auth/google/callback` → `http://localhost:3001/api/auth/google/callback`
+- `OAUTH_CALLBACK_URL=https://prod.com/callback` → `http://localhost:3001/api/oauth/callback`
+
+---
+
+### Rule 8: JWT Secrets
+
+**Pattern Match:**
+- Key contains "JWT" AND "SECRET"
+- Key equals "JWT_SECRET"
+- Key equals "ACCESS_TOKEN_SECRET"
+- Key equals "REFRESH_TOKEN_SECRET"
+
+**Generation Logic:**
+
+```javascript
+example_value = "your_jwt_secret_key_here_min_32_chars";
+```
+
+**Examples:**
+- `JWT_SECRET=prod-secret-xxx` → `your_jwt_secret_key_here_min_32_chars`
+- `ACCESS_TOKEN_SECRET=xxx` → `your_jwt_secret_key_here_min_32_chars`
+
+---
+
+### Rule 9: Boolean Flags
+
+**Pattern Match:**
+- Original value is exactly "true" or "false" (case-insensitive)
+
+**Generation Logic:**
+
+```javascript
+// Keep original boolean value (not sensitive)
+example_value = original_value.toLowerCase();
+```
+
+**Examples:**
+- `DEBUG=true` → `true`
+- `ENABLE_LOGGING=false` → `false`
+
+---
+
+### Rule 10: Node Environment
+
+**Pattern Match:**
+- Key equals "NODE_ENV"
+
+**Generation Logic:**
+
+```javascript
+example_value = "development";
+```
+
+**Examples:**
+- `NODE_ENV=production` → `development`
+
+---
+
+### Rule 11: Default Fallback (Lowest Priority)
+
+**Pattern Match:**
+- No other rule matched
+
+**Generation Logic:**
+
+```javascript
+// Generate helpful TODO comment
+example_value = `# TODO: Add example value for ${key}`;
+```
+
+**Examples:**
+- `CUSTOM_CONFIG=xxx` → `# TODO: Add example value for CUSTOM_CONFIG`
+- `MY_SPECIAL_KEY=xxx` → `# TODO: Add example value for MY_SPECIAL_KEY`
+
+---
+
+## Enforcement Requirements
+
+**APO-3 MUST:**
+1. ✅ Apply these rules to EVERY environment variable
+2. ✅ Apply rules in priority order (stop at first match)
+3. ✅ NEVER create empty values (KEY= with no value)
+4. ✅ Use {{PROJECT_NAME}}, {{PORT}}, {{FRAMEWORK}} variables where applicable
+5. ✅ Check {{DISCOVERED_ENDPOINTS}} for OAuth callback routes
+
+**APO-3 MUST NOT:**
+1. ❌ Skip any environment variable keys
+2. ❌ Create keys with empty values
+3. ❌ Use production URLs or secrets in examples
+4. ❌ Ignore the rule priority order
+
+---
+
+## Validation
+
+**Phase 2.5 Validation 7 will verify:**
+- No empty values in .env.example
+- All keys from .env are present in .env.example
+- All values are sensible examples or placeholders
+- No production secrets leaked
+
+---
+
+## Variables from JUNO SECTION C
+
+APO-3 will receive these pre-filled variables from JUNO's audit report:
+
+- `{{PROJECT_NAME}}` - Project name
+- `{{PORT}}` - Discovered backend port
+- `{{FRAMEWORK}}` - Frontend framework (if detected)
+- `{{DISCOVERED_ENDPOINTS}}` - Array of API endpoint objects with path and method
+- `{{ENV_KEYS}}` - Array of environment variable keys discovered
+
+**Example JUNO SECTION C Structure:**
+
+```markdown
+## File 1: .env.example
+
+**Template:** .claude/trinity/templates/documentation/config/env-example-generator.md.template
+
+**Variables to Replace:**
+- {{PROJECT_NAME}}: "dnd-tool"
+- {{PORT}}: "3001"
+- {{FRAMEWORK}}: "React (Vite)"
+- {{DISCOVERED_ENDPOINTS}}: [...]
+- {{ENV_KEYS}}: ["DATABASE_URL", "PORT", "JWT_SECRET", "STRIPE_API_KEY", ...]
+
+**Output:** .env.example
+**Required:** YES
+```
+
+---
+
+## Usage Example
+
+**Input (from .env):**
+```
+DATABASE_URL=postgresql://prod@aws.rds.com/mydb
+PORT=3001
+FRONTEND_URL=https://app.production.com
+STRIPE_API_KEY=sk_live_xxxxxxxxxx
+GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxx
+JWT_SECRET=prod-secret-key-do-not-share
+DEBUG=true
+NODE_ENV=production
+```
+
+**Output (.env.example after applying rules):**
+```
+# Database Configuration
+DATABASE_URL=postgresql://user:password@localhost:5432/dnd_tool_db
+
+# Server Configuration
+PORT=3001
+NODE_ENV=development
+
+# Frontend Configuration
+FRONTEND_URL=http://localhost:5173
+
+# Stripe Integration
+STRIPE_API_KEY=your_stripe_api_key_here
+
+# Google OAuth
+GOOGLE_CLIENT_ID=your_google_client_id_here
+GOOGLE_CLIENT_SECRET=your_google_client_secret_here
+
+# Security
+JWT_SECRET=your_jwt_secret_key_here_min_32_chars
+
+# Development
+DEBUG=true
+```
+
+---
+
+**Last Updated:** {{GENERATION_DATE}}

package/dist/templates/trinity/templates/documentation/discovery/api-endpoint-scanner.md.template

@@ -0,0 +1,343 @@
+# API Endpoint Scanner Patterns
+**Category:** Discovery
+**Purpose:** Discover API routes and endpoints for Express, Fastify, NestJS, and Koa
+**Used By:** JUNO (Phase 1), APO-1 (API Diagrams), APO-2 (API Docs)
+
+---
+
+## Overview
+
+This template provides patterns for discovering API endpoints across popular Node.js backend frameworks.
+
+---
+
+## Route File Discovery
+
+### Common Route Locations
+
+```javascript
+const route_directories = [
+  "server/routes/",
+  "src/routes/",
+  "api/",
+  "server/api/",
+  "src/api/",
+  "app/routes/",
+  "routes/"
+];
+```
+
+### Route File Patterns
+
+```javascript
+const route_file_patterns = [
+  "**/*.routes.{ts,js}",
+  "**/*.route.{ts,js}",
+  "**/*.controller.{ts,js}",
+  "**/routes/**/*.{ts,js}",
+  "**/api/**/*.{ts,js}"
+];
+```
+
+---
+
+## Framework-Specific Patterns
+
+### Express.js
+
+**HTTP Method Patterns:**
+```javascript
+// Grep patterns for Express routes:
+- router.get('...')
+- router.post('...')
+- router.put('...')
+- router.patch('...')
+- router.delete('...')
+- app.get('...')
+- app.post('...')
+- router.route('...').get|post|put|patch|delete()
+- app.route('...').get|post|put|patch|delete()
+- router.all('...')
+```
+
+**Example extraction:**
+```javascript
+// From: router.get('/users/:id', userController.getUser);
+// Extract:
+{
+  method: 'GET',
+  path: '/users/:id',
+  file: 'server/routes/users.js'
+}
+```
+
+### Fastify
+
+**HTTP Method Patterns:**
+```javascript
+// Grep patterns for Fastify routes:
+- fastify.get('...')
+- fastify.post('...')
+- fastify.put('...')
+- fastify.patch('...')
+- fastify.delete('...')
+- app.get('...')
+- server.route({ method: 'GET', url: '...' })
+```
+
+### NestJS
+
+**Controller Decorator Patterns:**
+```javascript
+// Grep patterns for NestJS:
+- @Controller('...')
+- @Get('...')
+- @Post('...')
+- @Put('...')
+- @Patch('...')
+- @Delete('...')
+```
+
+**Example extraction:**
+```javascript
+// From:
+// @Controller('users')
+// class UserController {
+//   @Get(':id')
+//   getUser() {}
+// }
+//
+// Extract:
+{
+  method: 'GET',
+  path: '/users/:id',
+  file: 'src/users/users.controller.ts'
+}
+```
+
+### Koa
+
+**HTTP Method Patterns:**
+```javascript
+// Grep patterns for Koa routes:
+- router.get('...')
+- router.post('...')
+- router.put('...')
+- router.patch('...')
+- router.delete('...')
+```
+
+---
+
+## Endpoint Extraction Logic
+
+### Step 1: Find Route Files
+
+```javascript
+// Use Glob to find all route files
+const route_files = Glob(route_file_patterns);
+```
+
+### Step 2: Parse Each File for HTTP Methods
+
+```javascript
+// Use Grep to find HTTP method declarations
+const methods = ['get', 'post', 'put', 'patch', 'delete'];
+const endpoint_patterns = methods.map(m => `router\\.${m}\\(`);
+```
+
+### Step 3: Extract Path and Method
+
+```javascript
+// Example line: router.get('/users/:id', userController.getUser);
+// Parse with regex:
+const match = line.match(/router\.(get|post|put|patch|delete)\(['"](.+?)['"]/);
+if (match) {
+  const method = match[1].toUpperCase(); // "GET"
+  const path = match[2]; // "/users/:id"
+}
+```
+
+### Step 4: Group by Resource
+
+```javascript
+// Group endpoints by base resource:
+// /users, /users/:id, /users/:id/posts → "users" resource
+const resource = path.split('/')[1]; // First path segment
+```
+
+---
+
+## Template Variable Mapping
+
+**Variables to populate:**
+- `{{API_ENDPOINT_COUNT}}` → Total number of endpoints found
+- `{{API_RESOURCES}}` → Unique resource names (e.g., "users, posts, auth")
+- `{{API_ENDPOINTS}}` → List of [METHOD /path] pairs
+- `{{API_BASE_URL}}` → Base URL if detectable (e.g., "/api/v1")
+
+---
+
+## Endpoint Categorization
+
+### By HTTP Method
+
+```javascript
+const by_method = {
+  GET: [],    // Read operations
+  POST: [],   // Create operations
+  PUT: [],    // Update (full) operations
+  PATCH: [],  // Update (partial) operations
+  DELETE: []  // Delete operations
+};
+```
+
+### By Resource
+
+```javascript
+const by_resource = {
+  users: ['GET /users', 'POST /users', 'GET /users/:id'],
+  posts: ['GET /posts', 'POST /posts', 'DELETE /posts/:id'],
+  auth: ['POST /auth/login', 'POST /auth/logout']
+};
+```
+
+---
+
+## Verification Requirements
+
+### For APO-1 (API Endpoint Map Diagram)
+
+**Must provide:**
+1. HTTP method (GET/POST/PUT/PATCH/DELETE)
+2. Full endpoint path
+3. Resource grouping
+4. File location (for verification)
+
+**Example output for JUNO report:**
+```
+API Endpoints (12 total):
+
+Users Resource:
+- GET /users (list users)
+- POST /users (create user)
+- GET /users/:id (get user)
+- PUT /users/:id (update user)
+- DELETE /users/:id (delete user)
+
+Auth Resource:
+- POST /auth/login
+- POST /auth/logout
+- POST /auth/refresh
+```
+
+### For APO-2 (API Documentation)
+
+**Must provide:**
+1. Endpoint count
+2. Resource list
+3. Example endpoints for documentation
+
+---
+
+## Fallback Detection
+
+If no endpoints found with primary patterns:
+
+1. **Search for common route keywords:**
+   - Grep for: `app.use`, `router.use`, `@Controller`
+2. **Check server entry points:**
+   - Look for: `server.js`, `app.js`, `main.ts`, `index.ts`
+3. **Parse server configuration:**
+   - Find route mounting: `app.use('/api', apiRouter)`
+4. **Log warning:** "⚠️ No API endpoints found with standard patterns - may be frontend-only project"
+
+---
+
+## Base URL Detection
+
+### Common Patterns
+
+```javascript
+// Detect base URL from route mounting:
+// app.use('/api/v1', routes) → base = "/api/v1"
+// app.use('/api', routes) → base = "/api"
+
+const base_url_pattern = /app\.use\(['"](\/api[^'"]*)['"]/;
+```
+
+### Prefix Application
+
+```javascript
+// If base URL detected, prepend to all endpoints:
+const full_path = `${base_url}${endpoint_path}`;
+// Example: "/api/v1" + "/users" = "/api/v1/users"
+```
+
+---
+
+## Examples
+
+### Example 1: Express REST API
+
+```javascript
+// Route file: server/routes/users.js
+router.get('/users', userController.list);
+router.post('/users', userController.create);
+router.get('/users/:id', userController.get);
+router.put('/users/:id', userController.update);
+router.delete('/users/:id', userController.delete);
+
+// Extracted endpoints:
+API_ENDPOINT_COUNT = 5
+API_RESOURCES = "users"
+API_ENDPOINTS = [
+  "GET /users",
+  "POST /users",
+  "GET /users/:id",
+  "PUT /users/:id",
+  "DELETE /users/:id"
+]
+```
+
+### Example 2: NestJS API
+
+```javascript
+// Controller: src/users/users.controller.ts
+@Controller('users')
+export class UsersController {
+  @Get()
+  findAll() {}
+
+  @Get(':id')
+  findOne() {}
+
+  @Post()
+  create() {}
+}
+
+// Extracted endpoints:
+API_ENDPOINT_COUNT = 3
+API_RESOURCES = "users"
+API_BASE_URL = "/users"
+```
+
+---
+
+## Error Handling
+
+**No endpoints found:**
+- Log: "ℹ️ No API endpoints discovered - may be frontend-only project or static site"
+- Set `API_ENDPOINT_COUNT = 0`
+- Continue processing (not critical for frontend projects)
+
+**Too many endpoints (>50):**
+- Log: "ℹ️ Large API surface detected: [count] endpoints"
+- Provide full list to APO-1, summarize by resource in JUNO report
+
+**Malformed route syntax:**
+- Log: "⚠️ Could not parse route in [file]:[line] - skipping"
+- Continue with other endpoints
+
+---
+