ctx7 0.5.0 → 0.5.2

package/dist/index.js

@@ -925,58 +925,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 crypto from "crypto";
-import * as http from "http";
+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");
-function generatePKCE() {
-  const codeVerifier = crypto.randomBytes(32).toString("base64url");
-  const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
-  return { codeVerifier, codeChallenge };
+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 generateState() {
-  return crypto.randomBytes(16).toString("base64url");
+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) {
@@ -1017,157 +1112,12 @@ async function getValidAccessToken() {
     return null;
   }
 }
-var CALLBACK_PORT = 52417;
-function createCallbackServer(expectedState) {
-  let resolvePort;
-  let resolveResult;
-  let rejectResult;
-  let serverInstance = null;
-  const portPromise = new Promise((resolve3) => {
-    resolvePort = resolve3;
-  });
-  const resultPromise = new Promise((resolve3, reject) => {
-    resolveResult = resolve3;
-    rejectResult = reject;
-  });
-  const server = http.createServer((req, res) => {
-    const url = new URL(req.url || "/", `http://localhost`);
-    if (url.pathname === "/callback") {
-      const code = url.searchParams.get("code");
-      const state = url.searchParams.get("state");
-      const error = url.searchParams.get("error");
-      const errorDescription = url.searchParams.get("error_description");
-      res.writeHead(200, { "Content-Type": "text/html" });
-      if (error) {
-        res.end(errorPage(errorDescription || error));
-        serverInstance?.close();
-        rejectResult(new Error(errorDescription || error));
-        return;
-      }
-      if (!code || !state) {
-        res.end(errorPage("Missing authorization code or state"));
-        serverInstance?.close();
-        rejectResult(new Error("Missing authorization code or state"));
-        return;
-      }
-      if (state !== expectedState) {
-        res.end(errorPage("State mismatch - possible CSRF attack"));
-        serverInstance?.close();
-        rejectResult(new Error("State mismatch"));
-        return;
-      }
-      res.end(successPage());
-      serverInstance?.close();
-      resolveResult({ code, state });
-    } else {
-      res.writeHead(404);
-      res.end("Not found");
-    }
-  });
-  serverInstance = server;
-  server.on("error", (err) => {
-    rejectResult(err);
-  });
-  server.listen(CALLBACK_PORT, "127.0.0.1", () => {
-    resolvePort(CALLBACK_PORT);
-  });
-  const timeout = setTimeout(
-    () => {
-      server.close();
-      rejectResult(new Error("Login timed out after 5 minutes"));
-    },
-    5 * 60 * 1e3
-  );
-  return {
-    port: portPromise,
-    result: resultPromise,
-    close: () => {
-      clearTimeout(timeout);
-      server.close();
-    }
-  };
-}
-function successPage() {
-  return `<!DOCTYPE html>
-<html>
-  <head><title>Login Successful</title></head>
-  <body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #f9fafb;">
-    <div style="text-align: center; padding: 2rem;">
-      <div style="width: 64px; height: 64px; background: #16a34a; border-radius: 50%; display: flex; align-items: center; justify-content: center; margin: 0 auto 1rem;">
-        <svg width="32" height="32" fill="none" stroke="white" stroke-width="3" viewBox="0 0 24 24">
-          <path d="M5 13l4 4L19 7" stroke-linecap="round" stroke-linejoin="round"/>
-        </svg>
-      </div>
-      <h1 style="color: #16a34a; margin: 0 0 0.5rem;">Login Successful!</h1>
-      <p style="color: #6b7280; margin: 0;">You can close this window and return to the terminal.</p>
-    </div>
-  </body>
-</html>`;
-}
-function escapeHtml(text) {
-  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
-}
-function errorPage(message) {
-  const safeMessage = escapeHtml(message);
-  return `<!DOCTYPE html>
-<html>
-  <head><title>Login Failed</title></head>
-  <body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #f9fafb;">
-    <div style="text-align: center; padding: 2rem;">
-      <div style="width: 64px; height: 64px; background: #dc2626; border-radius: 50%; display: flex; align-items: center; justify-content: center; margin: 0 auto 1rem;">
-        <svg width="32" height="32" fill="none" stroke="white" stroke-width="3" viewBox="0 0 24 24">
-          <path d="M6 18L18 6M6 6l12 12" stroke-linecap="round" stroke-linejoin="round"/>
-        </svg>
-      </div>
-      <h1 style="color: #dc2626; margin: 0 0 0.5rem;">Login Failed</h1>
-      <p style="color: #6b7280; margin: 0;">${safeMessage}</p>
-      <p style="color: #9ca3af; margin: 1rem 0 0; font-size: 0.875rem;">You can close this window.</p>
-    </div>
-  </body>
-</html>`;
-}
-async function exchangeCodeForTokens(baseUrl3, code, codeVerifier, redirectUri, clientId) {
-  const response = await fetch(`${baseUrl3}/api/oauth/token`, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams({
-      grant_type: "authorization_code",
-      client_id: clientId,
-      code,
-      code_verifier: codeVerifier,
-      redirect_uri: redirectUri
-    }).toString()
-  });
-  if (!response.ok) {
-    const err = await response.json().catch(() => ({}));
-    throw new Error(err.error_description || err.error || "Failed to exchange code for tokens");
-  }
-  return await response.json();
-}
-function buildAuthorizationUrl(baseUrl3, clientId, redirectUri, codeChallenge, state) {
-  const url = new URL(`${baseUrl3}/api/oauth/authorize`);
-  url.searchParams.set("client_id", clientId);
-  url.searchParams.set("redirect_uri", redirectUri);
-  url.searchParams.set("code_challenge", codeChallenge);
-  url.searchParams.set("code_challenge_method", "S256");
-  url.searchParams.set("state", state);
-  url.searchParams.set("scope", "profile email");
-  url.searchParams.set("response_type", "code");
-  return url.toString();
-}
 var DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 var DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5;
