thevoidforge 21.0.0

package/dist/wizard/lib/adapters/sandbox-bank.js

@@ -0,0 +1,77 @@
+/**
+ * Sandbox Bank Adapter — full implementation for development/demo.
+ *
+ * Implements RevenueSourceAdapter with realistic fake financial data.
+ * Every method returns valid-shaped data. No throws.
+ * This IS a full implementation for a sandbox bank (No Stubs Doctrine, v17.0).
+ */
+import { randomUUID } from 'node:crypto';
+export class SandboxBankAdapter {
+    accountName;
+    balanceCents;
+    constructor(label = 'Sandbox Bank', initialBalanceCents = 500000) {
+        this.accountName = label;
+        this.balanceCents = initialBalanceCents;
+    }
+    async connect(credentials) {
+        return {
+            connected: true,
+            accountName: this.accountName,
+            accountId: `sandbox_bank_${randomUUID().slice(0, 8)}`,
+            currency: 'USD',
+        };
+    }
+    async getTransactions(dateRange, cursor) {
+        // Generate realistic transaction data
+        const dayCount = Math.ceil((new Date(dateRange.end).getTime() - new Date(dateRange.start).getTime()) / (24 * 60 * 60 * 1000));
+        // Invalid date range (end before start) — return empty result
+        if (dayCount <= 0) {
+            return {
+                transactions: [],
+                hasMore: false,
+                cursor: undefined,
+            };
+        }
+        const transactions = [];
+        // Simulate 2-5 transactions per day
+        for (let d = 0; d < dayCount; d++) {
+            const date = new Date(new Date(dateRange.start).getTime() + d * 86400000);
+            const txCount = 2 + Math.floor(Math.random() * 4);
+            for (let t = 0; t < txCount; t++) {
+                const isRevenue = Math.random() > 0.4; // 60% revenue, 40% expenses
+                const amountCents = isRevenue
+                    ? Math.round(500 + Math.random() * 9500) // $5-$100 revenue
+                    : -Math.round(100 + Math.random() * 5000); // $1-$50 expenses
+                const descriptions = isRevenue
+                    ? ['Stripe payout', 'Customer payment', 'Subscription renewal', 'One-time purchase']
+                    : ['Ad spend - Google', 'Ad spend - Meta', 'SaaS subscription', 'Domain renewal', 'Hosting'];
+                transactions.push({
+                    externalId: `txn_${randomUUID().slice(0, 12)}`,
+                    type: isRevenue ? 'charge' : 'refund',
+                    amount: amountCents,
+                    currency: 'USD',
+                    description: descriptions[Math.floor(Math.random() * descriptions.length)],
+                    metadata: { sandbox: 'true', category: isRevenue ? 'revenue' : 'expense' },
+                    createdAt: date.toISOString(),
+                });
+            }
+        }
+        return {
+            transactions,
+            hasMore: false,
+            cursor: undefined,
+        };
+    }
+    async getBalance() {
+        // Slightly vary the balance to simulate real account activity
+        this.balanceCents += Math.round((Math.random() - 0.3) * 10000);
+        return {
+            available: this.balanceCents,
+            pending: Math.round(Math.random() * 50000),
+            currency: 'USD',
+        };
+    }
+    async detectCurrency(_credentials) {
+        return 'USD';
+    }
+}

