thevoidforge 21.0.0

package/dist/wizard/lib/patterns/ad-platform-adapter.js

@@ -0,0 +1,212 @@
+/**
+ * Pattern: Ad Platform Adapter (Split Interface)
+ *
+ * Key principles:
+ * - Separate interactive setup (browser OAuth) from runtime operations (daemon)
+ * - AdPlatformSetup runs in CLI/Danger Room (interactive, user-present)
+ * - AdPlatformAdapter runs in heartbeat daemon (non-interactive, autonomous)
+ * - All amounts in integer cents (Cents branded type) — never float
+ * - Rate limiting per-platform with token bucket
+ * - Errors normalized to common PlatformError format
+ * - Idempotency keys on all write operations (WAL pattern per ADR-3)
+ *
+ * Agents: Breeze (platform relations), Wax (paid ads), Dockson (treasury)
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ *
+ * Authorization Guard (§9.20.4):
+ *   Daemon Tier 1 jobs receive ReadOnlyAdapter (pause, read operations only).
+ *   Authenticated external commands receive full AdPlatformAdapter.
+ *   See financial-transaction.ts for the Cents branded type.
+ */
+function toCents(dollars) {
+    return Math.round(dollars * 100);
+}
+function toDollars(cents) {
+    return cents / 100;
+}
+// Authenticated external commands receive the full AdPlatformAdapter
+//
+// ── Adapter Caching Rule (field report #258) ────────────
+// Stateful adapters (in-memory campaign store, e.g. sandbox) MUST be cached
+// per platform — one instance per platform key. Creating a new instance per
+// call loses state between operations (campaigns created become invisible).
+// Stateless adapters (HTTP clients calling external APIs) can be created per
+// call since they hold no local state. Use a module-level Map<string, Adapter>
+// for caching when the adapter's constructor initializes mutable collections.
+// ── Reference Implementation: Meta Marketing API ──────
+class MetaAdapter {
+    adAccountId;
+    baseUrl = 'https://graph.facebook.com/v19.0';
+    rateLimiter;
+    constructor(adAccountId) {
+        this.adAccountId = adAccountId;
+        // Meta: 200 calls/hr/ad account (sliding window)
+        this.rateLimiter = new TokenBucketLimiter({ capacity: 200, refillRate: 200 / 3600 });
+    }
+    // ── Setup (interactive) ──────────
+    async authenticate() {
+        // 1. Open browser to Facebook Login
+        // 2. User authorizes → callback with short-lived token
+        // 3. Exchange for long-lived token (60 days)
+        // 4. Return OAuthTokens
+        throw new Error('Interactive OAuth — implement per platform');
+    }
+    async verifyConnection(tokens) {
+        const res = await this.apiCall('GET', `/act_${this.adAccountId}`, tokens, {
+            fields: 'name,currency,account_status'
+        });
+        return {
+            connected: true,
+            accountId: this.adAccountId,
+            accountName: res.name,
+            currency: res.currency,
+        };
+    }
+    async detectCurrency(tokens) {
+        const status = await this.verifyConnection(tokens);
+        return status.currency ?? 'USD';
+    }
+    // ── Runtime (daemon) ─────────────
+    async refreshToken(token) {
+        // Meta long-lived tokens: exchange at 80% of 60-day TTL
+        const res = await this.apiCall('GET', '/oauth/access_token', token, {
+            grant_type: 'fb_exchange_token',
+            fb_exchange_token: token.accessToken,
+        });
+        return { ...token, accessToken: res.access_token, expiresAt: res.expires_at };
+    }
+    async createCampaign(config) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('POST', `/act_${this.adAccountId}/campaigns`, undefined, {
+            name: config.name,
+            objective: this.mapObjective(config.objective),
+            status: 'PAUSED', // Create paused, activate after ad set + ad creation
+            special_ad_categories: [],
+        });
+        return {
+            externalId: res.id,
+            platform: 'meta',
+            status: 'created',
+            dashboardUrl: `https://www.facebook.com/adsmanager/manage/campaigns?act=${this.adAccountId}&campaign_ids=${res.id}`,
+        };
+    }
+    async pauseCampaign(id) {
+        await this.rateLimiter.acquire();
+        await this.apiCall('POST', `/${id}`, undefined, { status: 'PAUSED' });
+    }
+    async resumeCampaign(id) {
+        await this.rateLimiter.acquire();
+        await this.apiCall('POST', `/${id}`, undefined, { status: 'ACTIVE' });
+    }
+    async deleteCampaign(id) {
+        await this.rateLimiter.acquire();
+        await this.apiCall('DELETE', `/${id}`, undefined, {});
+    }
+    async updateCampaign(id, changes) {
+        await this.rateLimiter.acquire();
+        const params = {};
+        if (changes.name)
+            params.name = changes.name;
+        // Budget changes go through ad set, not campaign on Meta
+        await this.apiCall('POST', `/${id}`, undefined, params);
+    }
+    async updateBudget(id, dailyBudget) {
+        await this.rateLimiter.acquire();
+        // Meta budgets are in the account's currency smallest unit (cents for USD)
+        await this.apiCall('POST', `/${id}`, undefined, { daily_budget: dailyBudget });
+    }
+    async updateCreative(id, creative) {
+        await this.rateLimiter.acquire();
+        // Creative updates go through the ad object, not campaign
+        throw new Error('Creative update requires ad-level API call — implement per ad structure');
+    }
+    async getSpend(dateRange) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('GET', `/act_${this.adAccountId}/insights`, undefined, {
+            fields: 'campaign_id,spend,impressions,clicks,conversions',
+            time_range: JSON.stringify({ since: dateRange.start, until: dateRange.end }),
+            level: 'campaign',
+        });
+        const resData = res.data;
+        return {
+            platform: 'meta',
+            dateRange,
+            totalSpend: toCents(resData.reduce((sum, r) => sum + parseFloat(r.spend), 0)),
+            campaigns: resData.map((r) => ({
+                externalId: r.campaign_id,
+                spend: toCents(parseFloat(r.spend)),
+                impressions: parseInt(r.impressions),
+                clicks: parseInt(r.clicks),
+                conversions: parseInt(r.conversions || '0'),
+            })),
+        };
+    }
+    async getPerformance(campaignId) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('GET', `/${campaignId}/insights`, undefined, {
+            fields: 'impressions,clicks,conversions,spend,ctr,cpc',
+        });
+        const d = res.data[0];
+        const spend = toCents(parseFloat(d.spend));
+        const conversions = parseInt(d.conversions || '0');
+        const revenue = 0; // Revenue comes from Stripe, not the ad platform
+        return {
+            campaignId,
+            impressions: parseInt(d.impressions),
+            clicks: parseInt(d.clicks),
+            conversions,
+            spend,
+            ctr: parseFloat(d.ctr),
+            cpc: toCents(parseFloat(d.cpc)),
+            roas: (revenue > 0 ? toDollars(revenue) / toDollars(spend) : 0),
+        };
+    }
+    async getInsights(campaignId, metrics) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('GET', `/${campaignId}/insights`, undefined, {
+            fields: metrics.join(','),
+        });
+        return { campaignId, metrics: res.data[0] ?? {} };
+    }
+    // ── Helpers ──────────────────────
+    mapObjective(obj) {
+        const map = { awareness: 'OUTCOME_AWARENESS', traffic: 'OUTCOME_TRAFFIC', conversions: 'OUTCOME_SALES' };
+        return map[obj];
+    }
+    async apiCall(method, path, tokens, params) {
+        // Sanitize platform response data per §9.19.16
+        // All string fields: strip HTML tags, escape <>&"', truncate to 500 chars
+        // Use idempotency key for POST/DELETE per ADR-3
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+// ── Token Bucket Rate Limiter ─────────────────────────
+class TokenBucketLimiter {
+    tokens;
+    lastRefill;
+    capacity;
+    refillRate; // tokens per second
+    constructor(opts) {
+        this.capacity = opts.capacity;
+        this.refillRate = opts.refillRate;
+        this.tokens = opts.capacity;
+        this.lastRefill = Date.now();
+    }
+    async acquire() {
+        this.refill();
+        if (this.tokens < 1) {
+            const waitMs = (1 / this.refillRate) * 1000;
+            await new Promise(resolve => setTimeout(resolve, waitMs));
+            this.refill();
+        }
+        this.tokens -= 1;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000;
+        this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
+        this.lastRefill = now;
+    }
+}
+export { toCents, toDollars, MetaAdapter, TokenBucketLimiter };

package/dist/wizard/lib/patterns/daemon-process.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Pattern: Daemon Process (Heartbeat)
+ *
+ * Key principles:
+ * - PID file with flock to prevent concurrent instances
+ * - Unix domain socket for IPC (ADR-1: single writer)
+ * - Session token auth (rotated every 24 hours)
+ * - Graceful shutdown on SIGTERM (10s deadline)
+ * - Sleep/wake recovery with tiered catch-up
+ * - Core dumps disabled for processes holding vault keys
+ * - Log rotation: daily or at 10MB, retain 7 days
+ * - macOS: F_FULLFSYNC for financial files
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §9.7, §9.18, §9.19.2, §9.20.11
+ */
+import { createServer } from 'node:net';
+declare const PID_FILE: string;
+declare const SOCKET_PATH: string;
+declare const TOKEN_FILE: string;
+declare const STATE_FILE: string;
+declare const LOG_FILE: string;
+type DaemonState = 'starting' | 'healthy' | 'degraded' | 'recovering' | 'recovery_failed' | 'shutting_down' | 'stopped';
+interface HeartbeatState {
+    pid: number;
+    state: DaemonState;
+    startedAt: string;
+    lastHeartbeat: string;
+    lastEventId: number;
+    cultivationState: string;
+    activePlatforms: string[];
+    activeCampaigns: number;
+    todaySpend: number;
+    dailyBudget: number;
+    alerts: string[];
+    tokenHealth: Record<string, {
+        status: string;
+        expiresAt: string;
+    }>;
+    lastAgentMessage?: {
+        agent: string;
+        text: string;
+        timestamp: string;
+    };
+    stablecoinBalanceCents?: number;
+    bankBalanceCents?: number;
+    runwayDays?: number;
+    fundingFrozen?: boolean;
+    pendingTransferCount?: number;
+}
+declare function writePidFile(): Promise<void>;
+declare function checkStalePid(): Promise<boolean>;
+declare function removePidFile(): Promise<void>;
+declare function generateSessionToken(): Promise<string>;
+declare function validateToken(provided: string, expected: string): boolean;
+declare function createSocketServer(sessionToken: string, handleRequest: (method: string, path: string, body: unknown, auth: {
+    hasToken: boolean;
+    vaultPassword: string;
+    totpCode: string;
+}) => Promise<{
+    status: number;
+    body: unknown;
+}>): ReturnType<typeof createServer>;
+declare function startSocketServer(server: ReturnType<typeof createServer>): Promise<void>;
+declare function writeState(state: HeartbeatState): Promise<void>;
+declare function setupSignalHandlers(cleanup: () => Promise<void>, server: ReturnType<typeof createServer>): void;
+interface ScheduledJob {
+    name: string;
+    intervalMs: number;
+    handler: () => Promise<void>;
+    lastRun: number;
+}
+declare class JobScheduler {
+    private jobs;
+    private timer;
+    private lastTick;
+    add(name: string, intervalMs: number, handler: () => Promise<void>): void;
+    start(): void;
+    stop(): void;
+    private tick;
+}
+declare function createLogger(logPath: string): {
+    log: (msg: string) => void;
+    close: () => void;
+};
+export { writePidFile, checkStalePid, removePidFile, generateSessionToken, validateToken, createSocketServer, startSocketServer, writeState, setupSignalHandlers, JobScheduler, createLogger, PID_FILE, SOCKET_PATH, TOKEN_FILE, STATE_FILE, LOG_FILE, };
+export type { DaemonState, HeartbeatState, ScheduledJob };

package/dist/wizard/lib/patterns/daemon-process.js

@@ -0,0 +1,271 @@
+/**
+ * Pattern: Daemon Process (Heartbeat)
+ *
+ * Key principles:
+ * - PID file with flock to prevent concurrent instances
+ * - Unix domain socket for IPC (ADR-1: single writer)
+ * - Session token auth (rotated every 24 hours)
+ * - Graceful shutdown on SIGTERM (10s deadline)
+ * - Sleep/wake recovery with tiered catch-up
+ * - Core dumps disabled for processes holding vault keys
+ * - Log rotation: daily or at 10MB, retain 7 days
+ * - macOS: F_FULLFSYNC for financial files
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §9.7, §9.18, §9.19.2, §9.20.11
+ */
+import { createServer } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { readFile, unlink, mkdir, open, rename } from 'node:fs/promises';
+import { existsSync, createWriteStream } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+const VOIDFORGE_DIR = join(homedir(), '.voidforge');
+const RUN_DIR = join(VOIDFORGE_DIR, 'run');
+const PID_FILE = join(RUN_DIR, 'heartbeat.pid');
+const SOCKET_PATH = join(RUN_DIR, 'heartbeat.sock');
+const TOKEN_FILE = join(VOIDFORGE_DIR, 'heartbeat.token');
+const STATE_FILE = join(VOIDFORGE_DIR, 'heartbeat.json');
+const LOG_FILE = join(VOIDFORGE_DIR, 'heartbeat.log');
+// ── PID Management ────────────────────────────────────
+async function writePidFile() {
+    await mkdir(RUN_DIR, { recursive: true, mode: 0o700 });
+    const fh = await open(PID_FILE, 'w', 0o600);
+    try {
+        await fh.writeFile(String(process.pid));
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+}
+async function checkStalePid() {
+    if (!existsSync(PID_FILE))
+        return false;
+    try {
+        const pid = parseInt(await readFile(PID_FILE, 'utf-8'));
+        process.kill(pid, 0); // Check if process exists (throws if not)
+        return true; // Another daemon is alive
+    }
+    catch {
+        await unlink(PID_FILE).catch(() => { });
+        return false; // Stale PID — cleaned up
+    }
+}
+async function removePidFile() {
+    await unlink(PID_FILE).catch(() => { });
+}
+// ── Session Token ─────────────────────────────────────
+// Rotated every 24 hours (§9.19.15)
+async function generateSessionToken() {
+    const token = randomBytes(32).toString('hex');
+    await mkdir(RUN_DIR, { recursive: true, mode: 0o700 });
+    const tmpPath = TOKEN_FILE + '.tmp.' + process.pid;
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(token);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, TOKEN_FILE);
+    return token;
+}
+function validateToken(provided, expected) {
+    if (provided.length !== expected.length)
+        return false;
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    const { timingSafeEqual } = require('node:crypto');
+    return timingSafeEqual(a, b);
+}
+// ── Socket Server ─────────────────────────────────────
+// JSON-over-HTTP on Unix domain socket (§9.20.11)
+function createSocketServer(sessionToken, handleRequest) {
+    const MAX_REQUEST_SIZE = 1024 * 1024; // 1MB — R2-NIGHTWING-003: enforce during streaming
+    const server = createServer(async (conn) => {
+        let data = '';
+        let rejected = false;
+        conn.on('data', (chunk) => {
+            data += chunk.toString();
+            if (data.length > MAX_REQUEST_SIZE && !rejected) {
+                rejected = true;
+                conn.write('HTTP/1.1 413 Payload Too Large\r\nContent-Type: application/json\r\n\r\n{"ok":false,"error":"Request too large"}');
+                conn.end();
+            }
+        });
+        conn.on('end', async () => {
+            try {
+                // Parse HTTP-like request from the socket
+                const lines = data.split('\r\n');
+                const [method, path] = (lines[0] || 'GET /').split(' ');
+                // Extract auth headers — pass VALUES, not just presence (SEC-001 fix)
+                const authHeader = lines.find(l => l.toLowerCase().startsWith('authorization:'));
+                const token = authHeader ? authHeader.split(' ').pop() || '' : '';
+                const hasToken = validateToken(token, sessionToken);
+                const vaultHeader = lines.find(l => l.toLowerCase().startsWith('x-vault-password:'));
+                const vaultPassword = vaultHeader ? vaultHeader.substring(vaultHeader.indexOf(':') + 1).trim() : '';
+                const totpHeader = lines.find(l => l.toLowerCase().startsWith('x-totp-code:'));
+                const totpCode = totpHeader ? totpHeader.substring(totpHeader.indexOf(':') + 1).trim() : '';
+                // Parse body (after blank line)
+                const bodyStart = data.indexOf('\r\n\r\n');
+                if (rejected)
+                    return; // Already rejected during streaming
+                const body = bodyStart >= 0 ? JSON.parse(data.substring(bodyStart + 4) || '{}') : {};
+                const result = await handleRequest(method, path, body, {
+                    hasToken,
+                    vaultPassword, // Actual value for verification by handler
+                    totpCode, // Actual value for verification by handler
+                });
+                conn.write(`HTTP/1.1 ${result.status} OK\r\nContent-Type: application/json\r\n\r\n${JSON.stringify(result.body)}`);
+            }
+            catch (err) {
+                conn.write(`HTTP/1.1 500 Error\r\nContent-Type: application/json\r\n\r\n${JSON.stringify({ ok: false, error: 'Internal error' })}`);
+            }
+            conn.end();
+        });
+    });
+    return server;
+}
+async function startSocketServer(server) {
+    // Clean up stale socket
+    if (existsSync(SOCKET_PATH)) {
+        try {
+            const { connect } = require('node:net');
+            const testConn = connect(SOCKET_PATH);
+            await new Promise((resolve, reject) => {
+                testConn.on('connect', () => { testConn.destroy(); reject(new Error('Another daemon is running')); });
+                testConn.on('error', () => { resolve(); }); // ECONNREFUSED = stale socket
+            });
+            await unlink(SOCKET_PATH);
+        }
+        catch (err) {
+            if (err.message === 'Another daemon is running')
+                throw err;
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.listen(SOCKET_PATH, () => {
+            // Set socket permissions (§9.18)
+            require('node:fs').chmodSync(SOCKET_PATH, 0o600);
+            resolve();
+        });
+        server.on('error', reject);
+    });
+}
+// ── State File ────────────────────────────────────────
+async function writeState(state) {
+    const tmpPath = STATE_FILE + '.tmp.' + process.pid;
+    const fh = await open(tmpPath, 'w');
+    try {
+        await fh.writeFile(JSON.stringify(state, null, 2));
+        if (platform() === 'darwin') {
+            await fh.datasync(); // Best-effort on macOS; see §9.18 F_FULLFSYNC caveat
+        }
+        else {
+            await fh.sync();
+        }
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, STATE_FILE);
+}
+// ── Signal Handling ───────────────────────────────────
+function setupSignalHandlers(cleanup, server) {
+    let shuttingDown = false;
+    async function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        // 10-second deadline for in-flight requests
+        const deadline = setTimeout(() => {
+            process.exit(1);
+        }, 10000);
+        try {
+            server.close();
+            await cleanup();
+            await removePidFile();
+            await unlink(SOCKET_PATH).catch(() => { });
+            clearTimeout(deadline);
+            process.exit(0);
+        }
+        catch {
+            clearTimeout(deadline);
+            process.exit(1);
+        }
+    }
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    // Disable core dumps — vault key in memory (§9.18)
+    try {
+        // @ts-expect-error — setrlimit not in Node.js types
+        if (process.setrlimit)
+            process.setrlimit('core', { soft: 0, hard: 0 });
+    }
+    catch { /* not available on all platforms */ }
+}
+class JobScheduler {
+    jobs = [];
+    timer = null;
+    lastTick = Date.now();
+    add(name, intervalMs, handler) {
+        this.jobs.push({ name, intervalMs, handler, lastRun: 0 });
+    }
+    start() {
+        this.lastTick = Date.now();
+        this.timer = setInterval(() => this.tick(), 1000);
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+    }
+    async tick() {
+        const now = Date.now();
+        const delta = now - this.lastTick;
+        this.lastTick = now;
+        // Sleep/wake detection (§9.18): if delta > 2x expected (2s), catch-up mode
+        if (delta > 2000) {
+            // Stagger overdue jobs over 5 minutes, prioritize token refresh
+            const overdue = this.jobs.filter(j => now - j.lastRun > j.intervalMs);
+            const sorted = overdue.sort((a, b) => {
+                if (a.name.includes('token'))
+                    return -1;
+                if (b.name.includes('token'))
+                    return 1;
+                return 0;
+            });
+            for (const job of sorted) {
+                try {
+                    await job.handler();
+                }
+                catch { /* logged by handler */ }
+                job.lastRun = now;
+            }
+            return;
+        }
+        // Normal tick: run due jobs
+        for (const job of this.jobs) {
+            if (now - job.lastRun >= job.intervalMs) {
+                try {
+                    await job.handler();
+                }
+                catch { /* logged by handler */ }
+                job.lastRun = now;
+            }
+        }
+    }
+}
+// ── Log Rotation ──────────────────────────────────────
+function createLogger(logPath) {
+    let stream = createWriteStream(logPath, { flags: 'a' });
+    return {
+        log(msg) {
+            stream.write(JSON.stringify({ ts: new Date().toISOString(), msg }) + '\n');
+        },
+        close() { stream.end(); }
+    };
+}
+export { writePidFile, checkStalePid, removePidFile, generateSessionToken, validateToken, createSocketServer, startSocketServer, writeState, setupSignalHandlers, JobScheduler, createLogger, PID_FILE, SOCKET_PATH, TOKEN_FILE, STATE_FILE, LOG_FILE, };