@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/src/cli/metadata.ts

@@ -0,0 +1,194 @@
+import type { z } from 'zod';
+import {
+    AddCasePayloadSchema,
+    UpdateCasePayloadSchema,
+    AddRunPayloadSchema,
+    AddResultPayloadSchema,
+    AddResultsForCasesPayloadSchema,
+} from '../schemas.js';
+
+/**
+ * Declarative spec for every resource:action exposed by the CLI.
+ *
+ * Single source of truth shared by:
+ * - PR 3 tests: assert both directions of the metadata↔dispatch
+ *   correspondence — every `ACTIONS` entry must have a registered handler
+ *   in `dispatch.ts` HANDLERS, and every HANDLERS key must have an
+ *   `ACTIONS` entry. Catches drift in either direction.
+ * - PR 4 skill generator: renders the `<!-- GENERATED:command-table -->` and
+ *   `<!-- GENERATED:payload-schemas -->` regions of `skill/SKILL.md` from
+ *   this array.
+ *
+ * Adding a new action requires touching exactly two places: the handler in
+ * `src/cli/handlers/`, and an entry here. The dispatcher and the skill stay
+ * accurate automatically.
+ */
+
+export interface PathParam {
+    name: string;
+    description: string;
+}
+
+export interface ActionSpec {
+    resource: string;
+    action: string;
+    summary: string;
+    pathParams: readonly PathParam[];
+    /** Zod schema for the request body. `undefined` for read actions and for
+     *  no-body POSTs like `run close`. */
+    bodySchema?: z.ZodTypeAny;
+    /** True for write actions (POST / payload-bearing). Affects skill recipes,
+     *  generator output, and `--dry-run` applicability. */
+    isWrite: boolean;
+}
+
+export const ACTIONS: readonly ActionSpec[] = [
+    // ── Read actions ──────────────────────────────────────────────────────
+    {
+        resource: 'project',
+        action: 'get',
+        summary: 'Fetch a single project by ID',
+        pathParams: [{ name: 'project_id', description: 'TestRail project ID' }],
+        isWrite: false,
+    },
+    {
+        resource: 'project',
+        action: 'list',
+        summary: 'List all projects (paginated)',
+        pathParams: [],
+        isWrite: false,
+    },
+    {
+        resource: 'suite',
+        action: 'get',
+        summary: 'Fetch a single suite by ID',
+        pathParams: [{ name: 'suite_id', description: 'TestRail suite ID' }],
+        isWrite: false,
+    },
+    {
+        resource: 'suite',
+        action: 'list',
+        summary: 'List suites in a project',
+        pathParams: [],
+        isWrite: false,
+    },
+    {
+        resource: 'case',
+        action: 'get',
+        summary: 'Fetch a single test case by ID',
+        pathParams: [{ name: 'case_id', description: 'TestRail case ID' }],
+        isWrite: false,
+    },
+    {
+        resource: 'case',
+        action: 'list',
+        summary: 'List cases in a project (optionally filtered by suite)',
+        pathParams: [],
+        isWrite: false,
+    },
+    {
+        resource: 'run',
+        action: 'get',
+        summary: 'Fetch a single run by ID',
+        pathParams: [{ name: 'run_id', description: 'TestRail run ID' }],
+        isWrite: false,
+    },
+    {
+        resource: 'run',
+        action: 'list',
+        summary: 'List runs in a project (paginated)',
+        pathParams: [],
+        isWrite: false,
+    },
+    {
+        resource: 'result',
+        action: 'list',
+        summary: 'List results for a run (paginated)',
+        pathParams: [],
+        isWrite: false,
+    },
+    {
+        resource: 'milestone',
+        action: 'get',
+        summary: 'Fetch a single milestone by ID',
+        pathParams: [{ name: 'milestone_id', description: 'TestRail milestone ID' }],
+        isWrite: false,
+    },
+    {
+        resource: 'milestone',
+        action: 'list',
+        summary: 'List milestones in a project (paginated)',
+        pathParams: [],
+        isWrite: false,
+    },
+    {
+        resource: 'user',
+        action: 'get',
+        summary: 'Fetch a single user by ID',
+        pathParams: [{ name: 'user_id', description: 'TestRail user ID' }],
+        isWrite: false,
+    },
+    {
+        resource: 'user',
+        action: 'list',
+        summary: 'List users (paginated)',
+        pathParams: [],
+        isWrite: false,
+    },
+    // ── Write actions ─────────────────────────────────────────────────────
+    {
+        resource: 'case',
+        action: 'add',
+        summary: 'Create a new test case under a section',
+        pathParams: [{ name: 'section_id', description: 'Section to create the case under' }],
+        bodySchema: AddCasePayloadSchema,
+        isWrite: true,
+    },
+    {
+        resource: 'case',
+        action: 'update',
+        summary: 'Update an existing test case (partial fields)',
+        pathParams: [{ name: 'case_id', description: 'TestRail case ID' }],
+        bodySchema: UpdateCasePayloadSchema,
+        isWrite: true,
+    },
+    {
+        resource: 'run',
+        action: 'add',
+        summary: 'Create a new test run in a project',
+        pathParams: [{ name: 'project_id', description: 'TestRail project ID' }],
+        bodySchema: AddRunPayloadSchema,
+        isWrite: true,
+    },
+    {
+        resource: 'run',
+        action: 'close',
+        summary: 'Close a test run (no body)',
+        pathParams: [{ name: 'run_id', description: 'TestRail run ID' }],
+        isWrite: true,
+    },
+    {
+        resource: 'result',
+        action: 'add',
+        summary: 'Record a single result for a case in a run',
+        pathParams: [
+            { name: 'run_id', description: 'TestRail run ID' },
+            { name: 'case_id', description: 'TestRail case ID' },
+        ],
+        bodySchema: AddResultPayloadSchema,
+        isWrite: true,
+    },
+    {
+        resource: 'result',
+        action: 'add-bulk',
+        summary: 'Record multiple results for cases in one API call',
+        pathParams: [{ name: 'run_id', description: 'TestRail run ID' }],
+        bodySchema: AddResultsForCasesPayloadSchema,
+        isWrite: true,
+    },
+];
+
+/** Look up the spec for a resource:action pair, or return undefined. */
+export function getActionSpec(resource: string, action: string): ActionSpec | undefined {
+    return ACTIONS.find((a) => a.resource === resource && a.action === action);
+}

