mcp-vitals 0.1.0

package/dist/commands/call.js

@@ -0,0 +1,84 @@
+import { buildContext, buildSpec } from '../context.js';
+import { Connection } from '../mcpClient.js';
+import { resolveArgs } from '../args.js';
+import { AssertionFailure, ToolErrorExit, UsageError } from '../errors.js';
+import { makeColors } from '../renderers/colors.js';
+import { emitJson } from '../renderers/json.js';
+import { formatMs } from '../renderers/table.js';
+import { writeOut } from '../output.js';
+import { Progress } from '../renderers/progress.js';
+function renderContentText(content) {
+    const parts = [];
+    for (const block of content) {
+        if (block.type === 'text')
+            parts.push(block.text ?? '');
+        else if (block.type === 'image')
+            parts.push(`[image ${block.mimeType ?? '?'} ${sizeOf(block.data)}]`);
+        else if (block.type === 'audio')
+            parts.push(`[audio ${block.mimeType ?? '?'} ${sizeOf(block.data)}]`);
+        else if (block.type === 'resource')
+            parts.push(`[resource ${block.resource?.uri ?? '?'}]`);
+        else
+            parts.push(`[${block.type ?? 'unknown'}]`);
+    }
+    return parts.join('\n');
+}
+function sizeOf(data) {
+    if (!data)
+        return '0 B';
+    const bytes = Math.floor((data.length * 3) / 4);
+    return bytes >= 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${bytes} B`;
+}
+export async function runCall(server, opts) {
+    if (!opts.tool)
+        throw new UsageError('--tool <name> is required');
+    const ctx = buildContext(opts);
+    const spec = buildSpec(opts, server);
+    const c = makeColors(ctx.color);
+    const progress = new Progress({ quiet: ctx.quiet, json: ctx.json });
+    const args = await resolveArgs(opts.args);
+    progress.note(c.dim('connecting…'));
+    const conn = await Connection.connect(spec);
+    const t0 = process.hrtime.bigint();
+    const result = await conn.callTool(opts.tool, args);
+    const durationMs = Number(process.hrtime.bigint() - t0) / 1e6;
+    await conn.close();
+    const text = renderContentText(result.content);
+    if (ctx.json) {
+        emitJson({
+            ok: opts.expectError ? result.isError : !result.isError,
+            tool: opts.tool,
+            args,
+            durationMs,
+            isError: result.isError,
+            content: result.content,
+            structuredContent: result.structuredContent,
+        });
+    }
+    else if (opts.raw) {
+        writeOut(text);
+    }
+    else {
+        if (result.isError) {
+            writeOut(c.red(text));
+        }
+        else {
+            writeOut(text);
+            if (result.structuredContent !== undefined) {
+                writeOut('');
+                writeOut(c.dim('structured:') + ' ' + JSON.stringify(result.structuredContent));
+            }
+        }
+        progress.note(c.dim(`done in ${formatMs(durationMs)}`));
+    }
+    if (opts.expectError) {
+        if (!result.isError) {
+            throw new AssertionFailure(`expected tool "${opts.tool}" to error, but it succeeded`);
+        }
+        return 0;
+    }
+    if (result.isError) {
+        throw new ToolErrorExit(`tool "${opts.tool}" returned an error`);
+    }
+    return 0;
+}

package/dist/commands/check.d.ts

@@ -0,0 +1,13 @@
+import type { CommonOpts } from '../context.js';
+export interface CheckOpts extends CommonOpts {
+    config?: string;
+    junit?: string;
+    only: string[];
+    skip: string[];
+    iterations?: number;
+    warmup?: number;
+    concurrency?: number;
+    bail: boolean;
+    latency: boolean;
+}
+export declare function runCheck(server: string[], opts: CheckOpts): Promise<number>;

package/dist/commands/check.js

@@ -0,0 +1,140 @@
+import { writeFile } from 'node:fs/promises';
+import { assertNoSwallowedFlags, buildContext, stripSeparator } from '../context.js';
+import { Connection } from '../mcpClient.js';
+import { loadConfig } from '../assertions/loader.js';
+import { runChecks } from '../assertions/run.js';
+import { AssertionFailure, UsageError } from '../errors.js';
+import { makeColors } from '../renderers/colors.js';
+import { emitJson } from '../renderers/json.js';
+import { renderJUnit } from '../renderers/junit.js';
+import { renderTable } from '../renderers/table.js';
+import { writeOut } from '../output.js';
+import { Progress } from '../renderers/progress.js';
+function parseKv(items, sep, label) {
+    const out = {};
+    for (const item of items) {
+        const i = item.indexOf(sep);
+        if (i <= 0)
+            throw new UsageError(`invalid ${label} "${item}" (expected K${sep}V)`);
+        out[item.slice(0, i).trim()] = item.slice(i + sep.length).trim();
+    }
+    return out;
+}
+/** Combine the config's server block with any CLI overrides + positional command. */
+function buildCheckSpec(config, opts, server) {
+    const s = config.server;
+    const cleaned = stripSeparator(server);
+    const positional = cleaned[0];
+    const cliUrl = opts.url !== undefined && opts.url !== '' ? opts.url : undefined;
+    let command;
+    let args = [];
+    let url;
+    if (positional) {
+        command = positional;
+        args = cleaned.slice(1);
+    }
+    else if (cliUrl) {
+        url = cliUrl;
+    }
+    else if (s.url) {
+        url = s.url;
+    }
+    else {
+        command = s.command;
+        args = s.args ?? [];
+    }
+    const requestTimeoutMs = opts.timeout ?? s.timeoutMs ?? 10_000;
+    const connectTimeoutMs = opts.connectTimeout ?? s.connectTimeoutMs ?? requestTimeoutMs;
+    const forced = opts.transport ?? s.transport;
+    return {
+        forced,
+        command,
+        args,
+        url,
+        headers: { ...(s.headers ?? {}), ...parseKv(opts.header, ':', '--header') },
+        env: { ...(s.env ?? {}), ...parseKv(opts.env, '=', '--env') },
+        inheritEnv: opts.inheritEnv === true,
+        connectTimeoutMs,
+        requestTimeoutMs,
+    };
+}
+const GROUPS = [
+    ['presence', 'Capabilities'],
+    ['schema', 'Schemas'],
+    ['latency', 'Latency SLAs'],
+];
+function statusCell(status, c) {
+    if (status === 'pass')
+        return c.green('PASS');
+    if (status === 'fail')
+        return c.red('FAIL');
+    return c.dim('SKIP');
+}
+export async function runCheck(server, opts) {
+    const ctx = buildContext(opts);
+    const c = makeColors(ctx.color);
+    const progress = new Progress({ quiet: ctx.quiet, json: ctx.json });
+    if (ctx.json && opts.junit === '-') {
+        throw new UsageError('--junit - conflicts with --json (both write stdout); give --junit a file path');
+    }
+    assertNoSwallowedFlags(server);
+    const { path, config } = await loadConfig(opts.config);
+    progress.note(c.dim(`loaded ${path}`));
+    const spec = buildCheckSpec(config, opts, server);
+    progress.note(c.dim('connecting…'));
+    const conn = await Connection.connect(spec);
+    const { rows, summary } = await runChecks(conn, config, {
+        noLatency: opts.latency === false,
+        only: opts.only,
+        skip: opts.skip,
+        bail: opts.bail === true,
+        iterations: opts.iterations,
+        warmup: opts.warmup,
+        concurrency: opts.concurrency,
+        timeoutMs: spec.requestTimeoutMs,
+    });
+    await conn.close();
+    if (opts.junit) {
+        const xml = renderJUnit(rows, summary);
+        if (opts.junit === '-')
+            process.stdout.write(xml + '\n');
+        else
+            await writeFile(opts.junit, xml, 'utf8');
+    }
+    if (ctx.json) {
+        emitJson({
+            ok: summary.failed === 0,
+            config: path,
+            suites: rows.map((r) => ({
+                id: r.id,
+                kind: r.kind,
+                target: r.target,
+                expected: r.expected,
+                actual: r.actual,
+                status: r.status,
+            })),
+            summary,
+        });
+    }
+    else {
+        for (const [kind, label] of GROUPS) {
+            const groupRows = rows.filter((r) => r.kind === kind);
+            if (groupRows.length === 0)
+                continue;
+            writeOut('');
+            writeOut(c.bold(label));
+            writeOut(renderTable([{ header: 'CHECK' }, { header: 'EXPECTED' }, { header: 'ACTUAL' }, { header: 'STATUS' }], groupRows.map((r) => [r.id, r.expected, r.actual, statusCell(r.status, c)]), c));
+        }
+        writeOut('');
+        const parts = [
+            c.green(`${summary.passed} passed`),
+            summary.failed ? c.red(`${summary.failed} failed`) : `${summary.failed} failed`,
+            c.dim(`${summary.skipped} skipped`),
+        ];
+        writeOut(`${parts.join(', ')} ${c.dim(`in ${(summary.durationMs / 1000).toFixed(2)}s`)}`);
+    }
+    if (summary.failed > 0) {
+        throw new AssertionFailure(`${summary.failed} check(s) failed`);
+    }
+    return 0;
+}

package/dist/commands/inspect.d.ts

@@ -0,0 +1,10 @@
+import type { CommonOpts } from '../context.js';
+export interface InspectOpts extends CommonOpts {
+    tools?: boolean;
+    resources?: boolean;
+    prompts?: boolean;
+    schema?: boolean;
+    validateSchemas: boolean;
+    filter?: string;
+}
+export declare function runInspect(server: string[], opts: InspectOpts): Promise<number>;

package/dist/commands/inspect.js

@@ -0,0 +1,129 @@
+import { buildContext, buildSpec } from '../context.js';
+import { Connection } from '../mcpClient.js';
+import { validateJsonSchema } from '../schema.js';
+import { matchesAny } from '../glob.js';
+import { AssertionFailure } from '../errors.js';
+import { makeColors } from '../renderers/colors.js';
+import { emitJson } from '../renderers/json.js';
+import { renderKeyValues, renderTable } from '../renderers/table.js';
+import { writeOut } from '../output.js';
+import { Progress } from '../renderers/progress.js';
+export async function runInspect(server, opts) {
+    const ctx = buildContext(opts);
+    const spec = buildSpec(opts, server);
+    const c = makeColors(ctx.color);
+    const progress = new Progress({ quiet: ctx.quiet, json: ctx.json });
+    const wantAll = !opts.tools && !opts.resources && !opts.prompts;
+    const wantTools = wantAll || opts.tools === true;
+    const wantResources = wantAll || opts.resources === true;
+    const wantPrompts = wantAll || opts.prompts === true;
+    const filter = (name) => matchesAny(name, opts.filter ? [opts.filter] : undefined);
+    progress.note(c.dim('connecting…'));
+    const conn = await Connection.connect(spec);
+    const identity = conn.identity();
+    const caps = conn.capabilities();
+    let tools = wantTools ? await conn.listTools() : [];
+    tools = tools.filter((t) => filter(t.name));
+    const resources = (wantResources ? await conn.listResources() : []).filter((r) => filter(r.name ?? r.uri));
+    const prompts = (wantPrompts ? await conn.listPrompts() : []).filter((p) => filter(p.name));
+    let invalid = 0;
+    if (opts.validateSchemas) {
+        for (const t of tools) {
+            const res = validateJsonSchema(t.inputSchema);
+            t.schemaValid = res.valid;
+            t.schemaErrors = res.errors;
+            if (!res.valid)
+                invalid++;
+        }
+    }
+    await conn.close();
+    const schemasValid = tools.length - invalid;
+    const ok = invalid === 0;
+    if (ctx.json) {
+        emitJson({
+            ok,
+            server: identity,
+            transport: conn.kind,
+            capabilities: { ...caps.raw, tools: caps.tools, resources: caps.resources, prompts: caps.prompts },
+            tools: tools.map((t) => ({
+                name: t.name,
+                title: t.title,
+                description: t.description,
+                ...(opts.schema ? { inputSchema: t.inputSchema } : {}),
+                requiredArgs: t.requiredArgs,
+                totalArgs: t.totalArgs,
+                schemaValid: t.schemaValid,
+                schemaErrors: t.schemaErrors,
+            })),
+            resources: resources.map((r) => ({ uri: r.uri, name: r.name, mimeType: r.mimeType })),
+            prompts: prompts.map((p) => ({ name: p.name, arguments: p.arguments })),
+            summary: {
+                tools: tools.length,
+                resources: resources.length,
+                prompts: prompts.length,
+                schemasValid,
+                schemasInvalid: invalid,
+            },
+        });
+    }
+    else {
+        progress.clearStatus();
+        writeOut(renderKeyValues([
+            ['Server', `${c.bold(identity.name)} ${c.dim('v' + identity.version)}`],
+            ['Protocol', identity.protocolVersion ?? '—'],
+            ['Transport', conn.kind],
+            [
+                'Capabilities',
+                [
+                    caps.tools ? c.green('tools') : c.dim('tools'),
+                    caps.resources ? c.green('resources') : c.dim('resources'),
+                    caps.prompts ? c.green('prompts') : c.dim('prompts'),
+                ].join('  '),
+            ],
+        ], c));
+        if (identity.instructions) {
+            writeOut('');
+            writeOut(c.dim(identity.instructions));
+        }
+        if (wantTools) {
+            writeOut('');
+            writeOut(c.bold(`Tools (${tools.length})`));
+            if (tools.length > 0) {
+                writeOut(renderTable([
+                    { header: 'NAME' },
+                    { header: 'ARGS', align: 'right' },
+                    { header: 'SCHEMA' },
+                    { header: 'DESCRIPTION' },
+                ], tools.map((t) => [
+                    t.name,
+                    `${t.requiredArgs}/${t.totalArgs}`,
+                    opts.validateSchemas ? (t.schemaValid ? c.green('ok') : c.red('invalid')) : c.dim('—'),
+                    truncate(t.description ?? '', 48),
+                ]), c));
+            }
+        }
+        if (wantResources && resources.length > 0) {
+            writeOut('');
+            writeOut(c.bold(`Resources (${resources.length})`));
+            writeOut(renderTable([{ header: 'URI' }, { header: 'NAME' }, { header: 'TYPE' }], resources.map((r) => [r.uri, r.name ?? '', r.mimeType ?? '']), c));
+        }
+        if (wantPrompts && prompts.length > 0) {
+            writeOut('');
+            writeOut(c.bold(`Prompts (${prompts.length})`));
+            writeOut(renderTable([{ header: 'NAME' }, { header: 'ARGS' }], prompts.map((p) => [p.name, p.arguments.map((a) => a.name).join(', ')]), c));
+        }
+        writeOut('');
+        const schemaNote = opts.validateSchemas
+            ? `schemas: ${c.green(String(schemasValid) + ' ok')}${invalid ? ', ' + c.red(invalid + ' invalid') : ''}`
+            : 'schemas: not validated';
+        writeOut(c.dim(`${tools.length} tools, ${resources.length} resources, ${prompts.length} prompts — ${schemaNote}`));
+    }
+    if (opts.validateSchemas && invalid > 0) {
+        throw new AssertionFailure(`${invalid} tool inputSchema(s) are invalid`);
+    }
+    return 0;
+}
+function truncate(s, n) {
+    const oneLine = s.replace(/\s+/g, ' ').trim();
+    return oneLine.length > n ? oneLine.slice(0, n - 1) + '…' : oneLine;
+}

package/dist/commands/ping.d.ts

@@ -0,0 +1,6 @@
+import type { CommonOpts } from '../context.js';
+export interface PingOpts extends CommonOpts {
+    count: number;
+    list?: boolean;
+}
+export declare function runPing(server: string[], opts: PingOpts): Promise<number>;

package/dist/commands/ping.js

@@ -0,0 +1,55 @@
+import { buildContext, buildSpec } from '../context.js';
+import { Connection } from '../mcpClient.js';
+import { computeStats } from '../stats.js';
+import { makeColors } from '../renderers/colors.js';
+import { emitJson } from '../renderers/json.js';
+import { formatMs } from '../renderers/table.js';
+import { writeOut } from '../output.js';
+import { Progress } from '../renderers/progress.js';
+export async function runPing(server, opts) {
+    const ctx = buildContext(opts);
+    const spec = buildSpec(opts, server);
+    const c = makeColors(ctx.color);
+    const progress = new Progress({ quiet: ctx.quiet, json: ctx.json });
+    const count = Math.max(1, opts.count);
+    const handshakes = [];
+    let lastListMs = null;
+    let target = '';
+    for (let i = 0; i < count; i++) {
+        progress.status(c.dim(`ping ${i + 1}/${count}…`));
+        const conn = await Connection.connect(spec);
+        target = conn.target;
+        handshakes.push(conn.coldStartMs);
+        if (opts.list) {
+            const t0 = process.hrtime.bigint();
+            await conn.listTools();
+            lastListMs = Number(process.hrtime.bigint() - t0) / 1e6;
+        }
+        await conn.close();
+    }
+    progress.clearStatus();
+    const stats = computeStats(handshakes);
+    if (ctx.json) {
+        emitJson({
+            ok: true,
+            target,
+            count,
+            samples: handshakes,
+            handshake: stats
+                ? { min: stats.min, mean: stats.mean, p50: stats.p50, p95: stats.p95, max: stats.max }
+                : null,
+            listToolsMs: lastListMs,
+        });
+        return 0;
+    }
+    if (count === 1) {
+        const list = lastListMs !== null ? `, tools/list ${formatMs(lastListMs)}` : '';
+        writeOut(`${c.green('●')} connected to ${c.bold(target)} in ${c.bold(formatMs(handshakes[0]))}${c.dim(list)}`);
+    }
+    else if (stats) {
+        writeOut(c.bold(`${count} handshakes to ${target}`));
+        writeOut(c.dim('min/mean/p50/p95/max  ') +
+            `${formatMs(stats.min)} / ${formatMs(stats.mean)} / ${formatMs(stats.p50)} / ${formatMs(stats.p95)} / ${formatMs(stats.max)}`);
+    }
+    return 0;
+}

package/dist/context.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from 'commander';
+import type { RunContext, TransportSpec } from './types.js';
+/** Connection-related options shared by every subcommand. */
+export declare function addConnectionOptions(cmd: Command): Command;
+/** Output-related options shared by every subcommand. */
+export declare function addOutputOptions(cmd: Command): Command;
+export interface CommonOpts {
+    url?: string;
+    transport?: string;
+    header: string[];
+    env: string[];
+    inheritEnv: boolean;
+    timeout?: number;
+    connectTimeout?: number;
+    json: boolean;
+    color: boolean;
+    quiet: boolean;
+    verbose: boolean;
+}
+/**
+ * Reject an mcp-vitals long flag that landed after the server command (and so
+ * would be silently passed to the child). Everything after a `--` separator is
+ * explicitly the server's and is never flagged.
+ */
+export declare function assertNoSwallowedFlags(server: string[]): void;
+export declare function buildContext(opts: CommonOpts): RunContext;
+/** Drop the first `--` separator; everything else is the server command + argv. */
+export declare function stripSeparator(server: string[]): string[];
+/** Build the TransportSpec from common options + the positional stdio command. */
+export declare function buildSpec(opts: CommonOpts, server: string[]): TransportSpec;

package/dist/context.js

@@ -0,0 +1,114 @@
+import { UsageError } from './errors.js';
+import { resolveColor } from './renderers/colors.js';
+const DEFAULT_TIMEOUT_MS = 10_000;
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+/** Connection-related options shared by every subcommand. */
+export function addConnectionOptions(cmd) {
+    return cmd
+        .option('--url <url>', 'connect over HTTP/SSE (mutually exclusive with a stdio command)')
+        .option('--transport <kind>', 'force transport: stdio | http | sse')
+        .option('--header <k:v>', 'HTTP header for every request (repeatable)', collect, [])
+        .option('--env <k=v>', 'env var for the stdio child (repeatable)', collect, [])
+        .option('--inherit-env', 'spread process.env into the stdio child before --env vars', false)
+        .option('--timeout <ms>', 'per-request timeout in ms (default 10000)', (v) => parseInt(v, 10))
+        .option('--connect-timeout <ms>', 'handshake timeout in ms (default = --timeout)', (v) => parseInt(v, 10));
+}
+/** Output-related options shared by every subcommand. */
+export function addOutputOptions(cmd) {
+    return cmd
+        .option('--json', 'emit a single JSON object on stdout; all else to stderr', false)
+        .option('--no-color', 'disable ANSI color')
+        .option('-q, --quiet', 'suppress non-error progress on stderr', false)
+        .option('-v, --verbose', 'verbose per-request timing + relay server stderr', false);
+}
+function parseKv(items, sep, label) {
+    const out = {};
+    for (const item of items) {
+        const i = item.indexOf(sep);
+        if (i <= 0)
+            throw new UsageError(`invalid ${label} "${item}" (expected K${sep}V)`);
+        out[item.slice(0, i).trim()] = item.slice(i + sep.length).trim();
+    }
+    return out;
+}
+// Every long option mcp-vitals defines, across all subcommands. Used to catch
+// the passThroughOptions footgun where a vitals flag placed AFTER the server
+// command is silently handed to the child instead of parsed by mcp-vitals.
+const KNOWN_LONG_FLAGS = new Set([
+    '--url', '--transport', '--header', '--env', '--inherit-env', '--timeout',
+    '--connect-timeout', '--json', '--color', '--no-color', '--quiet', '--verbose',
+    '--tools', '--resources', '--prompts', '--schema', '--validate-schemas',
+    '--no-validate-schemas', '--filter', '--count', '--list', '--tool', '--probe',
+    '--args', '--iterations', '--warmup', '--concurrency', '--rps', '--duration',
+    '--fail-on', '--raw', '--expect-error', '--config', '--junit', '--only',
+    '--skip', '--bail', '--latency', '--no-latency', '--help', '--version',
+]);
+/**
+ * Reject an mcp-vitals long flag that landed after the server command (and so
+ * would be silently passed to the child). Everything after a `--` separator is
+ * explicitly the server's and is never flagged.
+ */
+export function assertNoSwallowedFlags(server) {
+    for (const token of server) {
+        if (token === '--')
+            return; // explicit handoff to the server
+        if (token.startsWith('--')) {
+            const base = token.split('=')[0] ?? token;
+            if (KNOWN_LONG_FLAGS.has(base)) {
+                throw new UsageError(`"${base}" looks like an mcp-vitals option but came after the server command, ` +
+                    `so it would be passed to the server instead.\n` +
+                    `  Put mcp-vitals options BEFORE the command, or after "--" to pass it to the server.`);
+            }
+        }
+    }
+}
+function parseTransport(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'stdio' || value === 'http' || value === 'sse')
+        return value;
+    throw new UsageError(`invalid --transport "${value}" (expected stdio | http | sse)`);
+}
+export function buildContext(opts) {
+    return {
+        json: opts.json === true,
+        color: resolveColor(opts.color === false),
+        quiet: opts.quiet === true,
+        verbose: opts.verbose === true,
+    };
+}
+/** Drop the first `--` separator; everything else is the server command + argv. */
+export function stripSeparator(server) {
+    const i = server.indexOf('--');
+    if (i === -1)
+        return server;
+    return [...server.slice(0, i), ...server.slice(i + 1)];
+}
+/** Build the TransportSpec from common options + the positional stdio command. */
+export function buildSpec(opts, server) {
+    assertNoSwallowedFlags(server);
+    const cleaned = stripSeparator(server);
+    const command = cleaned[0];
+    const hasStdio = command !== undefined;
+    const hasUrl = opts.url !== undefined && opts.url !== '';
+    if (hasStdio && hasUrl) {
+        throw new UsageError('pass either a stdio command OR --url, not both');
+    }
+    const requestTimeoutMs = opts.timeout !== undefined && Number.isFinite(opts.timeout) ? opts.timeout : DEFAULT_TIMEOUT_MS;
+    const connectTimeoutMs = opts.connectTimeout !== undefined && Number.isFinite(opts.connectTimeout)
+        ? opts.connectTimeout
+        : requestTimeoutMs;
+    return {
+        forced: parseTransport(opts.transport),
+        command,
+        args: cleaned.slice(1),
+        url: hasUrl ? opts.url : undefined,
+        headers: parseKv(opts.header, ':', '--header'),
+        env: parseKv(opts.env, '=', '--env'),
+        inheritEnv: opts.inheritEnv === true,
+        connectTimeoutMs,
+        requestTimeoutMs,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly ASSERTION: 2;
+    readonly CONNECTION: 3;
+    readonly USAGE: 4;
+    readonly TOOL_ERROR: 5;
+    readonly CONFIG: 6;
+};
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number);
+}
+/** Bad/conflicting flags, malformed --args JSON, etc. */
+export declare class UsageError extends CliError {
+    constructor(message: string);
+}
+/** Could not connect / handshake / initialize. */
+export declare class ConnectionError extends CliError {
+    constructor(message: string);
+}
+/** A `--fail-on` / `check` assertion failed, SLA exceeded, or an invalid schema. */
+export declare class AssertionFailure extends CliError {
+    constructor(message: string);
+}
+/** A single `call` returned isError:true without --expect-error. */
+export declare class ToolErrorExit extends CliError {
+    constructor(message: string);
+}
+/** check assertions file missing / unparseable / schema-invalid. */
+export declare class ConfigError extends CliError {
+    constructor(message: string);
+}
+export declare function toExitCode(err: unknown): number;

package/dist/errors.js

@@ -0,0 +1,52 @@
+// Typed error classes mapped to stable exit codes (see SPEC §6).
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    ASSERTION: 2,
+    CONNECTION: 3,
+    USAGE: 4,
+    TOOL_ERROR: 5,
+    CONFIG: 6,
+};
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.name = new.target.name;
+        this.exitCode = exitCode;
+    }
+}
+/** Bad/conflicting flags, malformed --args JSON, etc. */
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODES.USAGE);
+    }
+}
+/** Could not connect / handshake / initialize. */
+export class ConnectionError extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODES.CONNECTION);
+    }
+}
+/** A `--fail-on` / `check` assertion failed, SLA exceeded, or an invalid schema. */
+export class AssertionFailure extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODES.ASSERTION);
+    }
+}
+/** A single `call` returned isError:true without --expect-error. */
+export class ToolErrorExit extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODES.TOOL_ERROR);
+    }
+}
+/** check assertions file missing / unparseable / schema-invalid. */
+export class ConfigError extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODES.CONFIG);
+    }
+}
+export function toExitCode(err) {
+    if (err instanceof CliError)
+        return err.exitCode;
+    return 1;
+}

package/dist/glob.d.ts

@@ -0,0 +1,3 @@
+export declare function matchesGlob(name: string, glob: string): boolean;
+/** True if `name` matches any of the provided globs (empty list => true). */
+export declare function matchesAny(name: string, globs: string[] | undefined): boolean;