forgedev 1.2.0 → 1.4.0

package/src/uat-generator.js

@@ -1,189 +1,204 @@
-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);
-}
+import { writeFile } 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);
+  generateBusinessRulesPlaceholder(outputDir, stackConfig);
+}
+
+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);
+}
+
+function generateBusinessRulesPlaceholder(outputDir, config) {
+  let content = `# Business Rules: ${config.projectName}\n\n`;
+  content += `Run \`/generate-uat\` inside Claude Code to populate this file with extracted business rules from your codebase.\n\n`;
+  content += `## How It Works\n`;
+  content += `The /generate-uat command reads your source code, extracts conditional logic and business rules,\n`;
+  content += `and generates testable assertions with boundary values.\n\n`;
+  content += `## Format\n`;
+  content += `Each rule will include:\n`;
+  content += `- **Source**: file path and line number\n`;
+  content += `- **Logic**: what the rule does\n`;
+  content += `- **Test cases**: input/output pairs with boundary values\n`;
+  writeFile(path.join(outputDir, 'docs', 'uat', 'BUSINESS_RULES.md'), content);
+}

package/src/update-check.js

@@ -21,9 +21,14 @@ export function compareVersions(a, b) {
  * Returns { current, latest, updateAvailable } or null on failure.
  */
 export async function checkForUpdate() {
-  const pkg = JSON.parse(
-    fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')
-  );
+  let pkg;
+  try {
+    pkg = JSON.parse(
+      fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')
+    );
+  } catch {
+    return null;
+  }
   const currentVersion = pkg.version;
 
   try {
@@ -43,7 +48,7 @@ export async function checkForUpdate() {
       latest: latestVersion,
       updateAvailable: compareVersions(latestVersion, currentVersion) > 0,
     };
-  } catch {
+  } catch { // Network or parse failure, skip update check silently
     return null;
   }
 }

package/src/update.js

@@ -1,10 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import chalk from 'chalk';
-import { log } from './utils.js';
-import { checkForUpdate } from './update-check.js';
+import { log, ROOT_DIR } from './utils.js';
+import { checkForUpdate, compareVersions } from './update-check.js';
+
+/**
+ * Check if the current directory has stale DevForge infrastructure.
+ * Returns { stale, installedVersion, cliVersion } or null if no infrastructure found.
+ */
+function checkInfrastructure(projectDir) {
+  const versionFile = path.join(projectDir, '.claude', '.devforge-version');
+  if (!fs.existsSync(versionFile)) {
+    return null;
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf-8'));
+  } catch {
+    return null;
+  }
+
+  try {
+    const installed = JSON.parse(fs.readFileSync(versionFile, 'utf-8'));
+    if (typeof installed.version !== 'string') return null;
+    const stale = compareVersions(pkg.version, installed.version) > 0;
+    return {
+      stale,
+      installedVersion: installed.version,
+      cliVersion: pkg.version,
+    };
+  } catch {
+    // Corrupted version file — treat as stale
+    return { stale: true, installedVersion: 'unknown', cliVersion: pkg.version };
+  }
+}
 
 export async function runUpdate() {
   console.log('');
-  console.log(chalk.bold.cyan('  DevForge') + chalk.dim(' — Checking for updates...'));
+  console.log(chalk.bold.cyan('  DevForge') + chalk.dim('  Checking for updates...'));
   console.log('');
 
   const result = await checkForUpdate();
@@ -18,16 +52,26 @@ export async function runUpdate() {
   if (!result.updateAvailable) {
     log.success(`  ✓ You're on the latest version (${result.current})`);
     console.log('');
-    return;
+  } else {
+    log.warn(`  Update available: ${result.current} → ${result.latest}`);
+    console.log('');
+    console.log('  To update:');
+    console.log(`    ${chalk.bold('npm install -g forgedev@latest')}   ${chalk.dim('(if installed globally)')}`);
+    console.log(`    ${chalk.bold('npx forgedev@latest new my-app')}  ${chalk.dim('(one-time use)')}`);
+    console.log('');
   }
 
-  log.warn(`  Update available: ${result.current} → ${result.latest}`);
-  console.log('');
-  console.log('  To update:');
-  console.log(`    ${chalk.bold('npm install -g forgedev@latest')}   ${chalk.dim('(if installed globally)')}`);
-  console.log(`    ${chalk.bold('npx forgedev@latest new my-app')}  ${chalk.dim('(one-time use)')}`);
-  console.log('');
-  log.dim('  To update an existing project\'s Claude Code infrastructure:');
-  log.dim('    cd my-project && npx forgedev@latest init');
-  console.log('');
+  // Check if current directory has stale DevForge infrastructure
+  const infra = checkInfrastructure(process.cwd());
+  if (infra && infra.stale) {
+    console.log(chalk.yellow('  ⚠ ') + chalk.bold('Project infrastructure is outdated'));
+    console.log(chalk.dim(`    Installed: v${infra.installedVersion}  →  CLI: v${infra.cliVersion}`));
+    console.log('');
+    console.log('  New commands, agents, and hooks are available but not deployed here.');
+    console.log(`  Run ${chalk.bold.cyan('npx forgedev init')} to sync this project's .claude/ infrastructure.`);
+    console.log('');
+  } else if (infra && !infra.stale) {
+    log.success(`  ✓ Project infrastructure is up to date (v${infra.installedVersion})`);
+    console.log('');
+  }
 }