jaz-cli 2.7.0 → 2.8.0

package/dist/__tests__/jobs-month-end.test.js

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import { generateMonthEndBlueprint } from '../jobs/month-end.js';
+import { JobValidationError } from '../jobs/validate.js';
+describe('generateMonthEndBlueprint', () => {
+    const base = { period: '2025-01' };
+    // Structure
+    it('produces 5 phases', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.phases).toHaveLength(5);
+    });
+    it('produces 18 total steps', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.summary.totalSteps).toBe(18);
+    });
+    it('has correct jobType', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.jobType).toBe('month-end-close');
+    });
+    it('mode is standalone', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.mode).toBe('standalone');
+    });
+    it('period label is "Jan 2025"', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.period).toBe('Jan 2025');
+    });
+    // Phase names
+    it('phase names are correct', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.phases[0].name).toBe('Phase 1: Pre-Close Preparation');
+        expect(r.phases[1].name).toBe('Phase 2: Accruals & Adjustments');
+        expect(r.phases[2].name).toBe('Phase 3: Period-End Valuations');
+        expect(r.phases[3].name).toBe('Phase 4: Verification');
+        expect(r.phases[4].name).toBe('Phase 5: Close & Lock');
+    });
+    // Step categories per phase
+    it('Phase 1 steps are all "verify"', () => {
+        const r = generateMonthEndBlueprint(base);
+        for (const step of r.phases[0].steps) {
+            expect(step.category).toBe('verify');
+        }
+    });
+    it('Phase 2 steps are all "accrue"', () => {
+        const r = generateMonthEndBlueprint(base);
+        for (const step of r.phases[1].steps) {
+            expect(step.category).toBe('accrue');
+        }
+    });
+    it('Phase 3 steps are all "value"', () => {
+        const r = generateMonthEndBlueprint(base);
+        for (const step of r.phases[2].steps) {
+            expect(step.category).toBe('value');
+        }
+    });
+    it('Phase 4 steps are all "report"', () => {
+        const r = generateMonthEndBlueprint(base);
+        for (const step of r.phases[3].steps) {
+            expect(step.category).toBe('report');
+        }
+    });
+    it('Phase 5 steps are all "lock"', () => {
+        const r = generateMonthEndBlueprint(base);
+        for (const step of r.phases[4].steps) {
+            expect(step.category).toBe('lock');
+        }
+    });
+    // API dates
+    it('API calls contain correct dates for "2025-01"', () => {
+        const r = generateMonthEndBlueprint(base);
+        const allSteps = r.phases.flatMap(p => p.steps);
+        const stepsWithBody = allSteps.filter(s => s.apiBody);
+        for (const step of stepsWithBody) {
+            const body = step.apiBody;
+            // Check that date fields reference the correct period
+            if (body.filter && typeof body.filter === 'object') {
+                const filter = body.filter;
+                if (filter.valueDate && typeof filter.valueDate === 'object') {
+                    const vd = filter.valueDate;
+                    expect(vd.from).toBe('2025-01-01');
+                    expect(vd.to).toBe('2025-01-31');
+                }
+            }
+            if (body.endDate) {
+                expect(body.endDate).toBe('2025-01-31');
+            }
+            if (body.startDate) {
+                expect(body.startDate).toBe('2025-01-01');
+            }
+        }
+    });
+    // Summary counts
+    it('summary has recipe references', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.summary.recipeReferences.length).toBeGreaterThan(0);
+        // Sorted array — verify it is sorted
+        const sorted = [...r.summary.recipeReferences].sort();
+        expect(r.summary.recipeReferences).toEqual(sorted);
+    });
+    it('summary has calc references', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.summary.calcReferences.length).toBeGreaterThan(0);
+    });
+    it('summary has API calls', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.summary.apiCalls.length).toBeGreaterThan(0);
+    });
+    it('summary totalSteps matches actual step count', () => {
+        const r = generateMonthEndBlueprint(base);
+        const actual = r.phases.reduce((sum, p) => sum + p.steps.length, 0);
+        expect(r.summary.totalSteps).toBe(actual);
+    });
+    // Currency
+    it('currency defaults to "SGD"', () => {
+        const r = generateMonthEndBlueprint(base);
+        expect(r.currency).toBe('SGD');
+    });
+    it('custom currency "USD" passes through', () => {
+        const r = generateMonthEndBlueprint({ period: '2025-01', currency: 'USD' });
+        expect(r.currency).toBe('USD');
+    });
+    // Validation
+    it('invalid period throws JobValidationError', () => {
+        expect(() => generateMonthEndBlueprint({ period: 'bad' })).toThrow(JobValidationError);
+    });
+    it('invalid month 13 throws JobValidationError', () => {
+        expect(() => generateMonthEndBlueprint({ period: '2025-13' })).toThrow(JobValidationError);
+    });
+    // Prior month calculation
+    it('for "2025-01" the prior month is Dec 2024', () => {
+        const r = generateMonthEndBlueprint({ period: '2025-01' });
+        // Phase 4, step 4 ("Compare P&L to prior month") contains prior month dates
+        const compareStep = r.phases[3].steps[3];
+        expect(compareStep.notes).toContain('2024-12-01');
+        expect(compareStep.notes).toContain('2024-12-31');
+        expect(compareStep.apiBody).toBeDefined();
+        expect(compareStep.apiBody.secondarySnapshotDate).toBe('2024-12-01');
+    });
+    it('for "2025-06" the prior month is May 2025', () => {
+        const r = generateMonthEndBlueprint({ period: '2025-06' });
+        const compareStep = r.phases[3].steps[3];
+        expect(compareStep.notes).toContain('2025-05-01');
+        expect(compareStep.notes).toContain('2025-05-31');
+        expect(compareStep.apiBody.secondarySnapshotDate).toBe('2025-05-01');
+    });
+    // Step ordering
+    it('step ordering is continuous 1..N', () => {
+        const r = generateMonthEndBlueprint(base);
+        const allOrders = r.phases.flatMap(p => p.steps.map(s => s.order));
+        for (let i = 0; i < allOrders.length; i++) {
+            expect(allOrders[i]).toBe(i + 1);
+        }
+    });
+    // Different period
+    it('"2025-06" produces correct dates and label', () => {
+        const r = generateMonthEndBlueprint({ period: '2025-06' });
+        expect(r.period).toBe('Jun 2025');
+        // Check report body dates
+        const trialBalance = r.phases[3].steps[0];
+        expect(trialBalance.apiBody.startDate).toBe('2025-06-01');
+        expect(trialBalance.apiBody.endDate).toBe('2025-06-30');
+    });
+});

