@nwire/mcp 0.9.1 → 0.10.0

package/src/write-tools.ts

@@ -1,237 +0,0 @@
-/**
- * Write tools — the mutating counterpart to `inspect.ts`.
- *
- * Where the inspect tools proxy `GET /_nwire/*` (or fall back to the
- * `.nwire/` disk cache), write tools drive the running wire through its
- * mutating endpoints:
- *
- *   POST /_nwire/dispatch  — invoke a registered action  ← `dispatch_action`
- *   POST /_nwire/command   — invoke a defineCommand      ← NOT YET MOUNTED
- *   POST /_nwire/replay    — replay a hook recording     ← NOT YET MOUNTED
- *
- * The wire ships only `/_nwire/dispatch` today (see
- * `packages/nwire-http/src/inspect.ts`). For tools whose endpoint does
- * not yet exist, we ship the tool ANYWAY so the contract is visible in
- * `tools/list`, but the call returns `isError: true` with an explicit
- * "endpoint not implemented on wire side" message rather than
- * synthesizing a fake response. The companion follow-up in
- * `@nwire/http` will mount the missing routes.
- *
- * These tools register alongside `inspectTools` and reuse the same URL
- * discovery cache (`discoverInspectUrl`). They do NOT modify the
- * existing read-only surface.
- */
-
-import { request as httpRequest } from "node:http";
-import { discoverInspectUrl, type InspectToolDef } from "./inspect.js";
-
-// ─── HTTP helpers ──────────────────────────────────────────────────
-
-interface HttpResult {
-  readonly status: number;
-  readonly body: unknown;
-}
-
-/**
- * POST JSON to a URL. Resolves with `{ status, body }` even for 4xx/5xx
- * — the caller decides what to do with non-2xx responses, because the
- * wire returns useful diagnostics in the body (e.g. action-not-found).
- */
-async function httpPostJson(url: string, payload: unknown): Promise<HttpResult> {
-  return new Promise((resolvePost, rejectPost) => {
-    const u = new URL(url);
-    const data = JSON.stringify(payload ?? {});
-    const req = httpRequest(
-      {
-        host: u.hostname,
-        port: u.port || 80,
-        path: u.pathname + u.search,
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Content-Length": Buffer.byteLength(data).toString(),
-        },
-      },
-      (res) => {
-        let buf = "";
-        res.setEncoding("utf8");
-        res.on("data", (c: string) => {
-          buf += c;
-        });
-        res.on("end", () => {
-          const status = res.statusCode ?? 0;
-          if (buf.length === 0) return resolvePost({ status, body: undefined });
-          try {
-            resolvePost({ status, body: JSON.parse(buf) });
-          } catch {
-            // Non-JSON body — surface it raw so callers see the truth.
-            resolvePost({ status, body: buf });
-          }
-        });
-      },
-    );
-    req.setTimeout(10_000, () => {
-      req.destroy();
-      rejectPost(new Error(`POST ${url} timed out`));
-    });
-    req.once("error", rejectPost);
-    req.write(data);
-    req.end();
-  });
-}
-
-// ─── Tools ─────────────────────────────────────────────────────────
-
-const NO_WIRE =
-  "no running wire detected; this tool requires a live wire (set NWIRE_INSPECT_URL or start one).";
-
-/**
- * Invoke a registered action via `POST /_nwire/dispatch`. Returns the
- * wire's envelope + result on success; surfaces the wire's diagnostic
- * body on 4xx/5xx without rewriting it.
- */
-const dispatchAction: InspectToolDef = {
-  name: "dispatch_action",
-  description:
-    "Invoke a registered action on the running wire (POST /_nwire/dispatch). " +
-    "Args: { action: string, input: object, user?: { id, roles? } }. " +
-    "Returns the action result + correlation envelope, or the wire's error body on failure.",
-  inputSchema: {
-    type: "object",
-    additionalProperties: false,
-    required: ["action"],
-    properties: {
-      action: { type: "string" },
-      input: { type: "object", additionalProperties: true },
-      user: {
-        type: "object",
-        additionalProperties: false,
-        properties: {
-          id: { type: "string" },
-          roles: { type: "array", items: { type: "string" } },
-        },
-      },
-      tenant: { type: "string" },
-    },
-  },
-  async run(args) {
-    const url = await discoverInspectUrl();
-    if (!url) throw new Error(NO_WIRE);
-    const action = args.action as string | undefined;
-    if (!action) throw new Error("dispatch_action requires `action`");
-    const user = args.user as { id?: string; roles?: string[] } | undefined;
-    const tenant = args.tenant as string | undefined;
-    const payload = {
-      action,
-      input: args.input ?? {},
-      ...(user?.id !== undefined && { userId: user.id }),
-      ...(tenant !== undefined && { tenant }),
-    };
-    const { status, body } = await httpPostJson(`${url}/_nwire/dispatch`, payload);
-    if (status >= 400) {
-      throw new Error(
-        `dispatch failed (${status}): ${typeof body === "string" ? body : JSON.stringify(body)}`,
-      );
-    }
-    return body;
-  },
-};
-
-/**
- * Invoke a `defineCommand` on the wire. The wire does NOT currently
- * expose a `/_nwire/command` endpoint (see
- * `packages/nwire-http/src/inspect.ts`); this tool gap-flags until that
- * endpoint is mounted. The intended shape is documented in the error.
- */
-const runCommand: InspectToolDef = {
-  name: "run_command",
-  description:
-    "Invoke a registered defineCommand on the running wire by name. " +
-    "Args: { name: string, args: object }. " +
-    "NOTE: the wire-side endpoint (/_nwire/command) is not yet mounted — see gap-flag in tool output.",
-  inputSchema: {
-    type: "object",
-    additionalProperties: false,
-    required: ["name"],
-    properties: {
-      name: { type: "string" },
-      args: { type: "object", additionalProperties: true },
-    },
-  },
-  async run(args) {
-    const url = await discoverInspectUrl();
-    if (!url) throw new Error(NO_WIRE);
-    const name = args.name as string | undefined;
-    if (!name) throw new Error("run_command requires `name`");
-
-    // Try the canonical endpoint first; if the wire returns 404 we surface
-    // a clear gap message rather than silently faking something.
-    const { status, body } = await httpPostJson(`${url}/_nwire/command`, {
-      name,
-      args: args.args ?? {},
-    });
-    if (status === 404) {
-      throw new Error(
-        "endpoint not implemented yet on wire side: POST /_nwire/command. " +
-          "See packages/nwire-http/src/inspect.ts — only /_nwire/dispatch is mounted today. " +
-          "Workaround: invoke kernel commands via the CLI (`nwire please ...`) until the route lands.",
-      );
-    }
-    if (status >= 400) {
-      throw new Error(
-        `run_command failed (${status}): ${typeof body === "string" ? body : JSON.stringify(body)}`,
-      );
-    }
-    return body;
-  },
-};
-
-/**
- * Replay a `@nwire/hooks` recording on the wire. Same gap as
- * `run_command` — `/_nwire/replay` is not yet mounted; tool ships so
- * the contract is visible.
- */
-const replayTrace: InspectToolDef = {
-  name: "replay_trace",
-  description:
-    "Replay a @nwire/hooks recording on the running wire (POST /_nwire/replay). " +
-    "Args: { recording: object } where `recording` is the output of `record()`. " +
-    "NOTE: the wire-side endpoint (/_nwire/replay) is not yet mounted — see gap-flag in tool output.",
-  inputSchema: {
-    type: "object",
-    additionalProperties: false,
-    required: ["recording"],
-    properties: {
-      recording: { type: "object", additionalProperties: true },
-    },
-  },
-  async run(args) {
-    const url = await discoverInspectUrl();
-    if (!url) throw new Error(NO_WIRE);
-    const recording = args.recording as Record<string, unknown> | undefined;
-    if (!recording || typeof recording !== "object") {
-      throw new Error("replay_trace requires `recording` (object from @nwire/hooks record()).");
-    }
-
-    const { status, body } = await httpPostJson(`${url}/_nwire/replay`, { recording });
-    if (status === 404) {
-      throw new Error(
-        "endpoint not implemented yet on wire side: POST /_nwire/replay. " +
-          "See packages/nwire-http/src/inspect.ts — recordings can still be replayed in-process via " +
-          "`replay()` from @nwire/hooks; HTTP replay against a running wire requires the new route.",
-      );
-    }
-    if (status >= 400) {
-      throw new Error(
-        `replay_trace failed (${status}): ${typeof body === "string" ? body : JSON.stringify(body)}`,
-      );
-    }
-    return body;
-  },
-};
-
-export const writeTools: readonly InspectToolDef[] = [dispatchAction, runCommand, replayTrace];
-
-export function findWriteTool(name: string): InspectToolDef | undefined {
-  return writeTools.find((t) => t.name === name);
-}