optimal-cli 1.0.0 → 1.0.1

package/dist/lib/budget/projections.js

@@ -0,0 +1,384 @@
+/**
+ * Budget projection calculator for FY26 planning
+ *
+ * Ported from wes-dashboard/src/lib/projections/calculator.ts
+ * Pure TypeScript — no React, no framework deps.
+ *
+ * Supports two adjustment types:
+ * - Percentage: projected = actual * (1 + rate/100)
+ * - Flat: projected = actual + flatAmount
+ *
+ * Supports both unit AND average retail projections for revenue forecasting.
+ *
+ * Data sources:
+ * - Supabase `fpa_wes_imports` table (ReturnPro instance)
+ * - JSON file from stdin or --file flag
+ */
+import { getSupabase } from '../supabase.js';
+// --- Core calculation functions ---
+/**
+ * Calculate projected units based on adjustment type and value.
+ */
+export function calculateProjection(input) {
+    const { actualUnits, adjustmentType, adjustmentValue } = input;
+    if (adjustmentType === 'percentage') {
+        return Math.round(actualUnits * (1 + adjustmentValue / 100));
+    }
+    else {
+        return Math.max(0, actualUnits + adjustmentValue);
+    }
+}
+/**
+ * Calculate projected average retail price.
+ */
+export function calculateAvgRetailProjection(actualAvgRetail, adjustmentType, adjustmentValue) {
+    if (actualAvgRetail == null)
+        return undefined;
+    if (adjustmentType === 'percentage') {
+        return actualAvgRetail * (1 + adjustmentValue / 100);
+    }
+    else {
+        return Math.max(0, actualAvgRetail + adjustmentValue);
+    }
+}
+/**
+ * Convert checked-in units summary to projection entries with default values (0% change).
+ */
+export function initializeProjections(summary) {
+    return (summary ?? []).map((item) => {
+        const units = typeof item.unitCount === 'number' ? item.unitCount : 0;
+        const retail = typeof item.avgRetail === 'number' ? item.avgRetail : undefined;
+        return {
+            programCode: item.programCode ?? '',
+            masterProgram: item.masterProgram ?? '',
+            masterProgramId: item.masterProgramId ?? null,
+            clientId: item.clientId ?? null,
+            clientName: item.clientName ?? 'Unknown',
+            actualUnits: units,
+            adjustmentType: 'percentage',
+            adjustmentValue: 0,
+            projectedUnits: units,
+            avgRetail: retail,
+            avgRetailAdjustmentType: 'percentage',
+            avgRetailAdjustmentValue: 0,
+            projectedAvgRetail: retail,
+        };
+    });
+}
+/**
+ * Update a single projection entry's units.
+ */
+export function updateProjection(entry, adjustmentType, adjustmentValue) {
+    const projectedUnits = calculateProjection({
+        actualUnits: entry.actualUnits,
+        adjustmentType,
+        adjustmentValue,
+    });
+    return { ...entry, adjustmentType, adjustmentValue, projectedUnits };
+}
+/**
+ * Update a single projection entry's average retail.
+ */
+export function updateAvgRetailProjection(entry, adjustmentType, adjustmentValue) {
+    const projectedAvgRetail = calculateAvgRetailProjection(entry.avgRetail, adjustmentType, adjustmentValue);
+    return {
+        ...entry,
+        avgRetailAdjustmentType: adjustmentType,
+        avgRetailAdjustmentValue: adjustmentValue,
+        projectedAvgRetail,
+    };
+}
+/**
+ * Apply a uniform unit adjustment to all projections.
+ */
+export function applyUniformAdjustment(projections, adjustmentType, adjustmentValue) {
+    return projections.map((entry) => updateProjection(entry, adjustmentType, adjustmentValue));
+}
+/**
+ * Apply a uniform avg retail adjustment to all projections.
+ */
+export function applyUniformAvgRetailAdjustment(projections, adjustmentType, adjustmentValue) {
+    return projections.map((entry) => updateAvgRetailProjection(entry, adjustmentType, adjustmentValue));
+}
+/**
+ * Calculate totals for projection summary including revenue.
+ */
+export function calculateTotals(projections) {
+    const totalActual = projections.reduce((sum, p) => sum + p.actualUnits, 0);
+    const totalProjected = projections.reduce((sum, p) => sum + p.projectedUnits, 0);
+    const absoluteChange = totalProjected - totalActual;
+    const percentageChange = totalActual > 0
+        ? ((totalProjected - totalActual) / totalActual) * 100
+        : 0;
+    const actualRevenue = projections.reduce((sum, p) => {
+        if (p.avgRetail != null)
+            return sum + p.actualUnits * p.avgRetail;
+        return sum;
+    }, 0);
+    const projectedRevenue = projections.reduce((sum, p) => {
+        if (p.projectedAvgRetail != null)
+            return sum + p.projectedUnits * p.projectedAvgRetail;
+        return sum;
+    }, 0);
+    const revenueChange = projectedRevenue - actualRevenue;
+    const revenuePercentChange = actualRevenue > 0
+        ? ((projectedRevenue - actualRevenue) / actualRevenue) * 100
+        : 0;
+    return {
+        totalActual,
+        totalProjected,
+        percentageChange,
+        absoluteChange,
+        actualRevenue,
+        projectedRevenue,
+        revenueChange,
+        revenuePercentChange,
+    };
+}
+/**
+ * Group projections by client name.
+ */
+export function groupProjectionsByClient(projections) {
+    const groups = new Map();
+    for (const p of projections) {
+        const list = groups.get(p.clientName) ?? [];
+        list.push(p);
+        groups.set(p.clientName, list);
+    }
+    return groups;
+}
+/**
+ * Export projections to CSV format with unit + avgRetail + inventory value data.
+ */
+export function exportToCSV(projections) {
+    const headers = [
+        'Program Code',
+        'Master Program',
+        'Client',
+        '2025 Actual Units',
+        'Unit Adj Type',
+        'Unit Adj Value',
+        '2026 Projected Units',
+        'Unit Change',
+        'Unit Change %',
+        '2025 Avg Retail',
+        'Retail Adj Type',
+        'Retail Adj Value',
+        '2026 Projected Retail',
+        'Retail Change',
+        'Retail Change %',
+        '2025 Inventory Value',
+        '2026 Projected Inv. Value',
+        'Inv. Value Change',
+        'Inv. Value Change %',
+    ];
+    const rows = projections.map((p) => {
+        const unitChange = p.projectedUnits - p.actualUnits;
+        const unitChangePct = p.actualUnits > 0
+            ? ((unitChange / p.actualUnits) * 100).toFixed(1)
+            : '0.0';
+        const retailChange = (p.projectedAvgRetail ?? 0) - (p.avgRetail ?? 0);
+        const retailChangePct = p.avgRetail != null && p.avgRetail > 0
+            ? ((retailChange / p.avgRetail) * 100).toFixed(1)
+            : '0.0';
+        const actualRev = p.avgRetail != null ? p.actualUnits * p.avgRetail : 0;
+        const projRev = p.projectedAvgRetail != null
+            ? p.projectedUnits * p.projectedAvgRetail
+            : 0;
+        const revChange = projRev - actualRev;
+        const revChangePct = actualRev > 0 ? ((revChange / actualRev) * 100).toFixed(1) : '0.0';
+        return [
+            csvEscape(p.programCode),
+            csvEscape(p.masterProgram),
+            csvEscape(p.clientName),
+            p.actualUnits,
+            p.adjustmentType,
+            p.adjustmentType === 'percentage'
+                ? `${p.adjustmentValue}%`
+                : p.adjustmentValue,
+            p.projectedUnits,
+            unitChange,
+            `${unitChangePct}%`,
+            p.avgRetail != null ? `$${p.avgRetail.toFixed(2)}` : '',
+            p.avgRetailAdjustmentType,
+            p.avgRetailAdjustmentType === 'percentage'
+                ? `${p.avgRetailAdjustmentValue}%`
+                : `$${p.avgRetailAdjustmentValue}`,
+            p.projectedAvgRetail != null
+                ? `$${p.projectedAvgRetail.toFixed(2)}`
+                : '',
+            p.avgRetail != null ? `$${retailChange.toFixed(2)}` : '',
+            p.avgRetail != null ? `${retailChangePct}%` : '',
+            actualRev > 0 ? `$${actualRev.toFixed(2)}` : '',
+            projRev > 0 ? `$${projRev.toFixed(2)}` : '',
+            actualRev > 0 ? `$${revChange.toFixed(2)}` : '',
+            actualRev > 0 ? `${revChangePct}%` : '',
+        ].join(',');
+    });
+    return [headers.join(','), ...rows].join('\n');
+}
+// --- Data fetching ---
+const PAGE_SIZE = 1000;
+/**
+ * Fetch FY25 actuals from fpa_wes_imports on the ReturnPro Supabase instance.
+ * Aggregates across all months for a given fiscal year and user,
+ * returning one CheckedInUnitsSummary per master program.
+ */
+export async function fetchWesImports(options) {
+    const sb = getSupabase('returnpro');
+    const fy = options?.fiscalYear ?? 2025;
+    const summaryMap = new Map();
+    let from = 0;
+    while (true) {
+        let query = sb
+            .from('fpa_wes_imports')
+            .select(`
+        program_code,
+        master_program_id,
+        actual_units_prior_year,
+        projected_units,
+        avg_retail_prior_year,
+        projected_avg_retail,
+        unit_adj_type,
+        unit_adj_value,
+        retail_adj_type,
+        retail_adj_value,
+        dim_master_program(master_name, client_id, dim_client(client_name))
+      `)
+            .eq('fiscal_year', fy)
+            .order('master_program_id')
+            .range(from, from + PAGE_SIZE - 1);
+        if (options?.userId) {
+            query = query.eq('user_id', options.userId);
+        }
+        const { data, error } = await query;
+        if (error)
+            throw new Error(`Fetch fpa_wes_imports failed: ${error.message}`);
+        if (!data || data.length === 0)
+            break;
+        for (const row of data) {
+            const mpId = row.master_program_id;
+            const existing = summaryMap.get(mpId);
+            const units = row.actual_units_prior_year ?? row.projected_units ?? 0;
+            const retail = row.avg_retail_prior_year ?? null;
+            if (existing) {
+                existing.totalUnits += units;
+                if (retail != null) {
+                    existing.retailSum += retail;
+                    existing.retailCount += 1;
+                }
+            }
+            else {
+                const dim = row.dim_master_program;
+                summaryMap.set(mpId, {
+                    programCode: row.program_code ?? '',
+                    masterProgram: dim?.master_name ?? '',
+                    masterProgramId: mpId,
+                    clientId: dim?.client_id ?? null,
+                    clientName: dim?.dim_client?.client_name ?? 'Unknown',
+                    totalUnits: units,
+                    retailSum: retail ?? 0,
+                    retailCount: retail != null ? 1 : 0,
+                });
+            }
+        }
+        if (data.length < PAGE_SIZE)
+            break;
+        from += PAGE_SIZE;
+    }
+    const results = [];
+    for (const entry of summaryMap.values()) {
+        results.push({
+            programCode: entry.programCode,
+            masterProgram: entry.masterProgram,
+            masterProgramId: entry.masterProgramId,
+            clientId: entry.clientId,
+            clientName: entry.clientName,
+            unitCount: entry.totalUnits,
+            countMethod: 'Unit',
+            avgRetail: entry.retailCount > 0
+                ? entry.retailSum / entry.retailCount
+                : undefined,
+        });
+    }
+    results.sort((a, b) => a.clientName.localeCompare(b.clientName) || a.masterProgram.localeCompare(b.masterProgram));
+    return results;
+}
+/**
+ * Parse a JSON file (array of CheckedInUnitsSummary) as an alternative data source.
+ * Accepts raw JSON string (e.g., from stdin or file read).
+ */
+export function parseSummaryFromJson(json) {
+    const data = JSON.parse(json);
+    if (!Array.isArray(data)) {
+        throw new Error('Expected a JSON array of CheckedInUnitsSummary objects');
+    }
+    return data;
+}
+// --- Formatting helpers ---
+function csvEscape(s) {
+    if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+        return `"${s.replace(/"/g, '""')}"`;
+    }
+    return s;
+}
+function fmtCompact(n) {
+    const abs = Math.abs(n);
+    const sign = n < 0 ? '-' : '';
+    if (abs >= 1_000_000)
+        return `${sign}$${(abs / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${sign}$${(abs / 1_000).toFixed(1)}K`;
+    return `${sign}$${abs.toFixed(0)}`;
+}
+function fmtUnits(n) {
+    if (Math.abs(n) >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(2)}M`;
+    if (Math.abs(n) >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(n);
+}
+function fmtDelta(pct) {
+    const arrow = pct >= 0 ? '\u2191' : '\u2193';
+    return `${arrow}${pct >= 0 ? '+' : ''}${pct.toFixed(1)}%`;
+}
+/**
+ * Format projections as a Bloomberg-dense markdown table.
+ */
+export function formatProjectionTable(projections) {
+    if (projections.length === 0)
+        return 'No projection data.';
+    const totals = calculateTotals(projections);
+    const lines = [];
+    // Summary header
+    lines.push(`FY25 Actual: ${fmtUnits(totals.totalActual)} units  |  FY26 Projected: ${fmtUnits(totals.totalProjected)} units  |  ${fmtDelta(totals.percentageChange)}`);
+    if (totals.actualRevenue > 0) {
+        lines.push(`Revenue: ${fmtCompact(totals.actualRevenue)} -> ${fmtCompact(totals.projectedRevenue)}  |  ${fmtDelta(totals.revenuePercentChange)}`);
+    }
+    lines.push('');
+    // Table
+    lines.push('| Client | Program | FY25 Units | FY26 Units | Delta | Avg Retail | Proj Retail | Rev Delta |');
+    lines.push('|--------|---------|------------|------------|-------|------------|-------------|-----------|');
+    for (const p of projections) {
+        const unitDelta = p.projectedUnits - p.actualUnits;
+        const unitPct = p.actualUnits > 0
+            ? ((unitDelta / p.actualUnits) * 100).toFixed(1)
+            : '0.0';
+        const deltaStr = `${unitDelta >= 0 ? '+' : ''}${fmtUnits(unitDelta)} (${unitPct}%)`;
+        const retailStr = p.avgRetail != null ? `$${p.avgRetail.toFixed(2)}` : '-';
+        const projRetailStr = p.projectedAvgRetail != null
+            ? `$${p.projectedAvgRetail.toFixed(2)}`
+            : '-';
+        const actualRev = p.avgRetail != null ? p.actualUnits * p.avgRetail : 0;
+        const projRev = p.projectedAvgRetail != null
+            ? p.projectedUnits * p.projectedAvgRetail
+            : 0;
+        const revDelta = projRev - actualRev;
+        const revDeltaStr = actualRev > 0
+            ? `${revDelta >= 0 ? '+' : ''}${fmtCompact(revDelta)}`
+            : '-';
+        lines.push(`| ${p.clientName} | ${p.programCode} | ${fmtUnits(p.actualUnits)} | ${fmtUnits(p.projectedUnits)} | ${deltaStr} | ${retailStr} | ${projRetailStr} | ${revDeltaStr} |`);
+    }
+    lines.push(`\n${projections.length} programs`);
+    return lines.join('\n');
+}

package/dist/lib/budget/scenarios.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Budget scenario manager — save, load, list, compare, and delete named scenarios.
+ *
+ * Scenarios are stored as JSON files on disk at:
+ *   /home/optimal/optimal-cli/data/scenarios/{name}.json
+ *
+ * Each scenario captures a full snapshot of projected units after applying
+ * a uniform adjustment to the live fpa_wes_imports data.
+ */
+import 'dotenv/config';
+export interface SaveScenarioOptions {
+    name: string;
+    adjustmentType: 'percentage' | 'flat';
+    adjustmentValue: number;
+    fiscalYear?: number;
+    userId?: string;
+    description?: string;
+}
+export interface ScenarioData {
+    name: string;
+    createdAt: string;
+    adjustmentType: 'percentage' | 'flat';
+    adjustmentValue: number;
+    description?: string;
+    projections: Array<{
+        programCode: string;
+        masterProgram: string;
+        actualUnits: number;
+        projectedUnits: number;
+    }>;
+    totals: {
+        totalActual: number;
+        totalProjected: number;
+        percentageChange: number;
+    };
+}
+export interface ScenarioSummary {
+    name: string;
+    createdAt: string;
+    adjustmentType: string;
+    adjustmentValue: number;
+    description?: string;
+    totalProjected: number;
+    percentageChange: number;
+}
+export interface ComparisonResult {
+    scenarioNames: string[];
+    programs: Array<{
+        programCode: string;
+        masterProgram: string;
+        actual: number;
+        projectedByScenario: Record<string, number>;
+    }>;
+    totalsByScenario: Record<string, {
+        totalProjected: number;
+        percentageChange: number;
+    }>;
+}
+/**
+ * Save current projections as a named scenario to disk.
+ *
+ * Fetches live data via fetchWesImports, applies the given adjustment,
+ * calculates totals, and writes the result as JSON.
+ *
+ * @returns The absolute path to the saved scenario file.
+ */
+export declare function saveScenario(opts: SaveScenarioOptions): Promise<string>;
+/**
+ * Load a saved scenario from disk by name.
+ *
+ * Accepts the original name (will be sanitized) or the sanitized form.
+ */
+export declare function loadScenario(name: string): Promise<ScenarioData>;
+/**
+ * List all saved scenarios, returning lightweight summary objects.
+ *
+ * Scenarios with unreadable or malformed files are silently skipped.
+ */
+export declare function listScenarios(): Promise<ScenarioSummary[]>;
+/**
+ * Compare two or more scenarios side by side.
+ *
+ * For each program that appears in any of the loaded scenarios, the result
+ * includes the actual unit count and the projected units from each scenario.
+ * Programs missing from a given scenario will have projectedUnits of 0.
+ */
+export declare function compareScenarios(names: string[]): Promise<ComparisonResult>;
+/**
+ * Delete a scenario file from disk.
+ *
+ * Throws if the scenario does not exist.
+ */
+export declare function deleteScenario(name: string): Promise<void>;

package/dist/lib/budget/scenarios.js

@@ -0,0 +1,214 @@
+/**
+ * Budget scenario manager — save, load, list, compare, and delete named scenarios.
+ *
+ * Scenarios are stored as JSON files on disk at:
+ *   /home/optimal/optimal-cli/data/scenarios/{name}.json
+ *
+ * Each scenario captures a full snapshot of projected units after applying
+ * a uniform adjustment to the live fpa_wes_imports data.
+ */
+import 'dotenv/config';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fetchWesImports, initializeProjections, applyUniformAdjustment, calculateTotals, } from './projections.js';
+// --- Directory resolution ---
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Resolve relative to the repo root (lib/budget/ -> ../../data/scenarios/)
+const SCENARIOS_DIR = join(__dirname, '..', '..', 'data', 'scenarios');
+function ensureScenariosDir() {
+    mkdirSync(SCENARIOS_DIR, { recursive: true });
+}
+// --- Helpers ---
+/**
+ * Sanitize a scenario name into a safe filename segment.
+ * Lowercases, replaces spaces and disallowed chars with hyphens,
+ * collapses repeated hyphens, and strips leading/trailing hyphens.
+ */
+function sanitizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function scenarioPath(sanitized) {
+    return join(SCENARIOS_DIR, `${sanitized}.json`);
+}
+// --- Public API ---
+/**
+ * Save current projections as a named scenario to disk.
+ *
+ * Fetches live data via fetchWesImports, applies the given adjustment,
+ * calculates totals, and writes the result as JSON.
+ *
+ * @returns The absolute path to the saved scenario file.
+ */
+export async function saveScenario(opts) {
+    ensureScenariosDir();
+    const sanitized = sanitizeName(opts.name);
+    if (!sanitized) {
+        throw new Error(`Invalid scenario name: "${opts.name}"`);
+    }
+    // Fetch and process data
+    const summary = await fetchWesImports({
+        fiscalYear: opts.fiscalYear,
+        userId: opts.userId,
+    });
+    const initialized = initializeProjections(summary);
+    const adjusted = applyUniformAdjustment(initialized, opts.adjustmentType, opts.adjustmentValue);
+    const totals = calculateTotals(adjusted);
+    const scenarioData = {
+        name: opts.name,
+        createdAt: new Date().toISOString(),
+        adjustmentType: opts.adjustmentType,
+        adjustmentValue: opts.adjustmentValue,
+        ...(opts.description !== undefined ? { description: opts.description } : {}),
+        projections: adjusted.map((p) => ({
+            programCode: p.programCode,
+            masterProgram: p.masterProgram,
+            actualUnits: p.actualUnits,
+            projectedUnits: p.projectedUnits,
+        })),
+        totals: {
+            totalActual: totals.totalActual,
+            totalProjected: totals.totalProjected,
+            percentageChange: totals.percentageChange,
+        },
+    };
+    const filePath = scenarioPath(sanitized);
+    writeFileSync(filePath, JSON.stringify(scenarioData, null, 2), 'utf-8');
+    return filePath;
+}
+/**
+ * Load a saved scenario from disk by name.
+ *
+ * Accepts the original name (will be sanitized) or the sanitized form.
+ */
+export async function loadScenario(name) {
+    const sanitized = sanitizeName(name);
+    const filePath = scenarioPath(sanitized);
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Scenario not found: "${name}" (looked for ${filePath})`);
+    }
+    return JSON.parse(raw);
+}
+/**
+ * List all saved scenarios, returning lightweight summary objects.
+ *
+ * Scenarios with unreadable or malformed files are silently skipped.
+ */
+export async function listScenarios() {
+    ensureScenariosDir();
+    let files;
+    try {
+        files = readdirSync(SCENARIOS_DIR);
+    }
+    catch {
+        return [];
+    }
+    const jsonFiles = files.filter((f) => f.endsWith('.json'));
+    const summaries = [];
+    for (const file of jsonFiles) {
+        const filePath = join(SCENARIOS_DIR, file);
+        try {
+            const raw = readFileSync(filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            summaries.push({
+                name: data.name,
+                createdAt: data.createdAt,
+                adjustmentType: data.adjustmentType,
+                adjustmentValue: data.adjustmentValue,
+                ...(data.description !== undefined ? { description: data.description } : {}),
+                totalProjected: data.totals.totalProjected,
+                percentageChange: data.totals.percentageChange,
+            });
+        }
+        catch {
+            // Skip unreadable/malformed scenario files
+        }
+    }
+    // Sort newest first
+    summaries.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    return summaries;
+}
+/**
+ * Compare two or more scenarios side by side.
+ *
+ * For each program that appears in any of the loaded scenarios, the result
+ * includes the actual unit count and the projected units from each scenario.
+ * Programs missing from a given scenario will have projectedUnits of 0.
+ */
+export async function compareScenarios(names) {
+    if (names.length < 2) {
+        throw new Error('compareScenarios requires at least 2 scenario names');
+    }
+    // Load all scenarios in parallel
+    const loaded = await Promise.all(names.map((n) => loadScenario(n)));
+    // Build a unified map of programCode -> { masterProgram, actual, projectedByScenario }
+    const programMap = new Map();
+    for (const scenario of loaded) {
+        for (const p of scenario.projections) {
+            const existing = programMap.get(p.programCode);
+            if (existing) {
+                existing.projectedByScenario[scenario.name] = p.projectedUnits;
+                // Keep the actual from whichever scenario we see first
+            }
+            else {
+                programMap.set(p.programCode, {
+                    masterProgram: p.masterProgram,
+                    actual: p.actualUnits,
+                    projectedByScenario: { [scenario.name]: p.projectedUnits },
+                });
+            }
+        }
+    }
+    // Fill in zeros for scenarios that don't have a given program
+    for (const entry of programMap.values()) {
+        for (const scenario of loaded) {
+            if (!(scenario.name in entry.projectedByScenario)) {
+                entry.projectedByScenario[scenario.name] = 0;
+            }
+        }
+    }
+    const programs = Array.from(programMap.entries())
+        .map(([programCode, entry]) => ({
+        programCode,
+        masterProgram: entry.masterProgram,
+        actual: entry.actual,
+        projectedByScenario: entry.projectedByScenario,
+    }))
+        .sort((a, b) => a.programCode.localeCompare(b.programCode));
+    const totalsByScenario = {};
+    for (const scenario of loaded) {
+        totalsByScenario[scenario.name] = {
+            totalProjected: scenario.totals.totalProjected,
+            percentageChange: scenario.totals.percentageChange,
+        };
+    }
+    return {
+        scenarioNames: loaded.map((s) => s.name),
+        programs,
+        totalsByScenario,
+    };
+}
+/**
+ * Delete a scenario file from disk.
+ *
+ * Throws if the scenario does not exist.
+ */
+export async function deleteScenario(name) {
+    const sanitized = sanitizeName(name);
+    const filePath = scenarioPath(sanitized);
+    try {
+        unlinkSync(filePath);
+    }
+    catch {
+        throw new Error(`Scenario not found: "${name}" (looked for ${filePath})`);
+    }
+}