voidforge-build 23.10.0 → 23.11.0

package/dist/wizard/lib/codegen/openapi-gen.js

@@ -0,0 +1,79 @@
+/**
+ * OpenAPI/Swagger spec generation (ADR-025).
+ * Generates a starter OpenAPI spec from framework conventions.
+ * Framework-aware: Express, Next.js API routes.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+function generateOpenAPISpec(projectName, framework) {
+    const isNextjs = framework === 'next.js';
+    // Strip YAML-unsafe characters — only allow alphanumeric, spaces, hyphens, underscores
+    const safeName = projectName.replace(/[^a-zA-Z0-9 _-]/g, '').slice(0, 100) || 'My Project';
+    return `# OpenAPI Specification
+# Generated by VoidForge (ADR-025)
+# Edit this file to document your API endpoints
+# Serve with: npx swagger-ui-express (Express) or next-swagger-doc (Next.js)
+
+openapi: "3.1.0"
+info:
+  title: "${safeName} API"
+  version: "1.0.0"
+  description: "API documentation for ${safeName}"
+
+servers:
+  - url: http://localhost:${isNextjs ? '3000' : '3001'}
+    description: Development server
+
+paths:
+  /api/health:
+    get:
+      summary: Health check
+      responses:
+        "200":
+          description: Service is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: "ok"
+                  timestamp:
+                    type: string
+                    format: date-time
+
+  # Add your API endpoints below
+  # Example:
+  # /api/users:
+  #   get:
+  #     summary: List users
+  #     parameters:
+  #       - in: query
+  #         name: page
+  #         schema:
+  #           type: integer
+  #           default: 1
+  #     responses:
+  #       "200":
+  #         description: List of users
+`;
+}
+/**
+ * Generate an OpenAPI spec file for the project.
+ */
+export async function generateOpenAPIDoc(projectDir, projectName, framework, emit) {
+    emit({ step: 'openapi', status: 'started', message: 'Generating OpenAPI spec' });
+    try {
+        const docsDir = join(projectDir, 'docs');
+        await mkdir(docsDir, { recursive: true });
+        const spec = generateOpenAPISpec(projectName, framework);
+        await writeFile(join(docsDir, 'api.yaml'), spec, 'utf-8');
+        emit({ step: 'openapi', status: 'done', message: 'Generated docs/api.yaml — edit to document your API endpoints' });
+        return { success: true, file: 'docs/api.yaml' };
+    }
+    catch (err) {
+        emit({ step: 'openapi', status: 'error', message: 'Failed to generate OpenAPI spec', detail: err.message });
+        return { success: false, file: '', error: err.message };
+    }
+}

package/dist/wizard/lib/codegen/prisma-types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Type generation from Prisma schema (ADR-025).
+ * After Prisma schema changes, runs prisma generate and creates a barrel export.
+ * Conditional — only runs if prisma/schema.prisma exists.
+ */
+import type { ProvisionEmitter } from '../provisioners/types.js';
+export interface PrismaTypesResult {
+    success: boolean;
+    files: string[];
+    error?: string;
+}
+/**
+ * Run prisma generate and create a barrel export for types.
+ */
+export declare function generatePrismaTypes(projectDir: string, emit: ProvisionEmitter): Promise<PrismaTypesResult>;

package/dist/wizard/lib/codegen/prisma-types.js

