aztrx-cli 0.4.5 → 0.5.2

package/dist/mcp/protocol.js

@@ -0,0 +1,156 @@
+/**
+ * MCP wire format — framing, version negotiation, result envelopes.
+ *
+ * Hand-rolled, deliberately. Revisions `2025-11-25` and earlier open with an
+ * `initialize` handshake; `2026-07-28` removed it in favour of per-request
+ * metadata. Editors are split across the two (Cursor still opens with
+ * `initialize`), and neither official SDK speaks both: `@modelcontextprotocol/sdk`
+ * is legacy-only and pulls 17 runtime dependencies — express, hono, cors, jose,
+ * ajv — for a stdio server that needs none of them, and
+ * `@modelcontextprotocol/server` is the new revision only. A server that speaks
+ * one era is a server that is missing from somebody's editor. The spec has a name
+ * for the thing that speaks both — **dual-era** — and rules for it, which this
+ * follows rather than reinvents.
+ *
+ * This file imports nothing at all. It is loaded before the first request from
+ * an editor, and editors time out servers that boot slowly.
+ */
+/** Every revision this server can serve, oldest first. `2026-07-28` is the one
+ * that made `server/discover` mandatory and `resultType` required; the earlier
+ * four are the handshake era, and `2025-06-18` / `2025-11-25` are what the
+ * editors in the wild actually send today. */
+export const SUPPORTED_VERSIONS = [
+    "2024-11-05",
+    "2025-03-26",
+    "2025-06-18",
+    "2025-11-25",
+    "2026-07-28",
+];
+/** Newest revision implemented. Used only when we cannot serve what was asked
+ * for — never to "upgrade" a client that asked for something older. */
+export const LATEST_VERSION = SUPPORTED_VERSIONS[SUPPORTED_VERSIONS.length - 1];
+/** `_meta` keys, per the `_meta` naming rules in the 2026-07-28 base spec. */
+export const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+/** `UnsupportedProtocolVersionError`, per the 2026-07-28 error-code table. The
+ * number is not decorative: a modern client matches on it to tell "this server
+ * speaks my language but not this dialect — retry with one off `supported`"
+ * from "this server is old", and the two lead to opposite actions. */
+export const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** A failure of the *request* — bad method, bad shape. Distinct from a tool that
+ * ran and reported a problem, which is a normal result with `isError: true`. */
+export class ProtocolError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "ProtocolError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Framing
+// ---------------------------------------------------------------------------
+/** One JSON-RPC message, one line. That is the stdio binding, and `JSON.stringify`
+ * already guarantees it — a newline inside a string is escaped, never emitted raw. */
+export function encode(message) {
+    return JSON.stringify(message) + "\n";
+}
+/** Parse one line. A line that is not JSON has an unknowable id, so the error
+ * goes out with a null one — the JSON-RPC rule for exactly this case. */
+export function decode(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return { ok: false, response: error(null, PARSE_ERROR, "Parse error: line is not JSON") };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, response: error(null, INVALID_REQUEST, "Invalid request: not a JSON object") };
+    }
+    const msg = value;
+    if (typeof msg.method !== "string" && msg.id === undefined) {
+        // A response we have no use for, or a garbage object. Either way there is
+        // nothing to answer: an object with no method is not a request.
+        return { ok: false, response: error(msg.id ?? null, INVALID_REQUEST, "Invalid request: no method") };
+    }
+    return { ok: true, msg };
+}
+/** A request expects exactly one response; a notification expects none, and
+ * answering one is a protocol violation. `id` is what separates them — a
+ * notification simply has no `id` member. */
+export function isNotification(msg) {
+    return typeof msg.method === "string" && (msg.id === undefined || msg.id === null);
+}
+// ---------------------------------------------------------------------------
+// Version negotiation
+// ---------------------------------------------------------------------------
+export function supports(version) {
+    return typeof version === "string" && SUPPORTED_VERSIONS.includes(version);
+}
+/** The version a *modern* request declares in `_meta`, or undefined for a legacy
+ * request (which declares nothing — its version was fixed by `initialize`). */
+export function declaredVersion(msg) {
+    const meta = msg.params?.["_meta"];
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    const v = meta[META_PROTOCOL_VERSION];
+    return typeof v === "string" ? v : undefined;
+}
+/** Which version to answer a legacy `initialize` with.
+ *
+ * The legacy spec makes this a **MUST**, not a courtesy: *"If the server supports
+ * the requested protocol version, it MUST respond with the same version.
+ * Otherwise, the server MUST respond with another protocol version it supports."*
+ * So we echo what was asked for whenever we can serve it. Answering `initialize`
+ * with our newest version when the client asked for an older one we support is a
+ * spec violation, and it is the documented way to make a modern client refuse the
+ * server outright ("Server's protocol version is not supported") — the client has
+ * no fall-forward mechanism, so a needless mismatch is fatal, not merely noisy. */
+export function negotiate(requested) {
+    return supports(requested) ? requested : LATEST_VERSION;
+}
+/** Reject a request that declares a version we do not implement. Returns a
+ * ready-to-send error, or null when the request may proceed.
+ *
+ * Only modern requests declare a version; a legacy request carries none and is
+ * served under legacy semantics for the life of the process. The `data` shape is
+ * exact because it is load-bearing: the client picks a version off `supported`
+ * and retries, so an inexact copy costs it the retry it needs. */
+export function checkVersion(msg) {
+    const declared = declaredVersion(msg);
+    if (declared === undefined || supports(declared))
+        return null;
+    return error(msg.id ?? null, UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", {
+        supported: [...SUPPORTED_VERSIONS],
+        requested: declared,
+    });
+}
+// ---------------------------------------------------------------------------
+// Envelopes
+// ---------------------------------------------------------------------------
+/** A successful result.
+ *
+ * `resultType: "complete"` is required on every result from `2026-07-28` on, and
+ * older clients ignore fields they do not recognise — so it is written
+ * unconditionally rather than behind an era check. One response shape for every
+ * era is the whole reason this server can serve both. */
+export function result(id, payload = {}) {
+    return { jsonrpc: "2.0", id, result: { resultType: "complete", ...payload } };
+}
+export function error(id, code, message, data) {
+    const err = { code, message };
+    if (data !== undefined)
+        err.data = data;
+    return { jsonrpc: "2.0", id: id ?? null, error: err };
+}
+export function serverInfo(version) {
+    return { name: "aztrx-cli", version };
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The three tools, their schemas, and the handlers behind them.
+ *
+ * `aztrx_scan` finds and proves; `aztrx_repro` shows one finding's steps;
+ * `aztrx_fix` patches and verifies. The split is about the agent's context
+ * budget, not about the code: a `Finding` carries a whole minimized action
+ * sequence and a compiled spec, and a fix carries a diff — inlining all of that
+ * into every scan response is how a useful call becomes an expensive one. The
+ * scan returns a compact projection and a handle; detail is fetched by handle.
+ *
+ * Sessions are gone from the protocol in `2026-07-28` and never existed in this
+ * design. Cross-call state is an explicit, opaque, server-minted `scanId` held in
+ * a bounded in-memory map — which is easier to reason about than hidden state, and
+ * is exactly what the spec recommends for stateful tools.
+ *
+ * Nothing here imports the orchestrator, Playwright, or the heal stack. Those are
+ * `await import()`ed on first use, because an editor kills a server that is slow
+ * to answer `initialize` and `core/orchestrator.js` costs ~1.7s to load.
+ */
+import type { HealOptions, HealResult } from "../core/heal/types.js";
+import type { RunOptions } from "../core/orchestrator.js";
+import type { Finding } from "../core/types.js";
+export interface TextBlock {
+    type: "text";
+    text: string;
+}
+/** A tool result. `isError` marks a tool that *ran* and could not do the job —
+ * distinct from a protocol error, which is about the request itself. */
+export interface ToolCallResult {
+    content: TextBlock[];
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+export interface ToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const TOOLS: ToolDefinition[];
+export interface ScanRecord {
+    scanId: string;
+    repoRoot: string;
+    url: string;
+    findings: Finding[];
+    /** Heal results already paid for, so `apply: true` after a review call does not
+     * buy the same patch twice. */
+    heals: Map<string, HealResult>;
+    createdAt: number;
+}
+export type RunFn = (opts: RunOptions) => Promise<Finding[]>;
+export type HealFn = (finding: Finding, opts: HealOptions) => Promise<HealResult>;
+export interface RuntimeDeps {
+    /** Loaded on first use, never at module load. Injectable so the dispatch and
+     * purity tests can run without a browser. */
+    loadRun?: () => Promise<RunFn>;
+    loadHeal?: () => Promise<HealFn>;
+    /** Project used when a tool call does not name one. */
+    defaultRepoRoot?: string;
+}
+export declare class McpRuntime {
+    private deps;
+    private records;
+    /** Dev servers this process booted and has not yet stopped. The server tears
+     * these down on shutdown — a scan interrupted by a closing editor must not
+     * leave a dev server holding its port. */
+    private openTargets;
+    /** Scans and fixes run one at a time; see `serialize`. */
+    private queue;
+    constructor(deps?: RuntimeDeps);
+    call(name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
+    /** Stop every dev server this process started. Idempotent. */
+    closeAll(): Promise<void>;
+    /** One scanning run at a time.
+     *
+     * `run()` truncates `.aztrx/events.jsonl` and rewrites `.aztrx/report.html` and
+     * `.aztrx/repro/<id>.spec.ts`, and a zero-config scan boots a dev server on a
+     * port it picked. Two overlapping runs in one repo therefore corrupt each
+     * other's artifacts and race for the port — and an MCP client can pipeline
+     * requests, so this is a real case rather than a theoretical one. `heal`
+     * creates git worktrees and boots servers of its own, so it shares the queue. */
+    private serialize;
+    private defaultRepo;
+    private loadRun;
+    private loadHeal;
+    private remember;
+    private scan;
+    /** Find a running app, or start the project's own.
+     *
+     * `core/devServer.ts`'s `resolveTarget` does this too, but it also arms
+     * `process.once("SIGINT"/"SIGTERM")` handlers that are never removed and that
+     * call `process.exit` themselves. That is right for a CLI about to exit, and
+     * wrong for a process that will serve an editor for hours: the sixth scan trips
+     * MaxListenersExceededWarning, and the first Ctrl-C kills the server before it
+     * can tear the dev server down. So the same three steps are run here, and the
+     * close hook is handed back instead of wired to a signal. */
+    private bootOrAttach;
+    private release;
+    /** Resolve a `{scanId, findingId}` pair to the finding, or to the message the
+     * model needs. A stale handle is an ordinary, recoverable answer. */
+    private resolve;
+    private repro;
+    private fix;
+    private healOptions;
+    private finishFix;
+    private reportFix;
+}