package/dist/wizard/lib/adapters/sandbox.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Sandbox Ad Platform Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the AdPlatformSetup + AdPlatformAdapter
+ * interfaces. Every method returns valid-shaped data. No throws.
+ * This IS a full implementation for a sandbox platform (No Stubs Doctrine, v17.0).
+ *
+ * Use case: demonstrates the full Cultivation pipeline end-to-end without
+ * real platform API credentials. Users can see data flowing through dashboards,
+ * heartbeat daemon running real jobs, reconciliation processing, circuit breakers firing.
+ */
+import type { AdPlatformSetup, AdPlatformAdapter, OAuthTokens, ConnectionStatus, CampaignConfig, CampaignResult, CampaignUpdate, CreativeConfig, SpendReport, PerformanceMetrics, InsightData, Cents } from './types.js';
+export declare class SandboxSetup implements AdPlatformSetup {
+    private label;
+    constructor(label?: string);
+    authenticate(): Promise<OAuthTokens>;
+    verifyConnection(tokens: OAuthTokens): Promise<ConnectionStatus>;
+    detectCurrency(_tokens: OAuthTokens): Promise<string>;
+}
+export declare class SandboxAdapter implements AdPlatformAdapter {
+    private accountId;
+    private tokens;
+    private campaigns;
+    constructor(accountId?: string, tokens?: OAuthTokens);
+    refreshToken(token: OAuthTokens): Promise<OAuthTokens>;
+    createCampaign(config: CampaignConfig): Promise<CampaignResult>;
+    updateCampaign(id: string, changes: CampaignUpdate): Promise<void>;
+    pauseCampaign(id: string): Promise<void>;
+    resumeCampaign(id: string): Promise<void>;
+    deleteCampaign(id: string): Promise<void>;
+    updateBudget(id: string, dailyBudget: Cents): Promise<void>;
+    updateCreative(_id: string, _creative: CreativeConfig): Promise<void>;
+    getSpend(dateRange: {
+        start: string;
+        end: string;
+    }): Promise<SpendReport>;
+    getPerformance(campaignId: string): Promise<PerformanceMetrics>;
+    getInsights(campaignId: string, metrics: string[]): Promise<InsightData>;
+}

package/dist/wizard/lib/adapters/sandbox.js

