@nwire/mcp 0.9.1 → 0.10.0

package/src/__tests__/mcp-io.test.ts

@@ -1,182 +0,0 @@
-/**
- * MCP I/O tests — drive `serveMcp` over real PassThrough streams the
- * same way Claude / Cursor will over stdio. We submit newline-framed
- * JSON-RPC requests on the input stream and parse responses off the
- * output stream. The kernel underneath is the real CommandRouter — no
- * mocks. If this passes, an AI client can actually drive nwire.
- */
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { PassThrough } from "node:stream";
-import { createKernel, type Kernel } from "@nwire/kernel";
-import { serveMcp } from "../index";
-
-interface PendingResponse {
-  resolve: (value: any) => void;
-}
-
-class StdioHarness {
-  readonly stdin = new PassThrough();
-  readonly stdout = new PassThrough();
-  private buffer = "";
-  private pending = new Map<string | number, PendingResponse>();
-  readonly notifications: Array<{ method: string; params?: any }> = [];
-  readonly served: Promise<void>;
-  private id = 0;
-
-  constructor(kernel: Kernel) {
-    this.served = serveMcp({
-      kernel,
-      stdin: this.stdin,
-      stdout: this.stdout,
-      serverName: "nwire-test",
-      serverVersion: "0.0.0-test",
-    });
-    this.stdout.setEncoding("utf8");
-    this.stdout.on("data", (chunk: string) => {
-      this.buffer += chunk;
-      const lines = this.buffer.split("\n");
-      this.buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        if (!line.trim()) continue;
-        const msg = JSON.parse(line) as { id?: string | number; method?: string };
-        if (msg.id != null && this.pending.has(msg.id)) {
-          this.pending.get(msg.id)!.resolve(msg);
-          this.pending.delete(msg.id);
-        } else if (msg.method) {
-          this.notifications.push(msg as any);
-        }
-      }
-    });
-  }
-
-  request(method: string, params?: Record<string, unknown>): Promise<any> {
-    const id = ++this.id;
-    const promise = new Promise<any>((resolve) => {
-      this.pending.set(id, { resolve });
-    });
-    this.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
-    return promise;
-  }
-
-  async close(): Promise<void> {
-    this.stdin.end();
-    await this.served;
-  }
-}
-
-describe("@nwire/mcp — JSON-RPC over stdio", () => {
-  let kernel: Kernel;
-  let harness: StdioHarness;
-
-  beforeEach(() => {
-    kernel = createKernel();
-  });
-
-  afterEach(async () => {
-    if (harness) await harness.close();
-  });
-
-  it("handshakes via initialize", async () => {
-    harness = new StdioHarness(kernel);
-    const res = await harness.request("initialize", {});
-    expect(res.result.protocolVersion).toBe("2024-11-05");
-    expect(res.result.serverInfo).toEqual({ name: "nwire-test", version: "0.0.0-test" });
-    expect(res.result.capabilities.tools).toBeDefined();
-  });
-
-  it("tools/list returns every registered command", async () => {
-    kernel.router.register("greet", async () => "hi");
-    kernel.router.register("double", async (_ctx, a: { n: number }) => a.n * 2);
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/list", {});
-    const tools = res.result.tools as Array<{
-      name: string;
-      description: string;
-      inputSchema: { type: string };
-    }>;
-    const names = tools.map((t) => t.name);
-    // Kernel commands come first; inspect tools are appended after.
-    expect(names).toContain("double");
-    expect(names).toContain("greet");
-    const kernelTools = tools.filter((t) => t.name === "double" || t.name === "greet");
-    for (const tool of kernelTools) {
-      expect(tool.description).toContain(tool.name);
-      expect(tool.inputSchema.type).toBe("object");
-    }
-  });
-
-  it("tools/call invokes a command and returns the wrapped result", async () => {
-    kernel.router.register("double", async (_ctx, a: { n: number }) => ({ doubled: a.n * 2 }));
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "double",
-      arguments: { n: 21 },
-    });
-    expect(res.result.isError).toBe(false);
-    expect(res.result.content).toHaveLength(1);
-    expect(res.result.content[0].type).toBe("text");
-    expect(JSON.parse(res.result.content[0].text)).toEqual({ doubled: 42 });
-  });
-
-  it("tools/call streams command.log lines as progress notifications", async () => {
-    kernel.router.register("noisy", async (ctx) => {
-      ctx.log("step 1");
-      ctx.log("step 2", "stderr");
-      return "done";
-    });
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", { name: "noisy", arguments: {} });
-    expect(res.result.isError).toBe(false);
-
-    const progress = harness.notifications.filter((n) => n.method === "notifications/progress");
-    expect(progress.length).toBeGreaterThanOrEqual(2);
-    expect(progress.map((n) => n.params.message)).toContain("step 1");
-    expect(progress.map((n) => n.params.message)).toContain("step 2");
-    const stderrFrame = progress.find((n) => n.params.stream === "stderr");
-    expect(stderrFrame?.params.message).toBe("step 2");
-  });
-
-  it("tools/call surfaces handler throws as isError content (not JSON-RPC error)", async () => {
-    kernel.router.register("explode", async () => {
-      throw new Error("boom");
-    });
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", { name: "explode", arguments: {} });
-    expect(res.error).toBeUndefined();
-    expect(res.result.isError).toBe(true);
-    expect(res.result.content[0].text).toBe("boom");
-  });
-
-  it("unknown tool returns -32602 invalid params", async () => {
-    harness = new StdioHarness(kernel);
-    const res = await harness.request("tools/call", { name: "nope", arguments: {} });
-    expect(res.error?.code).toBe(-32602);
-    expect(res.error?.message).toMatch(/unknown tool/);
-  });
-
-  it("unknown method returns -32601 method not found", async () => {
-    harness = new StdioHarness(kernel);
-    const res = await harness.request("resources/list", {});
-    expect(res.error?.code).toBe(-32601);
-  });
-
-  it("malformed JSON line returns -32700 with null id", async () => {
-    harness = new StdioHarness(kernel);
-    const buf: any[] = [];
-    harness.stdout.on("data", (chunk: string) => {
-      for (const line of chunk.split("\n")) {
-        if (line.trim()) buf.push(JSON.parse(line));
-      }
-    });
-    harness.stdin.write("this is not json\n");
-    // Give the parser a tick to emit.
-    await new Promise((r) => setTimeout(r, 30));
-    const parseError = buf.find((m) => m.error?.code === -32700);
-    expect(parseError).toBeDefined();
-    expect(parseError.id).toBeNull();
-  });
-});

