ctx7 0.3.1 → 0.3.3

package/README.md

@@ -1,6 +1,6 @@
 # ctx7
 
-CLI for the [Context7 Skills Registry](https://context7.com) - install and manage AI coding skills across different AI coding assistants.
+CLI for [Context7](https://context7.com) - query up-to-date library documentation and manage AI coding skills.
 
 Skills are reusable prompt instructions that enhance your AI coding assistant with specialized capabilities like working with specific frameworks, libraries, or coding patterns.
 
@@ -26,6 +26,18 @@ ctx7 setup --claude
 ctx7 setup --opencode
 ```
 
+### Library Documentation
+
+```bash
+# Find a library
+ctx7 library react
+ctx7 library nextjs "app router"
+
+# Get documentation
+ctx7 docs /facebook/react "useEffect cleanup"
+ctx7 docs /vercel/next.js "middleware"
+```
+
 ### Skills
 
 ```bash
@@ -44,6 +56,32 @@ ctx7 skills list --claude
 
 ## Usage
 
+### Find a library
+
+Resolve a library name to a Context7 library ID.
+
+```bash
+ctx7 library react
+ctx7 library nextjs "app router setup"
+ctx7 library prisma "database relations"
+
+# Output as JSON
+ctx7 library react --json
+```
+
+### Query documentation
+
+Fetch documentation for a specific library using its Context7 ID.
+
+```bash
+ctx7 docs /facebook/react "useEffect cleanup"
+ctx7 docs /vercel/next.js "middleware authentication"
+ctx7 docs /prisma/prisma "one-to-many relations"
+
+# Output as JSON
+ctx7 docs /facebook/react "hooks" --json
+```
+
 ### Setup
 
 Configure Context7 MCP and a rule for your AI coding agents. Authenticates via OAuth, generates an API key, and writes the config.

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import pc9 from "picocolors";
+import pc10 from "picocolors";
 import figlet from "figlet";
 
 // src/commands/skill.ts
@@ -289,6 +289,65 @@ async function handleGenerateResponse(response, libraryName, onEvent) {
   }
   return { content, libraryName: finalLibraryName, error };
 }
+function getAuthHeaders(accessToken) {
+  const headers = {};
+  const apiKey = process.env.CONTEXT7_API_KEY;
+  if (apiKey) {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  } else if (accessToken) {
+    headers["Authorization"] = `Bearer ${accessToken}`;
+  }
+  return headers;
+}
+async function resolveLibrary(libraryName, query, accessToken) {
+  const params = new URLSearchParams({ libraryName });
+  if (query) {
+    params.set("query", query);
+  }
+  const response = await fetch(`${baseUrl}/api/v2/libs/search?${params}`, {
+    headers: getAuthHeaders(accessToken)
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    return {
+      results: [],
+      error: errorData.error || `HTTP error ${response.status}`,
+      message: errorData.message
+    };
+  }
+  return await response.json();
+}
+async function getLibraryContext(libraryId, query, options, accessToken) {
+  const params = new URLSearchParams({ libraryId, query });
+  if (options?.type) {
+    params.set("type", options.type);
+  }
+  const response = await fetch(`${baseUrl}/api/v2/context?${params}`, {
+    headers: getAuthHeaders(accessToken)
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    if (response.status === 301 && errorData.redirectUrl) {
+      return {
+        codeSnippets: [],
+        infoSnippets: [],
+        error: errorData.error || "library_redirected",
+        message: errorData.message,
+        redirectUrl: errorData.redirectUrl
+      };
+    }
+    return {
+      codeSnippets: [],
+      infoSnippets: [],
+      error: errorData.error || `HTTP error ${response.status}`,
+      message: errorData.message
+    };
+  }
+  if (options?.type === "txt") {
+    return await response.text();
+  }
+  return await response.json();
+}
 
 // src/utils/logger.ts
 import pc from "picocolors";
@@ -483,7 +542,7 @@ ${pc3.dim(pathLines.join("\n"))}`,
   }
   const universalLabel = `Universal \u2014 ${UNIVERSAL_AGENTS_LABEL} ${pc3.dim(`(${universalPath})`)}`;
   const choices = [
-    { name: universalLabel, value: "universal", checked: true }
+    { name: universalLabel, value: "universal", checked: false }
   ];
   for (const ide of VENDOR_SPECIFIC_AGENTS) {
     choices.push({
@@ -1175,6 +1234,12 @@ async function generateCommand(options) {
   }
   searchSpinner.succeed(pc6.green(`Found ${searchResult.results.length} relevant sources`));
   log.blank();
+  if (searchResult.searchFilterApplied) {
+    log.warn(
+      "Your results only include libraries matching your access settings. To search across all public libraries, update your settings at https://context7.com/dashboard?tab=libraries"
+    );
+    log.blank();
+  }
   let selectedLibraries;
   try {
     const formatProjectId = (id) => {
@@ -1853,11 +1918,14 @@ async function searchCommand(query) {
   trackEvent("search_query", { query, resultCount: data.results.length });
   log.blank();
   const indexWidth = data.results.length.toString().length;
-  const maxNameLen = Math.max(...data.results.map((s) => s.name.length));
+  const nameWithRepo = (s) => `${s.name} ${pc7.dim(`(${s.project})`)}`;
+  const nameWithRepoLen = (s) => `${s.name} (${s.project})`.length;
+  const maxNameLen = Math.max(...data.results.map(nameWithRepoLen));
   const installsColWidth = 10;
   const choices = data.results.map((s, index) => {
     const indexStr = pc7.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
-    const paddedName = s.name.padEnd(maxNameLen);
+    const rawLen = nameWithRepoLen(s);
+    const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen);
     const installsRaw = s.installCount ? String(s.installCount) : "-";
     const paddedInstalls = formatInstallCount(s.installCount, pc7.dim("-")) + " ".repeat(installsColWidth - installsRaw.length);
     const trust = formatTrustScore(s.trustScore);
@@ -1876,7 +1944,7 @@ async function searchCommand(query) {
       pc7.white(s.description || "No description")
     ];
     return {
-      name: `${indexStr} ${paddedName} ${paddedInstalls}${trust}`,
+      name: `${indexStr} ${displayName} ${paddedInstalls}${trust}`,
       value: s,
       description: metadataLines.join("\n")
     };
@@ -2124,14 +2192,17 @@ async function suggestCommand(options) {
   searchSpinner.succeed(`Found ${skills.length} relevant skill(s)`);
   trackEvent("suggest_results", { depCount: deps.length, skillCount: skills.length });
   log.blank();
-  const maxNameLen = Math.max(...skills.map((s) => s.name.length));
+  const nameWithRepo = (s) => `${s.name} ${pc7.dim(`(${s.project})`)}`;
+  const nameWithRepoLen = (s) => `${s.name} (${s.project})`.length;
+  const maxNameLen = Math.max(...skills.map(nameWithRepoLen));
   const installsColWidth = 10;
   const trustColWidth = 12;
   const maxMatchedLen = Math.max(...skills.map((s) => s.matchedDep.length));
   const indexWidth = skills.length.toString().length;
   const choices = skills.map((s, index) => {
     const indexStr = pc7.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
-    const paddedName = s.name.padEnd(maxNameLen);
+    const rawLen = nameWithRepoLen(s);
+    const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen);
     const installsRaw = s.installCount ? String(s.installCount) : "-";
     const paddedInstalls = formatInstallCount(s.installCount, pc7.dim("-")) + " ".repeat(installsColWidth - installsRaw.length);
     const trustRaw = s.trustScore !== void 0 && s.trustScore >= 0 ? s.trustScore.toFixed(1) : "-";
@@ -2153,7 +2224,7 @@ async function suggestCommand(options) {
       pc7.white(s.description || "No description")
     ];
     return {
-      name: `${indexStr} ${paddedName} ${paddedInstalls}${trust}${matched}`,
+      name: `${indexStr} ${displayName} ${paddedInstalls}${trust}${matched}`,
       value: s,
       description: metadataLines.join("\n")
     };
@@ -2687,6 +2758,175 @@ async function setupCommand(options) {
   trackEvent("setup", { agents: agents2, scope, authMode: auth.mode });
 }
 
+// src/commands/docs.ts
+import pc9 from "picocolors";
+import ora5 from "ora";
+var isTTY = process.stdout.isTTY;
+function getReputationLabel(score) {
+  if (score === void 0 || score < 0) return "Unknown";
+  if (score >= 7) return "High";
+  if (score >= 4) return "Medium";
+  return "Low";
+}
+function getAccessToken() {
+  const tokens = loadTokens();
+  if (!tokens || isTokenExpired(tokens)) return void 0;
+  return tokens.access_token;
+}
+function formatLibraryResult(lib, index) {
+  const lines = [];
+  lines.push(`${pc9.dim(`${index + 1}.`)} ${pc9.bold(`Title: ${lib.title}`)}`);
+  lines.push(`   ${pc9.cyan(`Context7-compatible library ID: ${lib.id}`)}`);
+  if (lib.description) {
+    lines.push(`   ${pc9.dim(`Description: ${lib.description}`)}`);
+  }
+  if (lib.totalSnippets) {
+    lines.push(`   ${pc9.dim(`Code Snippets: ${lib.totalSnippets}`)}`);
+  }
+  if (lib.trustScore !== void 0) {
+    lines.push(`   ${pc9.dim(`Source Reputation: ${getReputationLabel(lib.trustScore)}`)}`);
+  }
+  if (lib.benchmarkScore !== void 0 && lib.benchmarkScore > 0) {
+    lines.push(`   ${pc9.dim(`Benchmark Score: ${lib.benchmarkScore}`)}`);
+  }
+  if (lib.versions && lib.versions.length > 0) {
+    lines.push(`   ${pc9.dim(`Versions: ${lib.versions.join(", ")}`)}`);
+  }
+  return lines.join("\n");
+}
+async function resolveCommand(library, query, options) {
+  trackEvent("command", { name: "library" });
+  const spinner = isTTY ? ora5(`Searching for "${library}"...`).start() : null;
+  const accessToken = getAccessToken();
+  let data;
+  try {
+    data = await resolveLibrary(library, query, accessToken);
+  } catch (err) {
+    spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    if (!spinner) log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (data.error) {
+    spinner?.fail(data.message || data.error);
+    if (!spinner) log.error(data.message || data.error);
+    process.exitCode = 1;
+    return;
+  }
+  if (!data.results || data.results.length === 0) {
+    spinner?.warn(`No libraries found matching "${library}"`);
+    if (!spinner) log.warn(`No libraries found matching "${library}"`);
+    return;
+  }
+  const results = data.results;
+  spinner?.stop();
+  if (options.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  log.blank();
+  if (data.searchFilterApplied) {
+    log.warn(
+      "Your results only include libraries matching your access settings. To search across all public libraries, update your settings at https://context7.com/dashboard?tab=libraries"
+    );
+    log.blank();
+  }
+  for (let i = 0; i < results.length; i++) {
+    log.plain(formatLibraryResult(results[i], i));
+    log.blank();
+  }
+  if (isTTY && results.length > 0) {
+    const best = results[0];
+    log.plain(
+      `${pc9.bold("Quick command:")}
+  ${pc9.cyan(`ctx7 docs "${best.id}" "<your question>"`)}`
+    );
+    log.blank();
+  }
+}
+async function queryCommand(libraryId, query, options) {
+  trackEvent("command", { name: "docs" });
+  if (!libraryId.startsWith("/")) {
+    log.error(`Invalid library ID: ${libraryId}`);
+    log.info(`Library IDs start with "/" (e.g., /facebook/react)`);
+    log.info(`Run "ctx7 library <name>" to find the correct ID`);
+    process.exitCode = 1;
+    return;
+  }
+  const spinner = isTTY ? ora5(`Fetching docs for "${libraryId}"...`).start() : null;
+  const accessToken = getAccessToken();
+  const outputType = options.json ? "json" : "txt";
+  let result;
+  try {
+    result = await getLibraryContext(libraryId, query, { type: outputType }, accessToken);
+  } catch (err) {
+    spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    if (!spinner) log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (typeof result === "string") {
+    spinner?.stop();
+    console.log(result);
+    return;
+  }
+  const ctx = result;
+  if (ctx.error) {
+    if (ctx.redirectUrl) {
+      spinner?.warn("Library has been redirected");
+      if (!spinner) log.warn("Library has been redirected");
+      log.info(`New ID: ${pc9.cyan(ctx.redirectUrl)}`);
+      log.info(`Run: ${pc9.cyan(`ctx7 docs "${ctx.redirectUrl}" "${query}"`)}`);
+      process.exitCode = 1;
+      return;
+    }
+    spinner?.fail(ctx.message || ctx.error);
+    if (!spinner) log.error(ctx.message || ctx.error);
+    process.exitCode = 1;
+    return;
+  }
+  const total = (ctx.codeSnippets?.length || 0) + (ctx.infoSnippets?.length || 0);
+  if (total === 0) {
+    spinner?.warn(`No documentation found for: "${query}"`);
+    if (!spinner) log.warn(`No documentation found for: "${query}"`);
+    return;
+  }
+  spinner?.stop();
+  if (options.json) {
+    console.log(JSON.stringify(ctx, null, 2));
+    return;
+  }
+  log.blank();
+  if (ctx.codeSnippets) {
+    for (const snippet of ctx.codeSnippets) {
+      log.plain(pc9.bold(snippet.codeTitle));
+      if (snippet.codeDescription) log.dim(snippet.codeDescription);
+      log.blank();
+      for (const code of snippet.codeList) {
+        log.plain("```" + code.language);
+        log.plain(code.code);
+        log.plain("```");
+        log.blank();
+      }
+    }
+  }
+  if (ctx.infoSnippets) {
+    for (const snippet of ctx.infoSnippets) {
+      if (snippet.breadcrumb) log.plain(pc9.bold(snippet.breadcrumb));
+      log.plain(snippet.content);
+      log.blank();
+    }
+  }
+}
+function registerDocsCommands(program2) {
+  program2.command("library").argument("<name>", "Library name to search for").argument("[query]", "Question or task for relevance ranking").option("--json", "Output as JSON").description("Resolve a library name to a Context7 library ID").action(async (name, query, options) => {
+    await resolveCommand(name, query, options);
+  });
+  program2.command("docs").argument("<libraryId>", "Context7 library ID (e.g., /facebook/react)").argument("<query>", "Question or task to get docs for").option("--json", "Output as JSON").description("Query documentation for a library").action(async (libraryId, query, options) => {
+    await queryCommand(libraryId, query, options);
+  });
+}
+
 // src/constants.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { fileURLToPath } from "url";
@@ -2698,8 +2938,8 @@ var NAME = pkg.name;
 
 // src/index.ts
 var brand = {
-  primary: pc9.green,
-  dim: pc9.dim
+  primary: pc10.green,
+  dim: pc10.dim
 };
 var program = new Command();
 program.name("ctx7").description("Context7 CLI - Manage AI coding skills and documentation context").version(VERSION).option("--base-url <url>").hook("preAction", (thisCommand) => {
@@ -2728,6 +2968,10 @@ Examples:
   ${brand.primary("npx ctx7 skills list --claude")}
   ${brand.primary("npx ctx7 skills remove pdf")}
 
+  ${brand.dim("# Query library documentation")}
+  ${brand.primary('npx ctx7 library react "how to use hooks"')}
+  ${brand.primary('npx ctx7 docs /facebook/react "useEffect examples"')}
+
 Visit ${brand.primary("https://context7.com")} to browse skills
 `
 );
@@ -2735,6 +2979,7 @@ registerSkillCommands(program);
 registerSkillAliases(program);
 registerAuthCommands(program);
 registerSetupCommand(program);
+registerDocsCommands(program);
 program.action(() => {
   console.log("");
   const banner = figlet.textSync("Context7", { font: "ANSI Shadow" });