@@ -0,0 +1,174 @@
+/**
+ * Sandbox Ad Platform Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the AdPlatformSetup + AdPlatformAdapter
+ * interfaces. Every method returns valid-shaped data. No throws.
+ * This IS a full implementation for a sandbox platform (No Stubs Doctrine, v17.0).
+ *
+ * Use case: demonstrates the full Cultivation pipeline end-to-end without
+ * real platform API credentials. Users can see data flowing through dashboards,
+ * heartbeat daemon running real jobs, reconciliation processing, circuit breakers firing.
+ */
+import { randomUUID } from 'node:crypto';
+import { toCents } from './types.js';
+export class SandboxSetup {
+    label;
+    constructor(label = 'Sandbox') {
+        this.label = label;
+    }
+    async authenticate() {
+        return {
+            accessToken: `sandbox_access_${randomUUID().slice(0, 8)}`,
+            refreshToken: `sandbox_refresh_${randomUUID().slice(0, 8)}`,
+            expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
+            platform: 'meta',
+            scopes: ['ads_management', 'ads_read'],
+        };
+    }
+    async verifyConnection(tokens) {
+        return {
+            connected: true,
+            accountName: `${this.label} Demo Account`,
+            accountId: 'sandbox_' + randomUUID().slice(0, 8),
+            currency: 'USD',
+        };
+    }
+    async detectCurrency(_tokens) {
+        return 'USD';
+    }
+}
+export class SandboxAdapter {
+    accountId;
+    tokens;
+    // Instance-level campaign store — prevents state leaks between test runs and adapter instances
+    campaigns = new Map();
+    constructor(accountId = 'sandbox', tokens = { accessToken: '', refreshToken: '', expiresAt: '', platform: 'meta', scopes: [] }) {
+        this.accountId = accountId;
+        this.tokens = tokens;
+    }
+    async refreshToken(token) {
+        return {
+            ...token,
+            accessToken: `sandbox_access_${randomUUID().slice(0, 8)}`,
+            expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
+        };
+    }
+    async createCampaign(config) {
+        const id = `sandbox_camp_${randomUUID().slice(0, 12)}`;
+        this.campaigns.set(id, {
+            id,
+            name: config.name,
+            status: 'paused',
+            dailyBudgetCents: config.dailyBudget ?? 1000,
+            createdAt: new Date().toISOString(),
+            totalSpendCents: 0,
+            impressions: 0,
+            clicks: 0,
+            conversions: 0,
+        });
+        return {
+            externalId: id,
+            platform: config.platform ?? 'meta',
+            status: 'created',
+            dashboardUrl: `https://sandbox.voidforge.dev/campaigns/${id}`,
+        };
+    }
+    async updateCampaign(id, changes) {
+        const camp = this.campaigns.get(id);
+        if (camp) {
+            if (changes.name)
+                camp.name = changes.name;
+            if (changes.dailyBudget)
+                camp.dailyBudgetCents = changes.dailyBudget;
+        }
+    }
+    async pauseCampaign(id) {
+        const camp = this.campaigns.get(id);
+        if (camp)
+            camp.status = 'paused';
+    }
+    async resumeCampaign(id) {
+        const camp = this.campaigns.get(id);
+        if (camp)
+            camp.status = 'active';
+    }
+    async deleteCampaign(id) {
+        const camp = this.campaigns.get(id);
+        if (camp)
+            camp.status = 'deleted';
+    }
+    async updateBudget(id, dailyBudget) {
+        const camp = this.campaigns.get(id);
+        if (camp)
+            camp.dailyBudgetCents = dailyBudget;
+    }
+    async updateCreative(_id, _creative) {
+        // Sandbox accepts any creative update
+    }
+    async getSpend(dateRange) {
+        // Generate realistic spend data based on active campaigns
+        const activeCampaigns = [...this.campaigns.values()].filter(c => c.status === 'active');
+        const dayCount = Math.ceil((new Date(dateRange.end).getTime() - new Date(dateRange.start).getTime()) / (24 * 60 * 60 * 1000));
+        // Invalid date range (end before start) — return empty result
+        if (dayCount <= 0) {
+            return {
+                platform: 'meta',
+                dateRange,
+                totalSpend: toCents(0),
+                campaigns: [],
+            };
+        }
+        const campaignSpend = activeCampaigns.map(c => {
+            // Simulate realistic daily spend (~70-95% of budget)
+            const spendFactor = 0.7 + Math.random() * 0.25;
+            const dailySpend = Math.round(c.dailyBudgetCents * spendFactor);
+            const totalCampaignSpend = dailySpend * dayCount;
+            c.totalSpendCents += totalCampaignSpend;
+            c.impressions += Math.round(totalCampaignSpend / 2); // ~$0.02 CPM
+            c.clicks += Math.round(c.impressions * (0.01 + Math.random() * 0.03)); // 1-4% CTR
+            c.conversions += Math.round(c.clicks * (0.02 + Math.random() * 0.05)); // 2-7% CVR
+            return {
+                externalId: c.id,
+                spend: toCents(totalCampaignSpend / 100),
+                impressions: c.impressions,
+                clicks: c.clicks,
+                conversions: c.conversions,
+            };
+        });
+        const totalSpendValue = campaignSpend.reduce((sum, c) => sum + c.spend, 0);
+        return {
+            platform: 'meta',
+            dateRange,
+            totalSpend: toCents(totalSpendValue / 100),
+            campaigns: campaignSpend,
+        };
+    }
+    async getPerformance(campaignId) {
+        const camp = this.campaigns.get(campaignId);
+        const impressions = camp?.impressions ?? Math.round(1000 + Math.random() * 9000);
+        const clicks = camp?.clicks ?? Math.round(impressions * 0.025);
+        const conversions = camp?.conversions ?? Math.round(clicks * 0.04);
+        const spendCentsRaw = camp?.totalSpendCents ?? Math.round(impressions * 2);
+        return {
+            campaignId,
+            impressions,
+            clicks,
+            conversions,
+            spend: toCents(spendCentsRaw / 100),
+            ctr: (clicks / Math.max(impressions, 1)),
+            cpc: toCents((spendCentsRaw / Math.max(clicks, 1)) / 100),
+            roas: (conversions > 0 ? (conversions * 5000) / Math.max(spendCentsRaw, 1) : 0),
+        };
+    }
+    async getInsights(campaignId, metrics) {
+        const perf = await this.getPerformance(campaignId);
+        const data = {};
+        for (const metric of metrics) {
+            if (metric in perf)
+                data[metric] = perf[metric];
+            else
+                data[metric] = 0;
+        }
+        return { campaignId, metrics: data };
+    }
+}