package/src/__tests__/mcp.test.ts

@@ -1,48 +0,0 @@
-/**
- * MCP server smoke tests — exercise the dispatch logic without going
- * through stdio. We import the internal handle/callTool surface by
- * proxying through a fake JSON-RPC client: write a request to the
- * server's input, capture stdout.
- *
- * For the MVP we test the dispatch shape via the CommandRouter directly
- * — the JSON-RPC framing is straightforward enough that a full stdio
- * dance isn't worth the harness complexity right now.
- */
-
-import { describe, it, expect } from "vitest";
-import { createKernel } from "@nwire/kernel";
-
-describe("@nwire/mcp", () => {
-  it("kernel.router exposes registered commands by name", async () => {
-    const k = createKernel();
-    k.router.register("greet", async () => ({ hello: "world" }));
-    expect(k.router.list()).toEqual(["greet"]);
-    expect(k.router.has("greet")).toBe(true);
-  });
-
-  it("kernel.run dispatches and returns the handler's result", async () => {
-    const k = createKernel();
-    k.router.register("double", async (_ctx, args: { n: number }) => args.n * 2);
-    const handle = k.run<{ n: number }, number>("double", { n: 21 });
-    await expect(handle.promise).resolves.toBe(42);
-  });
-
-  it("command.log events stream through the handle's `on` subscription", async () => {
-    const k = createKernel();
-    k.router.register("noisy", async (ctx) => {
-      ctx.log("line 1");
-      ctx.log("line 2", "stderr");
-      return "done";
-    });
-    const handle = k.run("noisy", {});
-    const logs: Array<{ stream: string; line: string }> = [];
-    handle.on((e) => {
-      if (e.kind === "command.log") logs.push({ stream: e.stream, line: e.line });
-    });
-    await handle.promise;
-    expect(logs).toEqual([
-      { stream: "stdout", line: "line 1" },
-      { stream: "stderr", line: "line 2" },
-    ]);
-  });
-});

