thevoidforge 21.0.0

package/dist/wizard/lib/extensions.js

@@ -0,0 +1,183 @@
+/**
+ * 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.
+ */
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readMarker, writeMarker } from './marker.js';
+const extensions = new Map();
+export function getExtension(name) {
+    return extensions.get(name);
+}
+export function listExtensions() {
+    return Array.from(extensions.values());
+}
+// ── Install / Uninstall ──────────────────────────────────
+export async function installExtension(projectDir, name) {
+    const ext = getExtension(name);
+    if (!ext) {
+        throw new Error(`Unknown extension: ${name}. Available: ${listExtensions().map(e => e.name).join(', ')}`);
+    }
+    const marker = await readMarker(projectDir);
+    if (!marker) {
+        throw new Error('Not a VoidForge project — no .voidforge marker found.');
+    }
+    if (marker.extensions.includes(name)) {
+        throw new Error(`Extension "${name}" is already installed.`);
+    }
+    const filesCreated = await ext.install(projectDir);
+    // Register in marker
+    marker.extensions.push(name);
+    await writeMarker(projectDir, marker);
+    return { filesCreated };
+}
+export async function uninstallExtension(projectDir, name) {
+    const ext = getExtension(name);
+    if (!ext) {
+        throw new Error(`Unknown extension: ${name}.`);
+    }
+    const marker = await readMarker(projectDir);
+    if (!marker) {
+        throw new Error('Not a VoidForge project — no .voidforge marker found.');
+    }
+    if (!marker.extensions.includes(name)) {
+        throw new Error(`Extension "${name}" is not installed.`);
+    }
+    await ext.uninstall(projectDir);
+    // Deregister from marker
+    marker.extensions = marker.extensions.filter(e => e !== name);
+    await writeMarker(projectDir, marker);
+}
+// ── Danger Room Extension ────────────────────────────────
+const DANGER_ROOM_CONFIG = {
+    refreshIntervalMs: 30000,
+    panels: {
+        heartbeat: { enabled: true },
+        campaigns: { enabled: true },
+        treasury: { enabled: true },
+        deployments: { enabled: true },
+    },
+    alerts: {
+        spendThresholdCents: 100_00,
+        errorRateThreshold: 0.05,
+    },
+};
+extensions.set('danger-room', {
+    name: 'danger-room',
+    description: 'Operations dashboard — heartbeat grid, campaigns, treasury, deployments',
+    async install(projectDir) {
+        const configPath = join(projectDir, 'danger-room.config.json');
+        await writeFile(configPath, JSON.stringify(DANGER_ROOM_CONFIG, null, 2) + '\n', 'utf-8');
+        return 1;
+    },
+    async uninstall(projectDir) {
+        const configPath = join(projectDir, 'danger-room.config.json');
+        if (existsSync(configPath)) {
+            await rm(configPath);
+        }
+    },
+});
+// ── Cultivation Extension ────────────────────────────────
+const CULTIVATION_JOBS = [
+    'token-refresh',
+    'spend-check',
+    'campaign-status',
+    'reconciliation',
+    'ab-evaluation',
+    'revenue-ingest',
+    'budget-rebalance',
+    'anomaly-scan',
+    'report-generation',
+    'platform-health',
+    'creative-rotation',
+    'audience-refresh',
+];
+function jobTemplate(jobName) {
+    const camelName = jobName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    return `/**
+ * ${jobName} — thin wrapper importing from the VoidForge wizard.
+ *
+ * This file is a project-local entry point for the heartbeat daemon.
+ * The actual implementation lives in the globally-installed wizard.
+ */
+
+import type { HeartbeatJob } from 'voidforge/wizard/lib/daemon-core.js';
+
+export const job: HeartbeatJob = {
+  name: '${jobName}',
+  async execute(context) {
+    const { ${camelName} } = await import('voidforge/wizard/lib/heartbeat.js');
+    return ${camelName}(context);
+  },
+};
+`;
+}
+const HEARTBEAT_CONFIG = {
+    schedules: {
+        'token-refresh': { intervalMs: 3600000, enabled: true },
+        'spend-check': { intervalMs: 300000, enabled: true },
+        'campaign-status': { intervalMs: 600000, enabled: true },
+        'reconciliation': { intervalMs: 86400000, enabled: true },
+        'ab-evaluation': { intervalMs: 3600000, enabled: true },
+        'revenue-ingest': { intervalMs: 3600000, enabled: true },
+        'budget-rebalance': { intervalMs: 86400000, enabled: true },
+        'anomaly-scan': { intervalMs: 1800000, enabled: true },
+        'report-generation': { intervalMs: 86400000, enabled: false },
+        'platform-health': { intervalMs: 300000, enabled: true },
+        'creative-rotation': { intervalMs: 86400000, enabled: false },
+        'audience-refresh': { intervalMs: 86400000, enabled: false },
+    },
+    circuitBreakers: {
+        maxConsecutiveFailures: 3,
+        cooldownMs: 300000,
+        resetAfterMs: 3600000,
+    },
+    platforms: [],
+};
+const CULTIVATION_GITIGNORE = `# Runtime state — never committed
+treasury/spend-log.jsonl
+treasury/revenue-log.jsonl
+treasury/campaigns/
+treasury/*.json
+heartbeat.pid
+heartbeat.sock
+`;
+extensions.set('cultivation', {
+    name: 'cultivation',
+    description: 'Growth engine — ad platforms, treasury, heartbeat daemon, A/B testing',
+    async install(projectDir) {
+        const cultDir = join(projectDir, 'cultivation');
+        const jobsDir = join(cultDir, 'jobs');
+        const treasuryDir = join(cultDir, 'treasury');
+        const campaignsDir = join(treasuryDir, 'campaigns');
+        await mkdir(jobsDir, { recursive: true });
+        await mkdir(campaignsDir, { recursive: true });
+        let count = 0;
+        // Config
+        await writeFile(join(cultDir, 'heartbeat.config.json'), JSON.stringify(HEARTBEAT_CONFIG, null, 2) + '\n', 'utf-8');
+        count++;
+        // Job files
+        for (const jobName of CULTIVATION_JOBS) {
+            await writeFile(join(jobsDir, `${jobName}.ts`), jobTemplate(jobName), 'utf-8');
+            count++;
+        }
+        // .gitignore
+        await writeFile(join(cultDir, '.gitignore'), CULTIVATION_GITIGNORE, 'utf-8');
+        count++;
+        return count;
+    },
+    async uninstall(projectDir) {
+        const cultDir = join(projectDir, 'cultivation');
+        if (existsSync(cultDir)) {
+            await rm(cultDir, { recursive: true, force: true });
+        }
+        // Clean up PID/socket if running
+        const pidFile = join(projectDir, '.voidforge', 'heartbeat.pid');
+        if (existsSync(pidFile)) {
+            await rm(pidFile);
+        }
+    },
+});

