@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/src/cli/handlers/case.ts

@@ -0,0 +1,13 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId, optInt } from '../ids.js';
+
+export async function handleCaseGet(ctx: HandlerContext): Promise<void> {
+    const id = parseId(ctx.args.pathParams[0], 'case id');
+    ctx.out(await ctx.client.getCase(id));
+}
+
+export async function handleCaseList(ctx: HandlerContext): Promise<void> {
+    const pid = parseId(ctx.args.projectId, '--project-id');
+    const suiteId = optInt(ctx.args.suiteId);
+    ctx.out(await ctx.client.getCases(pid, suiteId !== undefined ? { suiteId } : undefined));
+}

package/src/cli/handlers/milestone.ts

@@ -0,0 +1,19 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId, optInt } from '../ids.js';
+
+export async function handleMilestoneGet(ctx: HandlerContext): Promise<void> {
+    const id = parseId(ctx.args.pathParams[0], 'milestone id');
+    ctx.out(await ctx.client.getMilestone(id));
+}
+
+export async function handleMilestoneList(ctx: HandlerContext): Promise<void> {
+    const pid = parseId(ctx.args.projectId, '--project-id');
+    const limit = optInt(ctx.args.limit);
+    const offset = optInt(ctx.args.offset);
+    ctx.out(
+        await ctx.client.getMilestones(pid, {
+            ...(limit !== undefined && { limit }),
+            ...(offset !== undefined && { offset }),
+        }),
+    );
+}

package/src/cli/handlers/project.ts

@@ -0,0 +1,13 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId, optInt } from '../ids.js';
+
+export async function handleProjectGet(ctx: HandlerContext): Promise<void> {
+    const id = parseId(ctx.args.pathParams[0], 'project id');
+    ctx.out(await ctx.client.getProject(id));
+}
+
+export async function handleProjectList(ctx: HandlerContext): Promise<void> {
+    const limit = optInt(ctx.args.limit);
+    const offset = optInt(ctx.args.offset);
+    ctx.out(await ctx.client.getProjects(limit, offset));
+}

package/src/cli/handlers/result-write.ts

@@ -0,0 +1,40 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId } from '../ids.js';
+import { resolveBody } from '../body.js';
+import { AddResultPayloadSchema, AddResultsForCasesPayloadSchema } from '../../schemas.js';
+
+export async function handleResultAdd(ctx: HandlerContext): Promise<void> {
+    const runId = parseId(ctx.args.pathParams[0], 'run_id');
+    const caseId = parseId(ctx.args.pathParams[1], 'case_id');
+    const body = resolveBody(ctx.bodyInput, AddResultPayloadSchema);
+    if (!body.ok) throw new Error(body.error);
+    if (ctx.dryRun) {
+        ctx.out({
+            dryRun: true,
+            action: 'result add',
+            runId,
+            caseId,
+            payload: body.payload,
+            source: body.source,
+        });
+        return;
+    }
+    ctx.out(await ctx.client.addResultForCase(runId, caseId, body.payload));
+}
+
+export async function handleResultAddBulk(ctx: HandlerContext): Promise<void> {
+    const runId = parseId(ctx.args.pathParams[0], 'run_id');
+    const body = resolveBody(ctx.bodyInput, AddResultsForCasesPayloadSchema);
+    if (!body.ok) throw new Error(body.error);
+    if (ctx.dryRun) {
+        ctx.out({
+            dryRun: true,
+            action: 'result add-bulk',
+            runId,
+            payload: body.payload,
+            source: body.source,
+        });
+        return;
+    }
+    ctx.out(await ctx.client.addResultsForCases(runId, body.payload));
+}

package/src/cli/handlers/result.ts

