githits 0.3.3 → 0.4.0

package/dist/cli.js

@@ -49,11 +49,11 @@ import {
   shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-2d202fpq.js";
+} from "./shared/chunk-1cyka46a.js";
 import {
   __require,
   version
-} from "./shared/chunk-tze0rsay.js";
+} from "./shared/chunk-fqzth5mv.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -254,9 +254,9 @@ async function authStatusAction(deps) {
 `);
     console.log(`  Environment: ${mcpUrl}
 `);
-    console.log("");
-    console.log("To authenticate:");
-    console.log("  githits login");
+    console.log(`  Storage: ${authStorage.getStorageLocation()}
+`);
+    printAuthTroubleshooting();
     return;
   }
   if (auth.expiresAt && new Date(auth.expiresAt) < new Date) {
@@ -276,8 +276,9 @@ async function authStatusAction(deps) {
     console.log(`  Environment: ${mcpUrl}`);
     console.log(`  Expired: ${new Date(auth.expiresAt).toLocaleDateString()}
 `);
-    console.log("");
-    console.log("Run `githits login` to re-authenticate.");
+    console.log(`  Storage: ${authStorage.getStorageLocation()}
+`);
+    printAuthTroubleshooting("expired");
     return;
   }
   console.log(`Authenticated.
@@ -287,6 +288,17 @@ async function authStatusAction(deps) {
   console.log(`
   Storage: ${authStorage.getStorageLocation()}`);
 }
+function printAuthTroubleshooting(reason = "missing") {
+  const loginCommand = reason === "expired" ? "githits login --force" : "githits login";
+  console.log("Recovery steps:");
+  console.log(`  ${loginCommand}`);
+  if (reason === "missing") {
+    console.log("  githits login --force  # if a previous login is stale");
+  }
+  console.log("For CI/automation, set GITHITS_API_TOKEN.");
+  console.log("If your system keychain is locked or unavailable, unlock it and retry.");
+  console.log("As a last resort, set GITHITS_AUTH_STORAGE=file to use plaintext file storage.");
+}
 var STATUS_DESCRIPTION = `Show current authentication status.
 
 Displays details about the stored token including environment
@@ -353,6 +365,11 @@ function highlight(text, useColors) {
     return text;
   return `${colors.bold}${colors.cyan}${text}${colors.reset}`;
 }
+function highlightMatch(text, useColors) {
+  if (!useColors)
+    return text;
+  return `${colors.bold}${colors.yellow}${text}${colors.reset}`;
+}
 function highlightRanges(text, ranges, useColors) {
   if (!useColors || !text || !ranges || ranges.length === 0)
     return text;
@@ -380,7 +397,7 @@ function highlightRanges(text, ranges, useColors) {
   for (const [start, end] of merged) {
     if (cursor < start)
       result += text.slice(cursor, start);
-    result += highlight(text.slice(start, end), useColors);
+    result += highlightMatch(text.slice(start, end), useColors);
     cursor = end;
   }
   if (cursor < text.length)
@@ -763,7 +780,7 @@ function parseCodeNavigationTargetSpec(spec) {
 function parseRepoTarget(spec) {
   const hashIndex = spec.lastIndexOf("#");
   if (hashIndex === -1) {
-    return { repoUrl: spec, gitRef: "HEAD" };
+    throw new InvalidArgumentError("Repository target must include #gitRef for exact code navigation.");
   }
   const repoUrl = spec.slice(0, hashIndex);
   const gitRef = spec.slice(hashIndex + 1);
@@ -804,7 +821,8 @@ function buildSearchHitFollowUpCommand(hit) {
       gitRef: loc.gitRef,
       filePath: loc.filePath,
       startLine: loc.startLine,
-      endLine: loc.endLine
+      endLine: loc.endLine,
+      preferPackageTarget: isPackageTarget(hit)
     });
   }
   if (hit.type === "repository_code" || hit.type === "repository_symbol") {
@@ -833,14 +851,24 @@ function buildCodeReadCommand(input) {
   return parts.join(" ");
 }
 function buildTargetSpec(input) {
+  if (input.preferPackageTarget && input.registry && input.packageName) {
+    return `${input.registry}:${input.packageName}${input.version ? `@${input.version}` : ""}`;
+  }
   if (input.repoUrl) {
-    return `${input.repoUrl}#${input.gitRef ?? "HEAD"}`;
+    if (!input.gitRef)
+      return;
+    return `${input.repoUrl}#${input.gitRef}`;
   }
   if (input.registry && input.packageName) {
     return `${input.registry}:${input.packageName}${input.version ? `@${input.version}` : ""}`;
   }
   return;
 }
