@agnox/mcp-server 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @agnox/mcp-server
+
+> **Drive [Agnox](https://agnox.dev) from your AI coding assistant and your terminal.**
+
+[![npm](https://img.shields.io/npm/v/@agnox/mcp-server)](https://www.npmjs.com/package/@agnox/mcp-server)
+[![node](https://img.shields.io/node/v/@agnox/mcp-server)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@agnox/mcp-server)](#license)
+
+One package, two commands:
+
+- **`mcp-server`**: an [MCP](https://modelcontextprotocol.io) server for Claude Code, Claude Desktop, Cursor and Windsurf. Your assistant can read why a run failed, including the page context at the moment of failure, quarantine a flaky test, and register the tests in your repo as Agnox test cases.
+- **`agnox`**: a CLI that lists runs, prints failures, triggers a run and waits for it, and exports manual test cases as Playwright spec skeletons.
+
+Both talk only to the Agnox public API (`/api/v1`). The package has no runtime dependencies and needs Node.js 20 or later.
+
+📖 **Full documentation:** [MCP server](https://docs.agnox.dev/docs/developer-tools/mcp-server) · [CLI](https://docs.agnox.dev/docs/developer-tools/cli) · [Public API v1](https://docs.agnox.dev/docs/api-reference/public-api-v1)
+
+## Quick start
+
+```bash
+# Claude Code
+claude mcp add agnox -e AGNOX_API_KEY=<your key> -- npx -y @agnox/mcp-server
+
+# Terminal
+AGNOX_API_KEY=<your key> npx -p @agnox/mcp-server agnox runs list
+```
+
+---
+
+## Configuration
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `AGNOX_API_KEY` | yes | | An API key from **Settings → My Profile → API keys**. Its role decides what it can do: viewers can only read. |
+| `AGNOX_API_URL` | no | `https://api.agnox.dev` | Your Agnox API, for a self-hosted install. Must be `https://`; plain `http://` is accepted only for `localhost`, `127.0.0.1` and `[::1]`. No credentials, query or fragment. Redirects are never followed, so the key cannot be sent to another host |
+| `AGNOX_PROJECT_ID` | no | | The default project for tools and commands |
+
+The key is sent only in the `x-api-key` header. It is never printed, logged or included in an error message.
+
+---
+
+## MCP server
+
+### Claude Code
+
+```bash
+claude mcp add agnox \
+  -e AGNOX_API_KEY=<your key> \
+  -e AGNOX_PROJECT_ID=<project id> \
+  -- npx -y @agnox/mcp-server
+```
+
+Or commit a project-scoped `.mcp.json`, and give each developer their own key through their environment:
+
+```json
+{
+  "mcpServers": {
+    "agnox": {
+      "command": "npx",
+      "args": ["-y", "@agnox/mcp-server"],
+      "env": {
+        "AGNOX_API_URL": "https://api.agnox.dev",
+        "AGNOX_API_KEY": "${AGNOX_API_KEY}",
+        "AGNOX_PROJECT_ID": "<project id>"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
+
+```json
+{
+  "mcpServers": {
+    "agnox": {
+      "command": "npx",
+      "args": ["-y", "@agnox/mcp-server"],
+      "env": {
+        "AGNOX_API_URL": "https://api.agnox.dev",
+        "AGNOX_API_KEY": "<your key>",
+        "AGNOX_PROJECT_ID": "<project id>"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+**Settings → Developer → Edit Config** opens `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`). Add the server and restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "agnox": {
+      "command": "npx",
+      "args": ["-y", "@agnox/mcp-server"],
+      "env": {
+        "AGNOX_API_KEY": "<your key>",
+        "AGNOX_PROJECT_ID": "<project id>"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Use the same `mcpServers` block in `~/.codeium/windsurf/mcp_config.json`.
+
+> On Windows, if the client cannot start `npx` directly, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@agnox/mcp-server"]`.
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `list_recent_executions` | Recent runs, newest first, with status and passed/failed counts. Optional `projectId`, `status`, `limit` (at most 25). |
+| `get_execution_failures` | Failed tests of a run (`taskId`): name, spec file, error, failure signature, test key, linked test case, and the page context at failure: URL, title, console and network errors, test ids and a DOM snapshot (cut at 4 000 characters). |
+| `get_flaky_and_quarantined_tests` | Tests that are quarantined or have a stability score of D or F. |
+| `toggle_test_quarantine` | Quarantine (`quarantined: true`) or release a test, by `testCaseId`, or by `testKey` from `get_execution_failures`. By key, the test case is created when it does not exist yet; give a `title`. |
+| `sync_test_cases` | Register tests from the code (`tests: [{ file, titlePath }]`, at most 500) as automated test cases, so they can be tracked and quarantined before their first run. |
+| `list_failure_clusters` | The most frequent failure signatures across recent runs (`days`, 1–30). Needs the Root Cause Analysis feature. |
+
+Results are a one-line summary followed by compact JSON, with lists capped at 20 items. A failing call returns a readable error to the assistant instead of breaking the session.
+
+Things to ask:
+
+- *"Why did the last failed Agnox run fail? Fix the broken locator."*
+- *"Which tests are flaky in Agnox? Quarantine the checkout one."*
+- *"Register every test in `tests/` with Agnox."*
+
+The server speaks JSON-RPC 2.0 over stdio, one message per line. It supports MCP protocol versions `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`. `agnox mcp` starts the same server.
+
+---
+
+## CLI
+
+Install it, or run it once through npx:
+
+```bash
+npm i -g @agnox/mcp-server         # then: agnox --help
+npx -p @agnox/mcp-server agnox --help
+```
+
+| Command | Behaviour |
+|---|---|
+| `agnox runs list [--project <id>] [--status <s>] [--limit <n>] [--json]` | Table of recent runs: task id, status, start, duration, passed/failed |
+| `agnox runs failures <taskId> [--json]` | One block per failed test: name, file, signature and the first error lines |
+| `agnox trigger --image <img> --command <cmd> --env <development\|staging\|production> [--project <id>] [--base-url <url>] [--folder <path>] [--wait] [--timeout <sec>]` | Starts a run. With `--wait`, polls every 5 s until it finishes (default timeout 1 800 s). |
+| `agnox export-specs --out <dir> [--project <id>] [--folder <path>] [--force]` | Writes a Playwright skeleton per top-level folder of manual test cases. Only flat lower-case `*.spec.ts` names are written (at most 500 files, 5 MB each); symbolic links are never written through. Existing files are kept unless you pass `--force`. |
+| `agnox mcp` | Runs the MCP server on stdio |
+| `agnox --help`, `agnox --version` | |
+
+`--json` prints the API data as JSON, for scripts. Exit codes: **0** success, **1** API or usage error, **2** the run finished but did not pass (`trigger --wait`).
+
+```yaml
+# GitHub Actions: run the suite on Agnox and fail the job when it fails
+- run: npx -p @agnox/mcp-server agnox trigger --image ghcr.io/acme/e2e:latest --command "npx playwright test" --env staging --wait
+  env:
+    AGNOX_API_KEY: ${{ secrets.AGNOX_API_KEY }}
+    AGNOX_PROJECT_ID: ${{ vars.AGNOX_PROJECT_ID }}
+```
+
+Generated specs mark every test `test.fixme(...)`, so a skeleton never passes before someone implements it.
+
+---
+
+## Public API
+
+The package is a thin client of the documented [Agnox Public API v1](https://docs.agnox.dev/docs/api-reference/public-api-v1). The OpenAPI 3.1 document is at `https://api.agnox.dev/api/openapi.json` (and `.yaml`).
+
+Moving test cases in from Qase, TestRail, Xray or Zephyr Scale? See [Migrate & Export Test Cases](https://docs.agnox.dev/docs/core-features/migrate-test-cases).
+
+## License
+
+MIT

package/dist/bin/agnox.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/agnox.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from '../cli.js';
+const code = await runCli(process.argv.slice(2), {
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+    env: process.env,
+    cwd: process.cwd(),
+    streams: { input: process.stdin, output: process.stdout },
+});
+process.exitCode = code;
+//# sourceMappingURL=agnox.js.map

package/dist/bin/agnox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agnox.js","sourceRoot":"","sources":["../../src/bin/agnox.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC7C,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;IACnD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;IACnD,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;CAC5D,CAAC,CAAC;AACH,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC"}

package/dist/bin/mcp-server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/mcp-server.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { startMcpServer } from '../commands/mcp.js';
+await startMcpServer(process.env, process.stdin, process.stdout, (line) => process.stderr.write(`${line}\n`));
+//# sourceMappingURL=mcp-server.js.map

package/dist/bin/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../../src/bin/mcp-server.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The agnox command line. Results go to stdout, diagnostics to stderr.
+ * Exit codes: 0 success, 1 API or usage error, 2 a run finished but did not pass (trigger --wait).
+ */
+import type { Readable, Writable } from 'node:stream';
+import { AgnoxClient } from './client.js';
+import { type CliFs } from './commands/context.js';
+export interface ICliIo {
+    stdout(line: string): void;
+    stderr(line: string): void;
+    env: Record<string, string | undefined>;
+    cwd: string;
+    /** Injected in tests; otherwise built from the environment. */
+    client?: AgnoxClient;
+    fs?: CliFs;
+    sleep?: (ms: number) => Promise<void>;
+    /** stdin/stdout for `agnox mcp`. */
+    streams?: {
+        input: Readable;
+        output: Writable;
+    };
+}
+export declare const HELP = "agnox 1.0.1 \u2014 Agnox from the terminal\n\nUsage:\n  agnox runs list [--project <id>] [--status <s>] [--limit <n>] [--json]\n  agnox runs failures <taskId> [--json]\n  agnox trigger --image <img> --command <cmd> --env <development|staging|production>\n                [--project <id>] [--base-url <url>] [--folder <path>] [--wait] [--timeout <sec>] [--json]\n  agnox export-specs --out <dir> [--project <id>] [--folder <path>] [--force]\n  agnox mcp                  Run the MCP server on stdio (for Claude Code, Cursor, Windsurf)\n  agnox --help | --version\n\nEnvironment:\n  AGNOX_API_KEY     API key from Settings \u2192 My Profile (required)\n  AGNOX_API_URL     default https://api.agnox.dev\n  AGNOX_PROJECT_ID  default project for --project\n\nExit codes: 0 success \u00B7 1 error \u00B7 2 run finished but did not pass (trigger --wait)";
+export declare function runCli(argv: string[], io: ICliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,102 @@
+/**
+ * The agnox command line. Results go to stdout, diagnostics to stderr.
+ * Exit codes: 0 success, 1 API or usage error, 2 a run finished but did not pass (trigger --wait).
+ */
+import * as fsPromises from 'node:fs/promises';
+import { AgnoxApiError, AgnoxClient } from './client.js';
+import { ConfigError, loadConfig } from './config.js';
+import { VERSION } from './version.js';
+import { sanitizeForTerminal } from './format.js';
+import { UsageError } from './commands/context.js';
+import { runsFailures, runsList } from './commands/runs.js';
+import { trigger } from './commands/trigger.js';
+import { exportSpecs } from './commands/export-specs.js';
+import { startMcpServer } from './commands/mcp.js';
+export const HELP = `agnox ${VERSION} — Agnox from the terminal
+
+Usage:
+  agnox runs list [--project <id>] [--status <s>] [--limit <n>] [--json]
+  agnox runs failures <taskId> [--json]
+  agnox trigger --image <img> --command <cmd> --env <development|staging|production>
+                [--project <id>] [--base-url <url>] [--folder <path>] [--wait] [--timeout <sec>] [--json]
+  agnox export-specs --out <dir> [--project <id>] [--folder <path>] [--force]
+  agnox mcp                  Run the MCP server on stdio (for Claude Code, Cursor, Windsurf)
+  agnox --help | --version
+
+Environment:
+  AGNOX_API_KEY     API key from Settings → My Profile (required)
+  AGNOX_API_URL     default https://api.agnox.dev
+  AGNOX_PROJECT_ID  default project for --project
+
+Exit codes: 0 success · 1 error · 2 run finished but did not pass (trigger --wait)`;
+const COMMANDS = {
+    'runs list': runsList,
+    'runs failures': runsFailures,
+    trigger,
+    'export-specs': exportSpecs,
+};
+function resolveCommand(argv) {
+    const two = argv.slice(0, 2).join(' ');
+    if (COMMANDS[two])
+        return { command: COMMANDS[two], args: argv.slice(2) };
+    if (argv[0] && COMMANDS[argv[0]])
+        return { command: COMMANDS[argv[0]], args: argv.slice(1) };
+    return null;
+}
+const realSleep = (ms) => new Promise((done) => setTimeout(done, ms));
+export async function runCli(argv, io) {
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+        for (const line of HELP.split('\n'))
+            io.stdout(line);
+        return 0;
+    }
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        io.stdout(VERSION);
+        return 0;
+    }
+    if (argv[0] === 'mcp') {
+        if (argv.length > 1) {
+            io.stderr('agnox mcp takes no arguments; configure it with AGNOX_API_KEY, AGNOX_API_URL and AGNOX_PROJECT_ID');
+            return 1;
+        }
+        if (!io.streams) {
+            io.stderr('agnox mcp needs stdin and stdout');
+            return 1;
+        }
+        await startMcpServer(io.env, io.streams.input, io.streams.output, io.stderr);
+        return 0;
+    }
+    const resolved = resolveCommand(argv);
+    if (!resolved) {
+        io.stderr(`Unknown command "${argv.join(' ')}". Run agnox --help.`);
+        return 1;
+    }
+    try {
+        const client = io.client ?? new AgnoxClient(loadConfig(io.env));
+        const ctx = {
+            client,
+            defaultProjectId: io.env.AGNOX_PROJECT_ID?.trim() || undefined,
+            stdout: io.stdout,
+            stderr: io.stderr,
+            cwd: io.cwd,
+            fs: io.fs ?? fsPromises,
+            sleep: io.sleep ?? realSleep,
+        };
+        return await resolved.command(resolved.args, ctx);
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof UsageError || error instanceof AgnoxApiError) {
+            io.stderr(error instanceof AgnoxApiError ? `Error: ${sanitizeForTerminal(error.message)}` : error.message);
+            return 1;
+        }
+        // parseArgs rejects unknown or malformed options with a TypeError carrying an ERR_PARSE_ARGS_* code
+        const code = error?.code;
+        if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS')) {
+            io.stderr(`${error.message}. Run agnox --help.`);
+            return 1;
+        }
+        io.stderr(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Small client for the Agnox public API (/api/v1). Zero dependencies: it uses
+ * the global fetch (Node 20+), which tests replace with a fake.
+ *
+ * The API key is sent as x-api-key and is never part of an error message.
+ */
+import type { IAgnoxConfig } from './config.js';
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export interface IPage<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+export interface IProject {
+    id: string;
+    name: string;
+    slug: string | null;
+}
+export interface IExecution {
+    taskId: string;
+    projectId: string | null;
+    status: string;
+    environment: string | null;
+    trigger: string | null;
+    groupName: string | null;
+    startTime: string | null;
+    endTime: string | null;
+    durationMs: number | null;
+    total: number;
+    passed: number;
+    failed: number;
+}
+export interface IFailureContext {
+    failureUrl?: string;
+    pageTitle?: string;
+    pageErrors?: string[];
+    consoleErrors?: string[];
+    networkErrors?: Array<{
+        url: string;
+        status?: number;
+        method?: string;
+        resourceType?: string;
+    }>;
+    domSnapshot?: string;
+    testIds?: string[];
+}
+export interface IFailure {
+    name: string;
+    file?: string;
+    testKey?: string;
+    testCaseId?: string;
+    error?: string;
+    failureSignature?: string;
+    isQuarantined: boolean;
+    attemptCount?: number;
+    context: IFailureContext;
+    analysis?: {
+        rootCause: string;
+        suggestedFix: string;
+        generatedAt: string | null;
+    };
+}
+export interface IFailures {
+    taskId: string;
+    projectId: string | null;
+    items: IFailure[];
+}
+export interface IUnstableTest {
+    id: string;
+    tcId?: string;
+    title: string;
+    file?: string;
+    testKey?: string;
+    isQuarantined: boolean;
+    quarantineSource?: string;
+    quarantinedAt?: string;
+    stabilityScore?: string;
+}
+export interface IQuarantineResult {
+    id: string;
+    tcId?: string;
+    projectId: string;
+    title: string;
+    testKey?: string;
+    isQuarantined: boolean;
+    quarantineSource?: string;
+    stabilityScore?: string;
+}
+export interface ISyncResult {
+    received: number;
+    created: number;
+    alreadyLinked: number;
+    skipped: number;
+}
+export interface ICluster {
+    signature: string;
+    occurrences: number;
+    runCount: number;
+    testCount: number;
+    tests: string[];
+    firstSeen: string | null;
+    lastSeen: string | null;
+    sampleError: string;
+    lastCorrelation?: {
+        classification: string;
+        confidence: string;
+        createdAt: string | null;
+    };
+}
+export interface IExportFile {
+    path: string;
+    content: string;
+}
+export interface ITriggerRequest {
+    projectId: string;
+    image: string;
+    command: string;
+    folder?: string;
+    config: {
+        environment: 'development' | 'staging' | 'production';
+        baseUrl?: string;
+    };
+    ciContext: {
+        source: 'github' | 'gitlab' | 'azure' | 'jenkins' | 'webhook';
+        repository?: string;
+        prNumber?: number;
+        commitSha?: string;
+    };
+    createCycle?: boolean;
+    cycleId?: string;
+}
+export interface IQuarantineRequest {
+    quarantined: boolean;
+    testCaseId?: string;
+    projectId?: string;
+    testKey?: string;
+    title?: string;
+    file?: string;
+}
+export interface ISyncRequest {
+    projectId: string;
+    tests: Array<{
+        file: string;
+        titlePath: string[];
+    }>;
+}
+export interface IExportRequest {
+    projectId: string;
+    format: 'json' | 'csv' | 'markdown' | 'playwright';
+    folderPath?: string;
+    ids?: string[];
+}
+export declare class AgnoxApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export declare class AgnoxClient {
+    private readonly config;
+    private readonly fetchImpl;
+    private readonly host;
+    constructor(config: IAgnoxConfig, fetchImpl?: typeof fetch);
+    /** Remove the key from any text that might be shown to a person or a model. */
+    private redact;
+    private request;
+    listProjects(): Promise<IPage<IProject>>;
+    listExecutions(query?: {
+        projectId?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<IPage<IExecution>>;
+    getExecution(taskId: string): Promise<IExecution>;
+    getExecutionFailures(taskId: string): Promise<IFailures>;
+    triggerExecution(body: ITriggerRequest): Promise<{
+        taskId: string;
+        cycleId?: string;
+    }>;
+    listUnstableTests(projectId: string, query?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<IPage<IUnstableTest>>;
+    setQuarantine(body: IQuarantineRequest): Promise<IQuarantineResult>;
+    syncTestCases(body: ISyncRequest): Promise<ISyncResult>;
+    listFailureClusters(query?: {
+        projectId?: string;
+        days?: number;
+        limit?: number;
+    }): Promise<{
+        items: ICluster[];
+    }>;
+    exportTestCases(body: IExportRequest): Promise<{
+        files: IExportFile[];
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,117 @@
+/**
+ * Small client for the Agnox public API (/api/v1). Zero dependencies: it uses
+ * the global fetch (Node 20+), which tests replace with a fake.
+ *
+ * The API key is sent as x-api-key and is never part of an error message.
+ */
+import { VERSION } from './version.js';
+export const REQUEST_TIMEOUT_MS = 30_000;
+// ── Errors ────────────────────────────────────────────────────────────────────
+export class AgnoxApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'AgnoxApiError';
+    }
+}
+export class AgnoxClient {
+    config;
+    fetchImpl;
+    host;
+    constructor(config, fetchImpl = globalThis.fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+        this.host = new URL(config.apiUrl).host;
+    }
+    /** Remove the key from any text that might be shown to a person or a model. */
+    redact(text) {
+        return this.config.apiKey ? text.split(this.config.apiKey).join('[redacted]') : text;
+    }
+    async request(method, path, options = {}) {
+        const url = new URL(`${this.config.apiUrl}/api/v1${path}`);
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== '')
+                url.searchParams.set(name, String(value));
+        }
+        const headers = {
+            'x-api-key': this.config.apiKey,
+            'user-agent': `agnox-cli/${VERSION}`,
+            accept: 'application/json',
+        };
+        if (options.body !== undefined)
+            headers['content-type'] = 'application/json';
+        let response;
+        try {
+            response = await this.fetchImpl(url.toString(), {
+                method,
+                headers,
+                // The key must never follow a redirect to another host.
+                redirect: 'manual',
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            const name = error instanceof Error ? error.name : '';
+            if (name === 'TimeoutError' || name === 'AbortError') {
+                throw new AgnoxApiError(`Agnox at ${this.host} did not answer within ${REQUEST_TIMEOUT_MS / 1000} s`, 0, 'TIMEOUT');
+            }
+            const cause = error instanceof Error && error.cause instanceof Error ? error.cause.message : error instanceof Error ? error.message : String(error);
+            throw new AgnoxApiError(this.redact(`Could not reach Agnox at ${this.host}: ${cause}`), 0, 'NETWORK_ERROR');
+        }
+        if (response.status >= 300 && response.status <= 399) {
+            throw new AgnoxApiError(`Agnox at ${this.host} answered with a redirect; check AGNOX_API_URL`, response.status, 'REDIRECT_REFUSED');
+        }
+        let payload;
+        try {
+            payload = (await response.json());
+        }
+        catch {
+            payload = undefined;
+        }
+        if (!response.ok || !payload || payload.success !== true) {
+            const code = typeof payload?.code === 'string' ? payload.code : undefined;
+            let message = typeof payload?.error === 'string' && payload.error
+                ? payload.error
+                : `Unexpected response (HTTP ${response.status}) from ${this.host}`;
+            if (response.status === 401)
+                message += ' — check AGNOX_API_KEY';
+            throw new AgnoxApiError(this.redact(message), response.status, code);
+        }
+        return payload.data;
+    }
+    listProjects() {
+        return this.request('GET', '/projects', { query: { limit: 100 } });
+    }
+    listExecutions(query = {}) {
+        return this.request('GET', '/executions', { query });
+    }
+    getExecution(taskId) {
+        return this.request('GET', `/executions/${encodeURIComponent(taskId)}`);
+    }
+    getExecutionFailures(taskId) {
+        return this.request('GET', `/executions/${encodeURIComponent(taskId)}/failures`);
+    }
+    triggerExecution(body) {
+        return this.request('POST', '/executions', { body });
+    }
+    listUnstableTests(projectId, query = {}) {
+        return this.request('GET', '/quality/unstable-tests', { query: { projectId, ...query } });
+    }
+    setQuarantine(body) {
+        return this.request('POST', '/test-cases/quarantine', { body });
+    }
+    syncTestCases(body) {
+        return this.request('POST', '/test-cases/sync', { body });
+    }
+    listFailureClusters(query = {}) {
+        return this.request('GET', '/failure-clusters', { query });
+    }
+    exportTestCases(body) {
+        return this.request('POST', '/test-cases/export', { body });
+    }
+}
+//# sourceMappingURL=client.js.map