noxctl 0.2.0 → 0.3.0

package/dist/cli.js

@@ -2,29 +2,65 @@
 import { Command, Option } from 'commander';
 import { readFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
-import { isJsonMode, outputList, outputDetail, outputConfirmation, formatTaxReport, formatFinancialReport, } from './formatter.js';
+import { isJsonMode, outputList, outputDetail, outputConfirmation, formatTaxReport, formatFinancialReport, errorEnvelope, } from './formatter.js';
 import { readActivePointer, readActivePointerOutcome, writeActivePointer, deleteActivePointer, readProfileIndex, resolveProfile, } from './profiles.js';
 import { setResolvedProfile } from './auth.js';
+import { applyPeriod } from './date-periods.js';
 import { DEFAULT_PROFILE, InvalidProfileNameError } from './profile-name.js';
-import { invoiceListColumns, invoiceDetailColumns, invoiceConfirmColumns, customerListColumns, customerDetailColumns, voucherListColumns, voucherDetailColumns, voucherRowColumns, accountListColumns, companyDetailColumns, articleListColumns, articleDetailColumns, supplierListColumns, supplierDetailColumns, supplierInvoiceListColumns, supplierInvoiceDetailColumns, supplierInvoiceConfirmColumns, invoicePaymentListColumns, invoicePaymentDetailColumns, supplierInvoicePaymentListColumns, supplierInvoicePaymentDetailColumns, offerListColumns, offerDetailColumns, orderListColumns, orderDetailColumns, projectListColumns, projectDetailColumns, costCenterListColumns, costCenterDetailColumns, taxReductionListColumns, taxReductionDetailColumns, priceListListColumns, priceListDetailColumns, priceListColumns, priceDetailColumns, } from './views.js';
+import { invoiceListColumns, invoiceDetailColumns, invoiceConfirmColumns, customerListColumns, customerDetailColumns, voucherListColumns, voucherDetailColumns, voucherRowColumns, accountListColumns, companyDetailColumns, articleListColumns, articleDetailColumns, supplierListColumns, supplierDetailColumns, supplierInvoiceListColumns, supplierInvoiceDetailColumns, supplierInvoiceConfirmColumns, invoicePaymentListColumns, invoicePaymentDetailColumns, supplierInvoicePaymentListColumns, supplierInvoicePaymentDetailColumns, offerListColumns, offerDetailColumns, orderListColumns, orderDetailColumns, projectListColumns, projectDetailColumns, costCenterListColumns, costCenterDetailColumns, taxReductionListColumns, taxReductionDetailColumns, priceListListColumns, priceListDetailColumns, priceListColumns, priceDetailColumns, financialYearListColumns, financialYearDetailColumns, lockedPeriodDetailColumns, contractListColumns, contractDetailColumns, topCustomerColumns, monthlyRevenueColumns, voucherAttachmentColumns, } from './views.js';
 const program = new Command();
 program
     .name('noxctl')
     .description('CLI and MCP server for Fortnox accounting')
-    .version('0.2.0')
-    .addOption(new Option('-o, --output <format>', 'Output format')
+    .version('0.3.0')
+    .addOption(new Option('-o, --output <format>', 'Output format (default: table on TTY, json when piped)')
     .choices(['json', 'table'])
     .default(undefined))
     .option('--profile <name>', 'Profile to operate on (overrides NOXCTL_PROFILE and active pointer)');
 function json() {
     return isJsonMode(program.opts());
 }
+// Suppress Commander's own plain-text usage errors (unknown command, missing
+// required option, ...) when in JSON mode, so the top-level catch can emit a
+// structured error envelope instead of leaving non-JSON on stderr. In table
+// mode, keep Commander's friendly usage message.
+//
+// Both configureOutput and exitOverride must be set HERE, before the command
+// tree is built: Commander only copies these settings into subcommands created
+// *after* they're configured on the parent. Set at the bottom, a subcommand's
+// parse error would call process.exit() directly and bypass the catch below
+// (leaving JSON-mode failures with no envelope).
+program.configureOutput({
+    outputError: (str, write) => {
+        if (!json())
+            write(str);
+    },
+});
+program.exitOverride();
+// Emit a fatal error honoring -o json mode (structured envelope to stderr) vs
+// plain text, then exit. Validation failures inside command actions must go
+// through this so they don't bypass the JSON error contract the way a bare
+// console.error would. The top-level catch handles thrown errors the same way;
+// this is for the cases where we want a specific non-1 exit code.
+function fail(message, exitCode = 1) {
+    if (json()) {
+        console.error(JSON.stringify(errorEnvelope(new Error(message)), null, 2));
+    }
+    else {
+        console.error(message);
+    }
+    process.exit(exitCode);
+}
+function fromToParams(opts) {
+    const { from, to } = applyPeriod(opts);
+    return { fromDate: from, toDate: to };
+}
 let resolvedProfileInfo = { name: DEFAULT_PROFILE, source: 'default' };
 export function getResolvedProfileInfo() {
     return resolvedProfileInfo;
 }
 // Commands that don't need (and shouldn't require) a resolved profile.
-const PROFILE_RESOLUTION_SKIP = new Set(['help']);
+const PROFILE_RESOLUTION_SKIP = new Set(['help', 'completion']);
 program.hook('preAction', async (thisCommand, actionCommand) => {
     const name = actionCommand.name();
     if (PROFILE_RESOLUTION_SKIP.has(name))
@@ -46,8 +82,7 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
         // loudly but continue so `doctor` / `profile use` can repair the state.
         const wouldRelyOnPointer = !flag && !env;
         if (wouldRelyOnPointer && name === 'serve') {
-            console.error(`Active profile pointer ${desc}. Refusing to start MCP server with ambiguous profile. Run \`noxctl doctor\` or set NOXCTL_PROFILE explicitly.`);
-            process.exit(2);
+            fail(`Active profile pointer ${desc}. Refusing to start MCP server with ambiguous profile. Run \`noxctl doctor\` or set NOXCTL_PROFILE explicitly.`, 2);
         }
         process.stderr.write(`[warning: active-profile pointer ${desc}; ignoring]\n`);
     }
@@ -56,8 +91,7 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     }
     catch (err) {
         if (err instanceof InvalidProfileNameError) {
-            console.error(err.message);
-            process.exit(2);
+            fail(err.message, 2);
         }
         throw err;
     }
@@ -108,6 +142,12 @@ async function confirmMutation(action, opts, payload) {
     }
     const company = await fetchCompanyHint();
     const suffix = company ? ` (${company})` : '';
+    // Show what will actually be sent so the user can verify before confirming.
+    if (payload !== undefined) {
+        console.log('Request payload:');
+        console.log(JSON.stringify(payload, null, 2));
+        console.log();
+    }
     const rl = createInterface({
         input: process.stdin,
         output: process.stdout,
@@ -120,6 +160,27 @@ async function confirmMutation(action, opts, payload) {
         rl.close();
     }
 }
+function requireDarwin() {
+    if (process.platform !== 'darwin') {
+        fail('The dedicated YubiKey-locked keychain is a macOS-only feature.', 2);
+    }
+}
+// Confirmation for local, irreversible operations (not Fortnox mutations).
+async function localConfirm(question, yes) {
+    if (yes)
+        return true;
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error('Confirmation required. Re-run with --yes.');
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        return ['y', 'yes'].includes(answer.trim().toLowerCase());
+    }
+    finally {
+        rl.close();
+    }
+}
 // --- init (interactive setup wizard) ---
 program
     .command('init')
@@ -541,6 +602,24 @@ program
             ? 'Windows DPAPI'
             : 'Linux Secret Service';
     pass('Credential store', storeBackend);
+    // 2a. Dedicated YubiKey-locked keychain (macOS only)
+    if (process.platform === 'darwin') {
+        const kt = await import('./keychain-target.js');
+        const activePath = kt.activeKeychainPath();
+        if (activePath) {
+            const state = kt.keychainLockState(activePath);
+            if (state === 'locked') {
+                fail('Dedicated keychain', 'locked — run `noxctl keychain unlock` (tap your YubiKey)');
+            }
+            else {
+                pass('Dedicated keychain', `active, ${state} (${activePath})`);
+            }
+            pass('ykman', kt.ykmanAvailable() ? 'installed' : 'not installed (brew install ykman)');
+        }
+        else {
+            pass('Dedicated keychain', 'not enabled (using login keychain)');
+        }
+    }
     // 2b. Profile resolution
     pass('Profile', `${resolvedProfileInfo.name} (source: ${resolvedProfileInfo.source})`);
     // 2c. Active pointer health — surface a corrupt pointer file even though
@@ -574,7 +653,19 @@ program
         // best-effort diagnostic — don't block doctor on filesystem issues
     }
     // 3. Credentials exist
-    const creds = await loadCredentials();
+    let creds;
+    try {
+        creds = await loadCredentials();
+    }
+    catch (err) {
+        const { KeychainLockedError } = await import('./keychain-target.js');
+        if (err instanceof KeychainLockedError) {
+            fail('Credentials', err.message);
+            console.log(`\n${ok ? 'All checks passed.' : 'Some checks failed.'}`);
+            return;
+        }
+        throw err;
+    }
     if (!creds) {
         fail('Credentials', `not found for profile "${resolvedProfileInfo.name}" — run \`noxctl init${resolvedProfileInfo.name === DEFAULT_PROFILE
             ? ''
@@ -636,6 +727,8 @@ program
         bookkeeping: 'vouchers?limit=1',
         companyinformation: 'companyinformation',
         settings: 'settings/company',
+        inbox: 'inbox',
+        connectfile: 'voucherfileconnections?limit=1',
     };
     const required = SCOPES.split(' ');
     const missing = [];
@@ -647,10 +740,13 @@ program
             await fortnoxRequest(endpoint);
         }
         catch (err) {
-            if (err instanceof FortnoxApiError && err.statusCode === 403) {
+            // A missing scope shows up as a 403, OR (for some endpoints, e.g. the
+            // archive/inbox family) a 400 whose message names the scope. Treat both
+            // as "not authorized"; other errors (500, etc.) aren't scope problems.
+            if (err instanceof FortnoxApiError &&
+                (err.statusCode === 403 || /scope/i.test(err.fortnoxMessage ?? ''))) {
                 missing.push(scope);
             }
-            // Non-403 errors (e.g. 500) are not scope problems — ignore here
         }
     }
     if (missing.length === 0) {
@@ -661,6 +757,245 @@ program
     }
     console.log(`\n${ok ? 'All checks passed.' : 'Some checks failed.'}`);
 });
+// --- keychain (dedicated YubiKey-locked credential store, macOS only) ---
+const keychain = program
+    .command('keychain')
+    .description('Manage the dedicated YubiKey-locked credential keychain (macOS)');
+keychain
+    .command('status')
+    .description('Show dedicated-keychain mode, lock state, and YubiKey availability')
+    .action(async () => {
+    const kt = await import('./keychain-target.js');
+    const onDarwin = process.platform === 'darwin';
+    console.log('Keychain status\n');
+    console.log(`  Platform          ${process.platform}${onDarwin ? '' : ' (dedicated keychain is macOS-only)'}`);
+    if (!onDarwin)
+        return;
+    const activePath = kt.activeKeychainPath();
+    const kcPath = activePath ?? kt.dedicatedKeychainPath();
+    const lockState = kt.keychainLockState(kcPath);
+    console.log(`  Dedicated mode    ${activePath ? 'active' : 'inactive (using login keychain)'}`);
+    console.log(`  Keychain file     ${kcPath} (${lockState})`);
+    console.log(`  Challenge file    ${kt.readChallenge() ? kt.challengeFilePath() : 'not present'}`);
+    console.log(`  ykman installed   ${kt.ykmanAvailable() ? 'yes' : 'no (brew install ykman)'}`);
+    console.log(`  YubiKey present   ${kt.yubikeyPresent() ? 'yes' : 'no'}`);
+    const enrolledSerial = kt.readEnrolledSerial();
+    console.log(`  Enrolled serial   ${enrolledSerial ?? 'not recorded'}`);
+    if (enrolledSerial) {
+        const mismatch = kt.diagnoseSerialMismatch(enrolledSerial, kt.listYubikeySerials());
+        if (mismatch)
+            console.log(`\n  ${mismatch}`);
+    }
+    if (activePath && lockState === 'locked') {
+        console.log('\n  Locked — run `noxctl keychain unlock` (tap your YubiKey).');
+    }
+});
+keychain
+    .command('unlock')
+    .description('Unlock the dedicated keychain for this session (tap your YubiKey)')
+    .action(async () => {
+    requireDarwin();
+    const kt = await import('./keychain-target.js');
+    const kcPath = kt.activeKeychainPath() ?? kt.dedicatedKeychainPath();
+    const state = kt.keychainLockState(kcPath);
+    if (state === 'missing') {
+        console.error('No dedicated keychain found. Run `noxctl keychain init` first.');
+        process.exit(1);
+    }
+    if (state === 'unlocked') {
+        console.log('Keychain is already unlocked.');
+        return;
+    }
+    const challenge = kt.readChallenge();
+    if (!challenge) {
+        console.error('Challenge file missing — cannot derive the unlock password. Re-run `noxctl keychain init`.');
+        process.exit(1);
+    }
+    // Preflight: a wrong/absent key is diagnosable from serials alone, before
+    // burning a tap on a challenge that can only fail.
+    const mismatch = kt.diagnoseSerialMismatch(kt.readEnrolledSerial(), kt.listYubikeySerials());
+    if (mismatch) {
+        console.error(mismatch);
+        process.exit(1);
+    }
+    console.log('Tap your YubiKey when it blinks...');
+    let password;
+    try {
+        password = kt.computeChallengeResponse(challenge);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    try {
+        kt.unlockDedicatedKeychain(kcPath, password);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    console.log('Keychain unlocked — open until your Mac sleeps.');
+});
+keychain
+    .command('lock')
+    .description('Lock the dedicated keychain now')
+    .action(async () => {
+    requireDarwin();
+    const kt = await import('./keychain-target.js');
+    const kcPath = kt.activeKeychainPath() ?? kt.dedicatedKeychainPath();
+    if (kt.keychainLockState(kcPath) === 'missing') {
+        console.error('No dedicated keychain found.');
+        process.exit(1);
+    }
+    kt.lockKeychain(kcPath);
+    console.log('Keychain locked.');
+});
+keychain
+    .command('init')
+    .description('Create the YubiKey-locked keychain and copy in existing credentials')
+    .action(async () => {
+    requireDarwin();
+    const kt = await import('./keychain-target.js');
+    if (!kt.ykmanAvailable()) {
+        console.error('ykman not found — install it with `brew install ykman`, then re-run.');
+        process.exit(1);
+    }
+    if (!kt.yubikeyPresent()) {
+        console.error('No YubiKey detected — insert it and re-run.');
+        process.exit(1);
+    }
+    const kcPath = kt.dedicatedKeychainPath();
+    if (kt.readChallenge()) {
+        console.error('Already initialized. Use `noxctl keychain unlock` or `noxctl keychain status`.');
+        process.exit(1);
+    }
+    if (kt.keychainLockState(kcPath) !== 'missing') {
+        console.error(`A keychain already exists at ${kcPath} but no challenge file is present.\n` +
+            `Remove the stale keychain (\`security delete-keychain "${kcPath}"\`) and re-run.`);
+        process.exit(1);
+    }
+    console.log('This creates a dedicated, lock-on-sleep keychain whose password is derived');
+    console.log('from your YubiKey (OTP slot 2 challenge-response). You unlock it once per');
+    console.log('session with a tap. Existing credentials are copied in; the login-keychain');
+    console.log('originals are left in place (run `noxctl keychain seal` to remove them later).');
+    console.log('');
+    console.log('Slot 2 must already be programmed: `ykman otp chalresp --generate --touch 2`.');
+    console.log('');
+    // Collect existing credentials from the LOGIN keychain BEFORE activating
+    // dedicated mode (challenge file absent -> activeKeychainPath() is null).
+    const { readProfileIndex } = await import('./profiles.js');
+    const { loadCredentialBlob, saveCredentialBlob } = await import('./credentials-store.js');
+    const idx = await readProfileIndex();
+    const names = new Set([DEFAULT_PROFILE, ...idx.profiles.map((p) => p.name)]);
+    const blobs = [];
+    for (const name of names) {
+        const { blob } = await loadCredentialBlob(name);
+        if (blob)
+            blobs.push({ profile: name, blob });
+    }
+    console.log(`Found ${blobs.length} credential set(s) to copy: ${blobs.map((b) => b.profile).join(', ') || '(none)'}`);
+    console.log('');
+    // Derive the keychain password from the YubiKey (requires a tap). Done
+    // before creating the keychain so a missed tap leaves nothing behind.
+    const challenge = kt.generateChallenge();
+    console.log('Tap your YubiKey when it blinks...');
+    let password;
+    try {
+        password = kt.computeChallengeResponse(challenge);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    const created = kt.createDedicatedKeychain(kcPath, password);
+    if (created === 'exists') {
+        console.error(`Unexpected: keychain already exists at ${kcPath}. Aborting.`);
+        process.exit(1);
+    }
+    kt.setLockOnSleep(kcPath);
+    // Activate dedicated mode: now activeKeychainPath() resolves to kcPath and
+    // saveCredentialBlob targets the new (still-unlocked) keychain.
+    kt.writeChallenge(challenge);
+    // Remember which physical key answered the enrollment challenge so unlock
+    // can distinguish "wrong key inserted" from "missed tap" later.
+    const serials = kt.listYubikeySerials();
+    if (serials.length === 1) {
+        kt.writeEnrolledSerial(serials[0]);
+        console.log(`Enrolled against YubiKey serial ${serials[0]}.`);
+    }
+    else if (serials.length > 1) {
+        console.log(`Multiple YubiKeys present (${serials.join(', ')}) — not recording an enrolled serial.`);
+    }
+    let copied = 0;
+    for (const { profile, blob } of blobs) {
+        try {
+            await saveCredentialBlob(blob, profile);
+            copied++;
+        }
+        catch (err) {
+            console.error(`  ! failed to copy "${profile}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    console.log('');
+    console.log(`Done. Created ${kcPath}, copied ${copied}/${blobs.length} credential set(s).`);
+    console.log('The keychain is unlocked now and will lock when your Mac sleeps.');
+    console.log('Next session: `noxctl keychain unlock` (one tap).');
+    console.log('When you trust it: `noxctl keychain seal` to delete the login-keychain copies.');
+});
+keychain
+    .command('seal')
+    .description('Delete the login-keychain credential copies left by `init` (irreversible)')
+    .option('--yes', 'Skip the confirmation prompt')
+    .action(async (opts) => {
+    requireDarwin();
+    const kt = await import('./keychain-target.js');
+    const activePath = kt.activeKeychainPath();
+    if (!activePath) {
+        console.error('Dedicated keychain mode is not active — nothing to seal. Run `noxctl keychain init` first.');
+        process.exit(1);
+    }
+    if (kt.keychainLockState(activePath) === 'locked') {
+        console.error('Dedicated keychain is locked — run `noxctl keychain unlock` first so the copies can be verified before the originals are deleted.');
+        process.exit(1);
+    }
+    const { readProfileIndex } = await import('./profiles.js');
+    const { LEGACY_KEYCHAIN_ACCOUNT, keychainAccount } = await import('./profile-name.js');
+    const { loadCredentialBlob } = await import('./credentials-store.js');
+    const idx = await readProfileIndex();
+    const uniqueNames = [
+        ...new Set([DEFAULT_PROFILE, ...idx.profiles.map((p) => p.name)].map((n) => n.toLowerCase())),
+    ];
+    // Verify the dedicated keychain actually holds each profile's creds before
+    // deleting the login originals — never strand the user with no copy.
+    const verified = [];
+    for (const name of uniqueNames) {
+        const { blob } = await loadCredentialBlob(name);
+        if (blob)
+            verified.push(name);
+    }
+    if (verified.length === 0) {
+        console.error('The dedicated keychain holds no credentials — refusing to delete the login copies.');
+        process.exit(1);
+    }
+    console.log(`Verified ${verified.length} credential set(s) in the dedicated keychain: ${verified.join(', ')}`);
+    const confirmed = await localConfirm('Delete the login-keychain copies now? This cannot be undone.', opts.yes);
+    if (!confirmed) {
+        console.log('Aborted. Login-keychain copies left in place.');
+        return;
+    }
+    // Accounts init may have written to the login keychain: the legacy
+    // "default" account plus profile:<name> for every known profile.
+    const accounts = new Set([LEGACY_KEYCHAIN_ACCOUNT]);
+    for (const name of uniqueNames)
+        accounts.add(keychainAccount(name));
+    let deleted = 0;
+    for (const account of accounts) {
+        if (kt.deleteLoginSecret(account))
+            deleted++;
+    }
+    console.log(`Deleted ${deleted} login-keychain entr${deleted === 1 ? 'y' : 'ies'}.`);
+    console.log('Credentials now live only in the YubiKey-locked keychain.');
+});
 // --- serve (default command) ---
 program
     .command('serve', { isDefault: true })
@@ -678,6 +1013,7 @@ invoices
     .option('--customer <number>', 'Filter by customer number')
     .option('--from <date>', 'From date (YYYY-MM-DD)')
     .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, this-quarter, last-quarter, this-month, last-month, ytd, this-year, last-year, or a bare year. Mutually exclusive with --from/--to.')
     .option('--page <number>', 'Page number', parseInt)
     .option('--limit <number>', 'Results per page', parseInt)
     .option('-a, --all', 'Fetch all pages')
@@ -686,8 +1022,7 @@ invoices
     const data = await listInvoices({
         filter: opts.filter,
         customerNumber: opts.customer,
-        fromDate: opts.from,
-        toDate: opts.to,
+        ...fromToParams(opts),
         page: opts.page,
         limit: opts.limit,
         all: opts.all,
@@ -701,7 +1036,7 @@ invoices
     .action(async (documentNumber) => {
     const { getInvoice } = await import('./operations/invoices.js');
     const data = await getInvoice(documentNumber);
-    outputDetail(data, invoiceDetailColumns, json());
+    outputDetail(data, invoiceDetailColumns, json(), 'Invoice');
 });
 invoices
     .command('create')
@@ -727,7 +1062,7 @@ Examples:
         return;
     }
     const data = await createInvoice(params);
-    outputDetail(data, invoiceDetailColumns, json());
+    outputDetail(data, invoiceDetailColumns, json(), 'Invoice');
 });
 invoices
     .command('update <documentNumber>')
@@ -747,7 +1082,7 @@ Examples:
         return;
     }
     const data = await updateInvoice(documentNumber, fields);
-    outputDetail(data, invoiceDetailColumns, json());
+    outputDetail(data, invoiceDetailColumns, json(), 'Invoice');
 });
 invoices
     .command('send <documentNumber>')
@@ -769,7 +1104,7 @@ invoices
         ? { subject: opts.subject, body: opts.body, bcc: opts.bcc }
         : undefined;
     const data = await sendInvoice(documentNumber, opts.method, emailOptions);
-    outputConfirmation(`Invoice ${documentNumber} sent via ${opts.method}.`, json(), data, invoiceConfirmColumns);
+    outputConfirmation(`Invoice ${documentNumber} sent via ${opts.method}.`, json(), data, invoiceConfirmColumns, 'Invoice');
 });
 invoices
     .command('bookkeep <documentNumber>')
@@ -782,7 +1117,7 @@ invoices
         return;
     }
     const data = await bookkeepInvoice(documentNumber);
-    outputConfirmation(`Invoice ${documentNumber} bookkeept.`, json(), data, invoiceConfirmColumns);
+    outputConfirmation(`Invoice ${documentNumber} bookkeept.`, json(), data, invoiceConfirmColumns, 'Invoice');
 });
 invoices
     .command('credit <documentNumber>')
@@ -795,21 +1130,26 @@ invoices
         return;
     }
     const data = await creditInvoice(documentNumber);
-    outputConfirmation(`Invoice ${documentNumber} credited.`, json(), data, invoiceConfirmColumns);
+    outputConfirmation(`Invoice ${documentNumber} credited.`, json(), data, invoiceConfirmColumns, 'Invoice');
 });
 // --- tax ---
 const tax = program.command('tax').description('Tax operations');
 tax
     .command('report')
     .description('Generate VAT tax report for a period')
-    .requiredOption('--from <date>', 'From date (YYYY-MM-DD)')
-    .requiredOption('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--from <date>', 'From date (YYYY-MM-DD)')
+    .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, this-quarter, last-quarter, this-month, last-month, ytd, this-year, last-year, or a bare year. Mutually exclusive with --from/--to.')
     .option('--year <number>', 'Financial year', parseInt)
     .action(async (opts) => {
     const { generateTaxReport } = await import('./operations/tax.js');
+    const range = fromToParams(opts);
+    if (!range.fromDate || !range.toDate) {
+        fail('tax report requires a period: --from/--to or --period.', 2);
+    }
     const data = await generateTaxReport({
-        fromDate: opts.from,
-        toDate: opts.to,
+        fromDate: range.fromDate,
+        toDate: range.toDate,
         financialYear: opts.year,
     });
     if (json()) {
@@ -830,12 +1170,12 @@ reports
     .option('--year <number>', 'Financial year', parseInt)
     .option('--from <date>', 'From date (YYYY-MM-DD)')
     .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, this-quarter, last-quarter, this-month, last-month, ytd, this-year, last-year, or a bare year. Mutually exclusive with --from/--to.')
     .action(async (opts) => {
     const { getIncomeStatement } = await import('./operations/financial-reports.js');
     const data = await getIncomeStatement({
         financialYear: opts.year,
-        fromDate: opts.from,
-        toDate: opts.to,
+        ...fromToParams(opts),
     });
     if (json()) {
         console.log(JSON.stringify(data, null, 2));
@@ -907,7 +1247,7 @@ customers
     .action(async (customerNumber) => {
     const { getCustomer } = await import('./operations/customers.js');
     const data = await getCustomer(customerNumber);
-    outputDetail(data, customerDetailColumns, json());
+    outputDetail(data, customerDetailColumns, json(), 'Customer');
 });
 customers
     .command('create')
@@ -932,7 +1272,7 @@ Examples:
         return;
     }
     const data = await createCustomer(params);
-    outputDetail(data, customerDetailColumns, json());
+    outputDetail(data, customerDetailColumns, json(), 'Customer');
 });
 customers
     .command('update <customerNumber>')
@@ -951,7 +1291,7 @@ Examples:
         return;
     }
     const data = await updateCustomer(customerNumber, fields);
-    outputDetail(data, customerDetailColumns, json());
+    outputDetail(data, customerDetailColumns, json(), 'Customer');
 });
 // --- articles ---
 const articles = program.command('articles').description('Article operations');
@@ -979,7 +1319,7 @@ articles
     .action(async (articleNumber) => {
     const { getArticle } = await import('./operations/articles.js');
     const data = await getArticle(articleNumber);
-    outputDetail(data, articleDetailColumns, json());
+    outputDetail(data, articleDetailColumns, json(), 'Article');
 });
 articles
     .command('create')
@@ -1007,7 +1347,7 @@ Examples:
         return;
     }
     const data = await createArticle(params);
-    outputDetail(data, articleDetailColumns, json());
+    outputDetail(data, articleDetailColumns, json(), 'Article');
 });
 articles
     .command('update <articleNumber>')
@@ -1026,7 +1366,7 @@ Examples:
         return;
     }
     const data = await updateArticle(articleNumber, fields);
-    outputDetail(data, articleDetailColumns, json());
+    outputDetail(data, articleDetailColumns, json(), 'Article');
 });
 // --- suppliers ---
 const suppliers = program.command('suppliers').description('Supplier operations');
@@ -1054,7 +1394,7 @@ suppliers
     .action(async (supplierNumber) => {
     const { getSupplier } = await import('./operations/suppliers.js');
     const data = await getSupplier(supplierNumber);
-    outputDetail(data, supplierDetailColumns, json());
+    outputDetail(data, supplierDetailColumns, json(), 'Supplier');
 });
 suppliers
     .command('create')
@@ -1079,7 +1419,7 @@ Examples:
         return;
     }
     const data = await createSupplier(params);
-    outputDetail(data, supplierDetailColumns, json());
+    outputDetail(data, supplierDetailColumns, json(), 'Supplier');
 });
 suppliers
     .command('update <supplierNumber>')
@@ -1098,7 +1438,7 @@ Examples:
         return;
     }
     const data = await updateSupplier(supplierNumber, fields);
-    outputDetail(data, supplierDetailColumns, json());
+    outputDetail(data, supplierDetailColumns, json(), 'Supplier');
 });
 // --- supplier-invoices ---
 const supplierInvoices = program
@@ -1112,6 +1452,7 @@ supplierInvoices
     .option('--supplier <number>', 'Filter by supplier number')
     .option('--from <date>', 'From date (YYYY-MM-DD)')
     .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, this-quarter, last-quarter, this-month, last-month, ytd, this-year, last-year, or a bare year. Mutually exclusive with --from/--to.')
     .option('--page <number>', 'Page number', parseInt)
     .option('--limit <number>', 'Results per page', parseInt)
     .option('-a, --all', 'Fetch all pages')
@@ -1120,8 +1461,7 @@ supplierInvoices
     const data = await listSupplierInvoices({
         filter: opts.filter,
         supplierNumber: opts.supplier,
-        fromDate: opts.from,
-        toDate: opts.to,
+        ...fromToParams(opts),
         page: opts.page,
         limit: opts.limit,
         all: opts.all,
@@ -1135,7 +1475,7 @@ supplierInvoices
     .action(async (givenNumber) => {
     const { getSupplierInvoice } = await import('./operations/supplier-invoices.js');
     const data = await getSupplierInvoice(givenNumber);
-    outputDetail(data, supplierInvoiceDetailColumns, json());
+    outputDetail(data, supplierInvoiceDetailColumns, json(), 'SupplierInvoice');
 });
 supplierInvoices
     .command('create')
@@ -1158,7 +1498,7 @@ Examples:
         return;
     }
     const data = await createSupplierInvoice(params);
-    outputDetail(data, supplierInvoiceDetailColumns, json());
+    outputDetail(data, supplierInvoiceDetailColumns, json(), 'SupplierInvoice');
 });
 supplierInvoices
     .command('bookkeep <givenNumber>')
@@ -1171,7 +1511,7 @@ supplierInvoices
         return;
     }
     const data = await bookkeepSupplierInvoice(givenNumber);
-    outputConfirmation(`Supplier invoice ${givenNumber} bookkeept.`, json(), data, supplierInvoiceConfirmColumns);
+    outputConfirmation(`Supplier invoice ${givenNumber} bookkeept.`, json(), data, supplierInvoiceConfirmColumns, 'SupplierInvoice');
 });
 // --- company ---
 const company = program.command('company').description('Company operations');
@@ -1181,7 +1521,7 @@ company
     .action(async () => {
     const { getCompanyInfo } = await import('./operations/company.js');
     const data = await getCompanyInfo();
-    outputDetail(data, companyDetailColumns, json());
+    outputDetail(data, companyDetailColumns, json(), 'CompanyInformation');
 });
 // --- vouchers ---
 const vouchers = program.command('vouchers').description('Voucher operations');
@@ -1191,6 +1531,7 @@ vouchers
     .option('--series <series>', 'Voucher series (e.g. "A")')
     .option('--from <date>', 'From date (YYYY-MM-DD)')
     .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, this-quarter, last-quarter, this-month, last-month, ytd, this-year, last-year, or a bare year. Mutually exclusive with --from/--to.')
     .option('--year <number>', 'Financial year', parseInt)
     .option('--page <number>', 'Page number', parseInt)
     .option('--limit <number>', 'Results per page', parseInt)
@@ -1199,8 +1540,7 @@ vouchers
     const { listVouchers } = await import('./operations/vouchers.js');
     const data = await listVouchers({
         series: opts.series,
-        fromDate: opts.from,
-        toDate: opts.to,
+        ...fromToParams(opts),
         financialYear: opts.year,
         page: opts.page,
         limit: opts.limit,
@@ -1217,7 +1557,7 @@ vouchers
     const { getVoucher } = await import('./operations/vouchers.js');
     const data = await getVoucher(series, voucherNumber, opts.year);
     if (json()) {
-        console.log(JSON.stringify(data, null, 2));
+        console.log(JSON.stringify({ Voucher: data }, null, 2));
     }
     else {
         outputDetail(data, voucherDetailColumns, false);
@@ -1247,7 +1587,35 @@ Examples:
         return;
     }
     const data = await createVoucher(params);
-    outputDetail(data, voucherDetailColumns, json());
+    outputDetail(data, voucherDetailColumns, json(), 'Voucher');
+});
+vouchers
+    .command('attach <series> <number> <files...>')
+    .description('Upload receipt/underlag files and link them to a voucher')
+    .option('--year <number>', 'Financial year (resolved from the voucher date if omitted)', parseInt)
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--dry-run', 'Preview without uploading')
+    .addHelpText('after', `
+Examples:
+  noxctl vouchers attach A 60 receipt.pdf
+  noxctl vouchers attach A 61 ica.pdf lunch.jpg --year 4`)
+    .action(async (series, voucherNumber, files, opts) => {
+    const { attachVoucherFiles } = await import('./operations/vouchers.js');
+    if (!(await confirmMutation(`Attach ${files.length} file(s) to voucher ${series}/${voucherNumber}`, opts, { files, year: opts.year }))) {
+        return;
+    }
+    const results = await attachVoucherFiles({
+        series,
+        voucherNumber,
+        filePaths: files,
+        financialYear: opts.year,
+    });
+    if (json()) {
+        console.log(JSON.stringify({ Attachments: results }, null, 2));
+    }
+    else {
+        outputList(results, voucherAttachmentColumns, false, results);
+    }
 });
 // --- invoice-payments ---
 const invoicePayments = program
@@ -1278,7 +1646,7 @@ invoicePayments
     .action(async (paymentNumber) => {
     const { getInvoicePayment } = await import('./operations/invoice-payments.js');
     const data = await getInvoicePayment(paymentNumber);
-    outputDetail(data, invoicePaymentDetailColumns, json());
+    outputDetail(data, invoicePaymentDetailColumns, json(), 'InvoicePayment');
 });
 invoicePayments
     .command('create')
@@ -1305,7 +1673,7 @@ Examples:
         return;
     }
     const data = await createInvoicePayment(params);
-    outputDetail(data, invoicePaymentDetailColumns, json());
+    outputDetail(data, invoicePaymentDetailColumns, json(), 'InvoicePayment');
 });
 invoicePayments
     .command('delete <paymentNumber>')
@@ -1318,7 +1686,7 @@ invoicePayments
         return;
     }
     await deleteInvoicePayment(paymentNumber);
-    outputConfirmation(`Invoice payment ${paymentNumber} deleted.`, json(), {});
+    outputConfirmation(`Invoice payment ${paymentNumber} deleted.`, json(), { Number: paymentNumber, deleted: true }, undefined, 'InvoicePayment');
 });
 invoicePayments
     .command('bookkeep <paymentNumber>')
@@ -1331,7 +1699,7 @@ invoicePayments
         return;
     }
     const result = await bookkeepInvoicePayment(paymentNumber);
-    outputConfirmation(`Invoice payment ${paymentNumber} bookkeept.`, json(), result);
+    outputConfirmation(`Invoice payment ${paymentNumber} bookkeept.`, json(), result, undefined, 'InvoicePayment');
 });
 // --- supplier-invoice-payments ---
 const supplierInvoicePayments = program
@@ -1362,7 +1730,7 @@ supplierInvoicePayments
     .action(async (paymentNumber) => {
     const { getSupplierInvoicePayment } = await import('./operations/supplier-invoice-payments.js');
     const data = await getSupplierInvoicePayment(paymentNumber);
-    outputDetail(data, supplierInvoicePaymentDetailColumns, json());
+    outputDetail(data, supplierInvoicePaymentDetailColumns, json(), 'SupplierInvoicePayment');
 });
 supplierInvoicePayments
     .command('create')
@@ -1387,7 +1755,7 @@ Examples:
         return;
     }
     const data = await createSupplierInvoicePayment(params);
-    outputDetail(data, supplierInvoicePaymentDetailColumns, json());
+    outputDetail(data, supplierInvoicePaymentDetailColumns, json(), 'SupplierInvoicePayment');
 });
 supplierInvoicePayments
     .command('delete <paymentNumber>')
@@ -1400,7 +1768,7 @@ supplierInvoicePayments
         return;
     }
     await deleteSupplierInvoicePayment(paymentNumber);
-    outputConfirmation(`Supplier invoice payment ${paymentNumber} deleted.`, json(), {});
+    outputConfirmation(`Supplier invoice payment ${paymentNumber} deleted.`, json(), { Number: paymentNumber, deleted: true }, undefined, 'SupplierInvoicePayment');
 });
 // --- offers ---
 const offers = program.command('offers').description('Offer/quote operations (offerter)');
@@ -1411,6 +1779,7 @@ offers
     .option('--customer <number>', 'Filter by customer number')
     .option('--from <date>', 'From date (YYYY-MM-DD)')
     .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, this-quarter, last-quarter, this-month, last-month, ytd, this-year, last-year, or a bare year. Mutually exclusive with --from/--to.')
     .option('--page <number>', 'Page number', parseInt)
     .option('--limit <number>', 'Results per page', parseInt)
     .option('-a, --all', 'Fetch all pages')
@@ -1419,8 +1788,7 @@ offers
     const data = await listOffers({
         filter: opts.filter,
         customerNumber: opts.customer,
-        fromDate: opts.from,
-        toDate: opts.to,
+        ...fromToParams(opts),
         page: opts.page,
         limit: opts.limit,
         all: opts.all,
@@ -1434,7 +1802,7 @@ offers
     .action(async (documentNumber) => {
     const { getOffer } = await import('./operations/offers.js');
     const data = await getOffer(documentNumber);
-    outputDetail(data, offerDetailColumns, json());
+    outputDetail(data, offerDetailColumns, json(), 'Offer');
 });
 offers
     .command('create')
@@ -1457,7 +1825,7 @@ Examples:
         return;
     }
     const data = await createOffer(params);
-    outputDetail(data, offerDetailColumns, json());
+    outputDetail(data, offerDetailColumns, json(), 'Offer');
 });
 offers
     .command('update <documentNumber>')
@@ -1473,7 +1841,7 @@ offers
         return;
     }
     const data = await updateOffer(documentNumber, fields);
-    outputDetail(data, offerDetailColumns, json());
+    outputDetail(data, offerDetailColumns, json(), 'Offer');
 });
 offers
     .command('create-invoice <documentNumber>')
@@ -1486,7 +1854,7 @@ offers
         return;
     }
     const data = await createInvoiceFromOffer(documentNumber);
-    outputConfirmation(`Invoice created from offer ${documentNumber}.`, json(), data, invoiceConfirmColumns);
+    outputConfirmation(`Invoice created from offer ${documentNumber}.`, json(), data, invoiceConfirmColumns, 'Invoice');
 });
 offers
     .command('create-order <documentNumber>')
@@ -1499,7 +1867,7 @@ offers
         return;
     }
     const data = await createOrderFromOffer(documentNumber);
-    outputConfirmation(`Order created from offer ${documentNumber}.`, json(), data);
+    outputConfirmation(`Order created from offer ${documentNumber}.`, json(), data, undefined, 'Order');
 });
 // --- orders ---
 const orders = program.command('orders').description('Order operations (ordrar)');
@@ -1510,6 +1878,7 @@ orders
     .option('--customer <number>', 'Filter by customer number')
     .option('--from <date>', 'From date (YYYY-MM-DD)')
     .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, this-quarter, last-quarter, this-month, last-month, ytd, this-year, last-year, or a bare year. Mutually exclusive with --from/--to.')
     .option('--page <number>', 'Page number', parseInt)
     .option('--limit <number>', 'Results per page', parseInt)
     .option('-a, --all', 'Fetch all pages')
@@ -1518,8 +1887,7 @@ orders
     const data = await listOrders({
         filter: opts.filter,
         customerNumber: opts.customer,
-        fromDate: opts.from,
-        toDate: opts.to,
+        ...fromToParams(opts),
         page: opts.page,
         limit: opts.limit,
         all: opts.all,
@@ -1533,7 +1901,7 @@ orders
     .action(async (documentNumber) => {
     const { getOrder } = await import('./operations/orders.js');
     const data = await getOrder(documentNumber);
-    outputDetail(data, orderDetailColumns, json());
+    outputDetail(data, orderDetailColumns, json(), 'Order');
 });
 orders
     .command('create')
@@ -1556,7 +1924,7 @@ Examples:
         return;
     }
     const data = await createOrder(params);
-    outputDetail(data, orderDetailColumns, json());
+    outputDetail(data, orderDetailColumns, json(), 'Order');
 });
 orders
     .command('update <documentNumber>')
@@ -1572,7 +1940,7 @@ orders
         return;
     }
     const data = await updateOrder(documentNumber, fields);
-    outputDetail(data, orderDetailColumns, json());
+    outputDetail(data, orderDetailColumns, json(), 'Order');
 });
 orders
     .command('create-invoice <documentNumber>')
@@ -1585,7 +1953,7 @@ orders
         return;
     }
     const data = await createInvoiceFromOrder(documentNumber);
-    outputConfirmation(`Invoice created from order ${documentNumber}.`, json(), data, invoiceConfirmColumns);
+    outputConfirmation(`Invoice created from order ${documentNumber}.`, json(), data, invoiceConfirmColumns, 'Invoice');
 });
 // --- projects ---
 const projects = program.command('projects').description('Project operations');
@@ -1611,7 +1979,7 @@ projects
     .action(async (projectNumber) => {
     const { getProject } = await import('./operations/projects.js');
     const data = await getProject(projectNumber);
-    outputDetail(data, projectDetailColumns, json());
+    outputDetail(data, projectDetailColumns, json(), 'Project');
 });
 projects
     .command('create')
@@ -1638,7 +2006,7 @@ projects
         return;
     }
     const data = await createProject(params);
-    outputDetail(data, projectDetailColumns, json());
+    outputDetail(data, projectDetailColumns, json(), 'Project');
 });
 projects
     .command('update <projectNumber>')
@@ -1654,7 +2022,7 @@ projects
         return;
     }
     const data = await updateProject(projectNumber, fields);
-    outputDetail(data, projectDetailColumns, json());
+    outputDetail(data, projectDetailColumns, json(), 'Project');
 });
 // --- cost centers ---
 const costcenters = program.command('costcenters').description('Cost center operations');
@@ -1680,7 +2048,7 @@ costcenters
     .action(async (code) => {
     const { getCostCenter } = await import('./operations/costcenters.js');
     const data = await getCostCenter(code);
-    outputDetail(data, costCenterDetailColumns, json());
+    outputDetail(data, costCenterDetailColumns, json(), 'CostCenter');
 });
 costcenters
     .command('create')
@@ -1706,7 +2074,7 @@ costcenters
         return;
     }
     const data = await createCostCenter(params);
-    outputDetail(data, costCenterDetailColumns, json());
+    outputDetail(data, costCenterDetailColumns, json(), 'CostCenter');
 });
 costcenters
     .command('update <code>')
@@ -1722,7 +2090,7 @@ costcenters
         return;
     }
     const data = await updateCostCenter(code, fields);
-    outputDetail(data, costCenterDetailColumns, json());
+    outputDetail(data, costCenterDetailColumns, json(), 'CostCenter');
 });
 costcenters
     .command('delete <code>')
@@ -1735,7 +2103,7 @@ costcenters
         return;
     }
     await deleteCostCenter(code);
-    console.log(`Cost center ${code} deleted.`);
+    outputConfirmation(`Cost center ${code} deleted.`, json(), { Code: code, deleted: true }, undefined, 'CostCenter');
 });
 // --- tax reductions (ROT/RUT) ---
 const taxreductions = program
@@ -1765,7 +2133,7 @@ taxreductions
     .action(async (id) => {
     const { getTaxReduction } = await import('./operations/taxreductions.js');
     const data = await getTaxReduction(parseInt(id, 10));
-    outputDetail(data, taxReductionDetailColumns, json());
+    outputDetail(data, taxReductionDetailColumns, json(), 'TaxReduction');
 });
 taxreductions
     .command('create')
@@ -1800,7 +2168,7 @@ taxreductions
         return;
     }
     const data = await createTaxReduction(params);
-    outputDetail(data, taxReductionDetailColumns, json());
+    outputDetail(data, taxReductionDetailColumns, json(), 'TaxReduction');
 });
 // --- price lists ---
 const pricelists = program.command('pricelists').description('Price list operations');
@@ -1826,7 +2194,7 @@ pricelists
     .action(async (code) => {
     const { getPriceList } = await import('./operations/pricelists.js');
     const data = await getPriceList(code);
-    outputDetail(data, priceListDetailColumns, json());
+    outputDetail(data, priceListDetailColumns, json(), 'PriceList');
 });
 pricelists
     .command('create')
@@ -1852,7 +2220,7 @@ pricelists
         return;
     }
     const data = await createPriceList(params);
-    outputDetail(data, priceListDetailColumns, json());
+    outputDetail(data, priceListDetailColumns, json(), 'PriceList');
 });
 pricelists
     .command('update <code>')
@@ -1868,7 +2236,7 @@ pricelists
         return;
     }
     const data = await updatePriceList(code, fields);
-    outputDetail(data, priceListDetailColumns, json());
+    outputDetail(data, priceListDetailColumns, json(), 'PriceList');
 });
 // --- prices ---
 const prices = program.command('prices').description('Price operations within price lists');
@@ -1899,7 +2267,7 @@ prices
     .action(async (opts) => {
     const { getPrice } = await import('./operations/pricelists.js');
     const data = await getPrice(opts.pricelist, opts.article, opts.fromQuantity);
-    outputDetail(data, priceDetailColumns, json());
+    outputDetail(data, priceDetailColumns, json(), 'Price');
 });
 prices
     .command('update')
@@ -1920,25 +2288,295 @@ prices
         return;
     }
     const data = await updatePrice(opts.pricelist, opts.article, fields, opts.fromQuantity);
-    outputDetail(data, priceDetailColumns, json());
+    outputDetail(data, priceDetailColumns, json(), 'Price');
 });
-// Error handling
-program.exitOverride();
+// --- contracts ---
+const contracts = program
+    .command('contracts')
+    .description('Contract operations (avtal — recurring invoicing)');
+contracts
+    .command('list')
+    .description('List/filter contracts')
+    .option('--filter <filter>', 'Filter: active, inactive, finished')
+    .option('--page <number>', 'Page number', parseInt)
+    .option('--limit <number>', 'Results per page', parseInt)
+    .option('-a, --all', 'Fetch all pages')
+    .action(async (opts) => {
+    const { listContracts } = await import('./operations/contracts.js');
+    const data = await listContracts({
+        filter: opts.filter,
+        page: opts.page,
+        limit: opts.limit,
+        all: opts.all,
+    });
+    outputList(data.Contracts ?? [], contractListColumns, json(), data, data.MetaInformation);
+});
+contracts
+    .command('get <documentNumber>')
+    .description('Get a single contract')
+    .action(async (documentNumber) => {
+    const { getContract } = await import('./operations/contracts.js');
+    const data = await getContract(documentNumber);
+    outputDetail(data, contractDetailColumns, json(), 'Contract');
+});
+contracts
+    .command('create')
+    .description('Create a contract (recurring invoicing)')
+    .requiredOption('--customer <number>', 'Customer number')
+    .requiredOption('--input <file>', 'Contract data as JSON file (or - for stdin)')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--dry-run', 'Preview the request without sending it')
+    .addHelpText('after', `
+Examples:
+  echo '{"InvoiceRows":[{"Description":"Hosting","DeliveredQuantity":1,"Price":500,"AccountNumber":3001,"VAT":25}],"PeriodStart":"2026-07-01","PeriodEnd":"2027-06-30","InvoiceInterval":3,"ContractLength":12}' | noxctl contracts create --customer 25 --input - --dry-run`)
+    .action(async (opts) => {
+    const { createContract } = await import('./operations/contracts.js');
+    const raw = opts.input === '-' ? readFileSync(0, 'utf-8') : readFileSync(opts.input, 'utf-8');
+    const input = JSON.parse(raw);
+    const params = { CustomerNumber: opts.customer, ...input };
+    if (!(await confirmMutation(`Create contract for customer ${opts.customer}`, opts, {
+        Contract: params,
+    }))) {
+        return;
+    }
+    const data = await createContract(params);
+    outputDetail(data, contractDetailColumns, json(), 'Contract');
+});
+contracts
+    .command('update <documentNumber>')
+    .description('Update a contract')
+    .requiredOption('--input <file>', 'Fields to update as JSON file (or - for stdin)')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--dry-run', 'Preview the request without sending it')
+    .action(async (documentNumber, opts) => {
+    const { updateContract } = await import('./operations/contracts.js');
+    const raw = opts.input === '-' ? readFileSync(0, 'utf-8') : readFileSync(opts.input, 'utf-8');
+    const fields = JSON.parse(raw);
+    if (!(await confirmMutation(`Update contract ${documentNumber}`, opts, { Contract: fields }))) {
+        return;
+    }
+    const data = await updateContract(documentNumber, fields);
+    outputDetail(data, contractDetailColumns, json(), 'Contract');
+});
+contracts
+    .command('finish <documentNumber>')
+    .description('Finish a contract — no further invoices will be created')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--dry-run', 'Preview the action without sending it')
+    .action(async (documentNumber, opts) => {
+    const { finishContract } = await import('./operations/contracts.js');
+    if (!(await confirmMutation(`Finish contract ${documentNumber}`, opts))) {
+        return;
+    }
+    const data = await finishContract(documentNumber);
+    outputConfirmation(`Contract ${documentNumber} finished.`, json(), data, contractDetailColumns, 'Contract');
+});
+contracts
+    .command('create-invoice <documentNumber>')
+    .description('Create the next invoice from a contract immediately')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--dry-run', 'Preview the action without sending it')
+    .action(async (documentNumber, opts) => {
+    const { createInvoiceFromContract } = await import('./operations/contracts.js');
+    if (!(await confirmMutation(`Create invoice from contract ${documentNumber}`, opts))) {
+        return;
+    }
+    const data = await createInvoiceFromContract(documentNumber);
+    outputConfirmation(`Invoice created from contract ${documentNumber}.`, json(), data, invoiceConfirmColumns, 'Invoice');
+});
+contracts
+    .command('increase-invoice-count <documentNumber>')
+    .description('Extend a non-continuous contract by one invoice')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--dry-run', 'Preview the action without sending it')
+    .action(async (documentNumber, opts) => {
+    const { increaseInvoiceCount } = await import('./operations/contracts.js');
+    if (!(await confirmMutation(`Increase invoice count for contract ${documentNumber}`, opts))) {
+        return;
+    }
+    const data = await increaseInvoiceCount(documentNumber);
+    outputConfirmation(`Invoice count increased for contract ${documentNumber}.`, json(), data, contractDetailColumns, 'Contract');
+});
+// --- financial years ---
+const financialYears = program
+    .command('financial-years')
+    .description('Financial year and locked period operations');
+financialYears
+    .command('list')
+    .description('List financial years (räkenskapsår)')
+    .option('--date <date>', 'Find the financial year containing this date (YYYY-MM-DD)')
+    .action(async (opts) => {
+    const { listFinancialYears } = await import('./operations/financial-years.js');
+    const data = await listFinancialYears({ date: opts.date });
+    outputList(data.FinancialYears ?? [], financialYearListColumns, json(), data, data.MetaInformation);
+});
+financialYears
+    .command('get <id>')
+    .description('Get a single financial year')
+    .action(async (id) => {
+    const { getFinancialYear } = await import('./operations/financial-years.js');
+    const data = await getFinancialYear(parseInt(id, 10));
+    outputDetail(data, financialYearDetailColumns, json(), 'FinancialYear');
+});
+financialYears
+    .command('locked-period')
+    .description('Show the locked period (bokföring låst t.o.m.)')
+    .action(async () => {
+    const { getLockedPeriod } = await import('./operations/financial-years.js');
+    const data = await getLockedPeriod();
+    if (json()) {
+        console.log(JSON.stringify({ LockedPeriod: data }, null, 2));
+        return;
+    }
+    if (!data.EndDate) {
+        console.log('No period is locked.');
+        return;
+    }
+    outputDetail(data, lockedPeriodDetailColumns, false);
+});
+// --- analytics ---
+const analytics = program
+    .command('analytics')
+    .description('Precomputed analytics views (overdue, unpaid, top customers, VAT)');
+analytics
+    .command('overdue')
+    .description('Overdue invoices summary')
+    .action(async () => {
+    const { getOverdueSummary } = await import('./operations/analytics.js');
+    const summary = await getOverdueSummary();
+    if (json()) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    if (summary.count === 0) {
+        console.log('No overdue invoices.');
+        return;
+    }
+    console.log(`Overdue: ${summary.count} invoice(s), ${summary.totalBalance.toFixed(2)} outstanding. Oldest due ${summary.oldestDueDate}.\n`);
+    outputList(summary.invoices, invoiceListColumns, false, summary.invoices);
+});
+analytics
+    .command('unpaid')
+    .description('Unpaid totals (outstanding receivables)')
+    .action(async () => {
+    const { getUnpaidTotals } = await import('./operations/analytics.js');
+    const s = await getUnpaidTotals();
+    if (json()) {
+        console.log(JSON.stringify(s, null, 2));
+        return;
+    }
+    console.log(`Unpaid:  ${s.count} invoice(s), ${s.totalBalance.toFixed(2)} outstanding.`);
+    console.log(`Overdue: ${s.overdueCount} invoice(s), ${s.overdueBalance.toFixed(2)}.`);
+});
+analytics
+    .command('top-customers')
+    .description('Top customers by invoiced amount')
+    .option('--from <date>', 'From date (YYYY-MM-DD)')
+    .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, last-quarter, ytd, ... Mutually exclusive with --from/--to.')
+    .option('--limit <number>', 'Number of customers (default 10)', parseInt)
+    .action(async (opts) => {
+    const { getTopCustomers } = await import('./operations/analytics.js');
+    const range = fromToParams(opts);
+    const result = await getTopCustomers({
+        fromDate: range.fromDate,
+        toDate: range.toDate,
+        limit: opts.limit,
+    });
+    if (json()) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    outputList(result.customers.map((c) => ({ ...c })), topCustomerColumns, false, result.customers);
+});
+analytics
+    .command('vat')
+    .description('VAT summary for a period (net VAT position)')
+    .option('--from <date>', 'From date (YYYY-MM-DD)')
+    .option('--to <date>', 'To date (YYYY-MM-DD)')
+    .option('--period <period>', 'Natural period (calendar-year): Q1, 2025-Q3, march/mars, last-quarter, ytd, ... Mutually exclusive with --from/--to.')
+    .option('--year <number>', 'Financial year', parseInt)
+    .action(async (opts) => {
+    const { getVatSummary } = await import('./operations/analytics.js');
+    const range = fromToParams(opts);
+    if (!range.fromDate || !range.toDate) {
+        fail('analytics vat requires a period: --from/--to or --period.', 2);
+    }
+    const summary = await getVatSummary({
+        fromDate: range.fromDate,
+        toDate: range.toDate,
+        financialYear: opts.year,
+    });
+    if (json()) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    console.log(formatTaxReport(summary));
+    console.log(`\nNet VAT: ${summary.netVat.toFixed(2)} (negative = owed to Skatteverket)`);
+});
+// --- dashboard ---
+program
+    .command('dashboard')
+    .description('At-a-glance summary: recent invoices, outstanding, overdue, monthly revenue')
+    .option('--months <number>', 'Months of revenue history (default 6)', parseInt)
+    .action(async (opts) => {
+    const { getDashboard } = await import('./operations/analytics.js');
+    const dash = await getDashboard({ months: opts.months });
+    if (json()) {
+        console.log(JSON.stringify(dash, null, 2));
+        return;
+    }
+    console.log('OUTSTANDING');
+    console.log(`  Unpaid:  ${dash.unpaid.count} invoice(s), ${dash.unpaid.totalBalance.toFixed(2)}`);
+    console.log(`  Overdue: ${dash.overdue.count} invoice(s), ${dash.overdue.totalBalance.toFixed(2)}` +
+        (dash.overdue.oldestDueDate ? ` (oldest due ${dash.overdue.oldestDueDate})` : ''));
+    if (dash.overdue.count > 0) {
+        console.log('\nOVERDUE INVOICES');
+        outputList(dash.overdue.invoices, invoiceListColumns, false, dash.overdue.invoices);
+    }
+    console.log('\nRECENT INVOICES');
+    outputList(dash.recentInvoices, invoiceListColumns, false, dash.recentInvoices);
+    console.log('\nMONTHLY INVOICED');
+    outputList(dash.monthlyRevenue.map((m) => ({ ...m })), monthlyRevenueColumns, false, dash.monthlyRevenue);
+});
+// --- completion ---
+program
+    .command('completion <shell>')
+    .description('Generate shell completion script (bash, zsh, fish)')
+    .addHelpText('after', `
+Examples:
+  noxctl completion bash > /usr/local/etc/bash_completion.d/noxctl
+  noxctl completion zsh > "\${fpath[1]}/_noxctl"
+  noxctl completion fish > ~/.config/fish/completions/noxctl.fish`)
+    .action(async (shell) => {
+    const { extractCommandTree, renderCompletion } = await import('./completions.js');
+    console.log(renderCompletion(shell, extractCommandTree(program)));
+});
+// Error handling (configureOutput + exitOverride set above, before the command
+// tree, so subcommands inherit them).
 try {
     await program.parseAsync(process.argv);
 }
 catch (err) {
-    if (err instanceof Error && 'code' in err) {
-        const code = err.code;
-        // Commander throws for --help and --version with exitCode 0
-        if (code === 'commander.helpDisplayed' || code === 'commander.version') {
-            process.exit(0);
-        }
-        if (code === 'commander.unknownCommand' || code === 'commander.missingMandatoryOptionValue') {
-            process.exit(1);
-        }
+    const code = err instanceof Error && 'code' in err ? err.code : undefined;
+    // Commander throws these for --help and --version after writing output; exit 0.
+    if (code === 'commander.helpDisplayed' || code === 'commander.version') {
+        process.exit(0);
+    }
+    // Commander parse errors (unknownCommand, missingMandatoryOptionValue,
+    // excessArguments, ...) carry a `commander.*` code. configureOutput above
+    // already wrote their plain-text usage message in table mode, so we must not
+    // print it again here; in JSON mode that output was suppressed, so we emit
+    // the structured envelope below instead.
+    const isCommanderParseError = typeof code === 'string' && code.startsWith('commander.');
+    if (json()) {
+        // Structured mode fails structured: scripted callers branch on .error
+        // instead of string-scraping stderr.
+        console.error(JSON.stringify(errorEnvelope(err), null, 2));
+    }
+    else if (!isCommanderParseError) {
+        console.error(err instanceof Error ? err.message : err);
     }
-    console.error(err instanceof Error ? err.message : err);
     process.exit(1);
 }
 //# sourceMappingURL=cli.js.map