jaz-cli 2.3.0 → 2.5.0

package/dist/calc/provision.js

@@ -0,0 +1,112 @@
+/**
+ * IAS 37 Provision calculator — PV measurement + discount unwinding.
+ *
+ * Calculates the present value of a future obligation and generates
+ * the periodic unwinding schedule (Dr Finance Cost / Cr Provision).
+ *
+ * Compliance references:
+ *  - IAS 37.36: Best estimate of expenditure required to settle
+ *  - IAS 37.45: PV when effect of time value is material
+ *  - IAS 37.60: Unwinding of discount = finance cost
+ *
+ * Uses `financial` package for PV calculation (same as lease calculator).
+ * Final period penny adjustment closes provision to the full nominal amount.
+ *
+ * Use cases:
+ *  - Warranty obligations
+ *  - Legal claims / litigation
+ *  - Decommissioning / restoration
+ *  - Restructuring provisions
+ *  - Onerous contracts
+ */
+import { pv } from 'financial';
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat, validateRate } from './validate.js';
+import { journalStep, fmtCapsuleAmount } from './blueprint.js';
+export function calculateProvision(inputs) {
+    const { amount, annualRate, termMonths, startDate, currency } = inputs;
+    validatePositive(amount, 'Estimated future outflow');
+    validateRate(annualRate, 'Discount rate');
+    validatePositiveInteger(termMonths, 'Term (months)');
+    validateDateFormat(startDate);
+    const monthlyRate = annualRate / 100 / 12;
+    // PV of a single future cash flow (IAS 37.45)
+    // pv(rate, nper, pmt, fv) — pmt=0, fv=amount → returns negative, negate
+    const presentValue = round2(-pv(monthlyRate, termMonths, 0, amount));
+    const totalUnwinding = round2(amount - presentValue);
+    // Initial recognition journal (Dr Expense / Cr Provision at PV)
+    const initialJournal = {
+        description: `Initial provision recognition at PV (IAS 37)`,
+        lines: [
+            { account: 'Provision Expense', debit: presentValue, credit: 0 },
+            { account: 'Provision for Obligations', debit: 0, credit: presentValue },
+        ],
+    };
+    // Unwinding schedule (effective interest method, IAS 37.60)
+    const schedule = [];
+    let provisionBalance = presentValue;
+    let totalInterest = 0;
+    for (let i = 1; i <= termMonths; i++) {
+        const openingBalance = round2(provisionBalance);
+        const isFinal = i === termMonths;
+        let interest;
+        if (isFinal) {
+            // Final period: close to nominal amount exactly
+            interest = round2(amount - openingBalance);
+        }
+        else {
+            interest = round2(openingBalance * monthlyRate);
+        }
+        provisionBalance = round2(openingBalance + interest);
+        totalInterest = round2(totalInterest + interest);
+        const date = startDate ? addMonths(startDate, i) : null;
+        const journal = {
+            description: `Provision unwinding — Month ${i} of ${termMonths}`,
+            lines: [
+                { account: 'Finance Cost — Unwinding', debit: interest, credit: 0 },
+                { account: 'Provision for Obligations', debit: 0, credit: interest },
+            ],
+        };
+        schedule.push({
+            period: i,
+            date,
+            openingBalance,
+            payment: 0, // no cash movement until settlement
+            interest,
+            principal: 0, // reuse ScheduleRow — principal not applicable
+            closingBalance: provisionBalance,
+            journal,
+        });
+    }
+    // Build blueprint for agent execution
+    let blueprint = null;
+    if (startDate) {
+        const steps = [
+            journalStep(1, initialJournal.description, startDate, initialJournal.lines),
+            ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
+        ];
+        blueprint = {
+            capsuleType: 'Provisions',
+            capsuleName: `Provision — ${fmtCapsuleAmount(amount, currency)} — ${annualRate}% — ${termMonths} months`,
+            tags: ['Provision', 'IAS 37'],
+            customFields: { 'Obligation Type': null, 'Expected Settlement Date': null },
+            steps,
+        };
+    }
+    return {
+        type: 'provision',
+        currency: currency ?? null,
+        inputs: {
+            amount,
+            annualRate,
+            termMonths,
+            startDate: startDate ?? null,
+        },
+        presentValue,
+        nominalAmount: amount,
+        totalUnwinding,
+        initialJournal,
+        schedule,
+        blueprint,
+    };
+}

