voidforge-build 23.9.2 → 23.11.0

package/dist/docs/patterns/refactor-extraction.md

@@ -0,0 +1,96 @@
+# Pattern: Large-Refactor Extraction (8-commit per-entity)
+
+**When to use:** A 1,000+ LOC router/service/handler file needs splitting and the project has an existing exit gate (e.g., max-LOC-per-file). Single-commit refactors of files this size cause review fatigue, hide bugs in the diff noise, and are nearly impossible to revert surgically.
+
+**Source:** Field report #320 §1. M-10 (Union Station): `routers/crm.py` 1,861 → 597 LOC across 8 commits. 0 regressions. Test count grew 2,099 → 2,246 (+147). Exit gate met with 78 LOC of headroom. The 5th commit's IDOR matrix surfaced a route-shadow bug that had made `PATCH /people/batch-update` unreachable in production for an unknown duration.
+
+This is the cleanest large-refactor template I've documented. Use it.
+
+## Architecture-Quick (Picard)
+
+Before any commit, write a 1-2 page architecture doc to `logs/reviews/<topic>-architecture.md`:
+
+```markdown
+# Refactor: <topic> — extraction plan
+
+## Current state
+- Source file: <path> at <LOC>
+- Exit gate: <LOC limit>
+- LOC delta needed: <gate - current>
+
+## Entity inventory
+| Entity | Endpoints | Estimated LOC delta |
+|---|---|---|
+| people | 7 | -167 |
+| companies | 10 | -345 |
+| ... | ... | ... |
+| | **Total** | **−1264** |
+
+## Commit plan (one per entity + scaffold + cleanup)
+| # | Commit | Adds | Removes | Cumulative LOC |
+|---|---|---|---|---|
+| 1 | scaffold (service base, error types, shared helpers) | services/_base.py | — | 1861 |
+| 2 | extract people | services/people_service.py | router code | 1694 |
+| ... | ... | ... | ... | ... |
+| 8 | cleanup (lift duplicated helpers, prune imports, lint) | — | router cleanup | 597 |
+
+## Function-signature contract (per service)
+- org_id: int (first), user_id: str (second)
+- Returns plain dict (no FastAPI Response wrappers)
+- Raises ApiError (no HTTPException — service knows nothing of HTTP)
+- No FastAPI imports in service modules
+
+## Roles
+- Strange — lead, owns sequencing
+- Stark — router-side rewrites (thin wrappers calling service)
+- Batgirl — IDOR matrix tests per entity
+- Coulson — version + commit per step
+
+## IDOR contract
+- Pattern A (primary): every service method takes org_id as first param,
+  every query is scoped, every test in matrix asserts cross-org denial
+- Pattern B (fallback): if a method legitimately spans tenants, document
+  the policy and test cross-tenant authorization explicitly
+```
+
+## Per-Commit Shape
+
+Each entity commit follows the same shape. Keep them mechanically uniform:
+
+1. **Extract** to `services/<entity>_service.py` — pure business logic, no FastAPI imports
+2. **Rewrite** the router file as thin wrappers: validate → call service → format response
+3. **Add** IDOR matrix tests for parametric paths AND fixed-suffix paths under same entity prefix (see `/docs/methods/SECURITY_AUDITOR.md` IDOR Matrix section)
+4. **Verify** LOC trajectory: `git diff --stat HEAD~1 -- routers/<file>.py` shows monotonic decrease; service module count grows by 1
+5. **Run targeted pytest** on touched files only (`pytest tests/services/test_<entity>_service.py tests/routers/test_<entity>.py`) — full suite is the orchestrator's gate, not the agent's
+6. **Commit** with a "Deviations from Contract" section in the build report (see SUB_AGENTS.md)
+
+## Final Cleanup Commit
+
+Commit 8 (or N for an N-entity refactor) is non-obvious and load-bearing:
+
+- Lift duplicated helpers that emerged across entities into a shared module
+- Prune unused imports in the router file (extraction leaves behind imports the wrappers no longer need)
+- Add lint scaffold if missing (LOC limit, signature-contract assertion)
+- Verify no test files were dropped (mock paths often need updating to follow the extracted code)
+- Confirm exit gate met with documented headroom: `wc -l routers/<file>.py`
+
+## What This Pattern Caught
+
+The IDOR matrix test in commit 5 (M-10 batch.py) surfaced that `/people/{person_id}` was shadowing `/people/batch-update`. FastAPI dispatches first-matching-route; a parametric path declared first eats subsequent fixed-suffix paths. The fix is path-converter type hints (`{person_id:int}`), restricting the parametric route to integer paths.
+
+This bug had been latent in production. No unit test exercised it. No previous Gauntlet caught it. Without the IDOR matrix discipline this pattern bakes in, it would still be unreachable. (Field report #320 §1.)
+
+## Anti-Patterns
+
+- **Single-commit refactor** for files >1,000 LOC. Review fatigue + impossible to revert surgically.
+- **No architecture-quick.** Without Picard's plan, the LOC trajectory drifts and entities get extracted in dependency-violating order.
+- **No IDOR matrix.** Refactoring multi-tenant code without cross-tenant denial tests is just rearranging the leak surface.
+- **Mixing entity extractions in one commit.** Each commit must remain shippable independently with green tests. One commit per entity, no exceptions.
+- **Skipping the final cleanup commit.** Duplicated helpers that emerged across entities don't lift themselves; pruning matters.
+- **Running full pytest as the agent's last step.** See SUB_AGENTS.md "Build-Agent Pytest Sequencing" — agent response window truncates mid-suite, orchestrator has to reconstruct.
+
+## When NOT to Use
+
+- File is under ~600 LOC. Just split it in one commit; the overhead isn't worth it.
+- The file is genuinely cohesive (state machine, single algorithm, generated code). Extraction would fragment what should stay together.
+- The exit gate isn't binding — if there's no LOC limit and no clear quality reason to split, the refactor is yak-shaving.

package/dist/wizard/lib/anomaly-detection.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Anomaly Detection — Spend spikes, traffic drops, conversion changes (§9.17).
+ *
+ * Runs hourly as a heartbeat daemon scheduled job.
+ * Compares current metrics against rolling averages.
+ * Alerts when deviations exceed thresholds.
+ *
+ * PRD Reference: §9.7 (hourly anomaly detection), §9.17 (thresholds)
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+type AnomalyType = 'spend_spike' | 'traffic_drop' | 'conversion_change' | 'roas_drop';
+type AnomalySeverity = 'warning' | 'alert' | 'critical';
+interface Anomaly {
+    type: AnomalyType;
+    severity: AnomalySeverity;
+    platform?: string;
+    metric: string;
+    currentValue: number;
+    expectedValue: number;
+    deviationPercent: number;
+    message: string;
+    timestamp: string;
+}
+declare const THRESHOLDS: {
+    spendSpikeWarning: number;
+    spendSpikeAlert: number;
+    spendSpikeCritical: number;
+    trafficDropWarning: number;
+    trafficDropAlert: number;
+    trafficDropCritical: number;
+    conversionChangeThreshold: number;
+    roasDropWarning: number;
+    roasDropAlert: number;
+};
+/** Run all anomaly checks for the current period */
+export declare function runAnomalyDetection(metrics: {
+    spendByPlatform: Array<{
+        platform: string;
+        currentHour: Cents;
+        avgHourly: Cents;
+    }>;
+    traffic: {
+        currentDay: number;
+        avgDaily: number;
+    };
+    conversion: {
+        currentRate: number;
+        avgRate: number;
+    };
+    roasByPlatform: Array<{
+        platform: string;
+        current: number;
+        avg: number;
+    }>;
+}): Anomaly[];
+export type { Anomaly, AnomalyType, AnomalySeverity };
+export { THRESHOLDS };

package/dist/wizard/lib/anomaly-detection.js

@@ -0,0 +1,122 @@
+/**
+ * Anomaly Detection — Spend spikes, traffic drops, conversion changes (§9.17).
+ *
+ * Runs hourly as a heartbeat daemon scheduled job.
+ * Compares current metrics against rolling averages.
+ * Alerts when deviations exceed thresholds.
+ *
+ * PRD Reference: §9.7 (hourly anomaly detection), §9.17 (thresholds)
+ */
+// ── Thresholds ────────────────────────────────────────
+const THRESHOLDS = {
+    // Spend spike: current hour spend > X% of daily average hourly spend
+    spendSpikeWarning: 50, // 50% above average
+    spendSpikeAlert: 100, // 100% above average (double)
+    spendSpikeCritical: 200, // 200% above average (triple)
+    // Traffic drop: current day traffic > X% below 7-day average
+    trafficDropWarning: 20, // 20% below average
+    trafficDropAlert: 40, // 40% below average
+    trafficDropCritical: 60, // 60% below average
+    // Conversion rate change: > X% from 7-day average
+    conversionChangeThreshold: 20, // 20% change in either direction
+    // ROAS drop: current < X% of 7-day average
+    roasDropWarning: 20, // 20% below average
+    roasDropAlert: 40, // 40% below average
+};
+// ── Detection Functions ───────────────────────────────
+function detectSpendSpike(currentHourSpend, avgHourlySpend, platform) {
+    if (avgHourlySpend === 0)
+        return null;
+    const deviation = ((currentHourSpend - avgHourlySpend) / avgHourlySpend) * 100;
+    if (deviation < THRESHOLDS.spendSpikeWarning)
+        return null;
+    const severity = deviation >= THRESHOLDS.spendSpikeCritical ? 'critical' :
+        deviation >= THRESHOLDS.spendSpikeAlert ? 'alert' : 'warning';
+    return {
+        type: 'spend_spike',
+        severity,
+        platform,
+        metric: 'hourly_spend',
+        currentValue: currentHourSpend,
+        expectedValue: avgHourlySpend,
+        deviationPercent: Math.round(deviation),
+        message: `Spend spike on ${platform}: $${(currentHourSpend / 100).toFixed(2)}/hr vs $${(avgHourlySpend / 100).toFixed(2)}/hr average (+${Math.round(deviation)}%)`,
+        timestamp: new Date().toISOString(),
+    };
+}
+function detectTrafficDrop(currentDayTraffic, avgDailyTraffic) {
+    if (avgDailyTraffic === 0)
+        return null;
+    const deviation = ((avgDailyTraffic - currentDayTraffic) / avgDailyTraffic) * 100;
+    if (deviation < THRESHOLDS.trafficDropWarning)
+        return null;
+    const severity = deviation >= THRESHOLDS.trafficDropCritical ? 'critical' :
+        deviation >= THRESHOLDS.trafficDropAlert ? 'alert' : 'warning';
+    return {
+        type: 'traffic_drop',
+        severity,
+        metric: 'daily_traffic',
+        currentValue: currentDayTraffic,
+        expectedValue: avgDailyTraffic,
+        deviationPercent: -Math.round(deviation),
+        message: `Traffic drop: ${currentDayTraffic} visitors today vs ${avgDailyTraffic} average (-${Math.round(deviation)}%)`,
+        timestamp: new Date().toISOString(),
+    };
+}
+function detectConversionChange(currentRate, avgRate) {
+    if (avgRate === 0)
+        return null;
+    const deviation = ((currentRate - avgRate) / avgRate) * 100;
+    if (Math.abs(deviation) < THRESHOLDS.conversionChangeThreshold)
+        return null;
+    return {
+        type: 'conversion_change',
+        severity: Math.abs(deviation) >= 40 ? 'alert' : 'warning',
+        metric: 'conversion_rate',
+        currentValue: currentRate,
+        expectedValue: avgRate,
+        deviationPercent: Math.round(deviation),
+        message: `Conversion rate ${deviation > 0 ? 'increase' : 'decrease'}: ${currentRate.toFixed(1)}% vs ${avgRate.toFixed(1)}% average (${deviation > 0 ? '+' : ''}${Math.round(deviation)}%)`,
+        timestamp: new Date().toISOString(),
+    };
+}
+function detectRoasDrop(currentRoas, avgRoas, platform) {
+    if (avgRoas === 0)
+        return null;
+    const deviation = ((avgRoas - currentRoas) / avgRoas) * 100;
+    if (deviation < THRESHOLDS.roasDropWarning)
+        return null;
+    return {
+        type: 'roas_drop',
+        severity: deviation >= THRESHOLDS.roasDropAlert ? 'alert' : 'warning',
+        platform,
+        metric: 'roas',
+        currentValue: currentRoas,
+        expectedValue: avgRoas,
+        deviationPercent: -Math.round(deviation),
+        message: `ROAS drop on ${platform}: ${currentRoas.toFixed(1)}x vs ${avgRoas.toFixed(1)}x average (-${Math.round(deviation)}%)`,
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Run all anomaly checks for the current period */
+export function runAnomalyDetection(metrics) {
+    const anomalies = [];
+    for (const s of metrics.spendByPlatform) {
+        const a = detectSpendSpike(s.currentHour, s.avgHourly, s.platform);
+        if (a)
+            anomalies.push(a);
+    }
+    const td = detectTrafficDrop(metrics.traffic.currentDay, metrics.traffic.avgDaily);
+    if (td)
+        anomalies.push(td);
+    const cc = detectConversionChange(metrics.conversion.currentRate, metrics.conversion.avgRate);
+    if (cc)
+        anomalies.push(cc);
+    for (const r of metrics.roasByPlatform) {
+        const a = detectRoasDrop(r.current, r.avg, r.platform);
+        if (a)
+            anomalies.push(a);
+    }
+    return anomalies;
+}
+export { THRESHOLDS };

package/dist/wizard/lib/asset-scanner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PRD asset scanner — identifies image/visual requirements from PRD prose.
+ * Used by Celebrimbor's /imagine command to find what needs generating.
+ * Pure text analysis — no API calls, no side effects.
+ */
+export interface AssetRequirement {
+    description: string;
+    category: string;
+    context: string;
+    width: number;
+    height: number;
+    section: string;
+}
+/**
+ * Scan a PRD document for visual asset requirements.
+ * Returns a list of assets that need generating.
+ */
+export declare function scanPrdForAssets(prdContent: string): AssetRequirement[];
+/**
+ * Extract brand/style keywords from the PRD for style prefix generation.
+ * Looks for Section 14 (Brand) or any section mentioning "brand", "style", "aesthetic".
+ */
+export declare function extractBrandStyle(prdContent: string): string[];

package/dist/wizard/lib/asset-scanner.js

@@ -0,0 +1,107 @@
+/**
+ * PRD asset scanner — identifies image/visual requirements from PRD prose.
+ * Used by Celebrimbor's /imagine command to find what needs generating.
+ * Pure text analysis — no API calls, no side effects.
+ */
+/** Patterns that indicate a visual asset requirement in PRD prose. */
+const ASSET_PATTERNS = [
+    { pattern: /illustrat(?:ion|ed|e)/i, category: 'illustration' },
+    { pattern: /portrait/i, category: 'portrait' },
+    { pattern: /silhouette/i, category: 'portrait' },
+    { pattern: /avatar/i, category: 'portrait' },
+    { pattern: /(?:custom\s+)?\bicon\b/i, category: 'icon' },
+    { pattern: /og[:\s-]image/i, category: 'og-image' },
+    { pattern: /social\s+(?:sharing\s+)?image/i, category: 'og-image' },
+    { pattern: /hero\s+(?:image|banner|art)/i, category: 'hero' },
+    { pattern: /splash\s+(?:page|screen)/i, category: 'hero' },
+    { pattern: /background\s+image/i, category: 'background' },
+    { pattern: /cover\s+image/i, category: 'background' },
+    { pattern: /\blogo\b/i, category: 'logo' },
+    { pattern: /\bfavicon\b/i, category: 'icon' },
+    { pattern: /comic\s+strip/i, category: 'illustration' },
+    { pattern: /comic\s+panel/i, category: 'illustration' },
+    { pattern: /screenshot/i, category: 'screenshot' },
+    { pattern: /mockup/i, category: 'screenshot' },
+];
+/** Default dimensions per asset category. */
+const CATEGORY_DIMENSIONS = {
+    'portrait': { width: 1024, height: 1024 },
+    'illustration': { width: 1024, height: 1024 },
+    'og-image': { width: 1200, height: 630 },
+    'hero': { width: 1792, height: 1024 },
+    'background': { width: 1792, height: 1024 },
+    'logo': { width: 512, height: 512 },
+    'icon': { width: 512, height: 512 },
+    'screenshot': { width: 1280, height: 720 },
+};
+/**
+ * Scan a PRD document for visual asset requirements.
+ * Returns a list of assets that need generating.
+ */
+export function scanPrdForAssets(prdContent) {
+    const assets = [];
+    const lines = prdContent.split('\n');
+    let currentSection = '';
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Track section headers
+        const headerMatch = line.match(/^#{1,4}\s+(.+)/);
+        if (headerMatch) {
+            currentSection = headerMatch[1].trim();
+            continue;
+        }
+        // Check each line against asset patterns
+        for (const { pattern, category } of ASSET_PATTERNS) {
+            if (pattern.test(line)) {
+                // Extract surrounding context (current line + next line for description)
+                const contextLines = lines.slice(Math.max(0, i - 1), Math.min(lines.length, i + 3));
+                const context = contextLines.join(' ').trim();
+                const dims = CATEGORY_DIMENSIONS[category] || { width: 1024, height: 1024 };
+                assets.push({
+                    description: line.trim(),
+                    category,
+                    context,
+                    width: dims.width,
+                    height: dims.height,
+                    section: currentSection,
+                });
+                break; // One match per line is enough
+            }
+        }
+    }
+    // Deduplicate by description similarity
+    const seen = new Set();
+    return assets.filter(a => {
+        const key = a.description.toLowerCase().slice(0, 60);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Extract brand/style keywords from the PRD for style prefix generation.
+ * Looks for Section 14 (Brand) or any section mentioning "brand", "style", "aesthetic".
+ */
+export function extractBrandStyle(prdContent) {
+    const keywords = [];
+    const lines = prdContent.split('\n');
+    let inBrandSection = false;
+    for (const line of lines) {
+        const headerMatch = line.match(/^#{1,4}\s+(.+)/);
+        if (headerMatch) {
+            const title = headerMatch[1].toLowerCase();
+            inBrandSection = title.includes('brand') || title.includes('style') || title.includes('aesthetic') || title.includes('design') || title.includes('personality');
+            continue;
+        }
+        if (inBrandSection && line.trim()) {
+            // Extract adjectives and style keywords
+            const styleWords = line.match(/\b(minimal|bold|playful|professional|elegant|modern|retro|vintage|comic|pulp|neon|dark|light|cinematic|warm|cool|vibrant|muted|halftone|watercolor|photorealistic|illustration|flat|gradient|geometric|organic)\b/gi);
+            if (styleWords) {
+                keywords.push(...styleWords.map(w => w.toLowerCase()));
+            }
+        }
+    }
+    // Deduplicate
+    return [...new Set(keywords)];
+}

package/dist/wizard/lib/build-analytics.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Build analytics — tracks metrics across projects for trend analysis.
+ * Stored at ~/.voidforge/analytics.json. No external dependencies.
+ *
+ * Wong guards the knowledge. The Sanctum grows.
+ */
+export interface PhaseMetric {
+    phase: string;
+    findingsCount: number;
+    fixesApplied: number;
+    /** Duration in seconds (optional — only if measurable) */
+    durationSeconds?: number;
+}
+export interface BuildRecord {
+    projectName: string;
+    framework: string;
+    database: string;
+    deployTarget: string;
+    timestamp: string;
+    version: string;
+    phases: PhaseMetric[];
+    totalFindings: number;
+    totalFixes: number;
+    testCount?: number;
+    lessonsExtracted: number;
+}
+export interface AnalyticsStore {
+    builds: BuildRecord[];
+}
+/** Record a completed build. */
+export declare function recordBuild(record: BuildRecord): Promise<void>;
+/** Surface trends across past builds. Returns human-readable insights. */
+export declare function surfaceTrends(currentFramework?: string): Promise<string[]>;
+/** Get a summary of all recorded builds. */
+export declare function getBuildHistory(): Promise<{
+    count: number;
+    frameworks: string[];
+    latestBuild: string | null;
+}>;

package/dist/wizard/lib/build-analytics.js

@@ -0,0 +1,91 @@
+/**
+ * Build analytics — tracks metrics across projects for trend analysis.
+ * Stored at ~/.voidforge/analytics.json. No external dependencies.
+ *
+ * Wong guards the knowledge. The Sanctum grows.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const ANALYTICS_DIR = join(homedir(), '.voidforge');
+const ANALYTICS_FILE = join(ANALYTICS_DIR, 'analytics.json');
+async function ensureDir() {
+    try {
+        await mkdir(ANALYTICS_DIR, { recursive: true });
+    }
+    catch { /* exists */ }
+}
+async function loadStore() {
+    try {
+        const raw = await readFile(ANALYTICS_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { builds: [] };
+    }
+}
+async function saveStore(store) {
+    await ensureDir();
+    await writeFile(ANALYTICS_FILE, JSON.stringify(store, null, 2), 'utf-8');
+}
+/** Record a completed build. */
+export async function recordBuild(record) {
+    const store = await loadStore();
+    store.builds.push(record);
+    // Keep last 100 builds to prevent unbounded growth
+    if (store.builds.length > 100) {
+        store.builds = store.builds.slice(-100);
+    }
+    await saveStore(store);
+}
+/** Surface trends across past builds. Returns human-readable insights. */
+export async function surfaceTrends(currentFramework) {
+    const store = await loadStore();
+    const builds = store.builds;
+    if (builds.length < 2)
+        return [];
+    const insights = [];
+    // Finding hotspots — which phases consistently produce the most findings?
+    const phaseFindings = {};
+    for (const build of builds) {
+        for (const phase of build.phases) {
+            if (!phaseFindings[phase.phase])
+                phaseFindings[phase.phase] = [];
+            phaseFindings[phase.phase].push(phase.findingsCount);
+        }
+    }
+    for (const [phase, counts] of Object.entries(phaseFindings)) {
+        const avg = counts.reduce((a, b) => a + b, 0) / counts.length;
+        if (avg > 5 && counts.length >= 2) {
+            insights.push(`Phase "${phase}" averages ${avg.toFixed(1)} findings across ${counts.length} builds — consider proactive checks in earlier phases.`);
+        }
+    }
+    // Framework-specific patterns
+    if (currentFramework) {
+        const frameworkBuilds = builds.filter(b => b.framework === currentFramework);
+        if (frameworkBuilds.length >= 2) {
+            const avgFindings = frameworkBuilds.reduce((a, b) => a + b.totalFindings, 0) / frameworkBuilds.length;
+            insights.push(`Your ${currentFramework} projects average ${avgFindings.toFixed(0)} findings per build (${frameworkBuilds.length} builds).`);
+        }
+    }
+    // Fix-to-finding ratio trend
+    const ratios = builds.map(b => b.totalFindings > 0 ? b.totalFixes / b.totalFindings : 1);
+    const recentRatios = ratios.slice(-5);
+    const avgRatio = recentRatios.reduce((a, b) => a + b, 0) / recentRatios.length;
+    if (avgRatio < 0.8) {
+        insights.push(`Fix-to-finding ratio is ${(avgRatio * 100).toFixed(0)}% — some findings are being deferred. Consider addressing all findings in each build.`);
+    }
+    // Lessons trend
+    const totalLessons = builds.reduce((a, b) => a + b.lessonsExtracted, 0);
+    if (totalLessons > 0) {
+        insights.push(`${totalLessons} lessons extracted across ${builds.length} builds. The forge is learning.`);
+    }
+    return insights;
+}
+/** Get a summary of all recorded builds. */
+export async function getBuildHistory() {
+    const store = await loadStore();
+    const frameworks = [...new Set(store.builds.map(b => b.framework))];
+    const latest = store.builds.length > 0 ? store.builds[store.builds.length - 1].timestamp : null;
+    return { count: store.builds.length, frameworks, latestBuild: latest };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Database ERD generation from Prisma schema (ADR-025).
+ * Parses prisma/schema.prisma and produces a Mermaid entity-relationship diagram.
+ * Conditional — only runs if prisma/schema.prisma exists.
+ */
+import type { ProvisionEmitter } from '../provisioners/types.js';
+export interface ERDResult {
+    success: boolean;
+    file: string;
+    modelCount: number;
+    error?: string;
+}
+/**
+ * Generate a Mermaid ERD from the Prisma schema.
+ */
+export declare function generateERD(projectDir: string, emit: ProvisionEmitter): Promise<ERDResult>;

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

@@ -0,0 +1,98 @@
+/**
+ * Database ERD generation from Prisma schema (ADR-025).
+ * Parses prisma/schema.prisma and produces a Mermaid entity-relationship diagram.
+ * 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';
+/**
+ * Minimal Prisma schema parser — extracts model names and fields.
+ * Not a full parser — handles the common cases for ERD generation.
+ */
+function parsePrismaSchema(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 = [];
+        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 isArray = !!fieldMatch[3];
+                const isOptional = !!fieldMatch[4];
+                // Skip Prisma directives like @id, @default, etc. — those are on the same line
+                const builtinTypes = ['String', 'Int', 'Float', 'Boolean', 'DateTime', 'Json', 'BigInt', 'Decimal', 'Bytes'];
+                const isRelation = !builtinTypes.includes(fieldType);
+                fields.push({ name: fieldName, type: fieldType, isRelation, isOptional, isArray });
+            }
+        }
+        models.push({ name, fields });
+    }
+    return models;
+}
+function generateMermaidERD(models) {
+    const lines = [
+        '```mermaid',
+        'erDiagram',
+    ];
+    // Generate entity definitions
+    for (const model of models) {
+        lines.push(`    ${model.name} {`);
+        for (const field of model.fields) {
+            if (!field.isRelation) {
+                const optional = field.isOptional ? '?' : '';
+                lines.push(`        ${field.type}${optional} ${field.name}`);
+            }
+        }
+        lines.push('    }');
+    }
+    // Generate relationships
+    for (const model of models) {
+        for (const field of model.fields) {
+            if (field.isRelation) {
+                const cardinality = field.isArray ? '}o--||' : '}o--o|';
+                lines.push(`    ${model.name} ${cardinality} ${field.type} : "${field.name}"`);
+            }
+        }
+    }
+    lines.push('```');
+    return lines.join('\n');
+}
+/**
+ * Generate a Mermaid ERD from the Prisma schema.
+ */
+export async function generateERD(projectDir, emit) {
+    const schemaPath = join(projectDir, 'prisma', 'schema.prisma');
+    if (!existsSync(schemaPath)) {
+        emit({ step: 'erd', status: 'skipped', message: 'No prisma/schema.prisma found — ERD generation skipped' });
+        return { success: true, file: '', modelCount: 0 };
+    }
+    emit({ step: 'erd', status: 'started', message: 'Generating database ERD from Prisma schema' });
+    try {
+        const schema = await readFile(schemaPath, 'utf-8');
+        const models = parsePrismaSchema(schema);
+        if (models.length === 0) {
+            emit({ step: 'erd', status: 'skipped', message: 'No models found in Prisma schema' });
+            return { success: true, file: '', modelCount: 0 };
+        }
+        const mermaid = generateMermaidERD(models);
+        const content = `# Database Schema\n\nAuto-generated from \`prisma/schema.prisma\` by VoidForge (ADR-025).\n\n${mermaid}\n`;
+        const docsDir = join(projectDir, 'docs');
+        await mkdir(docsDir, { recursive: true });
+        await writeFile(join(docsDir, 'schema.md'), content, 'utf-8');
+        emit({ step: 'erd', status: 'done', message: `Generated docs/schema.md — ${models.length} models mapped` });
+        return { success: true, file: 'docs/schema.md', modelCount: models.length };
+    }
+    catch (err) {
+        emit({ step: 'erd', status: 'error', message: 'Failed to generate ERD', detail: err.message });
+        return { success: false, file: '', modelCount: 0, error: err.message };
+    }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * OpenAPI/Swagger spec generation (ADR-025).
+ * Generates a starter OpenAPI spec from framework conventions.
+ * Framework-aware: Express, Next.js API routes.
+ */
+import type { ProvisionEmitter } from '../provisioners/types.js';
+export interface OpenAPIResult {
+    success: boolean;
+    file: string;
+    error?: string;
+}
+/**
+ * Generate an OpenAPI spec file for the project.
+ */
+export declare function generateOpenAPIDoc(projectDir: string, projectName: string, framework: string, emit: ProvisionEmitter): Promise<OpenAPIResult>;