voidforge-build 23.9.1

package/dist/wizard/lib/herald.js

@@ -0,0 +1,167 @@
+/**
+ * The Herald — intelligent agent dispatch via Haiku pre-scan.
+ *
+ * Before every major slash command, a single Haiku call selects the optimal
+ * agent roster from all agents based on the current context. ADR-048.
+ */
+import { request as httpsRequest } from 'node:https';
+import { readFile } from 'node:fs/promises';
+import { execCommand } from './exec.js';
+// ── Constants ───────────────────────────────────────────
+const HAIKU_MODEL = 'claude-haiku-4-5-20251001';
+const HERALD_TIMEOUT_MS = 10_000;
+const FILE_TREE_LIMIT = 80;
+const PRD_HEAD_LINES = 30;
+// ── Herald core ─────────────────────────────────────────
+function buildPrompt(input, agents) {
+    const agentList = agents
+        .map((a) => {
+        const tags = a.tags?.length ? ` [${a.tags.join(', ')}]` : '';
+        return `- ${a.id}: ${a.description}${tags}`;
+    })
+        .join('\n');
+    const sections = [
+        `Command: ${input.command}`,
+        input.userArgs ? `Arguments: ${input.userArgs}` : null,
+        input.focus ? `Focus bias: ${input.focus}` : null,
+        `\nCodebase files (top ${FILE_TREE_LIMIT}):\n${input.fileTree.join('\n')}`,
+        input.prdFrontmatter ? `\nPRD frontmatter:\n${input.prdFrontmatter}` : null,
+        input.gitDiffSummary ? `\nUncommitted changes:\n${input.gitDiffSummary}` : null,
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return [
+        'You are the Herald, an agent dispatch selector. Given the context below and the full agent registry, select which agents should be dispatched.',
+        '',
+        'Rules:',
+        '- OVER-INCLUDE rather than under-include. A false positive costs one sub-agent launch. A false negative costs a missed finding.',
+        '- Select agents whose expertise is relevant to the codebase content AND the command type.',
+        '- If a --focus bias is provided, weight matching agents higher but do not exclude others that are relevant.',
+        '- Typical roster size: 15-40 agents. Select fewer only if the codebase is genuinely narrow.',
+        '- Output ONLY a JSON object with keys: roster (array of agent IDs), reasoning (string), estimatedAgents (number).',
+        '',
+        '--- CONTEXT ---',
+        sections,
+        '',
+        '--- AGENT REGISTRY ---',
+        agentList,
+    ].join('\n');
+}
+function callHaiku(apiKey, prompt) {
+    return new Promise((resolve, reject) => {
+        const postData = JSON.stringify({
+            model: HAIKU_MODEL,
+            max_tokens: 4096,
+            messages: [{ role: 'user', content: prompt }],
+        });
+        const req = httpsRequest({
+            hostname: 'api.anthropic.com',
+            path: '/v1/messages',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01',
+                'Content-Length': Buffer.byteLength(postData),
+            },
+            timeout: HERALD_TIMEOUT_MS,
+        }, (res) => {
+            let body = '';
+            res.on('data', (chunk) => { body += chunk.toString(); });
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`Herald API returned ${res.statusCode}: ${body}`));
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(body);
+                    const text = parsed.content?.[0]?.text ?? '';
+                    resolve(text);
+                }
+                catch {
+                    reject(new Error('Failed to parse Herald response'));
+                }
+            });
+        });
+        req.on('error', reject);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Herald request timed out'));
+        });
+        req.write(postData);
+        req.end();
+    });
+}
+function parseHeraldResponse(text) {
+    // Extract JSON from response — Haiku may wrap it in markdown fences
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch)
+        throw new Error('No JSON found in Herald response');
+    const parsed = JSON.parse(jsonMatch[0]);
+    const roster = Array.isArray(parsed.roster)
+        ? parsed.roster.filter((id) => typeof id === 'string')
+        : [];
+    const reasoning = typeof parsed.reasoning === 'string' ? parsed.reasoning : '';
+    const estimatedAgents = typeof parsed.estimatedAgents === 'number'
+        ? parsed.estimatedAgents
+        : (typeof parsed.estimated_agents === 'number' ? parsed.estimated_agents : roster.length);
+    return { roster, reasoning, estimatedAgents };
+}
+export async function runHerald(input, agents) {
+    const apiKey = process.env['ANTHROPIC_API_KEY'];
+    if (!apiKey)
+        return { roster: [], reasoning: 'No API key available', estimatedAgents: 0 };
+    try {
+        const prompt = buildPrompt(input, agents);
+        const text = await callHaiku(apiKey, prompt);
+        return parseHeraldResponse(text);
+    }
+    catch {
+        // Graceful degradation — command falls back to hardcoded manifest
+        return { roster: [], reasoning: 'Herald unavailable', estimatedAgents: 0 };
+    }
+}
+// ── Context gatherer ────────────────────────────────────
+export async function gatherHeraldContext(commandName, userArgs, focus) {
+    const [fileTree, prdFrontmatter, gitDiffSummary] = await Promise.all([
+        gatherFileTree(),
+        gatherPrdFrontmatter(),
+        gatherGitDiff(),
+    ]);
+    return { command: commandName, userArgs, focus, fileTree, prdFrontmatter, gitDiffSummary };
+}
+async function gatherFileTree() {
+    try {
+        const { stdout } = await execCommand('find', [
+            '.', '-type', 'f',
+            '(', '-name', '*.ts', '-o', '-name', '*.tsx', '-o', '-name', '*.py',
+            '-o', '-name', '*.js', '-o', '-name', '*.jsx', ')',
+            '-not', '-path', '*/node_modules/*',
+            '-not', '-path', '*/.git/*',
+            '-not', '-path', '*/dist/*',
+        ], { timeout: 5000 });
+        return stdout.split('\n').filter(Boolean).slice(0, FILE_TREE_LIMIT);
+    }
+    catch {
+        return [];
+    }
+}
+async function gatherPrdFrontmatter() {
+    try {
+        const content = await readFile('docs/PRD.md', 'utf-8');
+        const lines = content.split('\n').slice(0, PRD_HEAD_LINES);
+        return lines.join('\n');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function gatherGitDiff() {
+    try {
+        const { stdout } = await execCommand('git', ['diff', '--stat'], { timeout: 5000 });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/wizard/lib/http-helpers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared HTTP helpers — used across all API modules.
+ * Extracted to eliminate 13 duplicate sendJson() implementations.
+ */
+import type { ServerResponse } from 'node:http';
+/** Send a JSON response with the given status code. */
+export declare function sendJson(res: ServerResponse, status: number, data: unknown, noCache?: boolean): void;
+/** Read a file, returning null if it doesn't exist or fails. */
+export declare function readFileOrNull(path: string): Promise<string | null>;

package/dist/wizard/lib/http-helpers.js

@@ -0,0 +1,24 @@
+/**
+ * Shared HTTP helpers — used across all API modules.
+ * Extracted to eliminate 13 duplicate sendJson() implementations.
+ */
+import { readFile } from 'node:fs/promises';
+/** Send a JSON response with the given status code. */
+export function sendJson(res, status, data, noCache = false) {
+    const headers = { 'Content-Type': 'application/json; charset=utf-8' };
+    if (noCache) {
+        headers['Cache-Control'] = 'no-store';
+        headers['Pragma'] = 'no-cache';
+    }
+    res.writeHead(status, headers);
+    res.end(JSON.stringify(data));
+}
+/** Read a file, returning null if it doesn't exist or fails. */
+export async function readFileOrNull(path) {
+    try {
+        return await readFile(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/wizard/lib/image-gen.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Image generation provider abstraction — Celebrimbor's forge tools.
+ * Default: OpenAI (gpt-image-1). Extensible to other providers.
+ * Uses the same vault system as other VoidForge credentials.
+ */
+import type { ProvisionEmitter } from './provisioners/types.js';
+export interface ImageGenerationOptions {
+    prompt: string;
+    width: number;
+    height: number;
+    model?: string;
+    quality?: 'low' | 'medium' | 'high';
+}
+export interface GeneratedAsset {
+    name: string;
+    filename: string;
+    prompt: string;
+    size: string;
+    generatedAt: string;
+    hash: string;
+}
+export interface AssetManifest {
+    generated: string;
+    model: string;
+    style: string;
+    assets: GeneratedAsset[];
+}
+/**
+ * Generate an image via OpenAI's API.
+ * Returns the raw image bytes as a Buffer.
+ */
+export declare function generateImage(apiKey: string, options: ImageGenerationOptions, emit: ProvisionEmitter): Promise<Buffer | null>;
+/**
+ * Validate an OpenAI API key by making a lightweight models list request.
+ */
+export declare function validateOpenAIKey(apiKey: string): Promise<boolean>;
+/**
+ * Estimate the cost of generating N images.
+ */
+export declare function estimateImageCost(count: number, model?: string): number;
+/**
+ * Read the asset manifest from disk.
+ */
+export declare function readManifest(imagesDir: string): Promise<AssetManifest | null>;
+/**
+ * Write the asset manifest to disk.
+ */
+export declare function writeManifest(imagesDir: string, manifest: AssetManifest): Promise<void>;
+/**
+ * Save a generated image to disk and update the manifest.
+ */
+export declare function saveGeneratedImage(imagesDir: string, category: string, name: string, imageBuffer: Buffer, prompt: string, size: string, manifest: AssetManifest): Promise<string>;
+/**
+ * Check if an asset already exists on disk.
+ */
+export declare function assetExists(imagesDir: string, category: string, name: string): boolean;

package/dist/wizard/lib/image-gen.js

@@ -0,0 +1,159 @@
+/**
+ * Image generation provider abstraction — Celebrimbor's forge tools.
+ * Default: OpenAI (gpt-image-1). Extensible to other providers.
+ * Uses the same vault system as other VoidForge credentials.
+ */
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { httpsPost, httpsGet, safeJsonParse } from './provisioners/http-client.js';
+// ── OpenAI Provider ──────────────────────────────────────
+const OPENAI_API = 'api.openai.com';
+/**
+ * Generate an image via OpenAI's API.
+ * Returns the raw image bytes as a Buffer.
+ */
+export async function generateImage(apiKey, options, emit) {
+    const model = options.model || 'gpt-image-1';
+    const size = `${options.width}x${options.height}`;
+    // OpenAI only supports specific sizes — map to nearest and warn
+    const validSizes = ['1024x1024', '1792x1024', '1024x1792'];
+    const actualSize = validSizes.includes(size) ? size : '1024x1024';
+    if (actualSize !== size) {
+        emit({ step: 'image-gen', status: 'started', message: `Requested ${size} → using ${actualSize} (API constraint)` });
+    }
+    const body = JSON.stringify({
+        model,
+        prompt: options.prompt,
+        n: 1,
+        size: actualSize,
+        quality: options.quality || 'medium',
+        response_format: 'b64_json',
+    });
+    // Retry logic: 3 attempts with exponential backoff (1s, 3s, 9s)
+    // DALL-E 3 returns 500 errors on ~15% of requests (field report #1)
+    const MAX_RETRIES = 3;
+    const BACKOFF_BASE_MS = 1000;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const res = await httpsPost(OPENAI_API, '/v1/images/generations', {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            }, body, 120_000); // 2 min timeout for image generation
+            if (res.status === 500 || res.status === 502 || res.status === 503) {
+                // Server error — retry with backoff
+                if (attempt < MAX_RETRIES) {
+                    const delay = BACKOFF_BASE_MS * Math.pow(3, attempt - 1);
+                    emit({ step: 'image-gen', status: 'started', message: `Server error (${res.status}), retrying in ${delay / 1000}s (attempt ${attempt}/${MAX_RETRIES})` });
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+                emit({ step: 'image-gen', status: 'error', message: `Server error (${res.status}) after ${MAX_RETRIES} attempts` });
+                return null;
+            }
+            if (res.status !== 200) {
+                const errData = safeJsonParse(res.body);
+                const errMsg = errData?.error?.message || `API returned ${res.status}`;
+                emit({ step: 'image-gen', status: 'error', message: `Generation failed: ${errMsg}` });
+                return null;
+            }
+            const data = safeJsonParse(res.body);
+            const b64 = data?.data?.[0]?.b64_json;
+            if (!b64) {
+                emit({ step: 'image-gen', status: 'error', message: 'No image data in API response' });
+                return null;
+            }
+            if (attempt > 1) {
+                emit({ step: 'image-gen', status: 'done', message: `Succeeded on attempt ${attempt}` });
+            }
+            return Buffer.from(b64, 'base64');
+        }
+        catch (err) {
+            if (attempt < MAX_RETRIES) {
+                const delay = BACKOFF_BASE_MS * Math.pow(3, attempt - 1);
+                emit({ step: 'image-gen', status: 'started', message: `Request failed, retrying in ${delay / 1000}s (attempt ${attempt}/${MAX_RETRIES})`, detail: err.message });
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            emit({ step: 'image-gen', status: 'error', message: `Image generation failed after ${MAX_RETRIES} attempts`, detail: err.message });
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Validate an OpenAI API key by making a lightweight models list request.
+ */
+export async function validateOpenAIKey(apiKey) {
+    try {
+        const res = await httpsGet(OPENAI_API, '/v1/models', {
+            'Authorization': `Bearer ${apiKey}`,
+        }, 10_000);
+        return res.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Estimate the cost of generating N images.
+ */
+export function estimateImageCost(count, model = 'gpt-image-1') {
+    const costPerImage = {
+        'gpt-image-1': 0.04,
+        'dall-e-3': 0.08,
+    };
+    return count * (costPerImage[model] || 0.04);
+}
+// ── Asset Manifest ──────────────────────────────────────
+const MANIFEST_FILENAME = 'manifest.json';
+/**
+ * Read the asset manifest from disk.
+ */
+export async function readManifest(imagesDir) {
+    const manifestPath = join(imagesDir, MANIFEST_FILENAME);
+    try {
+        const content = await readFile(manifestPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the asset manifest to disk.
+ */
+export async function writeManifest(imagesDir, manifest) {
+    await mkdir(imagesDir, { recursive: true });
+    await writeFile(join(imagesDir, MANIFEST_FILENAME), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Save a generated image to disk and update the manifest.
+ */
+export async function saveGeneratedImage(imagesDir, category, name, imageBuffer, prompt, size, manifest) {
+    const categoryDir = join(imagesDir, category);
+    await mkdir(categoryDir, { recursive: true });
+    const filename = `${category}/${name}.png`;
+    const filepath = join(imagesDir, filename);
+    await writeFile(filepath, imageBuffer);
+    const hash = createHash('sha256').update(imageBuffer).digest('hex');
+    // Remove any existing entry with the same filename (dedup for --regen)
+    manifest.assets = manifest.assets.filter(a => a.filename !== filename);
+    manifest.assets.push({
+        name,
+        filename,
+        prompt,
+        size,
+        generatedAt: new Date().toISOString(),
+        hash: `sha256:${hash}`,
+    });
+    await writeManifest(imagesDir, manifest);
+    return filepath;
+}
+/**
+ * Check if an asset already exists on disk.
+ */
+export function assetExists(imagesDir, category, name) {
+    return existsSync(join(imagesDir, category, `${name}.png`));
+}

package/dist/wizard/lib/instance-sizing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * EC2 instance type recommendation based on PRD scope signals.
+ * Pure function — no side effects, no AWS calls.
+ */
+export declare const VALID_INSTANCE_TYPES: readonly ["t3.micro", "t3.small", "t3.medium", "t3.large"];
+export type InstanceType = typeof VALID_INSTANCE_TYPES[number];
+export interface SizingInput {
+    type?: string;
+    framework?: string;
+    database?: string;
+    cache?: string;
+    workers?: string;
+    payments?: string;
+}
+/**
+ * Recommend an EC2 instance type based on PRD signals.
+ * Never auto-recommends above t3.medium (cost protection).
+ */
+export declare function recommendInstanceType(input: SizingInput): InstanceType;
+/** Map EC2 instance type to matching RDS instance class. */
+export declare function rdsInstanceClass(instanceType: InstanceType): string;
+/** Map EC2 instance type to matching ElastiCache node type. */
+export declare function cacheNodeType(instanceType: InstanceType): string;
+/** Recommended swap size in GB based on instance memory. */
+export declare function swapSizeGb(instanceType: InstanceType): number;
+export declare function isValidInstanceType(value: string): value is InstanceType;

package/dist/wizard/lib/instance-sizing.js

@@ -0,0 +1,51 @@
+/**
+ * EC2 instance type recommendation based on PRD scope signals.
+ * Pure function — no side effects, no AWS calls.
+ */
+export const VALID_INSTANCE_TYPES = ['t3.micro', 't3.small', 't3.medium', 't3.large'];
+/**
+ * Recommend an EC2 instance type based on PRD signals.
+ * Never auto-recommends above t3.medium (cost protection).
+ */
+export function recommendInstanceType(input) {
+    // Static sites and prototypes always get micro
+    if (input.type === 'static-site' || input.type === 'prototype') {
+        return 't3.micro';
+    }
+    let score = 0;
+    if (input.database === 'postgres' || input.database === 'mysql')
+        score++;
+    if (input.cache === 'redis')
+        score++;
+    if (input.workers === 'yes')
+        score++;
+    if (input.payments === 'stripe' || input.payments === 'lemonsqueezy')
+        score++;
+    if (input.framework === 'next.js')
+        score++; // SSR is memory-hungry
+    if (score >= 4)
+        return 't3.medium';
+    if (score >= 2)
+        return 't3.small';
+    return 't3.micro';
+}
+/** Map EC2 instance type to matching RDS instance class. */
+export function rdsInstanceClass(instanceType) {
+    return `db.${instanceType}`;
+}
+/** Map EC2 instance type to matching ElastiCache node type. */
+export function cacheNodeType(instanceType) {
+    return `cache.${instanceType}`;
+}
+/** Recommended swap size in GB based on instance memory. */
+export function swapSizeGb(instanceType) {
+    switch (instanceType) {
+        case 't3.micro': return 2;
+        case 't3.small': return 2;
+        case 't3.medium': return 1;
+        case 't3.large': return 0;
+    }
+}
+export function isValidInstanceType(value) {
+    return VALID_INSTANCE_TYPES.includes(value);
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Kongo Analytics — Campaign analytics and computed growth signal.
+ *
+ * Kongo doesn't have a dedicated growth-signal endpoint, so we compute it
+ * client-side from the campaign analytics data using statistical analysis.
+ *
+ * Real Kongo API endpoint:
+ * - GET /engine/campaigns/:campaignId/analytics — per-variant breakdown
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.3
+ */
+import { KongoClient } from './client.js';
+import type { CampaignAnalytics, AnalyticsPeriod, ComputedGrowthSignal } from './types.js';
+/**
+ * Get campaign analytics with per-variant, per-source, and daily breakdown.
+ */
+export declare function getCampaignAnalytics(client: KongoClient, campaignId: string, period?: AnalyticsPeriod): Promise<CampaignAnalytics>;
+/**
+ * Compute a growth signal from campaign analytics.
+ *
+ * This replaces the hypothetical /growth-signal endpoint from the PRD.
+ * Uses two-proportion z-test to determine if any variant significantly
+ * outperforms the control (first variant by order).
+ */
+export declare function computeGrowthSignal(campaignId: string, analytics: CampaignAnalytics): ComputedGrowthSignal;
+/**
+ * Fetch analytics and compute growth signal in one call.
+ */
+export declare function getGrowthSignal(client: KongoClient, campaignId: string, period?: AnalyticsPeriod): Promise<ComputedGrowthSignal>;