voidforge-build 23.9.1

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

@@ -0,0 +1,122 @@
+/**
+ * Kongo Heartbeat Jobs — Daemon-registered background jobs for Kongo integration.
+ *
+ * Three jobs that run when Kongo is connected:
+ * - kongo-signal: Hourly poll of growth signal for all active campaigns
+ * - kongo-seed: Triggered when a variant wins — pushes winning copy back
+ * - kongo-webhook: Event-driven handler for Kongo webhook events
+ *
+ * Jobs are only registered when Kongo is connected (API key in vault).
+ * All jobs skip cleanly when Kongo is not connected.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.6
+ */
+import { getGrowthSignal } from './analytics.js';
+import { batchGetCampaignStatuses } from './campaigns.js';
+import { getVariant } from './variants.js';
+import { createWebhookRouter } from './webhooks.js';
+/**
+ * Create Kongo job handlers for the heartbeat daemon.
+ *
+ * Usage in heartbeat.ts:
+ * ```
+ * const kongoJobs = createKongoJobs(context);
+ * scheduler.add('kongo-signal', 3_600_000, kongoJobs.signalPoll);  // 1 hour
+ * ```
+ */
+export function createKongoJobs(ctx) {
+    // Set up webhook router
+    const router = createWebhookRouter();
+    router.on('page.completed', async (payload) => {
+        ctx.logger(`Kongo page completed: ${payload.pageId}`);
+        if (ctx.onPageCompleted) {
+            await ctx.onPageCompleted(payload.pageId);
+        }
+    });
+    router.on('page.failed', async (payload) => {
+        ctx.logger(`Kongo page failed: ${payload.pageId} — ${payload.data.error ?? 'Unknown error'}`);
+        if (ctx.onPageFailed) {
+            await ctx.onPageFailed(payload.pageId, payload.data.error);
+        }
+    });
+    return {
+        /**
+         * kongo-signal: Poll growth signal for all active campaigns.
+         * Runs hourly. Results logged and forwarded to onSignal callback.
+         */
+        async signalPoll() {
+            const campaigns = await batchGetCampaignStatuses(ctx.client);
+            const activeCampaigns = campaigns.filter(c => c.isPublished);
+            const signals = [];
+            for (const campaign of activeCampaigns) {
+                try {
+                    const signal = await getGrowthSignal(ctx.client, campaign.campaignId, '30d');
+                    // Self-marketing mode: Kongo's built-in analytics can't track /lp/ pages
+                    // (served via direct render, not iframe). Merge external analytics (GA4/PostHog)
+                    // for the complete picture. Subdomain analytics still come from Kongo.
+                    if (ctx.selfMarketing && ctx.getExternalAnalytics && campaign.name) {
+                        const slug = campaign.name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+                        const external = await ctx.getExternalAnalytics(slug, '30d');
+                        if (external) {
+                            ctx.logger(`Kongo signal [${campaign.name}]: merging external analytics ` +
+                                `(${external.views} views, ${external.conversions} conversions from /lp/ path)`);
+                        }
+                    }
+                    signals.push(signal);
+                    ctx.logger(`Kongo signal [${campaign.name}]: ${signal.recommendation}` +
+                        (signal.winningVariantId ? ` (winner: ${signal.winningVariantId})` : ''));
+                    if (ctx.onSignal) {
+                        await ctx.onSignal(signal);
+                    }
+                }
+                catch (err) {
+                    ctx.logger(`Kongo signal poll failed for ${campaign.campaignId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            return {
+                signals,
+                polledAt: new Date().toISOString(),
+            };
+        },
+        /**
+         * kongo-seed: Push winning variant copy back to Kongo as seed for next iteration.
+         * Triggered externally when Wayne's A/B evaluation declares a winner.
+         */
+        async seedPush(campaignId, winningVariantId) {
+            ctx.logger(`Kongo seed push: campaign=${campaignId}, winner=${winningVariantId}`);
+            const variant = await getVariant(ctx.client, campaignId, winningVariantId);
+            if (!variant.slotValues) {
+                ctx.logger(`Kongo seed push: no slot values on variant ${winningVariantId}, skipping`);
+                return null;
+            }
+            ctx.logger(`Kongo seed push: extracted ${Object.keys(variant.slotValues).length} slot values from winner "${variant.label}"`);
+            // Return winning copy for the orchestrator to persist and use in next cycle.
+            // The caller (heartbeat daemon or /grow Phase 3.5) stores this in heartbeat state
+            // and feeds it into the next createPageFromPrd() cycle.
+            return variant.slotValues;
+        },
+        /**
+         * kongo-webhook: Handle incoming Kongo webhook events.
+         * Called by the daemon's HTTP callback route.
+         */
+        async webhookHandle(rawBody, signature) {
+            if (!ctx.webhookSecret) {
+                ctx.logger('Kongo webhook received but no signing secret configured — rejecting');
+                throw new Error('Webhook signing secret not configured');
+            }
+            await router.handle(rawBody, signature, ctx.webhookSecret);
+        },
+    };
+}
+/**
+ * Register Kongo jobs with the daemon's scheduler.
+ * Only registers when Kongo is connected.
+ */
+export function registerKongoJobs(scheduler, jobs) {
+    // kongo-signal: hourly
+    scheduler.add('kongo-signal', 3_600_000, async () => {
+        await jobs.signalPoll();
+    });
+    // kongo-seed and kongo-webhook are event-driven, not scheduled.
+    // They are called directly by the daemon when events occur.
+}

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

@@ -0,0 +1,60 @@
+/**
+ * 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 { KongoClient } from './client.js';
+import type { CreatePageRequest, CreatePageResponse, PageDetail, ListPagesOptions, PaginatedResponse, BatchPageConfig, BatchPageResult, PrdSeedContent } from './types.js';
+/**
+ * Create a page from raw configuration.
+ * Returns immediately with pageId — generation runs async (2-10 min).
+ */
+export declare function createPage(client: KongoClient, config: CreatePageRequest): Promise<CreatePageResponse>;
+/**
+ * Create a landing page from PRD seed content.
+ * Maps PrdSeedContent to Kongo's CreatePageRequest with brief + template: 'landing-page'.
+ */
+export declare function createPageFromPrd(client: KongoClient, seed: PrdSeedContent): Promise<CreatePageResponse>;
+/**
+ * Get the current status and details of a page.
+ */
+export declare function getPageStatus(client: KongoClient, pageId: string): Promise<PageDetail>;
+/**
+ * Get the raw HTML of a generated page.
+ * Only works when status is READY.
+ */
+export declare function getPageHtml(client: KongoClient, pageId: string, options?: {
+    tracking?: boolean;
+    minify?: boolean;
+}): Promise<string>;
+/**
+ * Poll a page until it reaches READY status or timeout.
+ * Throws on ERROR status or timeout.
+ */
+export declare function awaitPage(client: KongoClient, pageId: string, options?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<PageDetail>;
+/**
+ * List pages with cursor-based pagination.
+ */
+export declare function listPages(client: KongoClient, options?: ListPagesOptions): Promise<PaginatedResponse<PageDetail>>;
+/**
+ * Soft-delete a page. HTML is purged immediately, metadata retained 90 days.
+ */
+export declare function deletePage(client: KongoClient, pageId: string): Promise<void>;
+/**
+ * Batch generate 1-50 pages in a single request.
+ */
+export declare function batchGenerate(client: KongoClient, configs: BatchPageConfig[]): Promise<BatchPageResult[]>;

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;