ctx7 0.3.0 → 0.3.2

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";
@@ -2300,6 +2359,10 @@ var agents = {
       dir: (scope) => scope === "global" ? join7(homedir5(), ".claude", "rules") : join7(".claude", "rules"),
       filename: "context7.md"
     },
+    skill: {
+      name: "documentation-lookup",
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".claude", "skills") : join7(".claude", "skills")
+    },
     detect: {
       projectPaths: [".mcp.json", ".claude"],
       globalPaths: [join7(homedir5(), ".claude")]
@@ -2318,6 +2381,10 @@ var agents = {
       dir: (scope) => scope === "global" ? join7(homedir5(), ".cursor", "rules") : join7(".cursor", "rules"),
       filename: "context7.mdc"
     },
+    skill: {
+      name: "documentation-lookup",
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".cursor", "skills") : join7(".cursor", "skills")
+    },
     detect: {
       projectPaths: [".cursor"],
       globalPaths: [join7(homedir5(), ".cursor")]
@@ -2337,6 +2404,10 @@ var agents = {
       filename: "context7.md",
       instructionsGlob: (scope) => scope === "global" ? join7(homedir5(), ".config", "opencode", "rules", "*.md") : ".opencode/rules/*.md"
     },
+    skill: {
+      name: "documentation-lookup",
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".agents", "skills") : join7(".agents", "skills")
+    },
     detect: {
       projectPaths: [".opencode.json"],
       globalPaths: [join7(homedir5(), ".config", "opencode")]
@@ -2371,6 +2442,60 @@ async function detectAgents(scope) {
 }
 
 // src/setup/templates.ts
+var SKILL_CONTENT = `---
+name: documentation-lookup
+description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.
+---
+
+When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.
+
+## When to Use This Skill
+
+Activate this skill when the user:
+
+- Asks setup or configuration questions ("How do I configure Next.js middleware?")
+- Requests code involving libraries ("Write a Prisma query for...")
+- Needs API references ("What are the Supabase auth methods?")
+- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
+
+## How to Fetch Documentation
+
+### Step 1: Resolve the Library ID
+
+Call \`resolve-library-id\` with:
+
+- \`libraryName\`: The library name extracted from the user's question
+- \`query\`: The user's full question (improves relevance ranking)
+
+### Step 2: Select the Best Match
+
+From the resolution results, choose based on:
+
+- Exact or closest name match to what the user asked for
+- Higher benchmark scores indicate better documentation quality
+- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs
+
+### Step 3: Fetch the Documentation
+
+Call \`query-docs\` with:
+
+- \`libraryId\`: The selected Context7 library ID (e.g., \`/vercel/next.js\`)
+- \`query\`: The user's specific question
+
+### Step 4: Use the Documentation
+
+Incorporate the fetched documentation into your response:
+
+- Answer the user's question using current, accurate information
+- Include relevant code examples from the docs
+- Cite the library version when relevant
+
+## Guidelines
+
+- **Be specific**: Pass the user's full question as the query for better results
+- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step
+- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks
+`;
 var RULE_CONTENT = `---
 alwaysApply: true
 ---
@@ -2566,7 +2691,25 @@ async function setupAgent(agentName, auth, scope) {
   } catch (err) {
     ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
   }
-  return { agent: agent.displayName, mcpStatus, mcpPath, ruleStatus, rulePath };
+  const skillDir = scope === "global" ? agent.skill.dir("global") : join8(process.cwd(), agent.skill.dir("project"));
+  const skillPath = join8(skillDir, agent.skill.name, "SKILL.md");
+  let skillStatus;
+  try {
+    await mkdir4(dirname3(skillPath), { recursive: true });
+    await writeFile4(skillPath, SKILL_CONTENT, "utf-8");
+    skillStatus = "installed";
+  } catch (err) {
+    skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  return {
+    agent: agent.displayName,
+    mcpStatus,
+    mcpPath,
+    ruleStatus,
+    rulePath,
+    skillStatus,
+    skillPath
+  };
 }
 async function setupCommand(options) {
   trackEvent("command", { name: "setup" });
@@ -2595,11 +2738,177 @@ async function setupCommand(options) {
     const ruleIcon = r.ruleStatus === "installed" ? pc8.green("+") : pc8.dim("~");
     log.plain(`    ${ruleIcon} Rule ${r.ruleStatus}`);
     log.plain(`      ${pc8.dim(r.rulePath)}`);
+    const skillIcon = r.skillStatus === "installed" ? pc8.green("+") : pc8.dim("~");
+    log.plain(`    ${skillIcon} Skill ${r.skillStatus}`);
+    log.plain(`      ${pc8.dim(r.skillPath)}`);
   }
   log.blank();
   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 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(lib.title)} ${pc9.cyan(lib.id)}`);
+  if (lib.description) {
+    lines.push(`   ${pc9.dim(lib.description)}`);
+  }
+  const meta = [];
+  if (lib.totalSnippets) {
+    meta.push(`${lib.totalSnippets} snippets`);
+  }
+  if (lib.stars && lib.stars > 0) {
+    meta.push(`${lib.stars.toLocaleString()} stars`);
+  }
+  if (lib.trustScore !== void 0) {
+    meta.push(`trust: ${lib.trustScore}/10`);
+  }
+  if (lib.benchmarkScore !== void 0 && lib.benchmarkScore > 0) {
+    meta.push(`benchmark: ${lib.benchmarkScore}`);
+  }
+  if (meta.length > 0) {
+    lines.push(`   ${pc9.dim(meta.join(" \xB7 "))}`);
+  }
+  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();
+  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";
@@ -2611,8 +2920,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) => {
@@ -2641,6 +2950,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
 `
 );
@@ -2648,6 +2961,7 @@ registerSkillCommands(program);
 registerSkillAliases(program);
 registerAuthCommands(program);
 registerSetupCommand(program);
+registerDocsCommands(program);
 program.action(() => {
   console.log("");
   const banner = figlet.textSync("Context7", { font: "ANSI Shadow" });