thevoidforge 21.0.0

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

@@ -0,0 +1,150 @@
+/**
+ * Kongo Pages — Page lifecycle operations.
+ *
+ * Generate landing pages from PRD seed content, poll for completion,
+ * retrieve HTML, list/delete pages, and batch generate.
+ *
+ * Uses the real Kongo API surface:
+ * - POST /engine/pages — generate a page (accepts brief + template for structured input)
+ * - GET /engine/pages/:pageId — poll status until READY
+ * - GET /engine/pages/:pageId/html — get raw HTML
+ * - GET /engine/pages — list pages (cursor pagination)
+ * - DELETE /engine/pages/:pageId — soft delete
+ * - POST /engine/pages/batch — batch generate 1-50 pages
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.1
+ */
+import { randomUUID } from 'node:crypto';
+import { KongoApiError } from './client.js';
+// ── Page Operations ──────────────────────────────────────
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+// Kongo page generation takes 2-10 minutes. Default timeout covers the full range.
+const DEFAULT_POLL_TIMEOUT_MS = 660_000; // 11 minutes (10 min upper bound + 1 min buffer)
+/**
+ * Create a page from raw configuration.
+ * Returns immediately with pageId — generation runs async (2-10 min).
+ */
+export async function createPage(client, config) {
+    return client.post('/engine/pages', config, { 'Idempotency-Key': randomUUID() });
+}
+/**
+ * Create a landing page from PRD seed content.
+ * Maps PrdSeedContent to Kongo's CreatePageRequest with brief + template: 'landing-page'.
+ */
+export async function createPageFromPrd(client, seed) {
+    const brief = {
+        companyName: seed.projectName,
+        headline: seed.headline,
+        subheadline: seed.subheadline,
+        valuePropositions: seed.valueProps,
+        ctaText: seed.ctaText,
+        ctaUrl: seed.ctaUrl,
+    };
+    if (seed.logoUrl)
+        brief.logoUrl = seed.logoUrl;
+    if (seed.socialProof?.length)
+        brief.socialProof = seed.socialProof;
+    const metadata = {
+        source: 'voidforge',
+        projectName: seed.projectName,
+    };
+    if (seed.campaignId)
+        metadata.campaignId = seed.campaignId;
+    if (seed.platform)
+        metadata.platform = seed.platform;
+    return createPage(client, {
+        companyName: seed.projectName,
+        content: [
+            seed.headline,
+            seed.subheadline,
+            ...seed.valueProps,
+            seed.ctaText,
+            ...(seed.socialProof ?? []),
+        ].join('\n\n'),
+        brief,
+        template: 'landing-page',
+        style: {
+            colors: seed.brandColors,
+        },
+        hosted: true,
+        metadata,
+    });
+}
+/**
+ * Get the current status and details of a page.
+ */
+export async function getPageStatus(client, pageId) {
+    return client.get(`/engine/pages/${encodeURIComponent(pageId)}`);
+}
+/**
+ * Get the raw HTML of a generated page.
+ * Only works when status is READY.
+ */
+export async function getPageHtml(client, pageId, options) {
+    const query = {};
+    if (options?.tracking !== undefined)
+        query.tracking = String(options.tracking);
+    if (options?.minify !== undefined)
+        query.minify = String(options.minify);
+    return client.get(`/engine/pages/${encodeURIComponent(pageId)}/html`, query);
+}
+/**
+ * Poll a page until it reaches READY status or timeout.
+ * Throws on ERROR status or timeout.
+ */
+export async function awaitPage(client, pageId, options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    const intervalMs = options?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const page = await getPageStatus(client, pageId);
+        if (page.status === 'READY')
+            return page;
+        if (page.status === 'ERROR') {
+            throw new KongoApiError('GENERATION_FAILED', `Page generation failed: ${page.error?.message ?? 'Unknown error'}`, 500);
+        }
+        // Still GENERATING — wait and retry
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await sleep(Math.min(intervalMs, remaining));
+    }
+    throw new KongoApiError('TIMEOUT', `Page ${pageId} generation timed out after ${timeoutMs / 1000}s`, 408, true);
+}
+/**
+ * List pages with cursor-based pagination.
+ */
+export async function listPages(client, options) {
+    const query = {};
+    if (options?.cursor)
+        query.cursor = options.cursor;
+    if (options?.limit)
+        query.limit = options.limit;
+    if (options?.status)
+        query.status = options.status;
+    if (options?.sort)
+        query.sort = options.sort;
+    if (options?.order)
+        query.order = options.order;
+    return client.get('/engine/pages', query);
+}
+/**
+ * Soft-delete a page. HTML is purged immediately, metadata retained 90 days.
+ */
+export async function deletePage(client, pageId) {
+    await client.delete(`/engine/pages/${encodeURIComponent(pageId)}`);
+}
+/**
+ * Batch generate 1-50 pages in a single request.
+ */
+export async function batchGenerate(client, configs) {
+    if (configs.length === 0 || configs.length > 50) {
+        throw new KongoApiError('VALIDATION_ERROR', `Batch size must be 1-50, got ${configs.length}`, 400);
+    }
+    const result = await client.post('/engine/pages/batch', { pages: configs }, { 'Idempotency-Key': randomUUID() });
+    return result.pages;
+}
+// ── Helpers ──────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Kongo Provisioner — API key setup and connection verification.
+ *
+ * Called during /cultivation install Step 2b: "Connect Kongo for landing pages?"
+ *
+ * Kongo uses API keys (ke_live_ prefix), not OAuth. Keys are created in the
+ * Kongo dashboard at kongo.io/dashboard/api. The provisioner:
+ * 1. Accepts a user-provided API key
+ * 2. Verifies the connection with GET /engine/pages (expects 200)
+ * 3. Stores the key in the financial vault
+ * 4. Stores the webhook signing secret (optional)
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.4 (adjusted from OAuth to manual)
+ */
+import { KongoClient } from './client.js';
+/** Vault key for the Kongo API key */
+export declare const KONGO_API_KEY_VAULT_KEY = "kongo-api-key";
+/** Vault key for the webhook signing secret */
+export declare const KONGO_WEBHOOK_SECRET_VAULT_KEY = "kongo-webhook-secret";
+export interface KongoConnectionStatus {
+    readonly connected: boolean;
+    readonly pageCount?: number;
+    readonly error?: string;
+}
+/**
+ * Verify a Kongo API key by making a read-only API call.
+ * Returns connection status with page count on success.
+ */
+export declare function verifyKongoConnection(apiKey: string): Promise<KongoConnectionStatus>;
+export interface KongoProvisionConfig {
+    readonly apiKey: string;
+    readonly webhookSecret?: string;
+}
+export interface KongoProvisionResult {
+    readonly success: boolean;
+    readonly message: string;
+    readonly connection?: KongoConnectionStatus;
+}
+/**
+ * Provision Kongo access during /cultivation install.
+ *
+ * Steps:
+ * 1. Validate key format (ke_live_ prefix)
+ * 2. Verify connection with read-only API call
+ * 3. Store key in financial vault
+ * 4. Optionally store webhook signing secret
+ *
+ * @param config - API key and optional webhook secret
+ * @param vaultSet - Financial vault setter (injected for testability)
+ */
+export declare function provisionKongo(config: KongoProvisionConfig, vaultSet: (key: string, value: string) => Promise<void>): Promise<KongoProvisionResult>;
+/**
+ * Check if Kongo is connected (API key exists in vault).
+ */
+export declare function isKongoConnected(vaultGet: (key: string) => Promise<string | null>): Promise<boolean>;
+/**
+ * Create a KongoClient from vault credentials.
+ * Returns null if Kongo is not connected.
+ */
+export declare function getKongoClient(vaultGet: (key: string) => Promise<string | null>): Promise<KongoClient | null>;
+/**
+ * Remove Kongo credentials from vault (disconnect).
+ */
+export declare function disconnectKongo(vaultDelete: (key: string) => Promise<void>): Promise<void>;

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