package/src/__tests__/write-tools.test.ts

@@ -1,354 +0,0 @@
-/**
- * Write-tools tests — mutating counterpart to `inspect-tools.test.ts`.
- *
- * Pattern: stand up a stub HTTP server, point discovery at it via
- * `NWIRE_INSPECT_URL`, drive the tools through the same stdio harness.
- * Each tool gets a happy path (or, for tools whose endpoint isn't yet
- * mounted, a gap-flag assertion) and a "no wire running" graceful
- * failure.
- */
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { PassThrough } from "node:stream";
-import { createServer, type Server, type IncomingMessage } from "node:http";
-import { AddressInfo } from "node:net";
-import { createKernel, type Kernel } from "@nwire/kernel";
-import { serveMcp } from "../index";
-import { resetInspectDiscoveryCache } from "../inspect";
-
-interface PendingResponse {
-  resolve: (value: any) => void;
-}
-
-class StdioHarness {
-  readonly stdin = new PassThrough();
-  readonly stdout = new PassThrough();
-  private buffer = "";
-  private pending = new Map<string | number, PendingResponse>();
-  readonly notifications: Array<{ method: string; params?: any }> = [];
-  readonly served: Promise<void>;
-  private id = 0;
-
-  constructor(kernel: Kernel) {
-    this.served = serveMcp({
-      kernel,
-      stdin: this.stdin,
-      stdout: this.stdout,
-      serverName: "nwire-test",
-      serverVersion: "0.0.0-test",
-    });
-    this.stdout.setEncoding("utf8");
-    this.stdout.on("data", (chunk: string) => {
-      this.buffer += chunk;
-      const lines = this.buffer.split("\n");
-      this.buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        if (!line.trim()) continue;
-        const msg = JSON.parse(line) as { id?: string | number; method?: string };
-        if (msg.id != null && this.pending.has(msg.id)) {
-          this.pending.get(msg.id)!.resolve(msg);
-          this.pending.delete(msg.id);
-        } else if (msg.method) {
-          this.notifications.push(msg as any);
-        }
-      }
-    });
-  }
-
-  request(method: string, params?: Record<string, unknown>): Promise<any> {
-    const id = ++this.id;
-    const promise = new Promise<any>((resolve) => {
-      this.pending.set(id, { resolve });
-    });
-    this.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
-    return promise;
-  }
-
-  async close(): Promise<void> {
-    this.stdin.end();
-    await this.served;
-  }
-}
-
-interface CapturedRequest {
-  readonly method: string;
-  readonly url: string;
-  readonly body: unknown;
-}
-
-interface StubWire {
-  readonly url: string;
-  readonly server: Server;
-  readonly requests: CapturedRequest[];
-  /** Override per-path responses. Default → 404 so gap-flag tests fire. */
-  routes: Map<string, (body: unknown) => { status: number; body: unknown }>;
-}
-
-async function readBody(req: IncomingMessage): Promise<unknown> {
-  return new Promise((resolveBody) => {
-    let raw = "";
-    req.setEncoding("utf8");
-    req.on("data", (c: string) => {
-      raw += c;
-    });
-    req.on("end", () => {
-      if (raw.length === 0) return resolveBody(undefined);
-      try {
-        resolveBody(JSON.parse(raw));
-      } catch {
-        resolveBody(raw);
-      }
-    });
-  });
-}
-
-async function startStubWire(): Promise<StubWire> {
-  const stub: StubWire = {
-    url: "",
-    server: null as unknown as Server,
-    requests: [],
-    routes: new Map(),
-  };
-  const server = createServer(async (req, res) => {
-    const url = req.url ?? "";
-    const method = req.method ?? "?";
-    const body = method === "POST" ? await readBody(req) : undefined;
-    stub.requests.push({ method, url, body });
-
-    // The discovery probe hits GET /_nwire/events/recent — always 200 [].
-    if (method === "GET" && url.startsWith("/_nwire/events/recent")) {
-      res.statusCode = 200;
-      res.setHeader("Content-Type", "application/json");
-      res.end("[]");
-      return;
-    }
-
-    const handler = stub.routes.get(`${method} ${url.split("?")[0]}`);
-    if (handler) {
-      const { status, body: out } = handler(body);
-      res.statusCode = status;
-      res.setHeader("Content-Type", "application/json");
-      res.end(JSON.stringify(out));
-      return;
-    }
-    res.statusCode = 404;
-    res.setHeader("Content-Type", "application/json");
-    res.end(JSON.stringify({ error: "not found" }));
-  });
-  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
-  const port = (server.address() as AddressInfo).port;
-  stub.server = server;
-  (stub as { url: string }).url = `http://127.0.0.1:${port}`;
-  return stub;
-}
-
-async function stopStubWire(stub: StubWire): Promise<void> {
-  await new Promise<void>((r) => stub.server.close(() => r()));
-}
-
-function parseToolResult(res: any): unknown {
-  expect(res.result.content).toHaveLength(1);
-  expect(res.result.content[0].type).toBe("text");
-  return JSON.parse(res.result.content[0].text);
-}
-
-describe("@nwire/mcp — write tools", () => {
-  let kernel: Kernel;
-  let harness: StdioHarness;
-  let stub: StubWire | undefined;
-  let prevInspectUrl: string | undefined;
-  let prevProbePorts: string | undefined;
-
-  beforeEach(() => {
-    kernel = createKernel();
-    prevInspectUrl = process.env.NWIRE_INSPECT_URL;
-    prevProbePorts = process.env.NWIRE_PROBE_PORTS;
-    resetInspectDiscoveryCache();
-  });
-
-  afterEach(async () => {
-    if (harness) await harness.close();
-    if (stub) await stopStubWire(stub);
-    stub = undefined;
-    if (prevInspectUrl === undefined) delete process.env.NWIRE_INSPECT_URL;
-    else process.env.NWIRE_INSPECT_URL = prevInspectUrl;
-    if (prevProbePorts === undefined) delete process.env.NWIRE_PROBE_PORTS;
-    else process.env.NWIRE_PROBE_PORTS = prevProbePorts;
-    resetInspectDiscoveryCache();
-  });
-
-  it("tools/list includes the three write tools", async () => {
-    harness = new StdioHarness(kernel);
-    const res = await harness.request("tools/list", {});
-    const names = (res.result.tools as Array<{ name: string }>).map((t) => t.name);
-    expect(names).toContain("dispatch_action");
-    expect(names).toContain("run_command");
-    expect(names).toContain("replay_trace");
-  });
-
-  // ─── dispatch_action ─────────────────────────────────────────────
-
-  it("dispatch_action POSTs to /_nwire/dispatch and returns the wire body", async () => {
-    stub = await startStubWire();
-    stub.routes.set("POST /_nwire/dispatch", (body) => {
-      expect(body).toEqual({
-        action: "submissions.submit",
-        input: { studentId: "alice", answer: "42" },
-        userId: "u-1",
-      });
-      return {
-        status: 200,
-        body: {
-          ok: true,
-          result: { events: [{ name: "Submitted" }] },
-          envelope: { messageId: "m-1", correlationId: "c-1" },
-        },
-      };
-    });
-    process.env.NWIRE_INSPECT_URL = stub.url;
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "dispatch_action",
-      arguments: {
-        action: "submissions.submit",
-        input: { studentId: "alice", answer: "42" },
-        user: { id: "u-1", roles: ["student"] },
-      },
-    });
-    expect(res.result.isError).toBe(false);
-    const parsed = parseToolResult(res) as { ok: boolean; envelope: { correlationId: string } };
-    expect(parsed.ok).toBe(true);
-    expect(parsed.envelope.correlationId).toBe("c-1");
-    const hit = stub.requests.find((r) => r.url === "/_nwire/dispatch");
-    expect(hit?.method).toBe("POST");
-  });
-
-  it("dispatch_action gracefully fails when no wire is running", async () => {
-    delete process.env.NWIRE_INSPECT_URL;
-    process.env.NWIRE_PROBE_PORTS = "1";
-    resetInspectDiscoveryCache();
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "dispatch_action",
-      arguments: { action: "x", input: {} },
-    });
-    expect(res.result.isError).toBe(true);
-    expect(res.result.content[0].text).toMatch(/no running wire/);
-  });
-
-  // ─── run_command ─────────────────────────────────────────────────
-
-  it("run_command gap-flags when the wire returns 404 (endpoint not mounted)", async () => {
-    stub = await startStubWire();
-    // No route registered for POST /_nwire/command → stub returns 404.
-    process.env.NWIRE_INSPECT_URL = stub.url;
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "run_command",
-      arguments: { name: "dev", args: {} },
-    });
-    expect(res.result.isError).toBe(true);
-    expect(res.result.content[0].text).toMatch(
-      /endpoint not implemented yet on wire side: POST \/_nwire\/command/,
-    );
-    // Sanity: the tool DID POST against the wire (so the gap is detected
-    // by the wire's 404 rather than synthesized client-side).
-    const hit = stub.requests.find((r) => r.url === "/_nwire/command");
-    expect(hit?.method).toBe("POST");
-  });
-
-  it("run_command happy path returns the wire body if the endpoint is mounted", async () => {
-    // Belt-and-braces: if/when /_nwire/command lands on the wire, the
-    // existing tool already speaks the right contract.
-    stub = await startStubWire();
-    stub.routes.set("POST /_nwire/command", (body) => {
-      expect(body).toEqual({ name: "dev", args: { wire: "main" } });
-      return { status: 200, body: { ok: true, exitCode: 0, stdout: "started\n" } };
-    });
-    process.env.NWIRE_INSPECT_URL = stub.url;
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "run_command",
-      arguments: { name: "dev", args: { wire: "main" } },
-    });
-    expect(res.result.isError).toBe(false);
-    const parsed = parseToolResult(res) as { ok: boolean; exitCode: number };
-    expect(parsed.ok).toBe(true);
-    expect(parsed.exitCode).toBe(0);
-  });
-
-  it("run_command gracefully fails when no wire is running", async () => {
-    delete process.env.NWIRE_INSPECT_URL;
-    process.env.NWIRE_PROBE_PORTS = "1";
-    resetInspectDiscoveryCache();
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "run_command",
-      arguments: { name: "dev", args: {} },
-    });
-    expect(res.result.isError).toBe(true);
-    expect(res.result.content[0].text).toMatch(/no running wire/);
-  });
-
-  // ─── replay_trace ────────────────────────────────────────────────
-
-  it("replay_trace gap-flags when the wire returns 404 (endpoint not mounted)", async () => {
-    stub = await startStubWire();
-    process.env.NWIRE_INSPECT_URL = stub.url;
-    harness = new StdioHarness(kernel);
-
-    const recording = {
-      ctxIn: {},
-      outcome: "ok",
-      steps: [{ stepKind: "branch", stepName: "guard", phase: "enter" }],
-    };
-    const res = await harness.request("tools/call", {
-      name: "replay_trace",
-      arguments: { recording },
-    });
-    expect(res.result.isError).toBe(true);
-    expect(res.result.content[0].text).toMatch(
-      /endpoint not implemented yet on wire side: POST \/_nwire\/replay/,
-    );
-    const hit = stub.requests.find((r) => r.url === "/_nwire/replay");
-    expect(hit?.method).toBe("POST");
-    expect((hit?.body as { recording: unknown }).recording).toEqual(recording);
-  });
-
-  it("replay_trace happy path returns drift report if the endpoint is mounted", async () => {
-    stub = await startStubWire();
-    stub.routes.set("POST /_nwire/replay", () => ({
-      status: 200,
-      body: { ok: true, drift: [], stepsCompared: 1 },
-    }));
-    process.env.NWIRE_INSPECT_URL = stub.url;
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "replay_trace",
-      arguments: { recording: { ctxIn: {}, outcome: "ok", steps: [] } },
-    });
-    expect(res.result.isError).toBe(false);
-    const parsed = parseToolResult(res) as { ok: boolean; drift: unknown[] };
-    expect(parsed.ok).toBe(true);
-    expect(parsed.drift).toEqual([]);
-  });
-
-  it("replay_trace gracefully fails when no wire is running", async () => {
-    delete process.env.NWIRE_INSPECT_URL;
-    process.env.NWIRE_PROBE_PORTS = "1";
-    resetInspectDiscoveryCache();
-    harness = new StdioHarness(kernel);
-
-    const res = await harness.request("tools/call", {
-      name: "replay_trace",
-      arguments: { recording: { ctxIn: {}, outcome: "ok", steps: [] } },
-    });
-    expect(res.result.isError).toBe(true);
-    expect(res.result.content[0].text).toMatch(/no running wire/);
-  });
-});