@commissionsight/cli 0.1.0

package/dist/output/csv.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Deterministic, RFC-4180 CSV writer (plan §9.6). Column order is fixed per
+ * known result type so exports are stable/diff-friendly. Arrays render
+ * pipe-joined; nested objects are flattened with dotted keys.
+ */
+/** Canonical column orders for the exportable result types. */
+export declare const RESULT_ROW_COLUMNS: readonly ["memberRefId", "policyRefId", "status", "flags", "commissionAmount", "prevCommissionAmount", "commissionOwed", "comparedAgainstPeriod", "memberExternalId", "memberName", "email", "planName", "policyNumber", "premiumAmount"];
+export declare const CHARGEBACK_COLUMNS: readonly ["memberRefId", "policyRefId", "memberExternalId", "policyNumber", "planName", "chargebackAmount", "paidOut", "originalPayout.period", "originalPayout.amount", "originalPayout.fileName", "fullyReversed"];
+export declare const ATTRITION_COLUMNS: readonly ["period", "year", "month", "red", "memberCount", "attritionRate", "commissionAtRisk"];
+export declare const COMPARISON_COLUMNS: readonly ["memberRefId", "status", "flags", "commissionAmount", "prevCommissionAmount", "comparedAgainstPeriod", "memberName", "memberExternalId", "policyNumber"];
+/**
+ * Render rows to CSV text. When `columns` is omitted, the union of keys (in
+ * first-seen order) is used.
+ */
+export declare function toCSV(rows: Record<string, unknown>[], columns?: readonly string[]): string;
+/**
+ * Emit CSV to a file (when `outPath` is set) or to stdout. Returns a short
+ * status object for the command to surface. Keeps stdout CSV-only in --csv mode.
+ */
+export declare function emitCSV(io: {
+    stdout(s: string): void;
+}, rows: Record<string, unknown>[], columns: readonly string[] | undefined, outPath: string | undefined, writeFile: (path: string, data: string) => void): {
+    rows: number;
+    out: string;
+};

package/dist/output/csv.js

