popeye-cli 1.4.7 → 1.6.0

package/src/types/website-strategy.ts

@@ -0,0 +1,243 @@
+/**
+ * Website strategy type definitions
+ * Defines the strategic marketing document, site architecture,
+ * design tokens, and brand assets contract for website generation
+ */
+
+import { z } from 'zod';
+
+/**
+ * Navigation item for site header/footer
+ */
+export interface NavItem {
+  label: string;
+  href: string;
+  children?: NavItem[];
+}
+
+/**
+ * Footer section with links
+ */
+export interface FooterSection {
+  title: string;
+  links: Array<{ label: string; href: string }>;
+}
+
+/**
+ * Page definition in site architecture
+ */
+export interface SiteArchitecturePage {
+  path: string;
+  title: string;
+  purpose: string;
+  pageType:
+    | 'landing'
+    | 'pricing'
+    | 'solution'
+    | 'use-cases'
+    | 'about'
+    | 'contact'
+    | 'blog'
+    | 'docs'
+    | 'legal';
+  sections: string[];
+  seoKeywords: string[];
+  conversionGoal: string;
+}
+
+/**
+ * Complete website strategy document
+ * Generated by AI from product context, user docs, and market inputs
+ */
+export interface WebsiteStrategyDocument {
+  icp: {
+    primaryPersona: string;
+    painPoints: string[];
+    goals: string[];
+    objections: string[];
+  };
+  positioning: {
+    category: string;
+    differentiators: string[];
+    valueProposition: string;
+    proofPoints: string[];
+  };
+  messaging: {
+    headline: string;
+    subheadline: string;
+    elevatorPitch: string;
+    longDescription: string;
+  };
+  seoStrategy: {
+    primaryKeywords: string[];
+    secondaryKeywords: string[];
+    longTailKeywords: string[];
+    titleTemplates: Record<string, string>;
+    metaDescriptions: Record<string, string>;
+  };
+  siteArchitecture: {
+    pages: SiteArchitecturePage[];
+    navigation: NavItem[];
+    footerSections: FooterSection[];
+  };
+  conversionStrategy: {
+    primaryCta: { text: string; href: string };
+    secondaryCta: { text: string; href: string };
+    trustSignals: string[];
+    socialProof: string[];
+    leadCapture: 'none' | 'webhook' | 'resend' | 'postmark';
+  };
+  competitiveContext: {
+    category: string;
+    competitors: string[];
+    differentiators: string[];
+  };
+}
+
+/**
+ * Strategy metadata for caching and staleness detection
+ */
+export interface StrategyMetadata {
+  /** SHA-256 of (docs + spec + tokens) for staleness detection */
+  inputHash: string;
+  /** ISO timestamp of generation */
+  generatedAt: string;
+  /** Schema version */
+  version: number;
+}
+
+/**
+ * Design tokens extracted from project config or brand docs
+ */
+export interface DesignTokens {
+  colors: Record<string, string>;
+  fonts: { heading: string; body: string; mono?: string };
+  borderRadius: string;
+  source: 'tailwind-config' | 'css-variables' | 'brand-docs' | 'defaults';
+}
+
+/**
+ * Brand assets contract for deterministic logo/favicon placement
+ */
+export interface BrandAssetsContract {
+  /** Discovered source path for logo */
+  logoPath?: string;
+  /** Canonical output path: public/brand/logo.{ext} */
+  logoOutputPath: string;
+  /** Discovered source path for favicon */
+  faviconPath?: string;
+  /** Primary brand color */
+  primaryColor?: string;
+  /** Full color scheme */
+  colorScheme?: Record<string, string>;
+}
+
+// --- Zod Schemas ---
+
+export const NavItemSchema: z.ZodType<NavItem> = z.lazy(() =>
+  z.object({
+    label: z.string().min(1),
+    href: z.string().min(1),
+    children: z.array(NavItemSchema).optional(),
+  })
+);
+
+export const FooterSectionSchema = z.object({
+  title: z.string().min(1),
+  links: z.array(
+    z.object({
+      label: z.string().min(1),
+      href: z.string().min(1),
+    })
+  ),
+});
+
+export const SiteArchitecturePageSchema = z.object({
+  path: z.string().min(1),
+  title: z.string().min(1),
+  purpose: z.string(),
+  pageType: z.enum([
+    'landing',
+    'pricing',
+    'solution',
+    'use-cases',
+    'about',
+    'contact',
+    'blog',
+    'docs',
+    'legal',
+  ]),
+  sections: z.array(z.string()),
+  seoKeywords: z.array(z.string()),
+  conversionGoal: z.string(),
+});
+
+export const WebsiteStrategySchema = z.object({
+  icp: z.object({
+    primaryPersona: z.string().min(1),
+    painPoints: z.array(z.string()),
+    goals: z.array(z.string()),
+    objections: z.array(z.string()),
+  }),
+  positioning: z.object({
+    category: z.string().min(1),
+    differentiators: z.array(z.string()),
+    valueProposition: z.string().min(1),
+    proofPoints: z.array(z.string()),
+  }),
+  messaging: z.object({
+    headline: z.string().min(1),
+    subheadline: z.string().min(1),
+    elevatorPitch: z.string().min(1),
+    longDescription: z.string().min(1),
+  }),
+  seoStrategy: z.object({
+    primaryKeywords: z.array(z.string()),
+    secondaryKeywords: z.array(z.string()),
+    longTailKeywords: z.array(z.string()),
+    titleTemplates: z.record(z.string(), z.string()),
+    metaDescriptions: z.record(z.string(), z.string()),
+  }),
+  siteArchitecture: z.object({
+    pages: z.array(SiteArchitecturePageSchema),
+    navigation: z.array(NavItemSchema),
+    footerSections: z.array(FooterSectionSchema),
+  }),
+  conversionStrategy: z.object({
+    primaryCta: z.object({ text: z.string().min(1), href: z.string().min(1) }),
+    secondaryCta: z.object({ text: z.string().min(1), href: z.string().min(1) }),
+    trustSignals: z.array(z.string()),
+    socialProof: z.array(z.string()),
+    leadCapture: z.enum(['none', 'webhook', 'resend', 'postmark']),
+  }),
+  competitiveContext: z.object({
+    category: z.string(),
+    competitors: z.array(z.string()),
+    differentiators: z.array(z.string()),
+  }),
+});
+
+export const StrategyMetadataSchema = z.object({
+  inputHash: z.string().min(1),
+  generatedAt: z.string().min(1),
+  version: z.number(),
+});
+
+export const DesignTokensSchema = z.object({
+  colors: z.record(z.string(), z.string()),
+  fonts: z.object({
+    heading: z.string(),
+    body: z.string(),
+    mono: z.string().optional(),
+  }),
+  borderRadius: z.string(),
+  source: z.enum(['tailwind-config', 'css-variables', 'brand-docs', 'defaults']),
+});
+
+export const BrandAssetsContractSchema = z.object({
+  logoPath: z.string().optional(),
+  logoOutputPath: z.string().min(1),
+  faviconPath: z.string().optional(),
+  primaryColor: z.string().optional(),
+  colorScheme: z.record(z.string(), z.string()).optional(),
+});

package/src/types/workflow.ts

@@ -192,6 +192,19 @@ export interface ProjectState {
   error?: string;
   createdAt: string;
   updatedAt: string;
+  /** Raw user documentation discovered from CWD */
+  userDocs?: string;
+  /** Brand context discovered from CWD */
+  brandContext?: {
+    logoPath?: string;
+    primaryColor?: string;
+  };
+  /** 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[];
 }
 
 /**
@@ -229,6 +242,14 @@ export const ProjectStateSchema = z.object({
   error: z.string().optional(),
   createdAt: z.string(),
   updatedAt: z.string(),
+  userDocs: z.string().optional(),
+  brandContext: z.object({
+    logoPath: z.string().optional(),
+    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) {