package/src/cli/output.ts

@@ -0,0 +1,96 @@
+export interface OutputOptions {
+    quiet: boolean;
+    format: 'json' | 'table';
+}
+
+export interface Output {
+    out: (data: unknown) => void;
+    err: (message: string) => void;
+}
+
+export function valueToString(v: unknown): string {
+    if (v === null || v === undefined) return '';
+    if (typeof v === 'object') {
+        try {
+            return JSON.stringify(v);
+        } catch {
+            // JSON.stringify throws on circular refs and nested BigInt.
+            return '[Object]';
+        }
+    }
+    if (typeof v === 'string') return v;
+    if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint') return String(v);
+    if (typeof v === 'symbol') return v.toString();
+    return '[Function]';
+}
+
+function getField(row: unknown, key: string): unknown {
+    if (typeof row !== 'object' || row === null) return undefined;
+    return (row as Record<string, unknown>)[key];
+}
+
+export function renderTable(data: unknown): string {
+    const rows: unknown[] = Array.isArray(data) ? (data as unknown[]) : [data];
+    if (rows.length === 0) return '(empty)';
+
+    const first: unknown = rows[0];
+    if (typeof first !== 'object' || first === null) {
+        return rows.map(String).join('\n');
+    }
+
+    const keys = Object.keys(first);
+    const widths = keys.map((k) => Math.max(k.length, ...rows.map((r) => valueToString(getField(r, k)).length)));
+
+    const line = widths.map((w) => '-'.repeat(w)).join('-+-');
+    const header = keys.map((k, i) => k.padEnd(widths[i] ?? k.length)).join(' | ');
+    const body = rows.map((r) =>
+        keys.map((k, i) => valueToString(getField(r, k)).padEnd(widths[i] ?? k.length)).join(' | '),
+    );
+
+    return [header, line, ...body].join('\n');
+}
+
+/**
+ * Best-effort JSON.stringify with two fallbacks, guaranteeing the return
+ * value is always parseable JSON for downstream tools (e.g., `jq`):
+ *
+ * 1. If serialization throws (circular reference, nested BigInt, etc.),
+ *    emit a structured `{ error, message }` JSON object.
+ * 2. If `JSON.stringify` returns the JS value `undefined` — which it does
+ *    for `undefined`, function, or symbol inputs — emit the JSON literal
+ *    `"null"`. Without this guard, the caller's template literal would
+ *    coerce that `undefined` to the string `"undefined"`, which is not
+ *    valid JSON.
+ *
+ * Exported so unit tests can verify the fallbacks without spawning a
+ * subprocess.
+ */
+export function safeJsonStringify(data: unknown): string {
+    try {
+        // JSON.stringify returns the JS value undefined for inputs without a
+        // JSON representation (undefined, function, symbol); fall back to the
+        // JSON literal "null" so the result is always a parseable string.
+        return JSON.stringify(data, null, 2) ?? 'null';
+    } catch (e) {
+        return JSON.stringify(
+            { error: 'unserializable', message: e instanceof Error ? e.message : String(e) },
+            null,
+            2,
+        );
+    }
+}
+
+export function createOutput(opts: OutputOptions): Output {
+    const out = (data: unknown): void => {
+        if (opts.quiet) return;
+        if (opts.format === 'table') {
+            process.stdout.write(`${renderTable(data)}\n`);
+        } else {
+            process.stdout.write(`${safeJsonStringify(data)}\n`);
+        }
+    };
+    const err = (message: string): void => {
+        if (!opts.quiet) process.stderr.write(`Error: ${message}\n`);
+    };
+    return { out, err };
+}

