api-spec-cli 0.2.4 → 0.2.5

package/src/glob.js

@@ -1,34 +1,34 @@
-function globToRegex(pattern) {
-  return new RegExp(
-    "^" +
-      pattern
-        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-        .replace(/\*/g, ".*")
-        .replace(/\?/g, ".") +
-      "$",
-    "i"
-  );
-}
-
-/**
- * Search match: plain text = substring, glob chars (* ?) = anchored glob.
- * Used by grep — broad matching is desirable for search.
- */
-export function matchGlob(pattern, str) {
-  if (!pattern.includes("*") && !pattern.includes("?")) {
-    return str.toLowerCase().includes(pattern.toLowerCase());
-  }
-  return globToRegex(pattern).test(str);
-}
-
-/**
- * Filter match: plain text = exact (case-insensitive), glob chars (* ?) = anchored glob.
- * Used by --allow-tool / --disable-tool — precision is required for whitelists.
- * Use *pattern* for explicit substring matching.
- */
-export function matchFilter(pattern, str) {
-  if (!pattern.includes("*") && !pattern.includes("?")) {
-    return str.toLowerCase() === pattern.toLowerCase();
-  }
-  return globToRegex(pattern).test(str);
-}
+function globToRegex(pattern) {
+  return new RegExp(
+    "^" +
+      pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".") +
+      "$",
+    "i"
+  );
+}
+
+/**
+ * Search match: plain text = substring, glob chars (* ?) = anchored glob.
+ * Used by grep — broad matching is desirable for search.
+ */
+export function matchGlob(pattern, str) {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return str.toLowerCase().includes(pattern.toLowerCase());
+  }
+  return globToRegex(pattern).test(str);
+}
+
+/**
+ * Filter match: plain text = exact (case-insensitive), glob chars (* ?) = anchored glob.
+ * Used by --allow-tool / --disable-tool — precision is required for whitelists.
+ * Use *pattern* for explicit substring matching.
+ */
+export function matchFilter(pattern, str) {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return str.toLowerCase() === pattern.toLowerCase();
+  }
+  return globToRegex(pattern).test(str);
+}

package/src/mcp-client.js

@@ -4,17 +4,20 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { SpecCliOAuthProvider } from "./oauth/provider.js";
 import { ClientCredentialsProvider } from "@modelcontextprotocol/sdk/client/auth-extensions.js";
-import { loadTokenFile } from "./oauth/tokens.js";
+import { getClientSecret } from "./oauth/tokens.js";
+import {
+  expandSecrets,
+  expandSecretsMap,
+  envHeaderOverrides,
+  envUrlOverride,
+  mergeHeaders,
+} from "./secrets.js";
 
 const MAX_RETRIES = parseInt(process.env.MCP_MAX_RETRIES ?? "3");
 const RETRY_DELAY = parseInt(process.env.MCP_RETRY_DELAY ?? "1000");
 
