voidforge-build 23.9.1

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

@@ -0,0 +1,88 @@
+/**
+ * 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 { KongoApiError } from './client.js';
+// ── Variant Operations ───────────────────────────────────
+function campaignVariantsPath(campaignId) {
+    return `/engine/campaigns/${encodeURIComponent(campaignId)}/variants`;
+}
+function variantPath(campaignId, variantId) {
+    return `${campaignVariantsPath(campaignId)}/${encodeURIComponent(variantId)}`;
+}
+/**
+ * Create a single variant with explicit slot values.
+ */
+export async function createVariant(client, campaignId, config) {
+    return client.post(campaignVariantsPath(campaignId), config);
+}
+/**
+ * List all variants for a campaign.
+ * Returns view counts, conversions, CVR, weights, and direct URLs.
+ */
+export async function listVariants(client, campaignId) {
+    return client.get(campaignVariantsPath(campaignId));
+}
+/**
+ * Get a single variant with full details including slotValues and compiledHtml.
+ */
+export async function getVariant(client, campaignId, variantId) {
+    return client.get(variantPath(campaignId, variantId));
+}
+/**
+ * Update a variant's label, slot values, weight, or active status.
+ * Slot value updates are merged (existing preserved, new override).
+ */
+export async function updateVariant(client, campaignId, variantId, updates) {
+    return client.patch(variantPath(campaignId, variantId), updates);
+}
+/**
+ * Deactivate a variant (soft delete).
+ */
+export async function deleteVariant(client, campaignId, variantId) {
+    await client.delete(variantPath(campaignId, variantId));
+}
+/**
+ * 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 async function generateVariants(client, campaignId, config) {
+    if (config.count < 1 || config.count > 20) {
+        throw new KongoApiError('VALIDATION_ERROR', `Variant count must be 1-20, got ${config.count}`, 400);
+    }
+    if (config.vary.length === 0) {
+        throw new KongoApiError('VALIDATION_ERROR', 'At least one slot name must be specified in vary', 400);
+    }
+    return client.post(`${campaignVariantsPath(campaignId)}/generate`, config);
+}
+/**
+ * Regenerate specific slots of an existing variant using AI.
+ * Merged values are recompiled into HTML.
+ */
+export async function regenerateVariantSlots(client, campaignId, variantId, config) {
+    if (config.slots.length === 0) {
+        throw new KongoApiError('VALIDATION_ERROR', 'At least one slot name must be specified', 400);
+    }
+    return client.post(`${variantPath(campaignId, variantId)}/regenerate`, config);
+}
+/**
+ * Set rotation strategy for a campaign.
+ * Convenience wrapper around updateCampaign — updates only rotationStrategy.
+ */
+export async function setRotation(client, campaignId, strategy) {
+    await client.put(`/engine/campaigns/${encodeURIComponent(campaignId)}`, { rotationStrategy: strategy });
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Kongo Webhooks — Signature verification and event routing.
+ *
+ * Kongo sends webhooks for page.completed and page.failed events
+ * via the callbackUrl specified on page creation.
+ *
+ * Signature format: X-Kongo-Signature: t=timestamp,v1=signature
+ * Verification: HMAC-SHA256 of "timestamp.body" with webhook signing secret.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.3, §11
+ */
+import type { WebhookPayload, WebhookEventType } from './types.js';
+export interface WebhookVerificationResult {
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+/**
+ * Verify a Kongo webhook signature.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Rejects replayed webhooks older than 5 minutes.
+ *
+ * @param rawBody - The raw request body as a string (must not be parsed)
+ * @param signature - The X-Kongo-Signature header value
+ * @param secret - The webhook signing secret from vault
+ */
+export declare function verifyWebhookSignature(rawBody: string, signature: string, secret: string): WebhookVerificationResult;
+/**
+ * Parse a verified webhook body into a typed payload.
+ */
+export declare function parseWebhookPayload(rawBody: string): WebhookPayload;
+export type WebhookHandler = (payload: WebhookPayload) => Promise<void>;
+export interface WebhookRouter {
+    readonly handlers: Map<WebhookEventType, WebhookHandler>;
+    on(event: WebhookEventType, handler: WebhookHandler): void;
+    handle(rawBody: string, signature: string, secret: string): Promise<void>;
+}
+/**
+ * Create a webhook router that verifies signatures and routes events to handlers.
+ */
+export declare function createWebhookRouter(): WebhookRouter;

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

@@ -0,0 +1,112 @@
+/**
+ * Kongo Webhooks — Signature verification and event routing.
+ *
+ * Kongo sends webhooks for page.completed and page.failed events
+ * via the callbackUrl specified on page creation.
+ *
+ * Signature format: X-Kongo-Signature: t=timestamp,v1=signature
+ * Verification: HMAC-SHA256 of "timestamp.body" with webhook signing secret.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.3, §11
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+// ── Signature Verification ───────────────────────────────
+// Maximum age for webhook timestamp (5 minutes)
+const MAX_WEBHOOK_AGE_MS = 5 * 60 * 1000;
+// Maximum webhook body size (1 MB — defense in depth, HTTP layer should also limit)
+const MAX_WEBHOOK_BODY_BYTES = 1 * 1024 * 1024;
+/**
+ * Verify a Kongo webhook signature.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Rejects replayed webhooks older than 5 minutes.
+ *
+ * @param rawBody - The raw request body as a string (must not be parsed)
+ * @param signature - The X-Kongo-Signature header value
+ * @param secret - The webhook signing secret from vault
+ */
+export function verifyWebhookSignature(rawBody, signature, secret) {
+    if (!signature || !rawBody || !secret) {
+        return { valid: false, reason: 'Missing signature, body, or secret' };
+    }
+    if (Buffer.byteLength(rawBody) > MAX_WEBHOOK_BODY_BYTES) {
+        return { valid: false, reason: 'Webhook body too large' };
+    }
+    // Parse signature: t=timestamp,v1=hash
+    const parts = signature.split(',');
+    if (parts.length !== 2) {
+        return { valid: false, reason: 'Invalid signature format' };
+    }
+    const tPart = parts[0];
+    const vPart = parts[1];
+    if (!tPart.startsWith('t=') || !vPart.startsWith('v1=')) {
+        return { valid: false, reason: 'Invalid signature format: missing t= or v1= prefix' };
+    }
+    const timestamp = tPart.slice(2);
+    const providedHash = vPart.slice(3);
+    // Check timestamp freshness
+    const timestampMs = parseInt(timestamp, 10) * 1000;
+    if (isNaN(timestampMs)) {
+        return { valid: false, reason: 'Invalid timestamp' };
+    }
+    const age = Date.now() - timestampMs;
+    if (age < -60_000) {
+        return { valid: false, reason: 'Webhook timestamp is in the future' };
+    }
+    if (age > MAX_WEBHOOK_AGE_MS) {
+        return { valid: false, reason: `Webhook too old: ${Math.round(age / 1000)}s (max ${MAX_WEBHOOK_AGE_MS / 1000}s)` };
+    }
+    // Compute expected signature
+    const payload = `${timestamp}.${rawBody}`;
+    const expectedHash = createHmac('sha256', secret)
+        .update(payload)
+        .digest('hex');
+    // Timing-safe comparison
+    const providedBuf = Buffer.from(providedHash, 'hex');
+    const expectedBuf = Buffer.from(expectedHash, 'hex');
+    if (providedBuf.length !== expectedBuf.length) {
+        return { valid: false, reason: 'Signature length mismatch' };
+    }
+    const valid = timingSafeEqual(providedBuf, expectedBuf);
+    return valid ? { valid: true } : { valid: false, reason: 'Signature mismatch' };
+}
+// ── Event Parsing ────────────────────────────────────────
+/**
+ * Parse a verified webhook body into a typed payload.
+ */
+export function parseWebhookPayload(rawBody) {
+    const parsed = JSON.parse(rawBody);
+    if (!parsed.event || !parsed.pageId || !parsed.data) {
+        throw new Error('Invalid webhook payload: missing event, pageId, or data');
+    }
+    const validEvents = ['page.completed', 'page.failed'];
+    if (!validEvents.includes(parsed.event)) {
+        throw new Error(`Unknown webhook event type: ${parsed.event}`);
+    }
+    return parsed;
+}
+/**
+ * Create a webhook router that verifies signatures and routes events to handlers.
+ */
+export function createWebhookRouter() {
+    const handlers = new Map();
+    return {
+        handlers,
+        on(event, handler) {
+            handlers.set(event, handler);
+        },
+        async handle(rawBody, signature, secret) {
+            const verification = verifyWebhookSignature(rawBody, signature, secret);
+            if (!verification.valid) {
+                throw new Error(`Webhook verification failed: ${verification.reason}`);
+            }
+            const payload = parseWebhookPayload(rawBody);
+            const handler = handlers.get(payload.event);
+            if (!handler) {
+                // Log but don't throw — unknown event types should be ignored gracefully
+                return;
+            }
+            await handler(payload);
+        },
+    };
+}

package/dist/wizard/lib/marker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * .voidforge marker file — project identity and CLI detection.
+ *
+ * Every VoidForge project has a `.voidforge` JSON file at root.
+ * The CLI walks up from cwd to find it, determining the project root.
+ */
+export interface VoidForgeMarker {
+    id: string;
+    version: string;
+    created: string;
+    tier: 'full' | 'methodology';
+    extensions: string[];
+}
+export declare const MARKER_FILE = ".voidforge";
+export declare function readMarker(dir: string): Promise<VoidForgeMarker | null>;
+export declare function writeMarker(dir: string, marker: VoidForgeMarker): Promise<void>;
+export declare function createMarker(version: string, tier?: VoidForgeMarker['tier'], extensions?: string[]): VoidForgeMarker;
+/**
+ * Walk up from `startDir` to find the nearest `.voidforge` marker.
+ * Returns the directory containing the marker, or null if none found.
+ */
+export declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Like findProjectRoot but throws with a user-friendly message.
+ */
+export declare function requireProjectRoot(startDir?: string): string;
+export declare function getGlobalDir(): string;
+export declare function getVaultPath(): string;

package/dist/wizard/lib/marker.js

@@ -0,0 +1,79 @@
+/**
+ * .voidforge marker file — project identity and CLI detection.
+ *
+ * Every VoidForge project has a `.voidforge` JSON file at root.
+ * The CLI walks up from cwd to find it, determining the project root.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+// ── Constants ────────────────────────────────────────────
+export const MARKER_FILE = '.voidforge';
+// ── Read / Write ─────────────────────────────────────────
+export async function readMarker(dir) {
+    const markerPath = join(dir, MARKER_FILE);
+    if (!existsSync(markerPath))
+        return null;
+    try {
+        const raw = await readFile(markerPath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (!data.id || !data.version || !Array.isArray(data.extensions))
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeMarker(dir, marker) {
+    const markerPath = join(dir, MARKER_FILE);
+    await writeFile(markerPath, JSON.stringify(marker, null, 2) + '\n', 'utf-8');
+}
+export function createMarker(version, tier = 'full', extensions = []) {
+    return {
+        id: randomUUID(),
+        version,
+        created: new Date().toISOString(),
+        tier,
+        extensions,
+    };
+}
+// ── Project Detection ────────────────────────────────────
+/**
+ * Walk up from `startDir` to find the nearest `.voidforge` marker.
+ * Returns the directory containing the marker, or null if none found.
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    let current = startDir;
+    while (true) {
+        if (existsSync(join(current, MARKER_FILE))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break; // filesystem root
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Like findProjectRoot but throws with a user-friendly message.
+ */
+export function requireProjectRoot(startDir = process.cwd()) {
+    const root = findProjectRoot(startDir);
+    if (!root) {
+        console.error('Not a VoidForge project — run `npx voidforge init` to create one.');
+        process.exit(1);
+    }
+    return root;
+}
+// ── Global Config ────────────────────────────────────────
+export function getGlobalDir() {
+    const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? homedir();
+    return join(home, '.voidforge');
+}
+export function getVaultPath() {
+    return join(getGlobalDir(), 'vault.enc');
+}

package/dist/wizard/lib/migrator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Migration from v20.x — detects old-model projects (embedded wizard/)
+ * and converts them to v21.0 (standalone wizard, methodology-only projects).
+ */
+export interface MigrationPlan {
+    projectDir: string;
+    hasWizardDir: boolean;
+    wizardFileCount: number;
+    hasPackageJson: boolean;
+    voidforgeDeps: string[];
+    hasMethodology: boolean;
+    hasMarker: boolean;
+}
+export interface MigrationResult {
+    success: boolean;
+    backupDir: string;
+    wizardFilesRemoved: number;
+    depsRemoved: string[];
+    markerCreated: boolean;
+}
+/**
+ * Detect if a directory is a v20.x project (has embedded wizard/).
+ */
+export declare function detectV20Project(dir: string): Promise<MigrationPlan>;
+/**
+ * Migrate a v20.x project to v21.0.
+ *
+ * 1. Create backup at ~/.voidforge/migration-backup/
+ * 2. Remove wizard/ directory
+ * 3. Remove VoidForge deps from package.json
+ * 4. Add .voidforge marker file
+ * 5. Keep all methodology files in place
+ */
+export declare function migrateProject(projectDir: string, dryRun?: boolean): Promise<MigrationResult>;
+export declare function rollbackMigration(projectDir: string, backupDir: string): Promise<void>;

package/dist/wizard/lib/migrator.js

@@ -0,0 +1,190 @@
+/**
+ * Migration from v20.x — detects old-model projects (embedded wizard/)
+ * and converts them to v21.0 (standalone wizard, methodology-only projects).
+ */
+import { readdir, readFile, rm, cp, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createMarker, writeMarker } from './marker.js';
+// ── Detection ────────────────────────────────────────────
+async function countFiles(dir) {
+    if (!existsSync(dir))
+        return 0;
+    let count = 0;
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            count += await countFiles(join(dir, entry.name));
+        }
+        else {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Detect if a directory is a v20.x project (has embedded wizard/).
+ */
+export async function detectV20Project(dir) {
+    const projectDir = resolve(dir);
+    const wizardDir = join(projectDir, 'wizard');
+    const hasWizardDir = existsSync(wizardDir) && existsSync(join(wizardDir, 'server.ts'));
+    const wizardFileCount = hasWizardDir ? await countFiles(wizardDir) : 0;
+    // Check package.json for VoidForge dependencies
+    const pkgPath = join(projectDir, 'package.json');
+    const hasPackageJson = existsSync(pkgPath);
+    let voidforgeDeps = [];
+    if (hasPackageJson) {
+        try {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            voidforgeDeps = Object.keys(allDeps).filter(d => d.startsWith('@aws-sdk/') || d === 'node-pty' || d === 'ws');
+        }
+        catch {
+            // Invalid package.json
+        }
+    }
+    const hasMethodology = existsSync(join(projectDir, 'CLAUDE.md'));
+    const hasMarker = existsSync(join(projectDir, '.voidforge'));
+    return {
+        projectDir,
+        hasWizardDir,
+        wizardFileCount,
+        hasPackageJson,
+        voidforgeDeps,
+        hasMethodology,
+        hasMarker,
+    };
+}
+// ── Backup ───────────────────────────────────────────────
+async function createBackup(projectDir) {
+    const { homedir } = await import('node:os');
+    const backupBase = join(homedir(), '.voidforge', 'migration-backup');
+    await mkdir(backupBase, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const projectName = projectDir.split('/').pop() ?? 'project';
+    const backupDir = join(backupBase, `${projectName}-${timestamp}`);
+    await mkdir(backupDir);
+    // Backup wizard/ directory
+    const wizardDir = join(projectDir, 'wizard');
+    if (existsSync(wizardDir)) {
+        await cp(wizardDir, join(backupDir, 'wizard'), { recursive: true });
+    }
+    // Backup package.json
+    const pkgPath = join(projectDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        await cp(pkgPath, join(backupDir, 'package.json'));
+    }
+    // Backup package-lock.json
+    const lockPath = join(projectDir, 'package-lock.json');
+    if (existsSync(lockPath)) {
+        await cp(lockPath, join(backupDir, 'package-lock.json'));
+    }
+    return backupDir;
+}
+// ── Migration ────────────────────────────────────────────
+/**
+ * Migrate a v20.x project to v21.0.
+ *
+ * 1. Create backup at ~/.voidforge/migration-backup/
+ * 2. Remove wizard/ directory
+ * 3. Remove VoidForge deps from package.json
+ * 4. Add .voidforge marker file
+ * 5. Keep all methodology files in place
+ */
+export async function migrateProject(projectDir, dryRun = false) {
+    const plan = await detectV20Project(projectDir);
+    if (!plan.hasWizardDir) {
+        throw new Error('No wizard/ directory found — this is not a v20.x project.');
+    }
+    if (plan.hasMarker) {
+        throw new Error('Project already has a .voidforge marker — already migrated?');
+    }
+    if (dryRun) {
+        return {
+            success: true,
+            backupDir: '(dry run — no backup created)',
+            wizardFilesRemoved: plan.wizardFileCount,
+            depsRemoved: plan.voidforgeDeps,
+            markerCreated: true,
+        };
+    }
+    // 1. Create backup
+    const backupDir = await createBackup(projectDir);
+    // 2. Remove wizard/ directory
+    const wizardDir = join(projectDir, 'wizard');
+    await rm(wizardDir, { recursive: true, force: true });
+    // 3. Remove VoidForge deps from package.json
+    const depsRemoved = [];
+    const pkgPath = join(projectDir, 'package.json');
+    if (plan.hasPackageJson && plan.voidforgeDeps.length > 0) {
+        try {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+            for (const dep of plan.voidforgeDeps) {
+                if (pkg.dependencies?.[dep]) {
+                    delete pkg.dependencies[dep];
+                    depsRemoved.push(dep);
+                }
+                if (pkg.devDependencies?.[dep]) {
+                    delete pkg.devDependencies[dep];
+                    depsRemoved.push(dep);
+                }
+            }
+            const { writeFile } = await import('node:fs/promises');
+            await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+        }
+        catch {
+            // package.json modification failed — non-fatal
+        }
+    }
+    // 4. Write .voidforge marker
+    const marker = createMarker('21.0.0', 'full');
+    await writeMarker(projectDir, marker);
+    // 5. Remove old config files that moved to the wizard package
+    const oldConfigs = ['vitest.config.ts', 'playwright.config.ts'];
+    for (const config of oldConfigs) {
+        const configPath = join(projectDir, config);
+        if (existsSync(configPath)) {
+            await rm(configPath);
+        }
+    }
+    // 6. Remove wizard-specific scripts from package.json
+    const scriptsDir = join(projectDir, 'scripts');
+    const wizardScripts = ['voidforge.ts', 'danger-room-feed.sh', 'new-project.sh', 'vault-read.ts'];
+    for (const script of wizardScripts) {
+        const scriptPath = join(scriptsDir, script);
+        if (existsSync(scriptPath)) {
+            await rm(scriptPath);
+        }
+    }
+    return {
+        success: true,
+        backupDir,
+        wizardFilesRemoved: plan.wizardFileCount,
+        depsRemoved,
+        markerCreated: true,
+    };
+}
+// ── Rollback ─────────────────────────────────────────────
+export async function rollbackMigration(projectDir, backupDir) {
+    // Restore wizard/
+    const wizardBackup = join(backupDir, 'wizard');
+    if (existsSync(wizardBackup)) {
+        await cp(wizardBackup, join(projectDir, 'wizard'), { recursive: true });
+    }
+    // Restore package.json
+    const pkgBackup = join(backupDir, 'package.json');
+    if (existsSync(pkgBackup)) {
+        await cp(pkgBackup, join(projectDir, 'package.json'));
+    }
+    // Restore package-lock.json
+    const lockBackup = join(backupDir, 'package-lock.json');
+    if (existsSync(lockBackup)) {
+        await cp(lockBackup, join(projectDir, 'package-lock.json'));
+    }
+    // Remove marker (wasn't there before migration)
+    const markerPath = join(projectDir, '.voidforge');
+    if (existsSync(markerPath)) {
+        await rm(markerPath);
+    }
+}

package/dist/wizard/lib/natural-language-deploy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Natural Language Deploy — resolve prose deployment descriptions to YAML frontmatter.
+ *
+ * Parse: "I want a $20/month server with SSL and daily backups"
+ * → { deploy: 'vps', instanceType: 't3.small', hostname: '', resilience: { backups: 'daily', ... } }
+ *
+ * Uses keyword matching and heuristics — no AI API call required.
+ */
+export interface DeployConfig {
+    deploy: 'vps' | 'vercel' | 'railway' | 'cloudflare' | 'static' | 'docker';
+    instanceType: string;
+    hostname: string;
+    estimatedMonthlyCost: string;
+    resilience: {
+        multiEnv: boolean;
+        previewDeploys: boolean;
+        rollback: boolean;
+        migrations: 'auto' | 'manual' | 'no';
+        backups: 'daily' | 'weekly' | 'no';
+        healthCheck: boolean;
+        gracefulShutdown: boolean;
+        errorBoundaries: boolean;
+        rateLimiting: boolean;
+        deadLetterQueue: boolean;
+    };
+    reasoning: string[];
+}
+export declare function resolveDeployConfig(prose: string): DeployConfig | null;
+/** Convert a DeployConfig to YAML frontmatter fragment. */
+export declare function toFrontmatter(config: DeployConfig): string;