popeye-cli 1.5.0 → 1.7.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

@@ -60,6 +60,7 @@ export async function createProject(
     consensusHistory: [],
     createdAt: now,
     updatedAt: now,
+    qaEnabled: true,
   };
 
   await saveState(projectDir, state);
@@ -352,6 +353,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/consensus.ts

@@ -91,6 +91,8 @@ export interface ConsensusConfig {
   additionalReviewers?: AIProvider[];
   /** Custom reviewer persona for domain-specific reviews (e.g., marketing strategist for website projects) */
   reviewerPersona?: string;
+  /** Consensus threshold for test plans (default: 90, lower than code plan threshold) */
+  testPlanThreshold?: number;
 }
 
 /**
@@ -153,6 +155,7 @@ export const ConsensusConfigSchema = z.object({
   temperature: z.number().min(0).max(2).default(0.3),
   maxTokens: z.number().min(100).max(32000).default(4096),
   reviewerPersona: z.string().optional(),
+  testPlanThreshold: z.number().min(0).max(100).optional(),
 });
 
 /**

package/src/types/index.ts

@@ -80,6 +80,27 @@ export {
   type ConsensusTrackingRecord,
 } from './consensus.js';
 
+// Tester (QA) types
+export {
+  TestVerdictSchema,
+  TestScopeSchema,
+  TestCommandSchema,
+  TestCaseSchema,
+  TestPlanOutputSchema,
+  TestRunReviewSchema,
+  FixStepSchema,
+  TestFixPlanSchema,
+  type TestVerdict,
+  type TestScope,
+  type TestCommand,
+  type TestCase,
+  type TestPlanOutput,
+  type TestRunReview,
+  type FixStep,
+  type TestFixPlan,
+  type DiscoveredTestCommands,
+} from './tester.js';
+
 // CLI types
 export {
   EXIT_CODES,

package/src/types/tester.ts

@@ -0,0 +1,136 @@
+/**
+ * Tester (QA) skill type definitions
+ * Defines test planning, review, and fix plan structures
+ */
+
+import { z } from 'zod';
+
+/**
+ * Test verdict from the Tester's review
+ */
+export const TestVerdictSchema = z.enum(['PASS', 'PASS_WITH_NOTES', 'FAIL']);
+export type TestVerdict = z.infer<typeof TestVerdictSchema>;
+
+/**
+ * Scope components that a test plan can cover
+ */
+export const TestScopeSchema = z.enum(['frontend', 'backend', 'db', 'infra']);
+export type TestScope = z.infer<typeof TestScopeSchema>;
+
+/**
+ * A structured test command to execute
+ */
+export const TestCommandSchema = z.object({
+  /** The shell command to run */
+  command: z.string().min(1),
+  /** Working directory (relative to project root) */
+  cwd: z.string().optional(),
+  /** Human-readable purpose of this command */
+  purpose: z.string().min(1),
+  /** Whether this command must pass for the test run to succeed */
+  required: z.boolean(),
+});
+export type TestCommand = z.infer<typeof TestCommandSchema>;
+
+/**
+ * Individual test case in the test matrix
+ */
+export const TestCaseSchema = z.object({
+  /** Unique identifier within the test plan */
+  id: z.string().min(1),
+  /** Category: unit, integration, e2e, smoke, lint, build */
+  category: z.string().min(1),
+  /** Human-readable description of what is being tested */
+  description: z.string().min(1),
+  /** What must be true for this test to pass */
+  acceptanceCriteria: z.string().min(1),
+  /** What evidence (log output, report) is needed to verify */
+  evidenceRequired: z.string().min(1),
+  /** Priority: critical, high, medium, low */
+  priority: z.enum(['critical', 'high', 'medium', 'low']),
+});
+export type TestCase = z.infer<typeof TestCaseSchema>;
+
+/**
+ * Structured test plan output from the Tester
+ */
+export const TestPlanOutputSchema = z.object({
+  /** What risks this test plan targets */
+  summary: z.string().min(1),
+  /** Components covered by this plan */
+  scope: z.array(TestScopeSchema).min(1),
+  /** Matrix of test cases with acceptance criteria */
+  testMatrix: z.array(TestCaseSchema).min(1),
+  /** Exact commands to execute (with cwd, purpose, required flag) */
+  commands: z.array(TestCommandSchema).min(1),
+  /** Top risks this test plan focuses on (3-7 items) */
+  riskFocus: z.array(z.string().min(1)).min(1),
+  /** What evidence (logs, reports) to capture */
+  evidenceRequired: z.array(z.string().min(1)).min(1),
+  /** Minimum verification always present: build, lint, smoke */
+  minimumVerification: z.array(z.string().min(1)).min(1),
+  /** Rationale if tester decides no custom tests are needed (min verification still applies) */
+  noTestsRationale: z.string().optional(),
+});
+export type TestPlanOutput = z.infer<typeof TestPlanOutputSchema>;
+
+/**
+ * Post-run review from the Tester
+ */
+export const TestRunReviewSchema = z.object({
+  /** Overall verdict */
+  verdict: TestVerdictSchema,
+  /** Summary of the review */
+  summary: z.string().min(1),
+  /** List of evidence that was checked */
+  evidenceReviewed: z.array(z.string().min(1)).min(1),
+  /** Specific failures found (empty array if PASS) */
+  failures: z.array(z.string()),
+  /** Missing evidence or coverage gaps */
+  gaps: z.array(z.string()),
+  /** Recommendations for improvement */
+  recommendations: z.array(z.string()),
+  /** Whether this verdict requires consensus (true if FAIL) */
+  requiresConsensus: z.boolean(),
+});
+export type TestRunReview = z.infer<typeof TestRunReviewSchema>;
+
+/**
+ * Individual fix step in a TestFixPlan
+ */
+export const FixStepSchema = z.object({
+  /** File to modify */
+  file: z.string().min(1),
+  /** Description of the change */
+  change: z.string().min(1),
+  /** Why this change is needed */
+  reason: z.string().min(1),
+});
+export type FixStep = z.infer<typeof FixStepSchema>;
+
+/**
+ * Fix plan proposed by the Tester when tests fail
+ */
+export const TestFixPlanSchema = z.object({
+  /** Which acceptance criteria failed */
+  failedCriteria: z.array(z.string().min(1)).min(1),
+  /** Root cause analysis from the Tester */
+  rootCauseAnalysis: z.string().min(1),
+  /** Ordered steps to fix the failures */
+  fixSteps: z.array(FixStepSchema).min(1),
+  /** Risks of introducing regressions */
+  regressionRisks: z.array(z.string()),
+  /** Strategy for re-testing after fix */
+  retestStrategy: z.string().min(1),
+});
+export type TestFixPlan = z.infer<typeof TestFixPlanSchema>;
+
+/**
+ * Discovered test infrastructure for a project
+ */
+export interface DiscoveredTestCommands {
+  testCmd: string | null;
+  lintCmd: string | null;
+  buildCmd: string | null;
+  typecheckCmd: string | null;
+}

