thevoidforge 21.0.0

package/dist/wizard/lib/env-validator.js

@@ -0,0 +1,205 @@
+/**
+ * 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.
+ */
+import { writeFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Patterns that indicate a placeholder value, not a real value. */
+const PLACEHOLDER_PATTERNS = [
+    /^#\s*pending/i,
+    /^#\s*check/i,
+    /^your[-_]?\w+[-_]?here$/i,
+    /^TODO/i,
+    /^CHANGE[-_]?ME/i,
+    /^xxx/i,
+    /^\s*$/,
+];
+function isPlaceholder(value) {
+    return PLACEHOLDER_PATTERNS.some(p => p.test(value));
+}
+/**
+ * Parse a .env file and extract variable names and whether their values are real.
+ * Comments-only lines and section headers are skipped.
+ */
+function parseEnvFile(content) {
+    const vars = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx < 1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        let value = trimmed.slice(eqIdx + 1).trim();
+        // Strip matching quotes only (both must be the same character)
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Skip VoidForge metadata keys
+        if (key.startsWith('VERCEL_PROJECT_') || key.startsWith('CF_PROJECT_') || key.startsWith('RAILWAY_PROJECT_'))
+            continue;
+        vars.push({ key, hasValue: !isPlaceholder(value) });
+    }
+    return vars;
+}
+function generateNodeValidator(vars) {
+    const requiredKeys = vars.map(v => `  '${v.key}'`).join(',\n');
+    const pendingKeys = vars.filter(v => !v.hasValue).map(v => `  '${v.key}'`).join(',\n');
+    return `#!/usr/bin/env node
+/**
+ * Startup environment validation — checks required env vars before boot.
+ * Generated by VoidForge (ADR-018).
+ * Usage: node validate-env.js
+ * Works in both CommonJS and ESM projects.
+ */
+
+const required = [
+${requiredKeys}
+];
+
+const PLACEHOLDER_PATTERNS = [
+  /^#\\s*pending/i,
+  /^#\\s*check/i,
+  /^your[-_]?\\w+[-_]?here$/i,
+  /^TODO/i,
+  /^CHANGE[-_]?ME/i,
+  /^xxx/i,
+];
+
+function isPlaceholder(val) {
+  return !val.trim() || PLACEHOLDER_PATTERNS.some(p => p.test(val));
+}
+
+function validateEnv() {
+  const missing = [];
+  const empty = [];
+
+  for (const key of required) {
+    const val = process.env[key];
+    if (val === undefined) {
+      missing.push(key);
+    } else if (isPlaceholder(val)) {
+      empty.push(key);
+    }
+  }
+
+  if (missing.length > 0 || empty.length > 0) {
+    console.error('\\n=== Environment Validation Failed ===\\n');
+    if (missing.length > 0) {
+      console.error('Missing variables:');
+      for (const key of missing) console.error('  - ' + key);
+    }
+    if (empty.length > 0) {
+      console.error('Placeholder values (need real values):');
+      for (const key of empty) console.error('  - ' + key + ' (placeholder value detected)');
+    }
+    console.error('\\nSet these in your .env file or environment before starting the app.\\n');
+    process.exit(1);
+  }
+
+  console.log('Environment validation passed (' + required.length + ' vars checked)');
+}
+
+// Run if called directly — works in both CJS and ESM
+const isMain = typeof require !== 'undefined'
+  ? require.main === module
+  : process.argv[1]?.endsWith('validate-env.js');
+
+if (isMain) {
+  // Load .env if dotenv is available
+  try { require('dotenv').config(); } catch { /* dotenv not installed — using process.env */ }
+  validateEnv();
+}
+
+// Export for programmatic use
+if (typeof module !== 'undefined') module.exports = { validateEnv };
+`;
+}
+function generatePythonValidator(vars) {
+    const requiredList = vars.map(v => `    "${v.key}"`).join(',\n');
+    return `#!/usr/bin/env python3
+"""
+Startup environment validation — checks required env vars before boot.
+Generated by VoidForge (ADR-018).
+Usage: python validate_env.py
+"""
+
+import os
+import sys
+
+REQUIRED = [
+${requiredList}
+]
+
+PLACEHOLDER_PREFIXES = ["# pending", "# check", "TODO", "CHANGE_ME", "xxx"]
+
+
+def validate_env():
+    missing = []
+    empty = []
+
+    for key in REQUIRED:
+        val = os.environ.get(key)
+        if val is None:
+            missing.append(key)
+        elif not val.strip() or any(val.startswith(p) for p in PLACEHOLDER_PREFIXES):
+            empty.append(key)
+
+    if missing or empty:
+        print("\\n=== Environment Validation Failed ===\\n", file=sys.stderr)
+        if missing:
+            print("Missing variables:", file=sys.stderr)
+            for key in missing:
+                print(f"  - {key}", file=sys.stderr)
+        if empty:
+            print("Placeholder values (need real values):", file=sys.stderr)
+            for key in empty:
+                print(f"  - {key} (placeholder value detected)", file=sys.stderr)
+        print("\\nSet these in your .env file or environment before starting the app.\\n", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Environment validation passed ({len(REQUIRED)} vars checked)")
+
+
+if __name__ == "__main__":
+    # Load .env if python-dotenv is available
+    try:
+        from dotenv import load_dotenv
+        load_dotenv()
+    except ImportError:
+        pass
+    validate_env()
+`;
+}
+/**
+ * Generate an environment validation script based on the project's .env file.
+ */
+export async function generateEnvValidator(projectDir, framework) {
+    const isPython = framework === 'django' || framework === 'flask';
+    const filename = isPython ? 'validate_env.py' : 'validate-env.js';
+    try {
+        // Read the current .env file to discover required variables
+        let envContent = '';
+        try {
+            envContent = await readFile(join(projectDir, '.env'), 'utf-8');
+        }
+        catch {
+            // No .env file — generate a minimal validator
+            return { success: true, file: '' };
+        }
+        const vars = parseEnvFile(envContent);
+        if (vars.length === 0) {
+            return { success: true, file: '' };
+        }
+        const content = isPython
+            ? generatePythonValidator(vars)
+            : generateNodeValidator(vars);
+        await writeFile(join(projectDir, filename), content, 'utf-8');
+        return { success: true, file: filename };
+    }
+    catch (err) {
+        return { success: false, file: filename, error: err.message };
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Shared .env file writer — used by all provisioners.
+ * Appends a labeled section to the project's .env file.
+ * Extracted from 5 identical copy-pasted implementations.
+ */
+/**
+ * Append a section of environment variables to a project's .env file.
+ * Creates the file if it doesn't exist. Adds a blank line separator.
+ *
+ * WARNING: Not safe for concurrent calls. All provisioner steps run sequentially
+ * through the SSE stream, so this is safe in practice. Do not call in parallel.
+ */
+export declare function appendEnvSection(projectDir: string, lines: string[]): Promise<void>;

package/dist/wizard/lib/env-writer.js

@@ -0,0 +1,26 @@
+/**
+ * Shared .env file writer — used by all provisioners.
+ * Appends a labeled section to the project's .env file.
+ * Extracted from 5 identical copy-pasted implementations.
+ */
+import { readFile, writeFile, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Append a section of environment variables to a project's .env file.
+ * Creates the file if it doesn't exist. Adds a blank line separator.
+ *
+ * WARNING: Not safe for concurrent calls. All provisioner steps run sequentially
+ * through the SSE stream, so this is safe in practice. Do not call in parallel.
+ */
+export async function appendEnvSection(projectDir, lines) {
+    const envPath = join(projectDir, '.env');
+    let existing = '';
+    try {
+        existing = await readFile(envPath, 'utf-8');
+    }
+    catch { /* new file */ }
+    const separator = existing ? '\n\n' : '';
+    await writeFile(envPath, existing + separator + lines.join('\n') + '\n', 'utf-8');
+    // Restrict .env permissions — credentials should not be world-readable
+    await chmod(envPath, 0o600);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Shared child process utility — timeout, abort signal, streaming.
+ * Used by github.ts (git commands) and ssh-deploy.ts (ssh/rsync).
+ * Uses execFile (not exec) to prevent shell injection. (ADR-013)
+ */
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+interface ExecOptions {
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string | undefined>;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Execute a command with timeout and abort support.
+ * Uses execFile (not exec) — no shell, no injection risk.
+ */
+export declare function execCommand(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+/**
+ * Check if a binary is available on the system.
+ * Returns the path if found, null if not.
+ */
+export declare function whichBinary(name: string): Promise<string | null>;
+/**
+ * Validate that required binaries exist. Returns missing binary names.
+ */
+export declare function validateBinaries(names: string[]): Promise<string[]>;
+export {};

package/dist/wizard/lib/exec.js

@@ -0,0 +1,52 @@
+/**
+ * Shared child process utility — timeout, abort signal, streaming.
+ * Used by github.ts (git commands) and ssh-deploy.ts (ssh/rsync).
+ * Uses execFile (not exec) to prevent shell injection. (ADR-013)
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFileCb);
+const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes
+/**
+ * Execute a command with timeout and abort support.
+ * Uses execFile (not exec) — no shell, no injection risk.
+ */
+export async function execCommand(command, args, options) {
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
+    const result = await execFileAsync(command, args, {
+        cwd: options?.cwd,
+        timeout,
+        env: options?.env ? { ...process.env, ...options.env } : undefined,
+        signal: options?.abortSignal,
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+    });
+    return {
+        stdout: result.stdout?.toString() ?? '',
+        stderr: result.stderr?.toString() ?? '',
+    };
+}
+/**
+ * Check if a binary is available on the system.
+ * Returns the path if found, null if not.
+ */
+export async function whichBinary(name) {
+    try {
+        const { stdout } = await execCommand('which', [name], { timeout: 5000 });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate that required binaries exist. Returns missing binary names.
+ */
+export async function validateBinaries(names) {
+    const missing = [];
+    for (const name of names) {
+        const found = await whichBinary(name);
+        if (!found)
+            missing.push(name);
+    }
+    return missing;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Methodology A/B Testing — run two protocol variants on the same code and compare.
+ *
+ * Tracks per-agent true-positive rates across projects. Over time, tunes the
+ * methodology based on data, not intuition. Wong manages the experiments.
+ *
+ * Storage: ~/.voidforge/experiments.json
+ */
+export interface ExperimentVariant {
+    name: string;
+    description: string;
+    agentCount: number;
+    phases: string[];
+}
+export interface ExperimentResult {
+    variantName: string;
+    findings: number;
+    truePositives: number;
+    falsePositives: number;
+    contextTokens: number;
+    durationMs: number;
+    agentResults: AgentResult[];
+}
+export interface AgentResult {
+    agent: string;
+    universe: string;
+    findings: number;
+    truePositives: number;
+    falsePositives: number;
+    confidence: number;
+}
+export type ExperimentStatus = 'planned' | 'running' | 'complete' | 'cancelled';
+export interface Experiment {
+    id: string;
+    name: string;
+    description: string;
+    project: string;
+    domain: string;
+    status: ExperimentStatus;
+    createdAt: string;
+    completedAt: string | null;
+    variantA: ExperimentVariant;
+    variantB: ExperimentVariant;
+    resultA: ExperimentResult | null;
+    resultB: ExperimentResult | null;
+    winner: 'A' | 'B' | 'tie' | null;
+    winReason: string | null;
+}
+export interface ExperimentStore {
+    version: 1;
+    experiments: Experiment[];
+}
+/** Create a new experiment. */
+export declare function createExperiment(name: string, description: string, project: string, domain: string, variantA: ExperimentVariant, variantB: ExperimentVariant): Promise<Experiment>;
+/** Record the result of running a variant. */
+export declare function recordResult(experimentId: string, variant: 'A' | 'B', result: ExperimentResult): Promise<Experiment | null>;
+/** List all experiments, optionally filtered by status or project. */
+export declare function listExperiments(filter?: {
+    status?: ExperimentStatus;
+    project?: string;
+}): Promise<Experiment[]>;
+/** Get a single experiment by ID. */
+export declare function getExperiment(id: string): Promise<Experiment | null>;
+/** Get aggregate per-agent accuracy stats across all completed experiments. */
+export declare function getAgentStats(): Promise<Map<string, {
+    experiments: number;
+    truePositives: number;
+    falsePositives: number;
+    avgConfidence: number;
+}>>;

package/dist/wizard/lib/experiment.js

@@ -0,0 +1,169 @@
+/**
+ * Methodology A/B Testing — run two protocol variants on the same code and compare.
+ *
+ * Tracks per-agent true-positive rates across projects. Over time, tunes the
+ * methodology based on data, not intuition. Wong manages the experiments.
+ *
+ * Storage: ~/.voidforge/experiments.json
+ */
+import { readFile, mkdir, rename, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+const EXPERIMENTS_DIR = join(homedir(), '.voidforge');
+const EXPERIMENTS_FILE = join(EXPERIMENTS_DIR, 'experiments.json');
+// ── Storage ─────────────────────────────────────
+async function ensureDir() {
+    try {
+        await mkdir(EXPERIMENTS_DIR, { recursive: true });
+    }
+    catch { /* exists */ }
+}
+async function readStore() {
+    try {
+        const content = await readFile(EXPERIMENTS_FILE, 'utf-8');
+        const data = JSON.parse(content);
+        if (data.version === 1 && Array.isArray(data.experiments))
+            return data;
+    }
+    catch { /* missing or corrupt */ }
+    return { version: 1, experiments: [] };
+}
+// IG-R4 LOKI-002: Serialization queue prevents concurrent write corruption
+let writeQueue = Promise.resolve();
+function serialized(fn) {
+    const result = writeQueue.then(fn, () => fn());
+    writeQueue = result.then(() => { }, () => { });
+    return result;
+}
+async function writeStore(store) {
+    await ensureDir();
+    // IG-R4: Atomic write with fsync — temp+sync+rename
+    const tmpFile = EXPERIMENTS_FILE + '.tmp';
+    const fh = await open(tmpFile, 'w', 0o600);
+    try {
+        await fh.writeFile(JSON.stringify(store, null, 2));
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpFile, EXPERIMENTS_FILE);
+}
+// ── API ─────────────────────────────────────────
+/** Create a new experiment. */
+export function createExperiment(name, description, project, domain, variantA, variantB) {
+    return serialized(async () => {
+        const store = await readStore();
+        const experiment = {
+            id: randomUUID(),
+            name,
+            description,
+            project,
+            domain,
+            status: 'planned',
+            createdAt: new Date().toISOString(),
+            completedAt: null,
+            variantA,
+            variantB,
+            resultA: null,
+            resultB: null,
+            winner: null,
+            winReason: null,
+        };
+        store.experiments.push(experiment);
+        await writeStore(store);
+        return experiment;
+    });
+}
+/** Record the result of running a variant. */
+export function recordResult(experimentId, variant, result) {
+    return serialized(async () => {
+        const store = await readStore();
+        const experiment = store.experiments.find(e => e.id === experimentId);
+        if (!experiment)
+            return null;
+        if (variant === 'A')
+            experiment.resultA = result;
+        else
+            experiment.resultB = result;
+        // Auto-evaluate if both results are in
+        if (experiment.resultA && experiment.resultB) {
+            experiment.status = 'complete';
+            experiment.completedAt = new Date().toISOString();
+            const evaluation = evaluate(experiment.resultA, experiment.resultB);
+            experiment.winner = evaluation.winner;
+            experiment.winReason = evaluation.reason;
+        }
+        else {
+            experiment.status = 'running';
+        }
+        await writeStore(store);
+        return experiment;
+    });
+}
+/** List all experiments, optionally filtered by status or project. */
+export async function listExperiments(filter) {
+    const store = await readStore();
+    let results = store.experiments;
+    if (filter?.status)
+        results = results.filter(e => e.status === filter.status);
+    if (filter?.project)
+        results = results.filter(e => e.project === filter.project);
+    return results;
+}
+/** Get a single experiment by ID. */
+export async function getExperiment(id) {
+    const store = await readStore();
+    return store.experiments.find(e => e.id === id) ?? null;
+}
+/** Get aggregate per-agent accuracy stats across all completed experiments. */
+export async function getAgentStats() {
+    const store = await readStore();
+    const stats = new Map();
+    for (const exp of store.experiments) {
+        if (exp.status !== 'complete')
+            continue;
+        const allResults = [exp.resultA, exp.resultB].filter(Boolean);
+        for (const result of allResults) {
+            for (const ar of result.agentResults) {
+                const existing = stats.get(ar.agent) ?? { experiments: 0, truePositives: 0, falsePositives: 0, totalConfidence: 0 };
+                existing.experiments++;
+                existing.truePositives += ar.truePositives;
+                existing.falsePositives += ar.falsePositives;
+                existing.totalConfidence += ar.confidence;
+                stats.set(ar.agent, existing);
+            }
+        }
+    }
+    const result = new Map();
+    for (const [agent, s] of stats) {
+        result.set(agent, {
+            experiments: s.experiments,
+            truePositives: s.truePositives,
+            falsePositives: s.falsePositives,
+            avgConfidence: s.experiments > 0 ? Math.round(s.totalConfidence / s.experiments) : 0,
+        });
+    }
+    return result;
+}
+function evaluate(resultA, resultB) {
+    // Primary metric: true positive rate (findings that are real issues)
+    const tprA = resultA.findings > 0 ? resultA.truePositives / resultA.findings : 0;
+    const tprB = resultB.findings > 0 ? resultB.truePositives / resultB.findings : 0;
+    // Secondary metric: context efficiency (true positives per 1000 tokens)
+    const effA = resultA.contextTokens > 0 ? (resultA.truePositives / resultA.contextTokens) * 1000 : 0;
+    const effB = resultB.contextTokens > 0 ? (resultB.truePositives / resultB.contextTokens) * 1000 : 0;
+    const tprDiff = Math.abs(tprA - tprB);
+    const SIGNIFICANCE_THRESHOLD = 0.1; // 10% difference is significant
+    if (tprDiff < SIGNIFICANCE_THRESHOLD) {
+        // Similar accuracy — decide on efficiency
+        if (Math.abs(effA - effB) < 0.01) {
+            return { winner: 'tie', reason: `Similar accuracy (${(tprA * 100).toFixed(0)}% vs ${(tprB * 100).toFixed(0)}%) and similar context efficiency` };
+        }
+        const moreEfficient = effA > effB ? 'A' : 'B';
+        return { winner: moreEfficient, reason: `Similar accuracy but ${moreEfficient} is more context-efficient (${(effA * 100).toFixed(1)} vs ${(effB * 100).toFixed(1)} TP/1k tokens)` };
+    }
+    const moreAccurate = tprA > tprB ? 'A' : 'B';
+    return { winner: moreAccurate, reason: `${moreAccurate} has higher true-positive rate (${((moreAccurate === 'A' ? tprA : tprB) * 100).toFixed(0)}% vs ${((moreAccurate === 'A' ? tprB : tprA) * 100).toFixed(0)}%)` };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Extension system — install, uninstall, and list extensions for VoidForge projects.
+ *
+ * Extensions add optional capabilities to projects without npm dependencies.
+ * Templates are copied into the project; runtime imports come from the global wizard.
+ */
+export type ExtensionName = 'danger-room' | 'cultivation';
+interface ExtensionDef {
+    name: ExtensionName;
+    description: string;
+    install: (projectDir: string) => Promise<number>;
+    uninstall: (projectDir: string) => Promise<void>;
+}
+export declare function getExtension(name: string): ExtensionDef | undefined;
+export declare function listExtensions(): ExtensionDef[];
+export declare function installExtension(projectDir: string, name: string): Promise<{
+    filesCreated: number;
+}>;
+export declare function uninstallExtension(projectDir: string, name: string): Promise<void>;
+export {};