api-spec-cli 0.1.2 → 0.2.0

package/src/commands/call.js

@@ -1,38 +1,36 @@
 import { readFileSync } from "fs";
-import { getSpec, getConfig } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs, parseKV } from "../args.js";
 import { createMcpClient } from "../mcp-client.js";
+import { resolveActiveSpec, resolveConfig } from "../resolve.js";
 
 export async function callOperation(args) {
   const { flags, positional } = parseArgs(args);
   const target = positional[0];
-  if (!target) throw new Error("Usage: spec call <operationId-or-path> [--data '{}'] [--data-file path.json] [--query k=v] [--header k=v] [--var k=v] [--method GET]");
+  if (!target) throw new Error(
+    "Usage: spec call <operation> [--spec <name> | --openapi <url> | ...] [--data '{}'] [--var k=v] [--header k=v]"
+  );
 
-  // Support --data-file to avoid shell escaping issues
   if (flags["data-file"] && !flags.data) {
     flags.data = readFileSync(flags["data-file"], "utf-8").trim();
   }
 
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
-
-  const config = getConfig();
+  const { spec, entry } = await resolveActiveSpec(flags);
+  const config = resolveConfig(flags, entry);
 
   if (spec.type === "openapi") {
     await callOpenAPI(spec, config, target, flags);
   } else if (spec.type === "mcp") {
-    await callMCP(spec, target, flags);
+    await callMCP(spec, entry, target, flags);
   } else {
     await callGraphQL(spec, config, target, flags);
   }
 }
 
-async function callMCP(spec, 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.`);
 
-  // Build arguments: --data for full JSON object, --var for individual keys
   let toolArgs = {};
   if (flags.data) {
     try {
@@ -41,11 +39,11 @@ async function callMCP(spec, target, flags) {
       throw new Error("--data must be valid JSON when calling an MCP tool");
     }
   }
-  // --var key=value overrides / extends --data args
   const varOverrides = parseKV(flags.var);
   toolArgs = { ...toolArgs, ...varOverrides };
 
-  const client = await createMcpClient(spec);
+  // 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 });
     out({ tool: tool.name, arguments: toolArgs, result });
@@ -57,67 +55,38 @@ async function callMCP(spec, target, flags) {
 async function callOpenAPI(spec, config, target, flags) {
   const lower = target.toLowerCase();
 
-  const op = spec.operations.find((o) => {
-    return (
-      o.id.toLowerCase() === lower ||
-      o.path.toLowerCase() === lower ||
-      `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
-    );
-  });
+  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}`);
 
-  // Build URL
   const baseUrl = config.baseUrl || spec.servers?.[0]?.url || "";
   let path = op.path;
 
-  // Substitute path variables
   const vars = parseKV(flags.var);
   for (const [key, val] of Object.entries(vars)) {
     path = path.replace(`{${key}}`, encodeURIComponent(val));
   }
 
-  // Query params
   const queryParams = parseKV(flags.query);
   const qs = new URLSearchParams(queryParams).toString();
   const url = `${baseUrl}${path}${qs ? "?" + qs : ""}`;
 
-  // Method
   const method = (flags.method || op.method).toUpperCase();
+  const headers = { ...config.headers };
 
-  // Headers
-  const headers = {
-    ...config.headers,
-    ...parseKV(flags.header),
-  };
-
-  // Auth
-  if (config.auth) {
-    if (config.auth.startsWith("Bearer ") || config.auth.startsWith("Basic ")) {
-      headers["Authorization"] = config.auth;
-    } else {
-      headers["Authorization"] = `Bearer ${config.auth}`;
-    }
-  }
-
-  // Body
   let body = undefined;
   if (flags.data) {
     body = flags.data;
-    if (!headers["Content-Type"]) {
-      headers["Content-Type"] = "application/json";
-    }
+    if (!headers["Content-Type"]) headers["Content-Type"] = "application/json";
   }
 
   const res = await fetch(url, { method, headers, body });
   const contentType = res.headers.get("content-type") || "";
-  let responseBody;
-
-  if (contentType.includes("json")) {
-    responseBody = await res.json();
-  } else {
-    responseBody = await res.text();
-  }
+  const responseBody = contentType.includes("json") ? await res.json() : await res.text();
 
   out({
     status: res.status,
@@ -133,14 +102,12 @@ async function callGraphQL(spec, config, target, flags) {
   const op = spec.operations.find((o) => o.name.toLowerCase() === lower);
   if (!op) throw new Error(`Operation not found: ${target}`);
 
-  const endpoint = spec.endpoint;
-  if (!endpoint) throw new Error("No GraphQL endpoint set");
+  const endpoint = config.baseUrl || spec.endpoint;
+  if (!endpoint) throw new Error("No GraphQL endpoint. Set --base-url or register with --graphql <url>.");
 
-  // Build query from operation
   let query;
   let dataVariables;
   if (flags.data) {
-    // If --data is provided, treat as raw GraphQL query
     try {
       const parsed = JSON.parse(flags.data);
       query = parsed.query || flags.data;
@@ -149,34 +116,23 @@ async function callGraphQL(spec, config, target, flags) {
       query = flags.data;
     }
   } else {
-    // Auto-build a simple query/mutation
     query = buildGraphQLQuery(op, spec.types);
   }
 
-  // Variables: --data variables merged with --var overrides
   const varOverrides = parseKV(flags.var);
   const variables = { ...dataVariables, ...varOverrides };
 
   const headers = {
     "Content-Type": "application/json",
     ...config.headers,
-    ...parseKV(flags.header),
   };
 
-  if (config.auth) {
-    if (config.auth.startsWith("Bearer ") || config.auth.startsWith("Basic ")) {
-      headers["Authorization"] = config.auth;
-    } else {
-      headers["Authorization"] = `Bearer ${config.auth}`;
-    }
-  }
-
   const body = JSON.stringify({
     query,
     variables: Object.keys(variables).length > 0 ? variables : undefined,
   });
 
-  const res = await fetch(config.baseUrl || endpoint, { method: "POST", headers, body });
+  const res = await fetch(endpoint, { method: "POST", headers, body });
   const responseBody = await res.json();
 
   out({
@@ -193,18 +149,15 @@ function buildGraphQLQuery(op, types) {
   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(", ")})`
     : "";
 
