api-spec-cli 0.2.3 → 0.2.5

package/src/commands/grep.js

@@ -1,21 +1,22 @@
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
-import { getRegistry, getEntry, getCachedSpec, saveCachedSpec } from "../registry.js";
+import { getRegistry, getEntry, getCachedSpec, saveCachedSpec, allEntries } from "../registry.js";
 import { fetchSpec } from "./fetch.js";
 import { matchGlob } from "../glob.js";
 
 export async function grepCmd(args) {
   const { flags, positional } = parseArgs(args);
   const pattern = positional[0];
-  if (!pattern) throw new Error(
-    "Usage: spec grep <pattern> [--spec <name>]\n" +
-    "  Glob patterns: * matches anything, ? matches one char\n" +
-    "  Plain text: substring match across name and description"
-  );
+  if (!pattern)
+    throw new Error(
+      "Usage: spec grep <pattern> [--spec <name>]\n" +
+        "  Glob patterns: * matches anything, ? matches one char\n" +
+        "  Plain text: substring match across name and description"
+    );
 
   const entries = flags.spec
     ? [getEntry(flags.spec)]
-    : getRegistry().filter((e) => e.enabled);
+    : allEntries(getRegistry()).filter((e) => e.enabled);
 
   if (entries.length === 0) throw new Error("No registered specs. Run 'spec add' first.");
 
@@ -40,15 +41,17 @@ export async function grepCmd(args) {
       }
     } else if (spec.type === "openapi") {
       for (const op of spec.operations) {
-        if (matchGlob(pattern, op.id) || matchGlob(pattern, op.path) ||
-            (op.summary && matchGlob(pattern, op.summary))) {
+        if (
+          matchGlob(pattern, op.id) ||
+          matchGlob(pattern, op.path) ||
+          (op.summary && matchGlob(pattern, op.summary))
+        ) {
           matches.push({ id: op.id, method: op.method, path: op.path });
         }
       }
     } else if (spec.type === "graphql") {
       for (const op of spec.operations) {
-        if (matchGlob(pattern, op.name) ||
-            (op.description && matchGlob(pattern, op.description))) {
+        if (matchGlob(pattern, op.name) || (op.description && matchGlob(pattern, op.description))) {
           matches.push({ id: op.name, kind: op.kind });
         }
       }

package/src/commands/list.js

@@ -1,80 +1,89 @@
-import { out } from "../output.js";
-import { parseArgs } from "../args.js";
-import { resolveSpec } from "../resolve.js";
-
-export async function listOperations(args) {
-  const opts = parseArgs(args);
-  const { flags } = opts;
-
-  const { spec } = await resolveSpec(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") {
-    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 }
-        : {
-            id: op.id,
-            method: op.method,
-            path: op.path,
-            summary: op.summary,
-            tags: op.tags,
-            deprecated: op.deprecated,
-          }
-    );
-  } else if (spec.type === "mcp") {
-    operations = spec.tools.map((t) =>
-      compact
-        ? { id: t.name, description: t.description }
-        : { id: t.name, description: t.description, inputSchema: t.inputSchema }
-    );
-  } else {
-    // graphql
-    operations = spec.operations.map((op) =>
-      compact
-        ? { id: op.name, kind: op.kind }
-        : {
-            id: op.name,
-            kind: op.kind,
-            description: op.description,
-            args: op.args.map((a) => a.name),
-            returnType: op.returnType,
-            isDeprecated: op.isDeprecated,
-          }
-    );
-
-    if (tag) {
-      operations = operations.filter((op) => op.kind === tag);
-    }
-  }
-
-  if (filter) {
-    operations = operations.filter((op) =>
-      JSON.stringify(op).toLowerCase().includes(filter)
-    );
-  }
-
-  const total = operations.length;
-
-  if (offset > 0) operations = operations.slice(offset);
-  if (limit > 0)  operations = operations.slice(0, limit);
-
-  out({
-    type: spec.type,
-    total,
-    showing: operations.length,
-    offset: offset || 0,
-    operations,
-  });
-}
+import { out } from "../output.js";
+import { parseArgs } from "../args.js";
+import { resolveSpec } from "../resolve.js";
+import { getUsage } from "../usage.js";
+
+export async function listOperations(args) {
+  const opts = parseArgs(args);
+  const { flags } = opts;
+
+  const { spec } = await resolveSpec(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();
+  const top = parseInt(flags.top) || 0;
+
+  let operations;
+
+  if (spec.type === "openapi") {
+    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 }
+        : {
+            id: op.id,
+            method: op.method,
+            path: op.path,
+            summary: op.summary,
+            tags: op.tags,
+            deprecated: op.deprecated,
+          }
+    );
+  } else if (spec.type === "mcp") {
+    operations = spec.tools.map((t) =>
+      compact
+        ? { id: t.name, description: t.description }
+        : { id: t.name, description: t.description, inputSchema: t.inputSchema }
+    );
+  } else {
+    // graphql
+    operations = spec.operations.map((op) =>
+      compact
+        ? { id: op.name, kind: op.kind }
+        : {
+            id: op.name,
+            kind: op.kind,
+            description: op.description,
+            args: op.args.map((a) => a.name),
+            returnType: op.returnType,
+            isDeprecated: op.isDeprecated,
+          }
+    );
+
+    if (tag) {
+      operations = operations.filter((op) => op.kind === tag);
+    }
+  }
+
+  if (filter) {
+    operations = operations.filter((op) => JSON.stringify(op).toLowerCase().includes(filter));
+  }
+
+  const total = operations.length;
+
+  if (top > 0) {
+    const usageMap = flags.spec ? getUsage(flags.spec) : {};
+    operations = operations
+      .map((op) => ({ op, count: usageMap[op.id]?.count ?? 0 }))
+      .sort((a, b) => b.count - a.count)
+      .map(({ op }) => op)
+      .slice(0, top);
+  } else {
+    if (offset > 0) operations = operations.slice(offset);
+    if (limit > 0) operations = operations.slice(0, limit);
+  }
+
+  out({
+    type: spec.type,
+    total,
+    showing: operations.length,
+    offset: offset || 0,
+    operations,
+  });
+}

