githits 0.4.7 → 0.4.9

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "GitHits plugins for Claude Code - code examples from global open source",
-    "version": "0.4.7"
+    "version": "0.4.9"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

package/.plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

package/README.md

@@ -12,7 +12,7 @@ npx githits init
 
 `init` walks you through setup: choose the local MCP server or Agent Skills, detect your coding tools, sign in, and connect everything to GitHits.
 
-Supported tools: Claude Code, Cursor, Windsurf, VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Pi, Gemini CLI, Google Antigravity, and OpenCode.
+Supported tools: Claude Code, Cursor, Windsurf, VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Pi, Gemini CLI, Google Antigravity, OpenCode, and Hermes Agent.
 
 If you are using a tool that is not listed above, use the manual MCP setup instructions near the end of this README.
 

package/dist/cli.js

@@ -51,11 +51,11 @@ import {
   shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-tm11qwgr.js";
+} from "./shared/chunk-v23wr0eq.js";
 import {
   __require,
   version
-} from "./shared/chunk-7b4f7fd5.js";
+} from "./shared/chunk-yqx01jh9.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -8001,7 +8001,7 @@ grep run. --symbol-field hydrates enclosing symbol metadata (appears under each
 match in --verbose output; full payload in --json).`;
 function registerCodeGrepCommand(pkgCommand) {
   return pkgCommand.command("grep").summary("Deterministic text grep over indexed dependency source").description(PKG_GREP_DESCRIPTION).argument("[spec-or-pattern]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the pattern.").argument("[pattern-or-prefix]", "Spec mode: the pattern. Repo mode: optional path-prefix.").argument("[path-prefix]", "Spec mode only: optional path-prefix. Ignored with --repo-url.").option("--repo-url <url>", "Repository URL addressing (defaults to the repo default branch)").option("--git-ref <ref>", "Optional tag, commit, branch, or HEAD for --repo-url.").option("--path <path>", "Exact file path to grep").option("--glob <glob>", "Glob scope (repeatable)", collectRepeatable2, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable2, []).option("--regex", "Interpret the pattern as RE2 regex").option("--case-sensitive", "Enable ASCII case-sensitive matching").option("-C, --context <n>", "Context lines before and after each match (0-10)").option("-B, --before-context <n>", "Context lines before each match (0-10)").option("-A, --after-context <n>", "Context lines after each match (0-10)").option("--exclude-docs", "Skip files classified as documentation").option("--exclude-tests", "Skip files classified as tests").option("--limit <n>", "Max matches to return on this page (1-1000, default 50)").option("--per-file-limit <n>", "Cap matches per file within this page (0-1000, 0 = unlimited)").option("--cursor <cursor>", "Opaque nextCursor from a previous grep result").option("--symbol-field <field>", `Repeatable; surfaces in --json and under each --verbose match. ${GREP_REPO_SYMBOL_FIELDS_NOTE}`, collectRepeatable2, []).option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Render grouped output with file headers").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, arg3, options) => {
-    const { createContainer: createContainer2 } = await import("./shared/chunk-70bn2pmx.js");
+    const { createContainer: createContainer2 } = await import("./shared/chunk-phdms6y7.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -8465,7 +8465,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-70bn2pmx.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-phdms6y7.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -8529,11 +8529,21 @@ import {
   parse as parseJsonc,
   printParseErrorCode
 } from "jsonc-parser";
+import {
+  isMap,
+  isScalar,
+  parseDocument,
+  parse as parseYaml,
+  stringify as stringifyYaml
+} from "yaml";
+function normalizeConfigContent(content) {
+  if (content.charCodeAt(0) === 65279) {
+    return content.slice(1);
+  }
+  return content;
+}
 function parseConfigObject(content) {
-  let normalizedContent = content;
-  if (normalizedContent.charCodeAt(0) === 65279) {
-    normalizedContent = normalizedContent.slice(1);
-  }
+  const normalizedContent = normalizeConfigContent(content);
   const trimmed = normalizedContent.trim();
   if (trimmed === "") {
     return {
@@ -8581,6 +8591,221 @@ function parseConfigObject(content) {
     };
   }
 }
+function parseYamlConfigObject(content) {
+  const normalizedContent = normalizeConfigContent(content);
+  if (normalizedContent.trim() === "") {
+    return { value: {} };
+  }
+  try {
+    const parsed = parseYaml(normalizedContent);
+    if (parsed === null || parsed === undefined) {
+      return { value: {} };
+    }
+    if (!isPlainObject(parsed)) {
+      return { error: "Config file root is not a YAML object" };
+    }
+    return { value: parsed };
+  } catch (err) {
+    return {
+      error: `Invalid YAML: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function formatYamlError(error2) {
+  if (error2 instanceof Error) {
+    return error2.message;
+  }
+  return String(error2);
+}
+function parseYamlConfigDocument(content) {
+  const normalizedContent = normalizeConfigContent(content);
+  const source = normalizedContent.trim() === "" ? `{}
+` : normalizedContent;
+  let doc;
+  try {
+    doc = parseDocument(source);
+  } catch (err) {
+    return {
+      status: "error",
+      error: `Invalid YAML: ${formatYamlError(err)}`
+    };
+  }
+  if (doc.errors.length > 0) {
+    const firstError = doc.errors[0];
+    return {
+      status: "error",
+      error: `Invalid YAML: ${formatYamlError(firstError)}`
+    };
+  }
+  const contents = doc.contents;
+  if (!contents || !isMap(contents)) {
+    return {
+      status: "error",
+      error: "Config file root is not a YAML object"
+    };
+  }
+  return {
+    status: "ok",
+    doc,
+    root: contents
+  };
+}
+function toYamlConfigShapeError(serversKey) {
+  return `"${serversKey}" is not a YAML object`;
+}
+function toYamlKeyString(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (!isScalar(key) || typeof key.value !== "string") {
+    return null;
+  }
+  return key.value;
+}
+function getYamlMatchingServerKeys(serversMap, serverName) {
+  const normalizedTarget = serverName.toLowerCase();
+  return serversMap.items.map((pair) => toYamlKeyString(pair.key)).filter((key) => typeof key === "string" && key.toLowerCase() === normalizedTarget);
+}
+function yamlNodeToJsValue(value) {
+  if (typeof value === "object" && value !== null && "toJSON" in value && typeof value.toJSON === "function") {
+    return value.toJSON();
+  }
+  return value;
+}
+function createEmptyYamlMapNode() {
+  const map = parseDocument(`{}
+`).contents;
+  if (!map || !isMap(map)) {
+    throw new Error("Failed to initialize YAML object node");
+  }
+  return map;
+}
+function ensureYamlServersMapForSetup(root, serversKey) {
+  const existingServers = root.get(serversKey, true);
+  if (existingServers === undefined || existingServers === null || isScalar(existingServers) && existingServers.value === null) {
+    root.set(serversKey, createEmptyYamlMapNode());
+    const initializedServers = root.get(serversKey, true);
+    if (!initializedServers || !isMap(initializedServers)) {
+      return {
+        status: "error",
+        error: toYamlConfigShapeError(serversKey)
+      };
+    }
+    return {
+      status: "ok",
+      serversMap: initializedServers
+    };
+  }
+  if (!isMap(existingServers)) {
+    return {
+      status: "error",
+      error: toYamlConfigShapeError(serversKey)
+    };
+  }
+  return {
+    status: "ok",
+    serversMap: existingServers
+  };
+}
+function getYamlServersMapForUninstall(root, serversKey) {
+  const existingServers = root.get(serversKey, true);
+  if (existingServers === undefined || existingServers === null || isScalar(existingServers) && existingServers.value === null) {
+    return { status: "not_configured" };
+  }
+  if (!isMap(existingServers)) {
+    return {
+      status: "error",
+      error: toYamlConfigShapeError(serversKey)
+    };
+  }
+  return {
+    status: "ok",
+    serversMap: existingServers
+  };
+}
+function renderYamlDocument(doc) {
+  const rendered = doc.toString();
+  return rendered.endsWith(`
+`) ? rendered : `${rendered}
+`;
+}
+function mergeYamlServerConfig(existingContent, serversKey, serverName, serverConfig) {
+  const parsed = parseYamlConfigDocument(existingContent);
+  if (parsed.status === "error") {
+    return { status: "parse_error", error: parsed.error };
+  }
+  const serversResult = ensureYamlServersMapForSetup(parsed.root, serversKey);
+  if (serversResult.status !== "ok") {
+    return {
+      status: "parse_error",
+      error: serversResult.status === "error" ? serversResult.error : toYamlConfigShapeError(serversKey)
+    };
+  }
+  const { serversMap } = serversResult;
+  const matchingKeys = getYamlMatchingServerKeys(serversMap, serverName);
+  if (matchingKeys.length === 1 && matchingKeys[0] === serverName) {
+    const existingValue = yamlNodeToJsValue(serversMap.get(serverName, true));
+    if (isEquivalentConfiguredValue(existingValue, serverConfig)) {
+      return { status: "already_configured" };
+    }
+  }
+  for (const key of matchingKeys) {
+    serversMap.delete(key);
+  }
+  const hadExisting = matchingKeys.length > 0;
+  serversMap.set(serverName, serverConfig);
+  return {
+    status: hadExisting ? "updated" : "added",
+    content: renderYamlDocument(parsed.doc)
+  };
+}
+function removeYamlServerConfig(existingContent, serversKey, serverName) {
+  const parsed = parseYamlConfigDocument(existingContent);
+  if (parsed.status === "error") {
+    return { status: "parse_error", error: parsed.error };
+  }
+  const serversResult = getYamlServersMapForUninstall(parsed.root, serversKey);
+  if (serversResult.status === "not_configured") {
+    return { status: "not_configured" };
+  }
+  if (serversResult.status === "error") {
+    return {
+      status: "parse_error",
+      error: serversResult.error
+    };
+  }
+  const matchingKeys = getYamlMatchingServerKeys(serversResult.serversMap, serverName);
+  if (matchingKeys.length === 0) {
+    return { status: "not_configured" };
+  }
+  for (const key of matchingKeys) {
+    serversResult.serversMap.delete(key);
+  }
+  return {
+    status: "removed",
+    content: renderYamlDocument(parsed.doc)
+  };
+}
+function parseConfigObjectForFormat(content, format = "json") {
+  if (format === "yaml") {
+    return parseYamlConfigObject(content);
+  }
+  const parsed = parseConfigObject(content);
+  if (parsed.format === "invalid") {
+    return { error: parsed.error };
+  }
+  return { value: parsed.value };
+}
+function renderConfigObjectForFormat(config, format = "json") {
+  if (format === "yaml") {
+    const rendered = stringifyYaml(config);
+    return rendered.endsWith(`
+`) ? rendered : `${rendered}
+`;
+  }
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -8688,9 +8913,12 @@ function getMatchingServerKeys(servers, serverName) {
   const normalizedTarget = serverName.toLowerCase();
   return Object.keys(servers).filter((key) => key.toLowerCase() === normalizedTarget);
 }
-function mergeServerConfig(existingContent, serversKey, serverName, serverConfig) {
-  const parsedConfig = parseConfigObject(existingContent);
-  if (parsedConfig.format === "invalid") {
+function mergeServerConfig(existingContent, serversKey, serverName, serverConfig, format = "json") {
+  if (format === "yaml") {
+    return mergeYamlServerConfig(existingContent, serversKey, serverName, serverConfig);
+  }
+  const parsedConfig = parseConfigObjectForFormat(existingContent, format);
+  if ("error" in parsedConfig) {
     return {
       status: "parse_error",
       error: parsedConfig.error
@@ -8719,13 +8947,15 @@ function mergeServerConfig(existingContent, serversKey, serverName, serverConfig
   serversObj[serverName] = serverConfig;
   return {
     status: hadExisting ? "updated" : "added",
-    content: `${JSON.stringify(config, null, 2)}
-`
+    content: renderConfigObjectForFormat(config, format)
   };
 }
-function removeServerConfig(existingContent, serversKey, serverName) {
-  const parsedConfig = parseConfigObject(existingContent);
-  if (parsedConfig.format === "invalid") {
+function removeServerConfig(existingContent, serversKey, serverName, format = "json") {
+  if (format === "yaml") {
+    return removeYamlServerConfig(existingContent, serversKey, serverName);
+  }
+  const parsedConfig = parseConfigObjectForFormat(existingContent, format);
+  if ("error" in parsedConfig) {
     return {
       status: "parse_error",
       error: parsedConfig.error
@@ -8752,8 +8982,7 @@ function removeServerConfig(existingContent, serversKey, serverName) {
   }
   return {
     status: "removed",
-    content: `${JSON.stringify(config, null, 2)}
-`
+    content: renderConfigObjectForFormat(config, format)
   };
 }
 function formatUninstallPreview(config) {
@@ -8770,8 +8999,8 @@ function formatUninstallPreview(config) {
 async function isAlreadyConfigured(config, fs) {
   try {
     const content = await fs.readFile(config.configPath);
-    const parsedConfig = parseConfigObject(content);
-    if (parsedConfig.format === "invalid") {
+    const parsedConfig = parseConfigObjectForFormat(content, config.format);
+    if ("error" in parsedConfig) {
       return false;
     }
     const parsed = parsedConfig.value;
@@ -8792,21 +9021,21 @@ async function isAlreadyConfigured(config, fs) {
 async function getConfigUninstallCheckStatus(config, fs) {
   try {
     const content = await fs.readFile(config.configPath);
-    const parsedConfig = parseConfigObject(content);
-    if (parsedConfig.format === "invalid") {
+    const parsedConfig = parseConfigObjectForFormat(content, config.format);
+    if ("error" in parsedConfig) {
       return {
         status: "failed",
         message: `Cannot parse ${config.configPath}: ${parsedConfig.error}. File left unchanged.`
       };
     }
     const servers = parsedConfig.value[config.serversKey];
-    if (servers === undefined) {
+    if (servers === undefined || servers === null) {
       return { status: "not_configured" };
     }
     if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
       return {
         status: "failed",
-        message: `Cannot parse ${config.configPath}: "${config.serversKey}" is not a JSON object. File left unchanged.`
+        message: `Cannot parse ${config.configPath}: "${config.serversKey}" is not a ${config.format === "yaml" ? "YAML" : "JSON"} object. File left unchanged.`
       };
     }
     const hasEntry = getMatchingServerKeys(servers, config.serverName).length > 0;
@@ -9065,7 +9294,7 @@ async function executeConfigFileSetup(setup, fs) {
         };
       }
     }
-    const result = mergeServerConfig(existingContent, setup.serversKey, setup.serverName, setup.serverConfig);
+    const result = mergeServerConfig(existingContent, setup.serversKey, setup.serverName, setup.serverConfig, setup.format);
     if (result.status === "already_configured") {
       return {
         status: "already_configured",
@@ -9130,7 +9359,7 @@ async function executeConfigFileUninstall(setup, fs) {
         message: `Cannot read ${setup.configPath}: ${err instanceof Error ? err.message : String(err)}`
       };
     }
-    const result = removeServerConfig(existingContent, setup.serversKey, setup.serverName);
+    const result = removeServerConfig(existingContent, setup.serversKey, setup.serverName, setup.format);
     if (result.status === "not_configured") {
       return {
         status: "not_configured",
@@ -9218,6 +9447,16 @@ function getPiAgentDir(fs) {
 function getPiMcpConfigPath(fs) {
   return fs.joinPath(getPiAgentDir(fs), "mcp.json");
 }
+function getHermesHomeDir(fs) {
+  const configuredDir = process.env.HERMES_HOME?.trim();
+  if (configuredDir) {
+    return expandHomePath(fs, configuredDir);
+  }
+  return fs.joinPath(fs.getHomeDir(), ".hermes");
+}
+function getHermesConfigPath(fs) {
+  return fs.joinPath(getHermesHomeDir(fs), "config.yaml");
+}
 function getOpenCodeDesktopDetectPaths(fs) {
   const userDataRoot = getUserDataRoot(fs);
   return [
@@ -9612,6 +9851,25 @@ var openCode = {
     }
   })
 };
+var hermesAgent = {
+  name: "Hermes Agent",
+  id: "hermes-agent",
+  detectionMethod: "hybrid",
+  setupMethod: "config-file",
+  detectPaths: (fs) => [getHermesHomeDir(fs)],
+  detectBinary: async (exec) => isExecutableAvailable(exec, "hermes-agent"),
+  getSetupConfig: (fs) => ({
+    method: "config-file",
+    format: "yaml",
+    configPath: getHermesConfigPath(fs),
+    serversKey: "mcp_servers",
+    serverName: GITHITS_SERVER_NAME,
+    serverConfig: {
+      command: GITHITS_MCP_COMMAND,
+      args: [...GITHITS_MCP_ARGS]
+    }
+  })
+};
 var agentDefinitions = [
   claudeCode,
   cursor,
@@ -9623,7 +9881,8 @@ var agentDefinitions = [
   pi,
   geminiCli,
   googleAntigravity,
-  openCode
+  openCode,
+  hermesAgent
 ];
 async function scanSingleAgent(agent, fs, execService) {
   let detected = false;
@@ -9761,6 +10020,14 @@ function getPiConfigFileUninstall(agent, fileSystemService) {
 function formatCommand(command, useColors) {
   return colorizeBrand(command, "secondary", useColors, { bold: true });
 }
+var AGENT_SAFE_CLI = "npx -y githits@latest";
+var AGENT_DETECT_COMMAND = `${AGENT_SAFE_CLI} init --detect-agents`;
+var AGENT_INSTALL_COMMAND = `${AGENT_SAFE_CLI} init --install-agents`;
+var AGENT_LOGIN_COMMAND = `${AGENT_SAFE_CLI} login`;
+var AGENT_LOGIN_NO_BROWSER_COMMAND = `${AGENT_SAFE_CLI} login --no-browser`;
+var AGENTIC_INIT_YES_WARNING = "Do not run `githits init -y` or `githits init --yes` unless the user explicitly asks to configure every detected tool.";
+var AGENTIC_INIT_VERIFY_INSTRUCTION = "After a successful --install-agents run, verify with --detect-agents --json instead of running init again.";
+var AGENTIC_INIT_JSON_VERIFY_INSTRUCTION = "Do not run init again after a successful --install-agents run; verify with --detect-agents --json instead.";
 function printReadyNextSteps() {
   console.log("  GitHits is now connected to your coding agents.");
   console.log();
@@ -9793,6 +10060,57 @@ function printAuthNotCheckedNextSteps(useColors) {
   console.log("  If your agent asks you to sign in, run:");
   console.log(`    ${formatCommand("npx githits@latest login", useColors)}`);
 }
+function printAgenticLoginInstructions(useColors) {
+  console.log("  Authentication is still required before agents can use GitHits.");
+  console.log();
+  console.log("  Agent instruction:");
+  console.log();
+  console.log("  Ask the user:");
+  console.log(`    "GitHits needs to open a browser sign-in page. The sign-in happens in your browser, not in this chat or terminal. I will not see or handle your credentials. Should I run \`${AGENT_LOGIN_COMMAND}\` now?"`);
+  console.log();
+  console.log("  If the user approves, run:");
+  console.log(`    ${formatCommand(AGENT_LOGIN_COMMAND, useColors)}`);
+  console.log();
+  console.log("  If the browser cannot open, run:");
+  console.log(`    ${formatCommand(AGENT_LOGIN_NO_BROWSER_COMMAND, useColors)}`);
+}
+function printAgenticAlreadyAuthenticated() {
+  console.log("  GitHits MCP is installed and you are already signed in.");
+  console.log();
+  console.log("  Open a new coding agent session so it reloads MCP config.");
+}
+function printAgenticAuthNotChecked(useColors) {
+  console.log("  GitHits MCP is installed. Sign-in status was not checked.");
+  console.log();
+  console.log("  If the user is not already signed in, ask before running:");
+  console.log(`    ${formatCommand(AGENT_LOGIN_COMMAND, useColors)}`);
+}
+function printNonInteractiveInitGuidance(useColors) {
+  console.log("  This setup is interactive. Because this session is non-interactive, no changes were made.");
+  console.log();
+  console.log("  If you are an AI coding agent helping a user install GitHits:");
+  console.log();
+  console.log("  1. Run:");
+  console.log(`     ${formatCommand(AGENT_DETECT_COMMAND, useColors)}`);
+  console.log();
+  console.log("  2. Show the detected tools to the user.");
+  console.log();
+  console.log("  3. Ask which tools should receive the GitHits MCP server.");
+  console.log();
+  console.log("  4. Only after approval, run:");
+  console.log(`     ${formatCommand(`${AGENT_INSTALL_COMMAND} <ids>`, useColors)}`);
+  console.log();
+  console.log(`  ${AGENTIC_INIT_YES_WARNING}`);
+  console.log(`  ${AGENTIC_INIT_VERIFY_INSTRUCTION}`);
+}
+function printNonInteractiveYesRejected(useColors) {
+  console.error("Non-interactive `githits init --yes` is not supported because it can configure tools without explicit per-tool approval.");
+  console.error();
+  console.error("Use the agent-safe staged flow instead:");
+  console.error(`  ${formatCommand(AGENT_DETECT_COMMAND, useColors)}`);
+  console.error(`  ${formatCommand(`${AGENT_INSTALL_COMMAND} <ids>`, useColors)}`);
+  process.exitCode = 1;
+}
 var GITHITS_ASCII_LOGO = String.raw`
    ____ _ _   _   _ _ _       
   / ___(_) |_| | | (_) |_ ___ 
@@ -9922,7 +10240,7 @@ function printTask(status, label, detail, useColors) {
 }
 function printInitIntro(useColors) {
   console.log(colorizeLogo(GITHITS_ASCII_LOGO, useColors));
-  console.log("  Your agent can read your local codebase.");
+  console.log("  Your agent can only read your local codebase.");
   console.log();
   console.log("  GitHits lets it navigate the open-source code your app depends on.");
   console.log();
@@ -10059,6 +10377,287 @@ function printScanSummary(scan, useColors) {
     console.log(`    Found ${detected} supported tool${detected !== 1 ? "s" : ""}.`);
   }
 }
+function buildStagedAgentEntries(scan) {
+  const statuses = new Map;
+  for (const agent of scan.needsSetup)
+    statuses.set(agent.id, "needs_setup");
+  for (const agent of scan.alreadyConfigured) {
+    statuses.set(agent.id, "already_configured");
+  }
+  for (const agent of scan.notDetected)
+    statuses.set(agent.id, "not_detected");
+  return agentDefinitions.map((agent) => ({
+    id: agent.id,
+    name: agent.name,
+    status: statuses.get(agent.id) ?? "not_detected"
+  }));
+}
+function printAgenticDetectSummary(scan, useColors) {
+  const entries = buildStagedAgentEntries(scan);
+  const detected = entries.filter((entry) => entry.status !== "not_detected");
+  const installable = entries.filter((entry) => entry.status === "needs_setup");
+  const notDetected = entries.filter((entry) => entry.status === "not_detected");
+  console.log("Detected supported tools:");
+  console.log();
+  if (detected.length === 0) {
+    console.log("  None detected.");
+  } else {
+    console.log("  ID                 Tool                  Status");
+    for (const entry of detected) {
+      console.log(`  ${entry.id.padEnd(18)} ${entry.name.padEnd(21)} ${entry.status.replace("_", " ")}`);
+    }
+  }
+  console.log();
+  console.log("Not detected:");
+  console.log(`  ${notDetected.length > 0 ? notDetected.map((entry) => entry.id).join(", ") : "none"}`);
+  console.log();
+  if (detected.length === 0) {
+    console.log("No supported AI coding tools detected.");
+    console.log();
+    console.log("Next step for agents:");
+    console.log("  Tell the user to install a supported coding tool, then run detection again.");
+    return;
+  }
+  if (installable.length === 0) {
+    console.log("No detected tools need setup.");
+    console.log();
+    console.log("Next step for agents:");
+    console.log("  Tell the user that GitHits is already configured for detected tools.");
+    console.log(`  ${AGENTIC_INIT_YES_WARNING}`);
+    console.log("  Do not run init again as a verification step.");
+    return;
+  }
+  const installableIds = installable.map((entry) => entry.id);
+  console.log("Next step for agents:");
+  console.log();
+  console.log("  Ask the user:");
+  console.log(`    "GitHits can be installed for ${installable.map((entry) => entry.name).join(", ")}. Which should I configure?"`);
+  console.log();
+  console.log("  If the user approves all detected tools needing setup, run:");
+  console.log(`    ${formatCommand(`${AGENT_INSTALL_COMMAND} ${installableIds.join(",")}`, useColors)}`);
+  console.log();
+  console.log(`  ${AGENTIC_INIT_YES_WARNING}`);
+  console.log(`  ${AGENTIC_INIT_VERIFY_INSTRUCTION}`);
+}
+function printAgenticDetectJson(scan) {
+  const entries = buildStagedAgentEntries(scan);
+  const installableIds = entries.filter((entry) => entry.status === "needs_setup").map((entry) => entry.id);
+  console.log(JSON.stringify({
+    mode: "detect-agents",
+    agents: entries,
+    installableIds,
+    suggestedCommand: installableIds.length > 0 ? `${AGENT_INSTALL_COMMAND} ${installableIds.join(",")}` : null,
+    instructions: [
+      "Show detected tools to the user.",
+      "Ask which tools should receive the GitHits MCP server.",
+      "Only run --install-agents with user-approved IDs.",
+      AGENTIC_INIT_YES_WARNING,
+      AGENTIC_INIT_JSON_VERIFY_INSTRUCTION
+    ]
+  }, null, 2));
+}
+function getStagedModeCount(options) {
+  return [
+    options.detectAgents === true,
+    options.installAgents !== undefined
+  ].filter(Boolean).length;
+}
+function failInitArgument(message, json) {
+  if (json) {
+    console.error(JSON.stringify({ error: message, code: "INVALID_ARGUMENT" }));
+  } else {
+    console.error(message);
+  }
+  process.exitCode = 1;
+}
+function validateInitModeOptions(options) {
+  const stagedModeCount = getStagedModeCount(options);
+  if (stagedModeCount > 1) {
+    failInitArgument("Use only one staged init mode: --detect-agents or --install-agents.", options.json);
+    return false;
+  }
+  if (options.yes && stagedModeCount > 0) {
+    failInitArgument("--yes cannot be combined with --detect-agents or --install-agents.", options.json);
+    return false;
+  }
+  if (options.json && stagedModeCount === 0) {
+    failInitArgument("--json is only supported with --detect-agents or --install-agents.", options.json);
+    return false;
+  }
+  return true;
+}
+function parseAgentIdList(value) {
+  if (!value)
+    return [];
+  const ids = value.split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+  return [...new Set(ids)];
+}
+function findAgentsByIds(scan, ids) {
+  const detected = [...scan.needsSetup, ...scan.alreadyConfigured];
+  return ids.map((id) => detected.find((agent) => agent.id === id)).filter((agent) => Boolean(agent));
+}
+function validateInstallAgentIds(scan, ids) {
+  const supportedIds = new Set(agentDefinitions.map((agent) => agent.id));
+  const detectedIds = [...scan.needsSetup, ...scan.alreadyConfigured].map((agent) => agent.id);
+  const detectedIdSet = new Set(detectedIds);
+  if (ids.length === 0) {
+    return {
+      ok: false,
+      message: detectedIds.length > 0 ? `Provide at least one agent ID. Detected IDs: ${detectedIds.join(", ")}.` : "Provide at least one agent ID. No supported agents are currently detected.",
+      detectedIds
+    };
+  }
+  const unknown = ids.filter((id) => !supportedIds.has(id));
+  if (unknown.length > 0) {
+    return {
+      ok: false,
+      message: `Unsupported agent ID${unknown.length !== 1 ? "s" : ""}: ${unknown.join(", ")}.`,
+      detectedIds
+    };
+  }
+  const undetected = ids.filter((id) => !detectedIdSet.has(id));
+  if (undetected.length > 0) {
+    return {
+      ok: false,
+      message: `Agent ID${undetected.length !== 1 ? "s" : ""} not detected: ${undetected.join(", ")}. Detected IDs: ${detectedIds.length > 0 ? detectedIds.join(", ") : "none"}.`,
+      detectedIds
+    };
+  }
+  return { ok: true };
+}
+function printInstallValidationFailure(failure, json) {
+  if (json) {
+    console.error(JSON.stringify({
+      error: failure.message,
+      code: "INVALID_ARGUMENT",
+      detectedIds: failure.detectedIds
+    }));
+  } else {
+    console.error(failure.message);
+  }
+  process.exitCode = 1;
+}
+function hasUsableInstallOutcome(outcomes) {
+  return outcomes.some((outcome) => outcome.status === "success" || outcome.status === "already_configured");
+}
+async function getStagedInstallAuthStatus(createLoginDeps) {
+  if (!createLoginDeps)
+    return "not_checked";
+  try {
+    const loginDeps = await createLoginDeps();
+    if (typeof loginDeps.hasValidToken === "boolean") {
+      return loginDeps.hasValidToken ? "authenticated" : "required";
+    }
+    const tokens = await loginDeps.authStorage.loadTokens(loginDeps.mcpUrl);
+    const expired = tokens?.expiresAt ? new Date(tokens.expiresAt) < new Date : false;
+    return tokens && !expired ? "authenticated" : "required";
+  } catch {
+    return "not_checked";
+  }
+}
+function buildAgenticInstallAuthPayload(authStatus) {
+  if (authStatus === "authenticated") {
+    return { required: false, status: "authenticated" };
+  }
+  if (authStatus === "required") {
+    return {
+      required: true,
+      status: "required",
+      command: AGENT_LOGIN_COMMAND,
+      noBrowserCommand: AGENT_LOGIN_NO_BROWSER_COMMAND
+    };
+  }
+  return {
+    required: null,
+    status: "not_checked",
+    command: AGENT_LOGIN_COMMAND,
+    noBrowserCommand: AGENT_LOGIN_NO_BROWSER_COMMAND
+  };
+}
+function buildAgenticInstallInstructions(authStatus) {
+  if (authStatus === "authenticated") {
+    return ["Open a new coding agent session so it reloads MCP config."];
+  }
+  if (authStatus === "required") {
+    return [
+      `Ask the user before running ${AGENT_LOGIN_COMMAND}.`,
+      "Browser sign-in happens outside chat and terminal input.",
+      "Do not ask the user to paste passwords, tokens, cookies, or OAuth codes into chat."
+    ];
+  }
+  return [
+    "Sign-in status was not checked.",
+    `If the user is not already signed in, ask before running ${AGENT_LOGIN_COMMAND}.`
+  ];
+}
+function printAgenticInstallJson(outcomes, authStatus) {
+  const canAuthenticate = hasUsableInstallOutcome(outcomes);
+  console.log(JSON.stringify({
+    mode: "install-agents",
+    outcomes,
+    auth: canAuthenticate ? buildAgenticInstallAuthPayload(authStatus) : {
+      required: false,
+      status: "not_applicable",
+      reason: "Fix installation errors before starting sign-in."
+    },
+    instructions: canAuthenticate ? buildAgenticInstallInstructions(authStatus) : ["Fix installation errors before asking the user to sign in."]
+  }, null, 2));
+}
+async function runDetectAgentsMode(options, fileSystemService, execService, useColors) {
+  const scan = await scanAgents(agentDefinitions, fileSystemService, execService);
+  if (options.json) {
+    printAgenticDetectJson(scan);
+    return;
+  }
+  printAgenticDetectSummary(scan, useColors);
+}
+async function runInstallAgentsMode(options, fileSystemService, execService, createLoginDeps, useColors) {
+  const requestedIds = parseAgentIdList(options.installAgents);
+  const scan = await scanAgents(agentDefinitions, fileSystemService, execService);
+  const validation = validateInstallAgentIds(scan, requestedIds);
+  if (!validation.ok) {
+    printInstallValidationFailure(validation, options.json);
+    return;
+  }
+  const agents = findAgentsByIds(scan, requestedIds);
+  if (!options.json) {
+    console.log("Installing GitHits MCP:");
+    console.log();
+  }
+  const outcomes = await installSelectedAgents(agents, scan, fileSystemService, execService, useColors, !options.json);
+  const failed = outcomes.filter((outcome) => outcome.status === "failed");
+  const canAuthenticate = hasUsableInstallOutcome(outcomes);
+  const authStatus = canAuthenticate ? await getStagedInstallAuthStatus(createLoginDeps) : "not_checked";
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+  if (options.json) {
+    printAgenticInstallJson(outcomes, authStatus);
+    return;
+  }
+  console.log();
+  if (failed.length === 0) {
+    console.log("GitHits MCP installation complete.");
+  } else {
+    console.log("GitHits MCP installation completed with errors.");
+    for (const outcome of failed) {
+      console.log(`  ${outcome.name}: ${outcome.message ?? "Unknown error"}`);
+    }
+  }
+  console.log();
+  if (canAuthenticate) {
+    if (authStatus === "authenticated") {
+      printAgenticAlreadyAuthenticated();
+    } else if (authStatus === "required") {
+      printAgenticLoginInstructions(useColors);
+    } else {
+      printAgenticAuthNotChecked(useColors);
+    }
+  } else {
+    console.log("Fix installation errors before starting sign-in.");
+  }
+  console.log();
+}
 function printAuthExplanation() {
   console.log("    GitHits authentication is required before your agent can use GitHits tools.");
   console.log();
@@ -10184,6 +10783,62 @@ async function verifyAgentConfigured(agent, fileSystemService, execService) {
     message: `${agent.name} verification failed: agent not detected after setup.`
   };
 }
+async function executeAgentSetupWithVerification(agent, fileSystemService, execService) {
+  const config = getResolvedSetupConfig(agent, fileSystemService);
+  let result = config.method === "cli" ? await executeCliSetup(config, execService) : config.method === "config-file" ? await executeConfigFileSetup(config, fileSystemService) : await executeCompositeSetup(config, fileSystemService, execService);
+  if (result.status === "success" || result.status === "already_configured") {
+    const verification = await verifyAgentConfigured(agent, fileSystemService, execService);
+    if (!verification.ok) {
+      result = {
+        status: "failed",
+        message: agent.id === "gemini-cli" ? "Gemini installation did not complete. Retry, or run: gemini extensions install --consent https://github.com/githits-com/githits-cli" : verification.message ?? `${agent.name} verification failed after setup.`
+      };
+    }
+  }
+  return result;
+}
+async function installSelectedAgents(agents, scan, fileSystemService, execService, useColors, printResults) {
+  const alreadyConfiguredIds = new Set(scan.alreadyConfigured.map((agent) => agent.id));
+  const outcomes = [];
+  const installTasks = createInstallTaskReporter(useColors);
+  for (const agent of agents) {
+    if (alreadyConfiguredIds.has(agent.id)) {
+      outcomes.push({
+        id: agent.id,
+        name: agent.name,
+        status: "already_configured"
+      });
+      if (printResults) {
+        printTask("warning", agent.name, "already configured", useColors);
+      }
+      continue;
+    }
+    const finishTask = printResults ? installTasks.start(agent.name) : () => {};
+    let result;
+    try {
+      result = await executeAgentSetupWithVerification(agent, fileSystemService, execService);
+    } finally {
+      finishTask();
+    }
+    outcomes.push({
+      id: agent.id,
+      name: agent.name,
+      status: result.status,
+      message: result.status === "failed" ? result.message : undefined
+    });
+    if (!printResults) {
+      continue;
+    }
+    if (result.status === "success") {
+      printTask("success", agent.name, "configured and verified", useColors);
+    } else if (result.status === "already_configured") {
+      printTask("warning", agent.name, "already configured", useColors);
+    } else {
+      printTask("failed", agent.name, result.message, useColors);
+    }
+  }
+  return outcomes;
+}
 async function verifyAgentUnconfigured(agent, fileSystemService, execService) {
   const postCheck = await scanAgents([agent], fileSystemService, execService);
   if (postCheck.needsSetup.some((a) => a.id === agent.id)) {
@@ -10303,7 +10958,28 @@ async function scanAgentsForUninstall(fileSystemService, execService) {
 async function initAction(options, deps) {
   const useColors = shouldUseColors();
   const { fileSystemService, promptService, execService, createLoginDeps } = deps;
+  const isInteractive = deps.isInteractive ?? true;
+  if (!validateInitModeOptions(options)) {
+    return;
+  }
+  if (options.detectAgents) {
+    await runDetectAgentsMode(options, fileSystemService, execService, useColors);
+    return;
+  }
+  if (options.installAgents !== undefined) {
+    await runInstallAgentsMode(options, fileSystemService, execService, createLoginDeps, useColors);
+    return;
+  }
   printInitIntro(useColors);
+  if (!isInteractive) {
+    if (options.yes) {
+      printNonInteractiveYesRejected(useColors);
+      return;
+    }
+    printNonInteractiveInitGuidance(useColors);
+    console.log();
+    return;
+  }
   if (!options.yes) {
     let intent;
     try {
@@ -10322,7 +10998,7 @@ async function initAction(options, deps) {
       return;
     }
     if (intent === "later") {
-      console.log("\n  No changes made. Run `githits init` whenever you're ready.\n");
+      console.log("\n  No changes made. Run `npx githits@latest init` whenever you're ready.\n");
       return;
     }
   }
@@ -10361,7 +11037,6 @@ async function initAction(options, deps) {
   } else {
     printTask("success", "Selected all detected tools", "--yes", useColors);
   }
-  const outcomes = [];
   if (toSetup.length === 0 && scan.needsSetup.length > 0) {
     printTask("skipped", "Setup skipped", "no tools selected", useColors);
     console.log();
@@ -10379,39 +11054,7 @@ async function initAction(options, deps) {
     console.log();
     return;
   }
-  const installTasks = createInstallTaskReporter(useColors);
-  for (const agent of toSetup) {
-    const config = getResolvedSetupConfig(agent, fileSystemService);
-    const finishTask = installTasks.start(agent.name);
-    let result;
-    try {
-      result = config.method === "cli" ? await executeCliSetup(config, execService) : config.method === "config-file" ? await executeConfigFileSetup(config, fileSystemService) : await executeCompositeSetup(config, fileSystemService, execService);
-      if (result.status === "success" || result.status === "already_configured") {
-        const verification = await verifyAgentConfigured(agent, fileSystemService, execService);
-        if (!verification.ok) {
-          result = {
-            status: "failed",
-            message: agent.id === "gemini-cli" ? "Gemini installation did not complete. Retry, or run: gemini extensions install --consent https://github.com/githits-com/githits-cli" : verification.message ?? `${agent.name} verification failed after setup.`
-          };
-        }
-      }
-    } finally {
-      finishTask();
-    }
-    outcomes.push({
-      id: agent.id,
-      name: agent.name,
-      status: result.status,
-      message: result.status === "failed" ? result.message : undefined
-    });
-    if (result.status === "success") {
-      printTask("success", agent.name, "configured and verified", useColors);
-    } else if (result.status === "already_configured") {
-      printTask("warning", agent.name, "already configured", useColors);
-    } else {
-      printTask("failed", agent.name, result.message, useColors);
-    }
-  }
+  const outcomes = await installSelectedAgents(toSetup, scan, fileSystemService, execService, useColors, true);
   console.log();
   const configured = outcomes.filter((o) => o.status === "success").length;
   const alreadyDone = outcomes.filter((o) => o.status === "already_configured").length + scan.alreadyConfigured.length;
@@ -10594,7 +11237,7 @@ Scans for available agents that currently have GitHits configured, then removes
 only the GitHits MCP/plugin configuration with your confirmation. Authentication
 tokens are not removed; use \`githits logout\` to remove stored credentials.`;
 function registerInitCommand(program) {
-  const initCommand = program.command("init").summary("Connect GitHits to your coding agents").description(INIT_DESCRIPTION).option("-y, --yes", "Skip prompts, configure all detected tools").option("--skip-login", "Skip authentication step").action(async (options) => {
+  const initCommand = program.command("init").summary("Connect GitHits to your coding agents").description(INIT_DESCRIPTION).option("-y, --yes", "Skip prompts, configure all detected tools").option("--skip-login", "Skip authentication step").option("--detect-agents", "Scan supported agents without installing").option("--install-agents <ids>", "Install MCP server for comma-separated agent IDs from --detect-agents").option("--json", "Emit JSON for --detect-agents or --install-agents").action(async (options) => {
     const fileSystemService = new FileSystemServiceImpl;
     const promptService = new PromptServiceImpl;
     const execService = new ExecServiceImpl;
@@ -10602,7 +11245,8 @@ function registerInitCommand(program) {
       fileSystemService,
       promptService,
       execService,
-      createLoginDeps: () => createContainer()
+      createLoginDeps: () => createContainer(),
+      isInteractive: process.stdin.isTTY === true && process.stdout.isTTY === true
     });
   });
   initCommand.command("uninstall").summary("Remove MCP server from your coding agents").description(INIT_UNINSTALL_DESCRIPTION).option("-y, --yes", "Skip prompts, uninstall from all configured agents").action(async (options) => {
@@ -10665,17 +11309,10 @@ function registerLanguagesCommand(program) {
 // src/commands/logout.ts
 async function logoutAction(deps) {
   const { authStorage, mcpUrl } = deps;
-  const auth = await authStorage.loadTokens(mcpUrl);
   await authStorage.clearAuthSession(mcpUrl);
-  if (!auth) {
-    console.log(`Not currently logged in.
+  console.log(`Logged out.
 `);
-    console.log(`  Environment: ${mcpUrl}`);
-  } else {
-    console.log(`Logged out.
-`);
-    console.log(`  Environment: ${mcpUrl}`);
-  }
+  console.log(`  Environment: ${mcpUrl}`);
 }
 var LOGOUT_DESCRIPTION = `Remove stored credentials.
 
@@ -13005,7 +13642,7 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-70bn2pmx.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-phdms6y7.js");
   return createContainer2();
 }
 function parseTargetSpecs(specs) {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-7b4f7fd5.js";
+} from "./shared/chunk-yqx01jh9.js";
 export {
   version
 };

package/dist/shared/{chunk-70bn2pmx.js → chunk-phdms6y7.js}

@@ -4,8 +4,8 @@ import {
   createAuthStatusDependencies,
   createContainer,
   loadAutoLoginAuthSessionMetadata
-} from "./chunk-tm11qwgr.js";
-import"./chunk-7b4f7fd5.js";
+} from "./chunk-v23wr0eq.js";
+import"./chunk-yqx01jh9.js";
 export {
   loadAutoLoginAuthSessionMetadata,
   createContainer,

package/dist/shared/{chunk-tm11qwgr.js → chunk-v23wr0eq.js}

@@ -1,7 +1,7 @@
 import {
   __require,
   version
-} from "./chunk-7b4f7fd5.js";
+} from "./chunk-yqx01jh9.js";
 
 // src/services/app-config-paths.ts
 var APP_DIR = "githits";
@@ -6217,7 +6217,8 @@ class TokenManager {
   authStorage;
   mcpUrl;
   cachedToken = null;
-  refreshPromise = null;
+  softRefreshPromise = null;
+  forceRefreshPromise = null;
   constructor(deps) {
     this.authService = deps.authService;
     this.authStorage = deps.authStorage;
@@ -6225,6 +6226,9 @@ class TokenManager {
   }
   async getToken() {
     return withTelemetrySpan("token-manager.get-token", async () => {
+      if (this.forceRefreshPromise) {
+        return (await this.forceRefreshPromise).accessToken;
+      }
       if (!this.cachedToken) {
         this.cachedToken = await withTelemetrySpan("token-manager.load-tokens", () => this.authStorage.loadTokens(this.mcpUrl));
         if (!this.cachedToken)
@@ -6235,7 +6239,9 @@ class TokenManager {
       if (!shouldRefresh) {
         return currentToken;
       }
-      const refreshedToken = await this.doRefresh();
+      const refreshedToken = await this.doRefresh({
+        allowFreshExternalToken: true
+      });
       if (refreshedToken) {
         return refreshedToken;
       }
@@ -6246,27 +6252,56 @@ class TokenManager {
     });
   }
   async forceRefresh() {
-    return withTelemetrySpan("token-manager.force-refresh", () => this.doRefresh());
-  }
-  async doRefresh() {
-    if (this.refreshPromise) {
-      return this.refreshPromise;
+    return withTelemetrySpan("token-manager.force-refresh", () => this.doRefresh({ allowFreshExternalToken: false }));
+  }
+  async doRefresh(options) {
+    const result = await this.doRefreshResult(options);
+    return result.accessToken;
+  }
+  async doRefreshResult(options) {
+    if (!options.allowFreshExternalToken) {
+      if (this.forceRefreshPromise)
+        return this.forceRefreshPromise;
+      this.forceRefreshPromise = (async () => {
+        const softResult = await this.softRefreshPromise?.catch(() => {
+          return;
+        });
+        if (softResult?.accessToken && softResult.refreshedViaEndpoint) {
+          return softResult;
+        }
+        return this.executeRefresh(options);
+      })();
+      try {
+        return await this.forceRefreshPromise;
+      } finally {
+        this.forceRefreshPromise = null;
+      }
     }
-    this.refreshPromise = this.executeRefresh();
+    if (this.forceRefreshPromise)
+      return this.forceRefreshPromise;
+    if (this.softRefreshPromise)
+      return this.softRefreshPromise;
+    this.softRefreshPromise = this.executeRefresh(options);
     try {
-      return await this.refreshPromise;
+      return await this.softRefreshPromise;
     } finally {
-      this.refreshPromise = null;
+      this.softRefreshPromise = null;
     }
   }
-  async executeRefresh() {
+  async executeRefresh(options) {
     return withTelemetrySpan("token-manager.refresh", async () => {
-      const tokens = this.cachedToken ?? await withTelemetrySpan("token-manager.load-tokens", () => this.authStorage.loadTokens(this.mcpUrl));
-      if (!tokens)
-        return;
+      const candidate = await this.loadRefreshCandidate();
+      if (!candidate)
+        return refreshResult(undefined, false);
+      if (candidate.externallyUpdated && options.allowFreshExternalToken) {
+        const { shouldRefresh } = shouldRefreshToken(candidate.tokens, PROACTIVE_REFRESH_RATIO, new Date);
+        if (!shouldRefresh)
+          return refreshResult(candidate.tokens.accessToken, false);
+      }
+      const tokens = candidate.tokens;
       const client = await withTelemetrySpan("token-manager.load-client", () => this.authStorage.loadClient(this.mcpUrl));
       if (!client)
-        return;
+        return refreshResult(undefined, false);
       let response;
       try {
         const metadata = await withTelemetrySpan("token-manager.discover-endpoints", () => this.authService.discoverEndpoints(this.mcpUrl));
@@ -6279,21 +6314,25 @@ class TokenManager {
       } catch {
         const reloadedToken = await this.loadExternallyUpdatedToken(tokens);
         if (reloadedToken)
-          return reloadedToken.accessToken;
+          return refreshResult(reloadedToken.accessToken, false);
         const isExpired = tokens.expiresAt ? new Date >= new Date(tokens.expiresAt) : false;
+        if (candidate.externallyUpdated && !isExpired) {
+          return refreshResult(tokens.accessToken, false);
+        }
         if (isExpired) {
           const currentStoredTokens = await this.loadExternallyUpdatedToken(tokens);
-          if (currentStoredTokens)
-            return currentStoredTokens.accessToken;
+          if (currentStoredTokens) {
+            return refreshResult(currentStoredTokens.accessToken, false);
+          }
           const cleared = await withTelemetrySpan("token-manager.clear-tokens-if-unchanged", () => this.authStorage.clearTokensIfUnchanged(this.mcpUrl, tokens));
           if (!cleared) {
             const currentToken = await this.authStorage.loadTokens(this.mcpUrl);
             this.cachedToken = currentToken;
-            return currentToken?.accessToken;
+            return refreshResult(currentToken?.accessToken, false);
           }
           this.cachedToken = null;
         }
-        return;
+        return refreshResult(undefined, false);
       }
       const newTokenData = {
         accessToken: response.accessToken,
@@ -6301,30 +6340,53 @@ class TokenManager {
         expiresAt: new Date(Date.now() + response.expiresIn * 1000).toISOString(),
         createdAt: new Date().toISOString()
       };
-      const externallyUpdatedToken = await this.loadExternallyUpdatedToken(tokens, {
-        treatMissingAsExternalUpdate: true
-      });
-      if (externallyUpdatedToken === null)
-        return;
-      if (externallyUpdatedToken)
-        return externallyUpdatedToken.accessToken;
       const saved = await withTelemetrySpan("token-manager.save-tokens", () => this.authStorage.saveTokensIfUnchanged(this.mcpUrl, tokens, newTokenData));
       if (!saved) {
-        const currentToken = await this.authStorage.loadTokens(this.mcpUrl);
-        this.cachedToken = currentToken;
-        return currentToken?.accessToken;
+        return this.resolveSuccessfulRefreshConflict(tokens, response, newTokenData);
       }
       this.cachedToken = newTokenData;
-      return response.accessToken;
+      return refreshResult(response.accessToken, true);
     });
   }
-  async loadExternallyUpdatedToken(failedTokens, options = {}) {
-    const storedTokens = await withTelemetrySpan("token-manager.reload-tokens", () => this.authStorage.loadTokens(this.mcpUrl));
+  async resolveSuccessfulRefreshConflict(refreshedFrom, response, newTokenData) {
+    const currentToken = await withTelemetrySpan("token-manager.reload-tokens", () => this.authStorage.loadTokens(this.mcpUrl));
+    if (!currentToken) {
+      this.cachedToken = null;
+      return refreshResult(undefined, false);
+    }
+    if (!response.refreshToken || currentToken.refreshToken !== refreshedFrom.refreshToken) {
+      this.cachedToken = currentToken;
+      return refreshResult(currentToken.accessToken, false);
+    }
+    const saved = await withTelemetrySpan("token-manager.save-rotated-tokens-after-conflict", () => this.authStorage.saveTokensIfUnchanged(this.mcpUrl, currentToken, newTokenData));
+    if (saved) {
+      this.cachedToken = newTokenData;
+      return refreshResult(newTokenData.accessToken, true);
+    }
+    const latestToken = await withTelemetrySpan("token-manager.reload-tokens", () => this.authStorage.loadTokens(this.mcpUrl));
+    this.cachedToken = latestToken;
+    return refreshResult(latestToken?.accessToken, false);
+  }
+  async loadRefreshCandidate() {
+    const storedTokens = await withTelemetrySpan("token-manager.load-tokens", () => this.authStorage.loadTokens(this.mcpUrl));
+    if (!this.cachedToken) {
+      this.cachedToken = storedTokens;
+      return storedTokens ? { tokens: storedTokens, externallyUpdated: false } : null;
+    }
     if (!storedTokens) {
-      if (options.treatMissingAsExternalUpdate)
-        this.cachedToken = null;
-      return options.treatMissingAsExternalUpdate ? null : undefined;
+      this.cachedToken = null;
+      return null;
     }
+    if (!areSameTokenData(storedTokens, this.cachedToken)) {
+      this.cachedToken = storedTokens;
+      return { tokens: storedTokens, externallyUpdated: true };
+    }
+    return { tokens: this.cachedToken, externallyUpdated: false };
+  }
+  async loadExternallyUpdatedToken(failedTokens) {
+    const storedTokens = await withTelemetrySpan("token-manager.reload-tokens", () => this.authStorage.loadTokens(this.mcpUrl));
+    if (!storedTokens)
+      return;
     if (areSameTokenData(storedTokens, failedTokens))
       return;
     this.cachedToken = storedTokens;
@@ -6334,6 +6396,9 @@ class TokenManager {
 function areSameTokenData(a, b) {
   return a.accessToken === b.accessToken && a.refreshToken === b.refreshToken && a.expiresAt === b.expiresAt && a.createdAt === b.createdAt;
 }
+function refreshResult(accessToken, refreshedViaEndpoint) {
+  return { accessToken, refreshedViaEndpoint };
+}
 // src/services/update-check-service.ts
 import semver from "semver";
 var NPM_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/githits/dist-tags";

package/dist/shared/{chunk-7b4f7fd5.js → chunk-yqx01jh9.js}

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // package.json
-var version = "0.4.7";
+var version = "0.4.9";
 
 export { __require, version };

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Code examples from global open source for developers and AI assistants.",
   "mcpServers": {
     "githits": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "githits",
   "description": "CLI companion for GitHits - code examples from global open source for developers and AI assistants",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "type": "module",
   "files": [
     "dist",
@@ -83,6 +83,7 @@
     "open": "^11.0.0",
     "semver": "^7.8.0",
     "smol-toml": "^1.6.1",
+    "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"