-  // Try to build a field selection from the return type
   const returnTypeName = op.returnType?.replace(/[[\]!]/g, "");
   const returnType = types?.find((t) => t.name === returnTypeName);
   let fields = "";
 
   if (returnType?.fields) {
-    // Select scalar fields only (1 level deep)
     const scalarFields = returnType.fields
       .filter((f) => {
         const typeName = flattenType(f.type)?.replace(/[[\]!]/g, "");
@@ -213,9 +166,7 @@ function buildGraphQLQuery(op, types) {
       })
       .map((f) => f.name);
 
-    if (scalarFields.length > 0) {
-      fields = ` { ${scalarFields.join(" ")} }`;
-    }
+    if (scalarFields.length > 0) fields = ` { ${scalarFields.join(" ")} }`;
   }
 
   const keyword = op.kind === "mutation" ? "mutation" : "query";

package/src/commands/list.js

@@ -1,22 +1,27 @@
-import { getSpec } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
+import { resolveActiveSpec } from "../resolve.js";
 
 export async function listOperations(args) {
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
-
   const opts = parseArgs(args);
-  const filter = opts.flags.filter?.toLowerCase();
-  const compact = opts.flags.compact !== "false"; // compact by default
-  const limit = parseInt(opts.flags.limit) || 0;
-  const offset = parseInt(opts.flags.offset) || 0;
-  const tag = opts.flags.tag?.toLowerCase();
+  const { flags } = opts;
+
+  const { spec } = await resolveActiveSpec(flags);
+
+  const filter = flags.filter?.toLowerCase();
+  const compact = flags.compact !== "false";
+  const limit = parseInt(flags.limit) || 0;
+  const offset = parseInt(flags.offset) || 0;
+  const tag = flags.tag?.toLowerCase();
 
   let operations;
 
   if (spec.type === "openapi") {
-    operations = spec.operations.map((op) =>
+    let source = spec.operations;
+    if (tag) {
+      source = source.filter((op) => op.tags?.some((t) => t.toLowerCase().includes(tag)));
+    }
+    operations = source.map((op) =>
       compact
         ? { id: op.id, method: op.method, path: op.path }
         : {
@@ -28,14 +33,6 @@ export async function listOperations(args) {
             deprecated: op.deprecated,
           }
     );
-
-    // Filter by tag
-    if (tag) {
-      const fullOps = spec.operations;
-      operations = operations.filter((_, i) =>
-        fullOps[i].tags?.some((t) => t.toLowerCase().includes(tag))
-      );
-    }
   } else if (spec.type === "mcp") {
     operations = spec.tools.map((t) =>
       compact
@@ -57,28 +54,21 @@ export async function listOperations(args) {
           }
     );
 
-    // Filter by kind (query/mutation/subscription)
     if (tag) {
       operations = operations.filter((op) => op.kind === tag);
     }
   }
 
   if (filter) {
-    operations = operations.filter((op) => {
-      const text = JSON.stringify(op).toLowerCase();
-      return text.includes(filter);
-    });
+    operations = operations.filter((op) =>
+      JSON.stringify(op).toLowerCase().includes(filter)
+    );
   }
 
   const total = operations.length;
 
-  // Pagination
-  if (offset > 0) {
-    operations = operations.slice(offset);
-  }
-  if (limit > 0) {
-    operations = operations.slice(0, limit);
-  }
+  if (offset > 0) operations = operations.slice(offset);
+  if (limit > 0)  operations = operations.slice(0, limit);
 
   out({
     type: spec.type,

package/src/commands/load.js

@@ -1,9 +1,7 @@
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import YAML from "yaml";
-import { saveSpec } from "../store.js";
-import { out, err } from "../output.js";
-import { parseArgs } from "../args.js";
+import { parseKV } from "../args.js";
 import { createMcpClient } from "../mcp-client.js";
 
 const INTROSPECTION_QUERY = `{
@@ -61,78 +59,77 @@ fragment TypeRef on __Type {
   }
 }`;
 
-export async function loadSpec(args) {
-  const { flags, positional } = parseArgs(args);
-
-  // MCP transport flags
-  if (flags["mcp-stdio"] || flags["mcp-sse"] || flags["mcp-http"]) {
-    const spec = await loadMCP(flags);
-    saveSpec(spec);
-    out({
-      ok: true,
-      type: "mcp",
-      title: spec.title,
-      transport: spec.transport,
-      toolCount: spec.tools.length,
-    });
-    return;
-  }
-
-  const source = positional[0];
-  if (!source) throw new Error("Usage: spec load <file-or-url>  |  spec load --mcp-stdio <cmd>  |  spec load --mcp-sse <url>  |  spec load --mcp-http <url>");
-
-  // Detect if it's a URL or file
-  const isUrl = source.startsWith("http://") || source.startsWith("https://");
-
-  let spec;
-
-  if (isUrl) {
-    spec = await loadFromUrl(source);
-  } else {
-    spec = loadFromFile(source);
-  }
-
-  saveSpec(spec);
-  out({
-    ok: true,
-    type: spec.type,
-    title: spec.title || null,
-    operationCount: countOperations(spec),
-    source: source,
-  });
+/**
+ * Resolve a spec from a registry entry or inline flags entry.
+ * 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 } }
+ */
+export async function resolveSpec(entry) {
+  if (entry.type === "mcp") return await loadMCPFromEntry(entry);
+  if (entry.type === "graphql") return await loadGraphQL(entry.source, entry.config?.headers);
+  // openapi — url or file; skip GraphQL probe since type is explicitly declared
+  const isUrl = entry.source?.startsWith("http://") || entry.source?.startsWith("https://");
+  return isUrl ? await loadFromUrl(entry.source, true) : loadFromFile(entry.source);
 }
 
-async function loadMCP(flags) {
-  let transportConfig;
-
+/**
+ * Build an inline entry from flags (for ad-hoc commands like --mcp-http <url>).
+ * Returns null if no inline source flags present.
+ */
+export function inlineEntryFromFlags(flags) {
   if (flags["mcp-stdio"]) {
     const raw = flags["mcp-stdio"];
-    // Split on whitespace, respecting that the value is already a single flag string
-    const parts = raw.match(/(?:[^\s"]+|"[^"]*")+/g).map((p) => p.replace(/^"|"$/g, ""));
-    transportConfig = {
+    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",
       command: parts[0],
       args: parts.slice(1),
+      config: { env: parseKV(flags.env) },
     };
-  } else if (flags["mcp-sse"]) {
-    transportConfig = {
+  }
+  if (flags["mcp-sse"]) {
+    return {
+      type: "mcp",
       transport: "sse",
       url: flags["mcp-sse"],
+      config: { headers: parseKV(flags.header) },
     };
-  } else {
-    transportConfig = {
+  }
+  if (flags["mcp-http"]) {
+    return {
+      type: "mcp",
       transport: "streamable-http",
       url: flags["mcp-http"],
+      config: { headers: parseKV(flags.header) },
     };
   }
+  if (flags.graphql) {
+    return { type: "graphql", source: flags.graphql, config: { headers: parseKV(flags.header) } };
+  }
+  if (flags.openapi) {
+    return { type: "openapi", source: flags.openapi, config: { headers: parseKV(flags.header), baseUrl: flags["base-url"] || null } };
+  }
+  return null;
+}
+
+// --- Internal loaders ---
 
-  const client = await createMcpClient(transportConfig);
+async function loadMCPFromEntry(entry) {
+  const client = await createMcpClient(entry);
   try {
     const { tools } = await client.listTools();
     return {
       type: "mcp",
-      title: "MCP Server",
-      ...transportConfig,
+      title: entry.name || "MCP Server",
+      transport: entry.transport,
+      url: entry.url,
+      command: entry.command,
+      args: entry.args,
+      config: entry.config,
       tools: tools.map((t) => ({
         name: t.name,
         description: t.description || null,
@@ -144,24 +141,21 @@ async function loadMCP(flags) {
   }
 }
 
-async function loadFromUrl(url) {
-  // Try GraphQL introspection first if URL doesn't end with known extensions
+async function loadFromUrl(url, skipGraphQLProbe = false) {
   const lowerUrl = url.toLowerCase();
   const isLikelyFile =
     lowerUrl.endsWith(".json") ||
     lowerUrl.endsWith(".yaml") ||
     lowerUrl.endsWith(".yml");
 
-  if (!isLikelyFile) {
-    // Try GraphQL introspection
+  if (!isLikelyFile && !skipGraphQLProbe) {
     try {
       return await loadGraphQL(url);
-    } catch (e) {
+    } catch {
       // Fall through to OpenAPI
     }
   }
 
-  // Fetch as OpenAPI
   const res = await fetch(url);
   if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
   const text = await res.text();
@@ -175,10 +169,10 @@ function loadFromFile(path) {
   return parseOpenAPI(text, path);
 }
 
-async function loadGraphQL(url) {
+async function loadGraphQL(url, extraHeaders = {}) {
   const res = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...extraHeaders },
     body: JSON.stringify({ query: INTROSPECTION_QUERY }),
   });
 
@@ -190,8 +184,6 @@ async function loadGraphQL(url) {
   }
 
   const schema = json.data.__schema;
-
-  // Extract operations from query/mutation/subscription types
   const operations = [];
   const typeMap = {};
   for (const t of schema.types) {
@@ -237,7 +229,6 @@ function parseOpenAPI(text, source) {
     doc = YAML.parse(text);
   }
 
-  // Detect OpenAPI vs Swagger
   const version = doc.openapi || doc.swagger;
   if (!version) throw new Error("Not a valid OpenAPI/Swagger spec");
 
@@ -284,7 +275,3 @@ function flattenType(t) {
   }
   return t.kind;
 }
-
-function countOperations(spec) {
-  return spec.operations?.length || 0;
-}