@@ -0,0 +1,44 @@
+/**
+ * Type generation from Prisma schema (ADR-025).
+ * After Prisma schema changes, runs prisma generate and creates a barrel export.
+ * Conditional — only runs if prisma/schema.prisma exists.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { execCommand } from '../exec.js';
+/**
+ * Run prisma generate and create a barrel export for types.
+ */
+export async function generatePrismaTypes(projectDir, emit) {
+    const schemaPath = join(projectDir, 'prisma', 'schema.prisma');
+    if (!existsSync(schemaPath)) {
+        emit({ step: 'prisma-types', status: 'skipped', message: 'No prisma/schema.prisma found — type generation skipped' });
+        return { success: true, files: [] };
+    }
+    emit({ step: 'prisma-types', status: 'started', message: 'Generating Prisma types' });
+    try {
+        // Run prisma generate
+        await execCommand('npx', ['prisma', 'generate'], {
+            cwd: projectDir,
+            timeout: 60_000,
+        });
+        // Create barrel export
+        const typesDir = join(projectDir, 'types');
+        await mkdir(typesDir, { recursive: true });
+        const barrelContent = `// Auto-generated barrel export for Prisma types
+// Re-run: npx prisma generate
+// Generated by VoidForge (ADR-025)
+
+export * from '@prisma/client';
+export type { Prisma } from '@prisma/client';
+`;
+        await writeFile(join(typesDir, 'index.ts'), barrelContent, 'utf-8');
+        emit({ step: 'prisma-types', status: 'done', message: 'Prisma types generated — import from types/index.ts' });
+        return { success: true, files: ['types/index.ts'] };
+    }
+    catch (err) {
+        emit({ step: 'prisma-types', status: 'error', message: 'Failed to generate Prisma types', detail: err.message });
+        return { success: false, files: [], error: err.message };
+    }
+}

package/dist/wizard/lib/codegen/seed-gen.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Database seeding script generation (ADR-025).
+ * Generates seed.ts with factory functions for all Prisma models.
+ * Conditional — only runs if prisma/schema.prisma exists.
+ */
+import type { ProvisionEmitter } from '../provisioners/types.js';
+export interface SeedResult {
+    success: boolean;
+    file: string;
+    modelCount: number;
+    error?: string;
+}
+/**
+ * Generate a database seed script from the Prisma schema.
+ */
+export declare function generateSeedScript(projectDir: string, emit: ProvisionEmitter): Promise<SeedResult>;

package/dist/wizard/lib/codegen/seed-gen.js

