voidforge-build 23.9.1

package/dist/wizard/lib/kongo/seed.js

@@ -0,0 +1,237 @@
+/**
+ * Kongo Seed — Extract seed content from PRDs for landing page generation.
+ *
+ * Phase 3.5 of /grow: Before you distribute, you need somewhere to send them.
+ *
+ * Extracts headline, value props, CTA, brand colors, and social proof from
+ * PRD YAML frontmatter and prose content. Maps to PrdSeedContent which
+ * feeds into createPageFromPrd().
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.5
+ */
+/**
+ * Extract PrdSeedContent from a PRD document.
+ *
+ * Strategy:
+ * 1. Use frontmatter `name` for project name
+ * 2. Extract first ## heading or overview section for headline
+ * 3. Extract value props from feature descriptions or bullet lists
+ * 4. Use brand colors from frontmatter `style` or defaults
+ * 5. Extract CTA from conversion or signup references
+ */
+export function extractSeedFromPrd(prd) {
+    const fm = prd.frontmatter;
+    const body = prd.body;
+    const projectName = extractProjectName(fm);
+    const headline = extractHeadline(fm, body);
+    const subheadline = extractSubheadline(fm, body);
+    const valueProps = extractValueProps(body);
+    const { ctaText, ctaUrl } = extractCta(fm, body);
+    const brandColors = extractBrandColors(fm);
+    const socialProof = extractSocialProof(body);
+    return {
+        projectName,
+        headline,
+        subheadline,
+        valueProps,
+        ctaText,
+        ctaUrl,
+        brandColors,
+        socialProof: socialProof.length > 0 ? socialProof : undefined,
+    };
+}
+/**
+ * Extract seed content for a specific campaign.
+ * Enriches the base PRD seed with campaign-specific metadata.
+ *
+ * Self-marketing mode: When the product domain matches the Kongo domain
+ * (dogfooding), destination URLs use the /lp/ direct-render path instead
+ * of subdomain URLs. This avoids the iframe sandbox constraint that breaks
+ * GA4 cookie tracking and UTM relay. See GROWTH_STRATEGIST.md "Iframe
+ * Sandbox Constraint" section.
+ */
+export function extractSeedForCampaign(prd, campaignId, platform, options) {
+    const baseSeed = extractSeedFromPrd(prd);
+    const kongoDomain = options?.kongoDomain ?? 'kongo.io';
+    const slug = options?.slug ?? slugify(baseSeed.projectName, campaignId);
+    const isSelfMarketing = options?.selfMarketing ?? false;
+    // Self-marketing: use /lp/ direct-render path (no iframe sandbox)
+    // Standard: use subdomain URL
+    const destinationUrl = isSelfMarketing
+        ? `https://${kongoDomain}/lp/${slug}`
+        : `https://${slug}.${kongoDomain}`;
+    return {
+        ...baseSeed,
+        campaignId,
+        platform,
+        ctaUrl: destinationUrl,
+    };
+}
+/** Generate a URL-safe slug from project name and campaign ID */
+function slugify(projectName, campaignId) {
+    return `${projectName}-${campaignId}`
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+// ── Frontmatter Parsing ──────────────────────────────────
+/**
+ * Parse PRD text into frontmatter and body.
+ * Handles ```yaml fenced frontmatter and --- delimited frontmatter.
+ */
+export function parsePrdContent(raw) {
+    const lines = raw.split('\n');
+    let frontmatterStr = '';
+    let bodyStart = 0;
+    // Try ```yaml fenced block
+    if (lines[0]?.trim() === '```yaml' || lines[0]?.trim() === '---') {
+        const delimiter = lines[0].trim() === '```yaml' ? '```' : '---';
+        let found = false;
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === delimiter) {
+                bodyStart = i + 1;
+                found = true;
+                break;
+            }
+            frontmatterStr += lines[i] + '\n';
+        }
+        // No closing delimiter — treat as no frontmatter
+        if (!found) {
+            frontmatterStr = '';
+            bodyStart = 0;
+        }
+    }
+    // Simple YAML key: value parsing (no dependency on yaml parser)
+    const frontmatter = {};
+    for (const line of frontmatterStr.split('\n')) {
+        const match = line.match(/^(\w[\w-]*)\s*:\s*(.+)/);
+        if (match) {
+            const key = match[1];
+            let value = match[2].trim();
+            // Strip quotes
+            if (typeof value === 'string' && value.startsWith('"') && value.endsWith('"')) {
+                value = value.slice(1, -1);
+            }
+            frontmatter[key] = value;
+        }
+    }
+    return {
+        frontmatter,
+        body: lines.slice(bodyStart).join('\n'),
+    };
+}
+// ── Extraction Helpers ───────────────────────────────────
+function extractProjectName(fm) {
+    return String(fm.name ?? fm.projectName ?? fm.title ?? 'Untitled Project');
+}
+function extractHeadline(fm, body) {
+    // Check frontmatter tagline
+    if (fm.tagline)
+        return String(fm.tagline);
+    // First ## Overview section, or first sentence of body
+    const overviewMatch = body.match(/##\s+(?:Overview|Introduction|About)\s*\n+(.+)/i);
+    if (overviewMatch) {
+        return truncate(overviewMatch[1].trim(), 100);
+    }
+    // First meaningful paragraph
+    const firstParagraph = body.split('\n\n').find(p => p.trim().length > 20 && !p.startsWith('#'));
+    if (firstParagraph) {
+        return truncate(firstParagraph.split('.')[0].trim(), 100);
+    }
+    return String(fm.name ?? 'Your Next Big Thing');
+}
+function extractSubheadline(fm, body) {
+    if (fm.description)
+        return truncate(String(fm.description), 200);
+    // Second sentence of overview
+    const overviewMatch = body.match(/##\s+(?:Overview|Introduction|About)\s*\n+([\s\S]*?)(?=\n##|\n---)/i);
+    if (overviewMatch) {
+        const sentences = overviewMatch[1].trim().split(/\.\s+/);
+        if (sentences.length > 1)
+            return truncate(sentences[1].trim(), 200);
+    }
+    return `Built with ${String(fm.name ?? 'innovation')}`;
+}
+function extractValueProps(body) {
+    const props = [];
+    // Look for bullet lists in Features section
+    const featuresMatch = body.match(/##\s+(?:Features|Core Features|Key Features|Capabilities)\s*\n([\s\S]*?)(?=\n##|$)/i);
+    if (featuresMatch) {
+        const bullets = featuresMatch[1].match(/^[-*]\s+(.+)/gm);
+        if (bullets) {
+            for (const bullet of bullets.slice(0, 5)) {
+                props.push(bullet.replace(/^[-*]\s+/, '').trim());
+            }
+        }
+    }
+    // Fallback: any bullet lists in the first half of the document
+    if (props.length === 0) {
+        const halfBody = body.slice(0, body.length / 2);
+        const bullets = halfBody.match(/^[-*]\s+(.+)/gm);
+        if (bullets) {
+            for (const bullet of bullets.slice(0, 5)) {
+                props.push(bullet.replace(/^[-*]\s+/, '').trim());
+            }
+        }
+    }
+    // Ensure at least 3 value props
+    while (props.length < 3) {
+        props.push(props.length === 0 ? 'Built for speed' : props.length === 1 ? 'Easy to use' : 'Trusted by teams');
+    }
+    return props.slice(0, 5);
+}
+function extractCta(fm, body) {
+    // Check frontmatter for CTA
+    if (fm.ctaText && fm.ctaUrl) {
+        return { ctaText: String(fm.ctaText), ctaUrl: String(fm.ctaUrl) };
+    }
+    // Look for signup/demo/trial references
+    const ctaPatterns = [
+        { pattern: /sign\s*up|get\s*started|start\s*(free\s*)?trial/i, text: 'Get Started Free' },
+        { pattern: /request\s*(a\s*)?demo/i, text: 'Request a Demo' },
+        { pattern: /join\s*waitlist/i, text: 'Join the Waitlist' },
+        { pattern: /download/i, text: 'Download Now' },
+        { pattern: /subscribe/i, text: 'Subscribe' },
+    ];
+    for (const { pattern, text } of ctaPatterns) {
+        if (pattern.test(body))
+            return { ctaText: text, ctaUrl: '#signup' };
+    }
+    return { ctaText: 'Get Started', ctaUrl: '#signup' };
+}
+function extractBrandColors(fm) {
+    const style = fm.style;
+    const colors = style?.colors;
+    return {
+        primary: colors?.primary ?? '#1a1a2e',
+        secondary: colors?.secondary ?? '#16213e',
+        accent: colors?.accent ?? '#0f3460',
+    };
+}
+function extractSocialProof(body) {
+    const proof = [];
+    // Look for testimonials section
+    const testimonialsMatch = body.match(/##\s+(?:Testimonials|Social Proof|What .+ Say)\s*\n([\s\S]*?)(?=\n##|$)/i);
+    if (testimonialsMatch) {
+        const quotes = testimonialsMatch[1].match(/>\s*(.+)/gm);
+        if (quotes) {
+            for (const quote of quotes.slice(0, 3)) {
+                proof.push(quote.replace(/^>\s*/, '').trim());
+            }
+        }
+    }
+    // Look for stats
+    const statsMatch = body.match(/(\d+[+kKmM]?\s+(?:users|teams|companies|customers|downloads|stars))/gi);
+    if (statsMatch) {
+        for (const stat of statsMatch.slice(0, 2)) {
+            proof.push(stat.trim());
+        }
+    }
+    return proof;
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + '...';
+}

package/dist/wizard/lib/kongo/types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Kongo Engine API types — matched to the real Kongo API surface at kongo.io/api/v1.
+ *
+ * These types represent the actual API request/response shapes, not abstract
+ * interfaces. Kongo is a first-party integration (ADR-036): the user owns both
+ * VoidForge and Kongo, so no adapter abstraction is needed.
+ *
+ * Base URL: https://kongo.io/api/v1
+ * Auth: Bearer token with ke_live_ prefix
+ */
+export type PageStatus = 'GENERATING' | 'READY' | 'ERROR';
+export type PageTemplate = 'PITCH' | 'landing-page' | 'company-overview' | 'product-launch' | 'event-page' | 'one-pager';
+export interface PageStyle {
+    readonly colors?: {
+        primary?: string;
+        secondary?: string;
+        accent?: string;
+    };
+    readonly fonts?: {
+        heading?: string;
+        body?: string;
+    };
+    readonly designSystem?: Record<string, unknown>;
+}
+export interface AccessGate {
+    readonly password?: string;
+    readonly emailCapture?: boolean;
+}
+export interface CreatePageRequest {
+    readonly companyName: string;
+    readonly content: string;
+    readonly brief?: Record<string, unknown>;
+    readonly template?: PageTemplate;
+    readonly style?: PageStyle;
+    readonly hosted?: boolean;
+    readonly callbackUrl?: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly accessGate?: AccessGate;
+    readonly seoTitle?: string;
+    readonly seoDescription?: string;
+}
+export interface CreatePageResponse {
+    readonly pageId: string;
+    readonly status: 'GENERATING';
+    readonly statusUrl: string;
+    readonly createdAt: string;
+}
+export interface PageGenerationStats {
+    readonly durationSec: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costUsd: number;
+    readonly promptVersion?: string;
+}
+export interface PageProgressStep {
+    readonly step: string;
+    readonly status: string;
+    readonly timestamp?: string;
+}
+export interface PageErrorDetail {
+    readonly code: string;
+    readonly message: string;
+}
+export interface PageDetail {
+    readonly pageId: string;
+    readonly status: PageStatus;
+    readonly companyName: string;
+    readonly html?: string;
+    readonly hostedUrl?: string;
+    readonly progress?: PageProgressStep[];
+    readonly generation?: PageGenerationStats;
+    readonly error?: PageErrorDetail;
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface ListPagesOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly status?: PageStatus;
+    readonly sort?: 'createdAt' | 'updatedAt';
+    readonly order?: 'asc' | 'desc';
+}
+export interface PaginatedResponse<T> {
+    readonly items: T[];
+    readonly cursor?: string;
+    readonly hasMore: boolean;
+}
+export interface BatchPageConfig {
+    readonly companyName: string;
+    readonly content: string;
+    readonly brief?: Record<string, unknown>;
+    readonly template?: PageTemplate;
+    readonly style?: PageStyle;
+    readonly hosted?: boolean;
+    readonly callbackUrl?: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly accessGate?: AccessGate;
+    readonly seoTitle?: string;
+    readonly seoDescription?: string;
+}
+export interface BatchGenerateRequest {
+    readonly pages: BatchPageConfig[];
+}
+export interface BatchPageResult {
+    readonly pageId: string;
+    readonly status: 'GENERATING';
+    readonly statusUrl: string;
+    readonly createdAt: string;
+}
+export type RotationStrategy = 'weighted' | 'equal' | 'bandit';
+export interface SourceRule {
+    readonly source: string;
+    readonly variantId: string;
+}
+export interface CreateCampaignRequest {
+    readonly name: string;
+    readonly templateId: string;
+    readonly slug: string;
+    readonly rotationStrategy?: RotationStrategy;
+    readonly trackingEnabled?: boolean;
+    readonly accessGate?: AccessGate;
+    readonly metadata?: Record<string, unknown>;
+    readonly sourceRules?: SourceRule[];
+}
+export interface CampaignDetail {
+    readonly campaignId: string;
+    readonly name: string;
+    readonly templateId: string;
+    readonly slug: string;
+    readonly rotationStrategy: RotationStrategy;
+    readonly isPublished: boolean;
+    readonly trackingEnabled: boolean;
+    readonly accessGate?: {
+        passwordProtected: boolean;
+        emailCapture: boolean;
+    };
+    readonly metadata?: Record<string, unknown>;
+    readonly sourceRules?: SourceRule[];
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+}
+export interface UpdateCampaignRequest {
+    readonly rotationStrategy?: RotationStrategy;
+    readonly trackingEnabled?: boolean;
+    readonly accessGate?: AccessGate;
+    readonly metadata?: Record<string, unknown>;
+    readonly sourceRules?: SourceRule[];
+}
+export interface PublishResult {
+    readonly campaignId: string;
+    readonly slug: string;
+    readonly domain: string;
+    readonly publishedAt: string;
+}
+export interface ListCampaignsOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly published?: boolean;
+    readonly search?: string;
+}
+export interface CreateVariantRequest {
+    readonly label: string;
+    readonly slotValues: Record<string, string>;
+    readonly weight?: number;
+    readonly source?: string;
+}
+export interface VariantDetail {
+    readonly variantId: string;
+    readonly label: string;
+    readonly order: number;
+    readonly slotCount: number;
+    readonly slotValues?: Record<string, string>;
+    readonly compiledHtml?: string;
+    readonly weight: number;
+    readonly source?: string;
+    readonly isActive: boolean;
+    readonly views: number;
+    readonly conversions: number;
+    readonly cvr: number;
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+}
+export interface UpdateVariantRequest {
+    readonly label?: string;
+    readonly slotValues?: Record<string, string>;
+    readonly weight?: number;
+    readonly isActive?: boolean;
+}
+export interface GenerateVariantsRequest {
+    readonly count: number;
+    readonly vary: string[];
+    readonly baseValues?: Record<string, string>;
+    readonly context?: string;
+    readonly sources?: string[];
+}
+export interface GenerateVariantsResult {
+    readonly variants: Array<{
+        variantId: string;
+        label: string;
+        order: number;
+        slotCount: number;
+        source?: string;
+        createdAt: string;
+    }>;
+    readonly generation: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        durationMs: number;
+    };
+}
+export interface RegenerateVariantRequest {
+    readonly slots: string[];
+    readonly direction?: string;
+}
+export type AnalyticsPeriod = '7d' | '30d' | '90d' | 'all';
+export interface CampaignAnalytics {
+    readonly period: AnalyticsPeriod;
+    readonly summary: {
+        totalViews: number;
+        totalConversions: number;
+        cvr: number;
+    };
+    readonly byVariant: Array<{
+        variantId: string;
+        label: string;
+        order: number;
+        views: number;
+        conversions: number;
+        cvr: number;
+        weight: number;
+    }>;
+    readonly bySource: Array<{
+        source: string;
+        views: number;
+        conversions: number;
+        cvr: number;
+    }>;
+    readonly byDay: Array<{
+        date: string;
+        views: number;
+        conversions: number;
+    }>;
+}
+export type GrowthRecommendation = 'scale' | 'iterate' | 'kill' | 'wait';
+export interface ComputedGrowthSignal {
+    readonly campaignId: string;
+    readonly timestamp: string;
+    readonly winningVariantId: string | null;
+    readonly confidence: number;
+    readonly conversionRateDelta: number;
+    readonly recommendation: GrowthRecommendation;
+    readonly reasoning: string;
+    readonly sampleSize: {
+        control: number;
+        variant: number;
+    };
+}
+export type ConversionEventType = 'view' | 'click' | 'form_submit' | 'purchase';
+export interface ConversionEvent {
+    readonly campaignId: string;
+    readonly variantId: string;
+    readonly visitorId: string;
+    readonly type: ConversionEventType;
+    readonly eventName?: string;
+    readonly value?: number;
+    readonly utmSource?: string;
+    readonly utmMedium?: string;
+    readonly utmCampaign?: string;
+    readonly scrollDepth?: number;
+    readonly durationSec?: number;
+}
+export type WebhookEventType = 'page.completed' | 'page.failed';
+export interface WebhookPayload {
+    readonly event: WebhookEventType;
+    readonly pageId: string;
+    readonly data: {
+        companyName: string;
+        status: 'READY' | 'ERROR';
+        durationSec?: number;
+        costUsd?: number;
+        htmlLength?: number;
+        error?: string;
+    };
+}
+export interface KongoSuccessResponse<T> {
+    readonly success: true;
+    readonly data: T;
+}
+export interface KongoErrorResponse {
+    readonly success: false;
+    readonly error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+export type KongoResponse<T> = KongoSuccessResponse<T> | KongoErrorResponse;
+export type KongoErrorCode = 'UNAUTHORIZED' | 'TIER_RESTRICTED' | 'PERMISSION_DENIED' | 'RATE_LIMITED' | 'MONTHLY_LIMIT' | 'CONCURRENT_LIMIT' | 'SERVICE_BUSY' | 'VALIDATION_ERROR' | 'CONTENT_BLOCKED' | 'NOT_FOUND' | 'NOT_READY';
+export interface KongoClientConfig {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly rateLimitPerMinute?: number;
+}
+export interface PrdSeedContent {
+    readonly projectName: string;
+    readonly headline: string;
+    readonly subheadline: string;
+    readonly valueProps: string[];
+    readonly ctaText: string;
+    readonly ctaUrl: string;
+    readonly brandColors: {
+        primary: string;
+        secondary: string;
+        accent: string;
+    };
+    readonly logoUrl?: string;
+    readonly socialProof?: string[];
+    readonly campaignId?: string;
+    readonly platform?: string;
+}

package/dist/wizard/lib/kongo/types.js

@@ -0,0 +1,11 @@
+/**
+ * Kongo Engine API types — matched to the real Kongo API surface at kongo.io/api/v1.
+ *
+ * These types represent the actual API request/response shapes, not abstract
+ * interfaces. Kongo is a first-party integration (ADR-036): the user owns both
+ * VoidForge and Kongo, so no adapter abstraction is needed.
+ *
+ * Base URL: https://kongo.io/api/v1
+ * Auth: Bearer token with ke_live_ prefix
+ */
+export {};

package/dist/wizard/lib/kongo/variants.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Kongo Variants — Variant lifecycle and AI generation.
+ *
+ * Create, list, update, delete variants within campaigns.
+ * AI-powered bulk variant generation and slot regeneration.
+ *
+ * Real Kongo API endpoints:
+ * - POST /engine/campaigns/:campaignId/variants — create variant
+ * - GET /engine/campaigns/:campaignId/variants — list variants
+ * - GET /engine/campaigns/:campaignId/variants/:variantId — get variant
+ * - PATCH /engine/campaigns/:campaignId/variants/:variantId — update
+ * - DELETE /engine/campaigns/:campaignId/variants/:variantId — deactivate
+ * - POST /engine/campaigns/:campaignId/variants/generate — AI generate N variants
+ * - POST /engine/campaigns/:campaignId/variants/:variantId/regenerate — regen slots
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.2
+ */
+import { KongoClient } from './client.js';
+import type { CreateVariantRequest, VariantDetail, UpdateVariantRequest, GenerateVariantsRequest, GenerateVariantsResult, RegenerateVariantRequest } from './types.js';
+/**
+ * Create a single variant with explicit slot values.
+ */
+export declare function createVariant(client: KongoClient, campaignId: string, config: CreateVariantRequest): Promise<VariantDetail>;
+/**
+ * List all variants for a campaign.
+ * Returns view counts, conversions, CVR, weights, and direct URLs.
+ */
+export declare function listVariants(client: KongoClient, campaignId: string): Promise<VariantDetail[]>;
+/**
+ * Get a single variant with full details including slotValues and compiledHtml.
+ */
+export declare function getVariant(client: KongoClient, campaignId: string, variantId: string): Promise<VariantDetail>;
+/**
+ * Update a variant's label, slot values, weight, or active status.
+ * Slot value updates are merged (existing preserved, new override).
+ */
+export declare function updateVariant(client: KongoClient, campaignId: string, variantId: string, updates: UpdateVariantRequest): Promise<VariantDetail>;
+/**
+ * Deactivate a variant (soft delete).
+ */
+export declare function deleteVariant(client: KongoClient, campaignId: string, variantId: string): Promise<void>;
+/**
+ * AI-generate multiple variants in a single call.
+ * Uses Claude Sonnet to produce N variants varying specified slots.
+ * ~$0.01, ~3s for 5 variants.
+ */
+export declare function generateVariants(client: KongoClient, campaignId: string, config: GenerateVariantsRequest): Promise<GenerateVariantsResult>;
+/**
+ * Regenerate specific slots of an existing variant using AI.
+ * Merged values are recompiled into HTML.
+ */
+export declare function regenerateVariantSlots(client: KongoClient, campaignId: string, variantId: string, config: RegenerateVariantRequest): Promise<VariantDetail>;
+/**
+ * Set rotation strategy for a campaign.
+ * Convenience wrapper around updateCampaign — updates only rotationStrategy.
+ */
+export declare function setRotation(client: KongoClient, campaignId: string, strategy: 'weighted' | 'equal' | 'bandit'): Promise<void>;