thevoidforge 21.0.0

package/dist/wizard/lib/claude-merge.js

@@ -0,0 +1,115 @@
+/**
+ * CLAUDE.md Merge Utility — Safe append of project directives.
+ *
+ * Merges project-specific directives into VoidForge's CLAUDE.md by
+ * appending them under a clearly marked section. Never replaces the
+ * methodology content. Idempotent — won't duplicate if run multiple times.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+// ── Constants ───────────────────────────────────────
+const MERGE_MARKER = '# PROJECT-SPECIFIC DIRECTIVES';
+// ── Merge Function ──────────────────────────────────
+/**
+ * Append project directives to CLAUDE.md.
+ *
+ * Rules:
+ * - VoidForge's CLAUDE.md content is NEVER replaced
+ * - Project directives are appended under a clear marker section
+ * - Idempotent: if the marker already exists, the merge is skipped
+ * - The source directive file path is recorded in the merged section
+ *
+ * @param projectRoot - The project's root directory
+ * @param directivesRelativePath - Relative path to the directives file (e.g., 'docs/PROJECT-DIRECTIVES.md')
+ * @returns MergeResult describing what happened
+ */
+export async function mergeProjectDirectives(projectRoot, directivesRelativePath) {
+    const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+    const directivesPath = join(projectRoot, directivesRelativePath);
+    // Validate both files exist
+    if (!existsSync(claudeMdPath)) {
+        return {
+            merged: false,
+            reason: 'CLAUDE.md not found in project root',
+            claudeMdPath,
+            directivesPath: directivesRelativePath,
+        };
+    }
+    if (!existsSync(directivesPath)) {
+        return {
+            merged: false,
+            reason: `Directives file not found: ${directivesRelativePath}`,
+            claudeMdPath,
+            directivesPath: directivesRelativePath,
+        };
+    }
+    // Read both files
+    const claudeMdContent = await readFile(claudeMdPath, 'utf-8');
+    const directivesContent = await readFile(directivesPath, 'utf-8');
+    // Idempotency check: already merged?
+    if (claudeMdContent.includes(MERGE_MARKER)) {
+        return {
+            merged: false,
+            reason: 'Project directives already merged (marker found)',
+            claudeMdPath,
+            directivesPath: directivesRelativePath,
+        };
+    }
+    // Validate directives content is non-empty
+    if (directivesContent.trim().length === 0) {
+        return {
+            merged: false,
+            reason: 'Directives file is empty',
+            claudeMdPath,
+            directivesPath: directivesRelativePath,
+        };
+    }
+    // Merge: append directives under the marker
+    const merged = `${claudeMdContent.trimEnd()}
+
+---
+
+${MERGE_MARKER}
+
+_Loaded from \`${directivesRelativePath}\` by /blueprint_
+
+${directivesContent.trimEnd()}
+`;
+    await writeFile(claudeMdPath, merged, 'utf-8');
+    return {
+        merged: true,
+        reason: `Project directives appended from ${directivesRelativePath}`,
+        claudeMdPath,
+        directivesPath: directivesRelativePath,
+    };
+}
+/**
+ * Check if project directives have already been merged into CLAUDE.md.
+ */
+export async function isAlreadyMerged(projectRoot) {
+    const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+    if (!existsSync(claudeMdPath))
+        return false;
+    const content = await readFile(claudeMdPath, 'utf-8');
+    return content.includes(MERGE_MARKER);
+}
+/**
+ * Remove previously merged project directives from CLAUDE.md.
+ * Useful for re-merging with updated directives.
+ */
+export async function unmergeProjectDirectives(projectRoot) {
+    const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+    if (!existsSync(claudeMdPath))
+        return false;
+    const content = await readFile(claudeMdPath, 'utf-8');
+    const markerIndex = content.indexOf(`\n---\n\n${MERGE_MARKER}`);
+    if (markerIndex === -1)
+        return false;
+    // Remove everything from the marker onwards
+    const cleaned = content.slice(0, markerIndex).trimEnd() + '\n';
+    await writeFile(claudeMdPath, cleaned, 'utf-8');
+    return true;
+}

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/integrations.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Integration templates — pre-built client wrappers (ADR-025).
+ * Selected via PRD frontmatter (payments: stripe, email: resend).
+ * Framework-aware: generates TypeScript or Python.
+ */
+import type { ProvisionEmitter } from '../provisioners/types.js';
+export interface IntegrationResult {
+    generated: {
+        key: string;
+        file: string;
+        pkg: string;
+    }[];
+    skipped: string[];
+}
+/**
+ * Generate integration templates based on PRD frontmatter flags.
+ */
+export declare function generateIntegrations(projectDir: string, frontmatter: Record<string, string | undefined>, emit: ProvisionEmitter): Promise<IntegrationResult>;

package/dist/wizard/lib/codegen/integrations.js

