forgedev 1.0.0

package/src/scanner.js

@@ -0,0 +1,368 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function scanProject(projectDir) {
+  const scan = {
+    stackId: null,
+    projectName: path.basename(projectDir),
+
+    frontend: detectFrontend(projectDir),
+    backend: detectBackend(projectDir),
+    database: detectDatabase(projectDir),
+    auth: detectAuth(projectDir),
+    testing: detectTesting(projectDir),
+    deployment: detectDeployment(projectDir),
+    ai: detectAI(projectDir),
+
+    infrastructure: {
+      hasClaudeMd: false,
+      claudeMdLines: 0,
+      hasHooks: false,
+      hasAgents: false,
+      hasCommands: false,
+      hasSkills: false,
+      hasUAT: false,
+    },
+
+    files: {
+      packageJson: fileExists(projectDir, 'package.json'),
+      requirementsTxt: fileExists(projectDir, 'requirements.txt') || fileExists(projectDir, 'backend/requirements.txt'),
+      prismaSchema: fileExists(projectDir, 'prisma/schema.prisma') || fileExists(projectDir, 'frontend/prisma/schema.prisma'),
+      alembicIni: fileExists(projectDir, 'alembic.ini') || fileExists(projectDir, 'backend/alembic.ini'),
+      dockerCompose: fileExists(projectDir, 'docker-compose.yml') || fileExists(projectDir, 'docker-compose.yaml'),
+      nextConfig: hasNextConfig(projectDir),
+      pyprojectToml: fileExists(projectDir, 'pyproject.toml') || fileExists(projectDir, 'backend/pyproject.toml'),
+    },
+  };
+
+  // Detect stack
+  scan.stackId = detectStack(projectDir, scan);
+
+  // Detect Claude infrastructure
+  scan.infrastructure = detectClaudeInfra(projectDir);
+
+  return scan;
+}
+
+export function detectStack(projectDir, scan) {
+  const hasNext = scan ? scan.files.nextConfig : hasNextConfig(projectDir);
+  const hasFastapi = scan ? scan.backend.detected && scan.backend.framework === 'fastapi' : detectBackend(projectDir).detected;
+  const hasFrontendNext = hasNext || fileExists(projectDir, 'frontend/next.config.ts') || fileExists(projectDir, 'frontend/next.config.js') || fileExists(projectDir, 'frontend/next.config.mjs');
+
+  if (hasFrontendNext && hasFastapi) {
+    return 'polyglot-fullstack';
+  }
+  if (hasNext && !hasFastapi) {
+    return 'nextjs-fullstack';
+  }
+  if (hasFastapi && !hasNext) {
+    return 'fastapi-backend';
+  }
+
+  // Try to detect from package.json
+  const pkg = readJsonSafe(projectDir, 'package.json');
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) return 'nextjs-fullstack';
+    if (deps.react) return 'nextjs-fullstack'; // best guess
+    if (deps.express) return 'nextjs-fullstack'; // close enough
+  }
+
+  // Try requirements.txt for Python
+  if (fileExists(projectDir, 'requirements.txt') || fileExists(projectDir, 'backend/requirements.txt')) {
+    const reqPath = fileExists(projectDir, 'requirements.txt')
+      ? path.join(projectDir, 'requirements.txt')
+      : path.join(projectDir, 'backend/requirements.txt');
+    const content = fs.readFileSync(reqPath, 'utf-8').toLowerCase();
+    if (content.includes('fastapi')) return 'fastapi-backend';
+  }
+
+  return 'unknown';
+}
+
+function detectFrontend(projectDir) {
+  const result = { detected: false, framework: null, language: null, directory: null };
+
+  // Check for Next.js
+  if (hasNextConfig(projectDir)) {
+    result.detected = true;
+    result.framework = 'nextjs';
+    result.language = fileExists(projectDir, 'tsconfig.json') ? 'typescript' : 'javascript';
+    result.directory = 'src';
+    return result;
+  }
+
+  // Check in frontend/ subdirectory
+  if (hasNextConfig(path.join(projectDir, 'frontend'))) {
+    result.detected = true;
+    result.framework = 'nextjs';
+    result.language = fileExists(path.join(projectDir, 'frontend'), 'tsconfig.json') ? 'typescript' : 'javascript';
+    result.directory = 'frontend';
+    return result;
+  }
+
+  // Check package.json for React
+  const pkg = readJsonSafe(projectDir, 'package.json');
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) {
+      result.detected = true;
+      result.framework = 'nextjs';
+      result.language = fileExists(projectDir, 'tsconfig.json') ? 'typescript' : 'javascript';
+      result.directory = 'src';
+    } else if (deps.react) {
+      result.detected = true;
+      result.framework = 'react';
+      result.language = fileExists(projectDir, 'tsconfig.json') ? 'typescript' : 'javascript';
+      result.directory = 'src';
+    }
+  }
+
+  return result;
+}
+
+function detectBackend(projectDir) {
+  const result = { detected: false, framework: null, language: null, directory: null };
+
+  // Check for FastAPI
+  const backendPaths = ['backend/app/main.py', 'app/main.py', 'main.py'];
+  for (const p of backendPaths) {
+    if (fileExists(projectDir, p)) {
+      const content = fs.readFileSync(path.join(projectDir, p), 'utf-8');
+      if (content.includes('FastAPI') || content.includes('fastapi')) {
+        result.detected = true;
+        result.framework = 'fastapi';
+        result.language = 'python';
+        result.directory = p.includes('backend/') ? 'backend' : '.';
+        return result;
+      }
+    }
+  }
+
+  // Check requirements.txt for FastAPI
+  const reqPaths = ['requirements.txt', 'backend/requirements.txt'];
+  for (const p of reqPaths) {
+    if (fileExists(projectDir, p)) {
+      const content = fs.readFileSync(path.join(projectDir, p), 'utf-8').toLowerCase();
+      if (content.includes('fastapi')) {
+        result.detected = true;
+        result.framework = 'fastapi';
+        result.language = 'python';
+        result.directory = p.includes('backend/') ? 'backend' : '.';
+        return result;
+      }
+      if (content.includes('flask')) {
+        result.detected = true;
+        result.framework = 'flask';
+        result.language = 'python';
+        result.directory = p.includes('backend/') ? 'backend' : '.';
+        return result;
+      }
+      if (content.includes('django')) {
+        result.detected = true;
+        result.framework = 'django';
+        result.language = 'python';
+        result.directory = p.includes('backend/') ? 'backend' : '.';
+        return result;
+      }
+    }
+  }
+
+  // Check for Express/Node backend
+  const pkg = readJsonSafe(projectDir, 'package.json');
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.express) {
+      result.detected = true;
+      result.framework = 'express';
+      result.language = 'typescript';
+      result.directory = 'src';
+    } else if (deps.hono) {
+      result.detected = true;
+      result.framework = 'hono';
+      result.language = 'typescript';
+      result.directory = 'src';
+    }
+  }
+
+  return result;
+}
+
+function detectDatabase(projectDir) {
+  const result = { detected: false, type: null, orm: null };
+
+  if (fileExists(projectDir, 'prisma/schema.prisma') || fileExists(projectDir, 'frontend/prisma/schema.prisma')) {
+    result.detected = true;
+    result.orm = 'prisma';
+    const schemaPath = fileExists(projectDir, 'prisma/schema.prisma')
+      ? path.join(projectDir, 'prisma/schema.prisma')
+      : path.join(projectDir, 'frontend/prisma/schema.prisma');
+    const content = fs.readFileSync(schemaPath, 'utf-8').toLowerCase();
+    result.type = content.includes('postgresql') ? 'postgresql' :
+                  content.includes('mysql') ? 'mysql' :
+                  content.includes('sqlite') ? 'sqlite' : 'postgresql';
+    return result;
+  }
+
+  if (fileExists(projectDir, 'alembic.ini') || fileExists(projectDir, 'backend/alembic.ini')) {
+    result.detected = true;
+    result.orm = 'sqlalchemy';
+    result.type = 'postgresql';
+    return result;
+  }
+
+  return result;
+}
+
+function detectAuth(projectDir) {
+  const result = { detected: false, type: null };
+
+  // NextAuth
+  if (fileExists(projectDir, 'src/lib/auth.ts') || fileExists(projectDir, 'src/lib/auth.js') ||
+      fileExists(projectDir, 'frontend/src/lib/auth.ts')) {
+    result.detected = true;
+    result.type = 'nextauth';
+    return result;
+  }
+
+  // JWT custom
+  if (fileExists(projectDir, 'backend/app/core/security.py') || fileExists(projectDir, 'app/core/security.py')) {
+    result.detected = true;
+    result.type = 'jwt-custom';
+    return result;
+  }
+
+  // Check package.json for auth packages
+  const pkg = readJsonSafe(projectDir, 'package.json');
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps['next-auth'] || deps['@auth/core']) {
+      result.detected = true;
+      result.type = 'nextauth';
+    } else if (deps.passport) {
+      result.detected = true;
+      result.type = 'passport';
+    }
+  }
+
+  return result;
+}
+
+function detectTesting(projectDir) {
+  const result = { unit: null, e2e: null, backend: null };
+
+  const pkg = readJsonSafe(projectDir, 'package.json');
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.vitest) result.unit = 'vitest';
+    else if (deps.jest) result.unit = 'jest';
+    if (deps['@playwright/test'] || deps.playwright) result.e2e = 'playwright';
+    else if (deps.cypress) result.e2e = 'cypress';
+  }
+
+  // Frontend subdir
+  const frontendPkg = readJsonSafe(path.join(projectDir, 'frontend'), 'package.json');
+  if (frontendPkg) {
+    const deps = { ...frontendPkg.dependencies, ...frontendPkg.devDependencies };
+    if (deps.vitest && !result.unit) result.unit = 'vitest';
+    if (deps['@playwright/test'] && !result.e2e) result.e2e = 'playwright';
+  }
+
+  // Python tests
+  if (fileExists(projectDir, 'backend/tests/conftest.py') || fileExists(projectDir, 'tests/conftest.py') ||
+      fileExists(projectDir, 'backend/pytest.ini') || fileExists(projectDir, 'pytest.ini')) {
+    result.backend = 'pytest';
+  }
+
+  return result;
+}
+
+function detectDeployment(projectDir) {
+  if (fileExists(projectDir, 'docker-compose.yml') || fileExists(projectDir, 'docker-compose.yaml')) return 'docker';
+  if (fileExists(projectDir, 'vercel.json')) return 'vercel';
+  if (fileExists(projectDir, 'Dockerfile')) return 'docker';
+  if (fileExists(projectDir, '.github/workflows')) return 'github-actions';
+  return null;
+}
+
+function detectAI(projectDir) {
+  // Check package.json
+  const pkg = readJsonSafe(projectDir, 'package.json');
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.openai || deps['@anthropic-ai/sdk'] || deps['@google/generative-ai'] || deps.ai) return true;
+  }
+
+  // Check requirements.txt
+  const reqPaths = ['requirements.txt', 'backend/requirements.txt'];
+  for (const p of reqPaths) {
+    if (fileExists(projectDir, p)) {
+      const content = fs.readFileSync(path.join(projectDir, p), 'utf-8').toLowerCase();
+      if (content.includes('openai') || content.includes('anthropic') || content.includes('google-generativeai') || content.includes('langchain')) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function detectClaudeInfra(projectDir) {
+  const infra = {
+    hasClaudeMd: false,
+    claudeMdLines: 0,
+    hasHooks: false,
+    hasAgents: false,
+    hasCommands: false,
+    hasSkills: false,
+    hasUAT: false,
+  };
+
+  if (fileExists(projectDir, 'CLAUDE.md')) {
+    infra.hasClaudeMd = true;
+    const content = fs.readFileSync(path.join(projectDir, 'CLAUDE.md'), 'utf-8');
+    infra.claudeMdLines = content.split('\n').length;
+  }
+
+  infra.hasHooks = fileExists(projectDir, '.claude/settings.json');
+  infra.hasAgents = dirHasFiles(projectDir, '.claude/agents');
+  infra.hasCommands = dirHasFiles(projectDir, '.claude/commands');
+  infra.hasSkills = dirHasFiles(projectDir, '.claude/skills');
+  infra.hasUAT = dirExists(projectDir, 'docs/uat');
+
+  return infra;
+}
+
+// Helpers
+
+function fileExists(base, ...segments) {
+  return fs.existsSync(path.join(base, ...segments));
+}
+
+function dirExists(base, ...segments) {
+  const p = path.join(base, ...segments);
+  return fs.existsSync(p) && fs.statSync(p).isDirectory();
+}
+
+function dirHasFiles(base, rel) {
+  const dir = path.join(base, rel);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
+  const entries = fs.readdirSync(dir);
+  return entries.length > 0;
+}
+
+function hasNextConfig(dir) {
+  return fileExists(dir, 'next.config.ts') ||
+         fileExists(dir, 'next.config.js') ||
+         fileExists(dir, 'next.config.mjs');
+}
+
+function readJsonSafe(base, file) {
+  const p = path.join(base, file);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}

package/src/uat-generator.js

@@ -0,0 +1,189 @@
+import { writeFile, ensureDir } from './utils.js';
+import path from 'node:path';
+
+export async function generateUAT(outputDir, stackConfig) {
+  const scenarios = buildScenarios(stackConfig);
+  generateUATTemplate(outputDir, stackConfig, scenarios);
+  generateUATChecklist(outputDir, scenarios);
+}
+
+function buildScenarios(config) {
+  const scenarios = [];
+  let id = 1;
+
+  // Health check — every project gets this
+  scenarios.push({
+    id: `UAT-${String(id++).padStart(3, '0')}`,
+    feature: 'Health Check',
+    priority: 'P0',
+    preconditions: 'Application is running',
+    steps: [
+      'Send GET request to the health endpoint',
+      'Verify response status is 200',
+      'Verify response body contains status: "ok"',
+    ],
+    expected: 'Health endpoint responds with 200 and status "ok"',
+  });
+
+  // Database connectivity
+  if (config.database) {
+    scenarios.push({
+      id: `UAT-${String(id++).padStart(3, '0')}`,
+      feature: 'Database Connectivity',
+      priority: 'P0',
+      preconditions: 'Application and database are running',
+      steps: [
+        'Send GET request to deep health endpoint (/healthz)',
+        'Verify response includes database status',
+        'Verify database status is "connected"',
+      ],
+      expected: 'Deep health check confirms database connectivity',
+    });
+  }
+
+  // Homepage (frontend projects)
+  if (config.frontend) {
+    scenarios.push({
+      id: `UAT-${String(id++).padStart(3, '0')}`,
+      feature: 'Home Page Load',
+      priority: 'P0',
+      preconditions: 'Application is running',
+      steps: [
+        'Navigate to the application root URL',
+        'Verify the page loads without errors',
+        'Verify the page title is correct',
+      ],
+      expected: 'Home page loads successfully with correct title',
+    });
+  }
+
+  // Authentication
+  if (config.auth) {
+    scenarios.push({
+      id: `UAT-${String(id++).padStart(3, '0')}`,
+      feature: 'User Registration',
+      priority: 'P0',
+      preconditions: 'Application is running, no existing test user',
+      steps: [
+        'Navigate to registration page',
+        'Fill in valid email, password, and name',
+        'Submit the registration form',
+        'Verify account is created successfully',
+      ],
+      expected: 'User account is created and user is authenticated',
+    });
+
+    scenarios.push({
+      id: `UAT-${String(id++).padStart(3, '0')}`,
+      feature: 'User Login',
+      priority: 'P0',
+      preconditions: 'Test user account exists',
+      steps: [
+        'Navigate to login page',
+        'Enter valid credentials',
+        'Submit the login form',
+        'Verify user is redirected to dashboard/home',
+      ],
+      expected: 'User is authenticated and redirected appropriately',
+    });
+
+    scenarios.push({
+      id: `UAT-${String(id++).padStart(3, '0')}`,
+      feature: 'Invalid Login',
+      priority: 'P1',
+      preconditions: 'Application is running',
+      steps: [
+        'Navigate to login page',
+        'Enter invalid credentials',
+        'Submit the login form',
+        'Verify error message is displayed',
+      ],
+      expected: 'User sees a generic error message, no sensitive info leaked',
+    });
+
+    if (config.frontend) {
+      scenarios.push({
+        id: `UAT-${String(id++).padStart(3, '0')}`,
+        feature: 'Protected Route Access',
+        priority: 'P1',
+        preconditions: 'User is not authenticated',
+        steps: [
+          'Navigate to a protected route (e.g., /dashboard)',
+          'Verify redirect to login page',
+          'Log in with valid credentials',
+          'Verify redirect back to protected route',
+        ],
+        expected: 'Unauthenticated users are redirected to login, then back after auth',
+      });
+    }
+  }
+
+  // Error handling
+  scenarios.push({
+    id: `UAT-${String(id++).padStart(3, '0')}`,
+    feature: 'Structured Error Response',
+    priority: 'P1',
+    preconditions: 'Application is running',
+    steps: [
+      'Send a request to a non-existent endpoint',
+      'Verify response has structured error format',
+      'Verify no stack traces or internal details are leaked',
+    ],
+    expected: 'Error response follows format: { error: { code, message } }',
+  });
+
+  // Graceful shutdown
+  scenarios.push({
+    id: `UAT-${String(id++).padStart(3, '0')}`,
+    feature: 'Graceful Shutdown',
+    priority: 'P1',
+    preconditions: 'Application is running with active connections',
+    steps: [
+      'Send SIGTERM to the application process',
+      'Verify in-flight requests complete',
+      'Verify database connections are closed',
+      'Verify process exits with code 0',
+    ],
+    expected: 'Application shuts down gracefully without dropping requests',
+  });
+
+  return scenarios;
+}
+
+function generateUATTemplate(outputDir, config, scenarios) {
+  let content = `# UAT Scenario Pack: ${config.projectName}\n\n`;
+  content += `## Pre-Conditions\n`;
+  content += `- [ ] Application is deployed to staging\n`;
+  content += `- [ ] Test accounts are created\n`;
+  content += `- [ ] Test data is seeded\n`;
+  if (config.database) {
+    content += `- [ ] Database is running and migrated\n`;
+  }
+  content += `\n## Scenarios\n`;
+
+  for (const s of scenarios) {
+    content += `\n### ${s.id}: ${s.feature}\n`;
+    content += `**Priority:** ${s.priority}\n`;
+    content += `**Preconditions:** ${s.preconditions}\n`;
+    content += `**Steps:**\n`;
+    s.steps.forEach((step, i) => {
+      content += `${i + 1}. ${step}\n`;
+    });
+    content += `**Expected Result:** ${s.expected}\n`;
+    content += `**Actual Result:** ___\n`;
+    content += `**Status:** NOT RUN\n`;
+    content += `**Tester:** ___\n`;
+    content += `**Date:** ___\n`;
+    content += `**Notes:** ___\n`;
+  }
+
+  writeFile(path.join(outputDir, 'docs', 'uat', 'UAT_TEMPLATE.md'), content);
+}
+
+function generateUATChecklist(outputDir, scenarios) {
+  let csv = 'UAT_ID,Feature,Priority,Status,Tester,Date,Defect_ID,Notes\n';
+  for (const s of scenarios) {
+    csv += `${s.id},${s.feature},${s.priority},NOT RUN,,,,\n`;
+  }
+  writeFile(path.join(outputDir, 'docs', 'uat', 'UAT_CHECKLIST.csv'), csv);
+}

package/src/utils.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const ROOT_DIR = path.resolve(__dirname, '..');
+
+export const log = {
+  info: (msg) => console.log(chalk.cyan(msg)),
+  success: (msg) => console.log(chalk.green(msg)),
+  warn: (msg) => console.log(chalk.yellow(msg)),
+  error: (msg) => console.error(chalk.red(msg)),
+  step: (n, total, msg) => console.log(chalk.blue(`[${n}/${total}] ${msg}`)),
+  dim: (msg) => console.log(chalk.dim(msg)),
+};
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function copyFile(src, dest) {
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+}
+
+export function writeFile(dest, content) {
+  ensureDir(path.dirname(dest));
+  fs.writeFileSync(dest, content, 'utf-8');
+}
+
+export function readTemplate(templatePath) {
+  return fs.readFileSync(templatePath, 'utf-8');
+}
+
+export function replaceVars(content, vars) {
+  return content.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return key in vars ? vars[key] : match;
+  });
+}
+
+export function toPascalCase(str) {
+  return str
+    .split(/[-_\s]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+}
+
+export function toSnakeCase(str) {
+  return str.replace(/[-\s]+/g, '_').toLowerCase();
+}
+
+export function toKebabCase(str) {
+  return str.replace(/[\s_]+/g, '-').toLowerCase();
+}

package/templates/auth/jwt-custom/backend/app/api/auth.py.template

@@ -0,0 +1,45 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, EmailStr
+
+from app.core.security import create_access_token, hash_password, verify_password
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+class LoginRequest(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class RegisterRequest(BaseModel):
+    email: EmailStr
+    password: str
+    name: str
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(request: LoginRequest):
+    # TODO: Replace with actual database lookup
+    # user = await get_user_by_email(request.email)
+    # if not user or not verify_password(request.password, user.hashed_password):
+    #     raise HTTPException(status_code=401, detail="Invalid credentials")
+    raise HTTPException(status_code=501, detail="Implement user lookup")
+
+    token = create_access_token(data={"sub": request.email})
+    return TokenResponse(access_token=token)
+
+
+@router.post("/register", response_model=TokenResponse)
+async def register(request: RegisterRequest):
+    # TODO: Replace with actual database operations
+    # hashed = hash_password(request.password)
+    # user = await create_user(email=request.email, name=request.name, hashed_password=hashed)
+    raise HTTPException(status_code=501, detail="Implement user creation")
+
+    token = create_access_token(data={"sub": request.email})
+    return TokenResponse(access_token=token)

package/templates/auth/jwt-custom/backend/app/api/deps.py.template

@@ -0,0 +1,16 @@
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from app.core.security import decode_access_token
+
+security = HTTPBearer()
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+) -> dict:
+    """Dependency that extracts and validates the current user from the JWT token."""
+    payload = decode_access_token(credentials.credentials)
+    if payload is None:
+        raise HTTPException(status_code=401, detail="Invalid or expired token")
+    return payload