api-spec-cli 0.1.2 → 0.2.0

package/src/commands/show.js

@@ -1,14 +1,13 @@
-import { getSpec } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
+import { resolveActiveSpec } from "../resolve.js";
 
 export async function showOperation(args) {
-  const { positional } = parseArgs(args);
+  const { flags, positional } = parseArgs(args);
   const target = positional[0];
-  if (!target) throw new Error("Usage: spec show <operationId-or-path>");
+  if (!target) throw new Error("Usage: spec show <operationId-or-path> [--spec <name> | --openapi <url> | ...]");
 
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
+  const { spec } = await resolveActiveSpec(flags);
 
   if (spec.type === "openapi") {
     showOpenAPI(spec, target);
@@ -22,13 +21,11 @@ export async function showOperation(args) {
 function showOpenAPI(spec, target) {
   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}. Run 'spec list' to see available operations.`);
@@ -61,6 +58,18 @@ function showOpenAPI(spec, target) {
   });
 }
 
+function showMCP(spec, target) {
+  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.`);
+  }
+  out({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  });
+}
+
 function showGraphQL(spec, target) {
   const lower = target.toLowerCase();
 
@@ -89,18 +98,6 @@ function showGraphQL(spec, target) {
   });
 }
 
-function showMCP(spec, target) {
-  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.`);
-  }
-  out({
-    name: tool.name,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-  });
-}
-
 // --- Helpers ---
 
 function resolveRef(obj, root) {
@@ -108,9 +105,7 @@ function resolveRef(obj, root) {
   if (obj.$ref) {
     const path = obj.$ref.replace("#/", "").split("/");
     let resolved = root;
-    for (const p of path) {
-      resolved = resolved?.[p];
-    }
+    for (const p of path) resolved = resolved?.[p];
     return resolved || obj;
   }
   return obj;
@@ -120,7 +115,6 @@ function resolveRequestBody(body, root) {
   if (!body) return null;
   const resolved = resolveRef(body, root);
   if (resolved?.content) {
-    // Only show application/json if available (most useful for agents)
     const jsonContent = resolved.content["application/json"];
     if (jsonContent) {
       return {
@@ -129,7 +123,6 @@ function resolveRequestBody(body, root) {
         schema: resolveSchema(jsonContent.schema, root),
       };
     }
-    // Fallback: show first content type
     const [mediaType, value] = Object.entries(resolved.content)[0];
     return {
       description: resolved.description || undefined,
@@ -141,7 +134,6 @@ function resolveRequestBody(body, root) {
   return resolved;
 }
 
-// Only show success response schema — agent doesn't need error schemas to make a call
 function resolveResponsesCompact(responses, root) {
   if (!responses) return null;
   const result = {};
@@ -149,14 +141,9 @@ function resolveResponsesCompact(responses, root) {
     const resolved = resolveRef(resp, root);
     if (resolved?.content) {
       const jsonContent = resolved.content["application/json"];
-      if (jsonContent) {
-        result[code] = {
-          description: resolved.description,
-          schema: resolveSchema(jsonContent.schema, root),
-        };
-      } else {
-        result[code] = { description: resolved.description };
-      }
+      result[code] = jsonContent
+        ? { description: resolved.description, schema: resolveSchema(jsonContent.schema, root) }
+        : { description: resolved.description };
     } else {
       result[code] = { description: resolved.description };
     }
@@ -166,18 +153,12 @@ function resolveResponsesCompact(responses, root) {
 
 function resolveSchema(schema, root, depth = 0) {
   if (!schema || depth > 3) return schema;
-  if (schema.$ref) {
-    const resolved = resolveRef(schema, root);
-    // Resolve one more level for the top-level ref
-    return resolveSchema(resolved, root, depth + 1);
-  }
+  if (schema.$ref) return resolveSchema(resolveRef(schema, root), root, depth + 1);
   if (schema.properties) {
-    const result = { type: schema.type, required: schema.required };
-    result.properties = {};
+    const result = { type: schema.type, required: schema.required, properties: {} };
     for (const [key, val] of Object.entries(schema.properties)) {
       if (val.$ref) {
-        const refName = val.$ref.split("/").pop();
-        result.properties[key] = { $ref: refName };
+        result.properties[key] = { $ref: val.$ref.split("/").pop() };
       } else if (val.type === "array" && val.items?.$ref) {
         result.properties[key] = { type: "array", items: val.items.$ref.split("/").pop() };
       } else {
@@ -191,9 +172,7 @@ function resolveSchema(schema, root, depth = 0) {
     return result;
   }
   if (schema.items) {
-    if (schema.items.$ref) {
-      return { type: "array", items: schema.items.$ref.split("/").pop() };
-    }
+    if (schema.items.$ref) return { type: "array", items: schema.items.$ref.split("/").pop() };
     return { type: "array", items: resolveSchema(schema.items, root, depth + 1) };
   }
   return schema;
@@ -209,30 +188,16 @@ function findRelatedTypes(op, types) {
   }
 
   extractTypeNames(op.returnType);
-  for (const arg of op.args || []) {
-    extractTypeNames(flattenType(arg.type));
-  }
+  for (const arg of op.args || []) extractTypeNames(flattenType(arg.type));
 
   const scalars = new Set(["String", "Int", "Float", "Boolean", "ID"]);
   return types
     .filter((t) => names.has(t.name) && !scalars.has(t.name))
     .map((t) => {
       const result = { name: t.name, kind: t.kind };
-      if (t.fields) {
-        result.fields = t.fields.map((f) => ({
-          name: f.name,
-          type: flattenType(f.type),
-        }));
-      }
-      if (t.inputFields) {
-        result.inputFields = t.inputFields.map((f) => ({
-          name: f.name,
-          type: flattenType(f.type),
-        }));
-      }
-      if (t.enumValues) {
-        result.enumValues = t.enumValues.map((e) => e.name);
-      }
+      if (t.fields) result.fields = t.fields.map((f) => ({ name: f.name, type: flattenType(f.type) }));
+      if (t.inputFields) result.inputFields = t.inputFields.map((f) => ({ name: f.name, type: flattenType(f.type) }));
+      if (t.enumValues) result.enumValues = t.enumValues.map((e) => e.name);
       return result;
     });
 }

package/src/commands/specs.js

@@ -0,0 +1,69 @@
+import { parseArgs } from "../args.js";
+import { getRegistry, saveRegistry, getEntry, removeCachedSpec, saveCachedSpec } from "../registry.js";
+import { resolveSpec } from "./load.js";
+import { out } from "../output.js";
+
+export async function specsCmd(args) {
+  const { flags } = parseArgs(args);
+  const compact = flags.compact !== "false";
+  const registry = getRegistry();
+
+  const specs = registry.map((e) => {
+    if (compact) {
+      return {
+        name: e.name,
+        type: e.type,
+        transport: e.transport,
+        description: e.description || null,
+        enabled: e.enabled,
+      };
+    }
+    return e;
+  });
+
+  out({ specs });
+}
+
+export async function registryMutate(action, args) {
+  const { positional } = parseArgs(args);
+  const name = positional[0];
+  if (!name) throw new Error(`Usage: spec ${action} <name>`);
+
+  const registry = getRegistry();
+  const idx = registry.findIndex((e) => e.name === name);
+  if (idx === -1) throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
+
+  if (action === "remove") {
+    registry.splice(idx, 1);
+    saveRegistry(registry);
+    removeCachedSpec(name);
+    out({ ok: true, removed: name });
+    return;
+  }
+
+  if (action === "enable") {
+    registry[idx].enabled = true;
+    saveRegistry(registry);
+    out({ ok: true, enabled: name });
+    return;
+  }
+
+  if (action === "disable") {
+    registry[idx].enabled = false;
+    saveRegistry(registry);
+    out({ ok: true, disabled: name });
+    return;
+  }
+
+  if (action === "refresh") {
+    const entry = registry[idx];
+    if (!entry.enabled) throw new Error(`Spec '${name}' is disabled. Enable it first.`);
+    const spec = await resolveSpec(entry);
+    saveCachedSpec(name, spec);
+    const count = spec.tools?.length ?? spec.operations?.length ?? 0;
+    out({ ok: true, refreshed: name, type: spec.type, count });
+    return;
+  }
+
+  throw new Error(`Unknown registry action: ${action}`);
+}

package/src/commands/types.js

@@ -1,12 +1,10 @@
-import { getSpec } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
+import { resolveActiveSpec } from "../resolve.js";
 
 export async function typesCmd(args) {
-  const spec = getSpec();
-  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
-
   const { positional, flags } = parseArgs(args);
+  const { spec } = await resolveActiveSpec(flags);
   const target = positional[0];
 
   if (spec.type === "openapi") {

package/src/mcp-client.js

@@ -11,11 +11,18 @@ export async function createMcpClient(spec) {
     transport = new StdioClientTransport({
       command: spec.command,
       args: spec.args,
+      env: spec.config?.env ? { ...process.env, ...spec.config.env } : undefined,
     });
   } else if (spec.transport === "sse") {
-    transport = new SSEClientTransport(new URL(spec.url));
+    const h = spec.config?.headers;
+    transport = new SSEClientTransport(new URL(spec.url), {
+      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+    });
   } else if (spec.transport === "streamable-http") {
-    transport = new StreamableHTTPClientTransport(new URL(spec.url));
+    const h = spec.config?.headers;
+    transport = new StreamableHTTPClientTransport(new URL(spec.url), {
+      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+    });
   } else {
     throw new Error(`Unknown MCP transport: ${spec.transport}. Supported: stdio, sse, streamable-http`);
   }

package/src/registry.js

@@ -0,0 +1,53 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+
+const REGISTRY_DIR = join(homedir(), "spec-cli-config");
+const REGISTRY_FILE = join(REGISTRY_DIR, "registry.json");
+const CACHE_DIR = join(REGISTRY_DIR, "cache");
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function getRegistry() {
+  if (!existsSync(REGISTRY_FILE)) return [];
+  try {
+    return JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
+  } catch {
+    throw new Error(`Registry file is corrupt: ${REGISTRY_FILE}. Delete it to reset.`);
+  }
+}
+
+export function saveRegistry(entries) {
+  ensureDir(REGISTRY_DIR);
+  writeFileSync(REGISTRY_FILE, JSON.stringify(entries, null, 2));
+}
+
+export function getEntry(name) {
+  const registry = getRegistry();
+  const entry = registry.find((e) => e.name === name);
+  if (!entry) throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
+  if (!entry.enabled) throw new Error(`Spec '${name}' is disabled. Run 'spec enable ${name}' first.`);
+  return entry;
+}
+
+export function getCachedSpec(name) {
+  const file = join(CACHE_DIR, `${name}.json`);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return null; // Corrupt cache is treated as a miss — will re-fetch
+  }
+}
+
+export function saveCachedSpec(name, spec) {
+  ensureDir(CACHE_DIR);
+  writeFileSync(join(CACHE_DIR, `${name}.json`), JSON.stringify(spec, null, 2));
+}
+
+export function removeCachedSpec(name) {
+  const file = join(CACHE_DIR, `${name}.json`);
+  if (existsSync(file)) rmSync(file);
+}

package/src/resolve.js

@@ -0,0 +1,65 @@
+import { getEntry, getCachedSpec, saveCachedSpec } from "./registry.js";
+import { resolveSpec, inlineEntryFromFlags } from "./commands/load.js";
+import { getConfig } from "./store.js";
+import { parseKV } from "./args.js";
+
+/**
+ * Resolve the active spec from flags.
+ * Priority:
+ *   1. --spec <name>  → registry (auto-caches on first use)
+ *   2. Inline flags   → ad-hoc, no caching
+ *   3. Error          → no spec source given
+ */
+export async function resolveActiveSpec(flags) {
+  if (flags.spec) {
+    const entry = getEntry(flags.spec);     // throws if missing or disabled
+    let spec = getCachedSpec(flags.spec);
+    if (!spec) {
+      spec = await resolveSpec(entry);
+      saveCachedSpec(flags.spec, spec);
+    }
+    return { spec, entry };
+  }
+
+  const inlineEntry = inlineEntryFromFlags(flags);
+  if (inlineEntry) {
+    const spec = await resolveSpec(inlineEntry);
+    return { spec, entry: inlineEntry };
+  }
+
+  throw new Error(
+    "No spec source. Pass --spec <name> (registered) or an inline flag:\n" +
+    "  --openapi <url-or-file>\n" +
+    "  --graphql <url>\n" +
+    "  --mcp-http <url>\n" +
+    "  --mcp-sse <url>\n" +
+    '  --mcp-stdio "<cmd args>"'
+  );
+}
+
+/**
+ * Build the effective config for a command.
+ * Precedence (highest → lowest):
+ *   1. Call-time flags: --auth, --base-url, --header k=v
+ *   2. Registry entry config
+ *   3. .spec-cli/config.json
+ */
+export function resolveConfig(flags, entry) {
+  const global = getConfig();
+  const entryConfig = entry?.config || {};
+  const callHeaders = parseKV(flags.header);
+
+  const auth = flags.auth || entryConfig.auth || global.auth;
+  const baseUrl = flags["base-url"] || entryConfig.baseUrl || global.baseUrl;
+  const headers = { ...global.headers, ...(entryConfig.headers || {}), ...callHeaders };
+
+  // Apply auth as Authorization header if not already there (case-insensitive check)
+  const hasAuthHeader = Object.keys(headers).some((k) => k.toLowerCase() === "authorization");
+  if (auth && !hasAuthHeader) {
+    headers["Authorization"] = auth.startsWith("Bearer ") || auth.startsWith("Basic ")
+      ? auth
+      : `Bearer ${auth}`;
+  }
+
+  return { auth, baseUrl, headers };
+}