@@ -0,0 +1,14 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId, optInt } from '../ids.js';
+
+export async function handleResultList(ctx: HandlerContext): Promise<void> {
+    const rid = parseId(ctx.args.runId, '--run-id');
+    const limit = optInt(ctx.args.limit);
+    const offset = optInt(ctx.args.offset);
+    ctx.out(
+        await ctx.client.getResultsForRun(rid, {
+            ...(limit !== undefined && { limit }),
+            ...(offset !== undefined && { offset }),
+        }),
+    );
+}

package/src/cli/handlers/run-write.ts

@@ -0,0 +1,30 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId } from '../ids.js';
+import { resolveBody } from '../body.js';
+import { AddRunPayloadSchema } from '../../schemas.js';
+
+export async function handleRunAdd(ctx: HandlerContext): Promise<void> {
+    const projectId = parseId(ctx.args.pathParams[0], 'project_id');
+    const body = resolveBody(ctx.bodyInput, AddRunPayloadSchema);
+    if (!body.ok) throw new Error(body.error);
+    if (ctx.dryRun) {
+        ctx.out({ dryRun: true, action: 'run add', projectId, payload: body.payload, source: body.source });
+        return;
+    }
+    ctx.out(await ctx.client.addRun(projectId, body.payload));
+}
+
+/**
+ * Close a run. Unlike the other write actions this takes no body — just a
+ * single `run_id` path param. POST has no payload, so the body-source
+ * resolver is not consulted; any `--data` / `--data-file` / stdin supplied
+ * for this action is silently ignored.
+ */
+export async function handleRunClose(ctx: HandlerContext): Promise<void> {
+    const runId = parseId(ctx.args.pathParams[0], 'run_id');
+    if (ctx.dryRun) {
+        ctx.out({ dryRun: true, action: 'run close', runId });
+        return;
+    }
+    ctx.out(await ctx.client.closeRun(runId));
+}

package/src/cli/handlers/run.ts

@@ -0,0 +1,19 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId, optInt } from '../ids.js';
+
+export async function handleRunGet(ctx: HandlerContext): Promise<void> {
+    const id = parseId(ctx.args.pathParams[0], 'run id');
+    ctx.out(await ctx.client.getRun(id));
+}
+
+export async function handleRunList(ctx: HandlerContext): Promise<void> {
+    const pid = parseId(ctx.args.projectId, '--project-id');
+    const limit = optInt(ctx.args.limit);
+    const offset = optInt(ctx.args.offset);
+    ctx.out(
+        await ctx.client.getRuns(pid, {
+            ...(limit !== undefined && { limit }),
+            ...(offset !== undefined && { offset }),
+        }),
+    );
+}

package/src/cli/handlers/suite.ts

@@ -0,0 +1,12 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId } from '../ids.js';
+
+export async function handleSuiteGet(ctx: HandlerContext): Promise<void> {
+    const id = parseId(ctx.args.pathParams[0], 'suite id');
+    ctx.out(await ctx.client.getSuite(id));
+}
+
+export async function handleSuiteList(ctx: HandlerContext): Promise<void> {
+    const pid = parseId(ctx.args.projectId, '--project-id');
+    ctx.out(await ctx.client.getSuites(pid));
+}

package/src/cli/handlers/user.ts

@@ -0,0 +1,13 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId, optInt } from '../ids.js';
+
+export async function handleUserGet(ctx: HandlerContext): Promise<void> {
+    const id = parseId(ctx.args.pathParams[0], 'user id');
+    ctx.out(await ctx.client.getUser(id));
+}
+
+export async function handleUserList(ctx: HandlerContext): Promise<void> {
+    const limit = optInt(ctx.args.limit);
+    const offset = optInt(ctx.args.offset);
+    ctx.out(await ctx.client.getUsers(limit, offset));
+}

package/src/cli/ids.ts