package/dist/wizard/lib/adapters/stripe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stripe Revenue Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements RevenueSourceAdapter for Stripe's REST API.
+ * Read-only: VoidForge never processes payments, only reads revenue data.
+ * Uses Stripe API v1 (stable, well-documented, free test mode).
+ *
+ * PRD Reference: §9.4, §9.9 (revenue tracking)
+ * No Stubs Doctrine: every method makes a real API call.
+ */
+import type { RevenueSourceAdapter, RevenueCredentials, ConnectionResult, TransactionPage, BalanceResult, DateRange } from '../revenue-types.js';
+export declare class StripeAdapter implements RevenueSourceAdapter {
+    private apiKey;
+    constructor(apiKey: string);
+    connect(_credentials?: RevenueCredentials): Promise<ConnectionResult>;
+    detectCurrency(_credentials?: RevenueCredentials): Promise<string>;
+    getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage>;
+    getBalance(): Promise<BalanceResult>;
+}

package/dist/wizard/lib/adapters/stripe.js

@@ -0,0 +1,143 @@
+/**
+ * Stripe Revenue Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements RevenueSourceAdapter for Stripe's REST API.
+ * Read-only: VoidForge never processes payments, only reads revenue data.
+ * Uses Stripe API v1 (stable, well-documented, free test mode).
+ *
+ * PRD Reference: §9.4, §9.9 (revenue tracking)
+ * No Stubs Doctrine: every method makes a real API call.
+ */
+import { request as httpsRequest } from 'node:https';
+const STRIPE_HOST = 'api.stripe.com';
+/** Make a GET request to the Stripe API. */
+async function stripeGet(path, apiKey, params) {
+    const query = params ? '?' + new URLSearchParams(params).toString() : '';
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: STRIPE_HOST,
+            path: `/v1${path}${query}`,
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Stripe API timeout')); });
+        req.end();
+    });
+}
+export class StripeAdapter {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async connect(_credentials) {
+        try {
+            const { status, body } = await stripeGet('/account', this.apiKey);
+            if (status === 200) {
+                const account = JSON.parse(body);
+                return {
+                    connected: true,
+                    accountId: account.id,
+                    accountName: account.settings?.dashboard?.display_name
+                        ?? account.business_profile?.name
+                        ?? account.id
+                        ?? 'Stripe Account',
+                    currency: (account.default_currency ?? 'usd').toUpperCase(),
+                };
+            }
+            // VG-R1-005: Wrap error-path JSON.parse — response may be non-JSON (e.g., HTML from proxy 502)
+            try {
+                const error = JSON.parse(body);
+                return { connected: false, error: error.error?.message ?? `HTTP ${status}` };
+            }
+            catch {
+                return { connected: false, error: `HTTP ${status}` };
+            }
+        }
+        catch (err) {
+            return { connected: false, error: err instanceof Error ? err.message : 'Connection failed' };
+        }
+    }
+    async detectCurrency(_credentials) {
+        const result = await this.connect();
+        return result.currency ?? 'USD';
+    }
+    async getTransactions(range, cursor) {
+        try {
+            const params = {
+                limit: '100',
+                'created[gte]': String(Math.floor(new Date(range.start).getTime() / 1000)),
+                'created[lte]': String(Math.floor(new Date(range.end).getTime() / 1000)),
+            };
+            if (cursor)
+                params.starting_after = cursor;
+            const { status, body } = await stripeGet('/charges', this.apiKey, params);
+            if (status !== 200) {
+                // VG-R1-005: Wrap error-path JSON.parse — response may be non-JSON (e.g., HTML from proxy 502)
+                let errorMsg = `HTTP ${status}`;
+                try {
+                    const error = JSON.parse(body);
+                    errorMsg = error.error?.message ?? errorMsg;
+                }
+                catch { /* non-JSON response — use raw HTTP status */ }
+                throw new Error(errorMsg);
+            }
+            const data = JSON.parse(body);
+            const transactions = data.data
+                .filter(charge => charge.status === 'succeeded')
+                .map(charge => ({
+                externalId: charge.id,
+                type: 'charge',
+                amount: charge.amount, // Stripe amounts are already in cents
+                currency: 'USD',
+                description: charge.description ?? 'Stripe charge',
+                metadata: charge.metadata ?? {},
+                createdAt: new Date(charge.created * 1000).toISOString(),
+            }));
+            const lastId = data.data.length > 0 ? data.data[data.data.length - 1].id : undefined;
+            return {
+                transactions,
+                hasMore: data.has_more,
+                cursor: data.has_more ? lastId : undefined,
+            };
+        }
+        catch (err) {
+            throw new Error(`Stripe getTransactions failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+    async getBalance() {
+        try {
+            const { status, body } = await stripeGet('/balance', this.apiKey);
+            if (status !== 200) {
+                // VG-R1-005: Wrap error-path JSON.parse — response may be non-JSON (e.g., HTML from proxy 502)
+                let errorMsg = `HTTP ${status}`;
+                try {
+                    const error = JSON.parse(body);
+                    errorMsg = error.error?.message ?? errorMsg;
+                }
+                catch { /* non-JSON response — use raw HTTP status */ }
+                throw new Error(errorMsg);
+            }
+            const data = JSON.parse(body);
+            // Sum across all currencies (convert to USD cents — in practice, most accounts use one currency)
+            const availableTotal = data.available.reduce((sum, b) => sum + b.amount, 0);
+            const pendingTotal = data.pending.reduce((sum, b) => sum + b.amount, 0);
+            return {
+                available: availableTotal,
+                pending: pendingTotal,
+                currency: 'USD',
+            };
+        }
+        catch (err) {
+            throw new Error(`Stripe getBalance failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+}

package/dist/wizard/lib/adapters/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Ad Platform Adapter Types — shared across all platform implementations.
+ * Re-exports from the pattern file for convenience.
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ */
+export type { AdPlatformSetup, AdPlatformAdapter, ReadOnlyAdapter, CampaignConfig, CampaignResult, CampaignUpdate, CreativeConfig, SpendReport, PerformanceMetrics, InsightData, OAuthTokens, ConnectionStatus, PlatformError, Cents, Percentage, Ratio, AdPlatform, } from '../ad-platform-core.js';
+export { toCents, toDollars } from '../ad-platform-core.js';
+export { OutboundRateLimiter, getLimiter } from '../rate-limiter-core.js';

package/dist/wizard/lib/adapters/types.js

@@ -0,0 +1,10 @@
+/**
+ * Ad Platform Adapter Types — shared across all platform implementations.
+ * Re-exports from the pattern file for convenience.
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ */
+export { toCents, toDollars } from '../ad-platform-core.js';
+// Note: TokenBucketLimiter in ad-platform-adapter.ts is the simple reference version.
+// Production adapters use OutboundRateLimiter (below) which has safety margins, daily quotas, and retry logic.
+export { OutboundRateLimiter, getLimiter } from '../rate-limiter-core.js';

package/dist/wizard/lib/agent-memory.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent Memory — Cross-project lesson storage and retrieval.
+ *
+ * After each build, key learnings are stored here. When starting a new build,
+ * relevant lessons are loaded into methodology context.
+ * "Last time you built a Next.js app with Stripe, Phase 6 failed because
+ * webhook signatures weren't verified in test mode."
+ *
+ * Wong guards the knowledge. The Sanctum grows.
+ *
+ * Storage: ~/.voidforge/lessons.json (0600 permissions).
+ * Never stores credentials or PII — only methodology learnings.
+ */
+export interface Lesson {
+    id: string;
+    framework: string;
+    category: string;
+    lesson: string;
+    action: string;
+    project: string;
+    agent: string;
+    createdAt: string;
+}
+export type LessonInput = Omit<Lesson, 'id' | 'createdAt'>;
+/** Add a lesson. Returns the created lesson with ID and timestamp. */
+export declare function addLesson(input: LessonInput): Promise<Lesson>;
+/** Get all lessons, optionally filtered. */
+export declare function getLessons(filters?: {
+    framework?: string;
+    category?: string;
+    project?: string;
+}): Promise<Lesson[]>;
+/** Get lessons relevant to a build context (by framework). */
+export declare function getRelevantLessons(framework: string): Promise<Lesson[]>;
+/** Get total lesson count. */
+export declare function getLessonCount(): Promise<number>;

package/dist/wizard/lib/agent-memory.js

@@ -0,0 +1,114 @@
+/**
+ * Agent Memory — Cross-project lesson storage and retrieval.
+ *
+ * After each build, key learnings are stored here. When starting a new build,
+ * relevant lessons are loaded into methodology context.
+ * "Last time you built a Next.js app with Stripe, Phase 6 failed because
+ * webhook signatures weren't verified in test mode."
+ *
+ * Wong guards the knowledge. The Sanctum grows.
+ *
+ * Storage: ~/.voidforge/lessons.json (0600 permissions).
+ * Never stores credentials or PII — only methodology learnings.
+ */
+import { readFile, rename, mkdir, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+const VOIDFORGE_DIR = join(homedir(), '.voidforge');
+const LESSONS_PATH = join(VOIDFORGE_DIR, 'lessons.json');
+const MAX_LESSONS = 1000; // Cap to prevent unbounded growth
+// ── Write serialization ────────────────────────────
+let writeQueue = Promise.resolve();
+function serialized(fn) {
+    const result = writeQueue.then(fn, () => fn());
+    writeQueue = result.then(() => { }, () => { });
+    return result;
+}
+// ── File I/O ───────────────────────────────────────
+async function readLessons() {
+    try {
+        const raw = await readFile(LESSONS_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter(isValidLesson);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return [];
+        }
+        throw new Error(`Lessons file corrupted: ${err instanceof Error ? err.message : 'Unknown error'}`);
+    }
+}
+async function writeLessons(lessons) {
+    await mkdir(VOIDFORGE_DIR, { recursive: true });
+    const data = JSON.stringify(lessons, null, 2);
+    const tmpPath = LESSONS_PATH + '.tmp';
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(data);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, LESSONS_PATH);
+}
+function isValidLesson(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const l = obj;
+    return (typeof l.id === 'string' &&
+        typeof l.framework === 'string' &&
+        typeof l.category === 'string' &&
+        typeof l.lesson === 'string' &&
+        typeof l.action === 'string' &&
+        typeof l.project === 'string' &&
+        typeof l.agent === 'string' &&
+        typeof l.createdAt === 'string');
+}
+// ── Public API ─────────────────────────────────────
+/** Add a lesson. Returns the created lesson with ID and timestamp. */
+export function addLesson(input) {
+    return serialized(async () => {
+        const lessons = await readLessons();
+        const lesson = {
+            ...input,
+            id: randomUUID(),
+            createdAt: new Date().toISOString(),
+        };
+        lessons.push(lesson);
+        // Evict oldest if over cap
+        if (lessons.length > MAX_LESSONS) {
+            lessons.splice(0, lessons.length - MAX_LESSONS);
+        }
+        await writeLessons(lessons);
+        return lesson;
+    });
+}
+/** Get all lessons, optionally filtered. */
+export async function getLessons(filters) {
+    const lessons = await readLessons();
+    if (!filters)
+        return lessons;
+    return lessons.filter((l) => {
+        if (filters.framework && l.framework !== filters.framework)
+            return false;
+        if (filters.category && l.category !== filters.category)
+            return false;
+        if (filters.project && l.project !== filters.project)
+            return false;
+        return true;
+    });
+}
+/** Get lessons relevant to a build context (by framework). */
+export async function getRelevantLessons(framework) {
+    const lessons = await readLessons();
+    return lessons.filter((l) => l.framework === framework || l.framework === 'any');
+}
+/** Get total lesson count. */
+export async function getLessonCount() {
+    const lessons = await readLessons();
+    return lessons.length;
+}