@cleocode/runtime 2026.5.130 → 2026.5.132

package/dist/chunk-5ZXRYEQ5.js

@@ -0,0 +1,190 @@
+// src/gateway/rpc/codec.ts
+import {
+  GATEWAY_RPC_PROTOCOL_VERSION,
+  GatewayRpcFrameSchema,
+  isFrozenGatewayRpcVersion
+} from "@cleocode/contracts/gateway/rpc";
+var NEWLINE = "\n";
+function encodeFrame(frame) {
+  return `${JSON.stringify(frame)}${NEWLINE}`;
+}
+function buildErrorFrame(id, code, message) {
+  return {
+    protocol_version: GATEWAY_RPC_PROTOCOL_VERSION,
+    id,
+    direction: "error",
+    error: { code, message }
+  };
+}
+function decodeLine(line) {
+  let raw;
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    return { kind: "error", frame: buildErrorFrame("0", "E_RPC_PARSE", "invalid JSON line") };
+  }
+  const recoveredId = recoverId(raw);
+  const parsed = GatewayRpcFrameSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      kind: "error",
+      frame: buildErrorFrame(recoveredId, "E_RPC_BAD_FRAME", "frame failed schema validation")
+    };
+  }
+  const frame = parsed.data;
+  if (!isFrozenGatewayRpcVersion(frame.protocol_version)) {
+    return {
+      kind: "error",
+      frame: buildErrorFrame(
+        frame.id,
+        "E_RPC_BAD_VERSION",
+        `unsupported protocol version ${frame.protocol_version}; server speaks ${GATEWAY_RPC_PROTOCOL_VERSION}`
+      )
+    };
+  }
+  if (frame.direction !== "request") {
+    return {
+      kind: "error",
+      frame: buildErrorFrame(
+        frame.id,
+        "E_RPC_BAD_FRAME",
+        `server cannot accept a ${frame.direction} frame`
+      )
+    };
+  }
+  return { kind: "request", frame };
+}
+function recoverId(raw) {
+  if (raw && typeof raw === "object" && "id" in raw) {
+    const id = raw.id;
+    if (typeof id === "string" && id.length > 0) return id;
+  }
+  return "0";
+}
+var LineBuffer = class {
+  /** Pending bytes that have not yet completed a line. */
+  buffer = "";
+  /**
+   * Push a decoded UTF-8 chunk; return every complete line it completes.
+   *
+   * @param chunk - A UTF-8 string chunk from the socket.
+   * @returns Zero or more complete lines (trailing newline stripped, blanks
+   *   skipped).
+   */
+  push(chunk) {
+    this.buffer += chunk;
+    const lines = [];
+    let idx = this.buffer.indexOf(NEWLINE);
+    while (idx !== -1) {
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (line.length > 0) lines.push(line);
+      idx = this.buffer.indexOf(NEWLINE);
+    }
+    return lines;
+  }
+};
+
+// src/gateway/rpc/server.ts
+import { existsSync, unlinkSync } from "fs";
+import { createServer } from "net";
+import { GATEWAY_RPC_PROTOCOL_VERSION as GATEWAY_RPC_PROTOCOL_VERSION2 } from "@cleocode/contracts/gateway/rpc";
+import { getLogger } from "@cleocode/core";
+async function routeFrame(handler, frame) {
+  const request = {
+    ...frame.request,
+    // Force the transport of origin — a client cannot impersonate cli/mcp/http.
+    source: "rpc",
+    requestId: frame.request.requestId
+  };
+  try {
+    const response = await handler.handle(request);
+    return {
+      protocol_version: GATEWAY_RPC_PROTOCOL_VERSION2,
+      id: frame.id,
+      direction: "response",
+      response
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return buildErrorFrame(frame.id, "E_RPC_INTERNAL", message);
+  }
+}
+function handleConnection(handler, socket, log) {
+  socket.setEncoding("utf8");
+  const lines = new LineBuffer();
+  socket.on("data", (chunk) => {
+    for (const line of lines.push(chunk)) {
+      const decoded = decodeLine(line);
+      if (decoded.kind === "error") {
+        socket.write(encodeFrame(decoded.frame));
+        continue;
+      }
+      routeFrame(handler, decoded.frame).then((out) => {
+        if (!socket.destroyed) socket.write(encodeFrame(out));
+      }).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        log.warn({ err }, "rpc frame routing failed");
+        if (!socket.destroyed) {
+          socket.write(encodeFrame(buildErrorFrame(decoded.frame.id, "E_RPC_INTERNAL", message)));
+        }
+      });
+    }
+  });
+  socket.on("error", (err) => {
+    log.warn({ err }, "rpc connection error");
+  });
+}
+function startRpcServer(handler, opts) {
+  const log = getLogger("gateway-rpc");
+  const removeStale = opts.removeStaleSocket ?? true;
+  if (removeStale && existsSync(opts.socketPath)) {
+    try {
+      unlinkSync(opts.socketPath);
+    } catch (err) {
+      log.warn({ err, socketPath: opts.socketPath }, "failed to unlink stale rpc socket");
+    }
+  }
+  const server = createServer((socket) => handleConnection(handler, socket, log));
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(opts.socketPath, () => {
+      server.removeListener("error", reject);
+      log.info(
+        { socketPath: opts.socketPath, version: GATEWAY_RPC_PROTOCOL_VERSION2 },
+        "rpc server listening"
+      );
+      let closed = false;
+      const handle = {
+        server,
+        socketPath: opts.socketPath,
+        close() {
+          if (closed) return Promise.resolve();
+          closed = true;
+          return new Promise((res) => {
+            server.close(() => {
+              if (existsSync(opts.socketPath)) {
+                try {
+                  unlinkSync(opts.socketPath);
+                } catch {
+                }
+              }
+              res();
+            });
+          });
+        }
+      };
+      resolve(handle);
+    });
+  });
+}
+
+export {
+  encodeFrame,
+  buildErrorFrame,
+  decodeLine,
+  LineBuffer,
+  routeFrame,
+  startRpcServer
+};
+//# sourceMappingURL=chunk-5ZXRYEQ5.js.map