@@ -0,0 +1,20 @@
+export class IdParseError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'IdParseError';
+    }
+}
+
+export function parseId(raw: string | undefined, name: string): number {
+    const n = Number(raw);
+    if (raw === undefined || raw === '' || !Number.isInteger(n) || n <= 0) {
+        throw new IdParseError(`${name} must be a positive integer (got: ${raw ?? '(none)'})`);
+    }
+    return n;
+}
+
+export function optInt(raw: string | undefined): number | undefined {
+    if (raw === undefined) return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}

package/src/cli/index.ts

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { TestRailClient } from '../client.js';
+import { resolveAuth } from './auth.js';
+import { createOutput } from './output.js';
+import { dispatch } from './dispatch.js';
+import { runInstallSkill } from './install-skill.js';
+import type { BodyInput, HandlerArgs } from './handler-context.js';
+
+// ── Version ───────────────────────────────────────────────────────────────────
+
+const require = createRequire(import.meta.url);
+const VERSION: string = (require('../../package.json') as { version: string }).version;
+
+// ── Help ──────────────────────────────────────────────────────────────────────
+
+const HELP = `
+testrail <resource> <action> [args] [options]
+
+Read 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]
+
+Write actions (body via --data | --data-file | stdin):
+  case   add <section_id>           --data '{"title":"..."}'
+  case   update <case_id>           --data '{"title":"..."}'
+  run    add <project_id>           --data '{"name":"..."}'
+  run    close <run_id>             (no body)
+  result add <run_id> <case_id>     --data '{"status_id":1}'
+  result add-bulk <run_id>          --data '{"results":[{"case_id":1,"status_id":1}]}'
+
+Meta:
+  install-skill [--global] [--force] [--print-path]
+                                    Install the testrail-cli skill to
+                                    ./.claude/skills/testrail-cli (default)
+                                    or ~/.claude/skills/testrail-cli (--global)
+
+Auth (env var or flag):
+  TESTRAIL_BASE_URL / --base-url <url>
+  TESTRAIL_EMAIL    / --email <email>
+  TESTRAIL_API_KEY  / --api-key <key>
+
+Options:
+  --data <json>         Inline JSON body for write actions
+  --data-file <path>    Read JSON body from file
+  --dry-run             Validate payload but don't call the API
+  --format json|table   Output format (default: json)
+  --quiet               Suppress output; use exit code 0/1
+  --global              install-skill: install to ~/.claude/skills/ (default: ./.claude/skills/)
+  --force               install-skill: overwrite an existing SKILL.md
+  --print-path          install-skill: print bundled SKILL.md path and exit
+  --help                Show this help
+  --version             Print version
+
+For body-bearing write actions (all except 'run close'), exactly one body source
+is required (--data | --data-file | stdin). Stdin is auto-detected when input
+is piped (process.stdin.isTTY === false).
+`.trim();
+
+// ── Entry Point ───────────────────────────────────────────────────────────────
+
+/**
+ * Compute exit code in an async function and apply `process.exit()` once
+ * at the very end. parseArgs and createOutput are invoked inside main() so
+ * any failure during initialization (e.g. an invalid CLI shape that makes
+ * parseArgs throw) is funneled through the same exit-code return path
+ * rather than escaping as an uncaught module-evaluation error.
+ */
+async function main(): Promise<number> {
+    let values: Record<string, unknown>;
+    let positionals: string[];
+    try {
+        const parsed = 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' },
+                data: { type: 'string' },
+                'data-file': { type: 'string' },
+                'dry-run': { type: 'boolean', default: false },
+                global: { type: 'boolean', default: false },
+                force: { type: 'boolean', default: false },
+                'print-path': { type: 'boolean', default: false },
+            },
+            allowPositionals: true,
+            strict: false,
+        });
+        values = parsed.values;
+        positionals = parsed.positionals;
+        /* v8 ignore start -- defensive: parseArgs with strict:false is highly
+           tolerant; this catch funnels any future-Node-version edge cases
+           through the controlled exit path rather than crashing the module. */
+    } catch (e: unknown) {
+        process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    /* v8 ignore stop */
+
+    const quiet = values['quiet'] === true;
+    const formatRaw = values['format'];
+    const format: 'json' | 'table' = formatRaw === 'table' ? 'table' : 'json';
+    const { out, err } = createOutput({ quiet, format });
+
+    if (values['version'] === true) {
+        process.stdout.write(`testrail-cli v${VERSION}\n`);
+        return 0;
+    }
+
+    if (values['help'] === true || positionals.length === 0) {
+        process.stdout.write(`${HELP}\n`);
+        return 0;
+    }
+
+    // `install-skill` is a meta-command (manages the bundled skill on the
+    // user's filesystem). It deliberately sits outside the normal
+    // resource:action dispatch since there is no API call involved.
+    if (positionals[0] === 'install-skill') {
+        return runInstallSkill(
+            {
+                global: values['global'] === true,
+                force: values['force'] === true,
+                printPath: values['print-path'] === true,
+                quiet,
+            },
+            import.meta.url,
+        );
+    }
+
+    const [resource, action, ...rest] = positionals;
+    const pathParams: readonly string[] = rest;
+
+    if (resource === undefined || resource === '' || action === undefined || action === '') {
+        process.stderr.write('Usage: testrail <resource> <action> [args] [options]\nRun with --help for details.\n');
+        return 1;
+    }
+
+    const dispatched = dispatch(resource, action);
+    if (!dispatched.ok) {
+        err(dispatched.error);
+        return 1;
+    }
+
+    const auth = resolveAuth(
+        {
+            baseUrl: values['base-url'] as string | undefined,
+            email: values['email'] as string | undefined,
+            apiKey: values['api-key'] as string | undefined,
+        },
+        {
+            ...(process.env['TESTRAIL_BASE_URL'] !== undefined && {
+                TESTRAIL_BASE_URL: process.env['TESTRAIL_BASE_URL'],
+            }),
+            ...(process.env['TESTRAIL_EMAIL'] !== undefined && { TESTRAIL_EMAIL: process.env['TESTRAIL_EMAIL'] }),
+            ...(process.env['TESTRAIL_API_KEY'] !== undefined && { TESTRAIL_API_KEY: process.env['TESTRAIL_API_KEY'] }),
+        },
+    );
+
+    if (!auth.ok) {
+        err(auth.error);
+        return 1;
+    }
+
+    const args: HandlerArgs = {
+        pathParams,
+        ...(values['project-id'] !== undefined && { projectId: values['project-id'] as string }),
+        ...(values['suite-id'] !== undefined && { suiteId: values['suite-id'] as string }),
+        ...(values['run-id'] !== undefined && { runId: values['run-id'] as string }),
+        ...(values['case-id'] !== undefined && { caseId: values['case-id'] as string }),
+        ...(values['limit'] !== undefined && { limit: values['limit'] as string }),
+        ...(values['offset'] !== undefined && { offset: values['offset'] as string }),
+    };
+
+    const bodyInput: BodyInput = {
+        ...(values['data'] !== undefined && { dataFlag: values['data'] as string }),
+        ...(values['data-file'] !== undefined && { dataFileFlag: values['data-file'] as string }),
+        // Pass a thunk (not the read contents) so resolveBody() only drains
+        // stdin when it actually selects stdin as the body source. Read
+        // actions, no-body writes (`run close`), and write actions that
+        // received --data or --data-file never invoke this.
+        ...(process.stdin.isTTY === false && { readStdin: () => readFileSync(0, 'utf-8') }),
+    };
+
+    const dryRun = values['dry-run'] === true;
+
+    let client: TestRailClient | undefined;
+    try {
+        client = new TestRailClient(auth.config);
+        await dispatched.handler({ client, args, bodyInput, dryRun, out });
+        return 0;
+    } catch (e: unknown) {
+        err(e instanceof Error ? e.message : String(e));
+        return 1;
+    } finally {
+        client?.destroy();
+    }
+}
+
+/* v8 ignore start -- defensive: main() catches all reachable errors internally; this handler exists only for hypothetical failures (e.g., broken-pipe in process.stdout.write) that bypass the inner try/catch. */
+main().then(
+    (code) => process.exit(code),
+    (e: unknown) => {
+        process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    },
+);
+/* v8 ignore stop */

