@commissionsight/cli 0.1.0

package/dist/router.js

@@ -0,0 +1,267 @@
+/**
+ * Router (plan §7): parse argv → match command via longest-prefix → validate
+ * flags → run → wrap result in the JSON envelope (§5.1) → map errors to exit
+ * codes (§5.2). Commands return data; the router owns output and exit codes.
+ */
+import { parseArgs } from 'node:util';
+import { defaultIO } from './io.js';
+import { GLOBAL_OPTIONS, GLOBAL_KEYS, resolveGlobals } from './globals.js';
+import { getCommandTable } from './commands/registry.js';
+import { makeRunCtx } from './context.js';
+import { ok, errEnvelope } from './output/envelope.js';
+import { EXIT, UsageError, exitCodeFor } from './errors.js';
+import { makePrinter } from './output/print.js';
+import { cliVersion, sdkVersion } from './version.js';
+import { renderTopHelp, renderCommandHelp } from './output/help.js';
+/** Build the parseArgs `options` config from option specs. */
+function toParseArgsOptions(specs) {
+    const out = {};
+    for (const [name, spec] of Object.entries(specs)) {
+        out[name] = {
+            type: spec.type,
+            ...(spec.short ? { short: spec.short } : {}),
+            ...(spec.multiple ? { multiple: true } : {}),
+        };
+    }
+    return out;
+}
+const SHORT_TO_GLOBAL = {};
+for (const [long, spec] of Object.entries(GLOBAL_OPTIONS)) {
+    if (spec.short)
+        SHORT_TO_GLOBAL[spec.short] = { ...spec, long };
+}
+/**
+ * Phase A: collect the leading "words" that could form a command path,
+ * skipping global flags (accounting for their value arity) and stopping at the
+ * first command-specific flag or `--`.
+ */
+function collectWords(argv) {
+    const words = [];
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === '--')
+            break;
+        if (t.startsWith('--')) {
+            const eq = t.indexOf('=');
+            const name = eq >= 0 ? t.slice(2, eq) : t.slice(2);
+            const spec = GLOBAL_OPTIONS[name];
+            if (!spec)
+                break; // command-specific long flag → path ended
+            if (spec.type === 'string' && eq < 0)
+                i++; // consume the value token
+            continue;
+        }
+        if (t.startsWith('-') && t.length > 1) {
+            const short = t[1];
+            const g = SHORT_TO_GLOBAL[short];
+            if (!g)
+                break; // command-specific short flag → path ended
+            if (g.type === 'string' && t.length === 2)
+                i++;
+            continue;
+        }
+        words.push(t);
+    }
+    return words;
+}
+/** Longest-prefix match of `words` against the registered command paths. */
+function matchCommand(words, table) {
+    let best = null;
+    for (const cmd of table) {
+        const p = cmd.path;
+        if (p.length > words.length)
+            continue;
+        if (p.every((seg, i) => seg === words[i])) {
+            if (!best || p.length > best.depth)
+                best = { cmd, depth: p.length };
+        }
+    }
+    return best;
+}
+/** Group commands sharing a prefix (for "did you mean" / group help). */
+function commandsUnder(prefix, table) {
+    return table.filter((c) => prefix.every((seg, i) => c.path[i] === seg));
+}
+/** Entry point used by main() and tests. Returns the process exit code. */
+export async function run(argv, opts = {}) {
+    const io = opts.io ?? defaultIO();
+    const table = getCommandTable();
+    // Pre-scan for a bare top-level --version / -V (before any command).
+    const words = collectWords(argv);
+    const match = matchCommand(words, table);
+    // Top-level --version with no command.
+    if (!match && hasFlag(argv, 'version', 'V')) {
+        io.stdout(`cs ${cliVersion()} (@commissionsight/sdk ${sdkVersion()})\n`);
+        return EXIT.OK;
+    }
+    // No command resolved.
+    if (!match) {
+        const wantsHelp = hasFlag(argv, 'help', 'h') || argv.length === 0 || words.length === 0;
+        if (wantsHelp && (argv.length === 0 || hasFlag(argv, 'help', 'h'))) {
+            renderTopHelp(io, table);
+            return EXIT.OK;
+        }
+        // Unknown command word(s).
+        const attempted = words.join(' ') || argv[0] || '';
+        const near = commandsUnder([words[0] ?? ''], table);
+        io.stderr(`error: unknown command: ${attempted}\n`);
+        if (near.length) {
+            io.stderr('did you mean:\n');
+            for (const c of near)
+                io.stderr(`  cs ${c.path.join(' ')}\n`);
+        }
+        else {
+            io.stderr("run 'cs --help' to see available commands\n");
+        }
+        return EXIT.USAGE;
+    }
+    const { cmd, depth } = match;
+    // Per-command help.
+    if (hasFlag(argv, 'help', 'h')) {
+        renderCommandHelp(io, cmd, table);
+        return EXIT.OK;
+    }
+    // Phase B: parse the full argv against merged (global + command) specs.
+    const merged = { ...GLOBAL_OPTIONS, ...(cmd.options ?? {}) };
+    let values;
+    let positionals;
+    try {
+        const parsed = parseArgs({
+            args: argv,
+            options: toParseArgsOptions(merged),
+            allowPositionals: true,
+            strict: true,
+        });
+        values = parsed.values;
+        positionals = parsed.positionals;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return finishError(io, new UsageError(msg), false, false);
+    }
+    const globals = resolveGlobals(values, io);
+    // Validate choices and apply defaults for command options.
+    try {
+        applyDefaultsAndChoices(cmd, values);
+        validateArgs(cmd, positionals.slice(depth));
+    }
+    catch (err) {
+        return finishError(io, err, globals.json, globals.quiet);
+    }
+    // Strip the command path words from the front of positionals → command args.
+    const args = positionals.slice(depth);
+    // Command-facing options exclude global control keys.
+    const cmdOptions = {};
+    for (const [k, v] of Object.entries(values)) {
+        if (!GLOBAL_KEYS.has(k))
+            cmdOptions[k] = v;
+    }
+    const ctx = makeRunCtx(globals, io);
+    const parsed = { args, options: cmdOptions };
+    try {
+        const data = await cmd.run(ctx, parsed);
+        finishSuccess(io, cmd, data, ctx);
+        return EXIT.OK;
+    }
+    catch (err) {
+        return finishError(io, err, globals.json, globals.quiet);
+    }
+}
+function finishSuccess(io, cmd, data, ctx) {
+    if (ctx.globals.json) {
+        io.stdout(JSON.stringify(ok(data)) + '\n');
+        return;
+    }
+    if (data === undefined || data === null) {
+        if (!ctx.globals.quiet)
+            io.stderr('ok\n');
+        return;
+    }
+    if (cmd.render) {
+        cmd.render(data, ctx);
+        return;
+    }
+    defaultRender(data, ctx);
+}
+function defaultRender(data, ctx) {
+    const p = makePrinter(ctx.io, ctx.globals.color);
+    if (Array.isArray(data)) {
+        if (data.every((r) => r && typeof r === 'object')) {
+            p.table(data);
+        }
+        else {
+            for (const item of data)
+                p.line(String(item));
+        }
+        return;
+    }
+    if (data && typeof data === 'object') {
+        p.kv(data);
+        return;
+    }
+    p.line(String(data));
+}
+function finishError(io, err, json, quiet) {
+    const env = errEnvelope(err);
+    const code = exitCodeFor(err);
+    if (json) {
+        io.stderr(JSON.stringify(env) + '\n');
+        return code;
+    }
+    io.stderr(`error: ${env.error.message}\n`);
+    // Actionable hints.
+    if (env.error.status === 409 && env.error.code === 'period_exists') {
+        io.stderr('hint: retry with --replace to correct this period atomically\n');
+    }
+    if (env.error.status === 401 || env.error.status === 403) {
+        io.stderr("hint: check your token with 'cs auth status'\n");
+    }
+    if (err instanceof UsageError && err.candidates?.length) {
+        io.stderr('candidates:\n');
+        for (const c of err.candidates)
+            io.stderr(`  ${c}\n`);
+    }
+    void quiet;
+    return code;
+}
+function applyDefaultsAndChoices(cmd, values) {
+    for (const [name, spec] of Object.entries(cmd.options ?? {})) {
+        if (values[name] === undefined && spec.default !== undefined) {
+            values[name] = spec.default;
+        }
+        if (spec.choices && values[name] !== undefined) {
+            const vals = Array.isArray(values[name]) ? values[name] : [values[name]];
+            for (const v of vals) {
+                if (!spec.choices.includes(v)) {
+                    throw new UsageError(`invalid value for --${name}: ${v} (expected one of: ${spec.choices.join(', ')})`);
+                }
+            }
+        }
+    }
+}
+function validateArgs(cmd, args) {
+    const specs = cmd.args ?? [];
+    const requiredCount = specs.filter((a) => a.required).length;
+    if (args.length < requiredCount) {
+        const usage = specs
+            .map((a) => (a.required ? `<${a.name}>` : `[${a.name}]`) + (a.variadic ? '...' : ''))
+            .join(' ');
+        throw new UsageError(`missing required argument(s). usage: cs ${cmd.path.join(' ')} ${usage}`);
+    }
+    const hasVariadic = specs.some((a) => a.variadic);
+    if (!hasVariadic && args.length > specs.length) {
+        throw new UsageError(`too many arguments for 'cs ${cmd.path.join(' ')}' (expected ${specs.length}, got ${args.length})`);
+    }
+}
+/** Cheap flag presence check independent of parseArgs (for --help/--version). */
+function hasFlag(argv, long, short) {
+    for (const t of argv) {
+        if (t === '--')
+            break;
+        if (t === `--${long}`)
+            return true;
+        if (t.startsWith('-') && !t.startsWith('--') && t.slice(1).includes(short))
+            return true;
+    }
+    return false;
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Core types shared by the router, command table, and runtime context.
+ * The command table (see commands/registry.ts) is the single source of truth
+ * consumed by the router, `--help`, and `cs schema`.
+ */
+import type { CommissionSightClient } from '@commissionsight/sdk';
+import type { IO } from './io.js';
+/** One CLI flag specification. */
+export interface OptSpec {
+    type: 'string' | 'boolean';
+    short?: string;
+    desc: string;
+    default?: string | boolean;
+    choices?: readonly string[];
+    /** Flag may be repeated (parseArgs `multiple`). Values collect into an array. */
+    multiple?: boolean;
+    /** Placeholder shown in help for value-taking flags (e.g. `<YYYY-MM>`). */
+    placeholder?: string;
+}
+/** One positional argument specification. */
+export interface ArgSpec {
+    name: string;
+    required?: boolean;
+    variadic?: boolean;
+    desc?: string;
+}
+/** The parsed inputs handed to a command's `run`. */
+export interface Parsed {
+    args: string[];
+    options: Record<string, string | boolean | string[] | undefined>;
+}
+/** A single command (leaf) in the command tree. */
+export interface Cmd {
+    /** e.g. ["carrier","config","test"] */
+    path: string[];
+    summary: string;
+    args?: ArgSpec[];
+    options?: Record<string, OptSpec>;
+    /** Returns plain data; the router owns the envelope + exit-code mapping. */
+    run(ctx: RunCtx, parsed: Parsed): Promise<unknown>;
+    /** Optional custom human renderer; defaults to the generic printer. */
+    render?(data: unknown, ctx: RunCtx): void;
+}
+/** Resolved global flags + injected dependencies. */
+export interface Globals {
+    json: boolean;
+    quiet: boolean;
+    color: boolean;
+    yes: boolean;
+    token?: string;
+    tokenFile?: string;
+    tokenStdin?: boolean;
+    baseUrl?: string;
+    context?: string;
+}
+/** Runtime context threaded into every command. */
+export interface RunCtx {
+    globals: Globals;
+    io: IO;
+    /** Lazily-constructed SDK client (token/baseUrl resolved on first use). */
+    client(): CommissionSightClient;
+    /** Per-run cache (carrier list, workspace list) for batch reuse. */
+    cache: Map<string, unknown>;
+    /** Log a line to stderr (suppressed in --quiet / --json chrome rules). */
+    log(msg: string): void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,11 @@
+/** Small shared helpers. */
+/** Mask a secret to a short suffix for display (e.g. `…a1b2`). Never logs the token. */
+export declare function maskToken(token: string | undefined): string;
+/** Coerce a parsed option value to a string (last wins for repeated flags). */
+export declare function optStr(v: string | boolean | string[] | undefined): string | undefined;
+/** Coerce a parsed option value to a boolean. */
+export declare function optBool(v: string | boolean | string[] | undefined): boolean;
+/** Coerce a parsed option value to a number, or undefined. */
+export declare function optNum(v: string | boolean | string[] | undefined): number | undefined;
+/** Collect a repeatable/comma-separated option into a string array. */
+export declare function optList(v: string | boolean | string[] | undefined): string[];

package/dist/util.js

@@ -0,0 +1,39 @@
+/** Small shared helpers. */
+/** Mask a secret to a short suffix for display (e.g. `…a1b2`). Never logs the token. */
+export function maskToken(token) {
+    if (!token)
+        return '(none)';
+    if (token.length <= 4)
+        return '…' + token;
+    return '…' + token.slice(-4);
+}
+/** Coerce a parsed option value to a string (last wins for repeated flags). */
+export function optStr(v) {
+    if (typeof v === 'string')
+        return v;
+    if (Array.isArray(v))
+        return v[v.length - 1];
+    return undefined;
+}
+/** Coerce a parsed option value to a boolean. */
+export function optBool(v) {
+    return v === true;
+}
+/** Coerce a parsed option value to a number, or undefined. */
+export function optNum(v) {
+    const s = optStr(v);
+    if (s === undefined)
+        return undefined;
+    const n = Number(s);
+    if (!Number.isFinite(n))
+        return undefined;
+    return n;
+}
+/** Collect a repeatable/comma-separated option into a string array. */
+export function optList(v) {
+    if (Array.isArray(v))
+        return v.flatMap((x) => x.split(',')).map((s) => s.trim()).filter(Boolean);
+    if (typeof v === 'string')
+        return v.split(',').map((s) => s.trim()).filter(Boolean);
+    return [];
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare function cliVersion(): string;
+export declare function sdkVersion(): string;

package/dist/version.js

@@ -0,0 +1,41 @@
+/**
+ * Resolve the CLI's own version (from package.json) and the installed SDK
+ * version — both read from disk at runtime so they never drift from reality.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function cliVersion() {
+    try {
+        const url = new URL('../package.json', import.meta.url);
+        const pkg = JSON.parse(readFileSync(fileURLToPath(url), 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function sdkVersion() {
+    // The SDK is ESM-only with an `exports` map that omits a CJS entry, so
+    // `require.resolve` fails. Walk up from this module looking for the package's
+    // installed package.json under node_modules instead.
+    try {
+        let dir = dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 8; i++) {
+            const p = join(dir, 'node_modules', '@commissionsight', 'sdk', 'package.json');
+            if (existsSync(p)) {
+                const j = JSON.parse(readFileSync(p, 'utf8'));
+                if (j.version)
+                    return j.version;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return 'unknown';
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@commissionsight/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for the CommissionSight API — auth, workspaces, and statement uploads for any carrier and period.",
+  "keywords": [
+    "commissionsight",
+    "cli",
+    "commission",
+    "insurance",
+    "carrier",
+    "statements",
+    "upload"
+  ],
+  "license": "MIT",
+  "author": "CommissionSight",
+  "type": "module",
+  "bin": {
+    "cs": "bin/cs.mjs",
+    "commissionsight": "bin/cs.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@commissionsight/sdk": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}