package/src/types/workflow.ts

@@ -7,6 +7,8 @@ import { z } from 'zod';
 import { OutputLanguageSchema } from './project.js';
 import type { OutputLanguage, OpenAIModel } from './project.js';
 import type { ConsensusIteration } from './consensus.js';
+import type { TestPlanOutput } from './tester.js';
+import { TestPlanOutputSchema, TestVerdictSchema } from './tester.js';
 
 /**
  * Workflow phases
@@ -68,6 +70,17 @@ export interface Task {
 
   // App target (which app this task affects)
   appTarget?: 'frontend' | 'backend' | 'unified';
+
+  // Tester (QA) tracking
+  qaTestPlanText?: string;           // Approved test plan (markdown, for humans)
+  qaTestPlanParsed?: TestPlanOutput; // Parsed structured plan (for machine flow)
+  qaTestPlanScore?: number;          // Consensus score (0-100)
+  qaTestPlanIterations?: number;     // Iterations to reach consensus
+  qaTestPlanApproved?: boolean;      // Whether consensus was reached
+  qaTestPlanDoc?: string;            // Path to docs/qa/test-plans/...
+  qaVerdict?: 'PASS' | 'PASS_WITH_NOTES' | 'FAIL';
+  qaReviewNotes?: string;            // Tester's review notes
+  qaReviewDoc?: string;              // Path to docs/qa/test-runs/...
 }
 
 /**
@@ -107,6 +120,16 @@ export const TaskSchema = z.object({
   backendConsensus: AppConsensusTrackingSchema.optional(),
   unifiedConsensus: AppConsensusTrackingSchema.optional(),
   appTarget: z.enum(['frontend', 'backend', 'unified']).optional(),
+  // Tester (QA) tracking
+  qaTestPlanText: z.string().optional(),
+  qaTestPlanParsed: TestPlanOutputSchema.optional(),
+  qaTestPlanScore: z.number().optional(),
+  qaTestPlanIterations: z.number().optional(),
+  qaTestPlanApproved: z.boolean().optional(),
+  qaTestPlanDoc: z.string().optional(),
+  qaVerdict: TestVerdictSchema.optional(),
+  qaReviewNotes: z.string().optional(),
+  qaReviewDoc: z.string().optional(),
 });
 
 /**
@@ -201,6 +224,12 @@ 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[];
+  /** Whether QA Tester skill is active (default: true for new projects, undefined/false for existing) */
+  qaEnabled?: boolean;
 }
 
 /**
@@ -244,6 +273,9 @@ export const ProjectStateSchema = z.object({
     primaryColor: z.string().optional(),
   }).optional(),
   websiteStrategy: z.string().optional(),
+  strategyError: z.string().optional(),
+  sourceDocPaths: z.array(z.string()).optional(),
+  qaEnabled: z.boolean().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) {