ctx7 0.5.1 → 0.5.3

package/dist/index.js

@@ -152,15 +152,24 @@ function getGitHubHeaders() {
     ...ghToken && { Authorization: `token ${ghToken}` }
   };
 }
+async function extractGitHubError(response) {
+  let detail = `HTTP ${response.status}`;
+  try {
+    const body = await response.json();
+    if (body.message) detail += `: ${body.message}`;
+  } catch {
+  }
+  return detail;
+}
 async function fetchRepoTree(owner, repo, branch, headers) {
   const treeUrl = `${GITHUB_API}/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
   const response = await fetch(treeUrl, { headers });
-  if (!response.ok) return null;
+  if (!response.ok) return { error: await extractGitHubError(response) };
   return await response.json();
 }
 async function fetchDefaultBranch(owner, repo, headers) {
   const response = await fetch(`${GITHUB_API}/repos/${owner}/${repo}`, { headers });
-  if (!response.ok) return { status: response.status };
+  if (!response.ok) return { error: await extractGitHubError(response), status: response.status };
   const data = await response.json();
   return { branch: data.default_branch };
 }
@@ -171,9 +180,12 @@ async function listSkillsFromGitHub(project) {
     const [owner, repo] = parts;
     const headers = getGitHubHeaders();
     const branchResult = await fetchDefaultBranch(owner, repo, headers);
-    if ("status" in branchResult) return { status: "repo_not_found" };
+    if ("error" in branchResult) {
+      if (branchResult.status === 404) return { status: "repo_not_found" };
+      return { status: "error", error: branchResult.error };
+    }
     const treeData = await fetchRepoTree(owner, repo, branchResult.branch, headers);
-    if (!treeData) return { status: "error", error: "Could not fetch repository tree" };
+    if ("error" in treeData) return { status: "error", error: treeData.error };
     const skillMdFiles = treeData.tree.filter(
       (item) => item.type === "blob" && item.path.toLowerCase().endsWith("skill.md")
     );
@@ -214,8 +226,9 @@ async function downloadSkillFromGitHub(skill) {
     const { owner, repo, branch, path: skillPath } = parsed;
     const ghHeaders = getGitHubHeaders();
     const treeData = await fetchRepoTree(owner, repo, branch, ghHeaders);
-    if (!treeData) {
-      return { files: [], error: `GitHub API error` };
+    if ("error" in treeData) {
+      const hint = !ghHeaders["Authorization"] && /403|429|rate/.test(treeData.error) ? " \u2014 run `gh auth login` or set the GITHUB_TOKEN env var to increase rate limits" : "";
+      return { files: [], error: `GitHub API error: ${treeData.error}${hint}` };
     }
     const skillFiles = treeData.tree.filter(
       (item) => item.type === "blob" && item.path.startsWith(skillPath + "/")
@@ -925,48 +938,153 @@ function trackEvent(event, data) {
 // src/commands/generate.ts
 import pc6 from "picocolors";
 import ora2 from "ora";
-import { mkdir as mkdir2, writeFile as writeFile2, readFile, unlink } from "fs/promises";
+import { mkdir as mkdir3, writeFile as writeFile2, readFile, unlink } from "fs/promises";
 import { join as join4 } from "path";
 import { homedir as homedir3 } from "os";
 import { spawn } from "child_process";
 import { input, select as select2 } from "@inquirer/prompts";
 
 // src/utils/auth.ts
+import * as fs2 from "fs";
+import * as os2 from "os";
+
+// src/utils/storage-paths.ts
 import * as fs from "fs";
-import * as path from "path";
+import { access as access2, chmod, mkdir as mkdir2, rename } from "fs/promises";
 import * as os from "os";
-var CONFIG_DIR = path.join(os.homedir(), ".context7");
-var CREDENTIALS_FILE = path.join(CONFIG_DIR, "credentials.json");
+import * as path from "path";
+var APP_DIR = "context7";
+var LEGACY_DIR = ".context7";
+var CREDENTIALS_FILE_NAME = "credentials.json";
+var UPDATE_STATE_FILE_NAME = "cli-state.json";
+var PREVIEWS_DIR_NAME = "previews";
+function xdgBase(envVar, ...defaultSegments) {
+  const value = process.env[envVar];
+  const base = value && path.isAbsolute(value) ? value : path.join(os.homedir(), ...defaultSegments);
+  return path.join(base, APP_DIR);
+}
+function getConfigDir() {
+  return xdgBase("XDG_CONFIG_HOME", ".config");
+}
+function getStateDir() {
+  return xdgBase("XDG_STATE_HOME", ".local", "state");
+}
+function getCacheDir() {
+  return xdgBase("XDG_CACHE_HOME", ".cache");
+}
+function getCredentialsFilePath() {
+  return path.join(getConfigDir(), CREDENTIALS_FILE_NAME);
+}
+function getUpdateStateFilePath() {
+  return path.join(getStateDir(), UPDATE_STATE_FILE_NAME);
+}
+function getPreviewsDir() {
+  return path.join(getCacheDir(), PREVIEWS_DIR_NAME);
+}
+function getLegacyFilePath(fileName) {
+  return path.join(os.homedir(), LEGACY_DIR, fileName);
+}
+function migrateLegacyFileSync(fileName, targetPath, mode) {
+  const legacyPath = getLegacyFilePath(fileName);
+  if (legacyPath === targetPath || fs.existsSync(targetPath) || !fs.existsSync(legacyPath)) {
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true, mode: 448 });
+    fs.renameSync(legacyPath, targetPath);
+    if (mode !== void 0) {
+      fs.chmodSync(targetPath, mode);
+    }
+  } catch {
+  }
+}
+async function migrateLegacyFile(fileName, targetPath, mode) {
+  const legacyPath = getLegacyFilePath(fileName);
+  if (legacyPath === targetPath || await exists(targetPath) || !await exists(legacyPath)) {
+    return;
+  }
+  try {
+    await mkdir2(path.dirname(targetPath), { recursive: true, mode: 448 });
+    await rename(legacyPath, targetPath);
+    if (mode !== void 0) {
+      await chmod(targetPath, mode);
+    }
+  } catch {
+  }
+}
+function resolveReadPathSync(fileName, targetPath, mode) {
+  migrateLegacyFileSync(fileName, targetPath, mode);
+  if (fs.existsSync(targetPath)) {
+    return targetPath;
+  }
+  const legacyPath = getLegacyFilePath(fileName);
+  return fs.existsSync(legacyPath) ? legacyPath : targetPath;
+}
+async function resolveReadPath(fileName, targetPath, mode) {
+  await migrateLegacyFile(fileName, targetPath, mode);
+  if (await exists(targetPath)) {
+    return targetPath;
+  }
+  const legacyPath = getLegacyFilePath(fileName);
+  return await exists(legacyPath) ? legacyPath : targetPath;
+}
+async function exists(filePath) {
+  try {
+    await access2(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/utils/auth.ts
 function ensureConfigDir() {
-  if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  const configDir = getConfigDir();
+  if (!fs2.existsSync(configDir)) {
+    fs2.mkdirSync(configDir, { recursive: true, mode: 448 });
   }
 }
+var CREDENTIALS_MODE = 384;
 function saveTokens(tokens) {
+  const credentialsFile = getCredentialsFilePath();
+  migrateLegacyFileSync(CREDENTIALS_FILE_NAME, credentialsFile, CREDENTIALS_MODE);
   ensureConfigDir();
   const data = {
     ...tokens,
     expires_at: tokens.expires_at ?? (tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0)
   };
-  fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(data, null, 2), { mode: 384 });
+  fs2.writeFileSync(credentialsFile, JSON.stringify(data, null, 2), { mode: CREDENTIALS_MODE });
+  fs2.chmodSync(credentialsFile, CREDENTIALS_MODE);
 }
 function loadTokens() {
-  if (!fs.existsSync(CREDENTIALS_FILE)) {
+  const credentialsFile = resolveReadPathSync(
+    CREDENTIALS_FILE_NAME,
+    getCredentialsFilePath(),
+    CREDENTIALS_MODE
+  );
+  if (!fs2.existsSync(credentialsFile)) {
     return null;
   }
   try {
-    const data = JSON.parse(fs.readFileSync(CREDENTIALS_FILE, "utf-8"));
+    const data = JSON.parse(fs2.readFileSync(credentialsFile, "utf-8"));
     return data;
   } catch {
     return null;
   }
 }
 function clearTokens() {
-  if (fs.existsSync(CREDENTIALS_FILE)) {
-    fs.unlinkSync(CREDENTIALS_FILE);
-    return true;
+  const credentialsFile = getCredentialsFilePath();
+  let removed = false;
+  if (fs2.existsSync(credentialsFile)) {
+    fs2.unlinkSync(credentialsFile);
+    removed = true;
   }
-  return false;
+  const legacyCredentialsFile = getLegacyFilePath(CREDENTIALS_FILE_NAME);
+  if (fs2.existsSync(legacyCredentialsFile)) {
+    fs2.unlinkSync(legacyCredentialsFile);
+    removed = true;
+  }
+  return removed;
 }
 function isTokenExpired(tokens) {
   if (!tokens.expires_at) {
@@ -1012,7 +1130,7 @@ var DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5;
 async function startDeviceAuthorization(baseUrl3, clientId) {
   const params = new URLSearchParams({ client_id: clientId });
   try {
-    const hostname2 = os.hostname();
+    const hostname2 = os2.hostname();
     if (hostname2) params.set("hostname", hostname2);
   } catch {
   }
@@ -1686,8 +1804,8 @@ async function generateCommand(options) {
       log.blank();
     };
     const openInEditor = async () => {
-      const previewDir = join4(homedir3(), ".context7", "previews");
-      await mkdir2(previewDir, { recursive: true });
+      const previewDir = getPreviewsDir();
+      await mkdir3(previewDir, { recursive: true });
       previewFile = join4(previewDir, `${skillName}.md`);
       if (!previewFileWritten) {
         await writeFile2(previewFile, generatedContent, "utf-8");
@@ -1767,7 +1885,7 @@ async function generateCommand(options) {
     const skillDir = join4(finalDir, skillName);
     const skillPath = join4(skillDir, "SKILL.md");
     try {
-      await mkdir2(skillDir, { recursive: true });
+      await mkdir3(skillDir, { recursive: true });
       await writeFile2(skillPath, generatedContent, "utf-8");
     } catch (err) {
       const error = err;
@@ -2619,12 +2737,12 @@ ${headerLine}`,
 import pc8 from "picocolors";
 import ora4 from "ora";
 import { select as select3 } from "@inquirer/prompts";
-import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname6, join as join8 } from "path";
+import { mkdir as mkdir5, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname7, join as join8 } from "path";
 import { randomBytes } from "crypto";
 
 // src/setup/agents.ts