package/dist/calc/types.js

@@ -0,0 +1,21 @@
+/**
+ * Shared types for jaz calc financial calculators.
+ */
+/**
+ * Round to 2 decimal places (cents).
+ *
+ * Uses Math.round() (asymmetric, rounds 0.5 away from zero). This is the
+ * standard JavaScript rounding and works correctly for accounting amounts
+ * up to ~$90 trillion (Number.MAX_SAFE_INTEGER / 100). Final-period
+ * corrections in each calculator absorb any cumulative drift, ensuring
+ * balances always close to exactly $0.00.
+ */
+export function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Advance a date by N months. Returns YYYY-MM-DD string. */
+export function addMonths(dateStr, months) {
+    const d = new Date(dateStr + 'T00:00:00');
+    d.setMonth(d.getMonth() + months);
+    return d.toISOString().slice(0, 10);
+}

package/dist/calc/validate.js

@@ -0,0 +1,48 @@
+/**
+ * Input validation for jaz calc financial calculators.
+ * Throws CalcValidationError with user-friendly messages.
+ */
+export class CalcValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CalcValidationError';
+    }
+}
+export function validatePositive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new CalcValidationError(`${name} must be a positive number (got ${value})`);
+    }
+}
+export function validateNonNegative(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new CalcValidationError(`${name} must be zero or positive (got ${value})`);
+    }
+}
+export function validatePositiveInteger(value, name) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new CalcValidationError(`${name} must be a positive integer (got ${value})`);
+    }
+}
+export function validateSalvageLessThanCost(salvage, cost) {
+    if (salvage >= cost) {
+        throw new CalcValidationError(`Salvage value (${salvage}) must be less than cost (${cost})`);
+    }
+}
+export function validateDateFormat(date) {
+    if (!date)
+        return;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        throw new CalcValidationError(`Date must be YYYY-MM-DD format (got "${date}")`);
+    }
+    const d = new Date(date + 'T00:00:00');
+    if (isNaN(d.getTime())) {
+        throw new CalcValidationError(`Invalid date: "${date}"`);
+    }
+}
+export function validateRate(rate, name = 'Rate') {
+    validateNonNegative(rate, name);
+    if (rate > 100) {
+        // Warning only — rates >100% are rare but legal (e.g. hyperinflation)
+        process.stderr.write(`Warning: ${name} is ${rate}% — are you sure this isn't a decimal? (e.g. 6 for 6%, not 0.06)\n`);
+    }
+}

package/dist/commands/calc.js