package/dist/__tests__/jobs-payment-run.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { generatePaymentRunBlueprint } from '../jobs/payment-run.js';
+import { JobValidationError } from '../jobs/validate.js';
+describe('generatePaymentRunBlueprint (basic)', () => {
+    it('produces a valid JobBlueprint with correct jobType', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.jobType).toBe('payment-run');
+    });
+    it('has 6 phases and 10 total steps', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.phases).toHaveLength(6);
+        expect(bp.summary.totalSteps).toBe(10);
+    });
+    it('phase names are correct', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.phases.map(p => p.name)).toEqual([
+            'Identify Outstanding Bills',
+            'Summarize by Supplier',
+            'Select & Approve Payment Batch',
+            'Record Payments',
+            'FX Payments',
+            'Verification',
+        ]);
+    });
+    it('step categories match expectations', () => {
+        const bp = generatePaymentRunBlueprint();
+        const categories = bp.phases.flatMap(p => p.steps.map(s => s.category));
+        expect(categories).toEqual([
+            'verify', // 1 — list unpaid bills
+            'verify', // 2 — filter by due date
+            'report', // 3 — group by supplier
+            'report', // 4 — AP aging
+            'review', // 5 — check cash availability
+            'resolve', // 6 — record full payments
+            'resolve', // 7 — record partial payments
+            'resolve', // 8 — FX payments
+            'verify', // 9 — verify AP aging
+            'verify', // 10 — verify bank balance
+        ]);
+    });
+    it('summary has non-empty apiCalls', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.summary.apiCalls.length).toBeGreaterThan(0);
+    });
+    it('mode is standalone', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.mode).toBe('standalone');
+    });
+});
+describe('generatePaymentRunBlueprint (defaults)', () => {
+    it('default currency is SGD', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.currency).toBe('SGD');
+    });
+    it('default period is current', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.period).toBe('current');
+    });
+});
+describe('generatePaymentRunBlueprint (options)', () => {
+    it('custom currency works', () => {
+        const bp = generatePaymentRunBlueprint({ currency: 'PHP' });
+        expect(bp.currency).toBe('PHP');
+    });
+    it('dueBefore filter is applied', () => {
+        const bp = generatePaymentRunBlueprint({ dueBefore: '2025-06-30' });
+        expect(bp.period).toBe('Due before 2025-06-30');
+        const step1 = bp.phases[0].steps[0];
+        const filters = step1.apiBody.filters;
+        expect(filters).toHaveProperty('dueDateTo', '2025-06-30');
+    });
+    it('dueBefore absent by default', () => {
+        const bp = generatePaymentRunBlueprint();
+        const step1 = bp.phases[0].steps[0];
+        const filters = step1.apiBody.filters;
+        expect(filters).not.toHaveProperty('dueDateTo');
+    });
+});
+describe('generatePaymentRunBlueprint (validation)', () => {
+    it('invalid dueBefore format throws JobValidationError', () => {
+        expect(() => generatePaymentRunBlueprint({ dueBefore: '30-06-2025' }))
+            .toThrow(JobValidationError);
+    });
+    it('malformed date throws JobValidationError', () => {
+        expect(() => generatePaymentRunBlueprint({ dueBefore: '2025/06/30' }))
+            .toThrow(JobValidationError);
+    });
+});
+describe('generatePaymentRunBlueprint (summary)', () => {
+    it('recipeReferences include bill-payment and fx-bill-payment', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.summary.recipeReferences).toContain('bill-payment');
+        expect(bp.summary.recipeReferences).toContain('fx-bill-payment');
+    });
+    it('calcReferences include jaz calc fx-reval', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.summary.calcReferences).toContain('jaz calc fx-reval');
+    });
+    it('apiCalls include key endpoints', () => {
+        const bp = generatePaymentRunBlueprint();
+        expect(bp.summary.apiCalls).toContain('POST /bills/search');
+        expect(bp.summary.apiCalls).toContain('POST /bills/{id}/payments');
+        expect(bp.summary.apiCalls).toContain('POST /generate-reports/ap-aging');
+        expect(bp.summary.apiCalls).toContain('POST /generate-reports/trial-balance');
+    });
+});