@@ -0,0 +1,128 @@
+/**
+ * Database seeding script generation (ADR-025).
+ * Generates seed.ts with factory functions for all Prisma models.
+ * Conditional — only runs if prisma/schema.prisma exists.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+/** Map Prisma types to TypeScript factory values. */
+const FACTORY_VALUES = {
+    'String': "'Test value'",
+    'Int': '1',
+    'Float': '1.0',
+    'Boolean': 'true',
+    'DateTime': 'new Date()',
+    'Json': '{}',
+    'BigInt': 'BigInt(1)',
+    'Decimal': '1.0',
+};
+function parseSeedModels(content) {
+    const models = [];
+    const modelRegex = /model\s+(\w+)\s*\{([^}]+)\}/g;
+    let match;
+    while ((match = modelRegex.exec(content)) !== null) {
+        const name = match[1];
+        const body = match[2];
+        const fields = [];
+        const builtinTypes = ['String', 'Int', 'Float', 'Boolean', 'DateTime', 'Json', 'BigInt', 'Decimal', 'Bytes'];
+        for (const line of body.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('@@'))
+                continue;
+            const fieldMatch = trimmed.match(/^(\w+)\s+(\w+)(\[\])?\s*(\?)?\s*(.*)/);
+            if (fieldMatch) {
+                const fieldName = fieldMatch[1];
+                const fieldType = fieldMatch[2];
+                const isOptional = !!fieldMatch[4];
+                const rest = fieldMatch[5] || '';
+                const hasDefault = rest.includes('@default');
+                const isId = rest.includes('@id');
+                const isRelation = !builtinTypes.includes(fieldType);
+                if (!isRelation && !fieldMatch[3]) { // Skip arrays (relations)
+                    fields.push({ name: fieldName, type: fieldType, isOptional, hasDefault, isId, isRelation });
+                }
+            }
+        }
+        models.push({ name, fields });
+    }
+    return models;
+}
+function buildSeedContent(models) {
+    const factories = [];
+    const seedCalls = [];
+    for (const model of models) {
+        const lowerName = model.name.charAt(0).toLowerCase() + model.name.slice(1);
+        const factoryFields = model.fields
+            .filter(f => !f.isId && !f.hasDefault && !f.isOptional)
+            .map(f => `    ${f.name}: ${FACTORY_VALUES[f.type] || "'TODO'"},`)
+            .join('\n');
+        factories.push(`function create${model.name}(overrides: Partial<Prisma.${model.name}CreateInput> = {}): Prisma.${model.name}CreateInput {
+  return {
+${factoryFields}
+    ...overrides,
+  };
+}`);
+        seedCalls.push(`  // ${model.name}
+  const ${lowerName} = await prisma.${lowerName}.create({ data: create${model.name}() });
+  console.log('Created ${model.name}:', ${lowerName}.id ?? '(no id)');`);
+    }
+    return `// Database seed script — generated by VoidForge (ADR-025)
+// Run: npx tsx prisma/seed.ts
+// Or: npm run seed (add "seed": "npx tsx prisma/seed.ts" to package.json scripts)
+
+import { PrismaClient, Prisma } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+// ── Factory Functions ────────────────────────────────────
+
+${factories.join('\n\n')}
+
+// ── Seed ─────────────────────────────────────────────────
+
+async function seed() {
+  console.log('Seeding database...');
+
+${seedCalls.join('\n\n')}
+
+  console.log('Seeding complete.');
+}
+
+seed()
+  .catch((e) => {
+    console.error('Seed failed:', e);
+    process.exit(1);
+  })
+  .finally(() => prisma.$disconnect());
+`;
+}
+/**
+ * Generate a database seed script from the Prisma schema.
+ */
+export async function generateSeedScript(projectDir, emit) {
+    const schemaPath = join(projectDir, 'prisma', 'schema.prisma');
+    if (!existsSync(schemaPath)) {
+        emit({ step: 'seed', status: 'skipped', message: 'No prisma/schema.prisma found — seed generation skipped' });
+        return { success: true, file: '', modelCount: 0 };
+    }
+    emit({ step: 'seed', status: 'started', message: 'Generating database seed script' });
+    try {
+        const schema = await readFile(schemaPath, 'utf-8');
+        const models = parseSeedModels(schema);
+        if (models.length === 0) {
+            emit({ step: 'seed', status: 'skipped', message: 'No models found in Prisma schema' });
+            return { success: true, file: '', modelCount: 0 };
+        }
+        const prismaDir = join(projectDir, 'prisma');
+        await mkdir(prismaDir, { recursive: true });
+        const script = buildSeedContent(models);
+        await writeFile(join(prismaDir, 'seed.ts'), script, 'utf-8');
+        emit({ step: 'seed', status: 'done', message: `Generated prisma/seed.ts — ${models.length} model factories. Run: npx tsx prisma/seed.ts` });
+        return { success: true, file: 'prisma/seed.ts', modelCount: models.length };
+    }
+    catch (err) {
+        emit({ step: 'seed', status: 'error', message: 'Failed to generate seed script', detail: err.message });
+        return { success: false, file: '', modelCount: 0, error: err.message };
+    }
+}

package/dist/wizard/lib/correlation-engine.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Chakotay's Correlation Engine — connects product changes to metric outcomes (v12.2).
+ *
+ * Maintains an event log of product changes (campaigns, deploys) and metric
+ * observations (traffic, conversions, revenue, performance scores). Computes
+ * before/after comparisons to identify which changes drove which outcomes.
+ *
+ * PRD Reference: ROADMAP v12.2, DEEP_CURRENT.md LEARN step
+ */
+import type { CampaignProposal } from './campaign-proposer.js';
+interface ChangeEvent {
+    type: 'campaign_complete' | 'deploy' | 'config_change';
+    date: string;
+    campaign?: string;
+    missions?: number;
+    dimension?: string;
+    description: string;
+}
+interface MetricObservation {
+    type: 'metric';
+    date: string;
+    metric: string;
+    value: number;
+    source: string;
+}
+interface Correlation {
+    type: 'correlation';
+    date: string;
+    productChange: string;
+    metric: string;
+    valueBefore: number;
+    valueAfter: number;
+    delta: string;
+    confidence: 'high' | 'medium' | 'low';
+    lagDays: number;
+}
+export declare function logCampaignComplete(name: string, missions: number, dimension: string): Promise<void>;
+export declare function logMetric(metric: string, value: number, source: string): Promise<void>;
+/**
+ * Detect correlations between recent campaigns and metric changes.
+ * Uses before/after comparison with configurable lag windows.
+ */
+export declare function detectCorrelations(lagDays?: number): Promise<Correlation[]>;
+interface PredictionRecord {
+    proposalId: string;
+    proposalName: string;
+    predictedImpact: string;
+    actualImpact?: string;
+    accuracy?: number;
+    recordedAt: string;
+    evaluatedAt?: string;
+}
+export declare function recordPrediction(proposal: CampaignProposal): Promise<void>;
+export declare function evaluatePrediction(proposalId: string, actualImpact: string, accuracy: number): Promise<void>;
+/**
+ * Calculate average prediction accuracy across all evaluated predictions.
+ */
+export declare function getAveragePredictionAccuracy(): Promise<number>;
+export type { ChangeEvent, MetricObservation, Correlation, PredictionRecord };

