api-spec-cli 0.2.4 → 0.2.5

package/src/commands/grep.js

@@ -1,67 +1,67 @@
-import { out } from "../output.js";
-import { parseArgs } from "../args.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"
-    );
-
-  const entries = flags.spec
-    ? [getEntry(flags.spec)]
-    : allEntries(getRegistry()).filter((e) => e.enabled);
-
-  if (entries.length === 0) throw new Error("No registered specs. Run 'spec add' first.");
-
-  const results = [];
-
-  for (const entry of entries) {
-    let spec = getCachedSpec(entry.name);
-    if (!spec) {
-      spec = await fetchSpec(entry);
-      saveCachedSpec(entry.name, spec);
-    }
-
-    const matches = [];
-
-    if (spec.type === "mcp") {
-      for (const tool of spec.tools) {
-        const nameMatch = matchGlob(pattern, tool.name);
-        const descMatch = tool.description && matchGlob(pattern, tool.description);
-        if (nameMatch || descMatch) {
-          matches.push({ id: tool.name, description: tool.description });
-        }
-      }
-    } 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))
-        ) {
-          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))) {
-          matches.push({ id: op.name, kind: op.kind });
-        }
-      }
-    }
-
-    if (matches.length > 0) {
-      results.push({ spec: entry.name, type: spec.type, matches });
-    }
-  }
-
-  const total = results.reduce((s, r) => s + r.matches.length, 0);
-  out({ pattern, total, results });
-}
+import { out } from "../output.js";
+import { parseArgs } from "../args.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"
+    );
+
+  const entries = flags.spec
+    ? [getEntry(flags.spec)]
+    : allEntries(getRegistry()).filter((e) => e.enabled);
+
+  if (entries.length === 0) throw new Error("No registered specs. Run 'spec add' first.");
+
+  const results = [];
+
+  for (const entry of entries) {
+    let spec = getCachedSpec(entry.name);
+    if (!spec) {
+      spec = await fetchSpec(entry);
+      saveCachedSpec(entry.name, spec);
+    }
+
+    const matches = [];
+
+    if (spec.type === "mcp") {
+      for (const tool of spec.tools) {
+        const nameMatch = matchGlob(pattern, tool.name);
+        const descMatch = tool.description && matchGlob(pattern, tool.description);
+        if (nameMatch || descMatch) {
+          matches.push({ id: tool.name, description: tool.description });
+        }
+      }
+    } 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))
+        ) {
+          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))) {
+          matches.push({ id: op.name, kind: op.kind });
+        }
+      }
+    }
+
+    if (matches.length > 0) {
+      results.push({ spec: entry.name, type: spec.type, matches });
+    }
+  }
+
+  const total = results.reduce((s, r) => s + r.matches.length, 0);
+  out({ pattern, total, results });
+}

package/src/commands/list.js

@@ -1,6 +1,7 @@
 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);