@@ -0,0 +1,189 @@
+/**
+ * Integration templates — pre-built client wrappers (ADR-025).
+ * Selected via PRD frontmatter (payments: stripe, email: resend).
+ * Framework-aware: generates TypeScript or Python.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+// ── Stripe ──────────────────────────────────────────────
+const STRIPE_TS = `// Stripe integration — generated by VoidForge (ADR-025)
+// Install: npm install stripe
+// Set STRIPE_SECRET_KEY in .env
+
+import Stripe from 'stripe';
+
+if (!process.env.STRIPE_SECRET_KEY) {
+  throw new Error('STRIPE_SECRET_KEY is required');
+}
+
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
+  apiVersion: '2024-12-18.acacia',
+});
+
+/** Create a checkout session for a price. */
+export async function createCheckoutSession(priceId: string, successUrl: string, cancelUrl: string) {
+  return stripe.checkout.sessions.create({
+    mode: 'subscription',
+    payment_method_types: ['card'],
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: successUrl,
+    cancel_url: cancelUrl,
+  });
+}
+
+/** Create a customer portal session. */
+export async function createPortalSession(customerId: string, returnUrl: string) {
+  return stripe.billingPortal.sessions.create({
+    customer: customerId,
+    return_url: returnUrl,
+  });
+}
+
+/** Verify a webhook signature. */
+export function verifyWebhook(payload: string | Buffer, signature: string, secret: string): Stripe.Event {
+  return stripe.webhooks.constructEvent(payload, signature, secret);
+}
+`;
+// ── Resend ──────────────────────────────────────────────
+const RESEND_TS = `// Resend email integration — generated by VoidForge (ADR-025)
+// Install: npm install resend
+// Set RESEND_API_KEY in .env
+
+import { Resend } from 'resend';
+
+if (!process.env.RESEND_API_KEY) {
+  throw new Error('RESEND_API_KEY is required');
+}
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+interface SendEmailParams {
+  to: string | string[];
+  subject: string;
+  html: string;
+  from?: string;
+}
+
+/** Send a transactional email. */
+export async function sendEmail({ to, subject, html, from }: SendEmailParams) {
+  return resend.emails.send({
+    from: from || process.env.RESEND_FROM || 'noreply@example.com',
+    to: Array.isArray(to) ? to : [to],
+    subject,
+    html,
+  });
+}
+
+/** Send a welcome email. */
+export async function sendWelcomeEmail(to: string, name: string) {
+  return sendEmail({
+    to,
+    subject: 'Welcome!',
+    html: \`<h1>Welcome, \${name}!</h1><p>Thanks for signing up.</p>\`,
+  });
+}
+`;
+// ── S3 File Upload ──────────────────────────────────────
+const S3_TS = `// S3 file upload integration — generated by VoidForge (ADR-025)
+// Install: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+// Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, S3_UPLOAD_BUCKET in .env
+
+import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+if (!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY) {
+  throw new Error('AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are required');
+}
+if (!process.env.S3_UPLOAD_BUCKET) {
+  throw new Error('S3_UPLOAD_BUCKET is required');
+}
+
+const s3 = new S3Client({
+  region: process.env.AWS_REGION || 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+});
+
+const BUCKET = process.env.S3_UPLOAD_BUCKET;
+
+/** Generate a pre-signed upload URL (client uploads directly to S3). */
+export async function getUploadUrl(key: string, contentType: string, expiresIn = 3600): Promise<string> {
+  const command = new PutObjectCommand({
+    Bucket: BUCKET,
+    Key: key,
+    ContentType: contentType,
+  });
+  return getSignedUrl(s3, command, { expiresIn });
+}
+
+/** Generate a pre-signed download URL. */
+export async function getDownloadUrl(key: string, expiresIn = 3600): Promise<string> {
+  const command = new GetObjectCommand({
+    Bucket: BUCKET,
+    Key: key,
+  });
+  return getSignedUrl(s3, command, { expiresIn });
+}
+`;
+const TEMPLATES = [
+    {
+        key: 'stripe',
+        frontmatterField: 'payments',
+        frontmatterValue: 'stripe',
+        filename: 'lib/stripe.ts',
+        content: STRIPE_TS,
+        pkg: 'stripe',
+        envVars: ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'],
+    },
+    {
+        key: 'resend',
+        frontmatterField: 'email',
+        frontmatterValue: 'resend',
+        filename: 'lib/resend.ts',
+        content: RESEND_TS,
+        pkg: 'resend',
+        envVars: ['RESEND_API_KEY', 'RESEND_FROM'],
+    },
+    {
+        key: 's3',
+        frontmatterField: 'storage',
+        frontmatterValue: 's3',
+        filename: 'lib/s3-upload.ts',
+        content: S3_TS,
+        pkg: '@aws-sdk/client-s3 @aws-sdk/s3-request-presigner',
+        envVars: ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION', 'S3_UPLOAD_BUCKET'],
+    },
+];
+/**
+ * Generate integration templates based on PRD frontmatter flags.
+ */
+export async function generateIntegrations(projectDir, frontmatter, emit) {
+    const generated = [];
+    const skipped = [];
+    for (const template of TEMPLATES) {
+        const value = frontmatter[template.frontmatterField];
+        if (value === template.frontmatterValue) {
+            emit({ step: `integration-${template.key}`, status: 'started', message: `Generating ${template.key} integration` });
+            try {
+                const filePath = join(projectDir, template.filename);
+                const dir = join(projectDir, template.filename.split('/').slice(0, -1).join('/'));
+                await mkdir(dir, { recursive: true });
+                await writeFile(filePath, template.content, 'utf-8');
+                generated.push({ key: template.key, file: template.filename, pkg: template.pkg });
+                emit({ step: `integration-${template.key}`, status: 'done', message: `Generated ${template.filename} — install: npm install ${template.pkg}` });
+            }
+            catch (err) {
+                emit({ step: `integration-${template.key}`, status: 'error', message: `Failed to generate ${template.key}`, detail: err.message });
+            }
+        }
+        else {
+            skipped.push(template.key);
+        }
+    }
+    if (generated.length === 0) {
+        emit({ step: 'integrations', status: 'skipped', message: 'No integration templates requested in PRD frontmatter (payments: stripe, email: resend, storage: s3)' });
+    }
+    return { generated, skipped };
+}

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>;

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>;