jaz-cli 2.7.0 → 2.8.0

package/dist/__tests__/jobs-validate.test.js

@@ -0,0 +1,181 @@
+import { describe, it, expect } from 'vitest';
+import { parseMonthPeriod, parseQuarterPeriod, parseYearPeriod, validateDateString, validateOverdueDays, JobValidationError, } from '../jobs/validate.js';
+describe('parseMonthPeriod', () => {
+    it('parses "2025-01" → Jan 2025 with correct dates', () => {
+        const r = parseMonthPeriod('2025-01');
+        expect(r.type).toBe('month');
+        expect(r.year).toBe(2025);
+        expect(r.month).toBe(1);
+        expect(r.startDate).toBe('2025-01-01');
+        expect(r.endDate).toBe('2025-01-31');
+        expect(r.label).toBe('Jan 2025');
+    });
+    it('parses "2025-12" → Dec 2025 with correct dates', () => {
+        const r = parseMonthPeriod('2025-12');
+        expect(r.type).toBe('month');
+        expect(r.year).toBe(2025);
+        expect(r.month).toBe(12);
+        expect(r.startDate).toBe('2025-12-01');
+        expect(r.endDate).toBe('2025-12-31');
+        expect(r.label).toBe('Dec 2025');
+    });
+    it('handles February in a leap year', () => {
+        const r = parseMonthPeriod('2024-02');
+        expect(r.endDate).toBe('2024-02-29');
+    });
+    it('handles February in a non-leap year', () => {
+        const r = parseMonthPeriod('2025-02');
+        expect(r.endDate).toBe('2025-02-28');
+    });
+    it('rejects month 13 with JobValidationError', () => {
+        expect(() => parseMonthPeriod('2025-13')).toThrow(JobValidationError);
+    });
+    it('rejects non-date string "abc"', () => {
+        expect(() => parseMonthPeriod('abc')).toThrow(JobValidationError);
+    });
+    it('rejects single-digit month "2025-1"', () => {
+        expect(() => parseMonthPeriod('2025-1')).toThrow(JobValidationError);
+    });
+    it('rejects month 00', () => {
+        expect(() => parseMonthPeriod('2025-00')).toThrow(JobValidationError);
+    });
+});
+describe('parseQuarterPeriod', () => {
+    it('parses "2025-Q1" → Jan-Mar 2025', () => {
+        const r = parseQuarterPeriod('2025-Q1');
+        expect(r.type).toBe('quarter');
+        expect(r.year).toBe(2025);
+        expect(r.quarter).toBe(1);
+        expect(r.startDate).toBe('2025-01-01');
+        expect(r.endDate).toBe('2025-03-31');
+        expect(r.label).toBe('Q1 2025');
+        expect(r.months).toHaveLength(3);
+        expect(r.months[0].month).toBe(1);
+        expect(r.months[1].month).toBe(2);
+        expect(r.months[2].month).toBe(3);
+    });
+    it('parses "2025-Q4" → Oct-Dec 2025', () => {
+        const r = parseQuarterPeriod('2025-Q4');
+        expect(r.type).toBe('quarter');
+        expect(r.year).toBe(2025);
+        expect(r.quarter).toBe(4);
+        expect(r.startDate).toBe('2025-10-01');
+        expect(r.endDate).toBe('2025-12-31');
+        expect(r.label).toBe('Q4 2025');
+        expect(r.months).toHaveLength(3);
+        expect(r.months[0].month).toBe(10);
+        expect(r.months[1].month).toBe(11);
+        expect(r.months[2].month).toBe(12);
+    });
+    it('parses "2025-Q2" → Apr-Jun 2025', () => {
+        const r = parseQuarterPeriod('2025-Q2');
+        expect(r.startDate).toBe('2025-04-01');
+        expect(r.endDate).toBe('2025-06-30');
+    });
+    it('is case-insensitive for the Q prefix', () => {
+        const r = parseQuarterPeriod('2025-q3');
+        expect(r.quarter).toBe(3);
+        expect(r.startDate).toBe('2025-07-01');
+    });
+    it('rejects Q5 with JobValidationError', () => {
+        expect(() => parseQuarterPeriod('2025-Q5')).toThrow(JobValidationError);
+    });
+    it('rejects Q0 with JobValidationError', () => {
+        expect(() => parseQuarterPeriod('2025-q0')).toThrow(JobValidationError);
+    });
+    it('rejects invalid format "2025Q1"', () => {
+        expect(() => parseQuarterPeriod('2025Q1')).toThrow(JobValidationError);
+    });
+    it('each month in the quarter has correct start and end dates', () => {
+        const r = parseQuarterPeriod('2025-Q1');
+        expect(r.months[0].startDate).toBe('2025-01-01');
+        expect(r.months[0].endDate).toBe('2025-01-31');
+        expect(r.months[1].startDate).toBe('2025-02-01');
+        expect(r.months[1].endDate).toBe('2025-02-28');
+        expect(r.months[2].startDate).toBe('2025-03-01');
+        expect(r.months[2].endDate).toBe('2025-03-31');
+    });
+});
+describe('parseYearPeriod', () => {
+    it('parses "2025" → full year Jan-Dec with 4 quarters', () => {
+        const r = parseYearPeriod('2025');
+        expect(r.type).toBe('year');
+        expect(r.year).toBe(2025);
+        expect(r.startDate).toBe('2025-01-01');
+        expect(r.endDate).toBe('2025-12-31');
+        expect(r.label).toBe('FY2025');
+        expect(r.quarters).toHaveLength(4);
+    });
+    it('quarters span the correct months', () => {
+        const r = parseYearPeriod('2025');
+        expect(r.quarters[0].startDate).toBe('2025-01-01');
+        expect(r.quarters[0].endDate).toBe('2025-03-31');
+        expect(r.quarters[1].startDate).toBe('2025-04-01');
+        expect(r.quarters[1].endDate).toBe('2025-06-30');
+        expect(r.quarters[2].startDate).toBe('2025-07-01');
+        expect(r.quarters[2].endDate).toBe('2025-09-30');
+        expect(r.quarters[3].startDate).toBe('2025-10-01');
+        expect(r.quarters[3].endDate).toBe('2025-12-31');
+    });
+    it('each quarter has 3 months', () => {
+        const r = parseYearPeriod('2025');
+        for (const q of r.quarters) {
+            expect(q.months).toHaveLength(3);
+        }
+    });
+    it('rejects non-numeric string "abcd"', () => {
+        expect(() => parseYearPeriod('abcd')).toThrow(JobValidationError);
+    });
+    it('rejects partial year "25"', () => {
+        expect(() => parseYearPeriod('25')).toThrow(JobValidationError);
+    });
+    it('rejects YYYY-MM format "2025-01"', () => {
+        expect(() => parseYearPeriod('2025-01')).toThrow(JobValidationError);
+    });
+});
+describe('validateDateString', () => {
+    it('accepts a valid date "2025-06-15"', () => {
+        expect(() => validateDateString('2025-06-15', 'testDate')).not.toThrow();
+    });
+    it('accepts undefined (optional field)', () => {
+        expect(() => validateDateString(undefined, 'testDate')).not.toThrow();
+    });
+    it('rejects "not-a-date"', () => {
+        expect(() => validateDateString('not-a-date', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects invalid month "2025-13-01"', () => {
+        expect(() => validateDateString('2025-13-01', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects impossible calendar date "2025-02-31"', () => {
+        expect(() => validateDateString('2025-02-31', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects impossible calendar date "2025-06-31"', () => {
+        expect(() => validateDateString('2025-06-31', 'testDate')).toThrow(JobValidationError);
+    });
+    it('rejects wrong format "06/15/2025"', () => {
+        expect(() => validateDateString('06/15/2025', 'testDate')).toThrow(JobValidationError);
+    });
+    it('error message includes the field name', () => {
+        expect(() => validateDateString('bad', 'myField')).toThrow(/myField/);
+    });
+});
+describe('validateOverdueDays', () => {
+    it('accepts a valid positive integer 30', () => {
+        expect(() => validateOverdueDays(30)).not.toThrow();
+    });
+    it('accepts 1 (minimum valid)', () => {
+        expect(() => validateOverdueDays(1)).not.toThrow();
+    });
+    it('rejects 0', () => {
+        expect(() => validateOverdueDays(0)).toThrow(JobValidationError);
+    });
+    it('rejects negative values', () => {
+        expect(() => validateOverdueDays(-1)).toThrow(JobValidationError);
+    });
+    it('rejects non-integer 1.5', () => {
+        expect(() => validateOverdueDays(1.5)).toThrow(JobValidationError);
+    });
+    it('rejects non-integer 0.5', () => {
+        expect(() => validateOverdueDays(0.5)).toThrow(JobValidationError);
+    });
+});

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

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { generateYearEndBlueprint } from '../jobs/year-end.js';
+import { JobValidationError } from '../jobs/validate.js';
+describe('generateYearEndBlueprint', () => {
+    // Standalone mode (default)
+    describe('standalone mode', () => {
+        const base = { period: '2025' };
+        it('includes all quarterly phases plus annual extras and verification', () => {
+            const r = generateYearEndBlueprint(base);
+            // 4 quarters x 17 phases each (15 month-end + 2 quarterly) = 68
+            // + Phase 8 (annual extras) + Phase 9 (annual verification) = 70
+            expect(r.phases.length).toBeGreaterThan(0);
+            // Last two phases are annual extras and verification
+            const last = r.phases[r.phases.length - 1];
+            const secondLast = r.phases[r.phases.length - 2];
+            expect(secondLast.name).toBe('Phase 8: Annual Extras');
+            expect(last.name).toBe('Phase 9: Annual Verification');
+        });
+        it('has correct jobType', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.jobType).toBe('year-end-close');
+        });
+        it('mode is standalone', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.mode).toBe('standalone');
+        });
+        it('period label is "FY2025"', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.period).toBe('FY2025');
+        });
+        it('currency defaults to "SGD"', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.currency).toBe('SGD');
+        });
+        it('phase names are prefixed with quarter labels', () => {
+            const r = generateYearEndBlueprint(base);
+            // First batch of phases should contain Q1 prefix
+            expect(r.phases[0].name).toContain('Q1 2025');
+        });
+        it('annual extras has 7 steps', () => {
+            const r = generateYearEndBlueprint(base);
+            const extras = r.phases[r.phases.length - 2];
+            expect(extras.name).toBe('Phase 8: Annual Extras');
+            expect(extras.steps).toHaveLength(7);
+        });
+        it('annual verification has 3 steps', () => {
+            const r = generateYearEndBlueprint(base);
+            const verification = r.phases[r.phases.length - 1];
+            expect(verification.name).toBe('Phase 9: Annual Verification');
+            expect(verification.steps).toHaveLength(3);
+        });
+        it('annual extras ordering continues from last quarterly max order', () => {
+            const r = generateYearEndBlueprint(base);
+            // Each quarter ends with quarterly verification at order 26
+            // Annual extras starts at 27
+            const extras = r.phases[r.phases.length - 2];
+            expect(extras.steps[0].order).toBe(27);
+        });
+        it('annual verification follows annual extras ordering', () => {
+            const r = generateYearEndBlueprint(base);
+            const extras = r.phases[r.phases.length - 2];
+            const verification = r.phases[r.phases.length - 1];
+            const lastExtraOrder = extras.steps[extras.steps.length - 1].order;
+            expect(verification.steps[0].order).toBe(lastExtraOrder + 1);
+        });
+        it('summary totalSteps matches actual step count', () => {
+            const r = generateYearEndBlueprint(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 monthly, quarterly, and annual steps', () => {
+            const r = generateYearEndBlueprint(base);
+            // Monthly recipe
+            expect(r.summary.recipeReferences).toContain('accrued-expenses');
+            // Quarterly recipe
+            expect(r.summary.recipeReferences).toContain('intercompany');
+            // Annual recipe
+            expect(r.summary.recipeReferences).toContain('dividend');
+        });
+        it('summary recipe references are sorted', () => {
+            const r = generateYearEndBlueprint(base);
+            const sorted = [...r.summary.recipeReferences].sort();
+            expect(r.summary.recipeReferences).toEqual(sorted);
+        });
+        it('annual extras API calls use full year dates', () => {
+            const r = generateYearEndBlueprint(base);
+            const extras = r.phases[r.phases.length - 2];
+            const gstStep = extras.steps.find(s => s.description.includes('GST'));
+            expect(gstStep).toBeDefined();
+            expect(gstStep.apiBody.startDate).toBe('2025-01-01');
+            expect(gstStep.apiBody.endDate).toBe('2025-12-31');
+        });
+        it('annual verification reports use full year dates', () => {
+            const r = generateYearEndBlueprint(base);
+            const verification = r.phases[r.phases.length - 1];
+            const trialBalance = verification.steps[0];
+            expect(trialBalance.apiBody.startDate).toBe('2025-01-01');
+            expect(trialBalance.apiBody.endDate).toBe('2025-12-31');
+        });
+    });
+    // Incremental mode
+    describe('incremental mode', () => {
+        const base = { period: '2025', incremental: true };
+        it('has only annual extras and verification (no quarter/month phases)', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.phases).toHaveLength(2);
+            expect(r.phases[0].name).toBe('Phase 8: Annual Extras');
+            expect(r.phases[1].name).toBe('Phase 9: Annual Verification');
+        });
+        it('mode is incremental', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.mode).toBe('incremental');
+        });
+        it('step ordering starts at 1 for extras', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.phases[0].steps[0].order).toBe(1);
+        });
+        it('step ordering is continuous across extras and verification', () => {
+            const r = generateYearEndBlueprint(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 = 7 extras + 3 verification = 10', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.summary.totalSteps).toBe(10);
+        });
+        it('annual extras has 7 steps', () => {
+            const r = generateYearEndBlueprint(base);
+            expect(r.phases[0].steps).toHaveLength(7);
+        });
+    });
+    // Custom currency
+    it('custom currency "MYR" passes through', () => {
+        const r = generateYearEndBlueprint({ period: '2025', currency: 'MYR' });
+        expect(r.currency).toBe('MYR');
+    });
+    // Validation
+    it('invalid period throws JobValidationError', () => {
+        expect(() => generateYearEndBlueprint({ period: 'bad' })).toThrow(JobValidationError);
+    });
+    it('"2025-Q1" is not a valid year period', () => {
+        expect(() => generateYearEndBlueprint({ period: '2025-Q1' })).toThrow(JobValidationError);
+    });
+    it('"abcd" throws JobValidationError', () => {
+        expect(() => generateYearEndBlueprint({ period: 'abcd' })).toThrow(JobValidationError);
+    });
+});

