popeye-cli 1.5.0 → 1.6.0

package/src/generators/website.ts

@@ -48,6 +48,10 @@ import {
   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
@@ -75,6 +79,8 @@ export interface WebsiteGeneratorOptions {
   skipReadme?: boolean;
   /** Content context from user docs for populating templates */
   contentContext?: WebsiteContentContext;
+  /** Skip content validation (scaffold-only use) */
+  skipValidation?: boolean;
 }
 
 /**
@@ -111,6 +117,7 @@ export async function generateWebsiteProject(
     skipDocker = false,
     skipReadme = false,
     contentContext,
+    skipValidation = false,
   } = options;
 
   const projectName = spec.name || 'my-project';
@@ -140,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
@@ -157,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'),
@@ -313,11 +369,11 @@ export async function generateWebsiteProject(
       });
     }
 
-    // Copy logo to public/ if brand context has one
+    // 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', `logo${logoExt}`);
+        const destPath = path.join(projectDir, 'public', 'brand', `logo${logoExt}`);
         await fs.copyFile(contentContext.brand.logoPath, destPath);
         filesCreated.push(destPath);
       } catch {
@@ -347,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

@@ -352,6 +352,20 @@ export async function storeUserDocs(
   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
  *

package/src/types/workflow.ts

@@ -201,6 +201,10 @@ export interface ProjectState {
   };
   /** Path to website strategy JSON file (relative to .popeye/) */
   websiteStrategy?: string;
+  /** Error message from website strategy generation (for visibility) */
+  strategyError?: string;
+  /** Absolute paths to discovered source documentation files */
+  sourceDocPaths?: string[];
 }
 
 /**
@@ -244,6 +248,8 @@ export const ProjectStateSchema = z.object({
     primaryColor: z.string().optional(),
   }).optional(),
   websiteStrategy: z.string().optional(),
+  strategyError: z.string().optional(),
+  sourceDocPaths: z.array(z.string()).optional(),
 });
 
 /**

package/src/upgrade/handlers.ts

@@ -21,6 +21,10 @@ import {
   generateRootDockerCompose,
 } from '../generators/templates/fullstack.js';
 import { loadState, saveState } from '../state/persistence.js';
+import { buildWebsiteContext, resolveBrandAssets, validateWebsiteContext } from '../generators/website-context.js';
+import type { WebsiteContentContext } from '../generators/website-context.js';
+import { resolveWorkspaceRoot } from '../generators/workspace-root.js';
+import { loadWebsiteStrategy } from '../workflow/website-strategy.js';
 import type { UpgradeResult } from './index.js';
 
 /**
@@ -42,6 +46,57 @@ async function pathExists(filePath: string): Promise<boolean> {
   }
 }
 
+/**
+ * Build website content context from user docs, brand assets, and strategy
+ *
+ * Replicates the context-building pattern from website-updater.ts so that
+ * upgrade-generated websites get real content instead of TODO placeholders.
+ *
+ * @param projectDir - Project directory (workspace root)
+ * @param projectName - Project name
+ * @returns Content context and optional warning
+ */
+export async function buildUpgradeContentContext(
+  projectDir: string,
+  projectName: string,
+): Promise<{ context?: WebsiteContentContext; warning?: string }> {
+  try {
+    // Build context from user docs (scans projectDir + parent via getScanDirectories)
+    const context = await buildWebsiteContext(projectDir, projectName);
+
+    // Apply brand context from state if available
+    const state = await loadState(projectDir);
+    if (state?.brandContext?.primaryColor) {
+      context.brand = { ...context.brand, primaryColor: state.brandContext.primaryColor };
+    }
+    if (state?.brandContext?.logoPath) {
+      context.brand = { ...context.brand, logoPath: state.brandContext.logoPath };
+    }
+
+    // Resolve brand assets using workspace root
+    const workspaceRoot = await resolveWorkspaceRoot(projectDir);
+    context.brandAssets = await resolveBrandAssets(workspaceRoot, context.brand);
+
+    // Load website strategy if available
+    const strategyData = await loadWebsiteStrategy(projectDir);
+    if (strategyData) {
+      context.strategy = strategyData.strategy;
+    }
+
+    // Soft validation: include quality warnings in the return value
+    const validation = validateWebsiteContext(context, projectName);
+    const validationWarnings = [...validation.issues, ...validation.warnings]
+      .map((w) => `[quality-gate] ${w}`);
+
+    return {
+      context,
+      warning: validationWarnings.length > 0 ? validationWarnings.join('; ') : undefined,
+    };
+  } catch (e) {
+    return { warning: e instanceof Error ? e.message : 'Unknown error building website context' };
+  }
+}
+
 /**
  * Update state.json language field
  *
@@ -297,11 +352,21 @@ export async function upgradeFullstackToAll(
       openaiModel: 'gpt-4o',
     };
 
+    // Build content context from user docs, brand assets, and strategy
+    const { context: contentContext, warning } = await buildUpgradeContentContext(
+      projectDir,
+      projectName,
+    );
+    if (warning) {
+      console.warn(`[upgrade] Website context warning: ${warning}`);
+    }
+
     const result = await generateWebsiteProject(spec, projectDir, {
       baseDir: websiteDir,
       workspaceMode: true,
       skipDocker: true,
       skipReadme: true,
+      contentContext,
     });
 
     if (!result.success) {