package/dist/__tests__/jobs-quarter-end.test.js

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import { generateQuarterEndBlueprint } from '../jobs/quarter-end.js';
+import { JobValidationError } from '../jobs/validate.js';
+describe('generateQuarterEndBlueprint', () => {
+    // Standalone mode (default)
+    describe('standalone mode', () => {
+        const base = { period: '2025-Q1' };
+        it('includes month-end phases for Jan, Feb, Mar plus quarterly extras and verification', () => {
+            const r = generateQuarterEndBlueprint(base);
+            // 3 months x 5 phases each = 15 month phases + Phase 6 (extras) + Phase 7 (verification)
+            expect(r.phases).toHaveLength(17);
+        });
+        it('has correct jobType', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.jobType).toBe('quarter-end-close');
+        });
+        it('mode is standalone', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.mode).toBe('standalone');
+        });
+        it('period label is "Q1 2025"', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.period).toBe('Q1 2025');
+        });
+        it('currency defaults to "SGD"', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.currency).toBe('SGD');
+        });
+        it('month-end phases are prefixed with month labels', () => {
+            const r = generateQuarterEndBlueprint(base);
+            // First 5 phases are Jan month-end
+            expect(r.phases[0].name).toContain('Jan 2025');
+            expect(r.phases[0].name).toContain('Phase 1');
+            // Phases 5-9 are Feb month-end
+            expect(r.phases[5].name).toContain('Feb 2025');
+            // Phases 10-14 are Mar month-end
+            expect(r.phases[10].name).toContain('Mar 2025');
+        });
+        it('quarterly extras is Phase 6', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const extras = r.phases[15];
+            expect(extras.name).toBe('Phase 6: Quarterly Extras');
+        });
+        it('quarterly verification is Phase 7', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const verification = r.phases[16];
+            expect(verification.name).toBe('Phase 7: Quarterly Verification');
+        });
+        it('quarterly extras has 5 steps', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const extras = r.phases[15];
+            expect(extras.steps).toHaveLength(5);
+        });
+        it('quarterly verification has 3 steps', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const verification = r.phases[16];
+            expect(verification.steps).toHaveLength(3);
+        });
+        it('each month group has internally continuous ordering 1..18', () => {
+            const r = generateQuarterEndBlueprint(base);
+            // Each of the 3 months has 5 phases x 18 steps with ordering 1..18
+            for (let m = 0; m < 3; m++) {
+                const monthPhases = r.phases.slice(m * 5, m * 5 + 5);
+                const orders = monthPhases.flatMap(p => p.steps.map(s => s.order));
+                for (let i = 0; i < orders.length; i++) {
+                    expect(orders[i]).toBe(i + 1);
+                }
+            }
+        });
+        it('quarterly extras ordering continues from last month max order', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const extras = r.phases[15];
+            // Month-end phases each have 18 steps; quarterly extras starts at 19
+            expect(extras.steps[0].order).toBe(19);
+        });
+        it('summary totalSteps matches actual step count', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const actual = r.phases.reduce((sum, p) => sum + p.steps.length, 0);
+            expect(r.summary.totalSteps).toBe(actual);
+        });
+        it('summary includes recipe references from both monthly and quarterly steps', () => {
+            const r = generateQuarterEndBlueprint(base);
+            // Monthly recipes
+            expect(r.summary.recipeReferences).toContain('accrued-expenses');
+            expect(r.summary.recipeReferences).toContain('bank-loan');
+            // Quarterly extras recipes
+            expect(r.summary.recipeReferences).toContain('bad-debt-provision');
+            expect(r.summary.recipeReferences).toContain('intercompany');
+            expect(r.summary.recipeReferences).toContain('provisions');
+        });
+        it('summary recipe references are sorted', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const sorted = [...r.summary.recipeReferences].sort();
+            expect(r.summary.recipeReferences).toEqual(sorted);
+        });
+    });
+    // Incremental mode
+    describe('incremental mode', () => {
+        const base = { period: '2025-Q1', incremental: true };
+        it('has only quarterly extras and verification phases (no month-end)', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.phases).toHaveLength(2);
+            expect(r.phases[0].name).toBe('Phase 6: Quarterly Extras');
+            expect(r.phases[1].name).toBe('Phase 7: Quarterly Verification');
+        });
+        it('mode is incremental', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.mode).toBe('incremental');
+        });
+        it('step ordering starts at 1 for extras', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.phases[0].steps[0].order).toBe(1);
+        });
+        it('step ordering is continuous across extras and verification', () => {
+            const r = generateQuarterEndBlueprint(base);
+            const allOrders = r.phases.flatMap(p => p.steps.map(s => s.order));
+            for (let i = 0; i < allOrders.length; i++) {
+                expect(allOrders[i]).toBe(i + 1);
+            }
+        });
+        it('total steps = 5 extras + 3 verification = 8', () => {
+            const r = generateQuarterEndBlueprint(base);
+            expect(r.summary.totalSteps).toBe(8);
+        });
+    });
+    // Q4 dates
+    it('"2025-Q4" has correct dates Oct-Dec', () => {
+        const r = generateQuarterEndBlueprint({ period: '2025-Q4' });
+        // Quarterly extras phase uses quarter-level dates
+        const extras = r.phases[r.phases.length - 2];
+        const gstStep = extras.steps[0];
+        expect(gstStep.apiBody.startDate).toBe('2025-10-01');
+        expect(gstStep.apiBody.endDate).toBe('2025-12-31');
+    });
+    // Quarterly verification reports reference correct dates
+    it('quarterly verification reports reference full quarter dates', () => {
+        const r = generateQuarterEndBlueprint({ period: '2025-Q2', incremental: true });
+        const verification = r.phases[1];
+        const trialBalance = verification.steps[0];
+        expect(trialBalance.apiBody.startDate).toBe('2025-04-01');
+        expect(trialBalance.apiBody.endDate).toBe('2025-06-30');
+    });
+    // Custom currency
+    it('custom currency "USD" passes through', () => {
+        const r = generateQuarterEndBlueprint({ period: '2025-Q1', currency: 'USD' });
+        expect(r.currency).toBe('USD');
+    });
+    // Validation
+    it('invalid period throws JobValidationError', () => {
+        expect(() => generateQuarterEndBlueprint({ period: 'bad' })).toThrow(JobValidationError);
+    });
+    it('Q5 throws JobValidationError', () => {
+        expect(() => generateQuarterEndBlueprint({ period: '2025-Q5' })).toThrow(JobValidationError);
+    });
+});