@@ -0,0 +1,116 @@
+/**
+ * Kongo Provisioner — API key setup and connection verification.
+ *
+ * Called during /cultivation install Step 2b: "Connect Kongo for landing pages?"
+ *
+ * Kongo uses API keys (ke_live_ prefix), not OAuth. Keys are created in the
+ * Kongo dashboard at kongo.io/dashboard/api. The provisioner:
+ * 1. Accepts a user-provided API key
+ * 2. Verifies the connection with GET /engine/pages (expects 200)
+ * 3. Stores the key in the financial vault
+ * 4. Stores the webhook signing secret (optional)
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.4 (adjusted from OAuth to manual)
+ */
+import { KongoClient, KongoApiError } from './client.js';
+// ── Vault Keys ───────────────────────────────────────────
+/** Vault key for the Kongo API key */
+export const KONGO_API_KEY_VAULT_KEY = 'kongo-api-key';
+/** Vault key for the webhook signing secret */
+export const KONGO_WEBHOOK_SECRET_VAULT_KEY = 'kongo-webhook-secret';
+/**
+ * Verify a Kongo API key by making a read-only API call.
+ * Returns connection status with page count on success.
+ */
+export async function verifyKongoConnection(apiKey) {
+    try {
+        const client = new KongoClient({ apiKey });
+        const result = await client.get('/engine/pages', { limit: 1 });
+        return {
+            connected: true,
+            pageCount: result.items.length > 0 ? undefined : 0, // Can't know total from first page
+        };
+    }
+    catch (err) {
+        if (err instanceof KongoApiError) {
+            return {
+                connected: false,
+                error: `${err.code}: ${err.message}`,
+            };
+        }
+        return {
+            connected: false,
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Provision Kongo access during /cultivation install.
+ *
+ * Steps:
+ * 1. Validate key format (ke_live_ prefix)
+ * 2. Verify connection with read-only API call
+ * 3. Store key in financial vault
+ * 4. Optionally store webhook signing secret
+ *
+ * @param config - API key and optional webhook secret
+ * @param vaultSet - Financial vault setter (injected for testability)
+ */
+export async function provisionKongo(config, vaultSet) {
+    // Validate key format
+    if (!config.apiKey.startsWith('ke_live_')) {
+        return {
+            success: false,
+            message: 'Invalid API key format. Kongo keys use the ke_live_ prefix. Get yours at kongo.io/dashboard/api',
+        };
+    }
+    // Verify connection
+    const connection = await verifyKongoConnection(config.apiKey);
+    if (!connection.connected) {
+        return {
+            success: false,
+            message: `Kongo connection failed: ${connection.error}`,
+            connection,
+        };
+    }
+    // Store in vault
+    await vaultSet(KONGO_API_KEY_VAULT_KEY, config.apiKey);
+    if (config.webhookSecret) {
+        await vaultSet(KONGO_WEBHOOK_SECRET_VAULT_KEY, config.webhookSecret);
+    }
+    return {
+        success: true,
+        message: 'Kongo connected successfully.',
+        connection,
+    };
+}
+// ── Connection Check ─────────────────────────────────────
+/**
+ * Check if Kongo is connected (API key exists in vault).
+ */
+export async function isKongoConnected(vaultGet) {
+    const apiKey = await vaultGet(KONGO_API_KEY_VAULT_KEY);
+    return apiKey !== null && apiKey.startsWith('ke_live_');
+}
+/**
+ * Create a KongoClient from vault credentials.
+ * Returns null if Kongo is not connected.
+ */
+export async function getKongoClient(vaultGet) {
+    const apiKey = await vaultGet(KONGO_API_KEY_VAULT_KEY);
+    if (!apiKey)
+        return null;
+    try {
+        return new KongoClient({ apiKey });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove Kongo credentials from vault (disconnect).
+ */
+export async function disconnectKongo(vaultDelete) {
+    await vaultDelete(KONGO_API_KEY_VAULT_KEY);
+    await vaultDelete(KONGO_WEBHOOK_SECRET_VAULT_KEY);
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 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
+ */
+import type { PrdSeedContent } from './types.js';
+export interface PrdContent {
+    /** YAML frontmatter parsed as object */
+    readonly frontmatter: Record<string, unknown>;
+    /** Full PRD text content (after frontmatter) */
+    readonly body: string;
+}
+/**
+ * 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 declare function extractSeedFromPrd(prd: PrdContent): PrdSeedContent;
+/**
+ * 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 declare function extractSeedForCampaign(prd: PrdContent, campaignId: string, platform: string, options?: {
+    kongoDomain?: string;
+    selfMarketing?: boolean;
+    slug?: string;
+}): PrdSeedContent;
+/**
+ * Parse PRD text into frontmatter and body.
+ * Handles ```yaml fenced frontmatter and --- delimited frontmatter.
+ */
+export declare function parsePrdContent(raw: string): PrdContent;

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) + '...';
+}