@commissionsight/cli 0.1.1 → 0.1.2

package/README.md

@@ -51,9 +51,12 @@ onboarded immediately.)
 cs schema --json
 ```
 
-Returns the **entire** command/flag tree as JSON: every command, its positional
-args (with `required`/`variadic`), and every option (`type`, `short`, `desc`,
-`choices`, `default`). Parse this instead of memorizing commands. Shape:
+Returns the **entire** command/flag tree as JSON **plus a `conventions` block**
+(the envelope shape, exit-code table, error fields, auth, idempotency, and
+pagination rules) — so a single call fully onboards an agent. It contains every
+command, its positional args (with `required`/`variadic`), and every option
+(`type`, `short`, `desc`, `choices`, `default`). Parse this instead of memorizing
+commands. Shape:
 
 ```json
 {
@@ -92,8 +95,11 @@ safely `JSON.parse(stdout)` without stripping anything.
   ```
 
 `error.code` is a stable slug derived from the API's problem+json body
-(`period_exists`, `already_retracted`, …) or `null`. Branch on `error.code` /
-`error.status`, not on `message` text.
+(`period_exists`, `already_retracted`, …) or `null`. The error object also carries
+a machine-readable **`hint`** (the recovery action, e.g. "re-run with --replace")
+and **`retriable`** (true for rate-limits/timeouts/5xx) — so an agent can recover
+without parsing `message` text. Branch on `error.code` / `error.status` /
+`error.retriable`.
 
 ### 3. Use exit codes for control flow
 

package/dist/output/envelope.d.ts

@@ -13,6 +13,10 @@ export interface ErrEnvelope {
         status: number;
         code: string | null;
         message: string;
+        /** Actionable next step an agent can act on without parsing `message`. */
+        hint?: string;
+        /** True when retrying the same call may succeed (rate limit, timeout, 5xx). */
+        retriable: boolean;
         body?: unknown;
     };
 }
@@ -23,6 +27,14 @@ export declare function ok(data: unknown): OkEnvelope;
  * `type` URI slug, then `title`/`code`. Returns null when nothing usable.
  */
 export declare function deriveCode(body: unknown): string | null;
+/**
+ * Compute an actionable hint + retriability from an API status (+ derived code),
+ * so an agent can recover without parsing the human message.
+ */
+export declare function errorMeta(status: number, code: string | null): {
+    hint?: string;
+    retriable: boolean;
+};
 /** 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. */

package/dist/output/envelope.js

@@ -2,7 +2,7 @@
  * 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';
+import { ApiError, UsageError, TimeoutError, exitCodeFor } from '../errors.js';
 export function ok(data) {
     return { ok: true, data };
 }
@@ -32,19 +32,62 @@ function slug(s) {
         .replace(/[^a-z0-9]+/g, '_')
         .replace(/^_+|_+$/g, '');
 }
+/**
+ * Compute an actionable hint + retriability from an API status (+ derived code),
+ * so an agent can recover without parsing the human message.
+ */
+export function errorMeta(status, code) {
+    if (status === 409 && code === 'period_exists') {
+        return { hint: 're-run with --replace to overwrite this carrier+period', retriable: false };
+    }
+    if (status === 409 && code === 'already_retracted') {
+        return { hint: 'this carrier+period was already retracted/replaced; no action needed', retriable: false };
+    }
+    if (status === 409)
+        return { hint: 'resource conflict; inspect error.body', retriable: false };
+    if (status === 401 || status === 403) {
+        return { hint: 'authenticate: set COMMISSIONSIGHT_TOKEN or run `cs auth login --token-stdin`', retriable: false };
+    }
+    if (status === 404)
+        return { hint: 'not found; verify the id/ref exists', retriable: false };
+    if (status === 400 || status === 422) {
+        return { hint: 'inputs rejected; read error.body for field-level errors', retriable: false };
+    }
+    if (status === 429)
+        return { hint: 'rate limited; back off and retry', retriable: true };
+    if (status >= 500)
+        return { hint: 'server error; retry shortly', retriable: true };
+    return { retriable: false };
+}
 /** Shape any thrown value into the error envelope. */
 export function errEnvelope(err) {
     if (err instanceof ApiError) {
+        const code = deriveCode(err.body);
+        const { hint, retriable } = errorMeta(err.status, code);
         return {
             ok: false,
             error: {
                 status: err.status,
-                code: deriveCode(err.body),
+                code,
                 message: err.message,
+                ...(hint ? { hint } : {}),
+                retriable,
                 body: err.body,
             },
         };
     }
+    if (err instanceof TimeoutError) {
+        return {
+            ok: false,
+            error: {
+                status: 0,
+                code: 'timeout',
+                message: err.message,
+                hint: 'raise --timeout, or poll again with `cs job wait <jobId>`',
+                retriable: true,
+            },
+        };
+    }
     if (err instanceof UsageError) {
         return {
             ok: false,
@@ -52,6 +95,8 @@ export function errEnvelope(err) {
                 status: 0,
                 code: 'usage_error',
                 message: err.message,
+                hint: 'fix the invocation; run `cs <command> --help` or `cs schema --json`',
+                retriable: false,
                 ...(err.candidates ? { body: { candidates: err.candidates } } : {}),
             },
         };
@@ -60,7 +105,7 @@ export function errEnvelope(err) {
     const code = err instanceof Error && err.name && err.name !== 'Error'
         ? slug(err.name)
         : null;
-    return { ok: false, error: { status: 0, code, message } };
+    return { ok: false, error: { status: 0, code, message, retriable: false } };
 }
 /** Convenience: the exit code that pairs with a thrown value. */
 export { exitCodeFor };

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

@@ -23,10 +23,28 @@ export interface SchemaCommand {
     }[];
     options: SchemaOption[];
 }
+export interface SchemaConventions {
+    /** The stable output envelope (plan §5.1). */
+    envelope: {
+        success: string;
+        error: string;
+        stdout: string;
+    };
+    /** ApiError.status → exit-code semantics (plan §5.2). */
+    exitCodes: Record<string, string>;
+    /** Fields present on a failure envelope's `error` object. */
+    errorFields: string[];
+    auth: string;
+    idempotency: string;
+    pagination: string;
+}
 export interface SchemaDoc {
     name: string;
     version: string;
+    /** Machine-readable usage contract so one `cs schema --json` call is enough. */
+    conventions: SchemaConventions;
     globalOptions: SchemaOption[];
     commands: SchemaCommand[];
 }
+export declare const CONVENTIONS: SchemaConventions;
 export declare function buildSchema(table: Cmd[], version: string): SchemaDoc;

package/dist/output/schema-tree.js

@@ -1,4 +1,26 @@
 import { GLOBAL_OPTIONS } from '../globals.js';
+export const CONVENTIONS = {
+    envelope: {
+        success: '{"ok":true,"data":<result>}',
+        error: '{"ok":false,"error":{"status":<int>,"code":<string|null>,"message":<string>,"hint":<string?>,"retriable":<bool>,"body":<any?>}}',
+        stdout: 'With --json, stdout carries exactly one envelope; all logs/progress go to stderr.',
+    },
+    exitCodes: {
+        '0': 'success',
+        '1': 'unexpected/internal error (includes a job that finished failed)',
+        '2': 'usage error (bad flags/args)',
+        '3': 'auth error (401/403)',
+        '4': 'not found (404)',
+        '5': 'conflict (409) — e.g. period_exists; retry with --replace',
+        '6': 'validation/unprocessable (400/422)',
+        '7': 'rate limited (429) — retriable',
+        '124': 'timeout (--wait exceeded --timeout) — retriable',
+    },
+    errorFields: ['status', 'code', 'message', 'hint', 'retriable', 'body'],
+    auth: 'Set COMMISSIONSIGHT_TOKEN, or pipe a token via `cs auth login --token-stdin`. --token-file/--token also work; --token is discouraged (shell history).',
+    idempotency: 'cs upload / cs upload batch derive a stable idempotency key per file; re-running is safe and resumable (existing carrier+periods come back as skipped).',
+    pagination: 'List commands accept --limit and --all (auto-paginate); offset endpoints also take --offset, listFiles takes --cursor.',
+};
 function optionToSchema(flag, spec) {
     return {
         flag,
@@ -14,6 +36,7 @@ export function buildSchema(table, version) {
     return {
         name: 'cs',
         version,
+        conventions: CONVENTIONS,
         globalOptions: Object.entries(GLOBAL_OPTIONS).map(([f, s]) => optionToSchema(f, s)),
         commands: table
             .slice()

package/dist/router.js

@@ -212,13 +212,9 @@ function finishError(io, err, json, quiet) {
         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");
-    }
+    // Single source of truth for the actionable hint (also in the JSON envelope).
+    if (env.error.hint)
+        io.stderr(`hint: ${env.error.hint}\n`);
     if (err instanceof UsageError && err.candidates?.length) {
         io.stderr('candidates:\n');
         for (const c of err.candidates)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commissionsight/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Command-line interface for the CommissionSight API — auth, workspaces, and statement uploads for any carrier and period.",
   "keywords": [
     "commissionsight",