package/src/cli.ts

@@ -1,287 +1,2 @@
 #!/usr/bin/env node
-import { parseArgs } from 'node:util';
-import { createRequire } from 'node:module';
-import { TestRailClient } from './client.js';
-import type { TestRailConfig } from './types.js';
-
-// ── Version ───────────────────────────────────────────────────────────────────
-
-const require = createRequire(import.meta.url);
-const VERSION: string = (require('../package.json') as { version: string }).version;
-
-// ── Arg Parsing ───────────────────────────────────────────────────────────────
-
-const { values, positionals } = parseArgs({
-    args: process.argv.slice(2),
-    options: {
-        'base-url': { type: 'string' },
-        email: { type: 'string' },
-        'api-key': { type: 'string' },
-        format: { type: 'string', default: 'json' },
-        quiet: { type: 'boolean', default: false },
-        help: { type: 'boolean', default: false },
-        version: { type: 'boolean', default: false },
-        'project-id': { type: 'string' },
-        'suite-id': { type: 'string' },
-        'run-id': { type: 'string' },
-        'case-id': { type: 'string' },
-        limit: { type: 'string' },
-        offset: { type: 'string' },
-    },
-    allowPositionals: true,
-    strict: false,
-});
-
-// ── Output Helpers ────────────────────────────────────────────────────────────
-
-const quiet = values.quiet === true;
-const format = values.format ?? 'json';
-
-function out(data: unknown): void {
-    if (quiet) return;
-    if (format === 'table') {
-        process.stdout.write(`${renderTable(data)}\n`);
-    } else {
-        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
-    }
-}
-
-function err(message: string): void {
-    if (!quiet) process.stderr.write(`Error: ${message}\n`);
-}
-
-function valueToString(v: unknown): string {
-    if (v === null || v === undefined) return '';
-    if (typeof v === 'object') return JSON.stringify(v);
-    if (typeof v === 'string') return v;
-    if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint') return String(v);
-    if (typeof v === 'symbol') return v.toString();
-    return '[Function]';
-}
-
-function renderTable(data: unknown): string {
-    const rows: unknown[] = Array.isArray(data) ? (data as unknown[]) : [data];
-    if (rows.length === 0) return '(empty)';
-
-    const first: unknown = rows[0];
-    if (typeof first !== 'object' || first === null) {
-        return rows.map(String).join('\n');
-    }
-
-    const keys = Object.keys(first);
-    const widths = keys.map((k) =>
-        Math.max(k.length, ...rows.map((r) => valueToString((r as Record<string, unknown>)[k]).length)),
-    );
-
-    const line = widths.map((w) => '-'.repeat(w)).join('-+-');
-    const header = keys.map((k, i) => k.padEnd(widths[i] ?? k.length)).join(' | ');
-    const body = rows.map((r) =>
-        keys.map((k, i) => valueToString((r as Record<string, unknown>)[k]).padEnd(widths[i] ?? k.length)).join(' | '),
-    );
-
-    return [header, line, ...body].join('\n');
-}
-
-// ── Help ──────────────────────────────────────────────────────────────────────
-
-const HELP = `
-testrail <resource> <action> [id] [options]
-
-Resources & actions:
-  project  get <id> | list [--limit N] [--offset N]
-  suite    get <id> | list --project-id <id>
-  case     get <id> | list --project-id <id> [--suite-id <id>]
-  run      get <id> | list --project-id <id> [--limit N] [--offset N]
-  result   list --run-id <id> [--limit N] [--offset N]
-  milestone  get <id> | list --project-id <id> [--limit N] [--offset N]
-  user     get <id> | list [--limit N] [--offset N]
-
-Auth (env var or flag):
-  TESTRAIL_BASE_URL / --base-url <url>
-  TESTRAIL_EMAIL    / --email <email>
-  TESTRAIL_API_KEY  / --api-key <key>
-
-Options:
-  --format json|table   Output format (default: json)
-  --quiet               Suppress output; use exit code 0/1
-  --help                Show this help
-  --version             Print version
-`.trim();
-
-// ── Entry Point ───────────────────────────────────────────────────────────────
-
-if (values.version === true) {
-    process.stdout.write(`testrail-cli v${VERSION}\n`);
-    process.exit(0);
-}
-
-if (values.help === true || positionals.length === 0) {
-    process.stdout.write(`${HELP}\n`);
-    process.exit(0);
-}
-
-const [resource, action, idArg] = positionals;
-
-if (resource === undefined || resource === '' || action === undefined || action === '') {
-    process.stderr.write('Usage: testrail <resource> <action> [id] [options]\nRun with --help for details.\n');
-    process.exit(1);
-}
-
-// ── Auth Resolution ───────────────────────────────────────────────────────────
-
-const baseUrl = (values['base-url'] as string | undefined) ?? process.env['TESTRAIL_BASE_URL'];
-const email = (values['email'] as string | undefined) ?? process.env['TESTRAIL_EMAIL'];
-const apiKey = (values['api-key'] as string | undefined) ?? process.env['TESTRAIL_API_KEY'];
-
-if (
-    baseUrl === undefined ||
-    baseUrl === '' ||
-    email === undefined ||
-    email === '' ||
-    apiKey === undefined ||
-    apiKey === ''
-) {
-    err(
-        'Missing auth. Set TESTRAIL_BASE_URL, TESTRAIL_EMAIL, TESTRAIL_API_KEY or use --base-url, --email, --api-key flags.',
-    );
-    process.exit(1);
-}
-
-const config: TestRailConfig = { baseUrl, email, apiKey };
-const client = new TestRailClient(config);
-
-// ── Numeric Helpers ───────────────────────────────────────────────────────────
-
-function parseId(raw: string | undefined, name: string): number {
-    const n = Number(raw);
-    if (raw === undefined || raw === '' || !Number.isInteger(n) || n <= 0) {
-        err(`${name} must be a positive integer (got: ${raw ?? '(none)'})`);
-        process.exit(1);
-    }
-    return n;
-}
-
-function optInt(raw: string | undefined): number | undefined {
-    if (raw === undefined) return undefined;
-    const n = Number(raw);
-    return Number.isInteger(n) && n >= 0 ? n : undefined;
-}
-
-const suiteId = optInt(values['suite-id'] as string | undefined);
-const limit = optInt(values.limit as string | undefined);
-const offset = optInt(values.offset as string | undefined);
-
-// ── Command Dispatch ──────────────────────────────────────────────────────────
-
-async function run(res: string, act: string): Promise<void> {
-    switch (res) {
-        case 'project': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'project id');
-                out(await client.getProject(id));
-            } else if (act === 'list') {
-                out(await client.getProjects(limit, offset));
-            } else {
-                err(`Unknown action '${act}' for project. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'suite': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'suite id');
-                out(await client.getSuite(id));
-            } else if (act === 'list') {
-                const pid = parseId(values['project-id'] as string | undefined, '--project-id');
-                out(await client.getSuites(pid));
-            } else {
-                err(`Unknown action '${act}' for suite. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'case': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'case id');
-                out(await client.getCase(id));
-            } else if (act === 'list') {
-                const pid = parseId(values['project-id'] as string | undefined, '--project-id');
-                out(await client.getCases(pid, suiteId !== undefined ? { suiteId } : undefined));
-            } else {
-                err(`Unknown action '${act}' for case. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'run': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'run id');
-                out(await client.getRun(id));
-            } else if (act === 'list') {
-                const pid = parseId(values['project-id'] as string | undefined, '--project-id');
-                out(
-                    await client.getRuns(pid, {
-                        ...(limit !== undefined && { limit }),
-                        ...(offset !== undefined && { offset }),
-                    }),
-                );
-            } else {
-                err(`Unknown action '${act}' for run. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'result': {
-            if (act === 'list') {
-                const rid = parseId(values['run-id'] as string | undefined, '--run-id');
-                const resultOpts = { ...(limit !== undefined && { limit }), ...(offset !== undefined && { offset }) };
-                out(await client.getResultsForRun(rid, resultOpts));
-            } else {
-                err(`Unknown action '${act}' for result. Use: list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'milestone': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'milestone id');
-                out(await client.getMilestone(id));
-            } else if (act === 'list') {
-                const pid = parseId(values['project-id'] as string | undefined, '--project-id');
-                const msOpts = { ...(limit !== undefined && { limit }), ...(offset !== undefined && { offset }) };
-                out(await client.getMilestones(pid, msOpts));
-            } else {
-                err(`Unknown action '${act}' for milestone. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'user': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'user id');
-                out(await client.getUser(id));
-            } else if (act === 'list') {
-                out(await client.getUsers(limit, offset));
-            } else {
-                err(`Unknown action '${act}' for user. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        default: {
-            err(`Unknown resource '${res}'. Use: project, suite, case, run, result, milestone, user`);
-            process.exit(1);
-        }
-    }
-}
-
-run(resource, action)
-    .then(() => {
-        client.destroy();
-        process.exit(0);
-    })
-    .catch((e: unknown) => {
-        err(e instanceof Error ? e.message : String(e));
-        client.destroy();
-        process.exit(1);
-    });
+import './cli/index.js';