@@ -0,0 +1,119 @@
+/**
+ * Deterministic, RFC-4180 CSV writer (plan §9.6). Column order is fixed per
+ * known result type so exports are stable/diff-friendly. Arrays render
+ * pipe-joined; nested objects are flattened with dotted keys.
+ */
+/** Canonical column orders for the exportable result types. */
+export const RESULT_ROW_COLUMNS = [
+    'memberRefId',
+    'policyRefId',
+    'status',
+    'flags',
+    'commissionAmount',
+    'prevCommissionAmount',
+    'commissionOwed',
+    'comparedAgainstPeriod',
+    'memberExternalId',
+    'memberName',
+    'email',
+    'planName',
+    'policyNumber',
+    'premiumAmount',
+];
+export const CHARGEBACK_COLUMNS = [
+    'memberRefId',
+    'policyRefId',
+    'memberExternalId',
+    'policyNumber',
+    'planName',
+    'chargebackAmount',
+    'paidOut',
+    'originalPayout.period',
+    'originalPayout.amount',
+    'originalPayout.fileName',
+    'fullyReversed',
+];
+export const ATTRITION_COLUMNS = [
+    'period',
+    'year',
+    'month',
+    'red',
+    'memberCount',
+    'attritionRate',
+    'commissionAtRisk',
+];
+export const COMPARISON_COLUMNS = [
+    'memberRefId',
+    'status',
+    'flags',
+    'commissionAmount',
+    'prevCommissionAmount',
+    'comparedAgainstPeriod',
+    'memberName',
+    'memberExternalId',
+    'policyNumber',
+];
+function getPath(obj, path) {
+    if (!path.includes('.'))
+        return obj[path];
+    return path.split('.').reduce((acc, key) => {
+        if (acc && typeof acc === 'object')
+            return acc[key];
+        return undefined;
+    }, obj);
+}
+function cell(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (Array.isArray(value))
+        return value.join('|');
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/** RFC-4180 field quoting. */
+function quote(field) {
+    if (/[",\r\n]/.test(field)) {
+        return '"' + field.replace(/"/g, '""') + '"';
+    }
+    return field;
+}
+/**
+ * Render rows to CSV text. When `columns` is omitted, the union of keys (in
+ * first-seen order) is used.
+ */
+export function toCSV(rows, columns) {
+    const cols = columns ?? unionKeys(rows);
+    const lines = [];
+    lines.push(cols.map((c) => quote(c)).join(','));
+    for (const row of rows) {
+        lines.push(cols.map((c) => quote(cell(getPath(row, c)))).join(','));
+    }
+    return lines.join('\r\n') + '\r\n';
+}
+/**
+ * Emit CSV to a file (when `outPath` is set) or to stdout. Returns a short
+ * status object for the command to surface. Keeps stdout CSV-only in --csv mode.
+ */
+export function emitCSV(io, rows, columns, outPath, writeFile) {
+    const csv = toCSV(rows, columns);
+    if (outPath) {
+        writeFile(outPath, csv);
+        return { rows: rows.length, out: outPath };
+    }
+    io.stdout(csv);
+    return { rows: rows.length, out: '(stdout)' };
+}
+function unionKeys(rows) {
+    const seen = [];
+    const set = new Set();
+    for (const r of rows) {
+        for (const k of Object.keys(r)) {
+            if (!set.has(k)) {
+                set.add(k);
+                seen.push(k);
+            }
+        }
+    }
+    return seen;
+}

package/dist/output/envelope.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The stable JSON envelope (plan §5.1) and the error-shaping helpers.
+ * Success → { ok: true, data }. Failure → { ok: false, error }.
+ */
+import { exitCodeFor } from '../errors.js';
+export interface OkEnvelope {
+    ok: true;
+    data: unknown;
+}
+export interface ErrEnvelope {
+    ok: false;
+    error: {
+        status: number;
+        code: string | null;
+        message: string;
+        body?: unknown;
+    };
+}
+export type Envelope = OkEnvelope | ErrEnvelope;
+export declare function ok(data: unknown): OkEnvelope;
+/**
+ * Derive a stable machine `code` from an RFC 9457 problem+json body: prefer the
+ * `type` URI slug, then `title`/`code`. Returns null when nothing usable.
+ */
+export declare function deriveCode(body: unknown): string | null;
+/** Shape any thrown value into the error envelope. */
+export declare function errEnvelope(err: unknown): ErrEnvelope;
+/** Convenience: the exit code that pairs with a thrown value. */
+export { exitCodeFor };

package/dist/output/envelope.js

@@ -0,0 +1,66 @@
+/**
+ * The stable JSON envelope (plan §5.1) and the error-shaping helpers.
+ * Success → { ok: true, data }. Failure → { ok: false, error }.
+ */
+import { ApiError, UsageError, exitCodeFor } from '../errors.js';
+export function ok(data) {
+    return { ok: true, data };
+}
+/**
+ * Derive a stable machine `code` from an RFC 9457 problem+json body: prefer the
+ * `type` URI slug, then `title`/`code`. Returns null when nothing usable.
+ */
+export function deriveCode(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    if (typeof b['code'] === 'string' && b['code'])
+        return slug(b['code']);
+    if (typeof b['type'] === 'string' && b['type'] && b['type'] !== 'about:blank') {
+        const tail = b['type'].split(/[/#]/).filter(Boolean).pop();
+        if (tail)
+            return slug(tail);
+    }
+    if (typeof b['title'] === 'string' && b['title'])
+        return slug(b['title']);
+    return null;
+}
+function slug(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+/** Shape any thrown value into the error envelope. */
+export function errEnvelope(err) {
+    if (err instanceof ApiError) {
+        return {
+            ok: false,
+            error: {
+                status: err.status,
+                code: deriveCode(err.body),
+                message: err.message,
+                body: err.body,
+            },
+        };
+    }
+    if (err instanceof UsageError) {
+        return {
+            ok: false,
+            error: {
+                status: 0,
+                code: 'usage_error',
+                message: err.message,
+                ...(err.candidates ? { body: { candidates: err.candidates } } : {}),
+            },
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const code = err instanceof Error && err.name && err.name !== 'Error'
+        ? slug(err.name)
+        : null;
+    return { ok: false, error: { status: 0, code, message } };
+}
+/** Convenience: the exit code that pairs with a thrown value. */
+export { exitCodeFor };

package/dist/output/help.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `--help` rendering, derived from the command table and global flag specs.
+ */
+import type { Cmd } from '../types.js';
+import type { IO } from '../io.js';
+export declare function renderTopHelp(io: IO, table: Cmd[]): void;
+export declare function renderCommandHelp(io: IO, cmd: Cmd, table: Cmd[]): void;

package/dist/output/help.js

@@ -0,0 +1,57 @@
+import { GLOBAL_OPTIONS } from '../globals.js';
+import { cliVersion } from '../version.js';
+function optLine(name, spec) {
+    const short = spec.short ? `-${spec.short}, ` : '    ';
+    const val = spec.type === 'string' ? ` ${spec.placeholder ?? '<value>'}` : '';
+    const flag = `${short}--${name}${val}`;
+    const choices = spec.choices ? ` (${spec.choices.join('|')})` : '';
+    return `  ${flag.padEnd(30)}${spec.desc}${choices}`;
+}
+export function renderTopHelp(io, table) {
+    io.stdout(`cs ${cliVersion()} — CommissionSight CLI\n\n`);
+    io.stdout('Usage: cs <command> [subcommand] [args] [flags]\n\n');
+    // Group by top-level segment.
+    const groups = new Map();
+    for (const c of table) {
+        const key = c.path[0];
+        const arr = groups.get(key) ?? [];
+        arr.push(c);
+        groups.set(key, arr);
+    }
+    io.stdout('Commands:\n');
+    for (const key of [...groups.keys()].sort()) {
+        const cmds = groups.get(key).sort((a, b) => a.path.join(' ').localeCompare(b.path.join(' ')));
+        for (const c of cmds) {
+            io.stdout(`  ${c.path.join(' ').padEnd(28)}${c.summary}\n`);
+        }
+    }
+    io.stdout('\nGlobal flags:\n');
+    for (const [name, spec] of Object.entries(GLOBAL_OPTIONS)) {
+        io.stdout(optLine(name, spec) + '\n');
+    }
+    io.stdout("\nRun 'cs <command> --help' for command-specific help.\n");
+    io.stdout("Run 'cs schema --json' for the machine-readable command tree.\n");
+}
+export function renderCommandHelp(io, cmd, table) {
+    const usageArgs = (cmd.args ?? [])
+        .map((a) => (a.required ? `<${a.name}>` : `[${a.name}]`) + (a.variadic ? '...' : ''))
+        .join(' ');
+    io.stdout(`cs ${cmd.path.join(' ')} — ${cmd.summary}\n\n`);
+    io.stdout(`Usage: cs ${cmd.path.join(' ')} ${usageArgs} [flags]\n`);
+    // Subcommands sharing this prefix.
+    const subs = table.filter((c) => c !== cmd && cmd.path.every((seg, i) => c.path[i] === seg) && c.path.length > cmd.path.length);
+    if (subs.length) {
+        io.stdout('\nSubcommands:\n');
+        for (const s of subs.sort((a, b) => a.path.join(' ').localeCompare(b.path.join(' ')))) {
+            io.stdout(`  ${s.path.join(' ').padEnd(28)}${s.summary}\n`);
+        }
+    }
+    const opts = cmd.options ?? {};
+    if (Object.keys(opts).length) {
+        io.stdout('\nFlags:\n');
+        for (const [name, spec] of Object.entries(opts)) {
+            io.stdout(optLine(name, spec) + '\n');
+        }
+    }
+    io.stdout('\nGlobal flags apply (see `cs --help`).\n');
+}

package/dist/output/print.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Human renderer: a minimal table + key/value printer (plan §9.6). Zero deps.
+ * All output goes through the injected IO so tests can capture it.
+ */
+import type { IO } from '../io.js';
+import { type Painter } from './color.js';
+export interface Printer {
+    paint: Painter;
+    line(s?: string): void;
+    kv(obj: Record<string, unknown>): void;
+    table(rows: Record<string, unknown>[], columns?: string[]): void;
+    raw(s: string): void;
+}
+export declare function makePrinter(io: IO, colorEnabled: boolean): Printer;

package/dist/output/print.js

@@ -0,0 +1,70 @@
+import { makePainter, statusColor } from './color.js';
+export function makePrinter(io, colorEnabled) {
+    const paint = makePainter(colorEnabled);
+    const line = (s = '') => io.stdout(s + '\n');
+    return {
+        paint,
+        line,
+        raw: (s) => io.stdout(s),
+        kv(obj) {
+            const keys = Object.keys(obj);
+            const width = keys.reduce((m, k) => Math.max(m, k.length), 0);
+            for (const k of keys) {
+                const label = paint('gray', k.padEnd(width));
+                line(`${label}  ${fmtValue(obj[k], paint)}`);
+            }
+        },
+        table(rows, columns) {
+            if (rows.length === 0) {
+                line(paint('dim', '(no rows)'));
+                return;
+            }
+            const cols = columns ?? unionKeys(rows);
+            const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => plain(fmtValue(r[c], paint)).length)));
+            const header = cols
+                .map((c, i) => paint('bold', c.padEnd(widths[i] ?? c.length)))
+                .join('  ');
+            line(header);
+            line(paint('dim', cols.map((_, i) => '─'.repeat(widths[i] ?? 1)).join('  ')));
+            for (const r of rows) {
+                line(cols
+                    .map((c, i) => {
+                    const cell = fmtValue(r[c], paint);
+                    return pad(cell, widths[i] ?? 0);
+                })
+                    .join('  '));
+            }
+        },
+    };
+}
+function unionKeys(rows) {
+    const seen = new Set();
+    for (const r of rows)
+        for (const k of Object.keys(r))
+            seen.add(k);
+    return [...seen];
+}
+function fmtValue(v, paint) {
+    if (v === null || v === undefined)
+        return paint('dim', '—');
+    if (typeof v === 'boolean')
+        return v ? paint('green', 'yes') : paint('gray', 'no');
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    const s = String(v);
+    // Color known status words inline.
+    if (['green', 'yellow', 'red', 'ok', 'watch', 'alert', 'completed', 'failed', 'queued', 'processing'].includes(s.toLowerCase())) {
+        return paint(statusColor(s), s);
+    }
+    return s;
+}
+/** Strip ANSI codes to measure visible width. */
+function plain(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\[[0-9;]*m/g, '');
+}
+/** Pad accounting for invisible ANSI sequences. */
+function pad(s, width) {
+    const visible = plain(s).length;
+    return s + ' '.repeat(Math.max(0, width - visible));
+}

package/dist/output/schema-tree.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Build the machine-readable command/flag tree for `cs schema` and drive
+ * `--help` text — all from the same command table the router dispatches on.
+ */
+import type { Cmd } from '../types.js';
+export interface SchemaOption {
+    flag: string;
+    type: 'string' | 'boolean';
+    short?: string;
+    desc: string;
+    default?: string | boolean;
+    choices?: readonly string[];
+    multiple?: boolean;
+}
+export interface SchemaCommand {
+    command: string;
+    path: string[];
+    summary: string;
+    args: {
+        name: string;
+        required: boolean;
+        variadic: boolean;
+    }[];
+    options: SchemaOption[];
+}
+export interface SchemaDoc {
+    name: string;
+    version: string;
+    globalOptions: SchemaOption[];
+    commands: SchemaCommand[];
+}
+export declare function buildSchema(table: Cmd[], version: string): SchemaDoc;

package/dist/output/schema-tree.js

@@ -0,0 +1,33 @@
+import { GLOBAL_OPTIONS } from '../globals.js';
+function optionToSchema(flag, spec) {
+    return {
+        flag,
+        type: spec.type,
+        ...(spec.short ? { short: spec.short } : {}),
+        desc: spec.desc,
+        ...(spec.default !== undefined ? { default: spec.default } : {}),
+        ...(spec.choices ? { choices: spec.choices } : {}),
+        ...(spec.multiple ? { multiple: true } : {}),
+    };
+}
+export function buildSchema(table, version) {
+    return {
+        name: 'cs',
+        version,
+        globalOptions: Object.entries(GLOBAL_OPTIONS).map(([f, s]) => optionToSchema(f, s)),
+        commands: table
+            .slice()
+            .sort((a, b) => a.path.join(' ').localeCompare(b.path.join(' ')))
+            .map((c) => ({
+            command: c.path.join(' '),
+            path: c.path,
+            summary: c.summary,
+            args: (c.args ?? []).map((a) => ({
+                name: a.name,
+                required: Boolean(a.required),
+                variadic: Boolean(a.variadic),
+            })),
+            options: Object.entries(c.options ?? {}).map(([f, s]) => optionToSchema(f, s)),
+        })),
+    };
+}

package/dist/router.d.ts

@@ -0,0 +1,6 @@
+import type { IO } from './io.js';
+export interface RunOptions {
+    io?: IO;
+}
+/** Entry point used by main() and tests. Returns the process exit code. */
+export declare function run(argv: string[], opts?: RunOptions): Promise<number>;