voidforge-build 23.9.1

package/dist/wizard/lib/treasury-migrator.js

@@ -0,0 +1,227 @@
+/**
+ * Treasury Migrator — Migrate global treasury data to per-project paths.
+ *
+ * v22.0 moved financial paths per-project ({project}/cultivation/treasury/)
+ * but left no migration tooling. Existing users with global treasury data
+ * at ~/.voidforge/treasury/ see empty dashboards after upgrading.
+ *
+ * Strategy: Clean break. Global data is archived, not copied. Per-project
+ * logs start with genesis hash ('0'). Copying would create false provenance
+ * (Riker/Spock dissent, ADR-041 decision).
+ *
+ * v22.1 Mission 1 — Campaign 30
+ */
+import { existsSync } from 'node:fs';
+import { readFile, readdir, mkdir, rename, writeFile, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { getProject } from './project-registry.js';
+import { createProjectContext } from './project-scope.js';
+import { verifyChain } from './patterns/financial-transaction.js';
+// ── Constants ────────────────────────────────────────────
+const GLOBAL_TREASURY_DIR = join(homedir(), '.voidforge', 'treasury');
+const GLOBAL_ARCHIVE_DIR = join(homedir(), '.voidforge', 'treasury-pre-v22');
+const MIGRATION_MARKER = '.migrated';
+// Files that stay global (vault + TOTP are user-scoped, not project-scoped)
+const GLOBAL_ONLY_FILES = new Set(['vault.enc', 'totp.enc']);
+// ── Pre-flight ───────────────────────────────────────────
+export async function preFlightCheck(projectId) {
+    const errors = [];
+    const warnings = [];
+    // Look up project
+    const project = await getProject(projectId);
+    let context = null;
+    if (!project) {
+        errors.push(`Project "${projectId}" not found in registry. Register it first with the wizard.`);
+    }
+    else {
+        context = createProjectContext(project);
+        // Check project directory exists
+        if (!existsSync(project.directory)) {
+            errors.push(`Project directory does not exist: ${project.directory}`);
+        }
+    }
+    // Check global treasury
+    const globalTreasuryExists = existsSync(GLOBAL_TREASURY_DIR);
+    let globalFileCount = 0;
+    if (globalTreasuryExists) {
+        try {
+            const files = await readdir(GLOBAL_TREASURY_DIR, { recursive: true });
+            globalFileCount = files.length;
+        }
+        catch { /* directory may be unreadable */ }
+    }
+    if (!globalTreasuryExists) {
+        warnings.push('No global treasury directory found. Nothing to archive.');
+    }
+    // Check daemon is not running
+    let daemonRunning = false;
+    const pidFile = join(homedir(), '.voidforge', 'run', 'heartbeat.pid');
+    if (existsSync(pidFile)) {
+        try {
+            const pid = parseInt(await readFile(pidFile, 'utf-8'), 10);
+            if (!isNaN(pid)) {
+                try {
+                    process.kill(pid, 0); // Check if process exists
+                    daemonRunning = true;
+                    errors.push(`Heartbeat daemon is running (PID ${pid}). Stop it before migrating.`);
+                }
+                catch {
+                    // PID file is stale — daemon not running
+                }
+            }
+        }
+        catch { /* can't read PID file */ }
+    }
+    // Also check per-project daemon
+    if (context) {
+        if (existsSync(context.pidFile)) {
+            try {
+                const pid = parseInt(await readFile(context.pidFile, 'utf-8'), 10);
+                if (!isNaN(pid)) {
+                    try {
+                        process.kill(pid, 0);
+                        daemonRunning = true;
+                        errors.push(`Per-project daemon is running (PID ${pid}). Stop it before migrating.`);
+                    }
+                    catch { /* stale */ }
+                }
+            }
+            catch { /* can't read */ }
+        }
+    }
+    // Check cultivation directory
+    let cultivationInstalled = false;
+    if (context) {
+        cultivationInstalled = existsSync(context.cultivationDir);
+        if (!cultivationInstalled) {
+            warnings.push('Cultivation not yet installed. Treasury directory will be created.');
+        }
+    }
+    // Check for existing migration
+    if (context && existsSync(join(context.treasuryDir, MIGRATION_MARKER))) {
+        errors.push('This project has already been migrated. Remove .migrated to force re-migration.');
+    }
+    return {
+        projectId,
+        project,
+        context,
+        globalTreasuryDir: GLOBAL_TREASURY_DIR,
+        globalTreasuryExists,
+        globalFileCount,
+        cultivationInstalled,
+        daemonRunning,
+        errors,
+        warnings,
+    };
+}
+// ── Migration ────────────────────────────────────────────
+/**
+ * Execute treasury migration for a project.
+ *
+ * Steps:
+ * 1. Archive global treasury to ~/.voidforge/treasury-pre-v22/
+ * 2. Create per-project cultivation/treasury/ with genesis files
+ * 3. Write migration manifest
+ * 4. Set 0700 permissions on treasury directory
+ * 5. Validate hash chains in archived logs
+ */
+export async function migrateTreasury(context) {
+    const now = new Date().toISOString();
+    // Step 1: Archive global treasury (if it exists and hasn't been archived)
+    let sourceFileCount = 0;
+    if (existsSync(GLOBAL_TREASURY_DIR) && !existsSync(GLOBAL_ARCHIVE_DIR)) {
+        await rename(GLOBAL_TREASURY_DIR, GLOBAL_ARCHIVE_DIR);
+        try {
+            const files = await readdir(GLOBAL_ARCHIVE_DIR, { recursive: true });
+            sourceFileCount = files.length;
+        }
+        catch { /* count is best-effort */ }
+    }
+    else if (existsSync(GLOBAL_ARCHIVE_DIR)) {
+        // Already archived from a previous migration — count existing archive
+        try {
+            const files = await readdir(GLOBAL_ARCHIVE_DIR, { recursive: true });
+            sourceFileCount = files.length;
+        }
+        catch { /* count is best-effort */ }
+    }
+    // Step 2: Create per-project treasury directory structure
+    const treasuryDir = context.treasuryDir;
+    await mkdir(treasuryDir, { recursive: true });
+    await mkdir(join(treasuryDir, 'campaigns'), { recursive: true });
+    await mkdir(join(treasuryDir, 'reconciliation'), { recursive: true });
+    await mkdir(join(treasuryDir, 'reports'), { recursive: true });
+    // Genesis files — clean break, no copy (ADR-041 decision)
+    // Per-project logs start with hash '0' — the genesis hash
+    const genesisFiles = ['spend-log.jsonl', 'revenue-log.jsonl', 'pending-ops.jsonl'];
+    for (const file of genesisFiles) {
+        const filePath = join(treasuryDir, file);
+        if (!existsSync(filePath)) {
+            await writeFile(filePath, '', 'utf-8');
+        }
+    }
+    // Create empty budgets.json if it doesn't exist
+    const budgetsPath = join(treasuryDir, 'budgets.json');
+    if (!existsSync(budgetsPath)) {
+        await writeFile(budgetsPath, JSON.stringify({ totalBudgetCents: 0, allocations: [] }), 'utf-8');
+    }
+    // Step 3: Validate hash chains in archived logs (informational)
+    const spendLogStats = await validateArchivedLog(join(GLOBAL_ARCHIVE_DIR, 'spend-log.jsonl'));
+    const revenueLogStats = await validateArchivedLog(join(GLOBAL_ARCHIVE_DIR, 'revenue-log.jsonl'));
+    // Step 4: Set 0700 permissions on treasury directory
+    await chmod(treasuryDir, 0o700);
+    // Step 5: Write migration manifest
+    const manifest = {
+        version: '22.1',
+        migratedAt: now,
+        projectId: context.id,
+        projectName: context.name,
+        projectDir: context.directory,
+        sourceDir: GLOBAL_ARCHIVE_DIR,
+        archiveDir: GLOBAL_ARCHIVE_DIR,
+        sourceFileCount,
+        spendLogEntries: spendLogStats.entryCount,
+        revenueLogEntries: revenueLogStats.entryCount,
+        spendLogHashValid: spendLogStats.valid,
+        revenueLogHashValid: revenueLogStats.valid,
+    };
+    await writeFile(join(treasuryDir, MIGRATION_MARKER), JSON.stringify(manifest, null, 2), 'utf-8');
+    return {
+        success: true,
+        manifest,
+        archiveDir: GLOBAL_ARCHIVE_DIR,
+        treasuryDir,
+    };
+}
+async function validateArchivedLog(logPath) {
+    if (!existsSync(logPath)) {
+        return { entryCount: 0, valid: true };
+    }
+    try {
+        const raw = await readFile(logPath, 'utf-8');
+        const lines = raw.trim().split('\n').filter(Boolean);
+        const entries = [];
+        for (const line of lines) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch {
+                // Non-JSON line — chain is broken
+                return { entryCount: lines.length, valid: false, brokenAt: entries.length };
+            }
+        }
+        if (entries.length === 0) {
+            return { entryCount: 0, valid: true };
+        }
+        const result = verifyChain(entries);
+        return {
+            entryCount: entries.length,
+            valid: result.valid,
+            brokenAt: result.brokenAt,
+        };
+    }
+    catch {
+        return { entryCount: 0, valid: false };
+    }
+}