-// Expand ${VAR} placeholders from process.env at call time
 function expandEnv(val) {
-  return val.replace(/\$\{([^}]+)\}/g, (_, name) => {
-    if (!(name in process.env)) throw new Error(`Environment variable not set: ${name}`);
-    return process.env[name];
-  });
+  return expandSecrets(val);
 }
 
 async function connect(spec) {
@@ -33,36 +36,36 @@ async function connect(spec) {
       cwd: spec.cwd,
     });
   } else if (spec.type === "sse") {
-    const h = spec.headers;
+    const h = expandSecretsMap(mergeHeaders(spec.headers, envHeaderOverrides()));
+    const url = envUrlOverride() ?? spec.url;
     let authProvider;
-    // spec.name is only set for registry entries; inline connections (--mcp-sse <url>)
-    // have no token storage location, so no OAuth provider is created for them.
-    if (spec.name && !h?.Authorization) {
-      const clientSecret = loadTokenFile(spec.name).clientSecret;
+    const hasAuthSse = Object.keys(h).some((k) => k.toLowerCase() === "authorization");
+    if (spec.name && !hasAuthSse) {
+      const clientSecret = getClientSecret(spec.name);
       authProvider =
         spec.oauthFlow === "client_credentials" && spec.oauthClientId && clientSecret
           ? new ClientCredentialsProvider({ clientId: spec.oauthClientId, clientSecret })
           : new SpecCliOAuthProvider(spec.name, spec);
     }
-    transport = new SSEClientTransport(new URL(spec.url), {
+    transport = new SSEClientTransport(new URL(url), {
       authProvider,
-      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+      requestInit: Object.keys(h).length > 0 ? { headers: h } : undefined,
     });
   } else if (spec.type === "http") {
-    const h = spec.headers;
+    const h = expandSecretsMap(mergeHeaders(spec.headers, envHeaderOverrides()));
+    const url = envUrlOverride() ?? spec.url;
     let authProvider;
-    // spec.name is only set for registry entries; inline connections (--mcp-http <url>)
-    // have no token storage location, so no OAuth provider is created for them.
-    if (spec.name && !h?.Authorization) {
-      const clientSecret = loadTokenFile(spec.name).clientSecret;
+    const hasAuthHttp = Object.keys(h).some((k) => k.toLowerCase() === "authorization");
+    if (spec.name && !hasAuthHttp) {
+      const clientSecret = getClientSecret(spec.name);
       authProvider =
         spec.oauthFlow === "client_credentials" && spec.oauthClientId && clientSecret
           ? new ClientCredentialsProvider({ clientId: spec.oauthClientId, clientSecret })
           : new SpecCliOAuthProvider(spec.name, spec);
     }
-    transport = new StreamableHTTPClientTransport(new URL(spec.url), {
+    transport = new StreamableHTTPClientTransport(new URL(url), {
       authProvider,
-      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+      requestInit: Object.keys(h).length > 0 ? { headers: h } : undefined,
     });
   } else {
     throw new Error(`Unknown MCP type: ${spec.type}. Supported: stdio, sse, http`);

package/src/oauth/auth-flow.js

@@ -4,7 +4,7 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { ClientCredentialsProvider } from "@modelcontextprotocol/sdk/client/auth-extensions.js";
 import { SpecCliOAuthProvider } from "./provider.js";
-import { loadTokenFile } from "./tokens.js";
+import { getClientSecret } from "./tokens.js";
 
 /**
  * Run the full OAuth flow for a named MCP HTTP/SSE entry.
@@ -14,7 +14,7 @@ import { loadTokenFile } from "./tokens.js";
  */
 export async function runOAuthFlow(name, entry) {
   const TransportClass = entry.type === "sse" ? SSEClientTransport : StreamableHTTPClientTransport;
-  const clientSecret = loadTokenFile(name).clientSecret;
+  const clientSecret = getClientSecret(name);
 
   // Only use client credentials grant when explicitly requested.
   // Having a clientSecret does NOT imply client_credentials — for most OAuth apps

package/src/oauth/provider.js

@@ -1,7 +1,7 @@
 import { createServer } from "http";
 import { exec } from "child_process";
 import { randomUUID } from "crypto";
-import { loadTokenFile, saveTokenFile } from "./tokens.js";
+import { loadTokenFile, saveTokenFile, getClientSecret } from "./tokens.js";
 
 function openBrowser(url) {
   const cmd =
@@ -58,8 +58,7 @@ export class SpecCliOAuthProvider {
 
   get redirectUrl() {
     if (this.#flow === "device") return undefined;
-    if (!this.#redirectPort) throw new Error("Call prepareRedirect() before accessing redirectUrl");
-    return `http://127.0.0.1:${this.#redirectPort}/callback`;
+    return `http://127.0.0.1:${this.#redirectPort || 0}/callback`;
   }
 
   get clientMetadata() {
@@ -91,7 +90,7 @@ export class SpecCliOAuthProvider {
     const stored = loadTokenFile(this.#name).clientInfo;
     if (stored) return stored;
     if (this.#clientId) {
-      const clientSecret = loadTokenFile(this.#name).clientSecret;
+      const clientSecret = getClientSecret(this.#name);
       return clientSecret
         ? { client_id: this.#clientId, client_secret: clientSecret }
         : { client_id: this.#clientId };

package/src/oauth/tokens.js

@@ -1,6 +1,7 @@
 import { homedir } from "os";
 import { join } from "path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+import { expandSecrets } from "../secrets.js";
 
 let TOKEN_DIR = join(homedir(), "spec-cli-config", "tokens");
 
@@ -12,6 +13,11 @@ function tokenPath(name) {
   return join(TOKEN_DIR, `${name}.json`);
 }
 
+export function getClientSecret(name) {
+  const secret = loadTokenFile(name).clientSecret;
+  return secret ? expandSecrets(secret) : secret;
+}
+
 export function loadTokenFile(name) {
   const file = tokenPath(name);
   if (!existsSync(file)) return {};

package/src/output.js

@@ -1,61 +1,65 @@
-import YAML from "yaml";
-
-let outputFormat = "json";
-
-export function setFormat(format) {
-  if (format && ["json", "text", "yaml"].includes(format)) {
-    outputFormat = format;
-  }
-}
-
-export function out(data) {
-  switch (outputFormat) {
-    case "yaml":
-      console.log(YAML.stringify(data).trimEnd());
-      break;
-    case "text":
-      console.log(formatText(data));
-      break;
-    case "json":
-    default:
-      console.log(JSON.stringify(data, null, 2));
-      break;
-  }
-}
-
-export function err(message) {
-  // Errors are always JSON for reliable agent parsing
-  console.error(JSON.stringify({ error: message }));
-}
-
-function formatText(data, indent = 0) {
-  if (data === null || data === undefined) return "null";
-  if (typeof data === "string") return data;
-  if (typeof data === "number" || typeof data === "boolean") return String(data);
-
-  if (Array.isArray(data)) {
-    if (data.length === 0) return "(empty)";
-    return data
-      .map((item, i) => {
-        if (typeof item === "object" && item !== null) {
-          return `${"  ".repeat(indent)}[${i}]\n${formatText(item, indent + 1)}`;
-        }
-        return `${"  ".repeat(indent)}- ${item}`;
-      })
-      .join("\n");
-  }
-
-  if (typeof data === "object") {
-    return Object.entries(data)
-      .map(([key, val]) => {
-        if (val === null || val === undefined) return `${"  ".repeat(indent)}${key}: null`;
-        if (typeof val === "object") {
-          return `${"  ".repeat(indent)}${key}:\n${formatText(val, indent + 1)}`;
-        }
-        return `${"  ".repeat(indent)}${key}: ${val}`;
-      })
-      .join("\n");
-  }
-
-  return String(data);
-}
+import YAML from "yaml";
+import { encode } from "@toon-format/toon";
+
+let outputFormat = "json";
+
+export function setFormat(format) {
+  if (format && ["json", "text", "yaml", "toon"].includes(format)) {
+    outputFormat = format;
+  }
+}
+
+export function out(data) {
+  switch (outputFormat) {
+    case "yaml":
+      console.log(YAML.stringify(data).trimEnd());
+      break;
+    case "toon":
+      console.log(encode(data).trimEnd());
+      break;
+    case "text":
+      console.log(formatText(data));
+      break;
+    case "json":
+    default:
+      console.log(JSON.stringify(data, null, 2));
+      break;
+  }
+}
+
+export function err(message) {
+  // Errors are always JSON for reliable agent parsing
+  console.error(JSON.stringify({ error: message }));
+}
+
+function formatText(data, indent = 0) {
+  if (data === null || data === undefined) return "null";
+  if (typeof data === "string") return data;
+  if (typeof data === "number" || typeof data === "boolean") return String(data);
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) return "(empty)";
+    return data
+      .map((item, i) => {
+        if (typeof item === "object" && item !== null) {
+          return `${"  ".repeat(indent)}[${i}]\n${formatText(item, indent + 1)}`;
+        }
+        return `${"  ".repeat(indent)}- ${item}`;
+      })
+      .join("\n");
+  }
+
+  if (typeof data === "object") {
+    return Object.entries(data)
+      .map(([key, val]) => {
+        if (val === null || val === undefined) return `${"  ".repeat(indent)}${key}: null`;
+        if (typeof val === "object") {
+          return `${"  ".repeat(indent)}${key}:\n${formatText(val, indent + 1)}`;
+        }
+        return `${"  ".repeat(indent)}${key}: ${val}`;
+      })
+      .join("\n");
+  }
+
+  return String(data);
+}

package/src/registry.js

@@ -1,79 +1,79 @@
-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 });
-}
-
-const EMPTY = { mcp: {}, openapi: {}, graphql: {} };
-
-export function getRegistry() {
-  if (!existsSync(REGISTRY_FILE)) return { ...EMPTY };
-  try {
-    const data = JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
-    if (!data || typeof data !== "object" || Array.isArray(data)) {
-      throw new Error(`Registry file has old format: ${REGISTRY_FILE}. Delete it to reset.`);
-    }
-    return data;
-  } catch (e) {
-    if (e.message.includes("old format")) throw e;
-    throw new Error(`Registry file is corrupt: ${REGISTRY_FILE}. Delete it to reset.`);
-  }
-}
-
-export function saveRegistry(registry) {
-  ensureDir(REGISTRY_DIR);
-  writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2));
-}
-
-/**
- * Find an entry by name across all sections.
- * Returns the entry with `name` and `_section` injected.
- */
-export function allEntries(registry) {
-  const entries = [];
-  for (const section of ["mcp", "openapi", "graphql"]) {
-    for (const [name, entry] of Object.entries(registry[section] || {})) {
-      entries.push({ ...entry, name, _section: section });
-    }
-  }
-  return entries;
-}
-
-export function getEntry(name) {
-  const registry = getRegistry();
-  for (const section of ["mcp", "openapi", "graphql"]) {
-    const entry = registry[section]?.[name];
-    if (entry) {
-      if (!entry.enabled)
-        throw new Error(`Spec '${name}' is disabled. Run 'spec enable ${name}' first.`);
-      return { ...entry, name, _section: section };
-    }
-  }
-  throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
-}
-
-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;
-  }
-}
-
-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);
-}
+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 });
+}
+
+const EMPTY = { mcp: {}, openapi: {}, graphql: {} };
+
+export function getRegistry() {
+  if (!existsSync(REGISTRY_FILE)) return { ...EMPTY };
+  try {
+    const data = JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error(`Registry file has old format: ${REGISTRY_FILE}. Delete it to reset.`);
+    }
+    return data;
+  } catch (e) {
+    if (e.message.includes("old format")) throw e;
+    throw new Error(`Registry file is corrupt: ${REGISTRY_FILE}. Delete it to reset.`);
+  }
+}
+
+export function saveRegistry(registry) {
+  ensureDir(REGISTRY_DIR);
+  writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2));
+}
+
+/**
+ * Find an entry by name across all sections.
+ * Returns the entry with `name` and `_section` injected.
+ */
+export function allEntries(registry) {
+  const entries = [];
+  for (const section of ["mcp", "openapi", "graphql"]) {
+    for (const [name, entry] of Object.entries(registry[section] || {})) {
+      entries.push({ ...entry, name, _section: section });
+    }
+  }
+  return entries;
+}
+
+export function getEntry(name) {
+  const registry = getRegistry();
+  for (const section of ["mcp", "openapi", "graphql"]) {
+    const entry = registry[section]?.[name];
+    if (entry) {
+      if (!entry.enabled)
+        throw new Error(`Spec '${name}' is disabled. Run 'spec enable ${name}' first.`);
+      return { ...entry, name, _section: section };
+    }
+  }
+  throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
+}
+
+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;
+  }
+}
+
+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

@@ -2,17 +2,17 @@ import { getEntry, getCachedSpec, saveCachedSpec } from "./registry.js";
 import { fetchSpec, inlineEntryFromFlags } from "./commands/fetch.js";
 import { getConfig } from "./store.js";
 import { parseKV } from "./args.js";
+import {
+  expandSecrets,
+  expandSecretsMap,
+  envHeaderOverrides,
+  envUrlOverride,
+  mergeHeaders,
+} from "./secrets.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 resolveSpec(flags) {
   if (flags.spec) {
-    const entry = getEntry(flags.spec); // throws if missing or disabled
+    const entry = getEntry(flags.spec);
     let spec = getCachedSpec(flags.spec);
     if (!spec) {
       spec = await fetchSpec(entry);
@@ -37,23 +37,25 @@ export async function resolveSpec(flags) {
   );
 }
 
-/**
- * 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 };
+  const rawAuth = flags.auth || entryConfig.auth || global.auth;
+  const auth = rawAuth ? expandSecrets(rawAuth) : rawAuth;
+  const isGraphql = entry?.type === "graphql" || entry?._section === "graphql";
+  const envUrl = isGraphql ? envUrlOverride() : undefined;
+  const baseUrl = flags["base-url"] || envUrl || entryConfig.baseUrl || global.baseUrl;
+
+  const mergedHeaders = mergeHeaders(
+    global.headers,
+    entryConfig.headers,
+    envHeaderOverrides(),
+    callHeaders
+  );
+  const headers = expandSecretsMap(mergedHeaders);
 
-  // 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"] =

package/src/secrets.js

@@ -0,0 +1,46 @@
+const ENV_VAR_RE = /\$\{([^}]+)\}/g;
+
+export function expandSecrets(str) {
+  if (typeof str !== "string") return str;
+  if (!str.includes("${")) return str;
+  return str.replace(ENV_VAR_RE, (_, name) => {
+    if (!(name in process.env)) throw new Error(`Environment variable not set: ${name}`);
+    return process.env[name];
+  });
+}
+
+export function expandSecretsMap(obj) {
+  if (!obj || typeof obj !== "object") return obj;
+  return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expandSecrets(v)]));
+}
+
+export function envHeaderOverrides() {
+  const headers = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith("SPEC_HEADER_")) continue;
+    const headerName = key.slice("SPEC_HEADER_".length).replace(/_/g, "-").toLowerCase();
+    headers[headerName] = value;
+  }
+  return headers;
+}
+
+export function mergeHeaders(...maps) {
+  const canonical = {};
+  const result = {};
+  for (const map of maps) {
+    if (!map) continue;
+    for (const [key, value] of Object.entries(map)) {
+      const lower = key.toLowerCase();
+      if (lower in canonical) {
+        delete result[canonical[lower]];
+      }
+      canonical[lower] = key;
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+export function envUrlOverride() {
+  return process.env.SPEC_URL;
+}