thevoidforge 21.0.0

package/dist/wizard/lib/dns/cloudflare-dns.js

@@ -0,0 +1,216 @@
+/**
+ * Cloudflare DNS provisioning — zone lookup, record CRUD.
+ * Uses the shared HTTP client. No external dependencies.
+ */
+import { httpsGet, httpsPost, httpsDelete, safeJsonParse } from '../provisioners/http-client.js';
+import { recordResourcePending, recordResourceCreated } from '../provision-manifest.js';
+const CF_API = 'api.cloudflare.com';
+function cfHeaders(token) {
+    return {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+    };
+}
+/**
+ * Extract the root zone from a hostname.
+ * "app.voidforge.dev" → "voidforge.dev"
+ * "voidforge.dev" → "voidforge.dev"
+ */
+export function extractZoneName(hostname) {
+    const parts = hostname.replace(/\.$/, '').split('.');
+    if (parts.length <= 2)
+        return parts.join('.');
+    return parts.slice(-2).join('.');
+}
+/**
+ * Find the Cloudflare zone for a hostname.
+ * Accepts zones in any status (active, pending, etc.) — Cloudflare allows DNS
+ * record creation on pending zones, which is needed after fresh domain registration
+ * where zones start as pending until nameservers are verified (Kusanagi-5).
+ */
+export async function findZone(token, hostname) {
+    const zoneName = extractZoneName(hostname);
+    const res = await httpsGet(CF_API, `/client/v4/zones?name=${encodeURIComponent(zoneName)}`, cfHeaders(token));
+    if (res.status === 403) {
+        throw new Error('Cloudflare token lacks Zone:Read permission. Create a token with Zone:DNS:Edit at dash.cloudflare.com/profile/api-tokens');
+    }
+    if (res.status !== 200) {
+        throw new Error(`Cloudflare zones API returned ${res.status}`);
+    }
+    const data = safeJsonParse(res.body);
+    if (!data?.success || !data.result || data.result.length === 0) {
+        return null;
+    }
+    const zone = data.result[0];
+    return { id: zone.id, name: zone.name, status: zone.status };
+}
+/** List existing DNS records for a hostname. */
+export async function listRecords(token, zoneId, hostname) {
+    const res = await httpsGet(CF_API, `/client/v4/zones/${zoneId}/dns_records?name=${encodeURIComponent(hostname)}&type=A,AAAA,CNAME`, cfHeaders(token));
+    if (res.status !== 200)
+        return [];
+    const data = safeJsonParse(res.body);
+    return (data?.result ?? []).map((r) => ({
+        id: r.id,
+        type: r.type,
+        name: r.name,
+        content: r.content,
+        proxied: r.proxied,
+        ttl: r.ttl,
+    }));
+}
+/** Create a DNS record. */
+export async function createRecord(token, zoneId, type, name, content, proxied) {
+    const body = JSON.stringify({ type, name, content, proxied, ttl: 1 }); // ttl=1 = auto
+    const res = await httpsPost(CF_API, `/client/v4/zones/${zoneId}/dns_records`, cfHeaders(token), body);
+    if (res.status !== 200 && res.status !== 201) {
+        const data = safeJsonParse(res.body);
+        throw new Error(data?.errors?.[0]?.message || `DNS record creation returned ${res.status}`);
+    }
+    const data = safeJsonParse(res.body);
+    const r = data?.result;
+    if (!r)
+        throw new Error('No record returned from Cloudflare');
+    return {
+        id: r.id,
+        type: r.type,
+        name: r.name,
+        content: r.content,
+        proxied: r.proxied,
+        ttl: r.ttl,
+    };
+}
+/** Delete a DNS record. */
+export async function deleteRecord(token, zoneId, recordId) {
+    await httpsDelete(CF_API, `/client/v4/zones/${zoneId}/dns_records/${recordId}`, cfHeaders(token));
+}
+/**
+ * Determine the DNS record type and content based on deploy target outputs.
+ *
+ * VPS → A record pointing to EC2 public IP
+ * Cloudflare Pages → CNAME pointing to slug.pages.dev
+ * Static S3 → CNAME pointing to S3 website URL
+ * Vercel → CNAME pointing to cname.vercel-dns.com
+ * Railway → CNAME pointing to railway project URL
+ */
+function resolveRecordTarget(deployTarget, outputs) {
+    switch (deployTarget) {
+        case 'vps': {
+            const ip = outputs['SSH_HOST'];
+            if (!ip)
+                return null;
+            return { type: 'A', content: ip, proxied: true };
+        }
+        case 'cloudflare': {
+            const url = outputs['CF_PROJECT_URL'];
+            if (!url)
+                return null;
+            // Extract hostname from https://slug.pages.dev
+            const host = url.replace(/^https?:\/\//, '');
+            return { type: 'CNAME', content: host, proxied: true };
+        }
+        case 'static': {
+            const url = outputs['S3_WEBSITE_URL'];
+            if (!url)
+                return null;
+            const host = url.replace(/^https?:\/\//, '');
+            return { type: 'CNAME', content: host, proxied: true };
+        }
+        case 'vercel': {
+            return { type: 'CNAME', content: 'cname.vercel-dns.com', proxied: false };
+        }
+        case 'railway': {
+            // Railway custom domains need a CNAME to the project's railway.app subdomain
+            const projectName = outputs['RAILWAY_PROJECT_NAME'];
+            const content = projectName
+                ? `${projectName.toLowerCase().replace(/[^a-z0-9-]/g, '-')}.up.railway.app`
+                : 'railway.app';
+            return { type: 'CNAME', content, proxied: false };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Full DNS provisioning flow — called as a post-provision step.
+ * Non-fatal: returns success=false with error message, never throws.
+ */
+export async function provisionDns(runId, token, hostname, deployTarget, outputs, emit) {
+    const records = [];
+    let zoneId = '';
+    // Step 1: Find zone
+    emit({ step: 'dns-zone', status: 'started', message: `Looking up Cloudflare zone for ${hostname}` });
+    try {
+        const zone = await findZone(token, hostname);
+        if (!zone) {
+            emit({ step: 'dns-zone', status: 'error', message: `Zone not found for "${extractZoneName(hostname)}". Add your domain at dash.cloudflare.com first.` });
+            return { success: false, records, zoneId, error: 'Zone not found on Cloudflare' };
+        }
+        zoneId = zone.id;
+        emit({ step: 'dns-zone', status: 'done', message: `Zone found: ${zone.name} (${zone.status})` });
+    }
+    catch (err) {
+        emit({ step: 'dns-zone', status: 'error', message: 'Failed to look up DNS zone', detail: err.message });
+        return { success: false, records, zoneId, error: err.message };
+    }
+    // Step 2: Determine record target
+    const target = resolveRecordTarget(deployTarget, outputs);
+    if (!target) {
+        emit({ step: 'dns-records', status: 'error', message: `Cannot determine DNS target for deploy type "${deployTarget}". Infrastructure may still be provisioning.` });
+        return { success: false, records, zoneId, error: 'No DNS target available' };
+    }
+    // Step 3: Check for existing records
+    emit({ step: 'dns-records', status: 'started', message: `Creating ${target.type} record: ${hostname} → ${target.content}` });
+    try {
+        const existing = await listRecords(token, zoneId, hostname);
+        if (existing.length > 0) {
+            // Delete conflicting records before creating new ones
+            for (const record of existing) {
+                await deleteRecord(token, zoneId, record.id);
+            }
+            emit({ step: 'dns-cleanup', status: 'done', message: `Replaced ${existing.length} existing record(s) for ${hostname}` });
+        }
+        // Step 4: Create root record
+        await recordResourcePending(runId, 'dns-record', hostname, 'global');
+        const rootRecord = await createRecord(token, zoneId, target.type, hostname, target.content, target.proxied);
+        records.push(rootRecord);
+        await recordResourceCreated(runId, 'dns-record', `${zoneId}:${rootRecord.id}`, 'global');
+        // Step 5: Create www record (if root domain)
+        const parts = hostname.split('.');
+        if (parts.length === 2) {
+            const wwwHostname = `www.${hostname}`;
+            const existingWww = await listRecords(token, zoneId, wwwHostname);
+            for (const record of existingWww) {
+                await deleteRecord(token, zoneId, record.id);
+            }
+            await recordResourcePending(runId, 'dns-record', wwwHostname, 'global');
+            const wwwRecord = await createRecord(token, zoneId, 'CNAME', wwwHostname, hostname, target.proxied);
+            records.push(wwwRecord);
+            await recordResourceCreated(runId, 'dns-record', `${zoneId}:${wwwRecord.id}`, 'global');
+        }
+        const recordNames = records.map((r) => r.name).join(', ');
+        emit({ step: 'dns-records', status: 'done', message: `DNS configured: ${recordNames} → ${target.content}` });
+    }
+    catch (err) {
+        emit({ step: 'dns-records', status: 'error', message: 'Failed to create DNS records', detail: err.message });
+        return { success: false, records, zoneId, error: err.message };
+    }
+    return { success: true, records, zoneId };
+}
+/**
+ * Clean up DNS records created during provisioning.
+ * Resource IDs are stored as "zoneId:recordId".
+ */
+export async function cleanupDnsRecords(token, resourceIds) {
+    for (const resourceId of resourceIds) {
+        const [zoneId, recordId] = resourceId.split(':');
+        if (zoneId && recordId) {
+            try {
+                await deleteRecord(token, zoneId, recordId);
+            }
+            catch (err) {
+                console.error(`Failed to cleanup DNS record ${recordId}:`, err.message);
+            }
+        }
+    }
+}

package/dist/wizard/lib/dns/cloudflare-registrar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cloudflare Registrar — domain availability check and registration.
+ * Uses the shared HTTP client. No external dependencies.
+ */
+import type { ProvisionEmitter } from '../provisioners/types.js';
+export interface DomainCheckResult {
+    available: boolean;
+    premium: boolean;
+    price?: number;
+    currency?: string;
+    canRegister: boolean;
+    error?: string;
+}
+export interface DomainRegistrationResult {
+    success: boolean;
+    domain?: string;
+    expiresAt?: string;
+    autoRenew?: boolean;
+    error?: string;
+}
+/**
+ * Check domain availability via Cloudflare Registrar API.
+ * Returns availability status and price if registrable.
+ */
+export declare function checkDomainAvailability(token: string, accountId: string, domain: string): Promise<DomainCheckResult>;
+/**
+ * Register a domain via Cloudflare Registrar.
+ * Auto-renew is enabled by default.
+ * This is IRREVERSIBLE — domains cannot be deleted via API.
+ */
+export declare function registerDomain(token: string, accountId: string, domain: string, emit: ProvisionEmitter): Promise<DomainRegistrationResult>;

package/dist/wizard/lib/dns/cloudflare-registrar.js

@@ -0,0 +1,148 @@
+/**
+ * Cloudflare Registrar — domain availability check and registration.
+ * Uses the shared HTTP client. No external dependencies.
+ */
+import { httpsGet, httpsPost, safeJsonParse } from '../provisioners/http-client.js';
+const CF_API = 'api.cloudflare.com';
+/** Cloudflare account IDs are 32-character hex strings */
+const ACCOUNT_ID_RE = /^[a-f0-9]{32}$/i;
+/** Valid domain format: labels separated by dots, each 1-63 chars of alphanumeric/hyphens */
+const DOMAIN_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+function cfHeaders(token) {
+    return {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+    };
+}
+/**
+ * Check domain availability via Cloudflare Registrar API.
+ * Returns availability status and price if registrable.
+ */
+export async function checkDomainAvailability(token, accountId, domain) {
+    if (!ACCOUNT_ID_RE.test(accountId)) {
+        return { available: false, premium: false, canRegister: false, error: 'Invalid Cloudflare account ID format (expected 32-char hex)' };
+    }
+    if (!DOMAIN_RE.test(domain)) {
+        return { available: false, premium: false, canRegister: false, error: 'Invalid domain format' };
+    }
+    const res = await httpsGet(CF_API, `/client/v4/accounts/${encodeURIComponent(accountId)}/registrar/domains?query=${encodeURIComponent(domain)}`, cfHeaders(token));
+    if (res.status === 403) {
+        return { available: false, premium: false, canRegister: false, error: 'Token lacks Registrar:Read permission' };
+    }
+    if (res.status !== 200) {
+        return { available: false, premium: false, canRegister: false, error: `Registrar API returned ${res.status}` };
+    }
+    const data = safeJsonParse(res.body);
+    if (!data?.success || !data.result || data.result.length === 0) {
+        // If no results, try the domain status endpoint directly
+        const statusRes = await httpsGet(CF_API, `/client/v4/accounts/${encodeURIComponent(accountId)}/registrar/domains/${encodeURIComponent(domain)}`, cfHeaders(token));
+        if (statusRes.status === 404) {
+            // Domain not registered with this account — may be available.
+            // This is a best-guess: 404 means "not on THIS account", not "globally available."
+            // canRegister: true is a "proceed to try" signal — the registration API will
+            // correctly reject if the domain isn't actually available.
+            return { available: true, premium: false, canRegister: true, error: 'Domain not found on this account — availability is unconfirmed until registration is attempted' };
+        }
+        if (statusRes.status === 200) {
+            // Domain already registered with this account
+            return { available: false, premium: false, canRegister: false, error: 'Domain already registered on this account' };
+        }
+        return { available: false, premium: false, canRegister: false, error: data?.errors?.[0]?.message || 'Could not check availability' };
+    }
+    const result = data.result[0];
+    const price = result.pricing?.registration?.price;
+    const currency = result.pricing?.registration?.currency;
+    return {
+        available: result.available ?? false,
+        premium: result.premium ?? false,
+        price,
+        currency,
+        canRegister: (result.available ?? false) && !(result.premium ?? false),
+    };
+}
+/**
+ * Register a domain via Cloudflare Registrar.
+ * Auto-renew is enabled by default.
+ * This is IRREVERSIBLE — domains cannot be deleted via API.
+ */
+export async function registerDomain(token, accountId, domain, emit) {
+    if (!ACCOUNT_ID_RE.test(accountId)) {
+        return { success: false, error: 'Invalid Cloudflare account ID format (expected 32-char hex)' };
+    }
+    if (!DOMAIN_RE.test(domain)) {
+        return { success: false, error: 'Invalid domain format' };
+    }
+    // Step 1: Check availability
+    emit({ step: 'registrar-check', status: 'started', message: `Checking availability of ${domain}` });
+    const check = await checkDomainAvailability(token, accountId, domain);
+    if (!check.canRegister) {
+        const reason = check.error || (check.premium ? 'Premium domain — manual registration required' : 'Domain is not available');
+        emit({ step: 'registrar-check', status: 'error', message: reason });
+        return { success: false, error: reason };
+    }
+    const priceDisplay = check.price ? ` ($${(check.price / 100).toFixed(2)} ${check.currency || 'USD'}/year)` : '';
+    emit({ step: 'registrar-check', status: 'done', message: `${domain} is available${priceDisplay}` });
+    // Step 2: Register the domain
+    emit({ step: 'registrar-register', status: 'started', message: `Registering ${domain}...` });
+    const body = JSON.stringify({
+        name: domain,
+        auto_renew: true,
+    });
+    // Use a longer timeout (60s) for domain registration — this is an irreversible
+    // financial transaction. A 30-second timeout could mask a successful purchase.
+    let res;
+    try {
+        res = await httpsPost(CF_API, `/client/v4/accounts/${encodeURIComponent(accountId)}/registrar/domains/${encodeURIComponent(domain)}/register`, cfHeaders(token), body, 60000);
+    }
+    catch (regError) {
+        // Registration call failed (timeout, network error, etc.).
+        // Verify whether the domain was actually purchased before reporting failure.
+        emit({ step: 'registrar-register', status: 'started', message: 'Registration request failed — verifying whether domain was purchased...' });
+        const verifyCheck = await checkDomainAvailability(token, accountId, domain);
+        if (!verifyCheck.available) {
+            // Domain is no longer available — the purchase likely went through
+            emit({ step: 'registrar-register', status: 'done', message: `Domain ${domain} registered (confirmed after transient error) — auto-renew enabled` });
+            return { success: true, domain, autoRenew: true };
+        }
+        // Domain is still available — the purchase genuinely failed
+        const errMsg = `Registration failed: ${regError.message}`;
+        emit({ step: 'registrar-register', status: 'error', message: errMsg });
+        return { success: false, error: errMsg };
+    }
+    if (res.status === 403) {
+        const errMsg = 'Token lacks Registrar:Edit permission — update your Cloudflare API token';
+        emit({ step: 'registrar-register', status: 'error', message: errMsg });
+        return { success: false, error: errMsg };
+    }
+    if (res.status !== 200 && res.status !== 201) {
+        // Non-success status — verify whether the domain was actually purchased despite the error
+        const verifyCheck = await checkDomainAvailability(token, accountId, domain);
+        if (!verifyCheck.available) {
+            emit({ step: 'registrar-register', status: 'done', message: `Domain ${domain} registered (confirmed after API error) — auto-renew enabled` });
+            return { success: true, domain, autoRenew: true };
+        }
+        const data = safeJsonParse(res.body);
+        const errMsg = data?.errors?.[0]?.message || `Registration returned ${res.status}`;
+        emit({ step: 'registrar-register', status: 'error', message: `Registration failed: ${errMsg}` });
+        return { success: false, error: errMsg };
+    }
+    const data = safeJsonParse(res.body);
+    if (!data?.success) {
+        const errMsg = data?.errors?.[0]?.message || 'Registration failed';
+        emit({ step: 'registrar-register', status: 'error', message: errMsg });
+        return { success: false, error: errMsg };
+    }
+    const registered = data.result;
+    emit({
+        step: 'registrar-register',
+        status: 'done',
+        message: `Domain ${domain} registered — auto-renew enabled`,
+        detail: registered?.expires_at ? `Expires: ${registered.expires_at}` : undefined,
+    });
+    return {
+        success: true,
+        domain: registered?.domain_name || domain,
+        expiresAt: registered?.expires_at,
+        autoRenew: registered?.auto_renew ?? true,
+    };
+}

package/dist/wizard/lib/dns/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DNS provisioning types — shared across DNS providers.
+ */
+export interface DnsRecord {
+    id: string;
+    type: 'A' | 'AAAA' | 'CNAME';
+    name: string;
+    content: string;
+    proxied: boolean;
+    ttl: number;
+}
+export interface ZoneInfo {
+    id: string;
+    name: string;
+    status: string;
+}
+export interface DnsProvisionResult {
+    success: boolean;
+    records: DnsRecord[];
+    zoneId: string;
+    error?: string;
+}

package/dist/wizard/lib/dns/types.js

@@ -0,0 +1,4 @@
+/**
+ * DNS provisioning types — shared across DNS providers.
+ */
+export {};

package/dist/wizard/lib/document-discovery.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Document Discovery — Wong's supporting document scanner.
+ *
+ * Discovers and catalogs all supporting documents in a project directory
+ * following the Blueprint Path convention. Used by /blueprint, /campaign,
+ * and /build to load context beyond the PRD.
+ *
+ * Convention:
+ *   docs/PRD.md                     — Required. Product specification.
+ *   docs/PROJECT-DIRECTIVES.md      — Optional. Appended to CLAUDE.md.
+ *   docs/OPERATIONS.md              — Optional. Business context for Sisko.
+ *   docs/ADR/*.md                   — Optional. Architecture decisions for Picard.
+ *   docs/reference/*                — Optional. Available to all agents.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+export interface DiscoveredDocuments {
+    prd: string | null;
+    projectDirectives: string | null;
+    operations: string | null;
+    adrs: string[];
+    references: string[];
+    total: number;
+}
+/**
+ * Discover all supporting documents in the project directory.
+ * Returns a catalog of found files with their paths and total count.
+ */
+export declare function discoverDocuments(projectRoot: string): Promise<DiscoveredDocuments>;
+/**
+ * Produce a human-readable summary of discovered documents.
+ */
+export declare function summarizeDiscovery(docs: DiscoveredDocuments): string;

package/dist/wizard/lib/document-discovery.js

@@ -0,0 +1,145 @@
+/**
+ * Document Discovery — Wong's supporting document scanner.
+ *
+ * Discovers and catalogs all supporting documents in a project directory
+ * following the Blueprint Path convention. Used by /blueprint, /campaign,
+ * and /build to load context beyond the PRD.
+ *
+ * Convention:
+ *   docs/PRD.md                     — Required. Product specification.
+ *   docs/PROJECT-DIRECTIVES.md      — Optional. Appended to CLAUDE.md.
+ *   docs/OPERATIONS.md              — Optional. Business context for Sisko.
+ *   docs/ADR/*.md                   — Optional. Architecture decisions for Picard.
+ *   docs/reference/*                — Optional. Available to all agents.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+import { existsSync } from 'node:fs';
+import { readdir, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+const MAX_WALK_DEPTH = 10;
+const MAX_WALK_FILES = 1000;
+// ── Directive file search paths (checked in order) ──
+const DIRECTIVE_PATHS = [
+    'docs/PROJECT-DIRECTIVES.md',
+    'docs/PROJECT-CLAUDE.md',
+    'docs/DIRECTIVES.md',
+    'PROJECT-CLAUDE.md',
+    'PROJECT-DIRECTIVES.md',
+];
+// ── Discovery ───────────────────────────────────────
+/**
+ * Discover all supporting documents in the project directory.
+ * Returns a catalog of found files with their paths and total count.
+ */
+export async function discoverDocuments(projectRoot) {
+    const result = {
+        prd: null,
+        projectDirectives: null,
+        operations: null,
+        adrs: [],
+        references: [],
+        total: 0,
+    };
+    // PRD (required for /blueprint, optional for other commands)
+    const prdPath = join(projectRoot, 'docs/PRD.md');
+    if (existsSync(prdPath)) {
+        result.prd = 'docs/PRD.md';
+        result.total++;
+    }
+    // Project-specific directives (checked in priority order)
+    for (const relativePath of DIRECTIVE_PATHS) {
+        const fullPath = join(projectRoot, relativePath);
+        if (existsSync(fullPath)) {
+            result.projectDirectives = relativePath;
+            result.total++;
+            break;
+        }
+    }
+    // Operations playbook
+    const opsPath = join(projectRoot, 'docs/OPERATIONS.md');
+    if (existsSync(opsPath)) {
+        result.operations = 'docs/OPERATIONS.md';
+        result.total++;
+    }
+    // Architecture Decision Records
+    const adrDir = join(projectRoot, 'docs/ADR');
+    if (existsSync(adrDir)) {
+        try {
+            const files = await readdir(adrDir);
+            result.adrs = files
+                .filter(f => f.endsWith('.md'))
+                .sort()
+                .map(f => `docs/ADR/${f}`);
+            result.total += result.adrs.length;
+        }
+        catch { /* directory unreadable */ }
+    }
+    // Also check docs/adrs/ (lowercase variant)
+    const adrsDir = join(projectRoot, 'docs/adrs');
+    if (existsSync(adrsDir) && result.adrs.length === 0) {
+        try {
+            const files = await readdir(adrsDir);
+            result.adrs = files
+                .filter(f => f.endsWith('.md'))
+                .sort()
+                .map(f => `docs/adrs/${f}`);
+            result.total += result.adrs.length;
+        }
+        catch { /* directory unreadable */ }
+    }
+    // Reference materials (recursive scan, all file types)
+    const refDir = join(projectRoot, 'docs/reference');
+    if (existsSync(refDir)) {
+        try {
+            result.references = await walkDirectory(refDir, 'docs/reference');
+            result.total += result.references.length;
+        }
+        catch { /* directory unreadable */ }
+    }
+    return result;
+}
+/**
+ * Recursively walk a directory and return all file paths relative to the project root.
+ */
+async function walkDirectory(dirPath, relativeTo, depth = 0, fileCount = { count: 0 }) {
+    if (depth > MAX_WALK_DEPTH || fileCount.count > MAX_WALK_FILES)
+        return [];
+    const entries = await readdir(dirPath);
+    const files = [];
+    for (const entry of entries) {
+        if (fileCount.count > MAX_WALK_FILES)
+            break;
+        const fullPath = join(dirPath, entry);
+        const entryStat = await lstat(fullPath); // lstat: don't follow symlinks
+        if (entryStat.isSymbolicLink())
+            continue; // Skip symlinks — prevent escape
+        if (entryStat.isDirectory()) {
+            const subFiles = await walkDirectory(fullPath, `${relativeTo}/${entry}`, depth + 1, fileCount);
+            files.push(...subFiles);
+        }
+        else {
+            files.push(`${relativeTo}/${entry}`);
+            fileCount.count++;
+        }
+    }
+    return files.sort();
+}
+/**
+ * Produce a human-readable summary of discovered documents.
+ */
+export function summarizeDiscovery(docs) {
+    const lines = [];
+    if (docs.prd)
+        lines.push(`  PRD: ${docs.prd}`);
+    if (docs.projectDirectives)
+        lines.push(`  Project directives: ${docs.projectDirectives}`);
+    if (docs.operations)
+        lines.push(`  Operations playbook: ${docs.operations}`);
+    if (docs.adrs.length > 0)
+        lines.push(`  ADRs: ${docs.adrs.length} architecture decision records`);
+    if (docs.references.length > 0)
+        lines.push(`  References: ${docs.references.length} supporting files`);
+    lines.push(`  Total: ${docs.total} documents discovered`);
+    return lines.join('\n');
+}

package/dist/wizard/lib/env-validator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Startup environment validation script generator (ADR-018).
+ * Generates a script that checks required env vars at boot time.
+ * No dependencies — pure Node.js stdlib or Python stdlib.
+ */
+export interface EnvValidatorResult {
+    success: boolean;
+    file: string;
+    error?: string;
+}
+/**
+ * Generate an environment validation script based on the project's .env file.
+ */
+export declare function generateEnvValidator(projectDir: string, framework: string): Promise<EnvValidatorResult>;