package/src/cli/install-skill.ts

@@ -0,0 +1,89 @@
+/**
+ * `testrail install-skill` — copy the bundled SKILL.md from this package's
+ * own `skill/` directory into a Claude Code skills folder so the agent can
+ * auto-load it.
+ *
+ * Defaults: project-scoped install (`./.claude/skills/testrail-cli/`).
+ * Pass `--global` for `~/.claude/skills/testrail-cli/`. Pass `--force` to
+ * overwrite an existing file. Pass `--print-path` to print the bundled
+ * source path without installing (useful for vendoring / scripting).
+ *
+ * This is a meta-command — it operates on the user's filesystem, not on
+ * TestRail — so it sits outside the normal `resource:action` dispatch.
+ * Invoked directly from `index.ts` when positionals[0] === 'install-skill'.
+ */
+
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface InstallSkillOptions {
+    global: boolean;
+    force: boolean;
+    printPath: boolean;
+    quiet: boolean;
+    /** Override for tests; resolved from import.meta.url otherwise. */
+    sourceOverride?: string;
+    /** Override target root for tests; otherwise `homedir()` or `process.cwd()`. */
+    cwdOverride?: string;
+    homeOverride?: string;
+}
+
+/**
+ * Resolves the bundled `skill/SKILL.md` path. At runtime, the compiled
+ * handler lives at `<packageRoot>/dist/cli/install-skill.js`; the bundled
+ * skill ships in `<packageRoot>/skill/SKILL.md`. Two `..` segments climb
+ * from `dist/cli/` (the handler's dirname) to the package root, then
+ * `skill/SKILL.md` reaches the bundled file.
+ */
+export function getBundledSkillPath(metaUrl: string): string {
+    return resolve(dirname(fileURLToPath(metaUrl)), '..', '..', 'skill', 'SKILL.md');
+}
+
+export function runInstallSkill(opts: InstallSkillOptions, metaUrl: string): number {
+    // Match the rest of the CLI's --quiet semantics (createOutput in
+    // output.ts): when quiet, suppress both stdout success messages AND
+    // stderr errors. Callers rely on exit code 0/1 only.
+    const writeErr = (message: string): void => {
+        if (!opts.quiet) process.stderr.write(`Error: ${message}\n`);
+    };
+
+    const source = opts.sourceOverride ?? getBundledSkillPath(metaUrl);
+
+    if (opts.printPath) {
+        if (!opts.quiet) process.stdout.write(`${source}\n`);
+        return 0;
+    }
+
+    if (!existsSync(source)) {
+        writeErr(`bundled SKILL.md not found at ${source}`);
+        return 1;
+    }
+
+    const targetRoot = opts.global ? (opts.homeOverride ?? homedir()) : (opts.cwdOverride ?? process.cwd());
+    const target = join(targetRoot, '.claude', 'skills', 'testrail-cli', 'SKILL.md');
+
+    if (existsSync(target) && !opts.force) {
+        writeErr(`SKILL.md already exists at ${target}. Re-run with --force to overwrite.`);
+        return 1;
+    }
+
+    try {
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(source, target);
+        /* v8 ignore start -- defensive: triggered only by filesystem failures
+           (permission denied, full disk, etc.) that are flaky to simulate in
+           CI. The error path is exercised manually if invoked under an
+           unwritable HOME. */
+    } catch (e: unknown) {
+        writeErr(`failed to install skill: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+    /* v8 ignore stop */
+
+    if (!opts.quiet) {
+        process.stdout.write(`Installed testrail-cli skill → ${target}\n`);
+    }
+    return 0;
+}