thevoidforge 21.0.0

package/dist/wizard/lib/marker.js

@@ -0,0 +1,79 @@
+/**
+ * .voidforge marker file — project identity and CLI detection.
+ *
+ * Every VoidForge project has a `.voidforge` JSON file at root.
+ * The CLI walks up from cwd to find it, determining the project root.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+// ── Constants ────────────────────────────────────────────
+export const MARKER_FILE = '.voidforge';
+// ── Read / Write ─────────────────────────────────────────
+export async function readMarker(dir) {
+    const markerPath = join(dir, MARKER_FILE);
+    if (!existsSync(markerPath))
+        return null;
+    try {
+        const raw = await readFile(markerPath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (!data.id || !data.version || !Array.isArray(data.extensions))
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeMarker(dir, marker) {
+    const markerPath = join(dir, MARKER_FILE);
+    await writeFile(markerPath, JSON.stringify(marker, null, 2) + '\n', 'utf-8');
+}
+export function createMarker(version, tier = 'full', extensions = []) {
+    return {
+        id: randomUUID(),
+        version,
+        created: new Date().toISOString(),
+        tier,
+        extensions,
+    };
+}
+// ── Project Detection ────────────────────────────────────
+/**
+ * Walk up from `startDir` to find the nearest `.voidforge` marker.
+ * Returns the directory containing the marker, or null if none found.
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    let current = startDir;
+    while (true) {
+        if (existsSync(join(current, MARKER_FILE))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break; // filesystem root
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Like findProjectRoot but throws with a user-friendly message.
+ */
+export function requireProjectRoot(startDir = process.cwd()) {
+    const root = findProjectRoot(startDir);
+    if (!root) {
+        console.error('Not a VoidForge project — run `npx voidforge init` to create one.');
+        process.exit(1);
+    }
+    return root;
+}
+// ── Global Config ────────────────────────────────────────
+export function getGlobalDir() {
+    const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? homedir();
+    return join(home, '.voidforge');
+}
+export function getVaultPath() {
+    return join(getGlobalDir(), 'vault.enc');
+}

package/dist/wizard/lib/migrator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Migration from v20.x — detects old-model projects (embedded wizard/)
+ * and converts them to v21.0 (standalone wizard, methodology-only projects).
+ */
+export interface MigrationPlan {
+    projectDir: string;
+    hasWizardDir: boolean;
+    wizardFileCount: number;
+    hasPackageJson: boolean;
+    voidforgeDeps: string[];
+    hasMethodology: boolean;
+    hasMarker: boolean;
+}
+export interface MigrationResult {
+    success: boolean;
+    backupDir: string;
+    wizardFilesRemoved: number;
+    depsRemoved: string[];
+    markerCreated: boolean;
+}
+/**
+ * Detect if a directory is a v20.x project (has embedded wizard/).
+ */
+export declare function detectV20Project(dir: string): Promise<MigrationPlan>;
+/**
+ * Migrate a v20.x project to v21.0.
+ *
+ * 1. Create backup at ~/.voidforge/migration-backup/
+ * 2. Remove wizard/ directory
+ * 3. Remove VoidForge deps from package.json
+ * 4. Add .voidforge marker file
+ * 5. Keep all methodology files in place
+ */
+export declare function migrateProject(projectDir: string, dryRun?: boolean): Promise<MigrationResult>;
+export declare function rollbackMigration(projectDir: string, backupDir: string): Promise<void>;

package/dist/wizard/lib/migrator.js