package/dist/wizard/lib/correlation-engine.js

@@ -0,0 +1,152 @@
+/**
+ * Chakotay's Correlation Engine — connects product changes to metric outcomes (v12.2).
+ *
+ * Maintains an event log of product changes (campaigns, deploys) and metric
+ * observations (traffic, conversions, revenue, performance scores). Computes
+ * before/after comparisons to identify which changes drove which outcomes.
+ *
+ * PRD Reference: ROADMAP v12.2, DEEP_CURRENT.md LEARN step
+ */
+import { appendFile, readFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { correlationsPath, predictionsPath, deepCurrentDir } from './deep-current.js';
+import { findProjectRoot } from './marker.js';
+// ── Event Logging ─────────────────────────────────────
+async function appendEvent(entry) {
+    await mkdir(deepCurrentDir(findProjectRoot() ?? process.cwd()), { recursive: true });
+    await appendFile(correlationsPath(findProjectRoot() ?? process.cwd()), JSON.stringify(entry) + '\n', 'utf-8');
+}
+export async function logCampaignComplete(name, missions, dimension) {
+    await appendEvent({
+        type: 'campaign_complete',
+        date: new Date().toISOString(),
+        campaign: name,
+        missions,
+        dimension,
+        description: `Campaign "${name}" completed (${missions} missions, targeting ${dimension})`,
+    });
+}
+export async function logMetric(metric, value, source) {
+    await appendEvent({
+        type: 'metric',
+        date: new Date().toISOString(),
+        metric,
+        value,
+        source,
+    });
+}
+// ── Correlation Detection ─────────────────────────────
+/**
+ * Detect correlations between recent campaigns and metric changes.
+ * Uses before/after comparison with configurable lag windows.
+ */
+export async function detectCorrelations(lagDays = 7) {
+    if (!existsSync(correlationsPath(findProjectRoot() ?? process.cwd())))
+        return [];
+    const content = await readFile(correlationsPath(findProjectRoot() ?? process.cwd()), 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    const events = lines.map(l => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return null;
+    } }).filter(Boolean);
+    const changes = events.filter(e => e.type === 'campaign_complete');
+    const metrics = events.filter(e => e.type === 'metric');
+    const correlations = [];
+    for (const change of changes) {
+        const changeDate = new Date(change.date).getTime();
+        // Find metrics of the same type before and after the change
+        const metricNames = [...new Set(metrics.map(m => m.metric))];
+        for (const metricName of metricNames) {
+            const metricsOfType = metrics.filter(m => m.metric === metricName);
+            // Before: last metric reading before the change
+            const before = metricsOfType
+                .filter(m => new Date(m.date).getTime() < changeDate)
+                .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())[0];
+            // After: first metric reading lagDays after the change
+            const afterCutoff = changeDate + lagDays * 24 * 60 * 60 * 1000;
+            const after = metricsOfType
+                .filter(m => {
+                const t = new Date(m.date).getTime();
+                return t > changeDate && t <= afterCutoff;
+            })
+                .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())[0];
+            if (before && after && before.value !== after.value) {
+                const delta = after.value - before.value;
+                const pctChange = before.value !== 0 ? Math.round((delta / before.value) * 100) : 0;
+                const significance = Math.abs(pctChange);
+                // Only record meaningful changes (>5%)
+                if (significance > 5) {
+                    const correlation = {
+                        type: 'correlation',
+                        date: new Date().toISOString(),
+                        productChange: change.campaign || change.description,
+                        metric: metricName,
+                        valueBefore: before.value,
+                        valueAfter: after.value,
+                        delta: `${delta > 0 ? '+' : ''}${pctChange}%`,
+                        confidence: significance > 30 ? 'high' : significance > 15 ? 'medium' : 'low',
+                        lagDays,
+                    };
+                    correlations.push(correlation);
+                    await appendEvent(correlation); // Record the correlation in the log
+                }
+            }
+        }
+    }
+    return correlations;
+}
+export async function recordPrediction(proposal) {
+    await mkdir(deepCurrentDir(findProjectRoot() ?? process.cwd()), { recursive: true });
+    const record = {
+        proposalId: proposal.id,
+        proposalName: proposal.name,
+        predictedImpact: proposal.expectedImpact,
+        recordedAt: new Date().toISOString(),
+    };
+    await appendFile(predictionsPath(findProjectRoot() ?? process.cwd()), JSON.stringify(record) + '\n', 'utf-8');
+}
+export async function evaluatePrediction(proposalId, actualImpact, accuracy) {
+    // Read existing predictions, find the matching one, update it
+    if (!existsSync(predictionsPath(findProjectRoot() ?? process.cwd())))
+        return;
+    const content = await readFile(predictionsPath(findProjectRoot() ?? process.cwd()), 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    const updated = lines.map(line => {
+        try {
+            const record = JSON.parse(line);
+            if (record.proposalId === proposalId) {
+                record.actualImpact = actualImpact;
+                record.accuracy = accuracy;
+                record.evaluatedAt = new Date().toISOString();
+            }
+            return JSON.stringify(record);
+        }
+        catch {
+            return line;
+        }
+    });
+    const { writeFile: wf } = await import('node:fs/promises');
+    await wf(predictionsPath(findProjectRoot() ?? process.cwd()), updated.join('\n') + '\n');
+}
+/**
+ * Calculate average prediction accuracy across all evaluated predictions.
+ */
+export async function getAveragePredictionAccuracy() {
+    if (!existsSync(predictionsPath(findProjectRoot() ?? process.cwd())))
+        return 0;
+    const content = await readFile(predictionsPath(findProjectRoot() ?? process.cwd()), 'utf-8');
+    const records = content.trim().split('\n').filter(Boolean)
+        .map(l => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return null;
+    } })
+        .filter(Boolean);
+    const evaluated = records.filter(r => r.accuracy !== undefined);
+    if (evaluated.length === 0)
+        return 0;
+    return evaluated.reduce((sum, r) => sum + (r.accuracy || 0), 0) / evaluated.length;
+}