@@ -13,6 +14,7 @@ export async function listOperations(args) {
   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;
 
@@ -65,8 +67,17 @@ export async function listOperations(args) {
 
   const total = operations.length;
 
-  if (offset > 0) operations = operations.slice(offset);
-  if (limit > 0) operations = operations.slice(0, limit);
+  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,

package/src/commands/show.js

@@ -1,224 +1,224 @@
-import { out } from "../output.js";
-import { parseArgs } from "../args.js";
-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> | ...]"
-    );
-
-  const { spec } = await resolveSpec(flags);
-
-  if (spec.type === "openapi") {
-    showOpenAPI(spec, target);
-  } else if (spec.type === "mcp") {
-    showMCP(spec, target);
-  } else {
-    showGraphQL(spec, target);
-  }
-}
-
-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
-  );
-
-  if (!op) {
-    throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
-  }
-
-  const root = spec.raw || spec.components;
-
-  out({
-    id: op.id,
-    method: op.method,
-    path: op.path,
-    summary: op.summary,
-    description: op.description,
-    tags: op.tags,
-    deprecated: op.deprecated,
-    parameters: op.parameters.map((p) => {
-      const resolved = resolveRef(p, root);
-      return {
-        name: resolved.name,
-        in: resolved.in,
-        required: resolved.required || false,
-        type: resolved.schema?.type || null,
-        format: resolved.schema?.format || undefined,
-        description: resolved.description || undefined,
-        enum: resolved.schema?.enum || undefined,
-      };
-    }),
-    requestBody: op.requestBody ? resolveRequestBody(op.requestBody, root) : null,
-    responses: resolveResponsesCompact(op.responses, root),
-  });
-}
-
-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();
-
-  const op = spec.operations.find((o) => o.name.toLowerCase() === lower);
-
-  if (!op) {
-    throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
-  }
-
-  const relatedTypes = findRelatedTypes(op, spec.types);
-
-  out({
-    name: op.name,
-    kind: op.kind,
-    description: op.description,
-    returnType: op.returnType,
-    isDeprecated: op.isDeprecated,
-    args: op.args?.map((a) => ({
-      name: a.name,
-      type: flattenType(a.type),
-      required: a.type?.kind === "NON_NULL",
-      description: a.description || undefined,
-      defaultValue: a.defaultValue || undefined,
-    })),
-    relatedTypes,
-  });
-}
-
-// --- Helpers ---
-
-function resolveRef(obj, root) {
-  if (!obj || typeof obj !== "object") return obj;
-  if (obj.$ref) {
-    const path = obj.$ref.replace("#/", "").split("/");
-    let resolved = root;
-    for (const p of path) resolved = resolved?.[p];
-    return resolved || obj;
-  }
-  return obj;
-}
-
-function resolveRequestBody(body, root) {
-  if (!body) return null;
-  const resolved = resolveRef(body, root);
-  if (resolved?.content) {
-    const jsonContent = resolved.content["application/json"];
-    if (jsonContent) {
-      return {
-        description: resolved.description || undefined,
-        required: resolved.required || undefined,
-        schema: resolveSchema(jsonContent.schema, root),
-      };
-    }
-    const [mediaType, value] = Object.entries(resolved.content)[0];
-    return {
-      description: resolved.description || undefined,
-      required: resolved.required || undefined,
-      mediaType,
-      schema: resolveSchema(value.schema, root),
-    };
-  }
-  return resolved;
-}
-
-function resolveResponsesCompact(responses, root) {
-  if (!responses) return null;
-  const result = {};
-  for (const [code, resp] of Object.entries(responses)) {
-    const resolved = resolveRef(resp, root);
-    if (resolved?.content) {
-      const jsonContent = resolved.content["application/json"];
-      result[code] = jsonContent
-        ? { description: resolved.description, schema: resolveSchema(jsonContent.schema, root) }
-        : { description: resolved.description };
-    } else {
-      result[code] = { description: resolved.description };
-    }
-  }
-  return result;
-}
-
-function resolveSchema(schema, root, depth = 0) {
-  if (!schema || depth > 3) return schema;
-  if (schema.$ref) return resolveSchema(resolveRef(schema, root), root, depth + 1);
-  if (schema.properties) {
-    const result = { type: schema.type, required: schema.required, properties: {} };
-    for (const [key, val] of Object.entries(schema.properties)) {
-      if (val.$ref) {
-        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 {
-        const prop = { type: val.type };
-        if (val.format) prop.format = val.format;
-        if (val.enum) prop.enum = val.enum;
-        if (val.description) prop.description = val.description;
-        result.properties[key] = prop;
-      }
-    }
-    return result;
-  }
-  if (schema.items) {
-    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;
-}
-
-function findRelatedTypes(op, types) {
-  const names = new Set();
-
-  function extractTypeNames(typeStr) {
-    if (!typeStr) return;
-    const cleaned = typeStr.replace(/[[\]!]/g, "");
-    if (cleaned) names.add(cleaned);
-  }
-
-  extractTypeNames(op.returnType);
-  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);
-      return result;
-    });
-}
-
-function flattenType(t) {
-  if (!t) return null;
-  if (t.name) return t.kind === "NON_NULL" ? `${t.name}!` : t.name;
-  if (t.ofType) {
-    const inner = flattenType(t.ofType);
-    if (t.kind === "LIST") return `[${inner}]`;
-    if (t.kind === "NON_NULL") return `${inner}!`;
-    return inner;
-  }
-  return t.kind;
-}
+import { out } from "../output.js";
+import { parseArgs } from "../args.js";
+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> | ...]"
+    );
+
+  const { spec } = await resolveSpec(flags);
+
+  if (spec.type === "openapi") {
+    showOpenAPI(spec, target);
+  } else if (spec.type === "mcp") {
+    showMCP(spec, target);
+  } else {
+    showGraphQL(spec, target);
+  }
+}
+
+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
+  );
+
+  if (!op) {
+    throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
+  }
+
+  const root = spec.raw || spec.components;
+
+  out({
+    id: op.id,
+    method: op.method,
+    path: op.path,
+    summary: op.summary,
+    description: op.description,
+    tags: op.tags,
+    deprecated: op.deprecated,
+    parameters: op.parameters.map((p) => {
+      const resolved = resolveRef(p, root);
+      return {
+        name: resolved.name,
+        in: resolved.in,
+        required: resolved.required || false,
+        type: resolved.schema?.type || null,
+        format: resolved.schema?.format || undefined,
+        description: resolved.description || undefined,
+        enum: resolved.schema?.enum || undefined,
+      };
+    }),
+    requestBody: op.requestBody ? resolveRequestBody(op.requestBody, root) : null,
+    responses: resolveResponsesCompact(op.responses, root),
+  });
+}
+
+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();
+
+  const op = spec.operations.find((o) => o.name.toLowerCase() === lower);
+
+  if (!op) {
+    throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
+  }
+
+  const relatedTypes = findRelatedTypes(op, spec.types);
+
+  out({
+    name: op.name,
+    kind: op.kind,
+    description: op.description,
+    returnType: op.returnType,
+    isDeprecated: op.isDeprecated,
+    args: op.args?.map((a) => ({
+      name: a.name,
+      type: flattenType(a.type),
+      required: a.type?.kind === "NON_NULL",
+      description: a.description || undefined,
+      defaultValue: a.defaultValue || undefined,
+    })),
+    relatedTypes,
+  });
+}
+
+// --- Helpers ---
+
+function resolveRef(obj, root) {
+  if (!obj || typeof obj !== "object") return obj;
+  if (obj.$ref) {
+    const path = obj.$ref.replace("#/", "").split("/");
+    let resolved = root;
+    for (const p of path) resolved = resolved?.[p];
+    return resolved || obj;
+  }
+  return obj;
+}
+
+function resolveRequestBody(body, root) {
+  if (!body) return null;
+  const resolved = resolveRef(body, root);
+  if (resolved?.content) {
+    const jsonContent = resolved.content["application/json"];
+    if (jsonContent) {
+      return {
+        description: resolved.description || undefined,
+        required: resolved.required || undefined,
+        schema: resolveSchema(jsonContent.schema, root),
+      };
+    }
+    const [mediaType, value] = Object.entries(resolved.content)[0];
+    return {
+      description: resolved.description || undefined,
+      required: resolved.required || undefined,
+      mediaType,
+      schema: resolveSchema(value.schema, root),
+    };
+  }
+  return resolved;
+}
+
+function resolveResponsesCompact(responses, root) {
+  if (!responses) return null;
+  const result = {};
+  for (const [code, resp] of Object.entries(responses)) {
+    const resolved = resolveRef(resp, root);
+    if (resolved?.content) {
+      const jsonContent = resolved.content["application/json"];
+      result[code] = jsonContent
+        ? { description: resolved.description, schema: resolveSchema(jsonContent.schema, root) }
+        : { description: resolved.description };
+    } else {
+      result[code] = { description: resolved.description };
+    }
+  }
+  return result;
+}
+
+function resolveSchema(schema, root, depth = 0) {
+  if (!schema || depth > 3) return schema;
+  if (schema.$ref) return resolveSchema(resolveRef(schema, root), root, depth + 1);
+  if (schema.properties) {
+    const result = { type: schema.type, required: schema.required, properties: {} };
+    for (const [key, val] of Object.entries(schema.properties)) {
+      if (val.$ref) {
+        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 {
+        const prop = { type: val.type };
+        if (val.format) prop.format = val.format;
+        if (val.enum) prop.enum = val.enum;
+        if (val.description) prop.description = val.description;
+        result.properties[key] = prop;
+      }
+    }
+    return result;
+  }
+  if (schema.items) {
+    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;
+}
+
+function findRelatedTypes(op, types) {
+  const names = new Set();
+
+  function extractTypeNames(typeStr) {
+    if (!typeStr) return;
+    const cleaned = typeStr.replace(/[[\]!]/g, "");
+    if (cleaned) names.add(cleaned);
+  }
+
+  extractTypeNames(op.returnType);
+  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);
+      return result;
+    });
+}
+
+function flattenType(t) {
+  if (!t) return null;
+  if (t.name) return t.kind === "NON_NULL" ? `${t.name}!` : t.name;
+  if (t.ofType) {
+    const inner = flattenType(t.ofType);
+    if (t.kind === "LIST") return `[${inner}]`;
+    if (t.kind === "NON_NULL") return `${inner}!`;
+    return inner;
+  }
+  return t.kind;
+}

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