jaz-clio 4.34.6 → 4.35.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.34.6
+version: 4.35.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 117 production gotchas, error

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 4.34.6
+version: 4.35.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.34.6
+version: 4.35.0
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 4.34.6
+version: 4.35.0
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 4.34.6
+version: 4.35.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires

package/dist/commands/api-action.js

@@ -1,15 +1,23 @@
-import chalk from 'chalk';
 import { JazClient, JazApiError } from '../core/api/client.js';
 import { requireAuth, AuthError, resolvedProfileLabel, resolvedAuthSource, getProfile, listProfiles } from '../core/auth/index.js';
 import { isMachineFormat } from './output.js';
+import { renderOrgBanner } from './ui/banner.js';
+import { formatApiError, formatAuthError, formatGenericError } from './ui/error.js';
 /**
  * Shared action wrapper for all online CLI commands.
- * Handles auth resolution, client creation, org banner, and error formatting.
+ * Handles auth resolution, client creation, org banner, spinner, and error formatting.
  *
  * Exit codes: 1 = validation, 2 = API error, 3 = auth error.
  */
 export function apiAction(fn) {
     return async (opts) => {
+        let spinner;
+        // Hoist machine flag — computed once, safe to use in catch even if resolveFormat would throw
+        let machine = false;
+        try {
+            machine = isMachineFormat(opts);
+        }
+        catch { /* --json + --format conflict — treat as human mode for error display */ }
         try {
             // Conflict check: --api-key and --org are mutually exclusive
             if (opts.apiKey && opts.org) {
@@ -17,9 +25,8 @@ export function apiAction(fn) {
             }
             const auth = requireAuth(opts.apiKey);
             const client = new JazClient(auth);
-            // Org banner — show which org we're hitting (suppressed in machine formats)
-            // Visual guard: yellow warning when unpinned + multi-org, dim banner otherwise
-            if (!isMachineFormat(opts)) {
+            // Org banner — stderr, suppressed in machine formats
+            if (!machine) {
                 const label = resolvedProfileLabel();
                 if (label) {
                     const entry = getProfile(label);
@@ -31,43 +38,36 @@ export function apiAction(fn) {
                             orgCount = Object.keys(listProfiles() ?? {}).length;
                         }
                         catch { /* best-effort */ }
-                        if (!isPinned && orgCount > 1) {
-                            // UNPINNED multi-org: prominent yellow warning
-                            process.stderr.write(chalk.yellow(`  \u26A0 ${label} \u00B7 ${entry.orgName} (${entry.currency})`) +
-                                chalk.dim(` \u2014 not pinned to this terminal\n`) +
-                                chalk.dim(`    Pin: export JAZ_ORG=${label}  or  --org ${label}\n`));
-                        }
-                        else {
-                            // Pinned or single-org: normal dim banner
-                            process.stderr.write(chalk.dim(`  \u25B8 ${label} \u00B7 ${entry.orgName} (${entry.currency})\n`));
-                        }
+                        renderOrgBanner({ label, orgName: entry.orgName, currency: entry.currency }, isPinned, orgCount > 1);
                     }
                 }
             }
             await fn(client, opts, auth);
         }
         catch (err) {
-            const machine = isMachineFormat(opts);
             if (err instanceof AuthError) {
                 if (machine)
-                    console.log(JSON.stringify({ error: { code: 'AUTH_ERROR', message: err.message } }));
+                    console.error(JSON.stringify({ error: { code: 'AUTH_ERROR', message: err.message } }));
                 else
-                    console.error(chalk.red(`Error: ${err.message}`));
+                    console.error(formatAuthError(err.message));
                 process.exit(3);
             }
             if (err instanceof JazApiError) {
                 if (machine)
-                    console.log(JSON.stringify({ error: { code: 'API_ERROR', status: err.status, message: err.message } }));
+                    console.error(JSON.stringify({ error: { code: 'API_ERROR', status: err.status, message: err.message } }));
                 else
-                    console.error(chalk.red(`API Error (${err.status}): ${err.message}`));
+                    console.error(formatApiError(err.status, err.message, err.endpoint));
                 process.exit(2);
             }
             const message = err.message;
             if (machine)
-                console.log(JSON.stringify({ error: { code: 'UNKNOWN_ERROR', message } }));
+                console.error(JSON.stringify({ error: { code: 'UNKNOWN_ERROR', message } }));
             else
-                console.error(chalk.red(`Error: ${message}`));
+                console.error(formatGenericError(message));
             process.exit(2);
         }
+        finally {
+            spinner?.stop();
+        }
     };
 }

package/dist/commands/auth.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import prompts from 'prompts';
+import * as p from '@clack/prompts';
 import { clearStoredCredentials, requireAuth, getProfile, setProfile, removeProfile, getActiveLabel, setActiveLabel, listProfiles, findLabelByApiKey, resolvedAuthSource, } from '../core/auth/index.js';
 import { JazClient } from '../core/api/client.js';
 import { getOrganization } from '../core/api/organization.js';
@@ -118,19 +118,21 @@ export function registerAuthCommand(program) {
                 console.error(chalk.red('Error: --json and --export require a label argument.'));
                 process.exit(1);
             }
+            if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                console.error(chalk.red('Error: interactive picker requires a TTY. Provide a label argument.'));
+                process.exit(1);
+            }
             const active = getActiveLabel();
