popeye-cli 1.4.7 → 1.6.0

package/src/generators/website-debug.ts

@@ -0,0 +1,130 @@
+/**
+ * Debug tracing for website generation pipeline
+ * Enabled via POPEYE_DEBUG_WEBSITE=1 environment variable
+ * Shows exactly which value came from where during website generation
+ */
+
+/**
+ * Structured trace of website generation pipeline decisions
+ */
+export interface WebsiteDebugTrace {
+  workspaceRoot: string;
+  docsFound: Array<{ path: string; size: number }>;
+  brandAssets: { logoPath?: string; logoOutputPath: string };
+  productName: { value: string; source: 'docs' | 'spec' | 'package.json' | 'directory' };
+  primaryColor: { value?: string; source: 'brand-docs' | 'frontend' | 'defaults' };
+  strategyStatus: 'success' | 'failed' | 'skipped';
+  strategyError?: string;
+  feDesignAnalysis?: { componentLib?: string; darkMode: boolean; primaryColor?: string };
+  templateValues: { headline?: string; features: number; pricingTiers: number };
+  /** Sections rendered with their data sources */
+  sectionsRendered: Array<{
+    name: string;
+    dataSource: 'strategy' | 'docs' | 'defaults' | 'skipped';
+    itemCount: number;
+  }>;
+  /** Validation result from quality gate */
+  validationPassed: boolean;
+  validationIssues: string[];
+}
+
+/**
+ * Check if debug tracing is enabled
+ *
+ * @returns True if POPEYE_DEBUG_WEBSITE=1 is set
+ */
+export function isDebugEnabled(): boolean {
+  return process.env.POPEYE_DEBUG_WEBSITE === '1';
+}
+
+/**
+ * Format a debug trace for terminal output
+ *
+ * @param trace - The debug trace to format
+ * @returns Formatted string for terminal output
+ */
+export function formatDebugTrace(trace: WebsiteDebugTrace): string {
+  const lines: string[] = [];
+
+  lines.push('');
+  lines.push('=== WEBSITE GENERATION DEBUG TRACE ===');
+  lines.push('');
+
+  lines.push(`Workspace Root: ${trace.workspaceRoot}`);
+  lines.push('');
+
+  lines.push(`Docs Found (${trace.docsFound.length}):`);
+  if (trace.docsFound.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const doc of trace.docsFound) {
+      lines.push(`  - ${doc.path} (${doc.size} chars)`);
+    }
+  }
+  lines.push('');
+
+  lines.push(`Brand Assets:`);
+  lines.push(`  Logo Source: ${trace.brandAssets.logoPath || '(none)'}`);
+  lines.push(`  Logo Output: ${trace.brandAssets.logoOutputPath}`);
+  lines.push('');
+
+  lines.push(`Product Name: "${trace.productName.value}" (from: ${trace.productName.source})`);
+  lines.push('');
+
+  lines.push(`Primary Color: ${trace.primaryColor.value || '(default)'} (from: ${trace.primaryColor.source})`);
+  lines.push('');
+
+  lines.push(`Strategy: ${trace.strategyStatus}`);
+  if (trace.strategyError) {
+    lines.push(`  Error: ${trace.strategyError}`);
+  }
+  lines.push('');
+
+  if (trace.feDesignAnalysis) {
+    lines.push('Frontend Design Analysis:');
+    lines.push(`  Component Library: ${trace.feDesignAnalysis.componentLib || '(unknown)'}`);
+    lines.push(`  Dark Mode: ${trace.feDesignAnalysis.darkMode}`);
+    lines.push(`  Primary Color: ${trace.feDesignAnalysis.primaryColor || '(none)'}`);
+    lines.push('');
+  }
+
+  lines.push('Template Values:');
+  lines.push(`  Headline: ${trace.templateValues.headline || '(default)'}`);
+  lines.push(`  Features: ${trace.templateValues.features}`);
+  lines.push(`  Pricing Tiers: ${trace.templateValues.pricingTiers}`);
+  lines.push('');
+
+  lines.push(`Sections Rendered (${trace.sectionsRendered.length}):`);
+  if (trace.sectionsRendered.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const section of trace.sectionsRendered) {
+      lines.push(`  - ${section.name}: ${section.dataSource} (${section.itemCount} items)`);
+    }
+  }
+  lines.push('');
+
+  lines.push(`Validation: ${trace.validationPassed ? 'PASSED' : 'FAILED'}`);
+  if (trace.validationIssues.length > 0) {
+    for (const issue of trace.validationIssues) {
+      lines.push(`  - ${issue}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('=== END DEBUG TRACE ===');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Print debug trace to console if debug mode is enabled
+ *
+ * @param trace - The debug trace to print
+ */
+export function printDebugTrace(trace: WebsiteDebugTrace): void {
+  if (isDebugEnabled()) {
+    console.log(formatDebugTrace(trace));
+  }
+}

package/src/generators/website.ts

@@ -7,27 +7,51 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import type { ProjectSpec } from '../types/project.js';
 import {
-  generateWebsitePackageJson,
-  generateNextConfig,
-  generateWebsiteTsconfig,
-  generateWebsiteTailwindConfig,
-  generateWebsitePostcssConfig,
   generateWebsiteLayout,
   generateWebsiteGlobalsCss,
   generateWebsiteLandingPage,
   generateWebsitePricingPage,
-  generateWebsiteSitemap,
-  generateWebsiteRobots,
-  generateWebsiteDockerfile,
   generateWebsiteReadme,
   generateWebsiteSpec,
-  generateWebsiteVitestConfig,
-  generateWebsiteVitestSetup,
   generateWebsiteTest,
   generateWebsiteDocsPage,
   generateWebsiteBlogPage,
-  generateWebsiteNextEnv,
 } from './templates/website.js';
+import {
+  generateWebsitePackageJson,
+  generateNextConfig,
+  generateWebsiteTsconfig,
+  generateWebsiteTailwindConfig,
+  generateWebsitePostcssConfig,
+  generateWebsiteDockerfile,
+  generateWebsiteVitestConfig,
+  generateWebsiteVitestSetup,
+  generateWebsiteNextEnv,
+} from './templates/website-config.js';
+import {
+  generateWebsiteHeader,
+  generateWebsiteFooter,
+  generateWebsiteNavigation,
+} from './templates/website-components.js';
+import {
+  generateJsonLdComponent,
+  generateEnhancedSitemap,
+  generateEnhancedRobots,
+  generate404Page,
+  generate500Page,
+  generateWebManifest,
+  generateMetaHelper,
+} from './templates/website-seo.js';
+import {
+  generateLeadCaptureRoute,
+  generateContactForm,
+  generateLeadCaptureEnvExample,
+} from './templates/website-conversion.js';
+import type { WebsiteContentContext } from './website-context.js';
+import { validateWebsiteContextOrThrow } from './website-context.js';
+import { scanGeneratedContent } from './website-content-scanner.js';
+import { printDebugTrace, isDebugEnabled } from './website-debug.js';
+import type { WebsiteDebugTrace } from './website-debug.js';
 
 /**
  * Project generation result
@@ -53,6 +77,10 @@ export interface WebsiteGeneratorOptions {
   skipDocker?: boolean;
   /** Skip README (fullstack has root README) */
   skipReadme?: boolean;
+  /** Content context from user docs for populating templates */
+  contentContext?: WebsiteContentContext;
+  /** Skip content validation (scaffold-only use) */
+  skipValidation?: boolean;
 }
 
 /**
@@ -88,6 +116,8 @@ export async function generateWebsiteProject(
     workspaceMode = false,
     skipDocker = false,
     skipReadme = false,
+    contentContext,
+    skipValidation = false,
   } = options;
 
   const projectName = spec.name || 'my-project';
@@ -103,11 +133,13 @@ export async function generateWebsiteProject(
     await ensureDir(path.join(projectDir, 'src', 'app', 'pricing'));
     await ensureDir(path.join(projectDir, 'src', 'app', 'docs'));
     await ensureDir(path.join(projectDir, 'src', 'app', 'blog'));
+    await ensureDir(path.join(projectDir, 'src', 'app', 'api', 'lead'));
     await ensureDir(path.join(projectDir, 'src', 'components'));
     await ensureDir(path.join(projectDir, 'src', 'lib'));
     await ensureDir(path.join(projectDir, 'content', 'blog'));
     await ensureDir(path.join(projectDir, 'content', 'docs'));
     await ensureDir(path.join(projectDir, 'public'));
+    await ensureDir(path.join(projectDir, 'public', 'brand'));
     await ensureDir(path.join(projectDir, 'tests'));
 
     // Only create .popeye dir in standalone mode
@@ -115,6 +147,51 @@ export async function generateWebsiteProject(
       await ensureDir(path.join(projectDir, '.popeye'));
     }
 
+    // Validate content context quality gate
+    if (!skipValidation) {
+      const validationContext = contentContext || {
+        productName: projectName,
+        features: [],
+        rawDocs: '',
+      };
+      validateWebsiteContextOrThrow(validationContext, projectName);
+    }
+
+    // Debug trace
+    if (isDebugEnabled() && contentContext) {
+      const trace: WebsiteDebugTrace = {
+        workspaceRoot: projectDir,
+        docsFound: contentContext.rawDocs
+          ? contentContext.rawDocs.split(/^--- .+ ---$/m).filter(Boolean).map((s, i) => ({
+              path: `doc-${i}`,
+              size: s.length,
+            }))
+          : [],
+        brandAssets: {
+          logoPath: contentContext.brand?.logoPath,
+          logoOutputPath: contentContext.brandAssets?.logoOutputPath || 'public/brand/logo.svg',
+        },
+        productName: {
+          value: contentContext.productName,
+          source: contentContext.rawDocs ? 'docs' : 'directory',
+        },
+        primaryColor: {
+          value: contentContext.brand?.primaryColor,
+          source: contentContext.brand?.primaryColor ? 'brand-docs' : 'defaults',
+        },
+        strategyStatus: contentContext.strategy ? 'success' : 'skipped',
+        templateValues: {
+          headline: contentContext.strategy?.messaging.headline,
+          features: contentContext.features.length,
+          pricingTiers: contentContext.pricing?.length || 0,
+        },
+        sectionsRendered: [],
+        validationPassed: true,
+        validationIssues: [],
+      };
+      printDebugTrace(trace);
+    }
+
     // Generate and write files
     const files: Array<{ path: string; content: string }> = [
       // Config files
@@ -132,7 +209,11 @@ export async function generateWebsiteProject(
       },
       {
         path: path.join(projectDir, 'tailwind.config.ts'),
-        content: generateWebsiteTailwindConfig(),
+        content: generateWebsiteTailwindConfig({
+          primaryColor: contentContext?.brand?.primaryColor,
+          workspaceMode,
+          projectName: workspaceMode ? projectName : undefined,
+        }),
       },
       {
         path: path.join(projectDir, 'postcss.config.js'),
@@ -150,19 +231,19 @@ export async function generateWebsiteProject(
       // App Router files
       {
         path: path.join(projectDir, 'src', 'app', 'layout.tsx'),
-        content: generateWebsiteLayout(projectName),
+        content: generateWebsiteLayout(projectName, contentContext),
       },
       {
         path: path.join(projectDir, 'src', 'app', 'globals.css'),
-        content: generateWebsiteGlobalsCss(),
+        content: generateWebsiteGlobalsCss(contentContext),
       },
       {
         path: path.join(projectDir, 'src', 'app', 'page.tsx'),
-        content: generateWebsiteLandingPage(projectName),
+        content: generateWebsiteLandingPage(projectName, contentContext),
       },
       {
         path: path.join(projectDir, 'src', 'app', 'pricing', 'page.tsx'),
-        content: generateWebsitePricingPage(projectName),
+        content: generateWebsitePricingPage(projectName, contentContext),
       },
       {
         path: path.join(projectDir, 'src', 'app', 'docs', 'page.tsx'),
@@ -173,14 +254,64 @@ export async function generateWebsiteProject(
         content: generateWebsiteBlogPage(),
       },
 
+      // Shared components
+      {
+        path: path.join(projectDir, 'src', 'components', 'Header.tsx'),
+        content: generateWebsiteHeader(projectName, contentContext, contentContext?.strategy),
+      },
+      {
+        path: path.join(projectDir, 'src', 'components', 'Footer.tsx'),
+        content: generateWebsiteFooter(projectName, contentContext, contentContext?.strategy),
+      },
+      {
+        path: path.join(projectDir, 'src', 'components', 'JsonLd.tsx'),
+        content: generateJsonLdComponent(),
+      },
+      {
+        path: path.join(projectDir, 'src', 'components', 'ContactForm.tsx'),
+        content: generateContactForm(contentContext?.strategy),
+      },
+      {
+        path: path.join(projectDir, 'src', 'lib', 'navigation.ts'),
+        content: generateWebsiteNavigation(contentContext?.strategy),
+      },
+      {
+        path: path.join(projectDir, 'src', 'lib', 'metadata.ts'),
+        content: generateMetaHelper(projectName, contentContext?.strategy),
+      },
+
+      // Lead capture API route
+      {
+        path: path.join(projectDir, 'src', 'app', 'api', 'lead', 'route.ts'),
+        content: generateLeadCaptureRoute(
+          contentContext?.strategy?.conversionStrategy.leadCapture || 'webhook'
+        ),
+      },
+
       // SEO files
       {
         path: path.join(projectDir, 'src', 'app', 'sitemap.ts'),
-        content: generateWebsiteSitemap(projectName),
+        content: generateEnhancedSitemap(projectName, contentContext?.strategy),
       },
       {
         path: path.join(projectDir, 'src', 'app', 'robots.ts'),
-        content: generateWebsiteRobots(projectName),
+        content: generateEnhancedRobots(projectName),
+      },
+
+      // Error pages
+      {
+        path: path.join(projectDir, 'src', 'app', 'not-found.tsx'),
+        content: generate404Page(projectName, contentContext),
+      },
+      {
+        path: path.join(projectDir, 'src', 'app', 'error.tsx'),
+        content: generate500Page(projectName),
+      },
+
+      // PWA manifest
+      {
+        path: path.join(projectDir, 'public', 'manifest.webmanifest'),
+        content: generateWebManifest(projectName, contentContext),
       },
 
       // Test files
@@ -218,7 +349,10 @@ export async function generateWebsiteProject(
       // Environment
       {
         path: path.join(projectDir, '.env.example'),
-        content: 'NEXT_PUBLIC_SITE_URL=http://localhost:3001\nNEXT_PUBLIC_APP_URL=http://localhost:3000\n',
+        content: 'NEXT_PUBLIC_SITE_URL=http://localhost:3001\nNEXT_PUBLIC_APP_URL=http://localhost:3000\n' +
+          generateLeadCaptureEnvExample(
+            contentContext?.strategy?.conversionStrategy.leadCapture || 'webhook'
+          ),
       },
       {
         path: path.join(projectDir, '.gitignore'),
@@ -231,10 +365,22 @@ export async function generateWebsiteProject(
     if (!workspaceMode) {
       files.push({
         path: path.join(projectDir, '.popeye', 'website-spec.json'),
-        content: generateWebsiteSpec(projectName),
+        content: generateWebsiteSpec(projectName, contentContext),
       });
     }
 
+    // Copy logo to public/brand/ if brand context has one
+    if (contentContext?.brand?.logoPath) {
+      try {
+        const logoExt = path.extname(contentContext.brand.logoPath);
+        const destPath = path.join(projectDir, 'public', 'brand', `logo${logoExt}`);
+        await fs.copyFile(contentContext.brand.logoPath, destPath);
+        filesCreated.push(destPath);
+      } catch {
+        // Non-blocking: logo copy failure should not stop generation
+      }
+    }
+
     // Add README if not skipped
     if (!skipReadme) {
       files.push({
@@ -257,6 +403,18 @@ export async function generateWebsiteProject(
       filesCreated.push(file.path);
     }
 
+    // Post-generation content scan for placeholder fingerprints
+    try {
+      const scanResult = await scanGeneratedContent(projectDir);
+      if (scanResult.issues.length > 0) {
+        for (const issue of scanResult.issues) {
+          console.warn(`[content-scan] ${issue.severity}: ${issue.message} in ${issue.file}`);
+        }
+      }
+    } catch {
+      // Non-blocking: scan failures should not stop generation
+    }
+
     return {
       success: true,
       projectDir,

package/src/generators/workspace-root.ts

@@ -0,0 +1,113 @@
+/**
+ * Workspace root detection
+ * Resolves the workspace root directory by walking up the directory tree,
+ * looking for Popeye config, monorepo indicators, or package.json with workspaces
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Resolve the workspace root directory from a given working directory
+ *
+ * Heuristic priority:
+ * 1. Walk ancestors: first dir containing `.popeye/` -> workspace root
+ * 2. First dir containing `package.json` with "workspaces" field
+ * 3. First dir containing `pnpm-workspace.yaml` or `turbo.json`
+ * 4. `cwd` (fallback)
+ *
+ * @param cwd - The current working directory
+ * @returns The resolved workspace root path
+ */
+export async function resolveWorkspaceRoot(cwd: string): Promise<string> {
+  let current = path.resolve(cwd);
+  const root = path.parse(current).root;
+
+  while (current !== root) {
+    // Check for .popeye/ directory
+    if (await dirExists(path.join(current, '.popeye'))) {
+      return current;
+    }
+
+    // Check for package.json with "workspaces" field
+    const pkgJsonPath = path.join(current, 'package.json');
+    if (await fileExists(pkgJsonPath)) {
+      try {
+        const content = await fs.readFile(pkgJsonPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        if (pkg.workspaces) {
+          return current;
+        }
+      } catch {
+        // Invalid JSON, skip
+      }
+    }
+
+    // Check for pnpm-workspace.yaml or turbo.json
+    if (
+      (await fileExists(path.join(current, 'pnpm-workspace.yaml'))) ||
+      (await fileExists(path.join(current, 'turbo.json')))
+    ) {
+      return current;
+    }
+
+    current = path.dirname(current);
+  }
+
+  return cwd;
+}
+
+/**
+ * Build a list of directories to scan for docs and brand assets
+ * Includes workspace root, its parent, and relevant subdirectories
+ *
+ * @param cwd - The current working directory
+ * @returns Array of directories to scan (deduplicated)
+ */
+export async function getScanDirectories(cwd: string): Promise<string[]> {
+  const workspaceRoot = await resolveWorkspaceRoot(cwd);
+  const parentDir = path.dirname(workspaceRoot);
+
+  const candidates = [workspaceRoot, parentDir];
+  const subdirs = ['docs', 'brand', 'assets'];
+
+  for (const base of [workspaceRoot, parentDir]) {
+    for (const sub of subdirs) {
+      candidates.push(path.join(base, sub));
+    }
+  }
+
+  // Deduplicate by resolved path and filter to existing directories
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const dir of candidates) {
+    const resolved = path.resolve(dir);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+
+    if (await dirExists(resolved)) {
+      result.push(resolved);
+    }
+  }
+
+  return result;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function dirExists(dirPath: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(dirPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/state/index.ts

@@ -338,6 +338,62 @@ export async function storeSpecification(
   return updateState(projectDir, { specification });
 }
 
+/**
+ * Store discovered user documentation in project state
+ *
+ * @param projectDir - The project root directory
+ * @param userDocs - Combined user documentation content
+ * @returns The updated state
+ */
+export async function storeUserDocs(
+  projectDir: string,
+  userDocs: string
+): Promise<ProjectState> {
+  return updateState(projectDir, { userDocs });
+}
+
+/**
+ * Store discovered source document paths in project state
+ *
+ * @param projectDir - The project root directory
+ * @param sourceDocPaths - Array of absolute paths to doc files
+ * @returns The updated state
+ */
+export async function storeSourceDocPaths(
+  projectDir: string,
+  sourceDocPaths: string[]
+): Promise<ProjectState> {
+  return updateState(projectDir, { sourceDocPaths });
+}
+
+/**
+ * Store brand context in project state
+ *
+ * @param projectDir - The project root directory
+ * @param brandContext - Brand context with logo path and primary color
+ * @returns The updated state
+ */
+export async function storeBrandContext(
+  projectDir: string,
+  brandContext: { logoPath?: string; primaryColor?: string }
+): Promise<ProjectState> {
+  return updateState(projectDir, { brandContext });
+}
+
+/**
+ * Store website strategy path in project state
+ *
+ * @param projectDir - The project root directory
+ * @param strategyPath - Relative path to strategy JSON file
+ * @returns The updated state
+ */
+export async function storeWebsiteStrategyPath(
+  projectDir: string,
+  strategyPath: string
+): Promise<ProjectState> {
+  return updateState(projectDir, { websiteStrategy: strategyPath });
+}
+
 /**
  * Mark the project as complete
  *

package/src/types/consensus.ts

@@ -89,6 +89,8 @@ export interface ConsensusConfig {
   useOptimizedConsensus?: boolean;
   /** Additional reviewers beyond primary (for parallel reviews) */
   additionalReviewers?: AIProvider[];
+  /** Custom reviewer persona for domain-specific reviews (e.g., marketing strategist for website projects) */
+  reviewerPersona?: string;
 }
 
 /**
@@ -150,6 +152,7 @@ export const ConsensusConfigSchema = z.object({
   escalationAction: z.enum(['pause', 'continue', 'abort']).default('pause'),
   temperature: z.number().min(0).max(2).default(0.3),
   maxTokens: z.number().min(100).max(32000).default(4096),
+  reviewerPersona: z.string().optional(),
 });
 
 /**