package/dist/wizard/lib/financial/adapter-factory.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Adapter Factory — config-driven adapter instantiation.
+ *
+ * Reads funding-config from the financial vault and returns the correct
+ * adapter (real or sandbox) based on what the user configured during
+ * the interactive setup wizard.
+ *
+ * This eliminates the hard-coded SandboxStablecoinAdapter in the daemon.
+ * Each factory function:
+ *   1. If vaultKey is null → sandbox adapter (no vault access)
+ *   2. Reads funding-config from vault → determines provider
+ *   3. Reads provider API key from vault → instantiates real adapter
+ *   4. If API key missing → logs warning, falls back to sandbox
+ *
+ * PRD Reference: §12.1, §12.2, §12.3
+ * No Stubs Doctrine: every code path returns a working adapter instance.
+ */
+import type { StablecoinAdapter } from './stablecoin/base.js';
+import type { RevenueSourceAdapter } from '../revenue-types.js';
+import type { AdBillingAdapter, AdPlatform } from './billing/base.js';
+import type { AdPlatformAdapter } from './campaign/base.js';
+/** Minimal logger — matches the daemon Logger interface. */
+interface FactoryLogger {
+    log(message: string): void;
+}
+/**
+ * Returns a StablecoinAdapter: CircleAdapter if configured with credentials,
+ * otherwise SandboxStablecoinAdapter.
+ */
+export declare function getStablecoinAdapter(vaultKey: string | null, logger?: FactoryLogger): Promise<StablecoinAdapter>;
+/**
+ * Returns a RevenueSourceAdapter for bank operations: MercuryBankAdapter
+ * if configured with credentials, otherwise SandboxBankAdapter.
+ */
+export declare function getBankAdapter(vaultKey: string | null, logger?: FactoryLogger): Promise<RevenueSourceAdapter>;
+/**
+ * Returns an AdBillingAdapter for the given platform, or null if not configured.
+ * Platform credentials are read from the financial vault.
+ */
+export declare function getBillingAdapter(platform: AdPlatform, vaultKey: string | null, logger?: FactoryLogger): Promise<AdBillingAdapter | null>;
+/**
+ * Returns an AdPlatformAdapter for campaign CRUD on the given platform.
+ * If credentials are missing or platform is unrecognized, returns a cached
+ * SandboxCampaignAdapter (one per platform, so campaign state persists).
+ */
+export declare function getCampaignAdapter(platform: AdPlatform, vaultKey: string | null, logger?: FactoryLogger): Promise<AdPlatformAdapter>;
+export {};