package/dist/wizard/lib/desktop-notify.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Desktop Notifications — macOS/Linux native notifications for daemon events.
+ *
+ * Uses osascript on macOS and notify-send on Linux. No dependencies.
+ * Notifications are non-blocking and failure-tolerant (notification failure
+ * should never crash the daemon).
+ *
+ * PRD Reference: §9.7 (Danger Room shows warning), v11.3 deliverables
+ */
+type NotificationUrgency = 'low' | 'normal' | 'critical';
+interface NotificationOptions {
+    title: string;
+    message: string;
+    urgency?: NotificationUrgency;
+    sound?: boolean;
+}
+/**
+ * Send a desktop notification. Fails silently — never throws.
+ */
+export declare function notify(opts: NotificationOptions): void;
+export declare function notifySpendSpike(platform: string, amount: string): void;
+export declare function notifyCampaignKilled(name: string, reason: string): void;
+export declare function notifyTokenExpiring(platform: string, hoursLeft: number): void;
+export declare function notifyReconciliationDiscrepancy(platform: string, amount: string): void;
+export declare function notifyVaultExpiring(hoursLeft: number): void;
+export declare function notifyRevenueMilestone(amount: string): void;
+export {};

package/dist/wizard/lib/desktop-notify.js

@@ -0,0 +1,98 @@
+/**
+ * Desktop Notifications — macOS/Linux native notifications for daemon events.
+ *
+ * Uses osascript on macOS and notify-send on Linux. No dependencies.
+ * Notifications are non-blocking and failure-tolerant (notification failure
+ * should never crash the daemon).
+ *
+ * PRD Reference: §9.7 (Danger Room shows warning), v11.3 deliverables
+ */
+import { execFileSync } from 'node:child_process';
+import { platform } from 'node:os';
+/**
+ * Send a desktop notification. Fails silently — never throws.
+ */
+export function notify(opts) {
+    try {
+        if (platform() === 'darwin') {
+            notifyMacOS(opts);
+        }
+        else if (platform() === 'linux') {
+            notifyLinux(opts);
+        }
+        // Windows: notifications deferred — WSL2 path recommended
+    }
+    catch {
+        // Notification failure is never fatal
+    }
+}
+function notifyMacOS(opts) {
+    // SEC-005: Use execFileSync with args array to prevent shell injection
+    const sound = opts.sound !== false ? ' sound name "Submarine"' : '';
+    const script = `display notification "${sanitize(opts.message)}" with title "VoidForge"${sound} subtitle "${sanitize(opts.title)}"`;
+    try {
+        execFileSync('osascript', ['-e', script], { timeout: 5000, stdio: 'ignore' });
+    }
+    catch { /* notification failure is never fatal */ }
+}
+function notifyLinux(opts) {
+    // SEC-006: Use execFileSync with args array, validate urgency enum
+    const validUrgencies = ['low', 'normal', 'critical'];
+    const urgency = validUrgencies.includes(opts.urgency || '') ? opts.urgency : 'normal';
+    try {
+        execFileSync('notify-send', ['-u', urgency, '-a', 'VoidForge', sanitize(opts.title), sanitize(opts.message)], { timeout: 5000, stdio: 'ignore' });
+    }
+    catch { /* notification failure is never fatal */ }
+}
+/** Strip characters that could be dangerous in shell/AppleScript contexts */
+function sanitize(input) {
+    return input.replace(/[`$\\"\n\r\0]/g, '').slice(0, 200);
+}
+// ── Daemon Event Notifications ────────────────────────
+// Pre-built notifications for common daemon events (§9.20.7 agent voice)
+export function notifySpendSpike(platform, amount) {
+    notify({
+        title: `Spend Spike — ${platform}`,
+        message: `Wax reports: ${platform} spend is ${amount} above average this hour.`,
+        urgency: 'critical',
+        sound: true,
+    });
+}
+export function notifyCampaignKilled(name, reason) {
+    notify({
+        title: 'Campaign Paused',
+        message: `Wax pulled the trigger on "${name}" — ${reason}.`,
+        urgency: 'normal',
+    });
+}
+export function notifyTokenExpiring(platform, hoursLeft) {
+    notify({
+        title: `Token Expiring — ${platform}`,
+        message: `Breeze warns: ${platform} token expires in ${hoursLeft} hours. Refresh needed.`,
+        urgency: hoursLeft < 2 ? 'critical' : 'normal',
+        sound: hoursLeft < 2,
+    });
+}
+export function notifyReconciliationDiscrepancy(platform, amount) {
+    notify({
+        title: 'Reconciliation Alert',
+        message: `Dockson: Numbers don't match on ${platform} — ${amount} discrepancy.`,
+        urgency: 'critical',
+        sound: true,
+    });
+}
+export function notifyVaultExpiring(hoursLeft) {
+    notify({
+        title: 'Vault Session Expiring',
+        message: `Vault session expires in ${hoursLeft} hour(s). Run \`voidforge heartbeat unlock\` to extend.`,
+        urgency: 'critical',
+        sound: true,
+    });
+}
+export function notifyRevenueMilestone(amount) {
+    notify({
+        title: 'Revenue Milestone!',
+        message: `Dockson: ${amount} total revenue. Every coin has a story — this one's a good chapter.`,
+        urgency: 'low',
+    });
+}

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;