@badgie/crm-cli 0.6.0 → 0.7.0

package/dist/commands/finance.js

@@ -4,6 +4,96 @@ import { getAuthedClient } from '../core/supabase.js';
 import { commonListOptions, output, parseColumns, parseLimit } from '../core/format.js';
 import { callAppApi, postAppApiMultipart } from '../core/http.js';
 import { maybeResolve } from '../core/resolve.js';
+function parseIsoDateOption(raw, flag, required = false) {
+    if (raw == null || raw === '') {
+        if (required)
+            throw new Error(`${flag} YYYY-MM-DD is required`);
+        return undefined;
+    }
+    if (typeof raw !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        throw new Error(`${flag} must be YYYY-MM-DD`);
+    }
+    return raw;
+}
+function parseIntegerOption(raw, flag, min, max, required = false) {
+    if (raw == null || raw === '') {
+        if (required)
+            throw new Error(`${flag} is required`);
+        return undefined;
+    }
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n < min || n > max) {
+        throw new Error(`${flag} must be an integer between ${min} and ${max}`);
+    }
+    return n;
+}
+function parseAmountOption(raw, flag, required = false) {
+    if (raw == null || raw === '') {
+        if (required)
+            throw new Error(`${flag} is required`);
+        return undefined;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`${flag} must be a non-negative number`);
+    return n;
+}
+function currentPeriod() {
+    const d = new Date();
+    return { year: d.getFullYear(), month: d.getMonth() + 1, quarter: Math.ceil((d.getMonth() + 1) / 3) };
+}
+function appendQuery(path, params) {
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            qs.set(key, String(value));
+    }
+    const suffix = qs.toString();
+    return suffix ? `${path}?${suffix}` : path;
+}
+function csvEscape(value) {
+    const s = value == null ? '' : String(value);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+function printCsv(headers, row) {
+    console.log(headers.map(csvEscape).join(','));
+    console.log(row.map(csvEscape).join(','));
+}
+function moneyCsv(value) {
+    return (Math.round(value * 100) / 100).toFixed(2);
+}
+function parseDate(raw) {
+    if (!raw)
+        return null;
+    const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(raw);
+    if (!match)
+        return null;
+    const d = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+function isoDate(d) {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+function addMonths(d, months) {
+    return new Date(d.getFullYear(), d.getMonth() + months, d.getDate());
+}
+function startOfDay(d) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+// Paginates a Supabase query in 1000-row chunks. Aging/forecast aggregations need every row;
+// the default 1000-row cap silently truncates totals on tenants with high volume.
+async function fetchAllRows(builder, chunkSize = 1000) {
+    const out = [];
+    for (let from = 0;; from += chunkSize) {
+        const { data, error } = await builder().range(from, from + chunkSize - 1);
+        if (error)
+            throw error;
+        const rows = (data ?? []);
+        out.push(...rows);
+        if (rows.length < chunkSize)
+            return out;
+    }
+}
 // Invoices
 async function listInvoices(_a, opts) {
     const { client } = await getAuthedClient();
@@ -325,6 +415,443 @@ async function fxUsdEur(_a, opts) {
     const res = await callAppApi(`/api/finance/fx-usd-eur?${params.toString()}`);
     output(res, { pretty: !!opts.pretty });
 }
+// Finance OS
+async function financeHealth(_args, opts) {
+    const res = await callAppApi('/api/finance/health');
+    output(opts.criticalOnly ? { issues: res.issues.filter((i) => i.severity === 'critical') } : res, {
+        pretty: !!opts.pretty,
+    });
+}
+async function financeTaxSummary(_args, opts) {
+    const now = currentPeriod();
+    const year = parseIntegerOption(opts.year, '--year', 2020, 2100) ?? now.year;
+    const quarter = parseIntegerOption(opts.quarter, '--quarter', 1, 4) ?? now.quarter;
+    const res = await callAppApi(appendQuery('/api/finance/tax-summary', { year, quarter }));
+    const s = res.summary;
+    if (opts.csv) {
+        printCsv([
+            'periodo',
+            'base_emitida',
+            'base_recibida',
+            'iva_repercutido',
+            'iva_soportado',
+            'iva_neto',
+            'retenciones_emitidas',
+            'retenciones_recibidas',
+            'impacto_estimado',
+            'facturas',
+        ], [
+            s.periodLabel,
+            moneyCsv(s.issuedBase),
+            moneyCsv(s.receivedBase),
+            moneyCsv(s.vatCharged),
+            moneyCsv(s.vatDeductible),
+            moneyCsv(s.vatNet),
+            moneyCsv(s.withholdingOnIssued),
+            moneyCsv(s.withholdingOnReceived),
+            moneyCsv(s.estimatedTaxCashImpact),
+            s.invoiceCount,
+        ]);
+        return;
+    }
+    output(s, { pretty: !!opts.pretty });
+}
+function emptyAgingBucket() {
+    return { count: 0, amount: 0 };
+}
+function emptyAgingSummary() {
+    return {
+        overdue: emptyAgingBucket(),
+        due_0_7: emptyAgingBucket(),
+        due_8_30: emptyAgingBucket(),
+        due_31_60: emptyAgingBucket(),
+        due_60_plus: emptyAgingBucket(),
+        no_due: emptyAgingBucket(),
+    };
+}
+function agingBucketKey(dueDate, referenceDate) {
+    if (!dueDate)
+        return 'no_due';
+    const diffDays = Math.floor((startOfDay(dueDate).getTime() - startOfDay(referenceDate).getTime()) / 86_400_000);
+    if (diffDays < 0)
+        return 'overdue';
+    if (diffDays <= 7)
+        return 'due_0_7';
+    if (diffDays <= 30)
+        return 'due_8_30';
+    if (diffDays <= 60)
+        return 'due_31_60';
+    return 'due_60_plus';
+}
+function computeAging(invoices, referenceDate) {
+    const receivables = emptyAgingSummary();
+    const payables = emptyAgingSummary();
+    for (const inv of invoices) {
+        const status = String(inv.status ?? '');
+        const isReceivable = inv.type === 'emitida' && status !== 'pagada' && status !== 'anulada';
+        const isPayable = inv.type === 'recibida' && status !== 'pagada' && status !== 'anulada' && status !== 'borrador';
+        if (!isReceivable && !isPayable)
+            continue;
+        const bucket = agingBucketKey(parseDate(inv.due_date) ?? parseDate(inv.invoice_date), referenceDate);
+        const amount = Math.abs(Number(inv.total_amount) || 0);
+        const target = isReceivable ? receivables : payables;
+        target[bucket].count += 1;
+        target[bucket].amount += amount;
+    }
+    const sum = (summary) => Object.values(summary).reduce((total, bucket) => total + bucket.amount, 0);
+    return {
+        referenceDate: isoDate(referenceDate),
+        receivables,
+        payables,
+        totals: {
+            receivables: sum(receivables),
+            payables: sum(payables),
+            overdueReceivables: receivables.overdue.amount,
+            overduePayables: payables.overdue.amount,
+        },
+    };
+}
+async function financeAging(_args, opts) {
+    const referenceRaw = parseIsoDateOption(opts.date, '--date');
+    const referenceDate = referenceRaw ? parseDate(referenceRaw) : new Date();
+    if (!referenceDate)
+        throw new Error('--date must be YYYY-MM-DD');
+    const { client } = await getAuthedClient();
+    const invoices = await fetchAllRows(() => client.from('invoices').select('id, type, status, invoice_date, due_date, total_amount'));
+    output(computeAging(invoices, referenceDate), { pretty: !!opts.pretty });
+}
+function sumLatestBankBalances(movements) {
+    const byAccount = new Map();
+    for (const m of movements) {
+        if ((m.bank_account?.account_type ?? 'bank') !== 'bank')
+            continue;
+        const list = byAccount.get(m.bank_account_id) ?? [];
+        list.push(m);
+        byAccount.set(m.bank_account_id, list);
+    }
+    if (byAccount.size === 0)
+        return null;
+    let total = 0;
+    let foundAny = false;
+    for (const movs of byAccount.values()) {
+        const sorted = [...movs].sort((a, b) => {
+            const c = a.movement_date.localeCompare(b.movement_date);
+            return c !== 0 ? c : a.id.localeCompare(b.id);
+        });
+        for (let i = sorted.length - 1; i >= 0; i--) {
+            const balance = Number(sorted[i].balance);
+            if (Number.isFinite(balance)) {
+                total += balance;
+                foundAny = true;
+                break;
+            }
+        }
+    }
+    return foundAny ? total : null;
+}
+function profileOf(client) {
+    const raw = client.client_finance_profiles;
+    if (!raw)
+        return null;
+    return Array.isArray(raw) ? raw[0] ?? null : raw;
+}
+function monthlyRecurringRevenue(clients) {
+    return clients.reduce((sum, client) => {
+        if (client.show_in_finance === false)
+            return sum;
+        const profile = profileOf(client);
+        if (!profile || profile.plan_membership !== 'active')
+            return sum;
+        const amount = Number(profile.billing_price_amount) || 0;
+        if (amount <= 0)
+            return sum;
+        if (profile.billing_plan_interval === 'annual')
+            return sum + amount / 12;
+        if (profile.billing_plan_interval === 'monthly')
+            return sum + amount;
+        return sum;
+    }, 0);
+}
+function isPendingIncome(inv) {
+    return inv.type === 'emitida' && inv.status !== 'pagada' && inv.status !== 'anulada';
+}
+function isPendingExpense(inv) {
+    return inv.type === 'recibida' && inv.status !== 'pagada' && inv.status !== 'anulada' && inv.status !== 'borrador';
+}
+function nextOccurrence(date, recurrence) {
+    if (recurrence === 'monthly')
+        return addMonths(date, 1);
+    if (recurrence === 'quarterly')
+        return addMonths(date, 3);
+    if (recurrence === 'annual')
+        return addMonths(date, 12);
+    return addMonths(date, 1200);
+}
+function sumForecastItems(items, type, from, to) {
+    let total = 0;
+    for (const item of items) {
+        if (item.status !== 'active' || item.type !== type)
+            continue;
+        const start = parseDate(item.next_date);
+        if (!start)
+            continue;
+        const end = parseDate(item.end_date);
+        let cursor = start;
+        while (cursor <= to && (!end || cursor <= end)) {
+            if (cursor >= from)
+                total += Math.abs(Number(item.amount) || 0);
+            if (item.recurrence === 'one_off')
+                break;
+            cursor = nextOccurrence(cursor, item.recurrence);
+        }
+    }
+    return total;
+}
+function sumInvoiceCash(invoices, type, from, to) {
+    return invoices.reduce((sum, inv) => {
+        const include = type === 'income' ? isPendingIncome(inv) : isPendingExpense(inv);
+        if (!include)
+            return sum;
+        const due = parseDate(inv.due_date) ?? parseDate(inv.invoice_date);
+        if (!due || due < from || due > to)
+            return sum;
+        return sum + Math.abs(Number(inv.total_amount) || 0);
+    }, 0);
+}
+function computeCashForecast({ invoices, bankMovements, forecastItems, clients, referenceDate, }) {
+    const startCash = sumLatestBankBalances(bankMovements);
+    const mrr = monthlyRecurringRevenue(clients);
+    const start = startOfDay(referenceDate);
+    const horizons = [30, 60, 90];
+    const points = horizons.map((horizonDays) => {
+        const end = new Date(start);
+        end.setDate(end.getDate() + horizonDays);
+        const pendingIncome = sumInvoiceCash(invoices, 'income', start, end);
+        const pendingExpenses = sumInvoiceCash(invoices, 'expense', start, end);
+        const manualIncome = sumForecastItems(forecastItems, 'income', start, end);
+        const manualExpenses = sumForecastItems(forecastItems, 'expense', start, end);
+        const recurringIncome = Math.round(mrr * (horizonDays / 30) * 100) / 100;
+        const expectedIncome = pendingIncome + manualIncome + recurringIncome;
+        const expectedExpenses = pendingExpenses + manualExpenses;
+        const netChange = expectedIncome - expectedExpenses;
+        return {
+            horizonDays,
+            expectedIncome,
+            expectedExpenses,
+            netChange,
+            projectedCash: startCash === null ? null : startCash + netChange,
+        };
+    });
+    const p90 = points.find((p) => p.horizonDays === 90) ?? points[points.length - 1];
+    const avgDailyBurn = p90 && p90.netChange < 0 ? Math.abs(p90.netChange) / p90.horizonDays : 0;
+    return {
+        startCash,
+        referenceDate: isoDate(start),
+        mrr,
+        points,
+        runwayDays: startCash !== null && avgDailyBurn > 0 ? Math.floor(startCash / avgDailyBurn) : null,
+        nextReceivables: sumInvoiceCash(invoices, 'income', start, addMonths(start, 2)),
+        nextPayables: sumInvoiceCash(invoices, 'expense', start, addMonths(start, 2)),
+    };
+}
+async function loadForecastInputs() {
+    const { client } = await getAuthedClient();
+    const [invoices, bankMovements, forecastItems, clients] = await Promise.all([
+        fetchAllRows(() => client.from('invoices').select('id, type, status, invoice_date, due_date, total_amount')),
+        fetchAllRows(() => client.from('bank_movements').select('id, bank_account_id, movement_date, balance, bank_account:bank_accounts(account_type)')),
+        fetchAllRows(() => client
+            .from('finance_forecast_items')
+            .select('*')
+            .order('status', { ascending: true })
+            .order('next_date', { ascending: true })),
+        fetchAllRows(() => client.from('clients').select('show_in_finance, client_finance_profiles (billing_price_amount, billing_plan_interval, plan_membership)')),
+    ]);
+    return { invoices, bankMovements, forecastItems, clients };
+}
+async function financeForecastSummary(_args, opts) {
+    const referenceRaw = parseIsoDateOption(opts.date, '--date');
+    const referenceDate = referenceRaw ? parseDate(referenceRaw) : new Date();
+    if (!referenceDate)
+        throw new Error('--date must be YYYY-MM-DD');
+    const inputs = await loadForecastInputs();
+    output(computeCashForecast({ ...inputs, referenceDate }), { pretty: !!opts.pretty });
+}
+async function financeForecastList(_args, opts) {
+    const res = await callAppApi('/api/finance/forecast-items');
+    let rows = res.forecastItems;
+    if (opts.activeOnly)
+        rows = rows.filter((item) => item.status === 'active');
+    if (opts.pausedOnly)
+        rows = rows.filter((item) => item.status === 'paused');
+    if (typeof opts.type === 'string')
+        rows = rows.filter((item) => item.type === opts.type);
+    rows = rows.slice(0, parseLimit(opts));
+    output(rows, { pretty: !!opts.pretty, columns: parseColumns(opts) });
+}
+function forecastPayloadFromOpts(opts, mode) {
+    const payload = {};
+    if (opts.type !== undefined) {
+        if (opts.type !== 'income' && opts.type !== 'expense')
+            throw new Error('--type must be income|expense');
+        payload.type = opts.type;
+    }
+    if (typeof opts.name === 'string')
+        payload.name = opts.name;
+    const amount = parseAmountOption(opts.amount, '--amount', mode === 'insert');
+    if (amount !== undefined)
+        payload.amount = amount;
+    if (opts.recurrence !== undefined) {
+        if (!['one_off', 'monthly', 'quarterly', 'annual'].includes(String(opts.recurrence))) {
+            throw new Error('--recurrence must be one_off|monthly|quarterly|annual');
+        }
+        payload.recurrence = opts.recurrence;
+    }
+    const nextDate = parseIsoDateOption(opts.nextDate, '--next-date', mode === 'insert');
+    if (nextDate)
+        payload.next_date = nextDate;
+    const endDate = parseIsoDateOption(opts.endDate, '--end-date');
+    if (endDate)
+        payload.end_date = endDate;
+    if (opts.clearEndDate)
+        payload.end_date = null;
+    if (opts.status !== undefined) {
+        if (opts.status !== 'active' && opts.status !== 'paused')
+            throw new Error('--status must be active|paused');
+        payload.status = opts.status;
+    }
+    if (typeof opts.counterparty === 'string')
+        payload.counterparty_name = opts.counterparty;
+    if (opts.clearCounterparty)
+        payload.counterparty_name = null;
+    if (typeof opts.category === 'string')
+        payload.category = opts.category;
+    if (opts.clearCategory)
+        payload.category = null;
+    if (typeof opts.notes === 'string')
+        payload.notes = opts.notes;
+    if (opts.clearNotes)
+        payload.notes = null;
+    if (typeof opts.currency === 'string')
+        payload.currency = opts.currency;
+    if (mode === 'insert') {
+        if (!payload.type)
+            throw new Error('--type income|expense is required');
+        if (!payload.name)
+            throw new Error('--name is required');
+        if (!payload.recurrence)
+            payload.recurrence = 'monthly';
+    }
+    return payload;
+}
+async function financeForecastAdd(_args, opts) {
+    const payload = forecastPayloadFromOpts(opts, 'insert');
+    const res = await callAppApi('/api/finance/forecast-items', {
+        method: 'POST',
+        body: JSON.stringify(payload),
+    });
+    output(res, { pretty: !!opts.pretty });
+}
+async function financeForecastUpdate(args, opts) {
+    if (!args.id)
+        throw new Error('Falta forecast item id');
+    const payload = { id: args.id, ...forecastPayloadFromOpts(opts, 'patch') };
+    const res = await callAppApi('/api/finance/forecast-items', {
+        method: 'PATCH',
+        body: JSON.stringify(payload),
+    });
+    output(res, { pretty: !!opts.pretty });
+}
+async function financeForecastPause(args, opts) {
+    if (!args.id)
+        throw new Error('Falta forecast item id');
+    const res = await callAppApi('/api/finance/forecast-items', {
+        method: 'PATCH',
+        body: JSON.stringify({ id: args.id, status: 'paused' }),
+    });
+    output(res, { pretty: !!opts.pretty });
+}
+async function financeForecastResume(args, opts) {
+    if (!args.id)
+        throw new Error('Falta forecast item id');
+    const res = await callAppApi('/api/finance/forecast-items', {
+        method: 'PATCH',
+        body: JSON.stringify({ id: args.id, status: 'active' }),
+    });
+    output(res, { pretty: !!opts.pretty });
+}
+async function financeForecastDelete(args, opts) {
+    if (!args.id)
+        throw new Error('Falta forecast item id');
+    const res = await callAppApi(`/api/finance/forecast-items?id=${encodeURIComponent(args.id)}`, {
+        method: 'DELETE',
+    });
+    output(res, { pretty: !!opts.pretty });
+}
+async function financeClosingsList(_args, opts) {
+    const year = parseIntegerOption(opts.year, '--year', 2020, 2100);
+    const month = parseIntegerOption(opts.month, '--month', 1, 12);
+    const res = await callAppApi(appendQuery('/api/finance/closings', { year, month }));
+    output(res.closings.slice(0, parseLimit(opts)), { pretty: !!opts.pretty, columns: parseColumns(opts) });
+}
+async function financeClosingClose(_args, opts) {
+    const year = parseIntegerOption(opts.year, '--year', 2020, 2100, true);
+    const month = parseIntegerOption(opts.month, '--month', 1, 12, true);
+    const res = await callAppApi('/api/finance/closings', {
+        method: 'POST',
+        body: JSON.stringify({
+            year,
+            month,
+            status: 'closed',
+            close: true,
+            notes: typeof opts.notes === 'string' ? opts.notes : null,
+        }),
+    });
+    output(res, { pretty: !!opts.pretty });
+}
+async function financeClosingReopen(_args, opts) {
+    const year = parseIntegerOption(opts.year, '--year', 2020, 2100, true);
+    const month = parseIntegerOption(opts.month, '--month', 1, 12, true);
+    const res = await callAppApi('/api/finance/closings', {
+        method: 'PATCH',
+        body: JSON.stringify({
+            year,
+            month,
+            status: 'open',
+            notes: typeof opts.notes === 'string' ? opts.notes : undefined,
+        }),
+    });
+    output(res, { pretty: !!opts.pretty });
+}
+async function financeControlSummary(_args, opts) {
+    const now = currentPeriod();
+    const year = parseIntegerOption(opts.year, '--year', 2020, 2100) ?? now.year;
+    const month = parseIntegerOption(opts.month, '--month', 1, 12) ?? now.month;
+    const quarter = parseIntegerOption(opts.quarter, '--quarter', 1, 4) ?? Math.ceil(month / 3);
+    const [health, tax, closings, forecastInputs] = await Promise.all([
+        callAppApi('/api/finance/health'),
+        callAppApi(appendQuery('/api/finance/tax-summary', { year, quarter })),
+        callAppApi(appendQuery('/api/finance/closings', { year, month })),
+        loadForecastInputs(),
+    ]);
+    const referenceRaw = parseIsoDateOption(opts.date, '--date');
+    const referenceDate = referenceRaw ? parseDate(referenceRaw) : new Date();
+    if (!referenceDate)
+        throw new Error('--date must be YYYY-MM-DD');
+    const aging = computeAging(forecastInputs.invoices, referenceDate);
+    const forecast = computeCashForecast({ ...forecastInputs, referenceDate });
+    output({
+        period: { year, month, quarter },
+        closing: closings.closings[0] ?? null,
+        health: {
+            totalIssues: health.issues.length,
+            criticalIssues: health.issues.filter((issue) => issue.severity === 'critical').length,
+            issues: health.issues,
+        },
+        tax: tax.summary,
+        aging,
+        forecast,
+    }, { pretty: !!opts.pretty });
+}
 // Suppliers
 async function listSuppliers(_a, opts) {
     const { client } = await getAuthedClient();
@@ -568,6 +1095,213 @@ export const financeModule = {
             examples: ['badgie-crm finance fx usd-eur --date 2026-04-15 --amount 1200 --pretty'],
             handler: fxUsdEur,
         },
+        {
+            path: ['finance', 'control', 'summary'],
+            summary: 'Finance OS control summary: closing, health, tax, aging and cash forecast',
+            description: 'Read-only cockpit for agents. Uses Finance OS APIs for health/tax/closings and Supabase reads for aging/forecast. Defaults to the current month and quarter.',
+            tags: ['read', 'http'],
+            options: [
+                { flag: '--year <n>', description: 'period year (default current year)' },
+                { flag: '--month <n>', description: 'period month 1-12 (default current month)' },
+                { flag: '--quarter <n>', description: 'tax quarter 1-4 (default derived from month)' },
+                { flag: '--date <yyyy-mm-dd>', description: 'reference date for aging/forecast (default today)' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: [
+                'badgie-crm finance control summary --pretty',
+                'badgie-crm finance control summary --year 2026 --month 4 --quarter 2',
+            ],
+            handler: financeControlSummary,
+        },
+        {
+            path: ['finance', 'health'],
+            summary: 'List Finance OS health issues',
+            description: 'Returns actionable issues used by Finanzas → Control → Salud: unreconciled movements, missing categories/documents, duplicates, missing tax IDs and import warnings.',
+            tags: ['read', 'http'],
+            options: [
+                { flag: '--critical-only', description: 'only severity=critical issues' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: [
+                'badgie-crm finance health --pretty',
+                'badgie-crm finance health --critical-only',
+            ],
+            handler: financeHealth,
+        },
+        {
+            path: ['finance', 'aging'],
+            summary: 'Compute receivables/payables aging buckets',
+            description: 'Buckets pending issued/received invoices into overdue, 0-7, 8-30, 31-60 and 60+ days. Read-only and safe for agents.',
+            tags: ['read'],
+            options: [
+                { flag: '--date <yyyy-mm-dd>', description: 'reference date (default today)' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: [
+                'badgie-crm finance aging --pretty',
+                'badgie-crm finance aging --date 2026-04-30',
+            ],
+            handler: financeAging,
+        },
+        {
+            path: ['finance', 'tax-summary'],
+            summary: 'Finance OS quarterly tax summary',
+            description: 'Uses the same calculation as Control → Fiscal: issued/received base, VAT charged/deductible/net, withholdings and estimated cash impact.',
+            tags: ['read', 'http'],
+            options: [
+                { flag: '--year <n>', description: 'tax year (default current year)' },
+                { flag: '--quarter <n>', description: 'quarter 1-4 (default current quarter)' },
+                { flag: '--csv', description: 'emit one CSV row instead of JSON' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: [
+                'badgie-crm finance tax-summary --year 2026 --quarter 2 --pretty',
+                'badgie-crm finance tax-summary --year 2026 --quarter 2 --csv > fiscal-q2.csv',
+            ],
+            handler: financeTaxSummary,
+        },
+        {
+            path: ['finance', 'forecast', 'summary'],
+            summary: 'Compute Finance OS cash forecast for 30/60/90 days',
+            description: 'Combines latest bank balances, pending invoices, manual forecast items and active client MRR/ARR. Read-only.',
+            tags: ['read'],
+            options: [
+                { flag: '--date <yyyy-mm-dd>', description: 'reference date (default today)' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: ['badgie-crm finance forecast summary --pretty'],
+            handler: financeForecastSummary,
+        },
+        {
+            path: ['finance', 'forecast', 'list'],
+            summary: 'List manual Finance OS forecast items',
+            tags: ['read', 'http'],
+            options: [
+                { flag: '--type <income|expense>', description: 'filter by type' },
+                { flag: '--active-only', description: 'only active items' },
+                { flag: '--paused-only', description: 'only paused items' },
+                ...commonListOptions(),
+            ],
+            examples: ['badgie-crm finance forecast list --active-only --pretty'],
+            handler: financeForecastList,
+        },
+        {
+            path: ['finance', 'forecast', 'add'],
+            summary: 'Create a manual Finance OS forecast item',
+            description: 'Calls the Next app endpoint so audit log and closed-period guards are enforced.',
+            tags: ['write', 'http'],
+            options: [
+                { flag: '--type <income|expense>', description: 'required' },
+                { flag: '--name <text>', description: 'required concept/name' },
+                { flag: '--amount <n>', description: 'required positive amount' },
+                { flag: '--recurrence <one_off|monthly|quarterly|annual>', description: 'default monthly' },
+                { flag: '--next-date <yyyy-mm-dd>', description: 'required next occurrence date' },
+                { flag: '--end-date <yyyy-mm-dd>', description: 'optional end date' },
+                { flag: '--counterparty <name>', description: 'optional counterparty' },
+                { flag: '--category <slug>', description: 'optional category' },
+                { flag: '--currency <code>', description: 'default EUR' },
+                { flag: '--notes <text>', description: 'internal notes' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: [
+                'badgie-crm finance forecast add --type expense --name "Oficina" --amount 350 --recurrence monthly --next-date 2026-05-01 --pretty',
+                'badgie-crm finance forecast add --type income --name "Grant" --amount 5000 --recurrence one_off --next-date 2026-06-15',
+            ],
+            handler: financeForecastAdd,
+        },
+        {
+            path: ['finance', 'forecast', 'update'],
+            summary: 'Update a manual Finance OS forecast item',
+            tags: ['write', 'http'],
+            args: [{ name: 'id', required: true, description: 'finance_forecast_items.id' }],
+            options: [
+                { flag: '--type <income|expense>', description: 'set type' },
+                { flag: '--name <text>', description: 'set name' },
+                { flag: '--amount <n>', description: 'set amount' },
+                { flag: '--recurrence <one_off|monthly|quarterly|annual>', description: 'set recurrence' },
+                { flag: '--next-date <yyyy-mm-dd>', description: 'set next occurrence date' },
+                { flag: '--end-date <yyyy-mm-dd>', description: 'set end date' },
+                { flag: '--clear-end-date', description: 'clear end date' },
+                { flag: '--status <active|paused>', description: 'set status' },
+                { flag: '--counterparty <name>', description: 'set counterparty' },
+                { flag: '--clear-counterparty', description: 'clear counterparty' },
+                { flag: '--category <slug>', description: 'set category' },
+                { flag: '--clear-category', description: 'clear category' },
+                { flag: '--notes <text>', description: 'set notes' },
+                { flag: '--clear-notes', description: 'clear notes' },
+                { flag: '--currency <code>', description: 'set currency' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: [
+                'badgie-crm finance forecast update <id> --amount 420 --next-date 2026-06-01 --pretty',
+            ],
+            handler: financeForecastUpdate,
+        },
+        {
+            path: ['finance', 'forecast', 'pause'],
+            summary: 'Pause a manual forecast item',
+            tags: ['write', 'http'],
+            args: [{ name: 'id', required: true, description: 'finance_forecast_items.id' }],
+            options: [{ flag: '--pretty', description: 'human output' }],
+            handler: financeForecastPause,
+        },
+        {
+            path: ['finance', 'forecast', 'resume'],
+            summary: 'Resume a paused manual forecast item',
+            tags: ['write', 'http'],
+            args: [{ name: 'id', required: true, description: 'finance_forecast_items.id' }],
+            options: [{ flag: '--pretty', description: 'human output' }],
+            handler: financeForecastResume,
+        },
+        {
+            path: ['finance', 'forecast', 'delete'],
+            summary: 'Delete a manual forecast item',
+            description: 'Destructive: deletes a row from finance_forecast_items via the Finance OS API. Agents must ask for explicit confirmation.',
+            tags: ['destructive', 'http'],
+            args: [{ name: 'id', required: true, description: 'finance_forecast_items.id' }],
+            options: [{ flag: '--pretty', description: 'human output' }],
+            handler: financeForecastDelete,
+        },
+        {
+            path: ['finance', 'closings', 'list'],
+            summary: 'List Finance OS monthly closings',
+            tags: ['read', 'http'],
+            options: [
+                { flag: '--year <n>', description: 'filter by year' },
+                { flag: '--month <n>', description: 'filter by month 1-12' },
+                ...commonListOptions(),
+            ],
+            examples: ['badgie-crm finance closings list --year 2026 --pretty'],
+            handler: financeClosingsList,
+        },
+        {
+            path: ['finance', 'closings', 'close'],
+            summary: 'Close a Finance OS month',
+            description: 'Creates/updates finance_period_closings with an operational snapshot. Calls the app endpoint so audit log is written.',
+            tags: ['write', 'http'],
+            options: [
+                { flag: '--year <n>', description: 'required year' },
+                { flag: '--month <n>', description: 'required month 1-12' },
+                { flag: '--notes <text>', description: 'closing notes' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: ['badgie-crm finance closings close --year 2026 --month 4 --notes "Abril revisado" --pretty'],
+            handler: financeClosingClose,
+        },
+        {
+            path: ['finance', 'closings', 'reopen'],
+            summary: 'Reopen a Finance OS month',
+            description: 'Reopens a closed operational period. Agents should confirm because this allows period mutations again.',
+            tags: ['write', 'http'],
+            options: [
+                { flag: '--year <n>', description: 'required year' },
+                { flag: '--month <n>', description: 'required month 1-12' },
+                { flag: '--notes <text>', description: 'reason/notes' },
+                { flag: '--pretty', description: 'human output' },
+            ],
+            examples: ['badgie-crm finance closings reopen --year 2026 --month 4 --notes "Corrección pendiente" --pretty'],
+            handler: financeClosingReopen,
+        },
         {
             path: ['finance', 'suppliers', 'list'],
             summary: 'List suppliers',