+function isPackageTarget(hit) {
+  const registry = hit.locator.registry;
+  const packageName = hit.locator.packageName;
+  return Boolean(registry && packageName && hit.target.startsWith(`${registry}:${packageName}`));
+}
 function appendRange(parts, startLine, endLine) {
   if (typeof startLine === "number")
     parts.push(`start_line=${startLine}`);
@@ -1934,7 +1962,7 @@ function renderListPackageDocsText(envelope) {
     if (page.sourceKind === "repo" && page.repoUrl && page.filePath) {
       lines.push(`  ${buildCodeReadCommand({
         repoUrl: page.repoUrl,
-        gitRef: page.requestedRef ?? page.gitRef,
+        gitRef: page.gitRef,
         filePath: page.filePath,
         startLine: 1,
         endLine: 150
@@ -4110,7 +4138,7 @@ function renderReadPackageDocText(envelope) {
   if (envelope.sourceUrl)
     lines.push(`source: ${envelope.sourceUrl}`);
   if (envelope.filePath) {
-    const ref = envelope.requestedRef ?? envelope.gitRef;
+    const ref = envelope.gitRef;
     lines.push(`file: ${envelope.filePath}${ref ? ` @ ${ref}` : ""}`);
   }
   lines.push("");
@@ -4142,7 +4170,6 @@ function buildRange2(envelope) {
 }
 // src/shared/auto-login.ts
 var AUTO_LOGIN_ELIGIBLE_COMMANDS = new Set([
-  "init",
   "example",
   "languages",
   "feedback",
@@ -4175,9 +4202,6 @@ function isAutoLoginEligibleCommand(command, runtime = {
   stdoutIsTTY: Boolean(process.stdout.isTTY)
 }) {
   const commandPath = getCommandPath(command).join(" ");
-  if (commandPath === "init" && command.opts().skipLogin === true) {
-    return false;
-  }
   if (!AUTO_LOGIN_ELIGIBLE_COMMANDS.has(commandPath)) {
     return false;
   }
@@ -4237,8 +4261,6 @@ function createRootCliPreAction(deps) {
 }
 function getPostLoginContinuationMessage(command) {
   switch (getCommandPath(command).join(" ")) {
-    case "init":
-      return "Authentication complete. Continuing setup...";
     case "example":
       return "Authentication complete. Running example search...";
     case "languages":
@@ -4313,11 +4335,6 @@ function resolveTargets(target, targets) {
     seen.add(key);
     deduped.push(entry);
   }
-  const hasPackageTarget = deduped.some((entry) => entry.packageName);
-  const hasRepoTarget = deduped.some((entry) => entry.repoUrl);
-  if (hasPackageTarget && hasRepoTarget) {
-    throw new InvalidArgumentError("Do not mix package-scoped and repo-scoped targets in one search.");
-  }
   return deduped;
 }
 function normaliseRequiredQuery(query) {
@@ -4376,6 +4393,7 @@ 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 ?? [];
+  const progress = compactProgress(outcome.progress);
   const query = buildQueryEcho(params, rawQuery, compiledQuery, warnings);
   if (outcome.state === "incomplete") {
     const result = outcome.result;
@@ -4389,13 +4407,12 @@ function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outco
     if (result?.page.hasMore === true) {
       payload.nextOffset = result.page.offset + result.page.returned;
     }
-    const progress = compactProgress(outcome.progress);
     if (progress)
       payload.progress = progress;
     const sourceStatus2 = compactSourceStatus(result?.sourceStatus);
     if (sourceStatus2)
       payload.sourceStatus = sourceStatus2;
-    const combinedWarnings2 = combineWarnings(warnings, sourceStatus2);
+    const combinedWarnings2 = combineWarnings(warnings, sourceStatus2, payload.results, progress);
     if (combinedWarnings2.length > 0)
       payload.warnings = combinedWarnings2;
     return payload;
@@ -4414,15 +4431,17 @@ function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outco
   const sourceStatus = compactSourceStatus(outcome.result.sourceStatus);
   if (sourceStatus)
     completed.sourceStatus = sourceStatus;
-  const combinedWarnings = combineWarnings(warnings, sourceStatus);
+  const combinedWarnings = combineWarnings(warnings, sourceStatus, completed.results, progress);
   if (combinedWarnings.length > 0)
     completed.warnings = combinedWarnings;
   return completed;
 }
-function combineWarnings(parserWarnings, sourceStatus) {
+function combineWarnings(parserWarnings, sourceStatus, hits = [], progress) {
   const out = [];
   if (parserWarnings.length > 0)
     out.push(...parserWarnings);
+  out.push(...buildHitFreshnessWarnings(hits));
+  out.push(...buildProgressFreshnessWarnings(progress));
   out.push(...buildSourceStatusWarnings(sourceStatus));
   return out;
 }
@@ -4449,6 +4468,9 @@ function buildUnifiedSearchStatusPayload(outcome) {
     const progress = compactProgress(outcome.progress);
     if (progress)
       payload2.progress = progress;
+    const progressWarnings = buildProgressFreshnessWarnings(progress);
+    if (progressWarnings.length > 0)
+      payload2.warnings = progressWarnings;
     if (outcome.result) {
       payload2.result = buildUnifiedSearchStatusResultPayload(outcome.result);
     }
@@ -4464,6 +4486,7 @@ function buildUnifiedSearchStatusPayload(outcome) {
 }
 function buildUnifiedSearchStatusResultPayload(result) {
   const payload = {
+    query: buildStatusQueryEcho(result),
     hasMore: result.page.hasMore,
     results: result.results.map(buildHitPayload)
   };
@@ -4482,6 +4505,18 @@ function buildUnifiedSearchStatusResultPayload(result) {
   }
   return payload;
 }
+function buildStatusQueryEcho(result) {
+  const query = {
+    raw: result.query
+  };
+  if (result.queryWarnings.length > 0) {
+    query.warnings = result.queryWarnings;
+  }
+  if (result.sources.length > 0) {
+    query.sources = result.sources.map((entry) => entry.toLowerCase());
+  }
+  return query;
+}
 function buildQueryEcho(params, rawQuery, compiledQuery, warnings) {
   const echo = {
     raw: rawQuery
@@ -4531,6 +4566,12 @@ function buildHitPayload(hit) {
     target: hit.targetLabel,
     locator: buildLocatorPayload(hit)
   };
+  appendFreshness(payload, {
+    requestedTargetLabel: hit.requestedTargetLabel,
+    freshTargetLabel: hit.freshTargetLabel,
+    servedTargetLabel: hit.servedTargetLabel,
+    freshness: hit.freshness
+  });
   if (hit.title)
     payload.title = hit.title;
   if (hit.summary)
@@ -4538,6 +4579,9 @@ function buildHitPayload(hit) {
   const highlights = buildHighlights(hit.highlights);
   if (highlights)
     payload.highlights = highlights;
+  const followUp = buildSearchHitFollowUpCommand(payload);
+  if (followUp)
+    payload.followUp = followUp;
   return payload;
 }
 function buildLocatorPayload(hit) {
@@ -4599,10 +4643,79 @@ function compactProgress(progress) {
     targetsTotal: progress.targetsTotal,
     elapsedMs: progress.elapsedMs
   };
+  if (progress.query)
+    payload.query = progress.query;
+  if (progress.requestedSources?.length) {
+    payload.requestedSources = progress.requestedSources.map((entry) => entry.toLowerCase());
+  }
+  if (progress.targetMode)
+    payload.targetMode = progress.targetMode;
+  if (progress.requestedTargets?.length) {
+    payload.requestedTargets = progress.requestedTargets;
+  }
+  if (progress.filters)
+    payload.filters = buildFilterEcho3(progress.filters);
+  if (typeof progress.limit === "number")
+    payload.limit = progress.limit;
+  if (typeof progress.offset === "number")
+    payload.offset = progress.offset;
+  const targets = progress.targets?.map(compactProgressTarget).filter(Boolean);
+  if (targets?.length) {
+    payload.targets = targets;
+  }
   if (progress.expiresAt)
     payload.expiresAt = progress.expiresAt;
+  payload.next = `search_status search_ref=${JSON.stringify(progress.searchRef)}`;
   return payload;
 }
+function appendFreshness(payload, source) {
+  if (!isTrustRelevantFreshness(source.freshness) || !labelsDiverge({
+    requestedTarget: source.requestedTargetLabel,
+    freshTarget: source.freshTargetLabel,
+    servedTarget: source.servedTargetLabel
+  })) {
+    return;
+  }
+  if (source.requestedTargetLabel)
+    payload.requestedTarget = source.requestedTargetLabel;
+  if (source.freshTargetLabel)
+    payload.freshTarget = source.freshTargetLabel;
+  if (source.servedTargetLabel)
+    payload.servedTarget = source.servedTargetLabel;
+  if (source.freshness)
+    payload.freshness = source.freshness;
+}
+function compactProgressTarget(target) {
+  const payload = {};
+  if (target.requested)
+    payload.requested = target.requested;
+  if (target.resolvedRequested)
+    payload.resolvedRequested = target.resolvedRequested;
+  if (target.served)
+    payload.served = target.served;
+  if (target.freshness)
+    payload.freshness = target.freshness;
+  if (target.indexingRef)
+    payload.indexingRef = target.indexingRef;
+  if (target.requestedRefKind)
+    payload.requestedRefKind = target.requestedRefKind;
+  return Object.keys(payload).length > 0 ? payload : undefined;
+}
+function buildFilterEcho3(filters) {
+  const echo = {};
+  if (filters.kind)
+    echo.kind = filters.kind.toLowerCase();
+  if (filters.category)
+    echo.category = filters.category.toLowerCase();
+  if (filters.pathPrefix)
+    echo.pathPrefix = filters.pathPrefix;
+  if (filters.fileIntent)
+    echo.fileIntent = filters.fileIntent.toLowerCase();
+  if (typeof filters.publicOnly === "boolean") {
+    echo.publicOnly = filters.publicOnly;
+  }
+  return Object.keys(echo).length > 0 ? echo : undefined;
+}
 function buildSourceStatusWarnings(sourceStatus) {
   if (!sourceStatus || sourceStatus.length === 0)
     return [];
@@ -4614,8 +4727,51 @@ function buildSourceStatusWarnings(sourceStatus) {
   }
   return warnings;
 }
+function buildHitFreshnessWarnings(hits) {
+  return hits.map((hit) => freshnessWarning({
+    freshness: hit.freshness,
+    requestedTarget: hit.requestedTarget,
+    freshTarget: hit.freshTarget,
+    servedTarget: hit.servedTarget
+  })).filter((entry) => Boolean(entry));
+}
+function buildProgressFreshnessWarnings(progress) {
+  return (progress?.targets ?? []).map((target) => freshnessWarning({
+    freshness: target.freshness,
+    requestedTarget: target.requested,
+    freshTarget: target.resolvedRequested,
+    servedTarget: target.served
+  })).filter((entry) => Boolean(entry));
+}
+function freshnessWarning(input) {
+  if (!isTrustRelevantFreshness(input.freshness))
+    return;
+  if (!labelsDiverge(input))
+    return;
+  const requested = input.requestedTarget ?? "requested target";
+  const served = input.servedTarget ?? "served target";
+  const fresh = input.freshTarget;
+  return fresh ? `requested ${requested}; served stale ${served} while ${fresh} indexes.` : `requested ${requested}; served stale ${served}.`;
+}
+function isTrustRelevantFreshness(value) {
+  return value === "STALE" || value === "INDEXING";
+}
+function labelsDiverge(input) {
+  const served = input.servedTarget;
+  if (!served)
+    return false;
+  return Boolean(input.freshTarget && input.freshTarget !== served || input.requestedTarget && input.requestedTarget !== served);
+}
 function warningForEntry(entry) {
   const reasons = [];
+  const freshness = freshnessWarning({
+    freshness: entry.codeIndexState,
+    requestedTarget: entry.requestedTarget,
+    freshTarget: entry.freshTarget,
+    servedTarget: entry.servedTarget
+  });
+  if (freshness)
+    return freshness;
   if (entry.incompatibleQueryFeatures?.length) {
     reasons.push(`incompatible query features [${entry.incompatibleQueryFeatures.join(", ")}]`);
   }
@@ -4632,7 +4788,9 @@ function warningForEntry(entry) {
     reasons.push(`indexing status ${entry.indexingStatus}`);
   }
   if (entry.codeIndexState) {
-    reasons.push(`code index state ${entry.codeIndexState}`);
+    if (entry.codeIndexState !== "STALE") {
+      reasons.push(`code index state ${entry.codeIndexState}`);
+    }
   }
   const prefix = `Source '${entry.source}' for ${entry.targetLabel}`;
   if (reasons.length > 0) {
@@ -4660,11 +4818,23 @@ function compactSourceStatusEntry(entry) {
     targetLabel: entry.targetLabel
   };
   let interesting = false;
+  const staleDiverges = entry.codeIndexState === "STALE" && labelsDiverge({
+    requestedTarget: entry.requestedTargetLabel,
+    freshTarget: entry.freshTargetLabel,
+    servedTarget: entry.servedTargetLabel
+  });
+  if (staleDiverges) {
+    payload.requestedTarget = entry.requestedTargetLabel;
+    payload.freshTarget = entry.freshTargetLabel;
+    payload.servedTarget = entry.servedTargetLabel;
+    payload.codeIndexState = entry.codeIndexState;
+    interesting = true;
+  }
   if (entry.indexingStatus && entry.indexingStatus !== "INDEXED") {
     payload.indexingStatus = entry.indexingStatus;
     interesting = true;
   }
-  if (entry.codeIndexState && entry.codeIndexState !== "CURRENT" && entry.codeIndexState !== "STALE") {
+  if (entry.codeIndexState && entry.codeIndexState !== "CURRENT" && (entry.codeIndexState !== "STALE" || staleDiverges)) {
     payload.codeIndexState = entry.codeIndexState;
     interesting = true;
   }
@@ -4839,8 +5009,45 @@ function buildTrailer2(payload) {
       lines.push(`  - ${formatSourceStatus(entry)}`);
     }
   }
+  const progress = "progress" in payload ? payload.progress : undefined;
+  if (progress?.targets?.length) {
+    lines.push("progress targets:");
+    for (const target of progress.targets) {
+      lines.push(`  - ${formatProgressTarget(target)}`);
+    }
+  }
   return lines;
 }
+function formatProgressTarget(target) {
+  const parts = [];
+  if (target.requested)
+    parts.push(`requested=${target.requested}`);
+  if (target.resolvedRequested)
+    parts.push(`fresh=${target.resolvedRequested}`);
+  if (target.served)
+    parts.push(`served=${target.served}`);
+  if (target.freshness)
+    parts.push(`state=${describeFreshness(target.freshness)}`);
+  if (target.requestedRefKind)
+    parts.push(`intent=${target.requestedRefKind}`);
+  if (target.indexingRef)
+    parts.push(`indexingRef=${target.indexingRef}`);
+  return parts.length > 0 ? parts.join(SEP6) : "target progress unavailable";
+}
+function describeFreshness(value) {
+  switch (value) {
+    case "PENDING":
+    case "INDEXING":
+      return "indexing fresh target";
+    case "STALE":
+      return "served stale evidence";
+    case "CURRENT":
+    case "INDEXED":
+      return "current";
+    default:
+      return value.toLowerCase();
+  }
+}
 function formatSourceStatus(entry) {
   const parts = [`${entry.source} (${entry.targetLabel})`];
   if (entry.indexingStatus)
@@ -4903,6 +5110,17 @@ function renderUnifiedSearchStatusText(payload) {
   lines.push(buildHeader8(payload));
   if (!payload.completed && payload.progress) {
     lines.push(formatProgress(payload.progress));
+    if (payload.progress.targets?.length) {
+      lines.push("progress targets:");
+      for (const target of payload.progress.targets) {
+        lines.push(`  - ${formatProgressTarget(target)}`);
+      }
+    }
+  }
+  if (!payload.completed && payload.warnings && payload.warnings.length > 0) {
+    lines.push("warnings:");
+    for (const warning2 of payload.warnings)
+      lines.push(`  - ${warning2}`);
   }
   const result = payload.result;
   if (result)
@@ -4969,14 +5187,39 @@ function formatSourceStatus2(entry) {
   return parts.join(SEP7);
 }
 function formatProgress(progress) {
-  return `progress: ${progress.status}, ${progress.targetsReady}/${progress.targetsTotal} targets ready, ${progress.elapsedMs}ms elapsed`;
+  const next = progress.next ? `; next: ${progress.next}` : "";
+  return `progress: ${progress.status}, ${progress.targetsReady}/${progress.targetsTotal} targets ready, ${progress.elapsedMs}ms elapsed${next}`;
 }
 function quote5(value) {
   return JSON.stringify(value);
 }
 // src/shared/unified-search-target.ts
 function parseUnifiedSearchTargetSpec(spec) {
-  return parseCodeNavigationTargetSpec(spec);
+  const trimmed = spec.trim();
+  if (trimmed.length === 0) {
+    throw new InvalidArgumentError("Target spec cannot be empty.");
+  }
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+    return parseDiscoveryRepoTarget(trimmed);
+  }
+  const parsed = parsePackageSpec(trimmed);
+  return {
+    registry: toCodeNavigationRegistry(parsed.registry),
+    packageName: parsed.name,
+    version: parsed.version
+  };
+}
+function parseDiscoveryRepoTarget(spec) {
+  const hashIndex = spec.lastIndexOf("#");
+  if (hashIndex === -1) {
+    return { repoUrl: spec };
+  }
+  const repoUrl = spec.slice(0, hashIndex);
+  const gitRef = spec.slice(hashIndex + 1);
+  if (!repoUrl || !gitRef) {
+    throw new InvalidArgumentError("Repository target must be a full URL with optional #gitRef suffix.");
+  }
+  return { repoUrl, gitRef };
 }
 // src/shared/list-files-request.ts
 var LIMIT_MIN2 = 1;
@@ -5734,7 +5977,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)", 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-b6avnx6d.js");
+    const { createContainer: createContainer2 } = await import("./shared/chunk-1h7sanjw.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -6210,6 +6453,10 @@ async function registerDocsCommandGroup(program, options = {}) {
 // src/commands/example.ts
 import { Option } from "commander";
 async function exampleAction(query, options, deps) {
+  if (!deps.hasValidToken && options.json) {
+    printExampleError("Authentication required. Run `githits login`, then retry this command.", "AUTH_REQUIRED", true);
+    process.exit(1);
+  }
   requireAuth(deps);
   try {
     const result = await deps.githitsService.search({
@@ -6226,10 +6473,21 @@ async function exampleAction(query, options, deps) {
       console.log(result);
     }
   } catch (error2) {
-    console.error(`Failed to get example: ${error2 instanceof Error ? error2.message : error2}`);
+    if (error2 instanceof AuthenticationError) {
+      printExampleError("Authentication required. Run `githits login`, then retry this command.", "AUTH_REQUIRED", options.json ?? false);
+      process.exit(1);
+    }
+    printExampleError(`Failed to get example: ${error2 instanceof Error ? error2.message : error2}`, "UNKNOWN", options.json ?? false);
     process.exit(1);
   }
 }
+function printExampleError(error2, code, json) {
+  if (json) {
+    console.error(JSON.stringify({ error: error2, code, retryable: false }));
+    return;
+  }
+  console.error(error2);
+}
 var EXAMPLE_DESCRIPTION = `Get verified, canonical code examples from global open source.
 
 For dependency, package, or repository source search, use \`githits search\` instead.
@@ -6253,7 +6511,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-b6avnx6d.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-1h7sanjw.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -7140,7 +7398,13 @@ async function loginFlow(options, deps, output = stdoutLoginOutput) {
     state,
     codeChallenge: challenge
   });
-  const serverPromise = authService.startCallbackServer(port, state);
+  let callbackServer;
+  try {
+    callbackServer = await authService.startCallbackServer(port, state);
+  } catch (error2) {
+    const msg = error2 instanceof Error ? error2.message : String(error2);
+    return { status: "failed", message: msg };
+  }
   if (options.browser === false) {
     output.write(`Open this URL in your browser:
 `);
@@ -7148,7 +7412,17 @@ async function loginFlow(options, deps, output = stdoutLoginOutput) {
 `);
   } else {
     output.write("Opening browser...");
-    await browserService.open(authUrl);
+    try {
+      await browserService.open(authUrl);
+    } catch (error2) {
+      const msg = error2 instanceof Error ? error2.message : String(error2);
+      output.write(`Could not open browser automatically: ${msg}
+`);
+      output.write(`Open this URL in your browser:
+`);
+      output.write(`  ${authUrl}
+`);
+    }
   }
   output.write(`Waiting for authentication...
 `);
@@ -7158,12 +7432,13 @@ async function loginFlow(options, deps, output = stdoutLoginOutput) {
   });
   let callback;
   try {
-    callback = await Promise.race([serverPromise, timeoutPromise]);
+    callback = await Promise.race([callbackServer.result, timeoutPromise]);
     if (timeoutId)
       clearTimeout(timeoutId);
   } catch (error2) {
     if (timeoutId)
       clearTimeout(timeoutId);
+    await callbackServer.close().catch(() => {});
     const msg = error2 instanceof Error ? error2.message : "Authentication failed";
     return { status: "failed", message: `${msg}.` };
   }
@@ -7220,7 +7495,7 @@ async function loginAction(options, deps) {
   if (result.status === "failed") {
     console.error(`${result.message}
 `);
-    console.log("Run `githits login` to try again.");
+    printLoginRecoveryHint(result.message);
     process.exit(1);
   }
   console.log(`Logged in successfully.
@@ -7230,6 +7505,16 @@ async function loginAction(options, deps) {
   console.log(`
 You're ready to use githits with your AI assistant.`);
 }
+function printLoginRecoveryHint(message) {
+  console.log("Recovery steps:");
+  console.log("  githits auth status");
+  console.log("  githits login --force");
+  if (message.includes("Cannot persist OAuth credentials")) {
+    console.log("If your system keychain is locked or unavailable, unlock it and retry.");
+    console.log("For CI/automation, set GITHITS_API_TOKEN.");
+    console.log("As a last resort, set GITHITS_AUTH_STORAGE=file to use plaintext file storage.");
+  }
+}
 var LOGIN_DESCRIPTION = `Authenticate with your GitHits account via browser.
 
 Opens your browser to complete authentication securely using OAuth.
@@ -7266,6 +7551,7 @@ async function verifyAgentConfigured(agent, fileSystemService, execService) {
 async function initAction(options, deps) {
   const useColors = shouldUseColors();
   const { fileSystemService, promptService, execService, createLoginDeps } = deps;
+  let continuedWithoutAuth = false;
   console.log(`
   ${colorize("GitHits", "bold", useColors)} — Set up MCP server for your coding agents
 `);
@@ -7289,6 +7575,7 @@ async function initAction(options, deps) {
     } else {
       console.log(`    ${warning(`Login failed: ${loginResult.message}`, useColors)}
 `);
+      printAuthRecoveryHint();
       if (!options.yes) {
         try {
           const choice = await promptService.confirm3("Continue without authentication?");
@@ -7306,6 +7593,7 @@ async function initAction(options, deps) {
           throw err;
         }
       }
+      continuedWithoutAuth = true;
       console.log(`    Continuing without authentication...
 `);
     }
@@ -7329,6 +7617,11 @@ async function initAction(options, deps) {
     return;
   }
   if (scan.needsSetup.length === 0) {
+    if (continuedWithoutAuth) {
+      console.log("  MCP is already configured, but authentication is still required.");
+      console.log("  Run `githits login` before using GitHits tools.\n");
+      return;
+    }
     console.log(`  All detected agents are already configured. Nothing to do.
 `);
     return;
@@ -7401,6 +7694,9 @@ async function initAction(options, deps) {
   const skipped = outcomes.filter((o) => o.status === "skipped").length;
   if (failed > 0) {
     console.log("  Setup completed with errors.");
+  } else if (continuedWithoutAuth && (configured > 0 || alreadyDone > 0)) {
+    console.log("  MCP is configured, but authentication is still required.");
+    console.log("  Run `githits login` before using GitHits tools.");
   } else if (configured > 0 || alreadyDone > 0) {
     console.log("  Done! GitHits is ready.");
   } else if (skipped > 0) {
@@ -7417,6 +7713,15 @@ async function initAction(options, deps) {
   }
   console.log();
 }
+function printAuthRecoveryHint() {
+  console.log("    You can still configure MCP, but GitHits tools will require auth.");
+  console.log("    Recovery steps:");
+  console.log("      githits auth status");
+  console.log("      githits login --force");
+  console.log("    For CI or locked-down machines, set GITHITS_API_TOKEN.");
+  console.log(`    If your system keychain is unavailable, set GITHITS_AUTH_STORAGE=file after accepting plaintext storage.
+`);
+}
 var INIT_DESCRIPTION = `Set up GitHits MCP server for your coding agents.
 
 Authenticates with your GitHits account, then scans for available agents
@@ -7647,7 +7952,7 @@ var structuredCodeTargetSchema = z3.object({
 }).describe("Target: provide registry + package_name (package scope) or repo_url + git_ref (repo scope).");
 var codeTargetSchema = z3.union([
   structuredCodeTargetSchema,
-  z3.string().min(1).describe("Compact target string. Package: `npm:react@18.2.0`. Repository: `https://github.com/facebook/react#HEAD` (git ref suffix optional, defaults to HEAD).")
+  z3.string().min(1).describe("Compact target string. Package: `npm:react@18.2.0`. Repository: `https://github.com/facebook/react#HEAD` (git ref suffix required for exact code navigation).")
 ]);
 function resolveCodeTarget(target) {
   if (typeof target === "string") {
@@ -7679,10 +7984,7 @@ function resolveCodeTarget(target) {
     if (!target.repo_url) {
       return invalidTargetResult("Incomplete repository target: repo_url is required.");
     }
-    return {
-      repoUrl: target.repo_url,
-      gitRef: target.git_ref ?? "HEAD"
-    };
+    return invalidTargetResult("Incomplete repository target: git_ref is required for exact code navigation.");
   }
   return {
     repoUrl: target.repo_url,
@@ -8638,10 +8940,14 @@ function buildRange3(args, textMode) {
 }
 // src/tools/search.ts
 import { z as z13 } from "zod";
+var searchTargetSchema = z13.union([
+  structuredCodeTargetSchema,
+  z13.string().min(1).describe("Compact discovery target string. Package: `npm:react@18.2.0`. Repository: `https://github.com/facebook/react` for backend default branch or `https://github.com/facebook/react#HEAD` for an explicit ref.")
+]);
 var schema12 = {
   query: z13.string().min(1).describe("Discovery query string. Supports implicit AND, uppercase OR, parentheses, unary -, quoted phrases, semantic qualifiers (kind:, category:, path:, lang:, name:, intent:), and routing qualifiers (registry:, package:, version:, repo:). Parsed once and compiled per source; it is not forwarded as a raw backend query."),
-  target: codeTargetSchema.optional(),
-  targets: z13.array(codeTargetSchema).max(20).optional(),
+  target: searchTargetSchema.optional(),
+  targets: z13.array(searchTargetSchema).max(20).optional(),
   sources: z13.array(z13.enum(["docs", "code", "symbol"])).optional().describe("Optional source selection. Omit for backend AUTO."),
   category: z13.enum(["callable", "type", "module", "data", "documentation"]).optional(),
   kind: z13.enum([
@@ -8703,17 +9009,17 @@ function createSearchTool(service) {
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
-        const resolvedTarget = args.target ? resolveCodeTarget(args.target) : undefined;
+        const resolvedTarget = args.target ? resolveSearchTarget(args.target) : undefined;
         if (resolvedTarget && "content" in resolvedTarget)
           return resolvedTarget;
-        const resolvedTargets = args.targets?.map((entry) => resolveCodeTarget(entry));
+        const resolvedTargets = args.targets?.map((entry) => resolveSearchTarget(entry));
         const resolvedTargetsError = resolvedTargets?.find((entry) => ("content" in entry));
         if (resolvedTargetsError) {
           return resolvedTargetsError;
         }
         const built = buildUnifiedSearchParams({
           target: resolvedTarget && !("content" in resolvedTarget) ? resolvedTarget : undefined,
-          targets: resolvedTargets?.filter(isResolvedCodeTarget),
+          targets: resolvedTargets?.filter(isResolvedSearchTarget),
           query: args.query,
           sources: args.sources?.map((entry) => entry.toUpperCase()),
           kind: toSymbolKind(args.kind),
@@ -8744,9 +9050,53 @@ function createSearchTool(service) {
     }
   };
 }
-function isResolvedCodeTarget(target) {
+function isResolvedSearchTarget(target) {
   return !("content" in target);
 }
+function resolveSearchTarget(target) {
+  if (typeof target === "string") {
+    try {
+      return parseUnifiedSearchTargetSpec(target);
+    } catch (error2) {
+      const mapped = mapCodeNavigationError(error2);
+      return errorResult(JSON.stringify({
+        error: mapped.message,
+        code: mapped.code,
+        retryable: mapped.retryable ?? false,
+        ...mapped.details ? { details: mapped.details } : {}
+      }));
+    }
+  }
+  const hasPackageTarget = Boolean(target.registry || target.package_name);
+  const hasRepoTarget = Boolean(target.repo_url || target.git_ref);
+  if (hasPackageTarget && hasRepoTarget) {
+    return invalidSearchTargetResult("Invalid target: provide either registry + package_name or repo_url + git_ref, not both.");
+  }
+  if (!hasPackageTarget && !hasRepoTarget) {
+    return invalidSearchTargetResult("Missing target: provide registry + package_name or repo_url.");
+  }
+  if (hasPackageTarget) {
+    if (!target.registry || !target.package_name) {
+      return invalidSearchTargetResult("Incomplete package target: both registry and package_name are required.");
+    }
+    return {
+      registry: toCodeNavigationRegistry(target.registry),
+      packageName: target.package_name,
+      version: target.version
+    };
+  }
+  if (!target.repo_url) {
+    return invalidSearchTargetResult("Incomplete repository target: repo_url is required.");
+  }
+  return { repoUrl: target.repo_url, gitRef: target.git_ref };
+}
+function invalidSearchTargetResult(message) {
+  return errorResult(JSON.stringify({
+    error: message,
+    code: "INVALID_ARGUMENT",
+    retryable: false
+  }));
+}
 function isTextFormat11(format) {
   return format === undefined || format === "text" || format === "text-v1";
 }
@@ -9506,7 +9856,7 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-b6avnx6d.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-1h7sanjw.js");
   return createContainer2();
 }
 function parseTargetSpecs(specs) {
@@ -9585,8 +9935,9 @@ function formatSearchErrorTerminal(payload, context) {
 function formatUnifiedSearchTerminal(payload) {
   const lines = [];
   const useColors = shouldUseColors();
-  if (payload.query.warnings && payload.query.warnings.length > 0) {
-    for (const warning2 of payload.query.warnings) {
+  const warnings = payload.warnings ?? payload.query.warnings;
+  if (warnings && warnings.length > 0) {
+    for (const warning2 of warnings) {
       lines.push(`Warning: ${warning2}`);
     }
     lines.push("");
@@ -9625,7 +9976,7 @@ function formatUnifiedSearchTerminal(payload) {
   lines.push("");
   for (const entry of display) {
     const location = formatUnifiedSearchLocation(entry.locator);
-    const header = formatUnifiedSearchHeader(entry, useColors, location);
+    const header = formatUnifiedSearchHeader(entry, useColors, location, payload.query.raw);
     lines.push(header);
     const metadata = formatUnifiedSearchMetadata(entry, useColors);
     if (metadata.length > 0) {
@@ -9692,7 +10043,11 @@ function formatSearchStatusCompletedTerminal(payload) {
     results: payload.result.results,
     searchRef: payload.searchRef,
     progress: undefined,
-    query: { warnings: payload.result.warnings },
+    query: {
+      raw: payload.result.query?.raw,
+      warnings: payload.result.warnings
+    },
+    warnings: payload.result.warnings,
     sourceStatus: payload.result.sourceStatus
   });
 }
@@ -9704,7 +10059,11 @@ function formatSearchStatusPartialTerminal(payload) {
     results: payload.result.results,
     searchRef: payload.searchRef,
     progress: payload.progress,
-    query: { warnings: payload.result.warnings },
+    query: {
+      raw: payload.result.query?.raw,
+      warnings: payload.result.warnings
+    },
+    warnings: payload.result.warnings,
     sourceStatus: payload.result.sourceStatus
   });
 }
@@ -9815,11 +10174,113 @@ function formatUnifiedSearchLocation(locator) {
   }
   return `${locator.filePath}:${locator.startLine}${locator.endLine && locator.endLine !== locator.startLine ? `-${locator.endLine}` : ""}`;
 }
-function formatUnifiedSearchHeader(entry, useColors, location) {
-  const primary = entry.type === "documentation_page" ? entry.target : location ? `${entry.target} ${location}` : entry.target;
+function formatUnifiedSearchHeader(entry, useColors, location, rawQuery) {
+  const primary = formatUnifiedSearchPrimary(entry.type, entry.target, location, rawQuery, useColors);
   const badge = `[${formatUnifiedSearchResultLabel(entry.type)}]`;
   const title = entry.title ? highlightRanges(entry.title, entry.highlights?.title, useColors) : undefined;
-  return `${highlight(primary, useColors)} ${dim(badge, useColors)}${title ? ` - ${title}` : ""}`;
+  return `${primary} ${dim(badge, useColors)}${title ? ` - ${title}` : ""}`;
+}
+function formatUnifiedSearchPrimary(type, target, location, rawQuery, useColors) {
+  const formattedTarget = highlight(target, useColors);
+  if (type === "documentation_page" || !location) {
+    return formattedTarget;
+  }
+  return `${formattedTarget} ${formatLocationWithQueryHighlights(location, rawQuery, useColors)}`;
+}
+function formatLocationWithQueryHighlights(location, rawQuery, useColors) {
+  const ranges = buildQueryTermRanges(location, rawQuery);
+  if (ranges.length === 0)
+    return highlight(location, useColors);
+  if (!useColors)
+    return location;
+  let result = "";
+  let cursor2 = 0;
+  for (const [start, end] of ranges) {
+    if (cursor2 < start)
+      result += highlight(location.slice(cursor2, start), true);
+    result += highlightMatch(location.slice(start, end), true);
+    cursor2 = end;
+  }
+  if (cursor2 < location.length)
+    result += highlight(location.slice(cursor2), true);
+  return result;
+}
+function buildQueryTermRanges(text, rawQuery) {
+  const terms = extractQueryHighlightTerms(rawQuery);
+  if (terms.length === 0)
+    return [];
+  const lowerText = text.toLowerCase();
+  const ranges = [];
+  const orderedTerms = [...terms].sort((left, right) => right.length - left.length);
+  for (const term of orderedTerms) {
+    const lowerTerm = term.toLowerCase();
+    let cursor2 = 0;
+    while (cursor2 < lowerText.length) {
+      const start = lowerText.indexOf(lowerTerm, cursor2);
+      if (start === -1)
+        break;
+      const end = start + lowerTerm.length;
+      if (!ranges.some((range) => rangesOverlap(range, [start, end]))) {
+        ranges.push([start, end]);
+      }
+      cursor2 = end;
+    }
+  }
+  return mergeRanges2(ranges);
+}
+function extractQueryHighlightTerms(rawQuery) {
+  if (!rawQuery)
+    return [];
+  const booleanOperators = new Set(["AND", "OR", "NOT"]);
+  const terms = new Set;
+  const quotedRanges = [];
+  for (const match of rawQuery.matchAll(/"([^"]+)"/g)) {
+    const phrase = match[1];
+    if (phrase) {
+      addQueryHighlightTerm(phrase, terms, booleanOperators, {
+        stripQualifier: false
+      });
+    }
+    if (typeof match.index === "number") {
+      quotedRanges.push([match.index, match.index + match[0].length]);
+    }
+  }
+  for (const match of rawQuery.matchAll(/[A-Za-z0-9_./@:-]+/g)) {
+    const index = match.index ?? 0;
+    if (quotedRanges.some(([start, end]) => index >= start && index < end)) {
+      continue;
+    }
+    addQueryHighlightTerm(match[0], terms, booleanOperators);
+  }
+  return Array.from(terms);
+}
+function addQueryHighlightTerm(candidate, terms, booleanOperators, options = { stripQualifier: true }) {
+  const normalised = options.stripQualifier && /^[A-Za-z]+:.+/.test(candidate) ? candidate.split(":").slice(1).join(":") : candidate;
+  const term = normalised.replace(/^[-+]+/, "").replace(/[-+]+$/, "");
+  if (term.length < 2)
+    return;
+  if (booleanOperators.has(term.toUpperCase()))
+    return;
+  terms.add(term);
+}
+function rangesOverlap(left, right) {
+  return left[0] < right[1] && right[0] < left[1];
+}
+function mergeRanges2(ranges) {
+  const sorted = ranges.filter(([start, end]) => end > start).sort((left, right) => left[0] - right[0] || left[1] - right[1]);
+  const merged = [];
+  for (const current of sorted) {
+    const previous = merged[merged.length - 1];
+    if (!previous || current[0] > previous[1]) {
+      merged.push(current);
+      continue;
+    }
+    merged[merged.length - 1] = [
+      previous[0],
+      Math.max(previous[1], current[1])
+    ];
+  }
+  return merged;
 }
 function formatUnifiedSearchMetadata(entry, useColors) {
   if (entry.type !== "documentation_page" && entry.type !== "repository_doc") {
@@ -9827,16 +10288,14 @@ function formatUnifiedSearchMetadata(entry, useColors) {
   }
   const lines = [];
   if (entry.locator.pageId) {
-    lines.push(`  ${dim("pageId:", useColors)} ${entry.locator.pageId}`);
+    if (entry.type === "documentation_page") {
+      lines.push(`  ${dim("pageId:", useColors)} ${entry.locator.pageId}`);
+    }
   }
   const sourceBadge = entry.locator.sourceKind?.toLowerCase() === "repository" ? "[repo]" : entry.locator.sourceKind?.toLowerCase() === "crawled" ? "[crawled]" : undefined;
-  if (entry.locator.sourceUrl) {
+  if (entry.locator.sourceUrl && entry.type === "documentation_page") {
     lines.push(`  ${dim("source:", useColors)} ${sourceBadge ? `${sourceBadge} ` : ""}${entry.locator.sourceUrl}`);
   }
-  if (entry.type === "repository_doc" && entry.locator.filePath) {
-    const ref = entry.locator.requestedRef ?? entry.locator.gitRef;
-    lines.push(`  ${dim("file:", useColors)} ${entry.locator.filePath}${ref ? ` @ ${ref}` : ""}`);
-  }
   return lines;
 }
 // src/cli.ts