api-spec-cli 0.2.3 → 0.2.5

package/src/resolve.js

@@ -1,65 +1,66 @@
-import { getEntry, getCachedSpec, saveCachedSpec } from "./registry.js";
-import { fetchSpec, inlineEntryFromFlags } from "./commands/fetch.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 resolveSpec(flags) {
-  if (flags.spec) {
-    const entry = getEntry(flags.spec);     // throws if missing or disabled
-    let spec = getCachedSpec(flags.spec);
-    if (!spec) {
-      spec = await fetchSpec(entry);
-      saveCachedSpec(flags.spec, spec);
-    }
-    return { spec, entry };
-  }
-
-  const inlineEntry = inlineEntryFromFlags(flags);
-  if (inlineEntry) {
-    const spec = await fetchSpec(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 };
-}
+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";
+
+export async function resolveSpec(flags) {
+  if (flags.spec) {
+    const entry = getEntry(flags.spec);
+    let spec = getCachedSpec(flags.spec);
+    if (!spec) {
+      spec = await fetchSpec(entry);
+      saveCachedSpec(flags.spec, spec);
+    }
+    return { spec, entry };
+  }
+
+  const inlineEntry = inlineEntryFromFlags(flags);
+  if (inlineEntry) {
+    const spec = await fetchSpec(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>"'
+  );
+}
+
+export function resolveConfig(flags, entry) {
+  const global = getConfig();
+  const entryConfig = entry?.config || {};
+  const callHeaders = parseKV(flags.header);
+
+  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);
+
+  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 };
+}

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;
+}

package/src/skill/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: api-spec-cli
+description: Use when you need to explore or call an OpenAPI, GraphQL, or MCP API from the shell — register a spec once, search/list/inspect operations token-efficiently, then call them. Prefer this over loading whole specs or wiring an MCP client into context.
+---
+
+# Exploring and calling APIs with `spec`
+
+`spec` (the `api-spec-cli` package) turns any OpenAPI, GraphQL, or MCP server into a small set of shell commands. It is built for agents: output is compact JSON by default, you load only the operation you need, and you can search across many specs at once instead of holding full schemas in context.
+
+Install: `npm install -g api-spec-cli` (or `npx api-spec-cli <command>`).
+
+## The workflow
+
+Work in four steps. Each step narrows what you load into context — never fetch a whole spec when you can grep then show one operation.
+
+1. **Register once** — `spec add <name> ...`. Fetches and caches; later commands hit the cache.
+2. **Search** — `spec grep <pattern>` across all specs, or `spec list --spec <name>` for one. Both return compact IDs only.
+3. **Inspect one** — `spec show --spec <name> <op>` returns everything needed to call it (params, body, response, related types) in a single result.
+4. **Call** — `spec call --spec <name> <op> ...`.
+
+## Register a spec
+
+```bash
+spec add petstore --openapi https://petstore3.swagger.io/api/v3/openapi.json --base-url https://petstore3.swagger.io/api/v3
+spec add hashnode --graphql https://gql.hashnode.com
+spec add agno --mcp-http https://docs.agno.com/mcp
+spec add fs --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
+```
+
+You can skip registration and pass an inline source on any command: `--openapi <url>`, `--graphql <url>`, `--mcp-http <url>`, `--mcp-sse <url>`, `--mcp-stdio "<cmd>"`.
+
+## Discover without burning context
+
+```bash
+spec grep search                 # substring match across every registered spec
+spec grep "get*"                 # glob
+spec list --spec petstore        # compact IDs, no schemas
+spec list --spec petstore --filter pet --limit 10
+spec list --spec petstore --top 10   # the 10 most-called operations first
+spec show --spec petstore getPetById  # full detail for ONE operation
+spec types --spec petstore Pet        # one schema at a time (OpenAPI/GraphQL)
+```
+
+`list` is compact by default — add `--compact false` only when you actually need schemas.
+
+## Call
+
+```bash
+spec call --spec petstore getPetById --var petId=1
+spec call --spec petstore findPetsByStatus --query status=available
+spec call --spec petstore addPet --data '{"name":"Rex","photoUrls":[]}'
+spec call --spec hashnode publication --var host=blog.hashnode.dev
+spec call --spec agno search_agno --var query="how to create an agent"
+echo '{"query":"agents"}' | spec call --spec agno search_agno --data -
+```
+
+## Output formats — pick the cheapest that works
+
+```bash
+spec list --spec petstore --format toon   # most token-efficient for uniform arrays
+spec list --spec petstore --format json   # default
+spec show --spec petstore getPetById --format yaml
+```
+
+`toon` (Token-Oriented Object Notation) is the densest for tabular/list data and is the best default when feeding results back into a model. Errors are always JSON on stderr.
+
+## Usage ranking
+
+`spec` records which operations you call. Use it to surface the operations that matter:
+
+```bash
+spec list --spec petstore --top 5   # rank by call count
+spec usage                          # all recorded usage
+spec usage petstore                 # ranked operations for one spec
+```
+
+Set `SPEC_NO_USAGE=1` to disable tracking.
+
+## Secrets and per-call overrides
+
+Never paste raw secrets into the registry. Store a placeholder and let it expand from the environment at call time:
+
+```bash
+spec add gh --mcp-http https://api.example.com/mcp --header "Authorization=Bearer ${GH_TOKEN}"
+spec config set auth '${API_TOKEN}'
+```
+
+Override a registered spec's connection at call time without editing it:
+
+```bash
+SPEC_URL=https://staging.example.com/mcp spec call --spec gh some_tool
+SPEC_HEADER_X_TENANT=acme spec list --spec gh
+```
+
+A `.env` file next to where you run `spec` is auto-loaded (real environment variables win over it).
+
+## Auth (MCP OAuth)
+
+OAuth 2.1 MCP servers are handled automatically on `spec add` (browser flow opens; DCR servers need no flags). For pre-registered apps like GitHub, pass `--oauth-client-id` and `--oauth-callback-port`. Re-authenticate with `spec auth <name>`; tokens refresh automatically and persist across invocations.
+
+## Quick reference
+
+```bash
+spec specs                     # list registered specs
+spec grep <pattern>            # search across all specs
+spec list --spec <name>        # compact operation list
+spec show --spec <name> <op>   # full detail for one operation
+spec call --spec <name> <op>   # call it
+spec usage [<name>]            # usage ranking
+spec validate <file-or-url>    # check an OpenAPI spec for errors
+spec help                      # full flag reference
+```