package/dist/wizard/lib/financial/adapter-factory.js

@@ -0,0 +1,225 @@
+/**
+ * Adapter Factory — config-driven adapter instantiation.
+ *
+ * Reads funding-config from the financial vault and returns the correct
+ * adapter (real or sandbox) based on what the user configured during
+ * the interactive setup wizard.
+ *
+ * This eliminates the hard-coded SandboxStablecoinAdapter in the daemon.
+ * Each factory function:
+ *   1. If vaultKey is null → sandbox adapter (no vault access)
+ *   2. Reads funding-config from vault → determines provider
+ *   3. Reads provider API key from vault → instantiates real adapter
+ *   4. If API key missing → logs warning, falls back to sandbox
+ *
+ * PRD Reference: §12.1, §12.2, §12.3
+ * No Stubs Doctrine: every code path returns a working adapter instance.
+ */
+import { financialVaultGet } from '../financial-vault.js';
+import { SandboxStablecoinAdapter } from './stablecoin/sandbox-stablecoin.js';
+import { SandboxBankAdapter } from '../adapters/sandbox-bank.js';
+import { SandboxCampaignAdapter } from './campaign/sandbox-campaign.js';
+const noopLogger = { log() { } };
+// ── Config Reader ────────────────────────────────────
+async function readFundingConfig(vaultKey) {
+    const raw = await financialVaultGet(vaultKey, 'funding-config');
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Stablecoin Adapter Factory ───────────────────────
+/**
+ * Returns a StablecoinAdapter: CircleAdapter if configured with credentials,
+ * otherwise SandboxStablecoinAdapter.
+ */
+export async function getStablecoinAdapter(vaultKey, logger = noopLogger) {
+    if (!vaultKey) {
+        logger.log('Adapter factory: no vault key — using sandbox stablecoin adapter');
+        return new SandboxStablecoinAdapter();
+    }
+    try {
+        const config = await readFundingConfig(vaultKey);
+        if (!config || config.stablecoinProvider === 'sandbox') {
+            logger.log('Adapter factory: funding config specifies sandbox stablecoin');
+            return new SandboxStablecoinAdapter();
+        }
+        if (config.stablecoinProvider === 'circle') {
+            const apiKey = await financialVaultGet(vaultKey, 'circle-api-key');
+            if (!apiKey) {
+                logger.log('Adapter factory: circle-api-key not found in vault — falling back to sandbox');
+                return new SandboxStablecoinAdapter();
+            }
+            const bankId = config.circleBankId ?? '';
+            if (!bankId) {
+                logger.log('Adapter factory: circleBankId missing in funding config — falling back to sandbox');
+                return new SandboxStablecoinAdapter();
+            }
+            const { CircleAdapter } = await import('./stablecoin/circle.js');
+            logger.log('Adapter factory: using Circle stablecoin adapter');
+            return new CircleAdapter({ apiKey, bankId });
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        logger.log(`Adapter factory: stablecoin adapter creation failed (${msg}) — falling back to sandbox`);
+    }
+    return new SandboxStablecoinAdapter();
+}
+// ── Bank Adapter Factory ─────────────────────────────
+/**
+ * Returns a RevenueSourceAdapter for bank operations: MercuryBankAdapter
+ * if configured with credentials, otherwise SandboxBankAdapter.
+ */
+export async function getBankAdapter(vaultKey, logger = noopLogger) {
+    if (!vaultKey) {
+        logger.log('Adapter factory: no vault key — using sandbox bank adapter');
+        return new SandboxBankAdapter('Sandbox Bank');
+    }
+    try {
+        const config = await readFundingConfig(vaultKey);
+        if (!config || config.bankProvider === 'sandbox') {
+            logger.log('Adapter factory: funding config specifies sandbox bank');
+            return new SandboxBankAdapter('Sandbox Bank');
+        }
+        if (config.bankProvider === 'mercury') {
+            const apiKey = await financialVaultGet(vaultKey, 'mercury-api-key');
+            if (!apiKey) {
+                logger.log('Adapter factory: mercury-api-key not found in vault — falling back to sandbox');
+                return new SandboxBankAdapter('Sandbox Bank');
+            }
+            const { MercuryBankAdapter } = await import('./stablecoin/mercury.js');
+            logger.log('Adapter factory: using Mercury bank adapter');
+            return new MercuryBankAdapter(apiKey, config.mercuryAccountId);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        logger.log(`Adapter factory: bank adapter creation failed (${msg}) — falling back to sandbox`);
+    }
+    return new SandboxBankAdapter('Sandbox Bank');
+}
+// ── Billing Adapter Factory ──────────────────────────
+/**
+ * Returns an AdBillingAdapter for the given platform, or null if not configured.
+ * Platform credentials are read from the financial vault.
+ */
+export async function getBillingAdapter(platform, vaultKey, logger = noopLogger) {
+    if (!vaultKey) {
+        logger.log(`Adapter factory: no vault key — no ${platform} billing adapter`);
+        return null;
+    }
+    try {
+        if (platform === 'google') {
+            const accessToken = await financialVaultGet(vaultKey, 'google-ads-token');
+            const developerToken = await financialVaultGet(vaultKey, 'google-developer-token');
+            const customerId = await financialVaultGet(vaultKey, 'google-customer-id');
+            if (!accessToken || !developerToken || !customerId) {
+                logger.log('Adapter factory: Google Ads credentials incomplete — billing adapter unavailable');
+                return null;
+            }
+            const { GoogleBillingAdapter } = await import('./billing/google-billing.js');
+            logger.log('Adapter factory: using Google billing adapter');
+            return new GoogleBillingAdapter({ customerId, accessToken, developerToken });
+        }
+        if (platform === 'meta') {
+            const accessToken = await financialVaultGet(vaultKey, 'meta-access-token');
+            const adAccountId = await financialVaultGet(vaultKey, 'meta-ad-account-id');
+            if (!accessToken || !adAccountId) {
+                logger.log('Adapter factory: Meta Ads credentials incomplete — billing adapter unavailable');
+                return null;
+            }
+            const { MetaBillingAdapter } = await import('./billing/meta-billing.js');
+            logger.log('Adapter factory: using Meta billing adapter');
+            return new MetaBillingAdapter({ adAccountId, accessToken });
+        }
+        if (platform === 'tiktok') {
+            const accessToken = await financialVaultGet(vaultKey, 'tiktok-access-token');
+            const appId = await financialVaultGet(vaultKey, 'tiktok-app-id');
+            if (!accessToken || !appId) {
+                logger.log('Adapter factory: TikTok Ads credentials incomplete — billing adapter unavailable');
+                return null;
+            }
+            const { TikTokBillingAdapter } = await import('./billing/tiktok-billing.js');
+            logger.log('Adapter factory: using TikTok billing adapter');
+            return new TikTokBillingAdapter({ appId, accessToken });
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        logger.log(`Adapter factory: ${platform} billing adapter creation failed (${msg})`);
+    }
+    return null;
+}
+// ── Campaign Adapter Factory ────────────────────────
+/**
+ * Cached sandbox campaign adapters — one per platform.
+ * The sandbox adapter stores campaigns in memory; creating a new instance
+ * per call loses all campaign state between operations.
+ */
+const sandboxCampaignAdapters = new Map();
+function getSandboxCampaignAdapter(platform) {
+    let adapter = sandboxCampaignAdapters.get(platform);
+    if (!adapter) {
+        adapter = new SandboxCampaignAdapter(platform);
+        sandboxCampaignAdapters.set(platform, adapter);
+    }
+    return adapter;
+}
+/**
+ * Returns an AdPlatformAdapter for campaign CRUD on the given platform.
+ * If credentials are missing or platform is unrecognized, returns a cached
+ * SandboxCampaignAdapter (one per platform, so campaign state persists).
+ */
+export async function getCampaignAdapter(platform, vaultKey, logger = noopLogger) {
+    if (!vaultKey) {
+        logger.log(`Adapter factory: no vault key — using sandbox campaign adapter for ${platform}`);
+        return getSandboxCampaignAdapter(platform);
+    }
+    try {
+        if (platform === 'google') {
+            const accessToken = await financialVaultGet(vaultKey, 'google-ads-token');
+            const developerToken = await financialVaultGet(vaultKey, 'google-developer-token');
+            const customerId = await financialVaultGet(vaultKey, 'google-customer-id');
+            if (!accessToken || !developerToken || !customerId) {
+                logger.log('Adapter factory: Google Ads credentials incomplete — falling back to sandbox campaign adapter');
+                return getSandboxCampaignAdapter(platform);
+            }
+            const { GoogleCampaignAdapter } = await import('./campaign/google-campaign.js');
+            logger.log('Adapter factory: using Google campaign adapter');
+            return new GoogleCampaignAdapter({ customerId, accessToken, developerToken });
+        }
+        if (platform === 'meta') {
+            const accessToken = await financialVaultGet(vaultKey, 'meta-access-token');
+            const adAccountId = await financialVaultGet(vaultKey, 'meta-ad-account-id');
+            if (!accessToken || !adAccountId) {
+                logger.log('Adapter factory: Meta Ads credentials incomplete — falling back to sandbox campaign adapter');
+                return getSandboxCampaignAdapter(platform);
+            }
+            const { MetaCampaignAdapter } = await import('./campaign/meta-campaign.js');
+            logger.log('Adapter factory: using Meta campaign adapter');
+            return new MetaCampaignAdapter({ adAccountId, accessToken });
+        }
+        if (platform === 'tiktok') {
+            const accessToken = await financialVaultGet(vaultKey, 'tiktok-access-token');
+            const appId = await financialVaultGet(vaultKey, 'tiktok-app-id');
+            if (!accessToken || !appId) {
+                logger.log('Adapter factory: TikTok credentials incomplete — falling back to sandbox campaign adapter');
+                return getSandboxCampaignAdapter(platform);
+            }
+            const { TikTokCampaignAdapter } = await import('./campaign/tiktok-campaign.js');
+            logger.log('Adapter factory: using TikTok campaign adapter');
+            return new TikTokCampaignAdapter({ appId, accessToken });
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        logger.log(`Adapter factory: ${platform} campaign adapter creation failed (${msg}) — falling back to sandbox`);
+    }
+    logger.log(`Adapter factory: unrecognized platform '${platform}' — using sandbox campaign adapter`);
+    return getSandboxCampaignAdapter(platform);
+}

package/dist/wizard/lib/financial/billing/base.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Ad billing adapter types — re-exports from the pattern file.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export type { AdBillingSetup, AdBillingAdapter, CapabilityState, BillingMode, AdPlatform, Invoice, InvoiceLineItem, ExpectedDebit, SettlementInstruction, PlatformBillingProfile, BillingConfiguration, NormalizedFundingState, DateRange, Cents, } from '../../patterns/ad-billing-adapter.js';
+export { toCents } from '../../patterns/ad-billing-adapter.js';

package/dist/wizard/lib/financial/billing/base.js

@@ -0,0 +1 @@
+export { toCents } from '../../patterns/ad-billing-adapter.js';

package/dist/wizard/lib/financial/billing/google-billing.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Google Ads Billing Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdBillingSetup (interactive CLI) + AdBillingAdapter (daemon runtime)
+ * for Google Ads API v17.
+ *
+ * Google Ads API v17:
+ *   Base URL: https://googleads.googleapis.com/v17
+ *   Auth: Authorization: Bearer {accessToken} (OAuth2)
+ *   Also requires developer-token header for API access.
+ *
+ * Billing model: Monthly invoicing accounts receive invoices that must be paid
+ * via wire/ACH. Non-invoicing accounts are monitor-only (card or manual bank).
+ *
+ * PRD Reference: $10.2, $11.1B, $12.3
+ * No Stubs Doctrine: every method makes a real API call or returns documented empty.
+ */
+import type { AdBillingSetup, AdBillingAdapter, CapabilityState, BillingMode, AdPlatform, Invoice, ExpectedDebit, SettlementInstruction, PlatformBillingProfile, BillingConfiguration, NormalizedFundingState, DateRange, Cents } from './base.js';
+interface GoogleBillingConfig {
+    customerId: string;
+    accessToken: string;
+    developerToken: string;
+}
+export declare class GoogleBillingSetup implements AdBillingSetup {
+    private readonly developerToken;
+    constructor(developerToken: string);
+    verifyBillingCapability(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<CapabilityState>;
+    readBillingConfiguration(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingConfiguration>;
+    detectBillingMode(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingMode>;
+    /** Query billing_setup resource via Google Ads searchStream. */
+    private queryBillingSetup;
+}
+export declare class GoogleBillingAdapter implements AdBillingAdapter {
+    private readonly config;
+    private profile;
+    constructor(config: GoogleBillingConfig);
+    /** Set or update the billing profile (called by heartbeat after setup verification). */
+    setProfile(profile: PlatformBillingProfile): void;
+    getCapabilityState(_platform: AdPlatform): Promise<CapabilityState>;
+    readInvoices(_platform: AdPlatform, dateRange: DateRange): Promise<Invoice[]>;
+    readExpectedDebits(_platform: AdPlatform, _dateRange: DateRange): Promise<ExpectedDebit[]>;
+    generateSettlementInstructions(invoice: Invoice): Promise<SettlementInstruction>;
+    confirmSettlement(invoiceId: string, bankTransactionId: string): Promise<{
+        confirmed: boolean;
+        reconciledAmountCents: Cents;
+        varianceCents: Cents;
+    }>;
+    normalizeFundingState(): Promise<NormalizedFundingState[]>;
+}
+export {};