api-spec-cli 0.2.3 → 0.2.5

package/src/commands/call.js

@@ -1,207 +1,224 @@
-import { readFileSync } from "fs";
-import { out } from "../output.js";
-import { parseArgs, parseKV } from "../args.js";
-import { createMcpClient } from "../mcp-client.js";
-import { resolveSpec, resolveConfig } from "../resolve.js";
-
-const HTTP_TIMEOUT = parseInt(process.env.SPEC_HTTP_TIMEOUT ?? "30000");
-
-export async function callOperation(args) {
-  const { flags, positional } = parseArgs(args);
-  const target = positional[0];
-  if (!target) throw new Error(
-    "Usage: spec call <operation> [--spec <name> | --openapi <url> | ...] [--data '{}' | --data -] [--var k=v] [--header k=v]"
-  );
-
-  if (flags["data-file"] && !flags.data) {
-    flags.data = readFileSync(flags["data-file"], "utf-8").trim();
-  }
-
-  // Read from stdin only when --data - is explicitly passed.
-  // Agents run in non-TTY environments — auto-detecting stdin would add latency on every call.
-  if (flags.data === "-") {
-    const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(chunk);
-    flags.data = Buffer.concat(chunks).toString("utf-8").trim();
-  }
-
-  const { spec, entry } = await resolveSpec(flags);
-  const config = resolveConfig(flags, entry);
-
-  if (spec.type === "openapi") {
-    await callOpenAPI(spec, config, target, flags);
-  } else if (spec.type === "mcp") {
-    await callMCP(spec, entry, target, flags);
-  } else {
-    await callGraphQL(spec, config, target, flags);
-  }
-}
-
-async function callMCP(spec, entry, target, flags) {
-  const tool = spec.tools.find((t) => t.name.toLowerCase() === target.toLowerCase());
-  if (!tool) throw new Error(`Tool not found: ${target}. Run 'spec list' to see available tools.`);
-
-  let toolArgs = {};
-  if (flags.data) {
-    try {
-      toolArgs = JSON.parse(flags.data);
-    } catch {
-      throw new Error("--data must be valid JSON when calling an MCP tool");
-    }
-  }
-  const varOverrides = parseKV(flags.var);
-  toolArgs = { ...toolArgs, ...varOverrides };
-
-  // Re-connect using the original entry (which holds transport config + headers/env)
-  const client = await createMcpClient(entry);
-  try {
-    const result = await client.callTool({ name: tool.name, arguments: toolArgs });
-    // Normalize MCP result: expose isError and content at the top level
-    const isError = result.isError === true;
-    out({ tool: tool.name, arguments: toolArgs, isError, content: result.content, result });
-    if (isError) process.exit(1);
-  } finally {
-    await client.close();
-  }
-}
-
-async function callOpenAPI(spec, config, target, flags) {
-  const lower = target.toLowerCase();
-
-  const op = spec.operations.find((o) =>
-    o.id.toLowerCase() === lower ||
-    o.path.toLowerCase() === lower ||
-    `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
-  );
-
-  if (!op) throw new Error(`Operation not found: ${target}`);
-
-  const baseUrl = config.baseUrl || spec.servers?.[0]?.url || "";
-  let path = op.path;
-
-  const vars = parseKV(flags.var);
-  for (const [key, val] of Object.entries(vars)) {
-    path = path.replaceAll(`{${key}}`, encodeURIComponent(val));
-  }
-
-  // Detect unreplaced path parameters and error clearly
-  const missing = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
-  if (missing.length > 0) {
-    throw new Error(`Missing required path parameters: ${missing.join(", ")}. Pass --var ${missing[0]}=<value>`);
-  }
-
-  const queryParams = parseKV(flags.query);
-  const qs = new URLSearchParams(queryParams).toString();
-  const url = `${baseUrl}${path}${qs ? "?" + qs : ""}`;
-
-  const method = (flags.method || op.method).toUpperCase();
-  const headers = { ...config.headers };
-
-  let body = undefined;
-  if (flags.data) {
-    body = flags.data;
-    if (!headers["Content-Type"]) headers["Content-Type"] = "application/json";
-  }
-
-  const res = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(HTTP_TIMEOUT) });
-  const contentType = res.headers.get("content-type") || "";
-  const responseBody = contentType.includes("json") ? await res.json() : await res.text();
-
-  out({
-    status: res.status,
-    statusText: res.statusText,
-    headers: Object.fromEntries(res.headers.entries()),
-    body: responseBody,
-  });
-}
-
-async function callGraphQL(spec, config, target, flags) {
-  const lower = target.toLowerCase();
-
-  const op = spec.operations.find((o) => o.name.toLowerCase() === lower);
-  if (!op) throw new Error(`Operation not found: ${target}`);
-
-  const endpoint = config.baseUrl || spec.endpoint;
-  if (!endpoint) throw new Error("No GraphQL endpoint. Set --base-url or register with --graphql <url>.");
-
-  let query;
-  let dataVariables;
-  if (flags.data) {
-    try {
-      const parsed = JSON.parse(flags.data);
-      query = parsed.query || flags.data;
-      dataVariables = parsed.variables;
-    } catch {
-      query = flags.data;
-    }
-  } else {
-    query = buildGraphQLQuery(op, spec.types);
-  }
-
-  const varOverrides = parseKV(flags.var);
-  const variables = { ...dataVariables, ...varOverrides };
-
-  const headers = {
-    "Content-Type": "application/json",
-    ...config.headers,
-  };
-
-  const body = JSON.stringify({
-    query,
-    variables: Object.keys(variables).length > 0 ? variables : undefined,
-  });
-
-  const res = await fetch(endpoint, { method: "POST", headers, body, signal: AbortSignal.timeout(HTTP_TIMEOUT) });
-  const contentType = res.headers.get("content-type") || "";
-  const responseBody = contentType.includes("json") ? await res.json() : await res.text();
-
-  out({
-    status: res.status,
-    query,
-    variables: Object.keys(variables).length > 0 ? variables : undefined,
-    data: responseBody?.data || null,
-    errors: responseBody?.errors || null,
-  });
-}
-
-function buildGraphQLQuery(op, types) {
-  const args = op.args || [];
-  const argsStr = args.length > 0
-    ? `(${args.map((a) => `$${a.name}: ${flattenType(a.type)}`).join(", ")})`
-    : "";
-  const passArgs = args.length > 0
-    ? `(${args.map((a) => `${a.name}: $${a.name}`).join(", ")})`
-    : "";
-
-  const returnTypeName = op.returnType?.replace(/[[\]!]/g, "");
-  const returnType = types?.find((t) => t.name === returnTypeName);
-  let fields = "";
-
-  if (returnType?.fields) {
-    const scalarFields = returnType.fields
-      .filter((f) => {
-        const typeName = flattenType(f.type)?.replace(/[[\]!]/g, "");
-        const t = types?.find((tt) => tt.name === typeName);
-        return !t || t.kind === "SCALAR" || t.kind === "ENUM";
-      })
-      .map((f) => f.name);
-
-    if (scalarFields.length > 0) fields = ` { ${scalarFields.join(" ")} }`;
-  }
-
-  const keyword = op.kind === "mutation" ? "mutation" : "query";
-  return `${keyword}${argsStr} { ${op.name}${passArgs}${fields} }`;
-}
-
-function flattenType(t) {
-  if (!t) return null;
-  if (typeof t === "string") return t;
-  if (t.name) return t.kind === "NON_NULL" ? `${t.name}!` : t.name;
-  if (t.ofType) {
-    const inner = flattenType(t.ofType);
-    if (t.kind === "LIST") return `[${inner}]`;
-    if (t.kind === "NON_NULL") return `${inner}!`;
-    return inner;
-  }
-  return t.kind;
-}
+import { readFileSync } from "fs";
+import { out } from "../output.js";
+import { parseArgs, parseKV } from "../args.js";
+import { createMcpClient } from "../mcp-client.js";
+import { resolveSpec, resolveConfig } from "../resolve.js";
+import { recordUsage } from "../usage.js";
+
+const HTTP_TIMEOUT = parseInt(process.env.SPEC_HTTP_TIMEOUT ?? "30000");
+
+export async function callOperation(args) {
+  const { flags, positional } = parseArgs(args);
+  const target = positional[0];
+  if (!target)
+    throw new Error(
+      "Usage: spec call <operation> [--spec <name> | --openapi <url> | ...] [--data '{}' | --data -] [--var k=v] [--header k=v]"
+    );
+
+  if (flags["data-file"] && !flags.data) {
+    flags.data = readFileSync(flags["data-file"], "utf-8").trim();
+  }
+
+  // Read from stdin only when --data - is explicitly passed.
+  // Agents run in non-TTY environments — auto-detecting stdin would add latency on every call.
+  if (flags.data === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    flags.data = Buffer.concat(chunks).toString("utf-8").trim();
+  }
+
+  const { spec, entry } = await resolveSpec(flags);
+  const config = resolveConfig(flags, entry);
+
+  if (spec.type === "openapi") {
+    await callOpenAPI(spec, config, target, flags);
+  } else if (spec.type === "mcp") {
+    await callMCP(spec, entry, target, flags);
+  } else {
+    await callGraphQL(spec, config, target, flags);
+  }
+}
+
+async function callMCP(spec, entry, target, flags) {
+  const tool = spec.tools.find((t) => t.name.toLowerCase() === target.toLowerCase());
+  if (!tool) throw new Error(`Tool not found: ${target}. Run 'spec list' to see available tools.`);
+
+  let toolArgs = {};
+  if (flags.data) {
+    try {
+      toolArgs = JSON.parse(flags.data);
+    } catch {
+      throw new Error("--data must be valid JSON when calling an MCP tool");
+    }
+  }
+  const varOverrides = parseKV(flags.var);
+  toolArgs = { ...toolArgs, ...varOverrides };
+
+  // Re-connect using the original entry (which holds transport config + headers/env)
+  const client = await createMcpClient(entry);
+  try {
+    const result = await client.callTool({ name: tool.name, arguments: toolArgs });
+    // Normalize MCP result: expose isError and content at the top level
+    const isError = result.isError === true;
+    out({ tool: tool.name, arguments: toolArgs, isError, content: result.content, result });
+    recordUsage(flags.spec, tool.name);
+    if (isError) process.exit(1);
+  } finally {
+    await client.close();
+  }
+}
+
+async function callOpenAPI(spec, config, target, flags) {
+  const lower = target.toLowerCase();
+
+  const op = spec.operations.find(
+    (o) =>
+      o.id.toLowerCase() === lower ||
+      o.path.toLowerCase() === lower ||
+      `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
+  );
+
+  if (!op) throw new Error(`Operation not found: ${target}`);
+
+  const baseUrl = config.baseUrl || spec.servers?.[0]?.url || "";
+  let path = op.path;
+
+  const vars = parseKV(flags.var);
+  for (const [key, val] of Object.entries(vars)) {
+    path = path.replaceAll(`{${key}}`, encodeURIComponent(val));
+  }
+
+  // Detect unreplaced path parameters and error clearly
+  const missing = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required path parameters: ${missing.join(", ")}. Pass --var ${missing[0]}=<value>`
+    );
+  }
+
+  const queryParams = parseKV(flags.query);
+  const qs = new URLSearchParams(queryParams).toString();
+  const url = `${baseUrl}${path}${qs ? "?" + qs : ""}`;
+
+  const method = (flags.method || op.method).toUpperCase();
+  const headers = { ...config.headers };
+
+  let body = undefined;
+  if (flags.data) {
+    body = flags.data;
+    if (!headers["Content-Type"]) headers["Content-Type"] = "application/json";
+  }
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body,
+    signal: AbortSignal.timeout(HTTP_TIMEOUT),
+  });
+  const contentType = res.headers.get("content-type") || "";
+  const responseBody = contentType.includes("json") ? await res.json() : await res.text();
+
+  out({
+    status: res.status,
+    statusText: res.statusText,
+    headers: Object.fromEntries(res.headers.entries()),
+    body: responseBody,
+  });
+  recordUsage(flags.spec, op.id);
+}
+
+async function callGraphQL(spec, config, target, flags) {
+  const lower = target.toLowerCase();
+
+  const op = spec.operations.find((o) => o.name.toLowerCase() === lower);
+  if (!op) throw new Error(`Operation not found: ${target}`);
+
+  const endpoint = config.baseUrl || spec.endpoint;
+  if (!endpoint)
+    throw new Error("No GraphQL endpoint. Set --base-url or register with --graphql <url>.");
+
+  let query;
+  let dataVariables;
+  if (flags.data) {
+    try {
+      const parsed = JSON.parse(flags.data);
+      query = parsed.query || flags.data;
+      dataVariables = parsed.variables;
+    } catch {
+      query = flags.data;
+    }
+  } else {
+    query = buildGraphQLQuery(op, spec.types);
+  }
+
+  const varOverrides = parseKV(flags.var);
+  const variables = { ...dataVariables, ...varOverrides };
+
+  const headers = {
+    "Content-Type": "application/json",
+    ...config.headers,
+  };
+
+  const body = JSON.stringify({
+    query,
+    variables: Object.keys(variables).length > 0 ? variables : undefined,
+  });
+
+  const res = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body,
+    signal: AbortSignal.timeout(HTTP_TIMEOUT),
+  });
+  const contentType = res.headers.get("content-type") || "";
+  const responseBody = contentType.includes("json") ? await res.json() : await res.text();
+
+  out({
+    status: res.status,
+    query,
+    variables: Object.keys(variables).length > 0 ? variables : undefined,
+    data: responseBody?.data || null,
+    errors: responseBody?.errors || null,
+  });
+  recordUsage(flags.spec, op.name);
+}
+
+function buildGraphQLQuery(op, types) {
+  const args = op.args || [];
+  const argsStr =
+    args.length > 0 ? `(${args.map((a) => `$${a.name}: ${flattenType(a.type)}`).join(", ")})` : "";
+  const passArgs =
+    args.length > 0 ? `(${args.map((a) => `${a.name}: $${a.name}`).join(", ")})` : "";
+
+  const returnTypeName = op.returnType?.replace(/[[\]!]/g, "");
+  const returnType = types?.find((t) => t.name === returnTypeName);
+  let fields = "";
+
+  if (returnType?.fields) {
+    const scalarFields = returnType.fields
+      .filter((f) => {
+        const typeName = flattenType(f.type)?.replace(/[[\]!]/g, "");
+        const t = types?.find((tt) => tt.name === typeName);
+        return !t || t.kind === "SCALAR" || t.kind === "ENUM";
+      })
+      .map((f) => f.name);
+
+    if (scalarFields.length > 0) fields = ` { ${scalarFields.join(" ")} }`;
+  }
+
+  const keyword = op.kind === "mutation" ? "mutation" : "query";
+  return `${keyword}${argsStr} { ${op.name}${passArgs}${fields} }`;
+}
+
+function flattenType(t) {
+  if (!t) return null;
+  if (typeof t === "string") return t;
+  if (t.name) return t.kind === "NON_NULL" ? `${t.name}!` : t.name;
+  if (t.ofType) {
+    const inner = flattenType(t.ofType);
+    if (t.kind === "LIST") return `[${inner}]`;
+    if (t.kind === "NON_NULL") return `${inner}!`;
+    return inner;
+  }
+  return t.kind;
+}

package/src/commands/fetch.js

@@ -62,8 +62,10 @@ fragment TypeRef on __Type {
 
 function applyFilter(items, nameFn, allowed, disabled) {
   let result = items;
-  if (allowed?.length) result = result.filter((item) => allowed.some((p) => matchFilter(p, nameFn(item))));
-  if (disabled?.length) result = result.filter((item) => !disabled.some((p) => matchFilter(p, nameFn(item))));
+  if (allowed?.length)
+    result = result.filter((item) => allowed.some((p) => matchFilter(p, nameFn(item))));
+  if (disabled?.length)
+    result = result.filter((item) => !disabled.some((p) => matchFilter(p, nameFn(item))));
   return result;
 }
 
@@ -72,23 +74,33 @@ function applyFilter(items, nameFn, allowed, disabled) {
  * Entry shape:
  *   { type: "openapi", source: "<url-or-file>", config: { headers, auth } }
  *   { type: "graphql", source: "<url>", config: { headers, auth } }
- *   { type: "mcp", transport: "stdio|sse|streamable-http", url?, command?, args?, config: { headers, env } }
+ *   { _section: "mcp", type: "stdio"|"sse"|"http", url?, command?, args?, env?, headers? }
  */
 export async function fetchSpec(entry) {
-  if (entry.type === "mcp") return await loadMCPFromEntry(entry);
-  if (entry.type === "graphql") {
+  if (entry._section === "mcp") return await loadMCPFromEntry(entry);
+  if (entry._section === "graphql") {
     const spec = await loadGraphQL(entry.source, entry.config?.headers);
     return {
       ...spec,
-      operations: applyFilter(spec.operations, (op) => op.name, entry.config?.allowedTools, entry.config?.disabledTools),
+      operations: applyFilter(
+        spec.operations,
+        (op) => op.name,
+        entry.config?.allowedTools,
+        entry.config?.disabledTools
+      ),
     };
   }
-  // openapi — url or file; skip GraphQL probe since type is explicitly declared
+  // openapi
   const isUrl = entry.source?.startsWith("http://") || entry.source?.startsWith("https://");
   const spec = isUrl ? await loadFromUrl(entry.source, true) : loadFromFile(entry.source);
   return {
     ...spec,
-    operations: applyFilter(spec.operations, (op) => op.id, entry.config?.allowedTools, entry.config?.disabledTools),
+    operations: applyFilter(
+      spec.operations,
+      (op) => op.id,
+      entry.config?.allowedTools,
+      entry.config?.disabledTools
+    ),
   };
 }
 
@@ -106,38 +118,61 @@ export function inlineEntryFromFlags(flags) {
 
   if (flags["mcp-stdio"]) {
     const raw = flags["mcp-stdio"];
-    const parts = (raw.trim() ? raw.match(/(?:[^\s"]+|"[^"]*")+/g) : null)?.map((p) => p.replace(/^"|"$/g, ""));
+    const parts = (raw.trim() ? raw.match(/(?:[^\s"]+|"[^"]*")+/g) : null)?.map((p) =>
+      p.replace(/^"|"$/g, "")
+    );
     if (!parts?.length) throw new Error("--mcp-stdio requires a non-empty command string");
     return {
-      type: "mcp",
-      transport: "stdio",
+      _section: "mcp",
+      type: "stdio",
       command: parts[0],
       args: parts.slice(1),
       cwd: flags.cwd,
-      config: { env: parseKV(flags.env), ...filterConfig },
+      env: parseKV(flags.env),
+      ...filterConfig,
     };
   }
   if (flags["mcp-sse"]) {
+    const headers = parseKV(flags.header);
+    if (flags.auth && !headers["Authorization"]) headers["Authorization"] = `Bearer ${flags.auth}`;
     return {
-      type: "mcp",
-      transport: "sse",
+      _section: "mcp",
+      type: "sse",
       url: flags["mcp-sse"],
-      config: { headers: parseKV(flags.header), ...filterConfig },
+      ...(Object.keys(headers).length ? { headers } : {}),
+      ...filterConfig,
     };
   }
   if (flags["mcp-http"]) {
+    const headers = parseKV(flags.header);
+    if (flags.auth && !headers["Authorization"]) headers["Authorization"] = `Bearer ${flags.auth}`;
     return {
-      type: "mcp",
-      transport: "streamable-http",
+      _section: "mcp",
+      type: "http",
       url: flags["mcp-http"],
-      config: { headers: parseKV(flags.header), ...filterConfig },
+      ...(Object.keys(headers).length ? { headers } : {}),
+      ...filterConfig,
     };
   }
   if (flags.graphql) {
-    return { type: "graphql", source: flags.graphql, config: { headers: parseKV(flags.header), ...filterConfig } };
+    return {
+      _section: "graphql",
+      type: "graphql",
+      source: flags.graphql,
+      config: { headers: parseKV(flags.header), ...filterConfig },
+    };
   }
   if (flags.openapi) {
-    return { type: "openapi", source: flags.openapi, config: { headers: parseKV(flags.header), baseUrl: flags["base-url"] || null, ...filterConfig } };
+    return {
+      _section: "openapi",
+      type: "openapi",
+      source: flags.openapi,
+      config: {
+        headers: parseKV(flags.header),
+        baseUrl: flags["base-url"] || null,
+        ...filterConfig,
+      },
+    };
   }
   return null;
 }
@@ -154,17 +189,16 @@ async function loadMCPFromEntry(entry) {
       inputSchema: t.inputSchema || null,
     }));
 
-    mapped = applyFilter(mapped, (t) => t.name, entry.config?.allowedTools, entry.config?.disabledTools);
+    mapped = applyFilter(mapped, (t) => t.name, entry.allowedTools, entry.disabledTools);
 
     return {
       type: "mcp",
       title: entry.name || "MCP Server",
-      transport: entry.transport,
+      transport: entry.type,
       url: entry.url,
       command: entry.command,
       args: entry.args,
       cwd: entry.cwd,
-      config: entry.config,
       tools: mapped,
     };
   } finally {
@@ -175,9 +209,7 @@ async function loadMCPFromEntry(entry) {
 async function loadFromUrl(url, skipGraphQLProbe = false) {
   const lowerUrl = url.toLowerCase();
   const isLikelyFile =
-    lowerUrl.endsWith(".json") ||
-    lowerUrl.endsWith(".yaml") ||
-    lowerUrl.endsWith(".yml");
+    lowerUrl.endsWith(".json") || lowerUrl.endsWith(".yaml") || lowerUrl.endsWith(".yml");
 
   if (!isLikelyFile && !skipGraphQLProbe) {
     try {
@@ -288,7 +320,11 @@ function parseOpenAPI(text, source) {
     version,
     title: doc.info?.title || null,
     description: doc.info?.description || null,
-    servers: doc.servers || (doc.host ? [{ url: `${doc.schemes?.[0] || "https"}://${doc.host}${doc.basePath || ""}` }] : []),
+    servers:
+      doc.servers ||
+      (doc.host
+        ? [{ url: `${doc.schemes?.[0] || "https"}://${doc.host}${doc.basePath || ""}` }]
+        : []),
     operations,
     components: doc.components || doc.definitions || {},
     raw: doc,