@@ -0,0 +1,200 @@
+import chalk from 'chalk';
+import { calculateLoan } from '../calc/loan.js';
+import { calculateLease } from '../calc/lease.js';
+import { calculateDepreciation } from '../calc/depreciation.js';
+import { calculatePrepaidExpense, calculateDeferredRevenue } from '../calc/amortization.js';
+import { calculateFxReval } from '../calc/fx-reval.js';
+import { calculateEcl } from '../calc/ecl.js';
+import { calculateProvision } from '../calc/provision.js';
+import { printResult, printJson } from '../calc/format.js';
+import { CalcValidationError } from '../calc/validate.js';
+/** Wrap calc action with validation error handling. */
+function calcAction(fn) {
+    return (opts) => {
+        try {
+            fn(opts);
+        }
+        catch (err) {
+            if (err instanceof CalcValidationError) {
+                console.error(chalk.red(`Error: ${err.message}`));
+                process.exit(1);
+            }
+            throw err;
+        }
+    };
+}
+export function registerCalcCommand(program) {
+    const calc = program
+        .command('calc')
+        .description('Financial calculators — loan, lease, depreciation, prepaid-expense, deferred-revenue, fx-reval, ecl, provision');
+    // ── jaz calc loan ──────────────────────────────────────────────
+    calc
+        .command('loan')
+        .description('Loan amortization schedule')
+        .requiredOption('--principal <amount>', 'Loan principal', parseFloat)
+        .requiredOption('--rate <percent>', 'Annual interest rate (%)', parseFloat)
+        .requiredOption('--term <months>', 'Loan term in months', parseInt)
+        .option('--start-date <date>', 'Start date (YYYY-MM-DD)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const result = calculateLoan({
+            principal: opts.principal,
+            annualRate: opts.rate,
+            termMonths: opts.term,
+            startDate: opts.startDate,
+            currency: opts.currency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+    // ── jaz calc lease ─────────────────────────────────────────────
+    calc
+        .command('lease')
+        .description('IFRS 16 lease schedule (liability unwinding + ROU depreciation)')
+        .requiredOption('--payment <amount>', 'Monthly lease payment', parseFloat)
+        .requiredOption('--term <months>', 'Lease term in months', parseInt)
+        .requiredOption('--rate <percent>', 'Incremental borrowing rate (%)', parseFloat)
+        .option('--start-date <date>', 'Lease commencement date (YYYY-MM-DD)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const result = calculateLease({
+            monthlyPayment: opts.payment,
+            termMonths: opts.term,
+            annualRate: opts.rate,
+            startDate: opts.startDate,
+            currency: opts.currency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+    // ── jaz calc depreciation ──────────────────────────────────────
+    calc
+        .command('depreciation')
+        .description('Depreciation schedule (straight-line, double declining, or 150% declining)')
+        .requiredOption('--cost <amount>', 'Asset cost', parseFloat)
+        .requiredOption('--salvage <amount>', 'Salvage value', parseFloat)
+        .requiredOption('--life <years>', 'Useful life in years', parseInt)
+        .option('--method <method>', 'Method: sl, ddb (default), or 150db', 'ddb')
+        .option('--frequency <freq>', 'Frequency: annual (default) or monthly', 'annual')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const result = calculateDepreciation({
+            cost: opts.cost,
+            salvageValue: opts.salvage,
+            usefulLifeYears: opts.life,
+            method: opts.method,
+            frequency: opts.frequency,
+            currency: opts.currency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+    // ── jaz calc prepaid-expense ──────────────────────────────────
+    calc
+        .command('prepaid-expense')
+        .description('Prepaid expense recognition schedule (e.g. insurance, rent, subscriptions)')
+        .requiredOption('--amount <amount>', 'Total prepaid amount', parseFloat)
+        .requiredOption('--periods <count>', 'Number of recognition periods', parseInt)
+        .option('--frequency <freq>', 'Frequency: monthly (default) or quarterly', 'monthly')
+        .option('--start-date <date>', 'Start date (YYYY-MM-DD)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const result = calculatePrepaidExpense({
+            amount: opts.amount,
+            periods: opts.periods,
+            frequency: opts.frequency,
+            startDate: opts.startDate,
+            currency: opts.currency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+    // ── jaz calc deferred-revenue ───────────────────────────────────
+    calc
+        .command('deferred-revenue')
+        .description('Deferred revenue recognition schedule (e.g. annual contracts, retainers)')
+        .requiredOption('--amount <amount>', 'Total deferred amount', parseFloat)
+        .requiredOption('--periods <count>', 'Number of recognition periods', parseInt)
+        .option('--frequency <freq>', 'Frequency: monthly (default) or quarterly', 'monthly')
+        .option('--start-date <date>', 'Start date (YYYY-MM-DD)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const result = calculateDeferredRevenue({
+            amount: opts.amount,
+            periods: opts.periods,
+            frequency: opts.frequency,
+            startDate: opts.startDate,
+            currency: opts.currency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+    // ── jaz calc fx-reval ───────────────────────────────────────────
+    calc
+        .command('fx-reval')
+        .description('FX revaluation — unrealized gain/loss on non-AR/AP foreign currency balances (IAS 21)')
+        .requiredOption('--amount <amount>', 'Foreign currency amount outstanding', parseFloat)
+        .requiredOption('--book-rate <rate>', 'Original booking exchange rate', parseFloat)
+        .requiredOption('--closing-rate <rate>', 'Period-end closing exchange rate', parseFloat)
+        .option('--currency <code>', 'Foreign currency code (e.g. USD)', 'USD')
+        .option('--base-currency <code>', 'Base (functional) currency code (e.g. SGD)', 'SGD')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const result = calculateFxReval({
+            amount: opts.amount,
+            bookRate: opts.bookRate,
+            closingRate: opts.closingRate,
+            currency: opts.currency,
+            baseCurrency: opts.baseCurrency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+    // ── jaz calc ecl ────────────────────────────────────────────────
+    calc
+        .command('ecl')
+        .description('Expected credit loss provision matrix (IFRS 9 simplified approach)')
+        .requiredOption('--current <amount>', 'Current (not overdue) receivables balance', parseFloat)
+        .requiredOption('--30d <amount>', '1-30 days overdue balance', parseFloat)
+        .requiredOption('--60d <amount>', '31-60 days overdue balance', parseFloat)
+        .requiredOption('--90d <amount>', '61-90 days overdue balance', parseFloat)
+        .requiredOption('--120d <amount>', '91+ days overdue balance', parseFloat)
+        .requiredOption('--rates <rates>', 'Loss rates per bucket (comma-separated %)', (v) => v.split(',').map(Number))
+        .option('--existing-provision <amount>', 'Existing provision balance', parseFloat, 0)
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const rates = opts.rates;
+        const result = calculateEcl({
+            buckets: [
+                { name: 'Current', balance: opts.current, rate: rates[0] },
+                { name: '1-30 days', balance: opts['30d'], rate: rates[1] },
+                { name: '31-60 days', balance: opts['60d'], rate: rates[2] },
+                { name: '61-90 days', balance: opts['90d'], rate: rates[3] },
+                { name: '91+ days', balance: opts['120d'], rate: rates[4] },
+            ],
+            existingProvision: opts.existingProvision,
+            currency: opts.currency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+    // ── jaz calc provision ──────────────────────────────────────────
+    calc
+        .command('provision')
+        .description('IAS 37 provision PV measurement + discount unwinding schedule')
+        .requiredOption('--amount <amount>', 'Estimated future cash outflow', parseFloat)
+        .requiredOption('--rate <percent>', 'Discount rate (%)', parseFloat)
+        .requiredOption('--term <months>', 'Months until expected settlement', parseInt)
+        .option('--start-date <date>', 'Recognition date (YYYY-MM-DD)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(calcAction((opts) => {
+        const result = calculateProvision({
+            amount: opts.amount,
+            annualRate: opts.rate,
+            termMonths: opts.term,
+            startDate: opts.startDate,
+            currency: opts.currency,
+        });
+        opts.json ? printJson(result) : printResult(result);
+    }));
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import { dirname, join } from 'path';
 import { initCommand } from './commands/init.js';
 import { versionsCommand } from './commands/versions.js';
 import { updateCommand } from './commands/update.js';
+import { registerCalcCommand } from './commands/calc.js';
 import { SKILL_TYPES } from './types/index.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -49,4 +50,5 @@ program
         skill: options.skill,
     });
 });
+registerCalcCommand(program);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaz-cli",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "CLI to install Jaz AI skills for Claude Code",
   "type": "module",
   "bin": {
@@ -36,8 +36,9 @@
   "author": "Jaz Engineering <api-support@jaz.ai>",
   "license": "MIT",
   "dependencies": {
-    "commander": "^12.1.0",
     "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "financial": "^0.2.4",
     "ora": "^8.1.1",
     "prompts": "^2.4.2"
   },