thevoidforge 21.0.0

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

@@ -0,0 +1,262 @@
+/**
+ * Torres's Site Scanner — HTTP-based technical reconnaissance.
+ *
+ * Scans a deployed site without browser dependencies:
+ * - Response times and status codes on main routes
+ * - Meta tags (title, description, OG, JSON-LD)
+ * - Security headers (HTTPS, HSTS, CSP, CORS, X-Frame-Options)
+ * - Cache headers, compression (gzip/brotli)
+ * - Analytics detection (GA4, Plausible, PostHog snippets)
+ * - Mobile viewport, favicon, sitemap.xml, robots.txt
+ * - Growth infrastructure (email capture forms, cookie consent)
+ *
+ * Zero dependencies — uses node:https only.
+ *
+ * PRD Reference: ROADMAP v12.0 deliverables (Torres's site scanner)
+ */
+import { get as httpsGet } from 'node:https';
+import { get as httpGet } from 'node:http';
+import { URL } from 'node:url';
+// ── HTTP Helper ───────────────────────────────────────
+/** SSRF protection: reject private/internal IP ranges + DNS rebinding defense */
+function isPrivateIp(ip) {
+    // Block loopback, private ranges, link-local, metadata endpoints, mapped IPv6
+    if (/^(127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|169\.254\.|0\.|0x|::1|::ffff:(127|10|172\.(1[6-9]|2|3[01])|192\.168|169\.254)|fd|fe80)/i.test(ip))
+        return true;
+    if (ip === 'localhost' || ip === '::1' || ip === '[::1]' || ip === '0.0.0.0')
+        return true;
+    return false;
+}
+function isPrivateUrl(url) {
+    try {
+        const hostname = new URL(url).hostname;
+        // First check: hostname string (catches literal IPs and localhost)
+        if (isPrivateIp(hostname))
+            return true;
+        // DNS rebinding defense: resolve hostname and check resolved IP
+        // Note: full DNS resolution requires async — for the sync check, we block
+        // known-bad hostnames. The async fetchUrl also checks after connection.
+        if (/^(metadata|instance-data)/i.test(hostname))
+            return true; // Cloud metadata hostnames
+        return false;
+    }
+    catch {
+        return true;
+    } // Malformed URL = reject
+}
+function fetchUrl(url, timeoutMs = 10000, maxRedirects = 5) {
+    return new Promise((resolve, reject) => {
+        if (isPrivateUrl(url)) {
+            reject(new Error(`SSRF blocked: ${new URL(url).hostname} is a private/internal address`));
+            return;
+        }
+        const parsedUrl = new URL(url);
+        const getter = parsedUrl.protocol === 'https:' ? httpsGet : httpGet;
+        const start = Date.now();
+        let ttfb = 0;
+        const req = getter(url, { timeout: timeoutMs, headers: { 'User-Agent': 'VoidForge-Scanner/1.0' } }, (res) => {
+            ttfb = Date.now() - start;
+            let body = '';
+            // Follow redirects with depth limit
+            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                if (maxRedirects <= 0) {
+                    reject(new Error('Too many redirects (max 5)'));
+                    return;
+                }
+                const redirectUrl = new URL(res.headers.location, url).toString();
+                fetchUrl(redirectUrl, timeoutMs, maxRedirects - 1).then(resolve).catch(reject);
+                return;
+            }
+            res.setEncoding('utf-8');
+            res.on('data', (chunk) => { body += chunk; });
+            res.on('end', () => {
+                resolve({
+                    statusCode: res.statusCode || 0,
+                    headers: res.headers,
+                    body: body.slice(0, 500000), // Cap at 500KB to prevent memory issues
+                    ttfbMs: ttfb,
+                    totalMs: Date.now() - start,
+                });
+            });
+        });
+        req.on('timeout', () => { req.destroy(); reject(new Error('Timeout')); });
+        req.on('error', reject);
+    });
+}
+async function checkExists(url) {
+    try {
+        const res = await fetchUrl(url, 5000);
+        return res.statusCode === 200;
+    }
+    catch {
+        return false;
+    }
+}
+// ── HTML Parsing (zero-dep, regex-based) ──────────────
+function extractMeta(html, name) {
+    const re = new RegExp(`<meta[^>]+(?:name|property)=["']${name}["'][^>]+content=["']([^"']+)["']`, 'i');
+    const alt = new RegExp(`<meta[^>]+content=["']([^"']+)["'][^>]+(?:name|property)=["']${name}["']`, 'i');
+    return (html.match(re)?.[1] || html.match(alt)?.[1]) ?? null;
+}
+function extractTitle(html) {
+    return html.match(/<title[^>]*>([^<]+)<\/title>/i)?.[1]?.trim() ?? null;
+}
+function countTag(html, tag) {
+    const re = new RegExp(`<${tag}[\\s>]`, 'gi');
+    return (html.match(re) || []).length;
+}
+function hasTag(html, pattern) {
+    return new RegExp(pattern, 'i').test(html);
+}
+// ── Main Scanner ──────────────────────────────────────
+export async function scanSite(siteUrl) {
+    const result = {
+        url: siteUrl,
+        scannedAt: new Date().toISOString(),
+        reachable: false,
+        performance: { ttfbMs: null, totalTimeMs: null, contentLength: null, compressed: false, cacheControl: null },
+        seo: { title: null, description: null, ogTitle: null, ogDescription: null, ogImage: null, canonicalUrl: null, viewport: false, favicon: false, jsonLd: false, sitemapExists: false, robotsExists: false, h1Count: 0 },
+        security: { https: false, hsts: false, csp: null, xFrameOptions: null, xContentTypeOptions: false, referrerPolicy: null, corsAllowOrigin: null },
+        growth: { analyticsDetected: [], cookieConsentDetected: false, emailCaptureDetected: false, socialMetaComplete: false },
+        health: { statusCode: null, redirectChain: [], responseHeaders: {} },
+    };
+    try {
+        const res = await fetchUrl(siteUrl);
+        result.reachable = true;
+        const html = res.body;
+        const headers = res.headers;
+        // ── Performance ────────────────
+        result.performance.ttfbMs = res.ttfbMs;
+        result.performance.totalTimeMs = res.totalMs;
+        result.performance.contentLength = parseInt(headers['content-length'] || '0') || html.length;
+        result.performance.compressed = !!(headers['content-encoding']?.match(/gzip|br|deflate/));
+        result.performance.cacheControl = headers['cache-control'] ?? null;
+        // ── SEO ────────────────────────
+        result.seo.title = extractTitle(html);
+        result.seo.description = extractMeta(html, 'description');
+        result.seo.ogTitle = extractMeta(html, 'og:title');
+        result.seo.ogDescription = extractMeta(html, 'og:description');
+        result.seo.ogImage = extractMeta(html, 'og:image');
+        result.seo.canonicalUrl = html.match(/<link[^>]+rel=["']canonical["'][^>]+href=["']([^"']+)["']/i)?.[1] ?? null;
+        result.seo.viewport = hasTag(html, '<meta[^>]+name=["\'"]viewport');
+        result.seo.favicon = hasTag(html, '<link[^>]+rel=["\'"](?:icon|shortcut icon)');
+        result.seo.jsonLd = hasTag(html, '<script[^>]+type=["\'"]application/ld\\+json');
+        result.seo.h1Count = countTag(html, 'h1');
+        // Check sitemap and robots
+        const baseUrl = new URL(siteUrl).origin;
+        const [sitemapOk, robotsOk] = await Promise.all([
+            checkExists(baseUrl + '/sitemap.xml'),
+            checkExists(baseUrl + '/robots.txt'),
+        ]);
+        result.seo.sitemapExists = sitemapOk;
+        result.seo.robotsExists = robotsOk;
+        // ── Security ───────────────────
+        result.security.https = siteUrl.startsWith('https://');
+        result.security.hsts = !!headers['strict-transport-security'];
+        result.security.csp = headers['content-security-policy'] ?? null;
+        result.security.xFrameOptions = headers['x-frame-options'] ?? null;
+        result.security.xContentTypeOptions = headers['x-content-type-options'] === 'nosniff';
+        result.security.referrerPolicy = headers['referrer-policy'] ?? null;
+        result.security.corsAllowOrigin = headers['access-control-allow-origin'] ?? null;
+        // ── Growth ─────────────────────
+        if (hasTag(html, 'gtag|GA4|googletagmanager|G-[A-Z0-9]+'))
+            result.growth.analyticsDetected.push('ga4');
+        if (hasTag(html, 'plausible'))
+            result.growth.analyticsDetected.push('plausible');
+        if (hasTag(html, 'posthog'))
+            result.growth.analyticsDetected.push('posthog');
+        if (hasTag(html, 'hotjar'))
+            result.growth.analyticsDetected.push('hotjar');
+        if (hasTag(html, 'mixpanel'))
+            result.growth.analyticsDetected.push('mixpanel');
+        result.growth.cookieConsentDetected = hasTag(html, 'cookie.?consent|cookie.?banner|cookiebot|onetrust');
+        result.growth.emailCaptureDetected = hasTag(html, '<input[^>]+type=["\'"]email');
+        result.growth.socialMetaComplete = !!(result.seo.ogTitle && result.seo.ogDescription && result.seo.ogImage && extractMeta(html, 'twitter:card'));
+        // ── Health ─────────────────────
+        result.health.statusCode = res.statusCode;
+        result.health.responseHeaders = headers;
+    }
+    catch (err) {
+        result.error = err.message;
+    }
+    return result;
+}
+/**
+ * Score the scan result across the 5 Deep Current dimensions.
+ * Returns partial scores for performance, SEO (part of growth), and security.
+ */
+export function scoreScan(scan) {
+    if (!scan.reachable)
+        return { performance: 0, seoScore: 0, securityScore: 0, growthReadiness: 0 };
+    // Performance (0-100)
+    let perf = 50; // base
+    if (scan.performance.ttfbMs !== null) {
+        if (scan.performance.ttfbMs < 200)
+            perf += 20;
+        else if (scan.performance.ttfbMs < 800)
+            perf += 10;
+        else
+            perf -= 10;
+    }
+    if (scan.performance.compressed)
+        perf += 15;
+    if (scan.performance.cacheControl)
+        perf += 15;
+    perf = Math.max(0, Math.min(100, perf));
+    // SEO (0-100)
+    let seo = 0;
+    if (scan.seo.title)
+        seo += 15;
+    if (scan.seo.description)
+        seo += 15;
+    if (scan.seo.viewport)
+        seo += 10;
+    if (scan.seo.favicon)
+        seo += 5;
+    if (scan.seo.sitemapExists)
+        seo += 15;
+    if (scan.seo.robotsExists)
+        seo += 10;
+    if (scan.seo.jsonLd)
+        seo += 10;
+    if (scan.seo.canonicalUrl)
+        seo += 10;
+    if (scan.seo.h1Count === 1)
+        seo += 10; // Exactly one h1 is best practice
+    // Security (0-100)
+    let sec = 0;
+    if (scan.security.https)
+        sec += 25;
+    if (scan.security.hsts)
+        sec += 15;
+    if (scan.security.csp)
+        sec += 20;
+    if (scan.security.xFrameOptions)
+        sec += 10;
+    if (scan.security.xContentTypeOptions)
+        sec += 10;
+    if (scan.security.referrerPolicy)
+        sec += 10;
+    sec += 10; // base for being reachable
+    // Growth Readiness (0-100)
+    let growth = 0;
+    if (scan.growth.analyticsDetected.length > 0)
+        growth += 25;
+    if (scan.growth.socialMetaComplete)
+        growth += 20;
+    if (scan.growth.emailCaptureDetected)
+        growth += 20;
+    if (scan.growth.cookieConsentDetected)
+        growth += 10;
+    if (scan.seo.sitemapExists)
+        growth += 10;
+    if (scan.seo.jsonLd)
+        growth += 10;
+    growth += 5; // base
+    return {
+        performance: Math.min(100, perf),
+        seoScore: Math.min(100, seo),
+        securityScore: Math.min(100, sec),
+        growthReadiness: Math.min(100, growth),
+    };
+}

package/dist/wizard/lib/ssh-deploy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SSH deploy — connect to EC2, run provision.sh, deploy code via release directories.
+ * Uses exec.ts for child process operations (ADR-013).
+ * Performs release-directory management directly via SSH (not deploy.sh which is local-mode).
+ * Retry loop handles sshd startup delay after EC2 launch.
+ */
+import type { ProvisionEmitter } from './provisioners/types.js';
+export interface SshDeployResult {
+    success: boolean;
+    deployUrl?: string;
+    error?: string;
+}
+/**
+ * Full SSH deploy flow for AWS VPS:
+ * 1. Validate ssh/rsync binaries
+ * 2. Upload provision.sh via rsync
+ * 3. Run provision.sh (first-time server setup)
+ * 4. Create release directory, rsync code, install deps, swap symlink, restart
+ * 5. Health check with rollback on failure
+ *
+ * NOTE: deploy.sh is a LOCAL-mode script (runs from dev machine, SSHes into server).
+ * This module runs commands DIRECTLY on the server via SSH, matching the same
+ * release-directory strategy but without the SSH-over-SSH problem.
+ */
+export declare function sshDeploy(projectDir: string, host: string, user: string, keyPath: string, hostname: string | undefined, framework: string, emit: ProvisionEmitter, abortSignal?: AbortSignal): Promise<SshDeployResult>;

package/dist/wizard/lib/ssh-deploy.js

@@ -0,0 +1,225 @@
+/**
+ * SSH deploy — connect to EC2, run provision.sh, deploy code via release directories.
+ * Uses exec.ts for child process operations (ADR-013).
+ * Performs release-directory management directly via SSH (not deploy.sh which is local-mode).
+ * Retry loop handles sshd startup delay after EC2 launch.
+ */
+import { join } from 'node:path';
+import { execCommand, validateBinaries } from './exec.js';
+const SSH_RETRY_COUNT = 5;
+const SSH_RETRY_DELAY_MS = 10_000;
+const SSH_COMMAND_TIMEOUT_MS = 300_000; // 5 minutes per command
+const HEALTH_CHECK_RETRIES = 5;
+const HEALTH_CHECK_DELAY_MS = 5_000;
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+function sshArgs(keyPath, host, user) {
+    return [
+        '-i', keyPath,
+        '-o', 'StrictHostKeyChecking=accept-new',
+        '-o', 'ConnectTimeout=10',
+        '-o', 'BatchMode=yes',
+        `${user}@${host}`,
+    ];
+}
+/**
+ * Execute a single SSH command with retry for connection failures.
+ * Returns stdout on success, throws on failure after all retries.
+ */
+async function sshExec(keyPath, host, user, command, emit, stepName, abortSignal) {
+    for (let attempt = 1; attempt <= SSH_RETRY_COUNT; attempt++) {
+        try {
+            const result = await execCommand('ssh', [...sshArgs(keyPath, host, user), command], { timeout: SSH_COMMAND_TIMEOUT_MS, abortSignal });
+            return result.stdout;
+        }
+        catch (err) {
+            const msg = err.message;
+            const isConnectionError = msg.includes('Connection refused') ||
+                msg.includes('Connection timed out') ||
+                msg.includes('No route to host') ||
+                msg.includes('Connection reset');
+            if (isConnectionError && attempt < SSH_RETRY_COUNT) {
+                emit({
+                    step: stepName,
+                    status: 'started',
+                    message: `SSH connection failed (attempt ${attempt}/${SSH_RETRY_COUNT}), retrying in ${SSH_RETRY_DELAY_MS / 1000}s...`,
+                });
+                await sleep(SSH_RETRY_DELAY_MS);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error('SSH retry loop exited unexpectedly');
+}
+/**
+ * Full SSH deploy flow for AWS VPS:
+ * 1. Validate ssh/rsync binaries
+ * 2. Upload provision.sh via rsync
+ * 3. Run provision.sh (first-time server setup)
+ * 4. Create release directory, rsync code, install deps, swap symlink, restart
+ * 5. Health check with rollback on failure
+ *
+ * NOTE: deploy.sh is a LOCAL-mode script (runs from dev machine, SSHes into server).
+ * This module runs commands DIRECTLY on the server via SSH, matching the same
+ * release-directory strategy but without the SSH-over-SSH problem.
+ */
+export async function sshDeploy(projectDir, host, user, keyPath, hostname, framework, emit, abortSignal) {
+    // Step 1: Validate binaries
+    emit({ step: 'ssh-validate', status: 'started', message: 'Checking for ssh and rsync' });
+    const missingBins = await validateBinaries(['ssh', 'rsync']);
+    if (missingBins.length > 0) {
+        emit({ step: 'ssh-validate', status: 'error', message: `Missing binaries: ${missingBins.join(', ')}. Install them to enable SSH deploy.` });
+        return { success: false, error: `Missing: ${missingBins.join(', ')}` };
+    }
+    emit({ step: 'ssh-validate', status: 'done', message: 'ssh and rsync found' });
+    const fullKeyPath = keyPath.startsWith('/') ? keyPath : join(projectDir, keyPath);
+    const rsyncSshFlag = `ssh -i "${fullKeyPath}" -o StrictHostKeyChecking=accept-new -o ConnectTimeout=10`;
+    // Step 2: Upload infrastructure scripts
+    emit({ step: 'ssh-upload', status: 'started', message: 'Uploading infrastructure scripts' });
+    try {
+        await sshExec(fullKeyPath, host, user, 'mkdir -p ~/infra', emit, 'ssh-upload', abortSignal);
+        await execCommand('rsync', [
+            '-avz', '--progress',
+            '-e', rsyncSshFlag,
+            `${join(projectDir, 'infra')}/`,
+            `${user}@${host}:~/infra/`,
+        ], { timeout: 60_000, abortSignal });
+        emit({ step: 'ssh-upload', status: 'done', message: 'Infrastructure scripts uploaded' });
+    }
+    catch (err) {
+        emit({ step: 'ssh-upload', status: 'error', message: 'Failed to upload scripts', detail: err.message });
+        return { success: false, error: err.message };
+    }
+    // Step 3: Run provision.sh (first-time server setup — idempotent, safe to re-run)
+    emit({ step: 'ssh-provision', status: 'started', message: 'Running server provisioning (this may take 2-5 minutes)...' });
+    try {
+        const provStart = Date.now();
+        const heartbeat = setInterval(() => {
+            const elapsed = Math.round((Date.now() - provStart) / 1000);
+            emit({ step: 'ssh-provision', status: 'started', message: `Still provisioning... (${elapsed}s elapsed)` });
+        }, 30_000);
+        try {
+            await sshExec(fullKeyPath, host, user, 'chmod +x ~/infra/provision.sh && sudo ~/infra/provision.sh', emit, 'ssh-provision', abortSignal);
+        }
+        finally {
+            clearInterval(heartbeat);
+        }
+        emit({ step: 'ssh-provision', status: 'done', message: 'Server provisioning complete' });
+    }
+    catch (err) {
+        emit({ step: 'ssh-provision', status: 'error', message: 'Server provisioning failed', detail: err.message });
+        return { success: false, error: `provision.sh failed: ${err.message}` };
+    }
+    // Step 4: Deploy code using release-directory strategy
+    // Matches the deploy.sh pattern but executed server-side via SSH commands
+    const release = new Date().toISOString().replace(/[-:T.Z]/g, '').slice(0, 14);
+    const releasesDir = '/opt/app/releases';
+    const currentLink = '/opt/app/current';
+    const releaseDir = `${releasesDir}/${release}`;
+    emit({ step: 'ssh-deploy', status: 'started', message: `Creating release ${release}` });
+    let previousRelease = '';
+    try {
+        // Create release directory
+        await sshExec(fullKeyPath, host, user, `sudo mkdir -p ${releaseDir} && sudo chown ${user}:${user} ${releaseDir}`, emit, 'ssh-deploy', abortSignal);
+        // Rsync project code to release directory (excluding dev artifacts)
+        await execCommand('rsync', [
+            '-avz', '--delete',
+            '--exclude', '.git',
+            '--exclude', 'node_modules',
+            '--exclude', '.env',
+            '--exclude', '.ssh',
+            '--exclude', 'infra',
+            '--exclude', 'coverage',
+            '--exclude', 'logs',
+            '-e', rsyncSshFlag,
+            `${projectDir}/`,
+            `${user}@${host}:${releaseDir}/`,
+        ], { timeout: 120_000, abortSignal });
+        emit({ step: 'ssh-deploy', status: 'started', message: 'Code uploaded, installing dependencies...' });
+        // Install dependencies
+        const isNode = ['next.js', 'express'].includes(framework) || !framework;
+        const isDjango = framework === 'django';
+        const installCmd = isNode
+            ? 'npm ci --omit=dev'
+            : isDjango
+                ? 'pip3.12 install -r requirements.txt'
+                : 'bundle install --deployment --without development test';
+        await sshExec(fullKeyPath, host, user, `cd ${releaseDir} && ${installCmd}`, emit, 'ssh-deploy', abortSignal);
+        // Save previous release for rollback
+        try {
+            previousRelease = (await sshExec(fullKeyPath, host, user, `readlink ${currentLink} 2>/dev/null || echo ''`, emit, 'ssh-deploy', abortSignal)).trim();
+        }
+        catch { /* no previous release */ }
+        // Swap symlink atomically
+        await sshExec(fullKeyPath, host, user, `sudo ln -sfn ${releaseDir} ${currentLink}`, emit, 'ssh-deploy', abortSignal);
+        // Restart application
+        emit({ step: 'ssh-deploy', status: 'started', message: 'Restarting application...' });
+        const restartCmd = isNode
+            ? `cd ${currentLink} && pm2 startOrRestart ${currentLink}/ecosystem.config.js --env production && pm2 save`
+            : isDjango
+                ? `cd ${currentLink} && python3.12 manage.py migrate --noinput && python3.12 manage.py collectstatic --noinput && supervisorctl restart app`
+                : `cd ${currentLink} && RAILS_ENV=production bundle exec rails db:migrate && touch tmp/restart.txt`;
+        await sshExec(fullKeyPath, host, user, restartCmd, emit, 'ssh-deploy', abortSignal);
+        emit({ step: 'ssh-deploy', status: 'done', message: 'Application deployed and restarted' });
+    }
+    catch (err) {
+        // Rollback: restore previous symlink if available
+        if (previousRelease) {
+            emit({ step: 'ssh-rollback', status: 'started', message: 'Deployment failed — rolling back to previous release' });
+            try {
+                await sshExec(fullKeyPath, host, user, `sudo ln -sfn ${previousRelease} ${currentLink}`, emit, 'ssh-rollback', abortSignal);
+                const isNode = ['next.js', 'express'].includes(framework) || !framework;
+                if (isNode) {
+                    await sshExec(fullKeyPath, host, user, `cd ${currentLink} && pm2 startOrRestart ${currentLink}/ecosystem.config.js --env production`, emit, 'ssh-rollback', abortSignal);
+                }
+                emit({ step: 'ssh-rollback', status: 'done', message: `Rolled back to ${previousRelease}` });
+            }
+            catch {
+                emit({ step: 'ssh-rollback', status: 'error', message: 'Rollback also failed — check server manually' });
+            }
+        }
+        emit({ step: 'ssh-deploy', status: 'error', message: 'Deployment failed', detail: err.message });
+        return { success: false, error: err.message };
+    }
+    // Step 5: Health check
+    const deployUrl = hostname ? `https://${hostname}` : `http://${host}`;
+    emit({ step: 'ssh-health', status: 'started', message: `Checking health at ${deployUrl}` });
+    let healthy = false;
+    for (let i = 1; i <= HEALTH_CHECK_RETRIES; i++) {
+        try {
+            await sshExec(fullKeyPath, host, user, 'curl -sf http://localhost:3000/ -o /dev/null', emit, 'ssh-health', abortSignal);
+            healthy = true;
+            emit({ step: 'ssh-health', status: 'done', message: `Health check passed — live at ${deployUrl}` });
+            break;
+        }
+        catch {
+            if (i < HEALTH_CHECK_RETRIES) {
+                emit({ step: 'ssh-health', status: 'started', message: `Health check attempt ${i}/${HEALTH_CHECK_RETRIES} failed, retrying...` });
+                await sleep(HEALTH_CHECK_DELAY_MS);
+            }
+        }
+    }
+    if (!healthy) {
+        // Rollback on failed health check
+        if (previousRelease) {
+            emit({ step: 'ssh-rollback', status: 'started', message: 'Health check failed — rolling back' });
+            try {
+                await sshExec(fullKeyPath, host, user, `sudo ln -sfn ${previousRelease} ${currentLink}`, emit, 'ssh-rollback', abortSignal);
+                emit({ step: 'ssh-rollback', status: 'done', message: `Rolled back to ${previousRelease}` });
+            }
+            catch {
+                emit({ step: 'ssh-rollback', status: 'error', message: 'Rollback failed — check server manually' });
+            }
+        }
+        emit({ step: 'ssh-health', status: 'error', message: `Health check failed after ${HEALTH_CHECK_RETRIES} attempts`, detail: `Check: ssh -i ${keyPath} ${user}@${host}` });
+        return { success: false, deployUrl, error: 'Health check failed' };
+    }
+    // Clean up old releases (keep last 5)
+    try {
+        await sshExec(fullKeyPath, host, user, `cd ${releasesDir} && ls -1d */ 2>/dev/null | head -n -5 | xargs -r rm -rf`, emit, 'ssh-cleanup', abortSignal);
+    }
+    catch { /* non-fatal */ }
+    return { success: true, deployUrl };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Project templates — curated starters with pre-filled PRD frontmatter,
+ * recommended integrations, and seed configuration.
+ *
+ * Usage: `npx voidforge init --template saas`
+ * Or selected in Gandalf wizard Step 4 (PRD tab: "Start from a template")
+ */
+export interface ProjectTemplate {
+    id: string;
+    name: string;
+    description: string;
+    frontmatter: Record<string, string>;
+    suggestedIntegrations: string[];
+    prdSections: string;
+}
+export declare const TEMPLATES: ProjectTemplate[];
+/** Get a template by ID. Returns null if not found. */
+export declare function getTemplate(id: string): ProjectTemplate | null;
+/** List all available template IDs with descriptions. */
+export declare function listTemplates(): {
+    id: string;
+    name: string;
+    description: string;
+}[];