-            const response = await prompts({
-                type: 'select',
-                name: 'label',
+            const selected = await p.select({
                 message: 'Switch to:',
-                choices: labels.map(l => ({
-                    title: `${l === active ? '\u2605 ' : '  '}${l} \u2014 ${orgs[l].orgName} (${orgs[l].currency})`,
+                options: labels.map(l => ({
+                    label: `${l === active ? '\u2605 ' : '  '}${l} \u2014 ${orgs[l].orgName} (${orgs[l].currency})`,
                     value: l,
                 })),
             });
-            if (!response.label)
+            if (p.isCancel(selected))
                 return; // User cancelled
-            target = response.label;
+            target = selected;
         }
         try {
             setActiveLabel(target);

package/dist/commands/format-helpers.js

@@ -1,35 +1,44 @@
-import chalk from 'chalk';
+import { success, danger, warning, muted, accent } from './ui/theme.js';
 const STATUS_COLORS = {
-    DRAFT: chalk.yellow,
-    VOID: chalk.red,
-    VOIDED: chalk.red,
-    FAILED: chalk.red,
-    DELETED: chalk.red,
+    DRAFT: warning,
+    VOID: danger,
+    VOIDED: danger,
+    FAILED: danger,
+    DELETED: danger,
 };
 export function formatStatus(status) {
     const s = status || 'UNKNOWN';
-    return (STATUS_COLORS[s] ?? chalk.green)(s);
+    return (STATUS_COLORS[s] ?? success)(s);
 }
 // ── Shared column formatters (DRY across all command files) ─────
-/** Format a resource ID in cyan. */
+/** Format a resource ID in accent color. */
 export function formatId(v) {
-    return chalk.cyan(String(v));
+    return accent(String(v));
 }
 /** Format a reference field, showing '(no ref)' for empty values. */
 export function formatReference(v) {
-    return String(v || '(no ref)');
+    return String(v || muted('(no ref)'));
 }
-/** Format a currency amount to 2 decimal places. */
+/** Format a currency amount to 2 decimal places. Preserves decimal string precision. */
 export function formatCurrency(v) {
-    return v != null ? `$${Number(v).toFixed(2)}` : '-';
+    if (v == null || v === '')
+        return muted('-');
+    const s = String(v);
+    // If already a valid decimal string, format without binary float conversion
+    if (/^-?\d+(\.\d+)?$/.test(s)) {
+        const [int, dec] = s.split('.');
+        return `$${int}.${(dec ?? '').padEnd(2, '0').slice(0, 2)}`;
+    }
+    const n = Number(v);
+    return Number.isNaN(n) ? muted('-') : `$${n.toFixed(2)}`;
 }
 /** Format a payment direction as colored IN/OUT. */
 export function formatDirection(v) {
-    return String(v) === 'PAYIN' ? chalk.green('IN') : chalk.red('OUT');
+    return String(v) === 'PAYIN' ? success('IN') : danger('OUT');
 }
 /** Format an epoch-ms timestamp as YYYY-MM-DD. */
 export function formatEpochDate(v) {
     if (typeof v !== 'number' || v === 0 || Number.isNaN(v))
-        return '-';
+        return muted('-');
     return new Date(v).toISOString().slice(0, 10);
 }

package/dist/commands/init.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import ora from 'ora';
-import prompts from 'prompts';
+import * as p from '@clack/prompts';
 import { SKILL_DESCRIPTIONS } from '../types/index.js';
 import { installSkills, detectPlatform } from '../utils/template.js';
 import { logger } from '../utils/logger.js';
@@ -9,49 +9,47 @@ export async function initCommand(options) {
     let skillType = options.skill ?? 'all';
     // Prompt for skill selection if not specified
     if (!options.skill) {
-        const response = await prompts({
-            type: 'select',
-            name: 'skill',
+        const skill = await p.select({
             message: 'Which skills do you want to install?',
-            choices: [
+            options: [
                 {
-                    title: `All (Recommended)`,
-                    description: 'API reference + CLI + data conversion + transaction recipes + accounting jobs',
+                    label: 'All (Recommended)',
+                    hint: 'API reference + CLI + data conversion + transaction recipes + accounting jobs',
                     value: 'all',
                 },
                 {
-                    title: 'API only',
-                    description: SKILL_DESCRIPTIONS['jaz-api'],
+                    label: 'API only',
+                    hint: SKILL_DESCRIPTIONS['jaz-api'],
                     value: 'jaz-api',
                 },
                 {
-                    title: 'CLI only',
-                    description: SKILL_DESCRIPTIONS['jaz-cli'],
+                    label: 'CLI only',
+                    hint: SKILL_DESCRIPTIONS['jaz-cli'],
                     value: 'jaz-cli',
                 },
                 {
-                    title: 'Conversion only',
-                    description: SKILL_DESCRIPTIONS['jaz-conversion'],
+                    label: 'Conversion only',
+                    hint: SKILL_DESCRIPTIONS['jaz-conversion'],
                     value: 'jaz-conversion',
                 },
                 {
-                    title: 'Transaction Recipes only',
-                    description: SKILL_DESCRIPTIONS['jaz-recipes'],
+                    label: 'Transaction Recipes only',
+                    hint: SKILL_DESCRIPTIONS['jaz-recipes'],
                     value: 'jaz-recipes',
                 },
                 {
-                    title: 'Jobs only',
-                    description: SKILL_DESCRIPTIONS['jaz-jobs'],
+                    label: 'Jobs only',
+                    hint: SKILL_DESCRIPTIONS['jaz-jobs'],
                     value: 'jaz-jobs',
                 },
             ],
-            initial: 0,
+            initialValue: 'all',
         });
-        if (!response.skill) {
+        if (p.isCancel(skill)) {
             logger.warn('Installation cancelled');
             return;
         }
-        skillType = response.skill;
+        skillType = skill;
     }
     const skillLabel = skillType === 'all'
         ? 'jaz-api + jaz-cli + jaz-conversion + jaz-recipes + jaz-jobs'

package/dist/commands/jobs.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import prompts from 'prompts';
+import * as p from '@clack/prompts';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { generateMonthEndBlueprint } from '../core/jobs/month-end/blueprint.js';
@@ -93,16 +93,16 @@ async function resolveBankFormat(opts) {
     if (selected.length === 0) {
         // Interactive: prompt for format in TTY
         if (process.stdin.isTTY && !opts.json) {
-            const { format } = await prompts({
-                type: 'select',
-                name: 'format',
+            const format = await p.select({
                 message: 'Bank format',
-                choices: [
-                    { title: 'DBS GIRO (IDEAL UFF — CSV)', value: 'dbs-giro' },
-                    { title: 'OCBC GIRO/FAST (fixed-width 1000 chars)', value: 'ocbc-giro' },
-                    { title: 'UOB GIRO (tilde-delimited UFF)', value: 'uob-giro' },
+                options: [
+                    { label: 'DBS GIRO (IDEAL UFF — CSV)', value: 'dbs-giro' },
+                    { label: 'OCBC GIRO/FAST (fixed-width 1000 chars)', value: 'ocbc-giro' },
+                    { label: 'UOB GIRO (tilde-delimited UFF)', value: 'uob-giro' },
                 ],
-            }, { onCancel: () => process.exit(0) });
+            });
+            if (p.isCancel(format))
+                process.exit(0);
             return format;
         }
         throw new BankFileValidationError('No bank format specified. Pick one:\n\n' +
@@ -126,12 +126,12 @@ async function resolveBankFormat(opts) {
  * a pre-filled bank-file JSON input.
  */
 async function fetchOutstandingForBankFile(opts, format) {
-    const { fetch: doFetch } = await prompts({
-        type: 'confirm',
-        name: 'fetch',
+    const doFetch = await p.confirm({
         message: 'No input file. Fetch outstanding bills from API?',
-        initial: true,
-    }, { onCancel: () => process.exit(0) });
+        initialValue: true,
+    });
+    if (p.isCancel(doFetch))
+        process.exit(0);
     if (!doFetch) {
         throw new BankFileValidationError('No input provided. Use --input <file> or pipe JSON via stdin.\n\n' +
             `Sample JSON for ${format}:\n` +
@@ -190,40 +190,44 @@ async function fetchOutstandingForBankFile(opts, format) {
         value: s.contactResourceId,
         selected: true,
     }));
-    const { selected } = await prompts({
-        type: 'multiselect',
-        name: 'selected',
+    const selected = await p.multiselect({
         message: 'Select suppliers to pay',
-        choices,
-        hint: '- Space to toggle, Enter to confirm',
-    }, { onCancel: () => process.exit(0) });
+        options: choices.map(c => ({
+            label: c.title,
+            value: c.value,
+        })),
+        initialValues: choices.map(c => c.value),
+        required: true,
+    });
+    if (p.isCancel(selected))
+        process.exit(0);
     if (!selected || selected.length === 0) {
         throw new BankFileValidationError('No suppliers selected.');
     }
     const selectedSet = new Set(selected);
     const selectedSuppliers = outstanding.suppliers.filter(s => selectedSet.has(s.contactResourceId));
     // Prompt for originator details
-    const originatorAnswers = await prompts([
-        {
-            type: 'text',
-            name: 'accountNumber',
-            message: 'Originator account number',
-            validate: (v) => v.trim().length > 0 || 'Required',
-        },
-        {
-            type: 'text',
-            name: 'accountName',
-            message: 'Originator company name',
-            validate: (v) => v.trim().length > 0 || 'Required',
-        },
-        {
-            type: 'text',
-            name: 'valueDate',
-            message: 'Value date (YYYY-MM-DD)',
-            initial: new Date().toISOString().slice(0, 10),
-            validate: (v) => /^\d{4}-\d{2}-\d{2}$/.test(v) || 'Format: YYYY-MM-DD',
-        },
-    ], { onCancel: () => process.exit(0) });
+    const accountNumber = await p.text({
+        message: 'Originator account number',
+        validate: (v) => (!v || v.trim().length === 0) ? 'Required' : undefined,
+    });
+    if (p.isCancel(accountNumber))
+        process.exit(0);
+    const accountName = await p.text({
+        message: 'Originator company name',
+        validate: (v) => (!v || v.trim().length === 0) ? 'Required' : undefined,
+    });
+    if (p.isCancel(accountName))
+        process.exit(0);
+    const valueDate = await p.text({
+        message: 'Value date (YYYY-MM-DD)',
+        placeholder: new Date().toISOString().slice(0, 10),
+        defaultValue: new Date().toISOString().slice(0, 10),
+        validate: (v) => !/^\d{4}-\d{2}-\d{2}$/.test(v ?? '') ? 'Format: YYYY-MM-DD' : undefined,
+    });
+    if (p.isCancel(valueDate))
+        process.exit(0);
+    const originatorAnswers = { accountNumber, accountName, valueDate };
     // Build the bank-file input structure
     // NOTE: payee.accountNumber and payee.bankCode are NOT available from the API.
     // We use placeholders — user must fill them in or the generator will validate.
@@ -725,12 +729,10 @@ export function registerJobsCommand(program) {
             // Interactive mode — prompt user for each encrypted file
             console.error(chalk.yellow(`\n${needPassword.length} encrypted PDF(s) need a password:\n`));
             for (const f of needPassword) {
-                const { password } = await prompts({
-                    type: 'text',
-                    name: 'password',
+                const password = await p.text({
                     message: `PDF password for ${f.folder}/${f.filename}`,
                 });
-                if (!password) {
+                if (p.isCancel(password) || !password) {
                     console.error(chalk.red('Aborted — no password provided.'));
                     console.error(chalk.dim('Tip: embed password in filename to skip prompts: filename__pw__password.pdf'));
                     process.exit(1);

package/dist/commands/magic.js

@@ -3,7 +3,7 @@ import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:f
 import { formatStatus } from './format-helpers.js';
 import { basename, extname, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
-import prompts from 'prompts';
+import * as p from '@clack/prompts';
 import { createFromAttachment, searchMagicWorkflows, waitForWorkflows, } from '../core/api/magic.js';
 import { extractFilePassword, isPdfEncrypted, isQpdfAvailable, decryptPdf, cleanupDecryptedFile, } from '../core/jobs/document-collection/tools/ingest/decrypt.js';
 import { extractZipToDir, flattenSingleRoot } from '../core/jobs/document-collection/tools/ingest/cloud/zip.js';
@@ -298,17 +298,15 @@ async function resolveInputPdf(filePath, ext, opts) {
             }));
             process.exit(1);
         }
-        const response = await prompts({
-            type: 'text',
-            name: 'password',
+        const pwInput = await p.text({
             message: `PDF password for ${rawName}`,
         });
-        if (!response.password) {
+        if (p.isCancel(pwInput) || !pwInput) {
             console.error(chalk.red('Aborted — no password provided.'));
             console.error(chalk.dim('Tip: embed password in filename: name__pw__password.pdf'));
             process.exit(1);
         }
-        password = response.password;
+        password = pwInput;
     }
     const decryptedPath = decryptPdf(filePath, password);
     return { effectivePath: decryptedPath, cleanName, decryptedPath };

package/dist/commands/output.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { stringify as yamlStringify } from 'yaml';
 import { formatTable } from './table-formatter.js';
 import { displaySlice, paginatedJson } from './pagination.js';
+import { formatRecord } from './ui/record.js';
 /** Resolve the output format from CLI flags. --json is shorthand for --format json. */
 export function resolveFormat(opts) {
     if (opts.json && opts.format) {
@@ -114,7 +115,7 @@ export function outputRecord(record, opts) {
             console.log(yamlStringify(record).trimEnd());
             break;
         case 'table':
-            console.log(JSON.stringify(record, null, 2));
+            console.log(formatRecord(record));
             break;
     }
 }

package/dist/commands/pagination.js

@@ -1,5 +1,7 @@
 import chalk from 'chalk';
 import { fetchAllPages } from '../core/api/pagination.js';
+import { createProgress } from './ui/progress.js';
+import { isMachineFormat } from './output.js';
 /** Default row cap for --all mode. Prevents runaway fetches and agent token waste. */
 const DEFAULT_MAX_ROWS = 10_000;
 /** Display cap for human (non-JSON) output. */
@@ -14,13 +16,6 @@ const DISPLAY_CAP = 500;
  *   - Progress display on stderr (TTY-aware, suppressed for --json)
  *   - Truncation metadata (truncated field) for agent consumption
  *   - Single-page fetch when --all is not set
- *
- * Usage:
- *   const { data, totalElements, truncated } = await paginatedFetch(
- *     opts,
- *     (p) => listInvoices(client, p),
- *     { label: 'Fetching invoices' },
- *   );
  */
 export async function paginatedFetch(opts, fetcher, options) {
     const defaultLimit = options.defaultLimit ?? 100;
@@ -31,18 +26,15 @@ export async function paginatedFetch(opts, fetcher, options) {
     // ── Auto-paginate mode ──
     if (opts.all) {
         const resolvedFormat = opts.format?.toLowerCase() ?? (opts.json ? 'json' : 'table');
-        const showProgress = resolvedFormat === 'table' && process.stderr.isTTY;
+        const showProgress = resolvedFormat === 'table';
+        const progress = showProgress ? createProgress(options.label) : undefined;
         const result = await fetchAllPages((offset, limit) => fetcher({ limit, offset }), {
             pageSize: opts.limit ?? 200,
-            onProgress: showProgress
-                ? (fetched, total) => {
-                    process.stderr.write(`\r${chalk.dim(`${options.label}... ${fetched.toLocaleString()}/${total.toLocaleString()}`)}`);
-                }
+            onProgress: progress
+                ? (fetched, total) => progress.update(fetched, total)
                 : undefined,
         });
-        if (showProgress) {
-            process.stderr.write('\r\x1b[K'); // clear progress line
-        }
+        progress?.clear();
         // Apply max-rows soft cap
         const maxRows = opts.maxRows ?? DEFAULT_MAX_ROWS;
         let { truncated } = result;
@@ -51,7 +43,7 @@ export async function paginatedFetch(opts, fetcher, options) {
             data = data.slice(0, maxRows);
             truncated = true;
         }
-        if (truncated && !opts.json) {
+        if (truncated && !isMachineFormat(opts)) {
             console.error(chalk.yellow(`Warning: dataset has ${result.totalElements.toLocaleString()} items — showing ${data.length.toLocaleString()} (max-rows: ${maxRows.toLocaleString()})`));
         }
         const pageSize = opts.limit ?? defaultLimit;