package/dist/commands/jobs.js

@@ -0,0 +1,184 @@
+import chalk from 'chalk';
+import { generateMonthEndBlueprint } from '../jobs/month-end.js';
+import { generateQuarterEndBlueprint } from '../jobs/quarter-end.js';
+import { generateYearEndBlueprint } from '../jobs/year-end.js';
+import { generateBankReconBlueprint } from '../jobs/bank-recon.js';
+import { generateGstVatBlueprint } from '../jobs/gst-vat.js';
+import { generatePaymentRunBlueprint } from '../jobs/payment-run.js';
+import { generateCreditControlBlueprint } from '../jobs/credit-control.js';
+import { generateSupplierReconBlueprint } from '../jobs/supplier-recon.js';
+import { generateAuditPrepBlueprint } from '../jobs/audit-prep.js';
+import { generateFaReviewBlueprint } from '../jobs/fa-review.js';
+import { printBlueprint, printBlueprintJson } from '../jobs/format.js';
+import { JobValidationError } from '../jobs/validate.js';
+/** Wrap job action with validation error handling. */
+function jobAction(fn) {
+    return (opts) => {
+        try {
+            fn(opts);
+        }
+        catch (err) {
+            if (err instanceof JobValidationError) {
+                console.error(chalk.red(`Error: ${err.message}`));
+                process.exit(1);
+            }
+            throw err;
+        }
+    };
+}
+export function registerJobsCommand(program) {
+    const jobs = program
+        .command('jobs')
+        .description('Accounting job blueprints — month-end, quarter-end, year-end, bank-recon, gst-vat, payment-run, credit-control, supplier-recon, audit-prep, fa-review');
+    // ── jaz jobs month-end ──────────────────────────────────────────
+    jobs
+        .command('month-end')
+        .description('Month-end close blueprint (5 phases, 18 steps)')
+        .requiredOption('--period <YYYY-MM>', 'Month period (e.g., 2025-01)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateMonthEndBlueprint({
+            period: opts.period,
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs quarter-end ────────────────────────────────────────
+    jobs
+        .command('quarter-end')
+        .description('Quarter-end close blueprint (monthly × 3 + quarterly extras)')
+        .requiredOption('--period <YYYY-QN>', 'Quarter period (e.g., 2025-Q1)')
+        .option('--incremental', 'Generate only quarterly extras (assumes months already closed)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateQuarterEndBlueprint({
+            period: opts.period,
+            currency: opts.currency,
+            incremental: opts.incremental,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs year-end ───────────────────────────────────────────
+    jobs
+        .command('year-end')
+        .description('Year-end close blueprint (quarterly × 4 + annual extras)')
+        .requiredOption('--period <YYYY>', 'Fiscal year (e.g., 2025)')
+        .option('--incremental', 'Generate only annual extras (assumes quarters already closed)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateYearEndBlueprint({
+            period: opts.period,
+            currency: opts.currency,
+            incremental: opts.incremental,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs bank-recon ─────────────────────────────────────────
+    jobs
+        .command('bank-recon')
+        .description('Bank reconciliation catch-up blueprint')
+        .option('--account <name>', 'Specific bank account name')
+        .option('--period <YYYY-MM>', 'Month period to reconcile')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateBankReconBlueprint({
+            account: opts.account,
+            period: opts.period,
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs gst-vat ────────────────────────────────────────────
+    jobs
+        .command('gst-vat')
+        .description('GST/VAT filing preparation blueprint')
+        .requiredOption('--period <YYYY-QN>', 'Quarter period (e.g., 2025-Q1)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateGstVatBlueprint({
+            period: opts.period,
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs payment-run ────────────────────────────────────────
+    jobs
+        .command('payment-run')
+        .description('Payment run blueprint (bulk bill payments)')
+        .option('--due-before <YYYY-MM-DD>', 'Pay bills due on or before this date')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generatePaymentRunBlueprint({
+            dueBefore: opts.dueBefore,
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs credit-control ─────────────────────────────────────
+    jobs
+        .command('credit-control')
+        .description('Credit control / AR chase blueprint')
+        .option('--overdue-days <days>', 'Minimum overdue days to include', (v) => {
+        const n = Number.parseInt(v, 10);
+        if (!Number.isFinite(n))
+            throw new JobValidationError(`overdue-days must be an integer (got "${v}")`);
+        return n;
+    })
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateCreditControlBlueprint({
+            overdueDays: opts.overdueDays,
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs supplier-recon ─────────────────────────────────────
+    jobs
+        .command('supplier-recon')
+        .description('Supplier statement reconciliation blueprint')
+        .option('--supplier <name>', 'Specific supplier name')
+        .option('--period <YYYY-MM>', 'Month period')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateSupplierReconBlueprint({
+            supplier: opts.supplier,
+            period: opts.period,
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs audit-prep ─────────────────────────────────────────
+    jobs
+        .command('audit-prep')
+        .description('Audit preparation pack blueprint')
+        .requiredOption('--period <YYYY>', 'Fiscal year (e.g., 2025)')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateAuditPrepBlueprint({
+            period: opts.period,
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+    // ── jaz jobs fa-review ──────────────────────────────────────────
+    jobs
+        .command('fa-review')
+        .description('Fixed asset register review blueprint')
+        .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
+        .option('--json', 'Output as JSON')
+        .action(jobAction((opts) => {
+        const bp = generateFaReviewBlueprint({
+            currency: opts.currency,
+        });
+        opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
+    }));
+}

package/dist/index.js

@@ -7,6 +7,7 @@ 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 { registerJobsCommand } from './commands/jobs.js';
 import { SKILL_TYPES } from './types/index.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -51,4 +52,5 @@ program
     });
 });
 registerCalcCommand(program);
+registerJobsCommand(program);
 program.parse();