@vexyo/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1406 @@
+// src/types.ts
+var STABLE_SPEC_VERSION = "2025-11-25";
+
+// src/rule.ts
+var SkipRule = class extends Error {
+  constructor(reason) {
+    super(reason);
+    this.reason = reason;
+    this.name = "SkipRule";
+  }
+  reason;
+};
+function finding(rule, message, remediation, detail) {
+  return {
+    ruleId: rule.id,
+    severity: rule.severity,
+    message,
+    remediation,
+    specRef: rule.specRef,
+    detail
+  };
+}
+
+// src/rules/2025-11-25/init/server-info-name.ts
+var serverInfoName = {
+  id: "init/server-info-name",
+  specVersion: "2025-11-25",
+  category: "initialization",
+  severity: "error",
+  title: "Server advertises a non-empty serverInfo.name",
+  specRef: "Base Protocol \xA7Lifecycle / Initialization (serverInfo)",
+  async run(ctx) {
+    const name = ctx.serverInfo?.name;
+    if (typeof name !== "string" || name.length === 0) {
+      return [
+        finding(
+          this,
+          "Server did not return a non-empty `serverInfo.name` during initialization.",
+          "Return a non-empty `serverInfo.name` in the initialize response.",
+          { serverInfo: ctx.serverInfo }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/init/server-info-version.ts
+var serverInfoVersion = {
+  id: "init/server-info-version",
+  specVersion: "2025-11-25",
+  category: "initialization",
+  severity: "error",
+  title: "Server advertises a non-empty serverInfo.version",
+  specRef: "Base Protocol \xA7Lifecycle / Initialization (serverInfo)",
+  async run(ctx) {
+    const version = ctx.serverInfo?.version;
+    if (typeof version !== "string" || version.length === 0) {
+      return [
+        finding(
+          this,
+          "Server did not return a non-empty `serverInfo.version` during initialization.",
+          "Return a non-empty `serverInfo.version` in the initialize response.",
+          { serverInfo: ctx.serverInfo }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/support.ts
+import { z as z2 } from "zod";
+
+// src/mcp/errors.ts
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
+function cleanErrorMessage(err) {
+  let message = err instanceof Error ? err.message : String(err);
+  const prefix = /^MCP error -?\d+: /;
+  while (prefix.test(message)) {
+    message = message.replace(prefix, "");
+  }
+  return message;
+}
+function errorCode(err) {
+  return err instanceof McpError ? err.code : void 0;
+}
+
+// src/mcp/schemas.ts
+import { z } from "zod";
+var toolsListResult = z.object({ tools: z.array(z.record(z.string(), z.unknown())) });
+var resourcesListResult = z.object({
+  resources: z.array(z.record(z.string(), z.unknown()))
+});
+var promptsListResult = z.object({ prompts: z.array(z.record(z.string(), z.unknown())) });
+var anyResult = z.unknown();
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(record, key) {
+  const value = record[key];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/rules/2025-11-25/support.ts
+var callToolResult = z2.object({ isError: z2.boolean().optional() });
+function classifyError(err) {
+  return { threw: true, code: errorCode(err), message: cleanErrorMessage(err) };
+}
+async function requireToolList(ctx) {
+  try {
+    return (await ctx.client.request({ method: "tools/list", params: {} }, toolsListResult)).tools;
+  } catch {
+    throw new SkipRule("tools/list unavailable");
+  }
+}
+async function requireResourceList(ctx) {
+  try {
+    return (await ctx.client.request({ method: "resources/list", params: {} }, resourcesListResult)).resources;
+  } catch {
+    throw new SkipRule("resources/list unavailable");
+  }
+}
+async function requirePromptList(ctx) {
+  try {
+    return (await ctx.client.request({ method: "prompts/list", params: {} }, promptsListResult)).prompts;
+  } catch {
+    throw new SkipRule("prompts/list unavailable");
+  }
+}
+function toolWithRequiredParams(tools) {
+  for (const tool of tools) {
+    const name = stringField(tool, "name");
+    const schema = tool["inputSchema"];
+    if (name && isRecord(schema) && Array.isArray(schema["required"]) && schema["required"].length > 0) {
+      return name;
+    }
+  }
+  return void 0;
+}
+
+// src/rules/2025-11-25/discovery/tools-list.ts
+var toolsListAvailable = {
+  id: "discovery/tools-list-available",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "tools/list responds with a tool array",
+  specRef: "Server Features \xA7Tools / Listing Tools",
+  async run(ctx) {
+    if (!ctx.capabilities?.tools) {
+      throw new SkipRule("Server does not advertise the `tools` capability.");
+    }
+    try {
+      await ctx.client.request({ method: "tools/list", params: {} }, toolsListResult);
+      return [];
+    } catch (err) {
+      return [
+        finding(
+          this,
+          "`tools/list` failed despite the `tools` capability being advertised.",
+          "Implement `tools/list` to return `{ tools: Tool[] }`, or stop advertising the `tools` capability.",
+          { error: cleanErrorMessage(err) }
+        )
+      ];
+    }
+  }
+};
+
+// src/rules/2025-11-25/discovery/tools-have-names.ts
+var toolsHaveNames = {
+  id: "discovery/tools-have-names",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "Every tool has a non-empty name",
+  specRef: "Server Features \xA7Tools / Tool.name",
+  async run(ctx) {
+    if (!ctx.capabilities?.tools) {
+      throw new SkipRule("Server does not advertise the `tools` capability.");
+    }
+    const tools = await requireToolList(ctx);
+    const invalid = tools.filter((tool) => {
+      const name = stringField(tool, "name");
+      return name === void 0 || name.length === 0;
+    });
+    if (invalid.length > 0) {
+      return [
+        finding(
+          this,
+          `${invalid.length} tool(s) have a missing or empty name.`,
+          "Give every tool a non-empty string `name`.",
+          { tools }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/discovery/tools-have-input-schema.ts
+var toolsHaveInputSchema = {
+  id: "discovery/tools-have-input-schema",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "Every tool declares an object inputSchema",
+  specRef: "Server Features \xA7Tools / Tool.inputSchema",
+  async run(ctx) {
+    if (!ctx.capabilities?.tools) {
+      throw new SkipRule("Server does not advertise the `tools` capability.");
+    }
+    const tools = await requireToolList(ctx);
+    const invalid = tools.filter((tool) => {
+      const schema = tool["inputSchema"];
+      return !isRecord(schema) || schema["type"] !== "object";
+    });
+    if (invalid.length > 0) {
+      return [
+        finding(
+          this,
+          `${invalid.length} tool(s) are missing an object inputSchema (type: "object").`,
+          'Declare an `inputSchema` of `{ "type": "object", ... }` for every tool.',
+          { tools }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/discovery/tool-names-unique.ts
+var toolNamesUnique = {
+  id: "discovery/tool-names-unique",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "Tool names are unique",
+  specRef: "Server Features \xA7Tools / Tool.name",
+  async run(ctx) {
+    if (!ctx.capabilities?.tools) {
+      throw new SkipRule("Server does not advertise the `tools` capability.");
+    }
+    const tools = await requireToolList(ctx);
+    const names = tools.map((tool) => stringField(tool, "name")).filter((n) => !!n);
+    const duplicates = [...new Set(names.filter((name, i) => names.indexOf(name) !== i))];
+    if (duplicates.length > 0) {
+      return [
+        finding(
+          this,
+          `Duplicate tool name(s): ${duplicates.join(", ")}.`,
+          "Ensure every tool has a distinct `name`.",
+          { duplicates }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/discovery/resources-list.ts
+var resourcesListAvailable = {
+  id: "discovery/resources-list-available",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "resources/list responds with a resource array",
+  specRef: "Server Features \xA7Resources / Listing Resources",
+  async run(ctx) {
+    if (!ctx.capabilities?.resources) {
+      throw new SkipRule("Server does not advertise the `resources` capability.");
+    }
+    try {
+      await ctx.client.request({ method: "resources/list", params: {} }, resourcesListResult);
+      return [];
+    } catch (err) {
+      return [
+        finding(
+          this,
+          "`resources/list` failed despite the `resources` capability being advertised.",
+          "Implement `resources/list`, or stop advertising the `resources` capability.",
+          { error: cleanErrorMessage(err) }
+        )
+      ];
+    }
+  }
+};
+
+// src/rules/2025-11-25/discovery/resources-have-uri.ts
+var resourcesHaveUri = {
+  id: "discovery/resources-have-uri",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "Every resource has a non-empty uri",
+  specRef: "Server Features \xA7Resources / Resource.uri",
+  async run(ctx) {
+    if (!ctx.capabilities?.resources) {
+      throw new SkipRule("Server does not advertise the `resources` capability.");
+    }
+    const resources = await requireResourceList(ctx);
+    const invalid = resources.filter((resource) => {
+      const uri = stringField(resource, "uri");
+      return uri === void 0 || uri.length === 0;
+    });
+    if (invalid.length > 0) {
+      return [
+        finding(
+          this,
+          `${invalid.length} resource(s) have a missing or empty uri.`,
+          "Give every resource a non-empty `uri`.",
+          { resources }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/discovery/prompts-list.ts
+var promptsListAvailable = {
+  id: "discovery/prompts-list-available",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "prompts/list responds with a prompt array",
+  specRef: "Server Features \xA7Prompts / Listing Prompts",
+  async run(ctx) {
+    if (!ctx.capabilities?.prompts) {
+      throw new SkipRule("Server does not advertise the `prompts` capability.");
+    }
+    try {
+      await ctx.client.request({ method: "prompts/list", params: {} }, promptsListResult);
+      return [];
+    } catch (err) {
+      return [
+        finding(
+          this,
+          "`prompts/list` failed despite the `prompts` capability being advertised.",
+          "Implement `prompts/list`, or stop advertising the `prompts` capability.",
+          { error: cleanErrorMessage(err) }
+        )
+      ];
+    }
+  }
+};
+
+// src/rules/2025-11-25/discovery/prompts-have-names.ts
+var promptsHaveNames = {
+  id: "discovery/prompts-have-names",
+  specVersion: "2025-11-25",
+  category: "discovery",
+  severity: "error",
+  title: "Every prompt has a non-empty name",
+  specRef: "Server Features \xA7Prompts / Prompt.name",
+  async run(ctx) {
+    if (!ctx.capabilities?.prompts) {
+      throw new SkipRule("Server does not advertise the `prompts` capability.");
+    }
+    const prompts = await requirePromptList(ctx);
+    const invalid = prompts.filter((prompt) => {
+      const name = stringField(prompt, "name");
+      return name === void 0 || name.length === 0;
+    });
+    if (invalid.length > 0) {
+      return [
+        finding(
+          this,
+          `${invalid.length} prompt(s) have a missing or empty name.`,
+          "Give every prompt a non-empty string `name`.",
+          { prompts }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/errors/unknown-method.ts
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+var PROBE_UNSUPPORTED_METHOD = "vexyo/probe-unsupported-method";
+var unknownMethod = {
+  id: "errors/unknown-method",
+  specVersion: "2025-11-25",
+  category: "error-semantics",
+  severity: "error",
+  title: "Unknown methods return -32601 (Method not found)",
+  specRef: "Base Protocol \xA7JSON-RPC / Error codes",
+  async run(ctx) {
+    const probe = { method: PROBE_UNSUPPORTED_METHOD, params: {} };
+    try {
+      await ctx.client.request(probe, anyResult);
+      return [
+        finding(
+          this,
+          "An unknown method returned a result instead of an error.",
+          "Return JSON-RPC error -32601 (Method not found) for methods the server does not implement."
+        )
+      ];
+    } catch (err) {
+      const info = classifyError(err);
+      if (info.code === ErrorCode.MethodNotFound) {
+        return [];
+      }
+      return [
+        finding(
+          this,
+          `Unknown method returned error code ${info.code ?? "(none)"}, expected -32601 (Method not found).`,
+          "Return JSON-RPC error -32601 for methods the server does not implement.",
+          info
+        )
+      ];
+    }
+  }
+};
+
+// src/rules/2025-11-25/errors/unknown-tool.ts
+var NONEXISTENT_TOOL = "__vexyo_nonexistent_tool__";
+var unknownTool = {
+  id: "errors/unknown-tool",
+  specVersion: "2025-11-25",
+  category: "error-semantics",
+  severity: "error",
+  title: "Calling an unknown tool is signalled as an error",
+  specRef: "Server Features \xA7Tools / Calling Tools (error handling)",
+  async run(ctx) {
+    if (!ctx.capabilities?.tools) {
+      throw new SkipRule("Server does not advertise the `tools` capability.");
+    }
+    try {
+      const result = await ctx.client.request(
+        { method: "tools/call", params: { name: NONEXISTENT_TOOL, arguments: {} } },
+        callToolResult
+      );
+      if (result.isError === true) {
+        return [];
+      }
+      return [
+        finding(
+          this,
+          "Calling a nonexistent tool returned a successful result instead of an error.",
+          "Return a JSON-RPC error or a result with `isError: true` for unknown tool names.",
+          result
+        )
+      ];
+    } catch {
+      return [];
+    }
+  }
+};
+
+// src/rules/2025-11-25/errors/tool-invalid-params.ts
+var toolInvalidParams = {
+  id: "errors/tool-invalid-params",
+  specVersion: "2025-11-25",
+  category: "error-semantics",
+  severity: "error",
+  title: "Invalid tool arguments are rejected",
+  specRef: "Server Features \xA7Tools / Calling Tools (input validation)",
+  async run(ctx) {
+    if (!ctx.capabilities?.tools) {
+      throw new SkipRule("Server does not advertise the `tools` capability.");
+    }
+    const tools = await requireToolList(ctx);
+    const target = toolWithRequiredParams(tools);
+    if (target === void 0) {
+      throw new SkipRule("No tool declares required parameters to probe.");
+    }
+    try {
+      const result = await ctx.client.request(
+        { method: "tools/call", params: { name: target, arguments: {} } },
+        callToolResult
+      );
+      if (result.isError === true) {
+        return [];
+      }
+      return [
+        finding(
+          this,
+          `Tool "${target}" accepted a call with missing required arguments and returned success.`,
+          "Validate tool arguments and return an error (-32602 or `isError: true`) on invalid input.",
+          result
+        )
+      ];
+    } catch {
+      return [];
+    }
+  }
+};
+
+// src/rules/2025-11-25/errors/unknown-resource.ts
+var NONEXISTENT_URI = "vexyo://__vexyo_nonexistent_resource__";
+var unknownResource = {
+  id: "errors/unknown-resource",
+  specVersion: "2025-11-25",
+  category: "error-semantics",
+  severity: "error",
+  title: "Reading an unknown resource returns an error",
+  specRef: "Server Features \xA7Resources / Reading Resources (error handling)",
+  async run(ctx) {
+    if (!ctx.capabilities?.resources) {
+      throw new SkipRule("Server does not advertise the `resources` capability.");
+    }
+    try {
+      await ctx.client.request(
+        { method: "resources/read", params: { uri: NONEXISTENT_URI } },
+        anyResult
+      );
+      return [
+        finding(
+          this,
+          "Reading a nonexistent resource URI returned a successful result instead of an error.",
+          "Return a JSON-RPC error for resource URIs the server does not serve."
+        )
+      ];
+    } catch {
+      return [];
+    }
+  }
+};
+
+// src/rules/2025-11-25/errors/error-object-shape.ts
+var NONEXISTENT_URI2 = "vexyo://__vexyo_error_shape_probe__";
+var errorObjectShape = {
+  id: "errors/error-object-shape",
+  specVersion: "2025-11-25",
+  category: "error-semantics",
+  severity: "error",
+  title: "JSON-RPC error objects carry a numeric code and non-empty message",
+  specRef: "Base Protocol \xA7JSON-RPC / Error object",
+  async run(ctx) {
+    if (!ctx.capabilities?.resources) {
+      throw new SkipRule("Server does not advertise the `resources` capability.");
+    }
+    try {
+      await ctx.client.request(
+        { method: "resources/read", params: { uri: NONEXISTENT_URI2 } },
+        anyResult
+      );
+      throw new SkipRule("Server did not raise a JSON-RPC error for an unknown resource.");
+    } catch (err) {
+      if (err instanceof SkipRule) {
+        throw err;
+      }
+      const info = classifyError(err);
+      const problems = [];
+      if (typeof info.code !== "number") {
+        problems.push("missing numeric `code`");
+      }
+      if (info.message === void 0 || info.message.length === 0) {
+        problems.push("missing or empty `message`");
+      }
+      if (problems.length > 0) {
+        return [
+          finding(
+            this,
+            `JSON-RPC error object is malformed: ${problems.join(", ")}.`,
+            "Every JSON-RPC error must include a numeric `code` and a non-empty `message`.",
+            info
+          )
+        ];
+      }
+      return [];
+    }
+  }
+};
+
+// src/rules/2025-11-25/transport/http-session-id-valid.ts
+var VISIBLE_ASCII = /^[\x21-\x7e]+$/;
+var httpSessionIdValid = {
+  id: "transport/http-session-id-valid",
+  specVersion: "2025-11-25",
+  category: "transport",
+  severity: "error",
+  title: "HTTP session id contains only visible ASCII",
+  specRef: "Transports \xA7Streamable HTTP / Session management",
+  async run(ctx) {
+    if (ctx.transport.kind !== "http") {
+      throw new SkipRule("Not an HTTP connection.");
+    }
+    const sessionId = ctx.transport.sessionId;
+    if (sessionId === void 0) {
+      throw new SkipRule("Server operates statelessly (no Mcp-Session-Id issued).");
+    }
+    if (!VISIBLE_ASCII.test(sessionId)) {
+      return [
+        finding(
+          this,
+          "The issued Mcp-Session-Id contains characters outside visible ASCII (0x21\u20130x7E).",
+          "Generate session ids using only visible ASCII characters (e.g. a UUID).",
+          { sessionId }
+        )
+      ];
+    }
+    return [];
+  }
+};
+
+// src/rules/2025-11-25/index.ts
+var rules2025_11_25 = [
+  // initialization
+  serverInfoName,
+  serverInfoVersion,
+  // discovery
+  toolsListAvailable,
+  toolsHaveNames,
+  toolsHaveInputSchema,
+  toolNamesUnique,
+  resourcesListAvailable,
+  resourcesHaveUri,
+  promptsListAvailable,
+  promptsHaveNames,
+  // error-semantics
+  unknownMethod,
+  unknownTool,
+  toolInvalidParams,
+  unknownResource,
+  errorObjectShape,
+  // transport
+  httpSessionIdValid
+];
+
+// src/registry.ts
+var ALL_RULES = [...rules2025_11_25];
+function rulesForSpecVersion(version) {
+  return ALL_RULES.filter((rule) => rule.specVersion === version);
+}
+function allRules() {
+  return ALL_RULES;
+}
+
+// src/transports/http.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+// src/brand.ts
+var BRAND = {
+  /** Display name of the product. */
+  name: "vexyo",
+  /** CLI command / binary name. */
+  bin: "vexyo"
+};
+
+// src/transports/http.ts
+async function connectHttp(target) {
+  let url;
+  try {
+    url = new URL(target.url);
+  } catch (err) {
+    throw new Error(`Invalid HTTP target url: ${target.url}`, { cause: err });
+  }
+  const transport = new StreamableHTTPClientTransport(url, {
+    requestInit: target.headers ? { headers: target.headers } : void 0
+  });
+  const client = new Client(
+    { name: `${BRAND.name}-probe`, version: "0.0.0" },
+    { capabilities: {} }
+  );
+  try {
+    await client.connect(transport);
+  } catch (err) {
+    await transport.close().catch(() => void 0);
+    throw new Error(
+      `Failed to connect to an MCP server over Streamable HTTP (url: ${target.url}). Check that the server is running and the URL points at its MCP endpoint.`,
+      { cause: err }
+    );
+  }
+  return {
+    client,
+    transport: { kind: "http", sessionId: transport.sessionId },
+    close: async () => {
+      await client.close();
+    }
+  };
+}
+
+// src/transports/stdio.ts
+import { Client as Client2 } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+async function connectStdio(target) {
+  const transport = new StdioClientTransport({
+    command: target.command,
+    args: target.args,
+    cwd: target.cwd,
+    // When env is omitted the SDK supplies a safe default (PATH/HOME/etc.).
+    env: target.env,
+    stderr: "inherit"
+  });
+  const client = new Client2(
+    { name: `${BRAND.name}-probe`, version: "0.0.0" },
+    { capabilities: {} }
+  );
+  try {
+    await client.connect(transport);
+  } catch (err) {
+    await transport.close().catch(() => void 0);
+    throw new Error(
+      `Failed to connect to an MCP server over stdio (command: ${target.command}). Check that the command starts a stdio MCP server and exits cleanly on stdin close.`,
+      { cause: err }
+    );
+  }
+  return {
+    client,
+    transport: { kind: "stdio" },
+    close: async () => {
+      await client.close();
+    }
+  };
+}
+
+// src/transports/index.ts
+function connectTarget(target) {
+  return target.transport === "stdio" ? connectStdio(target.stdio) : connectHttp(target.http);
+}
+
+// src/runner.ts
+function describeTarget(target) {
+  if (target.transport === "http") {
+    return { transport: "http", description: `http: ${target.http.url}` };
+  }
+  const { command, args } = target.stdio;
+  return { transport: "stdio", description: `stdio: ${command} ${(args ?? []).join(" ")}`.trim() };
+}
+var SEVERITY_RANK = { info: 1, warning: 2, error: 3 };
+async function runSuite(opts) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const failOn = opts.failOn ?? "error";
+  const rules = rulesForSpecVersion(opts.specVersion);
+  const target = describeTarget(opts.target);
+  const conn = await connectTarget(opts.target);
+  let results;
+  try {
+    const ctx = {
+      client: conn.client,
+      serverInfo: conn.client.getServerVersion(),
+      capabilities: conn.client.getServerCapabilities(),
+      transport: conn.transport,
+      specVersion: opts.specVersion
+    };
+    results = await runRules(ctx, rules);
+    if (opts.extraChecks) {
+      results.push(...await opts.extraChecks(ctx));
+    }
+  } finally {
+    await conn.close().catch(() => void 0);
+  }
+  const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    specVersion: opts.specVersion,
+    target,
+    startedAt,
+    finishedAt,
+    results,
+    summary: summarizeResults(results),
+    exitCode: computeExitCode(results, failOn)
+  };
+}
+async function runRules(ctx, rules) {
+  const results = [];
+  for (const rule of rules) {
+    results.push(await runOneRule(rule, ctx));
+  }
+  return results;
+}
+async function runOneRule(rule, ctx) {
+  const start = Date.now();
+  const base = {
+    ruleId: rule.id,
+    title: rule.title,
+    category: rule.category,
+    severity: rule.severity,
+    specVersion: rule.specVersion,
+    specRef: rule.specRef
+  };
+  try {
+    const findings = await rule.run(ctx);
+    return {
+      ...base,
+      status: statusFromFindings(findings),
+      findings,
+      durationMs: Date.now() - start
+    };
+  } catch (err) {
+    if (err instanceof SkipRule) {
+      return {
+        ...base,
+        status: "skip",
+        skipReason: err.reason,
+        findings: [],
+        durationMs: Date.now() - start
+      };
+    }
+    return {
+      ...base,
+      status: "error",
+      findings: [
+        {
+          ruleId: rule.id,
+          severity: rule.severity,
+          message: `Rule threw an unexpected error: ${cleanErrorMessage(err)}`,
+          remediation: "This usually means the server crashed mid-run or the rule has a bug. Re-run and inspect the server logs.",
+          specRef: rule.specRef,
+          detail: err instanceof Error ? { stack: err.stack } : err
+        }
+      ],
+      durationMs: Date.now() - start
+    };
+  }
+}
+function statusFromFindings(findings) {
+  if (findings.length === 0) {
+    return "pass";
+  }
+  return findings.some((f) => f.severity === "error") ? "fail" : "warn";
+}
+function summarizeResults(results) {
+  const summary = {
+    pass: 0,
+    fail: 0,
+    warn: 0,
+    skip: 0,
+    error: 0,
+    total: results.length
+  };
+  for (const result of results) {
+    summary[result.status] += 1;
+  }
+  return summary;
+}
+function computeExitCode(results, failOn) {
+  const threshold = SEVERITY_RANK[failOn];
+  for (const result of results) {
+    if (result.status === "error") {
+      return 1;
+    }
+    for (const finding2 of result.findings) {
+      if (SEVERITY_RANK[finding2.severity] >= threshold) {
+        return 1;
+      }
+    }
+  }
+  return 0;
+}
+
+// src/golden/format.ts
+import { z as z3 } from "zod";
+var GOLDEN_FORMAT_VERSION = 1;
+var jsonRecord = z3.record(z3.string(), z3.unknown());
+var GoldenManifestSchema = z3.object({
+  formatVersion: z3.literal(GOLDEN_FORMAT_VERSION),
+  specVersion: z3.string(),
+  server: z3.object({ name: z3.string(), version: z3.string() }),
+  tools: z3.array(jsonRecord),
+  resources: z3.array(jsonRecord),
+  prompts: z3.array(jsonRecord)
+});
+var GoldenCaseSchema = z3.object({
+  case: z3.string(),
+  arguments: z3.record(z3.string(), z3.unknown()),
+  /** Names of the normalizers applied at record time (for human reference). */
+  normalizers: z3.array(z3.string()),
+  result: z3.unknown()
+});
+var GoldenRecordingSchema = z3.object({
+  formatVersion: z3.literal(GOLDEN_FORMAT_VERSION),
+  tool: z3.string(),
+  cases: z3.array(GoldenCaseSchema)
+});
+var FieldDiffSchema = z3.object({
+  path: z3.string(),
+  before: z3.unknown().optional(),
+  after: z3.unknown().optional()
+});
+var RegressionDetailSchema = z3.object({
+  kind: z3.enum(["schema", "behavioral", "coverage"]),
+  target: z3.object({
+    type: z3.enum(["tool", "resource", "prompt"]),
+    name: z3.string(),
+    case: z3.string().optional()
+  }),
+  change: z3.enum(["added", "removed", "changed"]),
+  before: z3.unknown().optional(),
+  after: z3.unknown().optional(),
+  fieldDiffs: z3.array(FieldDiffSchema).optional(),
+  /** Builtin normalizer names that would collapse a volatile-looking diff. */
+  suggestedNormalizers: z3.array(z3.string()).optional()
+});
+
+// src/golden/normalize.ts
+var STRING_PATTERNS = {
+  "iso-timestamp": {
+    regex: /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g,
+    placeholder: "<timestamp>"
+  },
+  uuid: {
+    regex: /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g,
+    placeholder: "<uuid>"
+  },
+  "hex-id": { regex: /\b[0-9a-fA-F]{16,}\b/g, placeholder: "<hex>" },
+  "abs-path": { regex: /(?:\/[\w.-]+){2,}\/?/g, placeholder: "<path>" }
+};
+var NUMBER_RANGES = {
+  "epoch-millis": { min: 1e12, max: 2e12 },
+  "epoch-seconds": { min: 1e9, max: 2e9 }
+};
+var BUILTIN_NORMALIZER_NAMES = [
+  ...Object.keys(STRING_PATTERNS),
+  ...Object.keys(NUMBER_RANGES)
+];
+function builtin(name) {
+  const stringPattern = STRING_PATTERNS[name];
+  if (stringPattern) {
+    return (value) => mapScalars(
+      value,
+      (scalar) => typeof scalar === "string" ? scalar.replace(stringPattern.regex, stringPattern.placeholder) : scalar
+    );
+  }
+  const range = NUMBER_RANGES[name];
+  if (range) {
+    return (value) => mapScalars(
+      value,
+      (scalar) => typeof scalar === "number" && Number.isInteger(scalar) && scalar >= range.min && scalar < range.max ? "<epoch>" : scalar
+    );
+  }
+  throw new Error(
+    `Unknown normalizer "${name}". Available builtins: ${BUILTIN_NORMALIZER_NAMES.join(", ")}.`
+  );
+}
+function mapScalars(value, fn) {
+  if (Array.isArray(value)) {
+    return value.map((item) => mapScalars(item, fn));
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value;
+    const out = {};
+    for (const key of Object.keys(record)) {
+      out[key] = mapScalars(record[key], fn);
+    }
+    return out;
+  }
+  return fn(value);
+}
+function resolve(ref) {
+  return typeof ref === "string" ? builtin(ref) : ref.apply;
+}
+function normalizerName(ref) {
+  return typeof ref === "string" ? ref : ref.name;
+}
+function applyNormalizers(value, refs) {
+  return refs.reduce((acc, ref) => resolve(ref)(acc), value);
+}
+function suggestNormalizer(before, after) {
+  const suggestions = [];
+  for (const [name, pattern] of Object.entries(STRING_PATTERNS)) {
+    if (typeof before === "string" && typeof after === "string" && matchesPattern(before, pattern.regex) && matchesPattern(after, pattern.regex)) {
+      suggestions.push(name);
+    }
+  }
+  for (const [name, range] of Object.entries(NUMBER_RANGES)) {
+    if (inRange(before, range) && inRange(after, range)) {
+      suggestions.push(name);
+    }
+  }
+  return suggestions;
+}
+function matchesPattern(value, regex) {
+  return new RegExp(regex.source).test(value);
+}
+function inRange(value, range) {
+  return typeof value === "number" && Number.isInteger(value) && value >= range.min && value < range.max;
+}
+
+// src/golden/record.ts
+async function recordGoldens(client, cfg) {
+  const manifest = await snapshotManifest(client, cfg.specVersion);
+  const recordings = [];
+  for (const tool of Object.keys(cfg.tools).sort()) {
+    const toolSpec = cfg.tools[tool];
+    if (!toolSpec) {
+      continue;
+    }
+    const refs = toolSpec.normalizers ?? cfg.defaultNormalizers;
+    const cases = [];
+    for (const spec of [...toolSpec.cases].sort((a, b) => compare(a.case, b.case))) {
+      const raw = await client.request(
+        { method: "tools/call", params: { name: tool, arguments: spec.arguments } },
+        anyResult
+      );
+      cases.push({
+        case: spec.case,
+        arguments: spec.arguments,
+        normalizers: refs.map(normalizerName),
+        result: applyNormalizers(raw, refs)
+      });
+    }
+    recordings.push({ formatVersion: GOLDEN_FORMAT_VERSION, tool, cases });
+  }
+  return { manifest, recordings };
+}
+async function snapshotManifest(client, specVersion) {
+  const caps = client.getServerCapabilities();
+  const info = client.getServerVersion();
+  const tools = caps?.tools ? (await client.request({ method: "tools/list", params: {} }, toolsListResult)).tools : [];
+  const resources = caps?.resources ? (await client.request({ method: "resources/list", params: {} }, resourcesListResult)).resources : [];
+  const prompts = caps?.prompts ? (await client.request({ method: "prompts/list", params: {} }, promptsListResult)).prompts : [];
+  return {
+    formatVersion: GOLDEN_FORMAT_VERSION,
+    specVersion,
+    server: { name: info?.name ?? "", version: info?.version ?? "" },
+    tools: sortBy(tools, "name"),
+    resources: sortBy(resources, "uri"),
+    prompts: sortBy(prompts, "name")
+  };
+}
+function sortBy(items, key) {
+  return [...items].sort((a, b) => compare(stringField(a, key) ?? "", stringField(b, key) ?? ""));
+}
+function compare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// src/golden/serialize.ts
+var PRINT_WIDTH = 100;
+var INDENT = "  ";
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item === void 0 ? null : item));
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const child = value[key];
+      if (child !== void 0 && typeof child !== "function") {
+        out[key] = canonicalize(child);
+      }
+    }
+    return out;
+  }
+  return typeof value === "function" ? null : value;
+}
+function flat(value) {
+  if (Array.isArray(value)) {
+    return value.length === 0 ? "[]" : `[${value.map(flat).join(", ")}]`;
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+      return "{}";
+    }
+    return `{ ${keys.map((k) => `${JSON.stringify(k)}: ${flat(value[k])}`).join(", ")} }`;
+  }
+  return JSON.stringify(value);
+}
+function print(value, level, column, trailer) {
+  if (!Array.isArray(value) && !isPlainObject(value)) {
+    return JSON.stringify(value);
+  }
+  const flatForm = flat(value);
+  const mustBreak = Array.isArray(value) && forcesBreak(value);
+  if (!mustBreak && column + flatForm.length + trailer <= PRINT_WIDTH) {
+    return flatForm;
+  }
+  const childIndent = INDENT.repeat(level + 1);
+  const closeIndent = INDENT.repeat(level);
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item === "number")) {
+      return fillNumbers(value, level);
+    }
+    const items = value.map(
+      (item, i) => print(item, level + 1, childIndent.length, i < value.length - 1 ? 1 : 0)
+    );
+    return `[
+${items.map((s) => childIndent + s).join(",\n")}
+${closeIndent}]`;
+  }
+  const keys = Object.keys(value);
+  const props = keys.map((key, i) => {
+    const prefix = `${JSON.stringify(key)}: `;
+    const rendered = print(
+      value[key],
+      level + 1,
+      childIndent.length + prefix.length,
+      i < keys.length - 1 ? 1 : 0
+    );
+    return `${childIndent}${prefix}${rendered}`;
+  });
+  return `{
+${props.join(",\n")}
+${closeIndent}}`;
+}
+function forcesBreak(value) {
+  return value.length > 1 && value.every(
+    (el) => Array.isArray(el) && el.length > 1 || isPlainObject(el) && Object.keys(el).length > 1
+  );
+}
+function fillNumbers(value, level) {
+  const childIndent = INDENT.repeat(level + 1);
+  const lines = [];
+  let current = "";
+  value.forEach((num, i) => {
+    const token = i < value.length - 1 ? `${JSON.stringify(num)},` : JSON.stringify(num);
+    if (current === "") {
+      current = token;
+    } else if (childIndent.length + current.length + 1 + token.length <= PRINT_WIDTH) {
+      current = `${current} ${token}`;
+    } else {
+      lines.push(current);
+      current = token;
+    }
+  });
+  if (current !== "") {
+    lines.push(current);
+  }
+  return `[
+${lines.map((l) => childIndent + l).join("\n")}
+${INDENT.repeat(level)}]`;
+}
+function stableStringify(value) {
+  return `${print(canonicalize(value), 0, 0, 0)}
+`;
+}
+function jsonEqual(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
+
+// src/golden/diff.ts
+function diffValue(before, after, path = "") {
+  if (jsonEqual(before, after)) {
+    return [];
+  }
+  if (isRecord(before) && isRecord(after)) {
+    const keys = [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+    return keys.flatMap((key) => diffValue(before[key], after[key], join(path, key)));
+  }
+  if (Array.isArray(before) && Array.isArray(after) && before.length === after.length) {
+    return before.flatMap((item, i) => diffValue(item, after[i], `${path}[${i}]`));
+  }
+  return [{ path: path || "(root)", before, after }];
+}
+function join(path, key) {
+  return path ? `${path}.${key}` : key;
+}
+
+// src/golden/regress.ts
+var SPEC_REF = "Regression / Golden set";
+async function runRegression(client, golden, cfg) {
+  const specVersion = cfg.specVersion;
+  const live = await snapshotLive(client);
+  const results = [];
+  results.push(...manifestDrift(specVersion, "tool", "name", golden.manifest.tools, live.tools));
+  results.push(
+    ...manifestDrift(specVersion, "resource", "uri", golden.manifest.resources, live.resources)
+  );
+  results.push(
+    ...manifestDrift(specVersion, "prompt", "name", golden.manifest.prompts, live.prompts)
+  );
+  const liveToolNames = new Set(
+    live.tools.map((t) => stringField(t, "name")).filter((n) => !!n)
+  );
+  for (const recording of golden.recordings) {
+    if (!liveToolNames.has(recording.tool)) {
+      continue;
+    }
+    const refs = cfg.tools[recording.tool]?.normalizers ?? cfg.defaultNormalizers;
+    for (const testCase of recording.cases) {
+      results.push(await behavioralDrift(client, specVersion, recording.tool, testCase, refs));
+    }
+  }
+  return results;
+}
+function manifestDrift(specVersion, type, keyField, goldenDefs, liveDefs) {
+  const results = [];
+  const liveByKey = /* @__PURE__ */ new Map();
+  for (const def of liveDefs) {
+    const key = stringField(def, keyField);
+    if (key !== void 0) {
+      liveByKey.set(key, def);
+    }
+  }
+  const goldenKeys = /* @__PURE__ */ new Set();
+  for (const def of goldenDefs) {
+    const key = stringField(def, keyField);
+    if (key === void 0) {
+      continue;
+    }
+    goldenKeys.add(key);
+    const liveDef = liveByKey.get(key);
+    if (!liveDef) {
+      results.push(
+        drift(specVersion, "coverage", "error", {
+          detail: { kind: "coverage", target: { type, name: key }, change: "removed", before: def },
+          message: `${type} "${key}" has a golden but no longer exists on the server.`,
+          remediation: "Restore the target, or remove its golden if the removal is intended, then re-record."
+        })
+      );
+    } else if (!jsonEqual(def, liveDef)) {
+      results.push(
+        drift(specVersion, "schema", "error", {
+          detail: {
+            kind: "schema",
+            target: { type, name: key },
+            change: "changed",
+            before: def,
+            after: liveDef,
+            fieldDiffs: diffValue(def, liveDef)
+          },
+          message: `${type} "${key}" definition changed since the golden was recorded.`,
+          remediation: "Review the change; if intended, re-record with `vexyo record`."
+        })
+      );
+    }
+  }
+  for (const def of liveDefs) {
+    const key = stringField(def, keyField);
+    if (key === void 0 || goldenKeys.has(key)) {
+      continue;
+    }
+    results.push(
+      drift(specVersion, "coverage", "warning", {
+        detail: { kind: "coverage", target: { type, name: key }, change: "added", after: def },
+        message: `${type} "${key}" exists on the server but has no golden.`,
+        remediation: "Run `vexyo record` to capture it into the golden set."
+      })
+    );
+  }
+  return results;
+}
+async function behavioralDrift(client, specVersion, tool, testCase, refs) {
+  let liveNormalized;
+  try {
+    const raw = await client.request(
+      { method: "tools/call", params: { name: tool, arguments: testCase.arguments } },
+      anyResult
+    );
+    liveNormalized = applyNormalizers(raw, refs);
+  } catch (err) {
+    liveNormalized = { error: err instanceof Error ? err.message : String(err) };
+  }
+  const fieldDiffs = diffValue(testCase.result, liveNormalized);
+  if (fieldDiffs.length === 0) {
+    return passResult(specVersion, tool, testCase.case);
+  }
+  const suggested = [...new Set(fieldDiffs.flatMap((d) => suggestNormalizer(d.before, d.after)))];
+  const remediation = suggested.length > 0 ? `Field(s) look volatile (${suggested.join(", ")}); add the normalizer(s) for "${tool}", or re-record if the change is real.` : "If the change is intended, re-record with `vexyo record`.";
+  return drift(specVersion, "behavioral", "error", {
+    detail: {
+      kind: "behavioral",
+      target: { type: "tool", name: tool, case: testCase.case },
+      change: "changed",
+      before: testCase.result,
+      after: liveNormalized,
+      fieldDiffs,
+      suggestedNormalizers: suggested.length > 0 ? suggested : void 0
+    },
+    message: `Tool "${tool}" (case "${testCase.case}") output differs from its golden.`,
+    remediation
+  });
+}
+function drift(specVersion, kind, severity, spec) {
+  const { target } = spec.detail;
+  const suffix = target.case ? `${target.name}:${target.case}` : target.name;
+  const ruleId = `regression/${kind}-drift:${target.type}:${suffix}`;
+  const finding2 = {
+    ruleId,
+    severity,
+    message: spec.message,
+    remediation: spec.remediation,
+    specRef: SPEC_REF,
+    detail: spec.detail
+  };
+  return {
+    ruleId,
+    title: `${kind} drift \u2014 ${target.type} ${target.name}`,
+    category: "regression",
+    severity,
+    specVersion,
+    specRef: SPEC_REF,
+    status: severity === "error" ? "fail" : "warn",
+    findings: [finding2],
+    durationMs: 0
+  };
+}
+function passResult(specVersion, tool, testCase) {
+  return {
+    ruleId: `regression/behavioral:${tool}:${testCase}`,
+    title: `behavioral \u2014 tool ${tool} (case ${testCase})`,
+    category: "regression",
+    severity: "info",
+    specVersion,
+    specRef: SPEC_REF,
+    status: "pass",
+    findings: [],
+    durationMs: 0
+  };
+}
+async function snapshotLive(client) {
+  const caps = client.getServerCapabilities();
+  const tools = caps?.tools ? (await client.request({ method: "tools/list", params: {} }, toolsListResult)).tools : [];
+  const resources = caps?.resources ? (await client.request({ method: "resources/list", params: {} }, resourcesListResult)).resources : [];
+  const prompts = caps?.prompts ? (await client.request({ method: "prompts/list", params: {} }, promptsListResult)).prompts : [];
+  return { tools, resources, prompts };
+}
+
+// src/golden/io.ts
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { join as join2 } from "path";
+import "zod";
+var GoldenError = class extends Error {
+  constructor(message, cause) {
+    super(message, cause !== void 0 ? { cause } : void 0);
+    this.name = "GoldenError";
+  }
+};
+async function writeGoldenSet(dir, set) {
+  await mkdir(join2(dir, "recordings"), { recursive: true });
+  const written = [];
+  const manifestPath = join2(dir, "manifest.json");
+  await writeFile(manifestPath, stableStringify(set.manifest));
+  written.push(manifestPath);
+  for (const recording of [...set.recordings].sort((a, b) => a.tool < b.tool ? -1 : 1)) {
+    const path = join2(dir, "recordings", `${recording.tool}.json`);
+    await writeFile(path, stableStringify(recording));
+    written.push(path);
+  }
+  return written;
+}
+async function readGoldenSet(dir) {
+  const manifestPath = join2(dir, "manifest.json");
+  let manifestRaw;
+  try {
+    manifestRaw = await readFile(manifestPath, "utf8");
+  } catch (err) {
+    throw new GoldenError(
+      `No golden manifest at ${manifestPath}. Run \`vexyo record\` to create one.`,
+      err
+    );
+  }
+  const manifest = parseGolden(GoldenManifestSchema, manifestRaw, manifestPath);
+  const recordings = [];
+  const recordingsDir = join2(dir, "recordings");
+  let files = [];
+  try {
+    files = (await readdir(recordingsDir)).filter((f) => f.endsWith(".json")).sort();
+  } catch {
+    files = [];
+  }
+  for (const file of files) {
+    const path = join2(recordingsDir, file);
+    recordings.push(parseGolden(GoldenRecordingSchema, await readFile(path, "utf8"), path));
+  }
+  return { manifest, recordings };
+}
+function parseGolden(schema, raw, path) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    throw new GoldenError(`Golden at ${path} is not valid JSON.`, err);
+  }
+  const parsed = schema.safeParse(json);
+  if (parsed.success) {
+    return parsed.data;
+  }
+  const version = isRecord(json) ? json["formatVersion"] : void 0;
+  if (version !== void 0 && version !== GOLDEN_FORMAT_VERSION) {
+    throw new GoldenError(
+      `Golden at ${path} has formatVersion ${String(version)}, but this build expects ${GOLDEN_FORMAT_VERSION}. Re-run \`vexyo record\` or upgrade vexyo.`
+    );
+  }
+  const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+  throw new GoldenError(`Golden at ${path} is malformed:
+${issues}`);
+}
+export {
+  BRAND,
+  BUILTIN_NORMALIZER_NAMES,
+  GOLDEN_FORMAT_VERSION,
+  GoldenError,
+  GoldenManifestSchema,
+  GoldenRecordingSchema,
+  RegressionDetailSchema,
+  STABLE_SPEC_VERSION,
+  SkipRule,
+  allRules,
+  applyNormalizers,
+  computeExitCode,
+  connectHttp,
+  connectStdio,
+  connectTarget,
+  finding,
+  normalizerName,
+  readGoldenSet,
+  recordGoldens,
+  rulesForSpecVersion,
+  runRegression,
+  runRules,
+  runSuite,
+  stableStringify,
+  suggestNormalizer,
+  summarizeResults,
+  writeGoldenSet
+};
+//# sourceMappingURL=index.js.map