package/dist/wizard/lib/treasury-reader.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Treasury Reader — Shared read-only functions for treasury data.
+ *
+ * Extracted from danger-room.ts heartbeat endpoint (ADR-041 M0.3).
+ * Reads treasury files from a given directory path. Used by both the
+ * Danger Room API and the Lobby aggregation endpoint.
+ *
+ * This module is READ-ONLY. The heartbeat daemon is the single writer (ADR-1).
+ */
+export interface TreasurySummary {
+    revenue: number;
+    spend: number;
+    net: number;
+    roas: number;
+    budgetRemaining: number;
+    stablecoinBalance: number | null;
+    pendingOfframps: number;
+    bankAvailable: number | null;
+    bankReserved: number | null;
+    runwayDays: number | null;
+    fundingState: string | null;
+    nextTreasuryEvent: string | null;
+    unsettledInvoices: number;
+    reconciliationStatus: string | null;
+}
+export interface HeartbeatSnapshot {
+    cultivationInstalled: boolean;
+    heartbeat: unknown;
+    campaigns: unknown[];
+    treasury: TreasurySummary;
+}
+/**
+ * Read full heartbeat snapshot from a treasury directory.
+ *
+ * @param treasuryDir — Path to treasury directory (e.g., project/cultivation/treasury/)
+ * @param stateFilePath — Path to heartbeat.json state file
+ * @param vaultCheckPath — Path to vault.enc (used to detect cultivation installation)
+ */
+export declare function readHeartbeatSnapshot(treasuryDir: string, stateFilePath: string, vaultCheckPath: string): Promise<HeartbeatSnapshot>;
+/** Filename for the cached summary written by the daemon (v22.1 M2). */
+export declare const TREASURY_SUMMARY_FILE = "treasury-summary.json";
+/**
+ * Read treasury summary. Tries the O(1) cached summary file first (written by
+ * the heartbeat daemon after each financial operation). Falls back to O(n)
+ * JSONL log scan if the summary file doesn't exist or is unreadable.
+ */
+export declare function readTreasurySummary(treasuryDir: string, heartbeatData?: unknown): Promise<TreasurySummary>;
+/**
+ * O(n) JSONL log scan — the original read path before v22.1.
+ * Used as fallback when treasury-summary.json is unavailable.
+ */
+export declare function readTreasurySummaryFromLogs(treasuryDir: string, heartbeatData?: unknown): Promise<TreasurySummary>;