package/src/usage.js

@@ -0,0 +1,62 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+
+let USAGE_DIR = join(homedir(), "spec-cli-config");
+
+export function setUsageDir(dir) {
+  USAGE_DIR = dir;
+}
+
+function usagePath() {
+  return join(USAGE_DIR, "usage.json");
+}
+
+function loadStore() {
+  const file = usagePath();
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveStore(store) {
+  mkdirSync(USAGE_DIR, { recursive: true });
+  writeFileSync(usagePath(), JSON.stringify(store, null, 2));
+}
+
+export function recordUsage(specName, operationId) {
+  if (process.env.SPEC_NO_USAGE) return;
+  if (!specName || !operationId) return;
+  try {
+    const store = loadStore();
+    if (!store[specName]) store[specName] = {};
+    const entry = store[specName][operationId] || { count: 0, lastUsed: null };
+    entry.count += 1;
+    entry.lastUsed = new Date().toISOString();
+    store[specName][operationId] = entry;
+    saveStore(store);
+  } catch {}
+}
+
+export function getUsage(specName) {
+  const store = loadStore();
+  return store[specName] || {};
+}
+
+export function topOperations(specName, n) {
+  const perSpec = getUsage(specName);
+  return Object.entries(perSpec)
+    .map(([id, { count, lastUsed }]) => ({ id, count, lastUsed }))
+    .sort((a, b) => {
+      if (b.count !== a.count) return b.count - a.count;
+      return (b.lastUsed || "") < (a.lastUsed || "") ? -1 : 1;
+    })
+    .slice(0, n);
+}
+
+export function allUsage() {
+  return loadStore();
+}