githits 0.2.3 → 0.3.0

package/dist/cli.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 import {
+  AuthConfigError,
+  AuthStoragePolicyError,
   AuthenticationError,
+  CLIENT_UPDATE_REQUIRED_REASON,
+  ClientUpdateRequiredError,
   CodeNavigationAccessError,
   CodeNavigationBackendError,
   CodeNavigationFeatureFlagRequiredError,
@@ -16,6 +20,7 @@ import {
   FileSystemServiceImpl,
   MalformedCodeNavigationResponseError,
   MalformedPackageIntelligenceResponseError,
+  NpmRegistryUpdateCheckService,
   PackageIntelligenceAccessError,
   PackageIntelligenceBackendError,
   PackageIntelligenceChangelogSourceNotFoundError,
@@ -26,30 +31,155 @@ import {
   PackageIntelligenceValidationError,
   PackageIntelligenceVersionNotFoundError,
   PromptServiceImpl,
+  createAuthCommandDependencies,
+  createAuthStatusDependencies,
   createContainer,
   debugLog,
   endTelemetrySpan,
   flushTelemetry,
-  getCodeNavigationCapability,
+  formatRequiredUpdateNotice,
+  formatUpdateNotice,
   getCodeNavigationUrl,
-  getEnvApiToken,
-  isCodeNavigationCliOverrideEnabled,
   isTelemetryEnabled,
   refreshExpiredToken,
-  resolveStartupCodeNavigationRegistrationState,
   setClientMode,
   setMcpClientVersionProvider,
+  shouldRunRequiredUpdateEnforcement,
+  shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-a9js75mw.js";
+} from "./shared/chunk-5mk9k2gv.js";
 import {
   __require,
   version
-} from "./shared/chunk-js72s35a.js";
+} from "./shared/chunk-gxya097b.js";
 
 // src/cli.ts
 import { Command } from "commander";
 
+// src/cli/update-check.ts
+function startUpdateCheckTask(service) {
+  const controller = new AbortController;
+  return {
+    promise: service.checkForUpdate(controller.signal),
+    abort: () => controller.abort()
+  };
+}
+function startRequiredUpdateRefreshTask(service) {
+  const controller = new AbortController;
+  return {
+    promise: service.refreshRequiredUpdateStatus(controller.signal),
+    abort: () => controller.abort()
+  };
+}
+function startUpdateCheckTaskForInvocation(options) {
+  if (!shouldRunUpdateCheck({
+    args: options.args,
+    env: options.env,
+    stderrIsTTY: options.stderrIsTTY,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY
+  })) {
+    return;
+  }
+  return startUpdateCheckTask(options.createService());
+}
+function startRequiredUpdateRefreshTaskForInvocation(options) {
+  if (!shouldRunRequiredUpdateEnforcement({
+    args: options.args,
+    env: options.env
+  })) {
+    return;
+  }
+  return startRequiredUpdateRefreshTask(options.createService());
+}
+async function enforceCachedRequiredUpdateForInvocation(options) {
+  if (!shouldRunRequiredUpdateEnforcement({
+    args: options.args,
+    env: options.env
+  })) {
+    return;
+  }
+  const notice = await options.createService().getRequiredUpdateNotice();
+  if (!notice) {
+    return;
+  }
+  if (isJsonInvocation(options.args)) {
+    options.stderr.write(`${JSON.stringify(requiredUpdateEnvelope(notice))}
+`);
+  } else {
+    options.stderr.write(`${formatRequiredUpdateNotice(notice)}
+`);
+  }
+  options.exit(1);
+}
+async function runWithUpdateCheckFlush(action, task, options) {
+  try {
+    return await action();
+  } finally {
+    await flushRequiredUpdateRefresh(options.requiredUpdateRefreshTask, {
+      timeoutMs: options.timeoutMs
+    });
+    await flushUpdateCheckNotice(task, options);
+  }
+}
+async function flushRequiredUpdateRefresh(task, options = {}) {
+  if (!task) {
+    return;
+  }
+  const timeoutMs = options.timeoutMs ?? 50;
+  let timeout;
+  const timeoutPromise = new Promise((resolve) => {
+    timeout = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const result = await Promise.race([task.promise, timeoutPromise]);
+  if (timeout) {
+    clearTimeout(timeout);
+  }
+  if (result === "timeout") {
+    task.abort();
+  }
+}
+async function flushUpdateCheckNotice(task, options) {
+  if (!task) {
+    return;
+  }
+  const timeoutMs = options.timeoutMs ?? 50;
+  let timeout;
+  const timeoutPromise = new Promise((resolve) => {
+    timeout = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const result = await Promise.race([task.promise, timeoutPromise]);
+  if (timeout) {
+    clearTimeout(timeout);
+  }
+  if (result === "timeout") {
+    task.abort();
+    return;
+  }
+  if (!result) {
+    return;
+  }
+  options.stderr.write(`${formatUpdateNotice(result)}
+`);
+}
+function isJsonInvocation(args) {
+  return args.includes("--json");
+}
+function requiredUpdateEnvelope(notice) {
+  return {
+    error: `Update required: ${notice.reason}`,
+    code: "UPDATE_REQUIRED",
+    retryable: false,
+    details: {
+      currentVersion: notice.currentVersion,
+      ...notice.latestKnownVersion ? { latestKnownVersion: notice.latestKnownVersion } : {},
+      updateCommand: notice.updateCommand,
+      reason: notice.reason
+    }
+  };
+}
+
 // src/commands/auth-status.ts
 function displayExpiry(expiresAt) {
   if (!expiresAt) {
@@ -65,23 +195,12 @@ function displayExpiry(expiresAt) {
     console.log(`  Expires: in ${minutesLeft} minute${minutesLeft !== 1 ? "s" : ""}`);
   }
 }
-function displayCodeNavigationStatus(capability, overrideEnabled) {
-  console.log(`  Code navigation: ${capability}`);
-  console.log(`  CLI override: ${overrideEnabled ? "enabled" : "disabled"}`);
-}
 async function authStatusAction(deps) {
-  const {
-    authStorage,
-    authService,
-    mcpUrl,
-    envApiToken,
-    codeNavigationCliOverrideEnabled
-  } = deps;
+  const { authStorage, authService, mcpUrl, envApiToken } = deps;
   if (envApiToken) {
     console.log(`Authenticated via environment variable.
 `);
     console.log(`  Source: GITHITS_API_TOKEN`);
-    displayCodeNavigationStatus(getCodeNavigationCapability(envApiToken), codeNavigationCliOverrideEnabled);
     return;
   }
   const auth = await authStorage.loadTokens(mcpUrl);
@@ -90,7 +209,6 @@ async function authStatusAction(deps) {
 `);
     console.log(`  Environment: ${mcpUrl}
 `);
-    displayCodeNavigationStatus("unknown", codeNavigationCliOverrideEnabled);
     console.log("");
     console.log("To authenticate:");
     console.log("  githits login");
@@ -100,12 +218,10 @@ async function authStatusAction(deps) {
     const refreshed = await refreshExpiredToken(authService, authStorage, mcpUrl);
     if (refreshed) {
       const refreshedAuth = await authStorage.loadTokens(mcpUrl);
-      const capability = getCodeNavigationCapability(refreshedAuth?.accessToken);
       console.log(`Authenticated (token refreshed).
 `);
       console.log(`  Environment: ${mcpUrl}`);
       displayExpiry(refreshedAuth?.expiresAt ?? null);
-      displayCodeNavigationStatus(capability, codeNavigationCliOverrideEnabled);
       console.log(`
   Storage: ${authStorage.getStorageLocation()}`);
       return;
@@ -115,7 +231,6 @@ async function authStatusAction(deps) {
     console.log(`  Environment: ${mcpUrl}`);
     console.log(`  Expired: ${new Date(auth.expiresAt).toLocaleDateString()}
 `);
-    displayCodeNavigationStatus("unknown", codeNavigationCliOverrideEnabled);
     console.log("");
     console.log("Run `githits login` to re-authenticate.");
     return;
@@ -124,35 +239,26 @@ async function authStatusAction(deps) {
 `);
   console.log(`  Environment: ${mcpUrl}`);
   displayExpiry(auth.expiresAt);
-  displayCodeNavigationStatus(getCodeNavigationCapability(auth.accessToken), codeNavigationCliOverrideEnabled);
   console.log(`
   Storage: ${authStorage.getStorageLocation()}`);
 }
 var STATUS_DESCRIPTION = `Show current authentication status.
 
 Displays details about the stored token including environment
-and expiration. Useful for debugging authentication issues.`;
+and expiration. If GITHITS_API_TOKEN is set, reports that source
+without reading local OAuth storage. Useful for debugging authentication issues.`;
 function registerAuthStatusCommand(program) {
   program.command("status").summary("Show authentication status").description(STATUS_DESCRIPTION).action(async () => {
-    const deps = await createContainer();
+    const deps = await createAuthStatusDependencies();
     await authStatusAction(deps);
   });
 }
 // src/commands/gated-command-group.ts
 async function resolveGatedCommandGroupRegistrationState(options = {}) {
   const codeNavigationUrl = options.codeNavigationUrl ?? getCodeNavigationUrl();
-  if (!codeNavigationUrl) {
-    return { codeNavigationUrl: undefined, shouldRegister: false };
-  }
-  const overrideEnabled = options.overrideEnabled ?? isCodeNavigationCliOverrideEnabled();
-  const registrationState = options.capability !== undefined || options.expiredStoredAuth !== undefined ? {
-    capability: options.capability ?? "unknown",
-    expiredStoredAuth: options.expiredStoredAuth ?? false
-  } : await resolveStartupCodeNavigationRegistrationState();
-  const envTokenPresent = options.envTokenPresent ?? Boolean(getEnvApiToken());
   return {
     codeNavigationUrl,
-    shouldRegister: overrideEnabled || registrationState.capability === "enabled" || envTokenPresent || registrationState.expiredStoredAuth
+    shouldRegister: codeNavigationUrl.length > 0
   };
 }
 
@@ -346,6 +452,9 @@ function mapCodeNavigationError(error2) {
   return mapped;
 }
 function classify(error2) {
+  if (error2 instanceof ClientUpdateRequiredError) {
+    return buildUpdateRequiredError(error2.reason, error2.currentVersion);
+  }
   if (error2 instanceof CodeNavigationVersionNotFoundError) {
     const details = {};
     if (error2.packageName)
@@ -456,6 +565,27 @@ function classify(error2) {
   }
   return { code: "UNKNOWN", message: "Unknown error", retryable: false };
 }
+function buildUpdateRequiredError(reason = CLIENT_UPDATE_REQUIRED_REASON, currentVersion) {
+  return {
+    code: "UPDATE_REQUIRED",
+    message: `Update required: ${reason}`,
+    retryable: false,
+    details: {
+      reason,
+      updateCommand: "npm i -g githits@latest",
+      ...currentVersion ? { currentVersion } : {}
+    }
+  };
+}
+function formatMappedErrorForTerminal(mapped) {
+  if (mapped.code !== "UPDATE_REQUIRED") {
+    return mapped.message;
+  }
+  const detail = mapped.details ?? {};
+  const updateCommand = typeof detail.updateCommand === "string" ? detail.updateCommand : "npm i -g githits@latest";
+  return [mapped.message, "", "Update with:", `  ${updateCommand}`].join(`
+`);
+}
 function classifyBackendError(error2) {
   const details = {};
   if (typeof error2.status === "number")
@@ -2305,6 +2435,9 @@ function mapPackageIntelligenceError(error2) {
   return mapped;
 }
 function classify2(error2) {
+  if (error2 instanceof ClientUpdateRequiredError) {
+    return buildUpdateRequiredError(error2.reason, error2.currentVersion);
+  }
   if (error2 instanceof PackageIntelligenceTargetNotFoundError || error2 instanceof PackageIntelligenceChangelogSourceNotFoundError) {
     return {
       code: "NOT_FOUND",
@@ -2864,19 +2997,20 @@ function isSeverityLabel(value) {
 function buildPackageVulnerabilitiesSuccessPayload(report, options = {}) {
   const pkg = report.package;
   const security = report.security;
-  const total = security?.vulnerabilityCount ?? 0;
+  const dedupedAdvisories = dedupAdvisoriesByAlias(security?.vulnerabilities ?? []);
+  const total = security?.affectedVulnerabilityCount ?? dedupedAdvisories.length;
   const payload = {
     registry: lowerRegistry3(pkg.registry),
     name: pkg.name,
     version: pkg.version,
-    summary: buildSummary(total, security)
+    summary: buildSummary(total, security, dedupedAdvisories)
   };
   const requestedEcho = deriveRequestedVersion2(options.requestedVersion, pkg.version);
   if (requestedEcho !== undefined) {
     payload.requestedVersion = requestedEcho;
   }
   if (total > 0) {
-    const sortedAdvisories = sortAdvisories((security?.vulnerabilities ?? []).map(buildAdvisory));
+    const sortedAdvisories = sortAdvisories(dedupedAdvisories.map(buildAdvisory));
     if (sortedAdvisories.length > 0) {
       payload.advisories = sortedAdvisories;
     }
@@ -2915,14 +3049,19 @@ function parseVersionForSort(v) {
   });
   return { main, pre };
 }
-function buildSummary(total, security) {
+function buildSummary(total, security, dedupedAdvisories) {
   const summary = { total };
-  if (total === 0)
-    return summary;
+  if (security) {
+    summary.affectedVulnerabilityCount = security.affectedVulnerabilityCount;
+    summary.nonAffectingVulnerabilityCount = security.nonAffectingVulnerabilityCount;
+    summary.allVulnerabilityCount = security.allVulnerabilityCount;
+  }
   if (typeof security?.currentVersionAffected === "boolean") {
     summary.affected = security.currentVersionAffected;
   }
-  const bySeverity = computeBySeverity(security?.vulnerabilities ?? []);
+  if (total === 0)
+    return summary;
+  const bySeverity = computeBySeverity(dedupedAdvisories);
   const anyCounted = Object.values(bySeverity).some((n) => n > 0);
   if (anyCounted) {
     const trimmed = {};
@@ -2977,6 +3116,231 @@ function vulnSeverityLabel(score) {
     return "medium";
   return "low";
 }
+function dedupAdvisoriesByAlias(advisories) {
+  if (advisories.length === 0)
+    return [];
+  const parent = new Map;
+  const find = (id) => {
+    let root = id;
+    let next = parent.get(root);
+    while (next !== undefined && next !== root) {
+      root = next;
+      next = parent.get(root);
+    }
+    let cursor = id;
+    while (cursor !== root) {
+      const parentOfCursor = parent.get(cursor);
+      if (parentOfCursor === undefined)
+        break;
+      parent.set(cursor, root);
+      cursor = parentOfCursor;
+    }
+    return root;
+  };
+  const union = (a, b) => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb)
+      parent.set(ra, rb);
+  };
+  const ensure = (id) => {
+    if (!parent.has(id))
+      parent.set(id, id);
+  };
+  const advisoryKeys = [];
+  for (let i = 0;i < advisories.length; i++) {
+    const advisory = advisories[i];
+    if (!advisory) {
+      advisoryKeys.push(`__synthetic_${i}`);
+      continue;
+    }
+    const ids = [];
+    if (advisory.osvId)
+      ids.push(advisory.osvId);
+    for (const alias of advisory.aliases ?? []) {
+      if (alias)
+        ids.push(alias);
+    }
+    if (ids.length === 0) {
+      const synthetic = `__synthetic_${i}`;
+      ensure(synthetic);
+      advisoryKeys.push(synthetic);
+      continue;
+    }
+    for (const id of ids)
+      ensure(id);
+    for (let j = 1;j < ids.length; j++) {
+      const a = ids[j - 1];
+      const b = ids[j];
+      if (a !== undefined && b !== undefined)
+        union(a, b);
+    }
+    advisoryKeys.push(ids[0]);
+  }
+  const clusters = new Map;
+  for (let i = 0;i < advisories.length; i++) {
+    const advisory = advisories[i];
+    if (!advisory)
+      continue;
+    const key = advisoryKeys[i];
+    if (key === undefined)
+      continue;
+    const root = find(key);
+    const bucket = clusters.get(root);
+    if (bucket)
+      bucket.push(advisory);
+    else
+      clusters.set(root, [advisory]);
+  }
+  const merged = [];
+  for (const cluster of clusters.values()) {
+    merged.push(mergeAdvisoryCluster(cluster));
+  }
+  return merged;
+}
+function mergeAdvisoryCluster(cluster) {
+  if (cluster.length === 1) {
+    const only = cluster[0];
+    if (!only)
+      throw new Error("empty advisory cluster");
+    return only;
+  }
+  const canonical = pickCanonical(cluster);
+  const aliasSet = new Set;
+  for (const member of cluster) {
+    if (member.osvId)
+      aliasSet.add(member.osvId);
+    for (const alias of member.aliases ?? []) {
+      if (alias)
+        aliasSet.add(alias);
+    }
+  }
+  if (canonical.osvId)
+    aliasSet.delete(canonical.osvId);
+  const aliases = Array.from(aliasSet).sort();
+  const affectedRangesSet = new Set;
+  const matchedAffectedRangesSet = new Set;
+  const fixedInSet = new Set;
+  const duplicateIdsSet = new Set;
+  let isMalicious = false;
+  let affectsInspectedVersion = false;
+  let affectedVersionRangesTruncated = false;
+  let affectedVersionRangesCount = 0;
+  let latestModifiedAt = canonical.modifiedAt;
+  let withdrawnAt;
+  let allWithdrawn = true;
+  let maxSeverityScore = typeof canonical.severityScore === "number" ? canonical.severityScore : 0;
+  for (const member of cluster) {
+    for (const range of member.affectedVersionRanges ?? []) {
+      affectedRangesSet.add(range);
+    }
+    for (const range of member.matchedAffectedVersionRanges ?? []) {
+      matchedAffectedRangesSet.add(range);
+    }
+    for (const fix of member.fixedInVersions ?? []) {
+      fixedInSet.add(fix);
+    }
+    for (const duplicateId of member.duplicateIds ?? []) {
+      duplicateIdsSet.add(duplicateId);
+    }
+    if (member.isMalicious === true)
+      isMalicious = true;
+    if (member.affectsInspectedVersion === true)
+      affectsInspectedVersion = true;
+    if (member.affectedVersionRangesTruncated === true) {
+      affectedVersionRangesTruncated = true;
+    }
+    if (typeof member.affectedVersionRangesCount === "number") {
+      affectedVersionRangesCount = Math.max(affectedVersionRangesCount, member.affectedVersionRangesCount);
+    }
+    if (member.modifiedAt) {
+      if (!latestModifiedAt || member.modifiedAt > latestModifiedAt) {
+        latestModifiedAt = member.modifiedAt;
+      }
+    }
+    if (member.withdrawnAt) {
+      if (!withdrawnAt || member.withdrawnAt > withdrawnAt) {
+        withdrawnAt = member.withdrawnAt;
+      }
+    } else {
+      allWithdrawn = false;
+    }
+    if (!member.withdrawnAt && typeof member.severityScore === "number" && member.severityScore > maxSeverityScore) {
+      maxSeverityScore = member.severityScore;
+    }
+  }
+  const merged = {
+    ...canonical,
+    aliases
+  };
+  if (maxSeverityScore > 0) {
+    merged.severityScore = maxSeverityScore;
+  }
+  if (affectedRangesSet.size > 0) {
+    merged.affectedVersionRanges = Array.from(affectedRangesSet);
+  }
+  const exactOrLowerBoundCount = Math.max(affectedVersionRangesCount, affectedRangesSet.size);
+  if (exactOrLowerBoundCount > 0) {
+    merged.affectedVersionRangesCount = exactOrLowerBoundCount;
+  }
+  if (affectedVersionRangesTruncated) {
+    merged.affectedVersionRangesTruncated = true;
+  }
+  if (matchedAffectedRangesSet.size > 0) {
+    merged.matchedAffectedVersionRanges = Array.from(matchedAffectedRangesSet);
+  }
+  if (affectsInspectedVersion)
+    merged.affectsInspectedVersion = true;
+  if (duplicateIdsSet.size > 0) {
+    merged.duplicateIds = Array.from(duplicateIdsSet).sort();
+  }
+  if (fixedInSet.size > 0) {
+    merged.fixedInVersions = Array.from(fixedInSet);
+  }
+  if (isMalicious)
+    merged.isMalicious = true;
+  if (latestModifiedAt) {
+    merged.modifiedAt = latestModifiedAt;
+  } else {
+    delete merged.modifiedAt;
+  }
+  if (allWithdrawn && withdrawnAt) {
+    merged.withdrawnAt = withdrawnAt;
+  } else {
+    delete merged.withdrawnAt;
+  }
+  return merged;
+}
+function pickCanonical(cluster) {
+  const ranked = cluster.slice().sort((a, b) => {
+    const aHasScore = typeof a.severityScore === "number" && a.severityScore > 0 ? 1 : 0;
+    const bHasScore = typeof b.severityScore === "number" && b.severityScore > 0 ? 1 : 0;
+    if (aHasScore !== bHasScore)
+      return bHasScore - aHasScore;
+    const aRank = idPrefixRank(a.osvId);
+    const bRank = idPrefixRank(b.osvId);
+    if (aRank !== bRank)
+      return aRank - bRank;
+    const aId = a.osvId ?? "";
+    const bId = b.osvId ?? "";
+    if (aId !== bId)
+      return aId < bId ? -1 : 1;
+    return 0;
+  });
+  const winner = ranked[0];
+  if (!winner)
+    throw new Error("empty cluster passed to pickCanonical");
+  return winner;
+}
+function idPrefixRank(id) {
+  if (!id)
+    return 99;
+  if (id.startsWith("GHSA-"))
+    return 0;
+  if (id.startsWith("RUSTSEC-"))
+    return 2;
+  return 1;
+}
 function buildAdvisory(advisory) {
   const lean = {};
   if (advisory.osvId)
@@ -2996,6 +3360,21 @@ function buildAdvisory(advisory) {
   if (advisory.affectedVersionRanges && advisory.affectedVersionRanges.length > 0) {
     lean.affectedRanges = advisory.affectedVersionRanges.slice();
   }
+  if (typeof advisory.affectedVersionRangesCount === "number") {
+    lean.affectedVersionRangesCount = advisory.affectedVersionRangesCount;
+  }
+  if (advisory.affectedVersionRangesTruncated === true) {
+    lean.affectedVersionRangesTruncated = true;
+  }
+  if (typeof advisory.affectsInspectedVersion === "boolean") {
+    lean.affectsInspectedVersion = advisory.affectsInspectedVersion;
+  }
+  if (advisory.matchedAffectedVersionRanges && advisory.matchedAffectedVersionRanges.length > 0) {
+    lean.matchedAffectedVersionRanges = advisory.matchedAffectedVersionRanges.slice();
+  }
+  if (advisory.duplicateIds && advisory.duplicateIds.length > 0) {
+    lean.duplicateIds = advisory.duplicateIds.slice();
+  }
   if (advisory.fixedInVersions && advisory.fixedInVersions.length > 0) {
     lean.fixedIn = advisory.fixedInVersions.slice();
   }
@@ -3078,7 +3457,7 @@ function formatPackageVulnerabilitiesTerminal(report, options = {}) {
     const lines = [headerLine];
     if (requestedLine)
       lines.push(requestedLine);
-    lines.push("No known vulnerabilities.");
+    lines.push(formatNoAffectedVulnerabilitiesLine(payload));
     return `${lines.join(`
 `)}
 `;
@@ -3112,15 +3491,25 @@ function formatHeader(payload, useColors) {
 function formatSummaryLine(payload, useColors) {
   const n = payload.summary.total;
   const noun = n === 1 ? "vulnerability" : "vulnerabilities";
-  const base = `${n} known ${noun}`;
+  const verb = n === 1 ? "affects" : "affect";
+  const base = `${n} ${noun} ${verb} this version`;
   if (payload.summary.affected === true) {
-    return colorize(`${base} · latest affected`, "yellow", useColors);
+    return colorize(base, "yellow", useColors);
   }
   if (payload.summary.affected === false) {
-    return `${base} · latest clean`;
+    return base;
   }
   return base;
 }
+function formatNoAffectedVulnerabilitiesLine(payload) {
+  const historical = payload.summary.nonAffectingVulnerabilityCount ?? 0;
+  if (historical > 0) {
+    const noun = historical === 1 ? "historical advisory" : "historical advisories";
+    const verb = historical === 1 ? "does" : "do";
+    return `No vulnerabilities affect this version (${historical} ${noun} ${verb} not apply).`;
+  }
+  return "No known vulnerabilities affect this version.";
+}
 function formatBreakdownLine(summary, useColors) {
   if (summary.total <= 1)
     return;
@@ -3206,7 +3595,7 @@ function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimi
     lines.push(`    ${label.padEnd(detailWidth)} ${value}`);
   };
   if (advisory.affectedRanges && advisory.affectedRanges.length > 0) {
-    pushRow("affected", formatRangeList(advisory.affectedRanges, verbose, useColors, rangeLimit));
+    pushRow("affected", formatRangeList(advisory.affectedRanges, verbose, useColors, rangeLimit, advisory.affectedVersionRangesCount, advisory.affectedVersionRangesTruncated));
   }
   if (advisory.fixedIn && advisory.fixedIn.length > 0) {
     pushRow("fixed in", advisory.fixedIn.join(", "));
@@ -3233,13 +3622,23 @@ function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimi
   }
   return lines;
 }
-function formatRangeList(ranges, verbose, useColors, limit) {
+function formatRangeList(ranges, verbose, useColors, limit, totalCount, backendTruncated) {
+  const actualTotal = Math.max(totalCount ?? ranges.length, ranges.length);
+  const backendHidden = backendTruncated === true ? actualTotal - ranges.length : 0;
+  const appendBackendHint = (shown2) => {
+    if (backendHidden > 0) {
+      const hint2 = dim(`… (+${backendHidden} ranges omitted by service)`, useColors);
+      return shown2.length > 0 ? `${shown2}, ${hint2}` : hint2;
+    }
+    return shown2;
+  };
   if (verbose || ranges.length <= limit) {
-    return ranges.join(", ");
+    return appendBackendHint(ranges.join(", "));
   }
   const shown = ranges.slice(0, limit).join(", ");
-  const hiddenCount = ranges.length - limit;
-  const hint = dim(`… (+${hiddenCount} more; use -v)`, useColors);
+  const localHidden = ranges.length - limit;
+  const hintText = backendHidden > 0 ? `… (+${localHidden} more with -v; +${backendHidden} omitted by service)` : `… (+${localHidden} more; use -v)`;
+  const hint = dim(hintText, useColors);
   return `${shown}, ${hint}`;
 }
 function resolveAffectedRangesLimit(terminalWidth) {
@@ -3254,8 +3653,8 @@ function formatUpgradeFooter(paths) {
   if (!paths || paths.length === 0)
     return;
   if (paths.length === 1)
-    return `Upgrade to ${paths[0]}.`;
-  return `Upgrade options: ${paths.join(", ")}.`;
+    return `Fix version: ${paths[0]}.`;
+  return `Fix versions: ${paths.join(", ")}.`;
 }
 // src/shared/parse-lines-option.ts
 function parseLinesOption(raw) {
@@ -3435,10 +3834,11 @@ Need help? support@githits.com`);
   throw new AuthRequiredError(`Authentication required${suffix}`);
 }
 // src/shared/unified-search-request.ts
+var DEFAULT_UNIFIED_SEARCH_LIMIT = 10;
 function buildUnifiedSearchParams(input) {
   const targets = resolveTargets(input.target, input.targets);
   const rawQuery = normaliseRequiredQuery(input.query);
-  const limit = input.limit ?? 20;
+  const limit = input.limit ?? DEFAULT_UNIFIED_SEARCH_LIMIT;
   const offset = input.offset ?? 0;
   const waitTimeoutMs = input.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
   const qualifierClauses = buildQualifierClauses({
@@ -3544,7 +3944,7 @@ function buildFilters(input) {
   return Object.keys(filters).length > 0 ? filters : undefined;
 }
 // src/shared/unified-search-response.ts
-var DEFAULT_LIMIT2 = 20;
+var DEFAULT_LIMIT2 = DEFAULT_UNIFIED_SEARCH_LIMIT;
 var DEFAULT_OFFSET = 0;
 function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outcome) {
   const warnings = outcome.state === "completed" ? outcome.result.queryWarnings : outcome.result?.queryWarnings ?? outcome.progress?.queryWarnings ?? [];
@@ -3567,6 +3967,9 @@ function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outco
     const sourceStatus2 = compactSourceStatus(result?.sourceStatus);
     if (sourceStatus2)
       payload.sourceStatus = sourceStatus2;
+    const combinedWarnings2 = combineWarnings(warnings, sourceStatus2);
+    if (combinedWarnings2.length > 0)
+      payload.warnings = combinedWarnings2;
     return payload;
   }
   const completed = {
@@ -3583,8 +3986,18 @@ function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outco
   const sourceStatus = compactSourceStatus(outcome.result.sourceStatus);
   if (sourceStatus)
     completed.sourceStatus = sourceStatus;
+  const combinedWarnings = combineWarnings(warnings, sourceStatus);
+  if (combinedWarnings.length > 0)
+    completed.warnings = combinedWarnings;
   return completed;
 }
+function combineWarnings(parserWarnings, sourceStatus) {
+  const out = [];
+  if (parserWarnings.length > 0)
+    out.push(...parserWarnings);
+  out.push(...buildSourceStatusWarnings(sourceStatus));
+  return out;
+}
 function buildUnifiedSearchErrorPayload(error2) {
   const mapped = mapCodeNavigationError(error2);
   const payload = {
@@ -3629,15 +4042,16 @@ function buildUnifiedSearchStatusResultPayload(result) {
   if (result.page.hasMore) {
     payload.nextOffset = result.page.offset + result.page.returned;
   }
-  if (result.queryWarnings.length > 0) {
-    payload.warnings = result.queryWarnings;
-  }
   if (result.sources.length > 0) {
     payload.sources = result.sources.map((entry) => entry.toLowerCase());
   }
   const sourceStatus = compactSourceStatus(result.sourceStatus);
   if (sourceStatus)
     payload.sourceStatus = sourceStatus;
+  const combinedWarnings = combineWarnings(result.queryWarnings, sourceStatus);
+  if (combinedWarnings.length > 0) {
+    payload.warnings = combinedWarnings;
+  }
   return payload;
 }
 function buildQueryEcho(params, rawQuery, compiledQuery, warnings) {
@@ -3763,6 +4177,46 @@ function compactProgress(progress) {
     payload.expiresAt = progress.expiresAt;
   return payload;
 }
+function buildSourceStatusWarnings(sourceStatus) {
+  if (!sourceStatus || sourceStatus.length === 0)
+    return [];
+  const warnings = [];
+  for (const entry of sourceStatus) {
+    const message = warningForEntry(entry);
+    if (message !== undefined)
+      warnings.push(message);
+  }
+  return warnings;
+}
+function warningForEntry(entry) {
+  const reasons = [];
+  if (entry.incompatibleQueryFeatures?.length) {
+    reasons.push(`incompatible query features [${entry.incompatibleQueryFeatures.join(", ")}]`);
+  }
+  if (entry.ignoredQueryFeatures?.length) {
+    reasons.push(`ignored query features [${entry.ignoredQueryFeatures.join(", ")}]`);
+  }
+  if (entry.incompatibleFilters?.length) {
+    reasons.push(`incompatible filters [${entry.incompatibleFilters.join(", ")}]`);
+  }
+  if (entry.ignoredFilters?.length) {
+    reasons.push(`ignored filters [${entry.ignoredFilters.join(", ")}]`);
+  }
+  if (entry.indexingStatus) {
+    reasons.push(`indexing status ${entry.indexingStatus}`);
+  }
+  if (entry.codeIndexState) {
+    reasons.push(`code index state ${entry.codeIndexState}`);
+  }
+  const prefix = `Source '${entry.source}' for ${entry.targetLabel}`;
+  if (reasons.length > 0) {
+    return `${prefix}: ${reasons.join("; ")}`;
+  }
+  if (entry.note) {
+    return `${prefix}: ${entry.note}`;
+  }
+  return;
+}
 function compactSourceStatus(sourceStatus) {
   if (!sourceStatus || sourceStatus.length === 0)
     return;
@@ -3962,6 +4416,12 @@ function formatScore(score) {
 }
 function buildTrailer2(payload) {
   const lines = [];
+  if (payload.warnings && payload.warnings.length > 0) {
+    lines.push("warnings:");
+    for (const warning2 of payload.warnings) {
+      lines.push(`  - ${warning2}`);
+    }
+  }
   if (payload.hasMore) {
     const nextOffsetHint = typeof payload.nextOffset === "number" ? ` Pass offset=${payload.nextOffset} for the next page or limit=N to widen.` : " Pass limit=N to widen.";
     lines.push(`More hits available.${nextOffsetHint}`);
@@ -4308,6 +4768,9 @@ function parseIntCliOption(raw, name, min, max) {
   return parsed;
 }
 function formatIndexingError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "INDEXING")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -4325,6 +4788,9 @@ function formatIndexingError(mapped) {
 `);
 }
 function formatFileErrorWithFilesHint(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code === "FILE_NOT_FOUND") {
     return `${mapped.message}
   Use \`code files\` to list available paths.`;
@@ -4590,7 +5056,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 (requires --git-ref)").option("--git-ref <ref>", "Tag, commit, branch, or HEAD. Required with --repo-url.").option("--path <path>", "Exact file path to grep").option("--glob <glob>", "Glob scope (repeatable)", collectRepeatable, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable, []).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}`, collectRepeatable, []).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-9zze00cp.js");
+    const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -4974,7 +5440,7 @@ function handleDocsListError(error2, json) {
       ...mapped.details ? { details: mapped.details } : {}
     }));
   } else {
-    console.error(mapped.message);
+    console.error(formatMappedErrorForTerminal(mapped));
   }
   process.exit(1);
 }
@@ -5030,7 +5496,7 @@ function handleDocsReadError(error2, json) {
       ...mapped.details ? { details: mapped.details } : {}
     }));
   } else {
-    console.error(mapped.message);
+    console.error(formatMappedErrorForTerminal(mapped));
   }
   process.exit(1);
 }
@@ -5109,7 +5575,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-9zze00cp.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -5883,6 +6349,36 @@ var TIMEOUT_MS = 5 * 60 * 1000;
 function randomPort() {
   return Math.floor(Math.random() * 2000) + 8000;
 }
+async function preflightAuthPersistence(authStorage, mcpUrl) {
+  const probeUrl = `${mcpUrl.replace(/\/+$/, "")}/__githits_storage_probe__`;
+  const probeClient = {
+    clientId: "__githits_storage_probe__",
+    clientSecret: "__githits_storage_probe__",
+    redirectUri: "http://127.0.0.1:1/callback",
+    registeredAt: new Date(0).toISOString()
+  };
+  const probeTokens = {
+    accessToken: "__githits_storage_probe__",
+    refreshToken: "__githits_storage_probe__",
+    expiresAt: new Date(0).toISOString(),
+    createdAt: new Date(0).toISOString()
+  };
+  try {
+    await authStorage.saveClient(probeUrl, probeClient);
+    await authStorage.saveTokens(probeUrl, probeTokens);
+    await authStorage.clearTokens(probeUrl);
+    await authStorage.clearClient(probeUrl);
+    return null;
+  } catch (error2) {
+    await authStorage.clearTokens(probeUrl).catch(() => {});
+    await authStorage.clearClient(probeUrl).catch(() => {});
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    return {
+      status: "failed",
+      message: `Cannot persist OAuth credentials: ${message}`
+    };
+  }
+}
 async function loginFlow(options, deps) {
   const { authService, authStorage, browserService, mcpUrl } = deps;
   if (options.port !== undefined && (Number.isNaN(options.port) || options.port < 1 || options.port > 65535)) {
@@ -5906,6 +6402,9 @@ async function loginFlow(options, deps) {
   if (!existing) {
     await authStorage.clearClient(mcpUrl);
   }
+  const persistenceError = await preflightAuthPersistence(authStorage, mcpUrl);
+  if (persistenceError)
+    return persistenceError;
   console.log("Discovering OAuth endpoints...");
   const metadata = await authService.discoverEndpoints(mcpUrl);
   let client = await authStorage.loadClient(mcpUrl);
@@ -6051,13 +6550,15 @@ You're ready to use githits with your AI assistant.`);
 var LOGIN_DESCRIPTION = `Authenticate with your GitHits account via browser.
 
 Opens your browser to complete authentication securely using OAuth.
-The CLI receives tokens stored locally and used for API requests.
+OAuth credentials are stored in the system keychain by default. If your
+machine has no usable keychain, use GITHITS_API_TOKEN or explicitly configure
+auth.storage = "file". File storage is plaintext on disk.
 
 Use --no-browser in environments without a display (CI, SSH sessions)
 to get a URL you can open on another device.`;
 function registerLoginCommand(program) {
   program.command("login").summary("Authenticate with your GitHits account").description(LOGIN_DESCRIPTION).option("--no-browser", "Print URL instead of opening browser").option("--port <port>", "Port for local callback server", parseInt).option("--force", "Re-authenticate even if already logged in").action(async (options) => {
-    const deps = await createContainer();
+    const deps = await createAuthCommandDependencies();
     await loginAction(options, deps);
   });
 }
@@ -6252,7 +6753,7 @@ function registerInitCommand(program) {
       fileSystemService,
       promptService,
       execService,
-      createLoginDeps: () => createContainer()
+      createLoginDeps: () => createAuthCommandDependencies()
     });
   });
 }
@@ -6329,10 +6830,11 @@ var LOGOUT_DESCRIPTION = `Remove stored credentials.
 
 Clears all locally stored authentication data including tokens and
 client registrations. OAuth tokens expire naturally; this
-removes the local copies from the keychain (or fallback file storage).`;
+removes local copies from the keychain, explicit file storage, and
+legacy auth file storage.`;
 function registerLogoutCommand(program) {
   program.command("logout").summary("Remove stored credentials").description(LOGOUT_DESCRIPTION).action(async () => {
-    const deps = await createContainer();
+    const deps = await createAuthCommandDependencies();
     await logoutAction(deps);
   });
 }
@@ -7141,7 +7643,7 @@ var schema9 = {
   min_severity: z10.string().optional().describe("Only return advisories at or above this severity (`low`, `medium`, `high`, `critical`; uppercase tolerated). Omit to see all, including null-severity advisories."),
   include_withdrawn: z10.boolean().optional().describe("Include retracted advisories (default: false).")
 };
-var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, or " + "Crates (other registries are not yet supported for vulnerability " + "data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges and fix versions, plus suggested " + "upgrade paths. Malicious-package advisories surface in a separate " + "bucket. Pass `version` to inspect a specific release; otherwise " + "the latest is checked. Use `min_severity` to filter to a threshold " + "(`low`, `medium`, `high`, `critical`) and `include_withdrawn` to " + "also see retracted advisories.";
+var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, or " + "Crates (other registries are not yet supported for vulnerability " + "data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges, and fix versions. Malicious-package advisories surface in a separate " + "bucket. Pass `version` to inspect a specific release; otherwise " + "the latest is checked. Use `min_severity` to filter to a threshold " + "(`low`, `medium`, `high`, `critical`) and `include_withdrawn` to " + "also see retracted advisories.";
 function createPackageVulnerabilitiesTool(service) {
   return {
     name: "pkg_vulns",
@@ -7368,7 +7870,7 @@ var schema12 = {
   name: z13.string().optional(),
   language: z13.string().optional(),
   allow_partial_results: z13.boolean().optional().describe("Default false waits for all sources; if the wait window expires, returns only searchRef/progress. When true, includes hits from sources that finished so far and still returns searchRef for continuation. Partial payloads support normal pagination via nextOffset."),
-  limit: z13.coerce.number().int().min(1).max(100).optional(),
+  limit: z13.coerce.number().int().min(1).max(100).optional().describe("Maximum results to return (default 10, max 100)."),
   offset: z13.coerce.number().int().min(0).optional(),
   wait_timeout_ms: z13.coerce.number().int().min(0).max(60000).optional(),
   format: z13.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output tuned for agent context efficiency. Pass `format: "json"` for the structured envelope (programmatic consumers, parity testing). `text` is an alias for `text-v1`. The text format is a public, snapshot-tested contract.')
@@ -7473,67 +7975,46 @@ function createSearchStatusTool(service) {
   };
 }
 // src/commands/mcp-instructions.ts
-var CORE_BLOCK = `GitHits surfaces verified, canonical code examples from global open source. Use it when you're stuck, the user is frustrated by repeated failed attempts, you need up-to-date API usage, the question is comparative across OSS projects (e.g. "how does X vs Y handle Z"), the answer requires reading how a real codebase implements a feature, or the user mentions GitHits.
+var CORE_BLOCK = `GitHits provides verified, canonical code examples from global open source. Use it when you're stuck, repeated attempts failed, you need up-to-date API usage, the question is comparative across OSS projects (e.g. "how does X vs Y handle Z"), the answer requires reading how a real codebase implements a feature, or the user mentions GitHits.
 
-Workflow: call \`get_example\` with one focused question, optionally passing \`language\` when the desired language is known; call \`search_language\` first only if you need to force a language and the exact name is uncertain. Send \`feedback\` on the returned solution_id so quality improves. Each search addresses a single issue; reuse context from prior results before re-searching.`;
-var PACKAGE_TOOLS_PREAMBLE = `Package tools work with third-party dependency source plus registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library actually works, or you're evaluating whether to add or upgrade a package.
+Example workflow: call \`get_example\` with one focused question; pass \`language\` only when you know the exact language name, otherwise call \`search_language\` first. Send \`feedback\` on the returned solution_id. Reuse prior results before searching again.`;
+var PACKAGE_TOOLS_PREAMBLE = `Indexed package/source tools inspect third-party dependency source, docs, and registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library works, or you're evaluating whether to add or upgrade a package.
 
 Package spec: \`registry:name[@version]\`.`;
 var PKG_INFO_BULLET = "- `pkg_info` — instant package overview: latest version, license, downloads, quickstart, and active advisory count.";
-var DOCS_LIST_BULLET = "- `docs_list` — browse mixed package documentation pages from hosted docs and repository-backed docs. Each entry includes a stable pageId, source kind, source URL, and for repo docs exact file follow-up metadata.";
+var DOCS_LIST_BULLET = "- `docs_list` — browse hosted and repository-backed package docs. Entries include stable pageIds, source URLs, and repo-file follow-up metadata when available.";
 var DOCS_READ_BULLET = "- `docs_read` — read a documentation page by pageId. Works for both hosted docs and repo-backed docs.";
-var PKG_VULNS_BULLET = "- `pkg_vulns` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages (optionally pinned to `@version`). Malicious-package advisories surface in a disjoint `malware` bucket; filter with `min_severity` or include retracted advisories with `include_withdrawn`.";
-var PKG_DEPS_BULLET = "- `pkg_deps` — direct runtime deps plus, when the backend has them, dev / peer / optional / feature groups. Pass `lifecycle` to filter groups server-side, `include_transitive` for the full graph, and `include_importers` when you also need per-package provenance. Supports npm, PyPI, Hex, Crates, vcpkg, and Zig.";
-var PKG_CHANGELOG_BULLET = "- `pkg_changelog` — release notes for a package or GitHub repo, newest-first. Default latest mode returns the 10 most recent entries with full markdown bodies; `from_version` switches to range mode between two versions. Addressable via `registry` + `package_name` or `repo_url`. Set `include_bodies: false` for a version / date / URL timeline when bodies aren't needed.";
-var SEARCH_BULLET = '- `search` — unified search across indexed dependency code, docs, and explicit symbols. Structured fields are the primary UX; omit `sources` for AUTO. Default response is a compact text listing (`text-v1`); pass `format: "json"` for the structured envelope with full locator fields, highlights, and source status. Returns only trustworthy complete results by default; opt into partial hits with `allow_partial_results: true`. If indexing is still in progress, the response carries a `searchRef`.';
-var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior unified search by `searchRef`. Use it after `search` returns incomplete state to check progress, fetch partial hits when the original request used `allow_partial_results: true`, or fetch final results.";
-var CODE_FILES_BULLET = '- `code_files` — discover what files a dependency ships. Use `path_prefix` to scope to a subdirectory. Default response is a paths-only listing (`text-v1`); pass `format: "json"` for the full envelope with each file\'s language, type, and byte size. Returned paths feed directly into `code_read` and help scope `code_grep`.';
-var CODE_READ_BULLET = "- `code_read` — fetch a file's contents from a dependency. Pass the same `path` emitted by `code_files`. **MCP cap: 150 lines per call** — broader requests (or no range) silently truncate to the first 150 lines from your start, with a `hint` describing what was returned vs. requested. Pick a focused window from a `search` / `code_grep` match. Binary files set `isBinary: true` and omit `content`. A `FILE_NOT_FOUND` (or `NOT_FOUND`) response is the signal to call `code_files` for the actual path.";
-var CODE_GREP_BULLET = '- `code_grep` — deterministic text grep over indexed source files. Use it when you know the exact text or regex to match; use `search` for discovery. Whole-target grep is the default; narrow with `path`, `path_prefix`, `globs`, or `extensions`. Default response groups matches by file with line numbers (`text-v1`); pass `format: "json"` for the `matches[]` array with byte offsets and symbol metadata. Each match\'s `path:line` chains directly into `code_read`.';
+var PKG_VULNS_BULLET = "- `pkg_vulns` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages, optionally pinned to `@version`. Filter with `min_severity`; include retracted advisories with `include_withdrawn`.";
+var PKG_DEPS_BULLET = "- `pkg_deps` — direct runtime deps plus lifecycle/feature groups when available. Use `lifecycle` to filter groups, `include_transitive` for the full graph, and `include_importers` for provenance. Supports npm, PyPI, Hex, Crates, vcpkg, and Zig.";
+var PKG_CHANGELOG_BULLET = "- `pkg_changelog` — release notes for a package or GitHub repo, newest-first. Default latest mode returns recent entries with markdown bodies; `from_version` switches to range mode. Set `include_bodies: false` for a compact timeline.";
+var SEARCH_BULLET = '- `search` — unified search across indexed dependency code, docs, and symbols. Omit `sources` for AUTO. Default output is compact `text-v1`; pass `format: "json"` for locators, highlights, and source status. Complete by default; opt into partial hits with `allow_partial_results: true`. Incomplete responses carry a `searchRef`.';
+var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior `search` by `searchRef` to check progress, fetch partial hits, or fetch final results.";
+var CODE_FILES_BULLET = '- `code_files` — list files in an indexed dependency. Use `path_prefix` to scope to a directory. Returned paths feed into `code_read` and help scope `code_grep`; pass `format: "json"` for language/type/size metadata.';
+var CODE_READ_BULLET = "- `code_read` — read a dependency file by `path`. **MCP cap: 150 lines per call**; choose focused `start_line` / `end_line` windows from `search` or `code_grep`. Binary files set `isBinary: true` and omit `content`. On `FILE_NOT_FOUND` / `NOT_FOUND`, call `code_files` for the actual path.";
+var CODE_GREP_BULLET = "- `code_grep` — deterministic text or regex grep over indexed source. Use it when you know the pattern; use `search` for discovery. Narrow with `path`, `path_prefix`, `globs`, or `extensions`. Each match's `path:line` chains into `code_read`.";
 var SEARCH_VS_SYMBOLS_TIP = 'Prefer `get_example` for canonical example retrieval; prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Use `code_grep` for deterministic text matching and `code_read` for focused-window inspection of a known file.';
-var REFERENCE_FIRST_TIP = "Strategy — reference-first, content-second. Locate symbols and lines with `search` / `code_grep` first, then read only the lines you actually need with `code_read` using explicit `start_line` / `end_line` windows around the match (typically 80-150 lines). The MCP `code_read` surface caps each call at 150 lines; bigger requests are silently truncated. Each turn — including retries to widen or re-narrow — costs context, so pick a focused window the first time rather than starting wide and trimming.";
-var MULTI_TURN_TIP = '**Delegate multi-call work to a sub-agent.** Code-navigation tools (`search`, `code_grep`, `code_read`, `code_files`) are inherently multi-call — answering even simple questions usually takes 3-10 tool calls, and reading raw source into the main conversation compounds quickly. The default approach for any cross-project comparison, codebase mapping, pattern survey, or "how does X actually work" investigation is to spawn a sub-task / sub-agent that does the digging and returns only a compact synthesis. Do the work in the main conversation only when the result genuinely belongs there (e.g., the user asked for a specific snippet to paste into their own code). When in doubt, delegate.';
-function isPackageToolsCapabilityOpen(deps) {
-  return deps.codeNavigationCliOverrideEnabled || deps.codeNavigationCapability === "enabled" || deps.codeNavigationCapability === "unknown" && deps.envApiToken !== undefined;
-}
-function buildMcpInstructions(deps) {
+var REFERENCE_FIRST_TIP = "Strategy — reference-first, content-second. Locate symbols and lines with `search` / `code_grep` first, then read only the needed window with `code_read` using explicit `start_line` / `end_line` values, typically 80-150 lines around the match. The MCP `code_read` surface caps each call at 150 lines.";
+var MULTI_TURN_TIP = '**Delegate multi-call work to a sub-agent.** Code-navigation work (`search`, `code_grep`, `code_read`, `code_files`) often takes 3-10 calls. For cross-project comparisons, codebase mapping, pattern surveys, or "how does X actually work" investigations, spawn a sub-task/sub-agent and ask for a compact synthesis. Do it inline only when the raw snippet belongs in the main conversation.';
+function buildMcpInstructions(_deps) {
   const sections = [CORE_BLOCK];
-  if (!isPackageToolsCapabilityOpen(deps)) {
-    return sections.join(`
-
-`);
-  }
   const bullets = [];
-  if (deps.packageIntelligenceService) {
-    bullets.push(DOCS_LIST_BULLET);
-    bullets.push(DOCS_READ_BULLET);
-    bullets.push(PKG_INFO_BULLET);
-    bullets.push(PKG_VULNS_BULLET);
-    bullets.push(PKG_DEPS_BULLET);
-    bullets.push(PKG_CHANGELOG_BULLET);
-  }
-  if (deps.codeNavigationService) {
-    bullets.push(SEARCH_BULLET);
-    bullets.push(SEARCH_STATUS_BULLET);
-    bullets.push(CODE_FILES_BULLET);
-    bullets.push(CODE_READ_BULLET);
-    bullets.push(CODE_GREP_BULLET);
-  }
-  if (bullets.length === 0) {
-    return sections.join(`
-
-`);
-  }
+  bullets.push(DOCS_LIST_BULLET);
+  bullets.push(DOCS_READ_BULLET);
+  bullets.push(PKG_INFO_BULLET);
+  bullets.push(PKG_VULNS_BULLET);
+  bullets.push(PKG_DEPS_BULLET);
+  bullets.push(PKG_CHANGELOG_BULLET);
+  bullets.push(SEARCH_BULLET);
+  bullets.push(SEARCH_STATUS_BULLET);
+  bullets.push(CODE_FILES_BULLET);
+  bullets.push(CODE_READ_BULLET);
+  bullets.push(CODE_GREP_BULLET);
   const parts = [PACKAGE_TOOLS_PREAMBLE];
-  if (deps.codeNavigationService) {
-    parts.push(MULTI_TURN_TIP);
-  }
+  parts.push(MULTI_TURN_TIP);
   parts.push(bullets.join(`
 `));
-  if (deps.codeNavigationService) {
-    parts.push(REFERENCE_FIRST_TIP);
-    parts.push(SEARCH_VS_SYMBOLS_TIP);
-  }
+  parts.push(REFERENCE_FIRST_TIP);
+  parts.push(SEARCH_VS_SYMBOLS_TIP);
   sections.push(parts.join(`
 
 `));
@@ -7549,22 +8030,17 @@ function getMcpToolDefinitions(deps) {
     eraseTool(createSearchLanguageTool(deps.githitsService)),
     eraseTool(createFeedbackTool(deps.githitsService))
   ];
-  const gateOpen = isPackageToolsCapabilityOpen(deps);
-  if (gateOpen && deps.codeNavigationService) {
-    tools.push(eraseTool(createSearchTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createSearchStatusTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createListFilesTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createReadFileTool(deps.codeNavigationService)));
-    tools.push(eraseTool(createGrepRepoTool(deps.codeNavigationService)));
-  }
-  if (gateOpen && deps.packageIntelligenceService) {
-    tools.push(eraseTool(createListPackageDocsTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createReadPackageDocTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageSummaryTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageVulnerabilitiesTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageDependenciesTool(deps.packageIntelligenceService)));
-    tools.push(eraseTool(createPackageChangelogTool(deps.packageIntelligenceService)));
-  }
+  tools.push(eraseTool(createSearchTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createSearchStatusTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createListFilesTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createReadFileTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createGrepRepoTool(deps.codeNavigationService)));
+  tools.push(eraseTool(createListPackageDocsTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createReadPackageDocTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageSummaryTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageVulnerabilitiesTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageDependenciesTool(deps.packageIntelligenceService)));
+  tools.push(eraseTool(createPackageChangelogTool(deps.packageIntelligenceService)));
   return tools;
 }
 function eraseTool(tool) {
@@ -7632,7 +8108,7 @@ function registerMcpCommand(program) {
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
 
-Available tools depend on the current authentication state and enabled features.`).action(async () => {
+Authenticated tool calls require a valid GitHits token.`).action(async () => {
     if (process.stdout.isTTY && process.stdin.isTTY) {
       showMcpSetupInstructions();
       return;
@@ -7721,6 +8197,9 @@ function handlePkgChangelogCommandError(error2, json) {
   process.exit(1);
 }
 function formatChangelogTerminalError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "VERSION_NOT_FOUND")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -7844,6 +8323,9 @@ function handlePkgDepsCommandError(error2, json) {
   process.exit(1);
 }
 function formatDepsTerminalError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "VERSION_NOT_FOUND")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -7930,7 +8412,7 @@ function handlePkgInfoCommandError(error2, json) {
     }));
     process.exit(1);
   }
-  console.error(mapped.message);
+  console.error(formatMappedErrorForTerminal(mapped));
   process.exit(1);
 }
 var PKG_INFO_DESCRIPTION = `Get a package overview — latest version, license, description,
@@ -8003,6 +8485,9 @@ function handlePkgVulnsCommandError(error2, json) {
   process.exit(1);
 }
 function formatVulnsTerminalError(mapped) {
+  if (mapped.code === "UPDATE_REQUIRED") {
+    return formatMappedErrorForTerminal(mapped);
+  }
   if (mapped.code !== "VERSION_NOT_FOUND")
     return mapped.message;
   const detail = mapped.details ?? {};
@@ -8027,8 +8512,8 @@ function formatVulnsTerminalError(mapped) {
 `);
 }
 var PKG_VULNS_DESCRIPTION = `Show known vulnerabilities for a package. Lists CVE / OSV advisories
-with severity, affected version ranges, fix versions, and suggested
-upgrade paths. Malicious-package advisories are flagged prominently.
+with severity, affected version ranges, and fix versions.
+Malicious-package advisories are flagged prominently.
 
 Package spec: <registry>:<name>[@<version>]. Supported registries:
 npm, pypi, hex, crates. Omit @<version> to check the latest release.
@@ -8155,7 +8640,7 @@ function registerSearchCommand(program) {
     "fixture",
     "build",
     "vendor"
-  ])).option("--public", "Filter to public symbols when supported").option("--name <name>", "Structured name qualifier").option("--lang <language>", "Structured language qualifier").option("--allow-partial", "Include hits already available while indexing continues; a searchRef is still returned so search-status can fetch the rest").option("--limit <n>", "Max results (1-100)").option("--offset <n>", "Result offset").option("--wait <seconds>", "Max seconds to wait before returning a searchRef (0-60; default: 20)").option("--json", "Output as JSON").action(async (query, options) => {
+  ])).option("--public", "Filter to public symbols when supported").option("--name <name>", "Structured name qualifier").option("--lang <language>", "Structured language qualifier").option("--allow-partial", "Include hits already available while indexing continues; a searchRef is still returned so search-status can fetch the rest").option("--limit <n>", "Max results (1-100, default: 10)").option("--offset <n>", "Result offset").option("--wait <seconds>", "Max seconds to wait before returning a searchRef (0-60; default: 20)").option("--json", "Output as JSON").action(async (query, options) => {
     const deps = await loadContainer2();
     await searchAction(query, options, deps);
   });
@@ -8169,14 +8654,6 @@ async function registerUnifiedSearchCommands(program, options = {}) {
   if (!codeNavigationUrl) {
     return;
   }
-  const overrideEnabled = options.overrideEnabled ?? isCodeNavigationCliOverrideEnabled();
-  const registrationState = options.capability !== undefined || options.expiredStoredAuth !== undefined ? {
-    capability: options.capability ?? "unknown",
-    expiredStoredAuth: options.expiredStoredAuth ?? false
-  } : await loadStartupCodeNavigationRegistrationState();
-  if (!overrideEnabled && registrationState.capability !== "enabled" && !registrationState.expiredStoredAuth) {
-    return;
-  }
   registerSearchCommand(program);
 }
 function requireSearchService(deps) {
@@ -8186,13 +8663,9 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-9zze00cp.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
   return createContainer2();
 }
-async function loadStartupCodeNavigationRegistrationState() {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-9zze00cp.js");
-  return resolveStartupCodeNavigationRegistrationState2();
-}
 function parseTargetSpecs(specs) {
   if (!specs || specs.length === 0) {
     throw new InvalidArgumentError("Provide at least one --in target.");
@@ -8525,7 +8998,32 @@ function formatUnifiedSearchMetadata(entry, useColors) {
 }
 // src/cli.ts
 var program = new Command;
+var argv = process.argv.slice(2);
 var commandSpans = new WeakMap;
+var createUpdateCheckService = () => new NpmRegistryUpdateCheckService({
+  currentVersion: version,
+  fileSystemService: new FileSystemServiceImpl
+});
+await enforceCachedRequiredUpdateForInvocation({
+  args: argv,
+  env: process.env,
+  createService: createUpdateCheckService,
+  stderr: process.stderr,
+  exit: process.exit
+});
+var updateCheckTask = startUpdateCheckTaskForInvocation({
+  args: argv,
+  env: process.env,
+  stderrIsTTY: process.stderr.isTTY === true,
+  stdinIsTTY: process.stdin.isTTY === true,
+  stdoutIsTTY: process.stdout.isTTY === true,
+  createService: createUpdateCheckService
+});
+var requiredUpdateRefreshTask = startRequiredUpdateRefreshTaskForInvocation({
+  args: argv,
+  env: process.env,
+  createService: createUpdateCheckService
+});
 if (isTelemetryEnabled()) {
   process.once("exit", (exitCode) => {
     flushTelemetry(exitCode);
@@ -8556,25 +9054,34 @@ registerMcpCommand(program);
 registerExampleCommand(program);
 registerLanguagesCommand(program);
 registerFeedbackCommand(program);
-var argv = process.argv.slice(2);
 var registrationArgv = stripRootRegistrationOptions(argv);
-var shouldLoadGatedHelpRegistration = needsGatedHelpRegistration(registrationArgv);
-var helpRegistrationOptions = shouldLoadGatedHelpRegistration ? await loadHelpRegistrationOptions(registrationArgv) : undefined;
 if (shouldEagerLoadSearchCommands(registrationArgv)) {
-  await withTelemetrySpan("cli.register.search", () => registerUnifiedSearchCommands(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.search", () => registerUnifiedSearchCommands(program));
 }
 if (shouldEagerLoadGatedCommandGroup(registrationArgv, "code")) {
-  await withTelemetrySpan("cli.register.code-group", () => registerCodeCommandGroup(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.code-group", () => registerCodeCommandGroup(program));
 }
 if (shouldEagerLoadGatedCommandGroup(registrationArgv, "pkg")) {
-  await withTelemetrySpan("cli.register.pkg-group", () => registerPkgCommandGroup(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.pkg-group", () => registerPkgCommandGroup(program));
 }
 if (shouldEagerLoadGatedCommandGroup(registrationArgv, "docs")) {
-  await withTelemetrySpan("cli.register.docs-group", () => registerDocsCommandGroup(program, helpRegistrationOptions));
+  await withTelemetrySpan("cli.register.docs-group", () => registerDocsCommandGroup(program));
 }
 var authCommand = program.command("auth").summary("Manage authentication").description("Manage authentication with GitHits.");
 registerAuthStatusCommand(authCommand);
-await withTelemetrySpan("cli.parse", () => program.parseAsync());
+try {
+  await runWithUpdateCheckFlush(() => withTelemetrySpan("cli.parse", () => program.parseAsync()), updateCheckTask, { stderr: process.stderr, requiredUpdateRefreshTask });
+} catch (error2) {
+  if (isUserFacingError(error2)) {
+    console.error(`${error2.message}
+`);
+    process.exit(1);
+  }
+  throw error2;
+}
+function isUserFacingError(error2) {
+  return error2 instanceof AuthConfigError || error2 instanceof AuthStoragePolicyError;
+}
 function stripRootRegistrationOptions(args) {
   return args.filter((arg) => arg !== "--no-color");
 }
@@ -8586,34 +9093,9 @@ function shouldEagerLoadSearchCommands(args) {
   const [firstArg] = args;
   return args.length === 0 || firstArg === "search" || firstArg === "search-status" || firstArg === "--help" || firstArg === "-h" || firstArg === "help" && (!args[1] || isSearchHelpTarget(args[1]));
 }
-function isHelpInvocation(args) {
-  return args.length === 0 || args[0] === "help" || args.includes("--help") || args.includes("-h");
-}
-function needsGatedHelpRegistration(args) {
-  if (!isHelpInvocation(args)) {
-    return false;
-  }
-  const [firstArg, secondArg] = args;
-  if (firstArg === "help") {
-    return isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg" || secondArg === "docs";
-  }
-  return isSearchHelpTarget(firstArg) || firstArg === "code" || firstArg === "pkg" || firstArg === "docs";
-}
 function isSearchHelpTarget(value) {
   return value === "search" || value === "search-status";
 }
-async function loadHelpRegistrationOptions(args) {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-9zze00cp.js");
-  const registrationState = await resolveStartupCodeNavigationRegistrationState2();
-  return {
-    capability: registrationState.capability,
-    expiredStoredAuth: shouldUseExpiredStoredAuthFallbackForHelp(args) ? registrationState.expiredStoredAuth : false
-  };
-}
-function shouldUseExpiredStoredAuthFallbackForHelp(args) {
-  const [firstArg, secondArg] = args;
-  return firstArg === "search" || firstArg === "search-status" || firstArg === "code" || firstArg === "pkg" || firstArg === "docs" || firstArg === "help" && (isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg" || secondArg === "docs");
-}
 function getTelemetryCommandName(command) {
   const names = [];
   let current = command;