package/dist/wizard/lib/treasury-reader.js

@@ -0,0 +1,235 @@
+/**
+ * Treasury Reader — Shared read-only functions for treasury data.
+ *
+ * Extracted from danger-room.ts heartbeat endpoint (ADR-041 M0.3).
+ * Reads treasury files from a given directory path. Used by both the
+ * Danger Room API and the Lobby aggregation endpoint.
+ *
+ * This module is READ-ONLY. The heartbeat daemon is the single writer (ADR-1).
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFileOrNull } from './http-helpers.js';
+const EMPTY_TREASURY = {
+    revenue: 0, spend: 0, net: 0, roas: 0, budgetRemaining: 0,
+    stablecoinBalance: null, pendingOfframps: 0,
+    bankAvailable: null, bankReserved: null,
+    runwayDays: null, fundingState: null,
+    nextTreasuryEvent: null, unsettledInvoices: 0,
+    reconciliationStatus: null,
+};
+// ── Readers ──────────────────────────────────────────
+/**
+ * Read full heartbeat snapshot from a treasury directory.
+ *
+ * @param treasuryDir — Path to treasury directory (e.g., project/cultivation/treasury/)
+ * @param stateFilePath — Path to heartbeat.json state file
+ * @param vaultCheckPath — Path to vault.enc (used to detect cultivation installation)
+ */
+export async function readHeartbeatSnapshot(treasuryDir, stateFilePath, vaultCheckPath) {
+    let cultivationInstalled = false;
+    let heartbeatData = null;
+    try {
+        cultivationInstalled = existsSync(vaultCheckPath);
+        const raw = await readFileOrNull(stateFilePath);
+        if (raw)
+            heartbeatData = JSON.parse(raw);
+    }
+    catch { /* no heartbeat data */ }
+    const campaigns = await readCampaigns(join(treasuryDir, 'campaigns'));
+    const treasury = await readTreasurySummary(treasuryDir, heartbeatData);
+    return { cultivationInstalled, heartbeat: heartbeatData, campaigns, treasury };
+}
+/** Read campaign JSON files from a campaigns directory. */
+async function readCampaigns(campaignsDir) {
+    const campaigns = [];
+    try {
+        if (!existsSync(campaignsDir))
+            return campaigns;
+        const files = await readdir(campaignsDir);
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const content = await readFile(join(campaignsDir, file), 'utf-8');
+                campaigns.push(JSON.parse(content));
+            }
+            catch { /* skip malformed campaign files */ }
+        }
+    }
+    catch { /* no campaigns directory */ }
+    return campaigns;
+}
+/** Filename for the cached summary written by the daemon (v22.1 M2). */
+export const TREASURY_SUMMARY_FILE = 'treasury-summary.json';
+/**
+ * Read treasury summary. Tries the O(1) cached summary file first (written by
+ * the heartbeat daemon after each financial operation). Falls back to O(n)
+ * JSONL log scan if the summary file doesn't exist or is unreadable.
+ */
+export async function readTreasurySummary(treasuryDir, heartbeatData) {
+    // O(1) path: read cached summary (written by daemon — ADR-1 single writer)
+    const summaryPath = join(treasuryDir, TREASURY_SUMMARY_FILE);
+    try {
+        if (existsSync(summaryPath)) {
+            const raw = await readFile(summaryPath, 'utf-8');
+            const cached = JSON.parse(raw);
+            // Validate it has the required shape (at minimum, spend + revenue)
+            if (typeof cached.spend === 'number' && typeof cached.revenue === 'number') {
+                return {
+                    revenue: cached.revenue,
+                    spend: cached.spend,
+                    net: cached.net ?? cached.revenue - cached.spend,
+                    roas: cached.roas ?? (cached.spend > 0 ? cached.revenue / cached.spend : 0),
+                    budgetRemaining: cached.budgetRemaining ?? 0,
+                    stablecoinBalance: cached.stablecoinBalance ?? null,
+                    pendingOfframps: cached.pendingOfframps ?? 0,
+                    bankAvailable: cached.bankAvailable ?? null,
+                    bankReserved: cached.bankReserved ?? null,
+                    runwayDays: cached.runwayDays ?? null,
+                    fundingState: cached.fundingState ?? null,
+                    nextTreasuryEvent: cached.nextTreasuryEvent ?? null,
+                    unsettledInvoices: cached.unsettledInvoices ?? 0,
+                    reconciliationStatus: cached.reconciliationStatus ?? null,
+                };
+            }
+        }
+    }
+    catch { /* summary file missing or corrupt — fall through to JSONL scan */ }
+    // O(n) fallback: scan JSONL logs directly
+    return readTreasurySummaryFromLogs(treasuryDir, heartbeatData);
+}
+/**
+ * O(n) JSONL log scan — the original read path before v22.1.
+ * Used as fallback when treasury-summary.json is unavailable.
+ */
+export async function readTreasurySummaryFromLogs(treasuryDir, heartbeatData) {
+    try {
+        const spendLogPath = join(treasuryDir, 'spend-log.jsonl');
+        const revenueLogPath = join(treasuryDir, 'revenue-log.jsonl');
+        let totalSpendCents = 0;
+        let totalRevenueCents = 0;
+        if (existsSync(spendLogPath)) {
+            const lines = (await readFile(spendLogPath, 'utf-8')).trim().split('\n').filter(Boolean);
+            for (const line of lines) {
+                try {
+                    const entry = JSON.parse(line);
+                    totalSpendCents += Math.max(0, entry.amountCents ?? 0);
+                }
+                catch { /* skip malformed lines */ }
+            }
+        }
+        if (existsSync(revenueLogPath)) {
+            const lines = (await readFile(revenueLogPath, 'utf-8')).trim().split('\n').filter(Boolean);
+            for (const line of lines) {
+                try {
+                    const entry = JSON.parse(line);
+                    totalRevenueCents += entry.amountCents ?? 0;
+                }
+                catch { /* skip malformed lines */ }
+            }
+        }
+        const net = totalRevenueCents - totalSpendCents;
+        const roas = totalSpendCents > 0 ? totalRevenueCents / totalSpendCents : 0;
+        let budgetRemaining = 0;
+        const budgetsFile = join(treasuryDir, 'budgets.json');
+        if (existsSync(budgetsFile)) {
+            try {
+                const budgetData = JSON.parse(await readFile(budgetsFile, 'utf-8'));
+                budgetRemaining = (budgetData.totalBudgetCents ?? 0) - totalSpendCents;
+            }
+            catch { /* skip malformed budgets */ }
+        }
+        // ── Stablecoin funding data ──
+        let stablecoinBalance = null;
+        let pendingOfframps = 0;
+        let bankAvailable = null;
+        let bankReserved = null;
+        let runwayDays = null;
+        let fundingState = null;
+        let nextTreasuryEvent = null;
+        let unsettledInvoices = 0;
+        let reconciliationStatus = null;
+        const fundingConfigPath = join(treasuryDir, 'funding-config.json.enc');
+        if (existsSync(fundingConfigPath) && heartbeatData) {
+            const hb = heartbeatData;
+            if (typeof hb.stablecoinBalanceCents === 'number')
+                stablecoinBalance = hb.stablecoinBalanceCents;
+            if (typeof hb.bankAvailableCents === 'number')
+                bankAvailable = hb.bankAvailableCents;
+            if (typeof hb.bankReservedCents === 'number')
+                bankReserved = hb.bankReservedCents;
+            if (typeof hb.runwayDays === 'number')
+                runwayDays = hb.runwayDays;
+            if (typeof hb.fundingState === 'string')
+                fundingState = hb.fundingState;
+            if (typeof hb.nextTreasuryEvent === 'string')
+                nextTreasuryEvent = hb.nextTreasuryEvent;
+        }
+        const fundingPlansLog = join(treasuryDir, 'funding-plans.jsonl');
+        if (existsSync(fundingPlansLog)) {
+            try {
+                const lines = (await readFile(fundingPlansLog, 'utf-8')).trim().split('\n').filter(Boolean);
+                for (const line of lines) {
+                    try {
+                        const plan = JSON.parse(line);
+                        if (plan.status === 'PENDING_SETTLEMENT' || plan.status === 'APPROVED')
+                            unsettledInvoices++;
+                    }
+                    catch { /* skip malformed lines */ }
+                }
+            }
+            catch { /* skip read errors */ }
+        }
+        const transfersLog = join(treasuryDir, 'transfers.jsonl');
+        if (existsSync(transfersLog)) {
+            try {
+                const lines = (await readFile(transfersLog, 'utf-8')).trim().split('\n').filter(Boolean);
+                for (const line of lines) {
+                    try {
+                        const transfer = JSON.parse(line);
+                        if ((transfer.status === 'pending' || transfer.status === 'processing')
+                            && transfer.direction === 'crypto_to_fiat')
+                            pendingOfframps++;
+                    }
+                    catch { /* skip malformed lines */ }
+                }
+            }
+            catch { /* skip read errors */ }
+        }
+        const reconciliationLog = join(treasuryDir, 'reconciliation.jsonl');
+        if (existsSync(reconciliationLog)) {
+            try {
+                const lines = (await readFile(reconciliationLog, 'utf-8')).trim().split('\n').filter(Boolean);
+                if (lines.length > 0) {
+                    const last = JSON.parse(lines[lines.length - 1]);
+                    if (last.result === 'MATCHED' || last.result === 'WITHIN_THRESHOLD')
+                        reconciliationStatus = 'matched';
+                    else if (last.result === 'MISMATCH')
+                        reconciliationStatus = 'mismatch';
+                }
+            }
+            catch { /* skip read errors */ }
+        }
+        if (fundingState === null && (stablecoinBalance !== null || bankAvailable !== null)) {
+            if (runwayDays !== null && runwayDays < 3)
+                fundingState = 'frozen';
+            else if (runwayDays !== null && runwayDays < 7)
+                fundingState = 'degraded';
+            else
+                fundingState = 'healthy';
+        }
+        return {
+            revenue: totalRevenueCents, spend: totalSpendCents, net, roas, budgetRemaining,
+            stablecoinBalance, pendingOfframps,
+            bankAvailable, bankReserved,
+            runwayDays, fundingState,
+            nextTreasuryEvent, unsettledInvoices,
+            reconciliationStatus,
+        };
+    }
+    catch {
+        return { ...EMPTY_TREASURY };
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Update mechanisms — methodology update (replaces /void git-fetch),
+ * self-update, and extension update.
+ */
+export interface UpdatePlan {
+    added: string[];
+    modified: string[];
+    removed: string[];
+    unchanged: number;
+}
+export interface UpdateResult {
+    applied: boolean;
+    plan: UpdatePlan;
+    newVersion: string;
+}
+/**
+ * Diff methodology source against project files.
+ * Returns a plan showing what would change.
+ */
+export declare function diffMethodology(projectDir: string): Promise<UpdatePlan>;
+/**
+ * Apply the update plan — copy new/modified files from source to project.
+ * Does NOT delete removed files (user may have customizations).
+ */
+export declare function applyUpdate(projectDir: string): Promise<UpdateResult>;
+export declare function selfUpdate(): {
+    success: boolean;
+    message: string;
+};