package/dist/__tests__/jobs-supplier-recon.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { generateSupplierReconBlueprint } from '../jobs/supplier-recon.js';
+describe('generateSupplierReconBlueprint (basic)', () => {
+    it('produces a valid JobBlueprint with correct jobType', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.jobType).toBe('supplier-recon');
+    });
+    it('has 4 phases and 7 total steps', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.phases).toHaveLength(4);
+        expect(bp.summary.totalSteps).toBe(7);
+    });
+    it('phase names are correct', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.phases.map(p => p.name)).toEqual([
+            'Pull AP Data',
+            'Compare Against Supplier Statement',
+            'Resolve Discrepancies',
+            'Verification',
+        ]);
+    });
+    it('step categories match expectations', () => {
+        const bp = generateSupplierReconBlueprint();
+        const categories = bp.phases.flatMap(p => p.steps.map(s => s.category));
+        expect(categories).toEqual([
+            'report', // 1 — AP aging report
+            'verify', // 2 — list bills for supplier
+            'verify', // 3 — match against statement
+            'review', // 4 — identify mismatches
+            'resolve', // 5 — create missing bills
+            'adjust', // 6 — record adjustments
+            'verify', // 7 — re-check AP aging
+        ]);
+    });
+    it('summary has non-empty apiCalls', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.summary.apiCalls.length).toBeGreaterThan(0);
+    });
+    it('mode is standalone', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.mode).toBe('standalone');
+    });
+});
+describe('generateSupplierReconBlueprint (defaults)', () => {
+    it('default currency is SGD', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.currency).toBe('SGD');
+    });
+    it('default period is current', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.period).toBe('current');
+    });
+});
+describe('generateSupplierReconBlueprint (options)', () => {
+    it('custom currency works', () => {
+        const bp = generateSupplierReconBlueprint({ currency: 'PHP' });
+        expect(bp.currency).toBe('PHP');
+    });
+    it('supplier filter is applied to bills search', () => {
+        const bp = generateSupplierReconBlueprint({ supplier: 'Acme Corp' });
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).toHaveProperty('supplierName', 'Acme Corp');
+    });
+    it('supplier filter absent by default', () => {
+        const bp = generateSupplierReconBlueprint();
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).not.toHaveProperty('supplierName');
+    });
+    it('supplier is reflected in AP aging notes', () => {
+        const bp = generateSupplierReconBlueprint({ supplier: 'Acme Corp' });
+        const step1 = bp.phases[0].steps[0];
+        expect(step1.notes).toContain('Acme Corp');
+    });
+    it('supplier is reflected in verification notes', () => {
+        const bp = generateSupplierReconBlueprint({ supplier: 'Acme Corp' });
+        const verifyStep = bp.phases[3].steps[0];
+        expect(verifyStep.notes).toContain('Acme Corp');
+    });
+    it('period filter is applied to bills search with correct end-of-month', () => {
+        const bp = generateSupplierReconBlueprint({ period: '2025-06' });
+        expect(bp.period).toBe('2025-06');
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).toHaveProperty('dateFrom', '2025-06-01');
+        expect(filters).toHaveProperty('dateTo', '2025-06-30');
+    });
+    it('period filter handles February correctly', () => {
+        const bp = generateSupplierReconBlueprint({ period: '2025-02' });
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).toHaveProperty('dateTo', '2025-02-28');
+    });
+    it('period filter absent by default', () => {
+        const bp = generateSupplierReconBlueprint();
+        const step2 = bp.phases[0].steps[1];
+        const filters = step2.apiBody.filters;
+        expect(filters).not.toHaveProperty('dateFrom');
+        expect(filters).not.toHaveProperty('dateTo');
+    });
+});
+describe('generateSupplierReconBlueprint (summary)', () => {
+    it('recipeReferences include standard-bill', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.summary.recipeReferences).toContain('standard-bill');
+    });
+    it('apiCalls include key endpoints', () => {
+        const bp = generateSupplierReconBlueprint();
+        expect(bp.summary.apiCalls).toContain('POST /generate-reports/ap-aging');
+        expect(bp.summary.apiCalls).toContain('POST /bills/search');
+        expect(bp.summary.apiCalls).toContain('POST /bills');
+        expect(bp.summary.apiCalls).toContain('POST /journals');
+    });
+});