@@ -0,0 +1,190 @@
+/**
+ * Migration from v20.x — detects old-model projects (embedded wizard/)
+ * and converts them to v21.0 (standalone wizard, methodology-only projects).
+ */
+import { readdir, readFile, rm, cp, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createMarker, writeMarker } from './marker.js';
+// ── Detection ────────────────────────────────────────────
+async function countFiles(dir) {
+    if (!existsSync(dir))
+        return 0;
+    let count = 0;
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            count += await countFiles(join(dir, entry.name));
+        }
+        else {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Detect if a directory is a v20.x project (has embedded wizard/).
+ */
+export async function detectV20Project(dir) {
+    const projectDir = resolve(dir);
+    const wizardDir = join(projectDir, 'wizard');
+    const hasWizardDir = existsSync(wizardDir) && existsSync(join(wizardDir, 'server.ts'));
+    const wizardFileCount = hasWizardDir ? await countFiles(wizardDir) : 0;
+    // Check package.json for VoidForge dependencies
+    const pkgPath = join(projectDir, 'package.json');
+    const hasPackageJson = existsSync(pkgPath);
+    let voidforgeDeps = [];
+    if (hasPackageJson) {
+        try {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            voidforgeDeps = Object.keys(allDeps).filter(d => d.startsWith('@aws-sdk/') || d === 'node-pty' || d === 'ws');
+        }
+        catch {
+            // Invalid package.json
+        }
+    }
+    const hasMethodology = existsSync(join(projectDir, 'CLAUDE.md'));
+    const hasMarker = existsSync(join(projectDir, '.voidforge'));
+    return {
+        projectDir,
+        hasWizardDir,
+        wizardFileCount,
+        hasPackageJson,
+        voidforgeDeps,
+        hasMethodology,
+        hasMarker,
+    };
+}
+// ── Backup ───────────────────────────────────────────────
+async function createBackup(projectDir) {
+    const { homedir } = await import('node:os');
+    const backupBase = join(homedir(), '.voidforge', 'migration-backup');
+    await mkdir(backupBase, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const projectName = projectDir.split('/').pop() ?? 'project';
+    const backupDir = join(backupBase, `${projectName}-${timestamp}`);
+    await mkdir(backupDir);
+    // Backup wizard/ directory
+    const wizardDir = join(projectDir, 'wizard');
+    if (existsSync(wizardDir)) {
+        await cp(wizardDir, join(backupDir, 'wizard'), { recursive: true });
+    }
+    // Backup package.json
+    const pkgPath = join(projectDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        await cp(pkgPath, join(backupDir, 'package.json'));
+    }
+    // Backup package-lock.json
+    const lockPath = join(projectDir, 'package-lock.json');
+    if (existsSync(lockPath)) {
+        await cp(lockPath, join(backupDir, 'package-lock.json'));
+    }
+    return backupDir;
+}
+// ── Migration ────────────────────────────────────────────
+/**
+ * Migrate a v20.x project to v21.0.
+ *
+ * 1. Create backup at ~/.voidforge/migration-backup/
+ * 2. Remove wizard/ directory
+ * 3. Remove VoidForge deps from package.json
+ * 4. Add .voidforge marker file
+ * 5. Keep all methodology files in place
+ */
+export async function migrateProject(projectDir, dryRun = false) {
+    const plan = await detectV20Project(projectDir);
+    if (!plan.hasWizardDir) {
+        throw new Error('No wizard/ directory found — this is not a v20.x project.');
+    }
+    if (plan.hasMarker) {
+        throw new Error('Project already has a .voidforge marker — already migrated?');
+    }
+    if (dryRun) {
+        return {
+            success: true,
+            backupDir: '(dry run — no backup created)',
+            wizardFilesRemoved: plan.wizardFileCount,
+            depsRemoved: plan.voidforgeDeps,
+            markerCreated: true,
+        };
+    }
+    // 1. Create backup
+    const backupDir = await createBackup(projectDir);
+    // 2. Remove wizard/ directory
+    const wizardDir = join(projectDir, 'wizard');
+    await rm(wizardDir, { recursive: true, force: true });
+    // 3. Remove VoidForge deps from package.json
+    const depsRemoved = [];
+    const pkgPath = join(projectDir, 'package.json');
+    if (plan.hasPackageJson && plan.voidforgeDeps.length > 0) {
+        try {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+            for (const dep of plan.voidforgeDeps) {
+                if (pkg.dependencies?.[dep]) {
+                    delete pkg.dependencies[dep];
+                    depsRemoved.push(dep);
+                }
+                if (pkg.devDependencies?.[dep]) {
+                    delete pkg.devDependencies[dep];
+                    depsRemoved.push(dep);
+                }
+            }
+            const { writeFile } = await import('node:fs/promises');
+            await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+        }
+        catch {
+            // package.json modification failed — non-fatal
+        }
+    }
+    // 4. Write .voidforge marker
+    const marker = createMarker('21.0.0', 'full');
+    await writeMarker(projectDir, marker);
+    // 5. Remove old config files that moved to the wizard package
+    const oldConfigs = ['vitest.config.ts', 'playwright.config.ts'];
+    for (const config of oldConfigs) {
+        const configPath = join(projectDir, config);
+        if (existsSync(configPath)) {
+            await rm(configPath);
+        }
+    }
+    // 6. Remove wizard-specific scripts from package.json
+    const scriptsDir = join(projectDir, 'scripts');
+    const wizardScripts = ['voidforge.ts', 'danger-room-feed.sh', 'new-project.sh', 'vault-read.ts'];
+    for (const script of wizardScripts) {
+        const scriptPath = join(scriptsDir, script);
+        if (existsSync(scriptPath)) {
+            await rm(scriptPath);
+        }
+    }
+    return {
+        success: true,
+        backupDir,
+        wizardFilesRemoved: plan.wizardFileCount,
+        depsRemoved,
+        markerCreated: true,
+    };
+}
+// ── Rollback ─────────────────────────────────────────────
+export async function rollbackMigration(projectDir, backupDir) {
+    // Restore wizard/
+    const wizardBackup = join(backupDir, 'wizard');
+    if (existsSync(wizardBackup)) {
+        await cp(wizardBackup, join(projectDir, 'wizard'), { recursive: true });
+    }
+    // Restore package.json
+    const pkgBackup = join(backupDir, 'package.json');
+    if (existsSync(pkgBackup)) {
+        await cp(pkgBackup, join(projectDir, 'package.json'));
+    }
+    // Restore package-lock.json
+    const lockBackup = join(backupDir, 'package-lock.json');
+    if (existsSync(lockBackup)) {
+        await cp(lockBackup, join(projectDir, 'package-lock.json'));
+    }
+    // Remove marker (wasn't there before migration)
+    const markerPath = join(projectDir, '.voidforge');
+    if (existsSync(markerPath)) {
+        await rm(markerPath);
+    }
+}

package/dist/wizard/lib/natural-language-deploy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Natural Language Deploy — resolve prose deployment descriptions to YAML frontmatter.
+ *
+ * Parse: "I want a $20/month server with SSL and daily backups"
+ * → { deploy: 'vps', instanceType: 't3.small', hostname: '', resilience: { backups: 'daily', ... } }
+ *
+ * Uses keyword matching and heuristics — no AI API call required.
+ */
+export interface DeployConfig {
+    deploy: 'vps' | 'vercel' | 'railway' | 'cloudflare' | 'static' | 'docker';
+    instanceType: string;
+    hostname: string;
+    estimatedMonthlyCost: string;
+    resilience: {
+        multiEnv: boolean;
+        previewDeploys: boolean;
+        rollback: boolean;
+        migrations: 'auto' | 'manual' | 'no';
+        backups: 'daily' | 'weekly' | 'no';
+        healthCheck: boolean;
+        gracefulShutdown: boolean;
+        errorBoundaries: boolean;
+        rateLimiting: boolean;
+        deadLetterQueue: boolean;
+    };
+    reasoning: string[];
+}
+export declare function resolveDeployConfig(prose: string): DeployConfig | null;
+/** Convert a DeployConfig to YAML frontmatter fragment. */
+export declare function toFrontmatter(config: DeployConfig): string;

package/dist/wizard/lib/natural-language-deploy.js

@@ -0,0 +1,186 @@
+/**
+ * Natural Language Deploy — resolve prose deployment descriptions to YAML frontmatter.
+ *
+ * Parse: "I want a $20/month server with SSL and daily backups"
+ * → { deploy: 'vps', instanceType: 't3.small', hostname: '', resilience: { backups: 'daily', ... } }
+ *
+ * Uses keyword matching and heuristics — no AI API call required.
+ */
+const BUDGET_TIERS = [
+    { maxMonthly: 10, instanceType: 't3.micro', label: '~$8/mo' },
+    { maxMonthly: 25, instanceType: 't3.small', label: '~$17/mo' },
+    { maxMonthly: 50, instanceType: 't3.medium', label: '~$34/mo' },
+    { maxMonthly: 100, instanceType: 't3.large', label: '~$68/mo' },
+    { maxMonthly: Infinity, instanceType: 't3.xlarge', label: '~$136/mo' },
+];
+function resolveInstanceFromBudget(budget) {
+    return BUDGET_TIERS.find(t => budget <= t.maxMonthly) ?? BUDGET_TIERS[BUDGET_TIERS.length - 1];
+}
+// ── Keyword patterns ────────────────────────────
+const PLATFORM_KEYWORDS = [
+    { pattern: /\bvercel\b/i, target: 'vercel', reason: 'Vercel mentioned explicitly' },
+    { pattern: /\brailway\b/i, target: 'railway', reason: 'Railway mentioned explicitly' },
+    { pattern: /\bcloudflare\b/i, target: 'cloudflare', reason: 'Cloudflare mentioned explicitly' },
+    { pattern: /\bdocker\b|\bcontainer\b/i, target: 'docker', reason: 'Docker/container mentioned' },
+    { pattern: /\bstatic\s*(?:site|hosting|files?)\b/i, target: 'static', reason: 'Static site hosting' },
+    { pattern: /\bvps\b|\bserver\b|\bec2\b|\baws\b|\bssh\b/i, target: 'vps', reason: 'Server/VPS/AWS mentioned' },
+    { pattern: /\bserverless\b|\bedge\b/i, target: 'vercel', reason: 'Serverless/edge → Vercel' },
+    { pattern: /\bfree\s*tier\b|\bno\s*cost\b|\bfree\b/i, target: 'railway', reason: 'Free tier → Railway' },
+];
+const FEATURE_KEYWORDS = [
+    { pattern: /\bbackup/i, key: 'backups', reason: 'Backups requested' },
+    { pattern: /\bssl\b|\bhttps\b|\btls\b/i, key: 'ssl', reason: 'SSL/TLS requested' },
+    { pattern: /\bcustom\s*domain\b|\bmy\s*domain\b/i, key: 'customDomain', reason: 'Custom domain' },
+    { pattern: /\brollback\b|\brevert\b/i, key: 'rollback', reason: 'Rollback requested' },
+    { pattern: /\bpreview\b|\bpr\s*deploy/i, key: 'previewDeploys', reason: 'Preview deploys' },
+    { pattern: /\bhealth\s*check\b|\bmonitoring\b|\buptime\b/i, key: 'healthCheck', reason: 'Health monitoring' },
+    { pattern: /\brate\s*limit/i, key: 'rateLimiting', reason: 'Rate limiting' },
+    { pattern: /\bgraceful\b|\bzero\s*downtime\b/i, key: 'gracefulShutdown', reason: 'Zero-downtime' },
+    { pattern: /\bmulti\s*(?:env|environment)\b|\bstaging\b/i, key: 'multiEnv', reason: 'Multi-environment' },
+    { pattern: /\berror\s*boundar/i, key: 'errorBoundaries', reason: 'Error boundaries' },
+    { pattern: /\bdead\s*letter\b|\bdlq\b|\bretry\s*queue\b/i, key: 'deadLetterQueue', reason: 'Dead letter queue' },
+    { pattern: /\bmigration/i, key: 'migrations', reason: 'Database migrations' },
+];
+const SCALE_KEYWORDS = [
+    { pattern: /\bsmall\b|\bsimple\b|\bblog\b|\bpersonal\b|\bside\s*project\b|\bmvp\b|\bprototype\b/i, scale: 'small', reason: 'Small/simple project' },
+    { pattern: /\bmedium\b|\bstartup\b|\bsaas\b|\bteam\b|\bgrow/i, scale: 'medium', reason: 'Medium/startup scale' },
+    { pattern: /\blarge\b|\benterprise\b|\bthousands\b|\bhigh\s*traffic\b|\bscale\b|\bproduction\b/i, scale: 'large', reason: 'Large/production scale' },
+];
+// ── Main resolver ───────────────────────────────
+export function resolveDeployConfig(prose) {
+    if (!prose.trim())
+        return null;
+    const reasoning = [];
+    const features = new Set();
+    // Extract budget — prefer amounts near cost keywords, fall back to first $N
+    const costContextMatch = prose.match(/(?:budget|spend|cost|month|mo)[^$]*\$(\d+(?:\.\d+)?)/i)
+        ?? prose.match(/\$(\d+(?:\.\d+)?)(?:\s*\/\s*mo(?:nth)?)/i)
+        ?? prose.match(/\$(\d+(?:\.\d+)?)/i);
+    const budget = costContextMatch ? Math.round(parseFloat(costContextMatch[1])) : -1;
+    // Detect explicit platform
+    let deploy = 'vps'; // default
+    let platformDetected = false;
+    for (const kw of PLATFORM_KEYWORDS) {
+        if (kw.pattern.test(prose)) {
+            deploy = kw.target;
+            reasoning.push(kw.reason);
+            platformDetected = true;
+            break;
+        }
+    }
+    // Detect features
+    for (const kw of FEATURE_KEYWORDS) {
+        if (kw.pattern.test(prose)) {
+            features.add(kw.key);
+            reasoning.push(kw.reason);
+        }
+    }
+    // Detect scale
+    let scale = 'small';
+    for (const kw of SCALE_KEYWORDS) {
+        if (kw.pattern.test(prose)) {
+            scale = kw.scale;
+            reasoning.push(kw.reason);
+            break;
+        }
+    }
+    // If no platform detected, infer from features and scale
+    if (!platformDetected) {
+        if (features.has('previewDeploys') || features.has('errorBoundaries')) {
+            deploy = 'vercel';
+            reasoning.push('Preview deploys/error boundaries → Vercel (best support)');
+        }
+        else if (scale === 'large' || features.has('customDomain') || budget > 30) {
+            deploy = 'vps';
+            reasoning.push('Large scale or custom domain with budget → VPS');
+        }
+        else if (scale === 'small' && budget < 0) {
+            deploy = 'railway';
+            reasoning.push('Small project, no budget specified → Railway (easiest start)');
+        }
+        else {
+            deploy = 'vps';
+            reasoning.push('Default → VPS (most flexible)');
+        }
+    }
+    // Resolve instance type from budget or scale
+    let instanceType = '';
+    let estimatedCost = '';
+    if (deploy === 'vps') {
+        if (budget >= 0) {
+            const tier = resolveInstanceFromBudget(budget);
+            instanceType = tier.instanceType;
+            estimatedCost = tier.label;
+            reasoning.push(`Budget $${budget}/mo → ${tier.instanceType} (${tier.label})`);
+        }
+        else {
+            const scaleMap = { small: 't3.micro', medium: 't3.small', large: 't3.medium' };
+            const costMap = { small: '~$8/mo', medium: '~$17/mo', large: '~$34/mo' };
+            instanceType = scaleMap[scale];
+            estimatedCost = costMap[scale];
+            reasoning.push(`${scale} scale → ${instanceType} (${estimatedCost})`);
+        }
+    }
+    else {
+        estimatedCost = deploy === 'railway' ? 'Free tier available' :
+            deploy === 'vercel' ? 'Free tier available' :
+                deploy === 'cloudflare' ? 'Free tier available' :
+                    deploy === 'static' ? 'Minimal (~$1/mo S3)' : 'Varies';
+    }
+    // Extract hostname if mentioned
+    const hostnameMatch = prose.match(/(?:domain|hostname|url)[\s:]*([a-z0-9.-]+\.[a-z]{2,})/i);
+    const hostname = hostnameMatch ? hostnameMatch[1] : '';
+    if (hostname)
+        reasoning.push(`Hostname detected: ${hostname}`);
+    // Build resilience config — defaults based on deploy target + detected features
+    const isVps = deploy === 'vps';
+    const isPlatform = ['vercel', 'railway', 'cloudflare'].includes(deploy);
+    const resilience = {
+        multiEnv: features.has('multiEnv') || scale !== 'small',
+        previewDeploys: features.has('previewDeploys') || (isPlatform && scale !== 'small'),
+        rollback: features.has('rollback') || isPlatform,
+        migrations: features.has('migrations') ? 'auto' : (isVps ? 'manual' : 'no'),
+        backups: features.has('backups') ? 'daily' : (isVps && scale !== 'small' ? 'weekly' : 'no'),
+        healthCheck: features.has('healthCheck') || isVps || scale !== 'small',
+        gracefulShutdown: features.has('gracefulShutdown') || isVps,
+        errorBoundaries: features.has('errorBoundaries'),
+        rateLimiting: features.has('rateLimiting') || scale === 'large',
+        deadLetterQueue: features.has('deadLetterQueue'),
+    };
+    return {
+        deploy,
+        instanceType,
+        hostname,
+        estimatedMonthlyCost: estimatedCost,
+        resilience,
+        reasoning,
+    };
+}
+/** Sanitize a string for safe YAML double-quoted interpolation. */
+function yamlSafe(value) {
+    return value.replace(/[\\"]/g, '');
+}
+/** Convert a DeployConfig to YAML frontmatter fragment. */
+export function toFrontmatter(config) {
+    const lines = [
+        `deploy: "${yamlSafe(config.deploy)}"`,
+    ];
+    if (config.instanceType) {
+        lines.push(`instance_type: "${yamlSafe(config.instanceType)}"`);
+    }
+    if (config.hostname) {
+        lines.push(`hostname: "${yamlSafe(config.hostname.toLowerCase())}"`);
+    }
+    lines.push('resilience:');
+    lines.push(`  multi-env: ${config.resilience.multiEnv ? 'yes' : 'no'}`);
+    lines.push(`  preview-deploys: ${config.resilience.previewDeploys ? 'yes' : 'no'}`);
+    lines.push(`  rollback: ${config.resilience.rollback ? 'yes' : 'no'}`);
+    lines.push(`  migrations: "${yamlSafe(config.resilience.migrations)}"`);
+    lines.push(`  backups: "${yamlSafe(config.resilience.backups)}"`);
+    lines.push(`  health-check: ${config.resilience.healthCheck ? 'yes' : 'no'}`);
+    lines.push(`  graceful-shutdown: ${config.resilience.gracefulShutdown ? 'yes' : 'no'}`);
+    lines.push(`  error-boundaries: ${config.resilience.errorBoundaries ? 'yes' : 'no'}`);
+    lines.push(`  rate-limiting: ${config.resilience.rateLimiting ? 'yes' : 'no'}`);
+    lines.push(`  dead-letter-queue: ${config.resilience.deadLetterQueue ? 'yes' : 'no'}`);
+    return lines.join('\n');
+}

package/dist/wizard/lib/network.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Network utilities — shared private IP detection for WebSocket origin validation.
+ * Consolidates duplicate implementations from health-poller.ts and site-scanner.ts.
+ *
+ * Covers:
+ * - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+ * - CGNAT/Tailscale: 100.64.0.0/10 (RFC 6598)
+ * - Loopback: 127.0.0.0/8
+ * - IPv6 ULA: fd00::/8 (ZeroTier, WireGuard)
+ * - IPv6 loopback: ::1
+ */
+/**
+ * Check if an IP address is in a private/internal range.
+ * Uses numeric octet parsing — NEVER string prefix matching.
+ * (SECURITY_AUDITOR.md: "ip.startsWith('172.2') matches public IPs like 172.200.x.x")
+ */
+export declare function isPrivateIp(ip: string): boolean;
+/**
+ * Check if a WebSocket/HTTP origin is from a private network.
+ * Extracts the hostname from the origin URL and checks if it's private.
+ */
+export declare function isPrivateOrigin(origin: string): boolean;

package/dist/wizard/lib/network.js

@@ -0,0 +1,72 @@
+/**
+ * Network utilities — shared private IP detection for WebSocket origin validation.
+ * Consolidates duplicate implementations from health-poller.ts and site-scanner.ts.
+ *
+ * Covers:
+ * - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+ * - CGNAT/Tailscale: 100.64.0.0/10 (RFC 6598)
+ * - Loopback: 127.0.0.0/8
+ * - IPv6 ULA: fd00::/8 (ZeroTier, WireGuard)
+ * - IPv6 loopback: ::1
+ */
+/**
+ * Check if an IP address is in a private/internal range.
+ * Uses numeric octet parsing — NEVER string prefix matching.
+ * (SECURITY_AUDITOR.md: "ip.startsWith('172.2') matches public IPs like 172.200.x.x")
+ */
+export function isPrivateIp(ip) {
+    // IPv6 checks
+    if (ip.includes(':')) {
+        const normalized = ip.replace(/^\[/, '').replace(/\]$/, '').toLowerCase();
+        if (normalized === '::1')
+            return true;
+        // IPv4-mapped IPv6 (::ffff:10.0.0.1) — extract and check the IPv4 part
+        const v4Mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+        if (v4Mapped)
+            return isPrivateIp(v4Mapped[1]);
+        // fd00::/8 — unique local addresses (ZeroTier, WireGuard)
+        if (normalized.startsWith('fd'))
+            return true;
+        // fe80::/10 — link-local
+        if (normalized.startsWith('fe80'))
+            return true;
+        return false;
+    }
+    // IPv4 checks — parse octets to integers
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return false;
+    const octets = parts.map(Number);
+    if (octets.some(n => isNaN(n) || n < 0 || n > 255))
+        return false;
+    const [a, b] = octets;
+    // 10.0.0.0/8
+    if (a === 10)
+        return true;
+    // 172.16.0.0/12 (172.16.x.x through 172.31.x.x)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168)
+        return true;
+    // 127.0.0.0/8 (loopback)
+    if (a === 127)
+        return true;
+    // 100.64.0.0/10 (CGNAT — Tailscale uses this range)
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    return false;
+}
+/**
+ * Check if a WebSocket/HTTP origin is from a private network.
+ * Extracts the hostname from the origin URL and checks if it's private.
+ */
+export function isPrivateOrigin(origin) {
+    try {
+        const url = new URL(origin);
+        return isPrivateIp(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/wizard/lib/oauth-core.d.ts

@@ -0,0 +1,6 @@
+/**
+ * OAuth core — re-exports from the oauth-token-lifecycle pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { needsRefresh, handleRefreshFailure, getTokenHealth, tokenVaultKey, deserializeTokens, shouldRotateSessionToken, rotateSessionToken, validateSessionToken, } from './patterns/oauth-token-lifecycle.js';
+export type { SessionTokenState } from './patterns/oauth-token-lifecycle.js';

package/dist/wizard/lib/oauth-core.js

@@ -0,0 +1,5 @@
+/**
+ * OAuth core — re-exports from the oauth-token-lifecycle pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { needsRefresh, handleRefreshFailure, getTokenHealth, tokenVaultKey, deserializeTokens, shouldRotateSessionToken, rotateSessionToken, validateSessionToken, } from './patterns/oauth-token-lifecycle.js';

package/dist/wizard/lib/open-browser.d.ts

@@ -0,0 +1 @@
+export declare function openBrowser(url: string): Promise<void>;

package/dist/wizard/lib/open-browser.js

@@ -0,0 +1,26 @@
+import { execFile } from 'node:child_process';
+export function openBrowser(url) {
+    return new Promise((resolve) => {
+        const platform = process.platform;
+        let cmd;
+        let args;
+        if (platform === 'darwin') {
+            cmd = 'open';
+            args = [url];
+        }
+        else if (platform === 'win32') {
+            cmd = 'cmd';
+            args = ['/c', 'start', '', url];
+        }
+        else {
+            cmd = 'xdg-open';
+            args = [url];
+        }
+        execFile(cmd, args, (err) => {
+            if (err) {
+                console.log(`  Open ${url} in your browser to continue`);
+            }
+            resolve();
+        });
+    });
+}