-import { access as access2 } from "fs/promises";
+import { access as access3 } from "fs/promises";
 import { join as join7 } from "path";
 import { homedir as homedir5 } from "os";
 var SETUP_AGENT_NAMES = {
@@ -2828,7 +2946,7 @@ function getAgent(name) {
 var ALL_AGENT_NAMES = Object.keys(agents);
 async function pathExists(p) {
   try {
-    await access2(p);
+    await access3(p);
     return true;
   } catch {
     return false;
@@ -2937,8 +3055,8 @@ function customizeSkillFilesForAgent(agent, skillName, files) {
 }
 
 // src/setup/mcp-writer.ts
-import { access as access3, readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname5 } from "path";
+import { access as access4, readFile as readFile3, writeFile as writeFile3, mkdir as mkdir4 } from "fs/promises";
+import { dirname as dirname6 } from "path";
 function stripJsonComments(text) {
   let result = "";
   let i = 0;
@@ -3009,7 +3127,7 @@ function removeServerEntry(existing, configKey, serverName) {
 async function resolveMcpPath(candidates) {
   for (const candidate of candidates) {
     try {
-      await access3(candidate);
+      await access4(candidate);
       return candidate;
     } catch {
     }
@@ -3017,7 +3135,7 @@ async function resolveMcpPath(candidates) {
   return candidates[0];
 }
 async function writeJsonConfig(filePath, config) {
-  await mkdir3(dirname5(filePath), { recursive: true });
+  await mkdir4(dirname6(filePath), { recursive: true });
   await writeFile3(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
 async function readTomlServerExists(filePath, serverName) {
@@ -3137,11 +3255,11 @@ async function appendTomlServer(filePath, serverName, entry) {
     const before = rawBefore.length > 0 ? rawBefore + "\n\n" : "";
     const after = rawAfter.length > 0 ? "\n" + rawAfter : "";
     const content = before + block + after;
-    await mkdir3(dirname5(filePath), { recursive: true });
+    await mkdir4(dirname6(filePath), { recursive: true });
     await writeFile3(filePath, content, "utf-8");
   } else {
     const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
-    await mkdir3(dirname5(filePath), { recursive: true });
+    await mkdir4(dirname6(filePath), { recursive: true });
     await writeFile3(filePath, existing + separator + block, "utf-8");
   }
   return { alreadyExists };
@@ -3174,7 +3292,7 @@ async function removeTomlServer(filePath, serverName) {
   const rawBefore = existing.slice(0, startIdx).replace(/\n+$/, "");
   const rawAfter = existing.slice(startIdx + sectionHeader.length + endOffset).replace(/^\n+/, "");
   const content = [rawBefore, rawAfter].filter(Boolean).join("\n\n");
-  await mkdir3(dirname5(filePath), { recursive: true });
+  await mkdir4(dirname6(filePath), { recursive: true });
   await writeFile3(filePath, content.length > 0 ? `${content}
 ` : "", "utf-8");
   return { removed: true };
@@ -3320,7 +3438,7 @@ async function installRule(agentName, mode, scope) {
   if (rule.kind === "file") {
     const ruleDir = scope === "global" ? rule.dir("global") : join8(process.cwd(), rule.dir("project"));
     const rulePath = join8(ruleDir, rule.filename);
-    await mkdir4(dirname6(rulePath), { recursive: true });
+    await mkdir5(dirname7(rulePath), { recursive: true });
     await writeFile4(rulePath, content, "utf-8");
     return { status: "installed", path: rulePath };
   }
@@ -3340,7 +3458,7 @@ ${content}${rule.sectionMarker}`;
     return { status: "updated", path: filePath };
   }
   const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
-  await mkdir4(dirname6(filePath), { recursive: true });
+  await mkdir5(dirname7(filePath), { recursive: true });
   await writeFile4(filePath, existing + separator + section + "\n", "utf-8");
   return { status: "installed", path: filePath };
 }
@@ -3411,6 +3529,20 @@ async function setupAgent(agentName, auth, transport, scope) {
     skillPath
   };
 }
+function logSkillStatus(skillStatus, skillPath) {
+  const skillFailed = skillStatus.startsWith("failed:");
+  const skillIcon = skillStatus === "installed" ? pc8.green("+") : skillFailed ? pc8.red("\u2716") : pc8.dim("~");
+  log.plain(`    ${skillIcon} Skill ${skillFailed ? "failed" : skillStatus}`);
+  log.plain(`      ${pc8.dim(skillPath)}`);
+  if (skillFailed) {
+    log.plain(`      ${pc8.red(skillStatus.slice("failed: ".length))}`);
+    if (skillStatus.includes("EACCES")) {
+      log.plain(
+        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname7(dirname7(skillPath))}`)}`
+      );
+    }
+  }
+}
 async function setupMcp(agents2, options, scope) {
   const transport = resolveTransport(options);
   if (transport === "stdio" && options.oauth) {
@@ -3439,14 +3571,7 @@ async function setupMcp(agents2, options, scope) {
     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)}`);
-    if (r.skillStatus.includes("EACCES")) {
-      log.plain(
-        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname6(dirname6(r.skillPath))}`)}`
-      );
-    }
+    logSkillStatus(r.skillStatus, r.skillPath);
   }
   log.blank();
   trackEvent("setup", { agents: agents2, scope, authMode: auth.mode });
@@ -3492,22 +3617,16 @@ async function setupCli(options) {
   const installSpinner = ora4("Installing...").start();
   const results = [];
   for (const agentName of agents2) {
-    installSpinner.text = `Setting up ${getAgent(agentName).displayName}...`;
+    const agentDef = getAgent(agentName);
+    installSpinner.text = `Setting up ${agentDef.displayName}...`;
     const r = await setupCliAgent(agentName, scope, downloadData);
-    results.push({ agent: getAgent(agentName).displayName, ...r });
+    results.push({ agent: agentDef.displayName, ...r });
   }
   installSpinner.succeed("Context7 CLI setup complete");
   log.blank();
   for (const r of results) {
     log.plain(`  ${pc8.bold(r.agent)}`);
-    const skillIcon = r.skillStatus === "installed" ? pc8.green("+") : pc8.dim("~");
-    log.plain(`    ${skillIcon} Skill ${r.skillStatus}`);
-    log.plain(`      ${pc8.dim(r.skillPath)}`);
-    if (r.skillStatus.includes("EACCES")) {
-      log.plain(
-        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname6(dirname6(r.skillPath))}`)}`
-      );
-    }
+    logSkillStatus(r.skillStatus, r.skillPath);
     const ruleIcon = r.ruleStatus === "installed" || r.ruleStatus === "updated" ? pc8.green("+") : pc8.dim("~");
     log.plain(`    ${ruleIcon} Rule ${r.ruleStatus}`);
     log.plain(`      ${pc8.dim(r.rulePath)}`);
@@ -3538,7 +3657,7 @@ async function setupCommand(options) {
 import pc9 from "picocolors";
 import ora5 from "ora";
 import { join as join9 } from "path";
-import { access as access4, readFile as readFile5, rm as rm3, writeFile as writeFile5 } from "fs/promises";
+import { access as access5, readFile as readFile5, rm as rm3, writeFile as writeFile5 } from "fs/promises";
 var CHECKBOX_THEME2 = {
   style: {
     highlight: (text) => pc9.green(text),
@@ -3638,7 +3757,7 @@ function resolveFlagModes(options) {
 }
 async function pathExists2(path2) {
   try {
-    await access4(path2);
+    await access5(path2);
     return true;
   } catch {
     return false;
@@ -3885,6 +4004,18 @@ async function removeCommand2(options) {
 // src/commands/docs.ts
 import pc10 from "picocolors";
 import ora6 from "ora";
+
+// src/utils/library-id.ts
+function recoverLibraryId(input2) {
+  if (input2.startsWith("//")) return input2.replace(/^\/+/, "/");
+  if (input2.startsWith("/")) return input2;
+  if (!/^[A-Za-z]:[\\/]/.test(input2)) return input2;
+  const normalized = input2.replace(/\\/g, "/");
+  const match = normalized.match(/^[A-Za-z]:\/.*?\/(?:Git|PortableGit|git-bash)\/(.+)$/i);
+  return match ? `/${match[1]}` : input2;
+}
+
+// src/commands/docs.ts
 var isTTY = process.stdout.isTTY;
 function getReputationLabel(score) {
   if (score === void 0 || score < 0) return "Unknown";
@@ -3970,10 +4101,16 @@ async function resolveCommand(library, query, options) {
 }
 async function queryCommand(libraryId, query, options) {
   trackEvent("command", { name: "docs" });
+  libraryId = recoverLibraryId(libraryId);
   if (!libraryId.startsWith("/") || !/^\/[^/]+\/[^/]/.test(libraryId)) {
     log.error(`Invalid library ID: "${libraryId}"`);
     log.info(`Expected format: /owner/repo or /owner/repo/version (e.g., /facebook/react)`);
     log.info(`Run "ctx7 library <name>" to find the correct ID`);
+    if (process.platform === "win32") {
+      log.info(
+        `On Git Bash, prefix the ID with an extra slash to avoid path conversion: ctx7 docs "//facebook/react" "<your question>"`
+      );
+    }
     process.exitCode = 1;
     return;
   }
@@ -4057,25 +4194,36 @@ import { spawn as spawn2 } from "child_process";
 import pc11 from "picocolors";
 
 // src/utils/update-check.ts
-import { homedir as homedir6 } from "os";
-import { dirname as dirname7, join as join10 } from "path";
-import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile6 } from "fs/promises";
+import { dirname as dirname8 } from "path";
+import { mkdir as mkdir6, readFile as readFile6, writeFile as writeFile6 } from "fs/promises";
 var DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
-var UPDATE_STATE_FILE = join10(homedir6(), ".context7", "cli-state.json");
 function getStateFilePath(stateFile) {
-  return stateFile ?? UPDATE_STATE_FILE;
+  return stateFile ?? getUpdateStateFilePath();
+}
+async function readStateFilePath(stateFile) {
+  if (stateFile) {
+    return stateFile;
+  }
+  return resolveReadPath(UPDATE_STATE_FILE_NAME, getUpdateStateFilePath());
+}
+async function writeStateFilePath(stateFile) {
+  const path2 = getStateFilePath(stateFile);
+  if (!stateFile) {
+    await migrateLegacyFile(UPDATE_STATE_FILE_NAME, path2);
+  }
+  return path2;
 }
 async function readUpdateState(stateFile) {
   try {
-    const raw = await readFile6(getStateFilePath(stateFile), "utf-8");
+    const raw = await readFile6(await readStateFilePath(stateFile), "utf-8");
     return JSON.parse(raw);
   } catch {
     return {};
   }
 }
 async function writeUpdateState(state, stateFile) {
-  const path2 = getStateFilePath(stateFile);
-  await mkdir5(dirname7(path2), { recursive: true });
+  const path2 = await writeStateFilePath(stateFile);
+  await mkdir6(dirname8(path2), { recursive: true });
   await writeFile6(path2, JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
 function compareVersions(a, b) {
@@ -4379,7 +4527,7 @@ var brand = {
   dim: pc12.dim
 };
 var program = new Command();
-program.name("ctx7").description("Context7 CLI - Fetch documentation context and configure Context7").version(VERSION).option("--base-url <url>").hook("preAction", (thisCommand) => {
+program.name("ctx7").description("Context7 CLI - Fetch documentation context and configure Context7").version(VERSION, "-v, --version").option("--base-url <url>").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
   if (opts.baseUrl) {
     setBaseUrl(opts.baseUrl);