package/src/commands/show.js

@@ -5,7 +5,10 @@ import { resolveSpec } from "../resolve.js";
 export async function showOperation(args) {
   const { flags, positional } = parseArgs(args);
   const target = positional[0];
-  if (!target) throw new Error("Usage: spec show <operationId-or-path> [--spec <name> | --openapi <url> | ...]");
+  if (!target)
+    throw new Error(
+      "Usage: spec show <operationId-or-path> [--spec <name> | --openapi <url> | ...]"
+    );
 
   const { spec } = await resolveSpec(flags);
 
@@ -21,10 +24,11 @@ export async function showOperation(args) {
 function showOpenAPI(spec, target) {
   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
+  const op = spec.operations.find(
+    (o) =>
+      o.id.toLowerCase() === lower ||
+      o.path.toLowerCase() === lower ||
+      `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
   );
 
   if (!op) {
@@ -195,8 +199,13 @@ function findRelatedTypes(op, 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.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/skill.js

@@ -0,0 +1,40 @@
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { parseArgs } from "../args.js";
+import { out } from "../output.js";
+
+const SKILL_NAME = "api-spec-cli";
+const BUNDLED = join(dirname(fileURLToPath(import.meta.url)), "..", "skill", "SKILL.md");
+
+function installDir() {
+  return join(homedir(), ".claude", "skills", SKILL_NAME);
+}
+
+export async function skillCmd(args) {
+  const { flags, positional } = parseArgs(args);
+
+  if (positional[0] === "path" || "path" in flags) {
+    out({ skill: SKILL_NAME, path: BUNDLED });
+    return;
+  }
+
+  if (positional[0] === "install" || "install" in flags) {
+    if (!existsSync(BUNDLED)) throw new Error(`Bundled skill not found at ${BUNDLED}`);
+    const dest = join(installDir(), "SKILL.md");
+    mkdirSync(installDir(), { recursive: true });
+    writeFileSync(dest, readFileSync(BUNDLED, "utf-8"));
+    out({ installed: true, skill: SKILL_NAME, path: dest });
+    return;
+  }
+
+  out({
+    skill: SKILL_NAME,
+    usage: {
+      install: "spec skill install    Copy the skill into ~/.claude/skills/",
+      path: "spec skill path       Print the bundled SKILL.md location",
+    },
+    bundled: BUNDLED,
+  });
+}

package/src/commands/specs.js

@@ -1,19 +1,32 @@
 import { parseArgs } from "../args.js";
-import { getRegistry, saveRegistry, getEntry, removeCachedSpec, saveCachedSpec } from "../registry.js";
+import {
+  getRegistry,
+  saveRegistry,
+  getEntry,
+  removeCachedSpec,
+  saveCachedSpec,
+  allEntries,
+} from "../registry.js";
 import { fetchSpec } from "./fetch.js";
 import { out } from "../output.js";
 
+function findSection(registry, name) {
+  for (const section of ["mcp", "openapi", "graphql"]) {
+    if (registry[section]?.[name]) return section;
+  }
+  return null;
+}
+
 export async function specsCmd(args) {
   const { flags } = parseArgs(args);
   const compact = flags.compact !== "false";
   const registry = getRegistry();
 
-  const specs = registry.map((e) => {
+  const specs = allEntries(registry).map((e) => {
     if (compact) {
       return {
         name: e.name,
         type: e.type,
-        transport: e.transport,
         description: e.description || null,
         enabled: e.enabled,
       };
@@ -30,11 +43,11 @@ export async function registryMutate(action, args) {
   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.`);
+  const section = findSection(registry, name);
+  if (!section) throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
 
   if (action === "remove") {
-    registry.splice(idx, 1);
+    delete registry[section][name];
     saveRegistry(registry);
     removeCachedSpec(name);
     out({ ok: true, removed: name });
@@ -42,21 +55,21 @@ export async function registryMutate(action, args) {
   }
 
   if (action === "enable") {
-    registry[idx].enabled = true;
+    registry[section][name].enabled = true;
     saveRegistry(registry);
     out({ ok: true, enabled: name });
     return;
   }
 
   if (action === "disable") {
-    registry[idx].enabled = false;
+    registry[section][name].enabled = false;
     saveRegistry(registry);
     out({ ok: true, disabled: name });
     return;
   }
 
   if (action === "refresh") {
-    const entry = registry[idx];
+    const entry = { ...registry[section][name], name, _section: section };
     if (!entry.enabled) throw new Error(`Spec '${name}' is disabled. Enable it first.`);
     const spec = await fetchSpec(entry);
     saveCachedSpec(name, spec);

package/src/commands/types.js

@@ -50,7 +50,8 @@ function showOpenAPISchema(spec, target, flags) {
 
 function showGraphQLType(spec, target, flags) {
   const scalars = new Set(["String", "Int", "Float", "Boolean", "ID"]);
-  const userTypes = spec.types?.filter((t) => !t.name.startsWith("__") && !scalars.has(t.name)) || [];
+  const userTypes =
+    spec.types?.filter((t) => !t.name.startsWith("__") && !scalars.has(t.name)) || [];
 
   if (!target) {
     // List type names grouped by kind — compact
@@ -85,7 +86,10 @@ function showGraphQLType(spec, target, flags) {
     result.fields = type.fields.map((f) => ({
       name: f.name,
       type: flattenType(f.type),
-      args: f.args?.length > 0 ? f.args.map((a) => ({ name: a.name, type: flattenType(a.type) })) : undefined,
+      args:
+        f.args?.length > 0
+          ? f.args.map((a) => ({ name: a.name, type: flattenType(a.type) }))
+          : undefined,
     }));
   }
 

package/src/commands/usage.js

@@ -0,0 +1,15 @@
+import { out } from "../output.js";
+import { parseArgs } from "../args.js";
+import { allUsage, topOperations } from "../usage.js";
+
+export async function usageCmd(args) {
+  const { positional } = parseArgs(args);
+  const specName = positional[0];
+
+  if (specName) {
+    const operations = topOperations(specName, Infinity);
+    out({ spec: specName, operations });
+  } else {
+    out({ usage: allUsage() });
+  }
+}

package/src/commands/validate.js

@@ -88,7 +88,10 @@ function validateInfo(doc, errors, warnings) {
     errors.push({ path: "info.version", message: "Missing required 'info.version'" });
   }
   if (!doc.info.description) {
-    warnings.push({ path: "info.description", message: "Missing 'info.description' (recommended)" });
+    warnings.push({
+      path: "info.description",
+      message: "Missing 'info.description' (recommended)",
+    });
   }
 }
 
@@ -121,7 +124,10 @@ function validatePaths(doc, errors, warnings, isV3) {
       if (method.startsWith("x-") || method === "parameters" || method === "$ref") continue;
 
       if (!METHODS.has(method)) {
-        warnings.push({ path: `paths.${path}.${method}`, message: `Unknown HTTP method '${method}'` });
+        warnings.push({
+          path: `paths.${path}.${method}`,
+          message: `Unknown HTTP method '${method}'`,
+        });
         continue;
       }
 
@@ -161,13 +167,19 @@ function validatePaths(doc, errors, warnings, isV3) {
       for (const param of pathParams) {
         if (!declaredParams.has(param)) {
           // Only warn — the param might be declared via $ref
-          warnings.push({ path: opPath, message: `Path parameter '{${param}}' may not be declared in parameters` });
+          warnings.push({
+            path: opPath,
+            message: `Path parameter '{${param}}' may not be declared in parameters`,
+          });
         }
       }
 
       // Request body on GET/DELETE/HEAD
       if (isV3 && op.requestBody && ["get", "delete", "head"].includes(method)) {
-        warnings.push({ path: opPath, message: `requestBody on ${method.toUpperCase()} is unusual` });
+        warnings.push({
+          path: opPath,
+          message: `requestBody on ${method.toUpperCase()} is unusual`,
+        });
       }
     }
   }
@@ -196,7 +208,15 @@ function validateSchema(schema, path, errors, warnings) {
   if (!schema || typeof schema !== "object") return;
   if (schema.$ref) return; // reference, skip
 
-  const VALID_TYPES = new Set(["string", "number", "integer", "boolean", "array", "object", "null"]);
+  const VALID_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "array",
+    "object",
+    "null",
+  ]);
 
   if (schema.type && !VALID_TYPES.has(schema.type)) {
     errors.push({ path, message: `Invalid type '${schema.type}'` });
@@ -220,11 +240,17 @@ function validateSchema(schema, path, errors, warnings) {
 function validateServers(doc, errors, warnings, isV3) {
   if (isV3) {
     if (!doc.servers || doc.servers.length === 0) {
-      warnings.push({ path: "servers", message: "No servers defined — agent will need baseUrl configured" });
+      warnings.push({
+        path: "servers",
+        message: "No servers defined — agent will need baseUrl configured",
+      });
     }
   } else {
     if (!doc.host) {
-      warnings.push({ path: "host", message: "No host defined — agent will need baseUrl configured" });
+      warnings.push({
+        path: "host",
+        message: "No host defined — agent will need baseUrl configured",
+      });
     }
   }
 }

package/src/dotenv.js

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+function parseEnv(text) {
+  const out = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (!key) continue;
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function loadDotenv(dir = process.cwd()) {
+  if (process.env.SPEC_NO_DOTENV) return;
+  const file = join(dir, ".env");
+  if (!existsSync(file)) return;
+  let parsed;
+  try {
+    parsed = parseEnv(readFileSync(file, "utf-8"));
+  } catch {
+    return;
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!(key in process.env)) process.env[key] = value;
+  }
+}

package/src/glob.js

@@ -1,6 +1,11 @@
 function globToRegex(pattern) {
   return new RegExp(
-    "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$",
+    "^" +
+      pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".") +
+      "$",
     "i"
   );
 }