package/dist/chunk-5ZXRYEQ5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/gateway/rpc/codec.ts","../src/gateway/rpc/server.ts"],"sourcesContent":["/**\n * NDJSON codec for the CLI-RPC transport.\n *\n * Implements the SAME framing discipline as the FROZEN `supervisor-ipc` v1.0\n * contract — one zod-validated JSON envelope per newline-delimited line, with\n * an explicit `protocol_version` negotiation step — but for the gateway-RPC\n * frame set (`@cleocode/contracts/gateway/rpc`). The supervisor-ipc module is\n * frozen and is NOT edited; this codec re-applies its pattern.\n *\n * The codec is intentionally socket-agnostic: it owns line buffering, JSON\n * parse, zod decode, and version negotiation, returning typed results the\n * server maps onto `node:net` reads/writes. This keeps the parse/validate logic\n * unit-testable without binding a real socket.\n *\n * @task T11449\n * @epic T11254\n * @saga T11243\n */\n\nimport {\n  GATEWAY_RPC_PROTOCOL_VERSION,\n  type GatewayRpcErrorCode,\n  type GatewayRpcErrorFrame,\n  type GatewayRpcFrame,\n  GatewayRpcFrameSchema,\n  type GatewayRpcRequestFrame,\n  type GatewayRpcResponseFrame,\n  isFrozenGatewayRpcVersion,\n} from '@cleocode/contracts/gateway/rpc';\n\n/** Newline delimiter for the NDJSON wire (mirrors supervisor-ipc). */\nconst NEWLINE = '\\n';\n\n/**\n * Encode any RPC frame to a single NDJSON line (JSON + trailing `\\n`).\n *\n * @param frame - The response or error frame to serialize.\n * @returns A newline-terminated JSON string ready to write to the socket.\n */\nexport function encodeFrame(frame: GatewayRpcResponseFrame | GatewayRpcErrorFrame): string {\n  return `${JSON.stringify(frame)}${NEWLINE}`;\n}\n\n/**\n * Build a protocol-level error frame.\n *\n * @param id - Correlation id (`'0'` when the originating frame's id is unknown).\n * @param code - One of the frozen {@link GatewayRpcErrorCode} values.\n * @param message - Human-readable detail.\n * @returns A fully-formed {@link GatewayRpcErrorFrame}.\n */\nexport function buildErrorFrame(\n  id: string,\n  code: GatewayRpcErrorCode,\n  message: string,\n): GatewayRpcErrorFrame {\n  return {\n    protocol_version: GATEWAY_RPC_PROTOCOL_VERSION,\n    id,\n    direction: 'error',\n    error: { code, message },\n  };\n}\n\n/**\n * The discriminated outcome of decoding a single inbound NDJSON line.\n *\n * - `request` — a valid, version-matched request frame ready to route.\n * - `error`   — a protocol-level error frame the server should write straight\n *               back (parse failure, version mismatch, or malformed frame). The\n *               server never routes these to the gateway.\n */\nexport type DecodeResult =\n  | { kind: 'request'; frame: GatewayRpcRequestFrame }\n  | { kind: 'error'; frame: GatewayRpcErrorFrame };\n\n/**\n * Decode + validate a single inbound NDJSON line into a routable request or a\n * protocol-level error frame.\n *\n * Steps (the supervisor-ipc pattern, applied to gateway frames):\n *  1. JSON parse — failure → `E_RPC_PARSE`.\n *  2. zod decode against {@link GatewayRpcFrameSchema} — failure → `E_RPC_BAD_FRAME`.\n *  3. version negotiation via {@link isFrozenGatewayRpcVersion} —\n *     mismatch → `E_RPC_BAD_VERSION`.\n *  4. direction must be `request` (a server never receives response/error\n *     frames) — otherwise → `E_RPC_BAD_FRAME`.\n *\n * The best-effort correlation `id` is recovered from the raw JSON when possible\n * so the client can match the error to its request even on a decode failure.\n *\n * @param line - One trimmed NDJSON line (no trailing newline).\n * @returns A {@link DecodeResult}.\n */\nexport function decodeLine(line: string): DecodeResult {\n  let raw: unknown;\n  try {\n    raw = JSON.parse(line);\n  } catch {\n    return { kind: 'error', frame: buildErrorFrame('0', 'E_RPC_PARSE', 'invalid JSON line') };\n  }\n\n  // Best-effort id recovery for error correlation before full validation.\n  const recoveredId = recoverId(raw);\n\n  const parsed = GatewayRpcFrameSchema.safeParse(raw);\n  if (!parsed.success) {\n    return {\n      kind: 'error',\n      frame: buildErrorFrame(recoveredId, 'E_RPC_BAD_FRAME', 'frame failed schema validation'),\n    };\n  }\n\n  const frame: GatewayRpcFrame = parsed.data;\n\n  if (!isFrozenGatewayRpcVersion(frame.protocol_version)) {\n    return {\n      kind: 'error',\n      frame: buildErrorFrame(\n        frame.id,\n        'E_RPC_BAD_VERSION',\n        `unsupported protocol version ${frame.protocol_version}; server speaks ${GATEWAY_RPC_PROTOCOL_VERSION}`,\n      ),\n    };\n  }\n\n  if (frame.direction !== 'request') {\n    return {\n      kind: 'error',\n      frame: buildErrorFrame(\n        frame.id,\n        'E_RPC_BAD_FRAME',\n        `server cannot accept a ${frame.direction} frame`,\n      ),\n    };\n  }\n\n  return { kind: 'request', frame };\n}\n\n/**\n * Recover a best-effort correlation id from raw decoded JSON, used so a\n * validation failure can still be correlated to the client's request.\n *\n * @param raw - The result of `JSON.parse` on the inbound line.\n * @returns The string `id` if present and non-empty, else `'0'`.\n */\nfunction recoverId(raw: unknown): string {\n  if (raw && typeof raw === 'object' && 'id' in raw) {\n    const id = (raw as { id: unknown }).id;\n    if (typeof id === 'string' && id.length > 0) return id;\n  }\n  return '0';\n}\n\n/**\n * A streaming line splitter for the NDJSON wire.\n *\n * `node:net` sockets deliver arbitrary chunk boundaries; a single `data` event\n * may carry a partial line or several lines. This buffer accumulates bytes and\n * yields only complete lines (split on `\\n`), matching the supervisor-ipc\n * client's `readline`-style framing without depending on `readline` (so it can\n * be driven directly off socket chunks).\n */\nexport class LineBuffer {\n  /** Pending bytes that have not yet completed a line. */\n  private buffer = '';\n\n  /**\n   * Push a decoded UTF-8 chunk; return every complete line it completes.\n   *\n   * @param chunk - A UTF-8 string chunk from the socket.\n   * @returns Zero or more complete lines (trailing newline stripped, blanks\n   *   skipped).\n   */\n  push(chunk: string): string[] {\n    this.buffer += chunk;\n    const lines: string[] = [];\n    let idx = this.buffer.indexOf(NEWLINE);\n    while (idx !== -1) {\n      const line = this.buffer.slice(0, idx).trim();\n      this.buffer = this.buffer.slice(idx + 1);\n      if (line.length > 0) lines.push(line);\n      idx = this.buffer.indexOf(NEWLINE);\n    }\n    return lines;\n  }\n}\n","/**\n * CLI-RPC unix-socket transport adapter — routes NDJSON frames through the gateway.\n *\n * Serves the gateway over a long-lived unix-domain socket using newline-delimited\n * JSON (NDJSON): one zod-validated {@link GatewayRpcFrame} per line. Any local\n * client (the `cleo` CLI talking to a warm daemon, Studio's server process, a\n * test harness) can open the socket, write `request` frames, and read back\n * `response`/`error` frames — without paying the per-invocation cold-start of\n * spawning a fresh `cleo` process.\n *\n * This is the THIRD transport adapter, mirroring the just-merged MCP stdio\n * adapter (`packages/runtime/src/gateway/mcp/`):\n *\n *   RPC request frame { direction:'request', request:{…} }\n *     → decode + validate (`@cleocode/contracts/gateway/rpc`)\n *     → DispatchRequest { source: 'rpc', … }  (re-validated at the boundary)\n *     → injected {@link GatewayHandler}.handle()\n *     → DispatchResponse (LAFS envelope)  →  RPC response frame\n *\n * The adapter owns ONLY wire concerns: socket lifecycle, line framing, version\n * negotiation, error rendering, and per-connection cleanup. All domain logic\n * (resolution, validation, middleware, handler execution) lives behind the\n * {@link GatewayHandler} — exactly mirroring the CLI and MCP adapters. There is\n * NO `process.exit` and NO error-render inside the handlers (R3 contract); the\n * adapter never calls `process.exit` at all (lifecycle is the caller's).\n *\n * The request `source` is forced to `'rpc'` regardless of what the client sent,\n * so a client cannot impersonate another transport.\n *\n * @task T11449\n * @epic T11254\n * @saga T11243\n */\n\nimport { existsSync, unlinkSync } from 'node:fs';\nimport { createServer, type Socket } from 'node:net';\nimport type { DispatchRequest } from '@cleocode/contracts/gateway';\nimport type {\n  GatewayRpcRequestFrame,\n  GatewayRpcResponseFrame,\n} from '@cleocode/contracts/gateway/rpc';\nimport { GATEWAY_RPC_PROTOCOL_VERSION } from '@cleocode/contracts/gateway/rpc';\nimport { getLogger } from '@cleocode/core';\nimport type { GatewayHandler } from '../index.js';\nimport { buildErrorFrame, decodeLine, encodeFrame, LineBuffer } from './codec.js';\nimport type { RpcServerHandle, RpcServerOptions } from './types.js';\n\n/**\n * Route a single decoded request frame through the gateway handler and build\n * the correlated response frame.\n *\n * The request's `source` is forced to `'rpc'`; the frame `id` is reused as the\n * response correlation id (and, when the client omitted a `requestId` shaped\n * for tracing, the frame id flows through as the dispatch `requestId`). Thrown\n * handler errors are caught and rendered as a protocol-level `E_RPC_INTERNAL`\n * error frame — never propagated as an unhandled rejection or `process.exit`.\n *\n * @param handler - The injected transport-neutral gateway handler.\n * @param frame - A validated, version-matched request frame.\n * @returns The response or error frame to write back on the same connection.\n */\nexport async function routeFrame(\n  handler: GatewayHandler,\n  frame: GatewayRpcRequestFrame,\n): Promise<GatewayRpcResponseFrame | ReturnType<typeof buildErrorFrame>> {\n  const request: DispatchRequest = {\n    ...frame.request,\n    // Force the transport of origin — a client cannot impersonate cli/mcp/http.\n    source: 'rpc',\n    requestId: frame.request.requestId,\n  };\n\n  try {\n    const response = await handler.handle(request);\n    return {\n      protocol_version: GATEWAY_RPC_PROTOCOL_VERSION,\n      id: frame.id,\n      direction: 'response',\n      response,\n    };\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err);\n    return buildErrorFrame(frame.id, 'E_RPC_INTERNAL', message);\n  }\n}\n\n/**\n * Handle a single client connection: buffer NDJSON lines, decode each, route\n * request frames through the gateway, and write back response/error frames.\n *\n * Each connection owns its own {@link LineBuffer}, so partial-line chunk\n * boundaries are reassembled per socket. Frames are processed concurrently;\n * each correlated response carries the originating frame `id`, so the client\n * can demultiplex out-of-order completions.\n *\n * @param handler - The injected gateway handler.\n * @param socket - The accepted `node:net` connection.\n * @param log - The adapter's pino logger.\n */\nfunction handleConnection(\n  handler: GatewayHandler,\n  socket: Socket,\n  log: ReturnType<typeof getLogger>,\n): void {\n  socket.setEncoding('utf8');\n  const lines = new LineBuffer();\n\n  socket.on('data', (chunk: string) => {\n    for (const line of lines.push(chunk)) {\n      const decoded = decodeLine(line);\n      if (decoded.kind === 'error') {\n        socket.write(encodeFrame(decoded.frame));\n        continue;\n      }\n      routeFrame(handler, decoded.frame)\n        .then((out) => {\n          if (!socket.destroyed) socket.write(encodeFrame(out));\n        })\n        .catch((err: unknown) => {\n          // routeFrame already traps handler errors; this guards the framing path.\n          const message = err instanceof Error ? err.message : String(err);\n          log.warn({ err }, 'rpc frame routing failed');\n          if (!socket.destroyed) {\n            socket.write(encodeFrame(buildErrorFrame(decoded.frame.id, 'E_RPC_INTERNAL', message)));\n          }\n        });\n    }\n  });\n\n  socket.on('error', (err) => {\n    log.warn({ err }, 'rpc connection error');\n  });\n}\n\n/**\n * Start the CLI-RPC unix-socket server over the gateway.\n *\n * Binds {@link RpcServerOptions.socketPath}, accepts connections, and routes\n * each inbound NDJSON `request` frame through the injected {@link GatewayHandler}.\n * The caller assembles the handler (via `createGatewayHandler` with its domain\n * handlers + middleware) and injects it here — this adapter never builds\n * handlers itself, keeping the runtime free of any `@cleocode/cleo` dependency.\n *\n * Returns once the socket is listening. The returned {@link RpcServerHandle}\n * exposes an idempotent `close()` for deterministic teardown (daemon shutdown,\n * tests). The adapter never calls `process.exit`.\n *\n * @param handler - The transport-neutral gateway handler to route through.\n * @param opts - Socket path + lifecycle options.\n * @returns A promise resolving to the live {@link RpcServerHandle}.\n */\nexport function startRpcServer(\n  handler: GatewayHandler,\n  opts: RpcServerOptions,\n): Promise<RpcServerHandle> {\n  const log = getLogger('gateway-rpc');\n  const removeStale = opts.removeStaleSocket ?? true;\n\n  if (removeStale && existsSync(opts.socketPath)) {\n    try {\n      unlinkSync(opts.socketPath);\n    } catch (err) {\n      log.warn({ err, socketPath: opts.socketPath }, 'failed to unlink stale rpc socket');\n    }\n  }\n\n  const server = createServer((socket) => handleConnection(handler, socket, log));\n\n  return new Promise<RpcServerHandle>((resolve, reject) => {\n    server.once('error', reject);\n    server.listen(opts.socketPath, () => {\n      server.removeListener('error', reject);\n      log.info(\n        { socketPath: opts.socketPath, version: GATEWAY_RPC_PROTOCOL_VERSION },\n        'rpc server listening',\n      );\n\n      let closed = false;\n      const handle: RpcServerHandle = {\n        server,\n        socketPath: opts.socketPath,\n        close(): Promise<void> {\n          if (closed) return Promise.resolve();\n          closed = true;\n          return new Promise<void>((res) => {\n            server.close(() => {\n              if (existsSync(opts.socketPath)) {\n                try {\n                  unlinkSync(opts.socketPath);\n                } catch {\n                  // best-effort cleanup; the OS reclaims the node on exit anyway.\n                }\n              }\n              res();\n            });\n          });\n        },\n      };\n      resolve(handle);\n    });\n  });\n}\n"],"mappings":"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","names":["GATEWAY_RPC_PROTOCOL_VERSION","GATEWAY_RPC_PROTOCOL_VERSION"]}

package/dist/chunk-R4XBXUQN.js

@@ -0,0 +1,253 @@
+// src/gateway/mcp/server.ts
+import { randomUUID } from "crypto";
+import * as readline from "readline";
+import { getLogger } from "@cleocode/core";
+
+// src/gateway/mcp/tool-naming.ts
+var MCP_TOOL_PREFIX = "cleo_";
+function toSnake(segment) {
+  return segment.replace(/[.-]/g, "_");
+}
+function operationToToolName(op) {
+  return `${MCP_TOOL_PREFIX}${toSnake(op.domain)}_${toSnake(op.operation)}`;
+}
+function toolNameToOperationKey(toolName, exposed) {
+  const match = exposed.find((op) => operationToToolName(op) === toolName);
+  return match ? { domain: match.domain, operation: match.operation } : void 0;
+}
+
+// src/gateway/registry.ts
+import { OPERATIONS as _OPERATIONS } from "@cleocode/contracts";
+var OPERATIONS = _OPERATIONS;
+function deriveGatewayMatrix(gateway) {
+  const matrix = {};
+  for (const op of OPERATIONS) {
+    if (op.gateway !== gateway) continue;
+    if (!matrix[op.domain]) matrix[op.domain] = [];
+    matrix[op.domain].push(op.operation);
+  }
+  return matrix;
+}
+function getGatewayDomains(gateway) {
+  return Object.keys(deriveGatewayMatrix(gateway));
+}
+function resolve(gateway, domain, operation) {
+  const def = OPERATIONS.find(
+    (o) => o.gateway === gateway && o.domain === domain && o.operation === operation
+  );
+  if (!def) return void 0;
+  return { domain: def.domain, operation: def.operation, def };
+}
+function validateRequiredParams(def, params) {
+  if (!def.requiredParams || def.requiredParams.length === 0) return [];
+  const provided = params || {};
+  const allowEmptyKeys = /* @__PURE__ */ new Set();
+  if (def.params) {
+    for (const p of def.params) {
+      if (p.allowEmpty === true) allowEmptyKeys.add(p.name);
+    }
+  }
+  return def.requiredParams.filter((key) => {
+    const v = provided[key];
+    if (v === void 0 || v === null) return true;
+    if (v === "" && !allowEmptyKeys.has(key)) return true;
+    return false;
+  });
+}
+function getByDomain(domain) {
+  return OPERATIONS.filter((o) => o.domain === domain);
+}
+function getByGateway(gateway) {
+  return OPERATIONS.filter((o) => o.gateway === gateway);
+}
+function getByTier(tier) {
+  return OPERATIONS.filter((o) => o.tier <= tier);
+}
+function getActiveDomains() {
+  const active = new Set(OPERATIONS.map((o) => o.domain));
+  return Array.from(active);
+}
+function getCounts() {
+  return {
+    query: OPERATIONS.filter((o) => o.gateway === "query").length,
+    mutate: OPERATIONS.filter((o) => o.gateway === "mutate").length,
+    total: OPERATIONS.length
+  };
+}
+var counts = getCounts();
+if (counts.total !== OPERATIONS.length) {
+  console.warn(
+    `[Registry] Operation count mismatch: total=${counts.total}, registry=${OPERATIONS.length}`
+  );
+}
+
+// src/gateway/mcp/tools-list.ts
+function exposedOperations() {
+  return OPERATIONS.filter((op) => op.mcpExposed === true);
+}
+function paramTypeToJsonSchema(type) {
+  return type === "array" ? "string" : type;
+}
+function buildInputSchema(op) {
+  const properties = {};
+  const required = [];
+  for (const param of op.params ?? []) {
+    if (param.hidden === true) continue;
+    const prop = {
+      type: paramTypeToJsonSchema(param.type),
+      description: param.description
+    };
+    if (param.enum !== void 0 && param.enum.length > 0) {
+      prop.enum = param.enum;
+    }
+    properties[param.name] = prop;
+    if (param.required) required.push(param.name);
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+function operationToMcpTool(op) {
+  return {
+    name: operationToToolName(op),
+    description: op.description,
+    inputSchema: buildInputSchema(op)
+  };
+}
+function buildToolsList() {
+  return exposedOperations().map(operationToMcpTool);
+}
+
+// src/gateway/mcp/server.ts
+function ok(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+function rpcError(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+var SERVER_NAME = "cleo-gateway-mcp";
+var PROTOCOL_VERSION = "2024-11-05";
+var GATEWAY_MCP_VERSION = "1.0.0";
+function responseToToolResult(response) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(response) }],
+    isError: response.success ? void 0 : true
+  };
+}
+async function callTool(handler, toolName, args) {
+  const exposed = exposedOperations();
+  const key = toolNameToOperationKey(toolName, exposed);
+  if (!key) {
+    return {
+      content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
+      isError: true
+    };
+  }
+  const def = exposed.find((op) => op.domain === key.domain && op.operation === key.operation);
+  if (!def) {
+    return {
+      content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
+      isError: true
+    };
+  }
+  const request = {
+    gateway: def.gateway,
+    domain: key.domain,
+    operation: key.operation,
+    params: args,
+    source: "mcp",
+    requestId: randomUUID()
+  };
+  try {
+    const response = await handler.handle(request);
+    return responseToToolResult(response);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Tool execution failed: ${message}` }],
+      isError: true
+    };
+  }
+}
+async function handleRequest(handler, req) {
+  const { id, method, params } = req;
+  switch (method) {
+    case "initialize":
+      return ok(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: SERVER_NAME, version: GATEWAY_MCP_VERSION }
+      });
+    case "tools/list":
+      return ok(id, { tools: buildToolsList() });
+    case "tools/call": {
+      const p = params;
+      const toolName = p?.name;
+      if (!toolName) {
+        return rpcError(id, -32602, "Missing tool name in params.name");
+      }
+      const result = await callTool(handler, toolName, p?.arguments ?? {});
+      return ok(id, result);
+    }
+    case "notifications/initialized":
+    case "ping":
+      return ok(id, {});
+    default:
+      return rpcError(id, -32601, `Method not found: ${method}`);
+  }
+}
+function startMcpServer(handler, opts) {
+  const input = opts?.input ?? process.stdin;
+  const output = opts?.output ?? process.stdout;
+  const exitOnClose = opts?.exitOnClose ?? true;
+  const log = getLogger("gateway-mcp");
+  const rl = readline.createInterface({ input, terminal: false });
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let req;
+    try {
+      req = JSON.parse(trimmed);
+    } catch {
+      output.write(`${JSON.stringify(rpcError(null, -32700, "Parse error: invalid JSON"))}
+`);
+      return;
+    }
+    handleRequest(handler, req).then((response) => {
+      output.write(`${JSON.stringify(response)}
+`);
+    }).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn({ err }, "mcp request handling failed");
+      output.write(
+        `${JSON.stringify(rpcError(req.id ?? null, -32603, `Internal error: ${message}`))}
+`
+      );
+    });
+  });
+  rl.on("close", () => {
+    if (exitOnClose) process.exit(0);
+  });
+}
+
+export {
+  OPERATIONS,
+  deriveGatewayMatrix,
+  getGatewayDomains,
+  resolve,
+  validateRequiredParams,
+  getByDomain,
+  getByGateway,
+  getByTier,
+  getActiveDomains,
+  getCounts,
+  MCP_TOOL_PREFIX,
+  operationToToolName,
+  toolNameToOperationKey,
+  exposedOperations,
+  operationToMcpTool,
+  buildToolsList,
+  callTool,
+  startMcpServer
+};
+//# sourceMappingURL=chunk-R4XBXUQN.js.map

package/dist/chunk-R4XBXUQN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/gateway/mcp/server.ts","../src/gateway/mcp/tool-naming.ts","../src/gateway/registry.ts","../src/gateway/mcp/tools-list.ts"],"sourcesContent":["/**\n * MCP stdio transport adapter — routes `tools/call` through the gateway.\n *\n * Serves the Model Context Protocol over stdio (newline-delimited JSON-RPC 2.0)\n * so any MCP-compatible client (Claude Code, LLM-agnostic tools) can discover\n * and invoke CLEO operations. Unlike the legacy standalone `@cleocode/mcp-adapter`\n * — which called the `@cleocode/core` SDK directly — this adapter is a thin\n * TRANSPORT over the unified gateway:\n *\n *   MCP `tools/call` { name, arguments }\n *     → {@link GatewayOperationKey} (via the `mcpExposed` registry subset)\n *     → DispatchRequest { source: 'mcp', gateway, domain, operation, params }\n *     → injected {@link GatewayHandler}.handle()\n *     → DispatchResponse (LAFS envelope)  →  MCP tool result (JSON text content)\n *\n * The adapter owns ONLY wire concerns: JSON-RPC framing, the stdio read loop,\n * `tools/list` generation, error rendering, and `process.exit` on stream close.\n * All domain logic (resolution, validation, middleware, handler execution) lives\n * behind the {@link GatewayHandler} — exactly mirroring how the CLI adapter\n * wraps the same handler. `process.exit` and error-render stay HERE, never in\n * the handlers (R3-T4 contract).\n *\n * `tools/list` is generated from the OPERATIONS registry behind the default-deny\n * `mcpExposed` flag, so the external tool surface is identical to the historical\n * standalone adapter (no behavior change).\n *\n * @task T11448\n * @epic T11254\n * @saga T11243\n */\n\nimport { randomUUID } from 'node:crypto';\nimport * as readline from 'node:readline';\nimport type { DispatchRequest, DispatchResponse } from '@cleocode/contracts/gateway';\nimport { getLogger } from '@cleocode/core';\nimport type { GatewayHandler } from '../index.js';\nimport { toolNameToOperationKey } from './tool-naming.js';\nimport { buildToolsList, exposedOperations } from './tools-list.js';\nimport type { McpTool, McpToolResult } from './types.js';\n\n// ---------------------------------------------------------------------------\n// JSON-RPC 2.0 envelope helpers\n// ---------------------------------------------------------------------------\n\n/** Inbound JSON-RPC request frame. */\ninterface JsonRpcRequest {\n  jsonrpc: '2.0';\n  id: number | string | null;\n  method: string;\n  params?: unknown;\n}\n\n/** Outbound JSON-RPC response frame. */\ninterface JsonRpcResponse {\n  jsonrpc: '2.0';\n  id: number | string | null;\n  result?: unknown;\n  error?: { code: number; message: string; data?: unknown };\n}\n\n/** Build a JSON-RPC success response. */\nfunction ok(id: number | string | null, result: unknown): JsonRpcResponse {\n  return { jsonrpc: '2.0', id, result };\n}\n\n/** Build a JSON-RPC error response. */\nfunction rpcError(id: number | string | null, code: number, message: string): JsonRpcResponse {\n  return { jsonrpc: '2.0', id, error: { code, message } };\n}\n\n// ---------------------------------------------------------------------------\n// Server identity\n// ---------------------------------------------------------------------------\n\n/** Advertised MCP server name. */\nconst SERVER_NAME = 'cleo-gateway-mcp';\n/** MCP protocol revision the adapter speaks. */\nconst PROTOCOL_VERSION = '2024-11-05';\n/** Version string advertised in the `initialize` handshake. */\nconst GATEWAY_MCP_VERSION = '1.0.0';\n\n// ---------------------------------------------------------------------------\n// tools/call → gateway routing\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a {@link DispatchResponse} envelope into an MCP tool result.\n *\n * The full LAFS envelope is serialized as the text content so MCP clients see\n * the same `{ success, data, meta, error }` payload every other transport\n * returns. `isError` is set from the envelope's `success` flag.\n *\n * @param response - The gateway dispatch response.\n * @returns An MCP {@link McpToolResult}.\n */\nfunction responseToToolResult(response: DispatchResponse): McpToolResult {\n  return {\n    content: [{ type: 'text', text: JSON.stringify(response) }],\n    isError: response.success ? undefined : true,\n  };\n}\n\n/**\n * Route a single MCP `tools/call` through the gateway handler.\n *\n * Resolves the tool name to a `(domain, operation)` key against the exposed\n * (`mcpExposed`) registry subset, builds a `source: 'mcp'` {@link DispatchRequest},\n * and delegates to the injected {@link GatewayHandler}. Unknown tool names and\n * thrown handler errors are rendered as MCP error results — never propagated as\n * `process.exit` from this layer.\n *\n * @param handler - The injected transport-neutral gateway handler.\n * @param toolName - The MCP `tools/call` tool name.\n * @param args - The parsed tool arguments (already JSON-decoded by the client).\n * @returns An MCP {@link McpToolResult}.\n */\nexport async function callTool(\n  handler: GatewayHandler,\n  toolName: string,\n  args: Record<string, unknown>,\n): Promise<McpToolResult> {\n  const exposed = exposedOperations();\n  const key = toolNameToOperationKey(toolName, exposed);\n  if (!key) {\n    return {\n      content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],\n      isError: true,\n    };\n  }\n\n  // The exposed def carries the CQRS gateway — no second lookup needed.\n  const def = exposed.find((op) => op.domain === key.domain && op.operation === key.operation);\n  if (!def) {\n    return {\n      content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],\n      isError: true,\n    };\n  }\n\n  const request: DispatchRequest = {\n    gateway: def.gateway,\n    domain: key.domain,\n    operation: key.operation,\n    params: args,\n    source: 'mcp',\n    requestId: randomUUID(),\n  };\n\n  try {\n    const response = await handler.handle(request);\n    return responseToToolResult(response);\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err);\n    return {\n      content: [{ type: 'text', text: `Tool execution failed: ${message}` }],\n      isError: true,\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------\n// JSON-RPC method handlers\n// ---------------------------------------------------------------------------\n\n/**\n * Handle a single decoded JSON-RPC request frame.\n *\n * @param handler - The injected gateway handler.\n * @param req - The decoded JSON-RPC request.\n * @returns The JSON-RPC response frame to write back.\n */\nasync function handleRequest(\n  handler: GatewayHandler,\n  req: JsonRpcRequest,\n): Promise<JsonRpcResponse> {\n  const { id, method, params } = req;\n\n  switch (method) {\n    case 'initialize':\n      return ok(id, {\n        protocolVersion: PROTOCOL_VERSION,\n        capabilities: { tools: {} },\n        serverInfo: { name: SERVER_NAME, version: GATEWAY_MCP_VERSION },\n      });\n\n    case 'tools/list':\n      return ok(id, { tools: buildToolsList() satisfies McpTool[] });\n\n    case 'tools/call': {\n      const p = params as { name?: string; arguments?: Record<string, unknown> } | undefined;\n      const toolName = p?.name;\n      if (!toolName) {\n        return rpcError(id, -32602, 'Missing tool name in params.name');\n      }\n      const result = await callTool(handler, toolName, p?.arguments ?? {});\n      return ok(id, result);\n    }\n\n    case 'notifications/initialized':\n    case 'ping':\n      return ok(id, {});\n\n    default:\n      return rpcError(id, -32601, `Method not found: ${method}`);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// stdio server entry point\n// ---------------------------------------------------------------------------\n\n/**\n * Options for {@link startMcpServer}.\n */\nexport interface McpServerOptions {\n  /** Inbound stream (defaults to `process.stdin`). */\n  input?: NodeJS.ReadableStream;\n  /** Outbound stream (defaults to `process.stdout`). */\n  output?: NodeJS.WritableStream;\n  /**\n   * Whether to call `process.exit(0)` when the input stream closes.\n   * Defaults to `true` (production stdio). Tests pass `false`.\n   */\n  exitOnClose?: boolean;\n}\n\n/**\n * Start the MCP stdio server over the gateway.\n *\n * Reads newline-delimited JSON-RPC 2.0 requests from the input stream, routes\n * `tools/call` through the injected {@link GatewayHandler}, and writes responses\n * to the output stream. Each inbound line must be one complete JSON-RPC request.\n *\n * The caller assembles the {@link GatewayHandler} (via `createGatewayHandler`\n * with its domain handlers + middleware) and injects it here — this adapter\n * never builds handlers itself, keeping the runtime free of any\n * `@cleocode/cleo` dependency.\n *\n * @param handler - The transport-neutral gateway handler to route through.\n * @param opts - Optional stream + lifecycle overrides (defaults to stdio).\n */\nexport function startMcpServer(handler: GatewayHandler, opts?: McpServerOptions): void {\n  const input = opts?.input ?? process.stdin;\n  const output = opts?.output ?? process.stdout;\n  const exitOnClose = opts?.exitOnClose ?? true;\n  const log = getLogger('gateway-mcp');\n\n  const rl = readline.createInterface({ input, terminal: false });\n\n  rl.on('line', (line) => {\n    const trimmed = line.trim();\n    if (!trimmed) return;\n\n    let req: JsonRpcRequest;\n    try {\n      req = JSON.parse(trimmed) as JsonRpcRequest;\n    } catch {\n      output.write(`${JSON.stringify(rpcError(null, -32700, 'Parse error: invalid JSON'))}\\n`);\n      return;\n    }\n\n    handleRequest(handler, req)\n      .then((response) => {\n        output.write(`${JSON.stringify(response)}\\n`);\n      })\n      .catch((err: unknown) => {\n        const message = err instanceof Error ? err.message : String(err);\n        log.warn({ err }, 'mcp request handling failed');\n        output.write(\n          `${JSON.stringify(rpcError(req.id ?? null, -32603, `Internal error: ${message}`))}\\n`,\n        );\n      });\n  });\n\n  rl.on('close', () => {\n    if (exitOnClose) process.exit(0);\n  });\n}\n","/**\n * MCP tool-name <-> gateway-operation mapping.\n *\n * The MCP wire protocol identifies a tool by a single flat `name` string\n * (snake_case, e.g. `cleo_sentient_propose_list`), whereas the gateway routes\n * on a `(gateway, domain, operation)` triple (e.g.\n * `query / sentient / propose.list`). This module is the bijective bridge\n * between the two surfaces:\n *\n *   gateway op  →  MCP tool name   {@link operationToToolName}\n *   MCP tool name  →  domain+operation   {@link toolNameToOperationKey}\n *\n * ## Naming convention (frozen — matches the legacy `@cleocode/mcp-adapter`)\n *\n * `cleo_<domain>_<operation>` where every `.` and `-` in the dotted operation\n * name becomes `_`. The three historically-exposed tools therefore map as:\n *\n *   | gateway op                  | MCP tool name                  |\n *   |-----------------------------|--------------------------------|\n *   | `sentient` · `status`       | `cleo_sentient_status`         |\n *   | `sentient` · `propose.list` | `cleo_sentient_propose_list`   |\n *   | `sentient` · `propose.enable` | `cleo_sentient_propose_enable` |\n *\n * Preserving this exact mapping is what guarantees R3-T4's \"no behavior change\n * to the MCP tool surface\" acceptance criterion.\n *\n * @task T11448\n * @epic T11254\n * @saga T11243\n */\n\nimport type { OperationDef } from '@cleocode/contracts';\n\n/** Prefix every CLEO MCP tool name carries. */\nexport const MCP_TOOL_PREFIX = 'cleo_';\n\n/**\n * Identifies a gateway operation by its `(domain, operation)` pair. The CQRS\n * gateway resolves which `Gateway` ('query' | 'mutate') the pair belongs to via\n * the operation registry, so the MCP adapter does not need to carry it.\n */\nexport interface GatewayOperationKey {\n  /** Canonical domain (e.g. `'sentient'`). */\n  readonly domain: string;\n  /** Dotted operation name (e.g. `'propose.list'`). */\n  readonly operation: string;\n}\n\n/**\n * Convert a dotted operation segment into its MCP-safe snake_case form.\n *\n * @param segment - A domain or operation string (may contain `.`/`-`).\n * @returns The segment with every `.`/`-` replaced by `_`.\n */\nfunction toSnake(segment: string): string {\n  return segment.replace(/[.-]/g, '_');\n}\n\n/**\n * Derive the flat MCP tool name for a gateway operation.\n *\n * @param op - An {@link OperationDef} (or any object carrying `domain` +\n *   `operation`) from the registry.\n * @returns The MCP tool name, e.g. `'cleo_sentient_propose_list'`.\n */\nexport function operationToToolName(op: Pick<OperationDef, 'domain' | 'operation'>): string {\n  return `${MCP_TOOL_PREFIX}${toSnake(op.domain)}_${toSnake(op.operation)}`;\n}\n\n/**\n * Resolve an MCP tool name back to its `(domain, operation)` gateway key.\n *\n * The reverse of {@link operationToToolName} cannot recover dots vs dashes from\n * the snake_case wire form, so resolution is performed against the provided\n * `exposed` set (the same `mcpExposed: true` subset used to build `tools/list`).\n * This keeps the mapping exact and rejects unknown tool names.\n *\n * @param toolName - The MCP `tools/call` tool name.\n * @param exposed - The exposed operation defs (the `mcpExposed` subset).\n * @returns The matching {@link GatewayOperationKey}, or `undefined` when the\n *   tool name does not correspond to any exposed operation.\n */\nexport function toolNameToOperationKey(\n  toolName: string,\n  exposed: readonly OperationDef[],\n): GatewayOperationKey | undefined {\n  const match = exposed.find((op) => operationToToolName(op) === toolName);\n  return match ? { domain: match.domain, operation: match.operation } : undefined;\n}\n","/**\n * Unified CQRS Dispatch Layer -- Operation Registry (shim)\n *\n * The `OPERATIONS` data array was relocated to\n * `@cleocode/contracts/dispatch/operations-registry` in T10061 / T9833b\n * (E-CLI-BOUNDARY · Saga T9831 SG-ARCH-SOLID). This file is now a thin\n * re-export shim that:\n *\n *   1. Re-exports `OPERATIONS` from contracts so every downstream consumer\n *      that already imports `{ OPERATIONS }` from this path continues to\n *      compile unchanged.\n *   2. Keeps the pure utility / derivation functions (`resolve`,\n *      `validateRequiredParams`, `getByDomain`, etc.) that operate on\n *      the data and are rightly colocated with the CLI package.\n *\n * @epic T4820\n * @task T4814, T5241, T5615, T10061\n */\n\n// OperationDef + Resolution live in @cleocode/contracts (SSoT — promoted in\n// T9954 / Phase 0b of SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION\n// T9832). Imported below for internal use AND re-exported so that every\n// downstream consumer that already imports from './registry.js' continues\n// to compile unchanged.\nimport type { OperationDef, Resolution } from '@cleocode/contracts';\nimport { OPERATIONS as _OPERATIONS } from '@cleocode/contracts';\nimport type { CanonicalDomain, Gateway, Tier } from '@cleocode/contracts/gateway';\n\nexport type { OperationDef, Resolution };\n\n/** The single source of truth for all operations in CLEO (data lives in @cleocode/contracts). */\nexport const OPERATIONS: OperationDef[] = _OPERATIONS;\n\n// ---------------------------------------------------------------------------\n// Gateway Matrix Derivation\n// ---------------------------------------------------------------------------\n\n/**\n * Derive a gateway operation matrix from the registry.\n *\n * Returns `Record<string, string[]>` containing:\n * - All canonical domains with their operations\n *\n * This is the SINGLE derivation point — gateways use this instead of\n * maintaining independent operation lists.\n */\nexport function deriveGatewayMatrix(gateway: Gateway): Record<string, string[]> {\n  const matrix: Record<string, string[]> = {};\n\n  for (const op of OPERATIONS) {\n    if (op.gateway !== gateway) continue;\n    if (!matrix[op.domain]) matrix[op.domain] = [];\n    matrix[op.domain].push(op.operation);\n  }\n\n  return matrix;\n}\n\n/**\n * Get all accepted domain names for a gateway (canonical only).\n */\nexport function getGatewayDomains(gateway: Gateway): string[] {\n  return Object.keys(deriveGatewayMatrix(gateway));\n}\n\n// ---------------------------------------------------------------------------\n// Lookup & Validation\n// ---------------------------------------------------------------------------\n\n/**\n * Resolves a domain + operation to its registered definition.\n */\nexport function resolve(\n  gateway: Gateway,\n  domain: string,\n  operation: string,\n): Resolution | undefined {\n  const def = OPERATIONS.find(\n    (o) => o.gateway === gateway && o.domain === domain && o.operation === operation,\n  );\n\n  if (!def) return undefined;\n\n  return { domain: def.domain, operation: def.operation, def };\n}\n\n/**\n * Validates that all required parameters are present in the request.\n * Returns an array of missing parameter keys.\n */\nexport function validateRequiredParams(\n  def: OperationDef,\n  params?: Record<string, unknown>,\n): string[] {\n  if (!def.requiredParams || def.requiredParams.length === 0) return [];\n  const provided = params || {};\n  // Build a quick lookup so we can honor per-param `allowEmpty` declarations.\n  // When a ParamDef sets `allowEmpty: true`, the empty string `\"\"` is a\n  // valid value rather than \"missing\" — e.g. `provenance.backfill --since \"\"`\n  // walks every reachable tag from the beginning of history.\n  const allowEmptyKeys = new Set<string>();\n  if (def.params) {\n    for (const p of def.params) {\n      if (p.allowEmpty === true) allowEmptyKeys.add(p.name);\n    }\n  }\n  return def.requiredParams.filter((key) => {\n    const v = provided[key];\n    if (v === undefined || v === null) return true;\n    if (v === '' && !allowEmptyKeys.has(key)) return true;\n    return false;\n  });\n}\n\n/** Get all operations for a specific canonical domain. */\nexport function getByDomain(domain: CanonicalDomain): OperationDef[] {\n  return OPERATIONS.filter((o) => o.domain === domain);\n}\n\n/** Get all operations for a specific gateway. */\nexport function getByGateway(gateway: Gateway): OperationDef[] {\n  return OPERATIONS.filter((o) => o.gateway === gateway);\n}\n\n/** Get all operations available at or below a specific tier. */\nexport function getByTier(tier: Tier): OperationDef[] {\n  return OPERATIONS.filter((o) => o.tier <= tier);\n}\n\n/** Get a list of canonical domains that actually have operations registered. */\nexport function getActiveDomains(): CanonicalDomain[] {\n  const active = new Set(OPERATIONS.map((o) => o.domain));\n  return Array.from(active);\n}\n\n/**\n * Returns summary counts of operations for module validation.\n */\nexport function getCounts(): { query: number; mutate: number; total: number } {\n  return {\n    query: OPERATIONS.filter((o) => o.gateway === 'query').length,\n    mutate: OPERATIONS.filter((o) => o.gateway === 'mutate').length,\n    total: OPERATIONS.length,\n  };\n}\n\n// Module load validation (dynamic, no hardcoded operation totals)\nconst counts = getCounts();\nif (counts.total !== OPERATIONS.length) {\n  console.warn(\n    `[Registry] Operation count mismatch: total=${counts.total}, registry=${OPERATIONS.length}`,\n  );\n}\n","/**\n * MCP `tools/list` generation from the OPERATIONS registry.\n *\n * The MCP tool surface is **default-deny**: only {@link OperationDef} entries\n * that explicitly set `mcpExposed: true` are surfaced. This replaces the legacy\n * `@cleocode/mcp-adapter`'s hand-maintained `ALL_TOOLS` array with a single\n * generation point driven by the canonical registry — promoting a new tool is\n * now one `mcpExposed: true` edit in `@cleocode/contracts`, not a fork-and-copy\n * into a standalone adapter.\n *\n * @task T11448\n * @epic T11254\n * @saga T11243\n */\n\nimport type { OperationDef, ParamDef } from '@cleocode/contracts';\nimport { OPERATIONS } from '../registry.js';\nimport { operationToToolName } from './tool-naming.js';\nimport type { McpInputProperty, McpTool } from './types.js';\n\n/**\n * The subset of OPERATIONS surfaced over MCP (default-deny `mcpExposed` filter).\n *\n * @returns Every {@link OperationDef} with `mcpExposed === true`, in registry\n *   order. Empty when no operation opts in.\n */\nexport function exposedOperations(): OperationDef[] {\n  return OPERATIONS.filter((op) => op.mcpExposed === true);\n}\n\n/**\n * Map a JSON-ish {@link ParamDef} type to its JSON Schema primitive.\n *\n * MCP clients consume standard JSON Schema, so `'array'` widens to `'string'`\n * the same way the CLI's citty bridge does (callers split/parse) and every\n * other type passes through unchanged.\n *\n * @param type - The {@link ParamDef} runtime type.\n * @returns The JSON Schema `type` keyword.\n */\nfunction paramTypeToJsonSchema(type: ParamDef['type']): string {\n  return type === 'array' ? 'string' : type;\n}\n\n/**\n * Build the MCP `inputSchema` for a single operation from its `params`.\n *\n * Hidden params (`hidden: true`) are excluded from the public tool surface,\n * matching the JSON Schema generation policy declared on {@link ParamDef}.\n *\n * @param op - The exposed operation definition.\n * @returns A JSON Schema object describing the tool's input.\n */\nfunction buildInputSchema(op: OperationDef): McpTool['inputSchema'] {\n  const properties: Record<string, McpInputProperty> = {};\n  const required: string[] = [];\n\n  for (const param of op.params ?? []) {\n    if (param.hidden === true) continue;\n    const prop: McpInputProperty = {\n      type: paramTypeToJsonSchema(param.type),\n      description: param.description,\n    };\n    if (param.enum !== undefined && param.enum.length > 0) {\n      prop.enum = param.enum;\n    }\n    properties[param.name] = prop;\n    if (param.required) required.push(param.name);\n  }\n\n  const schema: McpTool['inputSchema'] = { type: 'object', properties };\n  if (required.length > 0) schema.required = required;\n  return schema;\n}\n\n/**\n * Convert a single exposed {@link OperationDef} into its MCP tool definition.\n *\n * @param op - An operation with `mcpExposed === true`.\n * @returns The MCP {@link McpTool} (name + description + inputSchema).\n */\nexport function operationToMcpTool(op: OperationDef): McpTool {\n  return {\n    name: operationToToolName(op),\n    description: op.description,\n    inputSchema: buildInputSchema(op),\n  };\n}\n\n/**\n * Generate the full MCP `tools/list` payload from the registry.\n *\n * @returns Every exposed operation rendered as an {@link McpTool}, in registry\n *   order (stable across calls).\n */\nexport function buildToolsList(): McpTool[] {\n  return exposedOperations().map(operationToMcpTool);\n}\n"],"mappings":"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","names":[]}