popeye-cli 1.4.7 → 1.6.0

package/src/workflow/plan-mode.ts

@@ -17,11 +17,28 @@ import {
   setPhase,
   storePlan,
   storeSpecification,
+  storeUserDocs,
+  storeBrandContext,
+  storeSourceDocPaths,
+  storeWebsiteStrategyPath,
   addMilestones,
 } from '../state/index.js';
+import {
+  discoverProjectDocs,
+  readProjectDocs,
+  findBrandAssets,
+  resolveBrandAssets,
+} from '../generators/website-context.js';
 import { iterateUntilConsensus, type ConsensusProcessResult } from './consensus.js';
 import { getWorkflowLogger } from './workflow-logger.js';
 import { designUI, saveUISpecification } from './ui-designer.js';
+import {
+  generateWebsiteStrategy,
+  formatStrategyForPlanContext,
+  storeWebsiteStrategy,
+  loadWebsiteStrategy,
+} from './website-strategy.js';
+import type { WebsiteStrategyDocument } from '../types/website-strategy.js';
 
 /**
  * Options for plan mode
@@ -49,16 +66,18 @@ export interface PlanModeResult {
  * @param idea - The brief project idea
  * @param language - Target programming language
  * @param onProgress - Progress callback
+ * @param userDocs - Optional user documentation for context
  * @returns Expanded specification
  */
 export async function expandIdea(
   idea: string,
   language: OutputLanguage,
-  onProgress?: (message: string) => void
+  onProgress?: (message: string) => void,
+  userDocs?: string
 ): Promise<string> {
   onProgress?.('Expanding idea into specification...');
 
-  const specification = await openaiExpandIdea(idea, language);
+  const specification = await openaiExpandIdea(idea, language, userDocs);
 
   onProgress?.('Specification created');
   return specification;
@@ -247,7 +266,7 @@ function isActionableTask(name: string): boolean {
 /**
  * Task app tag for fullstack projects
  */
-export type TaskAppTag = 'FE' | 'BE' | 'INT';
+export type TaskAppTag = 'FE' | 'BE' | 'INT' | 'WEB';
 
 /**
  * Task with app targeting information for fullstack projects
@@ -256,7 +275,7 @@ export interface ParsedFullstackTask {
   name: string;
   description: string;
   appTag?: TaskAppTag;
-  appTarget?: 'frontend' | 'backend' | 'unified';
+  appTarget?: 'frontend' | 'backend' | 'unified' | 'website';
   files?: string[];
   dependencies?: string[];
   acceptanceCriteria?: string[];
@@ -271,7 +290,7 @@ export interface ParsedFullstackTask {
  * @returns The parsed app tag or undefined
  */
 export function parseTaskTag(taskName: string): TaskAppTag | undefined {
-  const tagMatch = taskName.match(/\[(FE|BE|INT)\]/i);
+  const tagMatch = taskName.match(/\[(FE|BE|INT|WEB)\]/i);
   if (tagMatch) {
     return tagMatch[1].toUpperCase() as TaskAppTag;
   }
@@ -284,10 +303,11 @@ export function parseTaskTag(taskName: string): TaskAppTag | undefined {
  * @param tag - The task tag
  * @returns The app target
  */
-export function tagToAppTarget(tag: TaskAppTag): 'frontend' | 'backend' | 'unified' {
+export function tagToAppTarget(tag: TaskAppTag): 'frontend' | 'backend' | 'unified' | 'website' {
   switch (tag) {
     case 'FE': return 'frontend';
     case 'BE': return 'backend';
+    case 'WEB': return 'website';
     case 'INT': return 'unified';
   }
 }
@@ -359,6 +379,7 @@ export function validateFullstackPlan(plan: string): {
     feTasks: number;
     beTasks: number;
     intTasks: number;
+    webTasks: number;
     untaggedTasks: number;
   };
 } {
@@ -367,6 +388,7 @@ export function validateFullstackPlan(plan: string): {
   let feTasks = 0;
   let beTasks = 0;
   let intTasks = 0;
+  let webTasks = 0;
   let untaggedTasks = 0;
 
   // Find all task headers
@@ -383,6 +405,7 @@ export function validateFullstackPlan(plan: string): {
         case 'FE': feTasks++; break;
         case 'BE': beTasks++; break;
         case 'INT': intTasks++; break;
+        case 'WEB': webTasks++; break;
       }
     } else {
       untaggedTasks++;
@@ -417,6 +440,7 @@ export function validateFullstackPlan(plan: string): {
       feTasks,
       beTasks,
       intTasks,
+      webTasks,
       untaggedTasks,
     },
   };
@@ -581,6 +605,7 @@ export function parsePlanMilestones(plan: string): Omit<Milestone, 'id'>[] {
   while ((taskMatch = explicitTaskPattern.exec(plan)) !== null) {
     const name = taskMatch[1].trim()
       .replace(/^\*\*(.+)\*\*$/, '$1')  // Remove bold
+      .replace(/^\[(?:FE|BE|INT|WEB|API|DB)\]\s*:?\s*/i, '')  // Strip app tags before verb check
       .replace(/^:/, '')                 // Remove leading colon
       .trim();
 
@@ -890,6 +915,33 @@ export async function runPlanMode(
       });
     }
 
+    // Discover user documentation from the CWD (parent of project dir)
+    let userDocs = state.userDocs || '';
+    if (!userDocs) {
+      const parentDir = path.dirname(projectDir);
+      const docPaths = await discoverProjectDocs(parentDir);
+      if (docPaths.length > 0) {
+        userDocs = await readProjectDocs(docPaths);
+        onProgress?.('doc-discovery', `Found ${docPaths.length} project doc(s)`);
+        state = await storeUserDocs(projectDir, userDocs);
+        // Store source doc paths for later re-reading
+        state = await storeSourceDocPaths(projectDir, docPaths);
+        await logger.info('init', 'docs_found', `Found ${docPaths.length} project docs`, {
+          docCount: docPaths.length,
+          docPaths: docPaths.map((p) => path.basename(p)),
+        });
+
+        // Generate PROJECT_BRIEF.md in .popeye/ for persistent reference
+        await generateProjectBrief(projectDir, spec.name || state.name, userDocs, docPaths);
+        onProgress?.('doc-discovery', 'Generated PROJECT_BRIEF.md');
+      }
+      const brandAssets = await findBrandAssets(parentDir);
+      if (brandAssets.logoPath) {
+        state = await storeBrandContext(projectDir, { logoPath: brandAssets.logoPath });
+        onProgress?.('doc-discovery', `Found brand logo: ${path.basename(brandAssets.logoPath)}`);
+      }
+    }
+
     // Expand idea if we don't have a specification
     if (!state.specification) {
       onProgress?.('expand-idea', 'Expanding idea into specification...');
@@ -898,7 +950,8 @@ export async function runPlanMode(
       const specification = await expandIdea(
         spec.idea,
         spec.language,
-        (msg) => onProgress?.('expand-idea', msg)
+        (msg) => onProgress?.('expand-idea', msg),
+        userDocs || undefined
       );
 
       state = await storeSpecification(projectDir, specification);
@@ -928,6 +981,62 @@ export async function runPlanMode(
       });
     }
 
+    // Generate website strategy for website projects (after spec, before plan)
+    const isWebsiteProject = spec.language === 'website' || spec.language === 'all';
+    let websiteStrategy: WebsiteStrategyDocument | undefined;
+
+    if (isWebsiteProject && state.specification) {
+      try {
+        onProgress?.('get-context', 'Generating website marketing strategy...');
+        await logger.stageStart('website-strategy', 'Generating website marketing strategy');
+
+        const parentDir = path.dirname(projectDir);
+        const brandAssets = await resolveBrandAssets(parentDir, state.brandContext);
+
+        const strategyInput = {
+          productContext: (userDocs || '') + '\n\n' + (state.specification || ''),
+          projectName: spec.name || state.name,
+          brandAssets,
+        };
+
+        // Check for cached strategy
+        const cached = await loadWebsiteStrategy(projectDir);
+        if (cached) {
+          websiteStrategy = cached.strategy;
+          onProgress?.('get-context', `Loaded cached strategy: ${cached.strategy.siteArchitecture.pages.length} pages`);
+        } else {
+          const result = await generateWebsiteStrategy(
+            strategyInput,
+            (msg) => onProgress?.('get-context', msg)
+          );
+          websiteStrategy = result.strategy;
+          await storeWebsiteStrategy(projectDir, result.strategy, result.metadata);
+          state = await storeWebsiteStrategyPath(projectDir, '.popeye/website-strategy.json');
+
+          onProgress?.(
+            'get-context',
+            `Strategy: ${result.strategy.siteArchitecture.pages.length} pages, ` +
+            `${result.strategy.seoStrategy.primaryKeywords.length} keywords`
+          );
+        }
+
+        await logger.stageComplete('website-strategy', 'Website strategy generated', {
+          pageCount: websiteStrategy.siteArchitecture.pages.length,
+          keywordCount: websiteStrategy.seoStrategy.primaryKeywords.length,
+        });
+      } catch (strategyError) {
+        // Non-blocking: strategy generation failure should not stop the workflow
+        const errorMsg = strategyError instanceof Error ? strategyError.message : 'Unknown error';
+        onProgress?.(
+          'get-context',
+          `WARNING: Website strategy failed: ${errorMsg}`
+        );
+        await logger.error('website-strategy', 'strategy_failed', 'Website strategy generation failed', {
+          error: errorMsg,
+        });
+      }
+    }
+
     // Get project context
     onProgress?.('get-context', 'Gathering project context...');
     let context = await getProjectContext(
@@ -941,6 +1050,12 @@ export async function runPlanMode(
       context = `${context}\n\nADDITIONAL GUIDANCE FROM USER:\n${additionalContext}`;
     }
 
+    // Inject website strategy as a separate context block (not appended to specification)
+    if (websiteStrategy) {
+      const strategyContext = formatStrategyForPlanContext(websiteStrategy);
+      context = `${context}\n\n## WEBSITE STRATEGY (authoritative reference)\n${strategyContext}`;
+    }
+
     // Create initial plan if we don't have one
     if (!state.plan) {
       onProgress?.('create-plan', 'Creating development plan...');
@@ -986,12 +1101,22 @@ export async function runPlanMode(
     onProgress?.('consensus', 'Starting consensus review...');
     await logger.stageStart('consensus', 'Starting consensus review process');
 
+    // Set marketing persona for website project reviews
+    const resolvedConsensusConfig = { ...consensusConfig };
+    if (isWebsiteProject && !resolvedConsensusConfig.reviewerPersona) {
+      resolvedConsensusConfig.reviewerPersona =
+        'a Senior Product Marketing Strategist, SEO expert, and Fullstack Web Architect. ' +
+        'Evaluate for: conversion optimization, messaging clarity, SEO best practices ' +
+        '(JSON-LD, heading hierarchy, meta tags), Lighthouse 95+ performance, WCAG 2.1 AA accessibility. ' +
+        'Reject generic template structures. Every section must connect to real product capabilities.';
+    }
+
     const consensusResult = await iterateUntilConsensus(
       state.plan!,
       context,
       {
         projectDir,
-        config: consensusConfig,
+        config: resolvedConsensusConfig,
         isFullstack: isWorkspace(spec.language),
         language: spec.language,
         onIteration: (iteration, result) => {
@@ -1262,3 +1387,63 @@ export async function resumePlanMode(
     }
   );
 }
+
+/**
+ * Generate a PROJECT_BRIEF.md file in .popeye/ that summarizes
+ * key project details extracted from user documentation.
+ *
+ * This brief is loaded at every workflow stage for consistent context.
+ *
+ * @param projectDir - The project root directory
+ * @param projectName - The project/product name
+ * @param userDocs - Combined user documentation content
+ * @param docPaths - Absolute paths to source doc files
+ */
+async function generateProjectBrief(
+  projectDir: string,
+  projectName: string,
+  userDocs: string,
+  docPaths: string[]
+): Promise<void> {
+  const briefDir = path.join(projectDir, '.popeye');
+  const briefPath = path.join(briefDir, 'PROJECT_BRIEF.md');
+
+  // Extract key details from docs
+  const productName = extractBriefField(userDocs, /^#\s+(.+)/m) || projectName;
+  const tagline = extractBriefField(userDocs, /(?:tagline|subtitle|description)[:\s]+["']?(.+?)["']?\s*$/im) || '';
+  const primaryColor = extractBriefField(userDocs, /#([0-9a-fA-F]{6})\b/) || '';
+
+  const briefContent = [
+    `# Project Brief: ${productName}`,
+    '',
+    `**Product Name:** ${productName}`,
+    tagline ? `**Tagline:** ${tagline}` : '',
+    primaryColor ? `**Primary Color:** #${primaryColor}` : '',
+    '',
+    '## Source Documents',
+    ...docPaths.map(p => `- ${path.basename(p)}`),
+    '',
+    '---',
+    '*Auto-generated by Popeye. Re-read source docs for full context.*',
+    '',
+  ].filter(line => line !== undefined).join('\n');
+
+  try {
+    await fs.mkdir(briefDir, { recursive: true });
+    await fs.writeFile(briefPath, briefContent, 'utf-8');
+  } catch {
+    // Non-critical: brief generation failure shouldn't stop workflow
+  }
+}
+
+/**
+ * Extract a field value from documentation using a regex pattern.
+ *
+ * @param content - Documentation content to search
+ * @param pattern - Regex with a capture group for the value
+ * @returns The captured value, or null if not found
+ */
+function extractBriefField(content: string, pattern: RegExp): string | null {
+  const match = content.match(pattern);
+  return match?.[1]?.trim() || null;
+}