-function shouldUseDeviceFlow() {
-  if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY) return true;
-  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
-    return true;
-  }
-  return false;
-}
 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 {
   }
@@ -1236,7 +1186,7 @@ function setAuthBaseUrl(url) {
   baseUrl2 = url;
 }
 function registerAuthCommands(program2) {
-  program2.command("login").description("Log in to Context7").option("--no-browser", "Don't open browser automatically").option("--device", "Force device-code flow (use on SSH / headless hosts)").action(async (options) => {
+  program2.command("login").description("Log in to Context7").option("--no-browser", "Don't open browser automatically").action(async (options) => {
     await loginCommand(options);
   });
   program2.command("logout").description("Log out of Context7").action(() => {
@@ -1299,7 +1249,7 @@ async function announceIdentity(accessToken) {
     return "Login successful!";
   }
 }
-async function performDeviceLogin(openBrowser = true) {
+async function performLogin(openBrowser = true) {
   const spinner = ora("Preparing login...").start();
   let authorization;
   try {
@@ -1367,67 +1317,6 @@ async function performDeviceLogin(openBrowser = true) {
   waitingSpinner.fail(pc4.red("Code expired without approval."));
   return null;
 }
-async function performLogin(openBrowser = true, forceDevice = false) {
-  if (forceDevice || shouldUseDeviceFlow()) {
-    return performDeviceLogin(openBrowser);
-  }
-  const spinner = ora("Preparing login...").start();
-  try {
-    const { codeVerifier, codeChallenge } = generatePKCE();
-    const state = generateState();
-    const callbackServer = createCallbackServer(state);
-    const port = await callbackServer.port;
-    const redirectUri = `http://localhost:${port}/callback`;
-    const authUrl = buildAuthorizationUrl(
-      baseUrl2,
-      CLI_CLIENT_ID,
-      redirectUri,
-      codeChallenge,
-      state
-    );
-    spinner.stop();
-    console.log("");
-    console.log(pc4.bold("Opening browser to log in..."));
-    console.log("");
-    if (openBrowser) {
-      await open(authUrl);
-      console.log(pc4.dim("If the browser didn't open, visit this URL:"));
-    } else {
-      console.log(pc4.dim("Open this URL in your browser:"));
-    }
-    console.log(pc4.cyan(authUrl));
-    console.log("");
-    const waitingSpinner = ora("Waiting for login...").start();
-    try {
-      const { code } = await callbackServer.result;
-      waitingSpinner.text = "Exchanging code for tokens...";
-      const tokens = await exchangeCodeForTokens(
-        baseUrl2,
-        code,
-        codeVerifier,
-        redirectUri,
-        CLI_CLIENT_ID
-      );
-      saveTokens(tokens);
-      callbackServer.close();
-      waitingSpinner.succeed(pc4.green("Login successful!"));
-      return tokens.access_token;
-    } catch (error) {
-      callbackServer.close();
-      waitingSpinner.fail(pc4.red("Login failed"));
-      if (error instanceof Error) {
-        console.error(pc4.red(error.message));
-      }
-      return null;
-    }
-  } catch (error) {
-    spinner.fail(pc4.red("Login failed"));
-    if (error instanceof Error) {
-      console.error(pc4.red(error.message));
-    }
-    return null;
-  }
-}
 async function loginCommand(options) {
   trackEvent("command", { name: "login" });
   const existingToken = await getValidAccessToken();
@@ -1437,7 +1326,7 @@ async function loginCommand(options) {
     return;
   }
   clearTokens();
-  const token = await performLogin(options.browser, options.device ?? false);
+  const token = await performLogin(options.browser);
   if (!token) {
     process.exit(1);
   }
@@ -1902,8 +1791,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");
@@ -1983,7 +1872,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;
@@ -2835,12 +2724,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 { randomBytes as randomBytes2 } from "crypto";
+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 = {
@@ -3044,7 +2933,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;
@@ -3153,8 +3042,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;
@@ -3225,7 +3114,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 {
     }
@@ -3233,7 +3122,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) {
@@ -3353,11 +3242,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 };
@@ -3390,7 +3279,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 };
@@ -3432,7 +3321,7 @@ async function authenticateAndGenerateKey() {
         Authorization: `Bearer ${accessToken}`,
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ name: `ctx7-cli-${randomBytes2(3).toString("hex")}` })
+      body: JSON.stringify({ name: `ctx7-cli-${randomBytes(3).toString("hex")}` })
     });
     if (!response.ok) {
       const err = await response.json().catch(() => ({}));
@@ -3536,7 +3425,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 };
   }
@@ -3556,7 +3445,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 };
 }
@@ -3660,7 +3549,7 @@ async function setupMcp(agents2, options, scope) {
     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))}`)}`
+        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname7(dirname7(r.skillPath))}`)}`
       );
     }
   }
@@ -3721,7 +3610,7 @@ async function setupCli(options) {
     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))}`)}`
+        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname7(dirname7(r.skillPath))}`)}`
       );
     }
     const ruleIcon = r.ruleStatus === "installed" || r.ruleStatus === "updated" ? pc8.green("+") : pc8.dim("~");
@@ -3754,7 +3643,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),
@@ -3854,7 +3743,7 @@ function resolveFlagModes(options) {
 }
 async function pathExists2(path2) {
   try {
-    await access4(path2);
+    await access5(path2);
     return true;
   } catch {
     return false;
@@ -4101,6 +3990,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";
@@ -4186,10 +4087,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;
   }
@@ -4273,25 +4180,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) {
@@ -4595,7 +4513,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);