githits 0.3.3 → 0.4.1

package/dist/cli.js

@@ -49,11 +49,11 @@ import {
   shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-2d202fpq.js";
+} from "./shared/chunk-rgvmtzjt.js";
 import {
   __require,
   version
-} from "./shared/chunk-tze0rsay.js";
+} from "./shared/chunk-f2ah8xnh.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("");
@@ -4140,9 +4168,293 @@ function buildRange2(envelope) {
     return `${envelope.totalLines} lines`;
   return;
 }
+// src/commands/login.ts
+var stdoutLoginOutput = {
+  write: (message) => {
+    console.log(message);
+  }
+};
+var stderrLoginOutput = {
+  write: (message) => {
+    console.error(message);
+  }
+};
+var TIMEOUT_MS = 5 * 60 * 1000;
+var AUTH_TIMEOUT_MESSAGE = "Authentication timed out after 5 minutes. The browser link has expired, so it will not work anymore. Run the same command again to try signing in again.";
+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.saveAuthSession(probeUrl, probeClient, probeTokens);
+    await authStorage.clearAuthSession(probeUrl);
+    return null;
+  } catch (error2) {
+    await authStorage.clearAuthSession(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, output = stdoutLoginOutput) {
+  const { authService, authStorage, browserService, mcpUrl } = deps;
+  const existing = await authStorage.loadTokens(mcpUrl);
+  if (options.port !== undefined && (Number.isNaN(options.port) || options.port < 1 || options.port > 65535)) {
+    return {
+      status: "failed",
+      message: "Invalid port number. Must be between 1 and 65535."
+    };
+  }
+  if (existing && !options.force) {
+    const isExpired = existing.expiresAt && new Date(existing.expiresAt) < new Date;
+    if (!isExpired) {
+      return { status: "already_authenticated", message: "Already logged in." };
+    }
+    output.write(`Token expired. Starting new login...
+`);
+  } else if (existing && options.force) {
+    output.write(`Re-authenticating (--force flag)...
+`);
+  }
+  if (!existing) {
+    await authStorage.clearClient(mcpUrl);
+  }
+  const persistenceError = await preflightAuthPersistence(authStorage, mcpUrl);
+  if (persistenceError)
+    return persistenceError;
+  output.write("Discovering OAuth endpoints...");
+  const metadata = await authService.discoverEndpoints(mcpUrl);
+  let client = await authStorage.loadClient(mcpUrl);
+  const hadStoredClient = client !== null;
+  let shouldClearClientOnFailedAttempt = false;
+  let port;
+  let redirectUri;
+  if (client) {
+    if (options.port) {
+      redirectUri = `http://127.0.0.1:${options.port}/callback`;
+      if (redirectUri !== client.redirectUri) {
+        output.write("Registering CLI client with new port...");
+        const registration = await authService.registerClient({
+          registrationEndpoint: metadata.registrationEndpoint,
+          redirectUri
+        });
+        client = {
+          clientId: registration.clientId,
+          clientSecret: registration.clientSecret,
+          redirectUri,
+          registeredAt: new Date().toISOString()
+        };
+        shouldClearClientOnFailedAttempt = !hadStoredClient;
+      }
+      port = options.port;
+    } else {
+      redirectUri = client.redirectUri;
+      const storedUrl = new URL(redirectUri);
+      port = Number(storedUrl.port) || randomPort();
+    }
+  } else {
+    port = options.port ?? randomPort();
+    redirectUri = `http://127.0.0.1:${port}/callback`;
+    output.write("Registering CLI client...");
+    const registration = await authService.registerClient({
+      registrationEndpoint: metadata.registrationEndpoint,
+      redirectUri
+    });
+    client = {
+      clientId: registration.clientId,
+      clientSecret: registration.clientSecret,
+      redirectUri,
+      registeredAt: new Date().toISOString()
+    };
+    shouldClearClientOnFailedAttempt = !hadStoredClient;
+  }
+  const { verifier, challenge, state } = authService.generatePkceParams();
+  const authUrl = authService.buildAuthUrl({
+    authorizationEndpoint: metadata.authorizationEndpoint,
+    clientId: client.clientId,
+    redirectUri,
+    state,
+    codeChallenge: challenge
+  });
+  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:
+`);
+    output.write(`  ${authUrl}
+`);
+  } else {
+    output.write("Opening browser...");
+    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...
+`);
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error(AUTH_TIMEOUT_MESSAGE)), TIMEOUT_MS);
+  });
+  let callback;
+  try {
+    callback = await Promise.race([callbackServer.result, timeoutPromise]);
+    if (timeoutId)
+      clearTimeout(timeoutId);
+  } catch (error2) {
+    if (timeoutId)
+      clearTimeout(timeoutId);
+    await callbackServer.close().catch(() => {});
+    if (shouldClearClientOnFailedAttempt) {
+      await authStorage.clearClient(mcpUrl).catch(() => {});
+    }
+    const msg = error2 instanceof Error ? error2.message : "Authentication failed";
+    return { status: "failed", message: ensureTerminalPeriod(msg) };
+  }
+  if (callback.type !== "success") {
+    await new Promise((r) => setTimeout(r, 2000));
+    if (shouldClearClientOnFailedAttempt) {
+      await authStorage.clearClient(mcpUrl).catch(() => {});
+    }
+    return {
+      status: "failed",
+      message: callback.message ?? "Authentication callback failed."
+    };
+  }
+  let tokenResponse;
+  try {
+    tokenResponse = await authService.exchangeCodeForTokens({
+      tokenEndpoint: metadata.tokenEndpoint,
+      clientId: client.clientId,
+      clientSecret: client.clientSecret,
+      code: callback.code,
+      codeVerifier: verifier,
+      redirectUri
+    });
+  } catch (error2) {
+    try {
+      await authStorage.clearClient(mcpUrl);
+    } catch {}
+    const msg = error2 instanceof Error ? error2.message : String(error2);
+    return {
+      status: "failed",
+      message: `Failed to complete authentication: ${msg}`
+    };
+  }
+  const expiresAt = new Date(Date.now() + tokenResponse.expiresIn * 1000).toISOString();
+  await authStorage.saveAuthSession(mcpUrl, client, {
+    accessToken: tokenResponse.accessToken,
+    refreshToken: tokenResponse.refreshToken,
+    expiresAt,
+    createdAt: new Date().toISOString()
+  });
+  const hours = Math.round(tokenResponse.expiresIn / 3600);
+  return {
+    status: "success",
+    message: `Logged in successfully. Token expires in ${hours} hour${hours !== 1 ? "s" : ""}.`
+  };
+}
+async function loginAction(options, deps) {
+  const result = await loginFlow(options, deps, stdoutLoginOutput);
+  if (result.status === "already_authenticated") {
+    console.log(`Already logged in.
+`);
+    console.log(`  Environment: ${deps.mcpUrl}
+`);
+    console.log("To re-authenticate, use `githits login --force`.");
+    return;
+  }
+  if (result.status === "failed") {
+    console.error(`${result.message}
+`);
+    printLoginRecoveryHint(result.message);
+    process.exit(1);
+  }
+  console.log(`Logged in successfully.
+`);
+  console.log(`  Environment: ${deps.mcpUrl}`);
+  console.log(result.message.replace("Logged in successfully. ", "  "));
+  console.log(`
+You're ready to use githits with your AI assistant.`);
+}
+function printLoginRecoveryHint(message) {
+  console.log("Recovery steps:");
+  if (message.includes("Authentication timed out")) {
+    console.log("  Run the same command again to open a fresh sign-in link.");
+    console.log("  githits login --no-browser  # if the browser did not open or you are on SSH");
+    console.log("  githits logout && githits login  # if sign-in keeps failing after a retry");
+    return;
+  }
+  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.");
+  }
+}
+function printAutoLoginRecoveryHint(message) {
+  if (message.includes("Authentication timed out")) {
+    console.error("Run the same command again to open a fresh sign-in link.");
+    console.error("If the browser did not open, run `githits login --no-browser` and follow the printed link.");
+    console.error("If sign-in keeps failing after a retry, run `githits logout` and then run your command again.");
+    return;
+  }
+  console.error("Run the same command again to try signing in again.");
+  console.error("Run `githits auth status` to check whether you are signed in.");
+  if (message.includes("Cannot persist OAuth credentials")) {
+    console.error("If your system keychain is locked or unavailable, unlock it and try again.");
+    console.error("For CI/automation, set GITHITS_API_TOKEN.");
+  }
+}
+function ensureTerminalPeriod(message) {
+  return /[.!?]$/.test(message) ? message : `${message}.`;
+}
+var LOGIN_DESCRIPTION = `Authenticate with your GitHits account via browser.
+
+Opens your browser to complete authentication securely using OAuth.
+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 createAuthCommandDependencies();
+    await loginAction(options, deps);
+  });
+}
+
 // src/shared/auto-login.ts
 var AUTO_LOGIN_ELIGIBLE_COMMANDS = new Set([
-  "init",
   "example",
   "languages",
   "feedback",
@@ -4175,9 +4487,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;
   }
@@ -4229,16 +4538,15 @@ function createRootCliPreAction(deps) {
     if (authResult.status !== "failed") {
       return;
     }
-    console.error(`${authResult.message}
+    const failureMessage = authResult.message ?? "Authentication failed.";
+    console.error(`${failureMessage}
 `);
-    console.error("Run `githits login` to try again.");
+    printAutoLoginRecoveryHint(failureMessage);
     (deps.exit ?? process.exit)(1);
   };
 }
 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 +4621,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 +4679,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 +4693,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 +4717,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 +4754,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 +4772,7 @@ function buildUnifiedSearchStatusPayload(outcome) {
 }
 function buildUnifiedSearchStatusResultPayload(result) {
   const payload = {
+    query: buildStatusQueryEcho(result),
     hasMore: result.page.hasMore,
     results: result.results.map(buildHitPayload)
   };
@@ -4482,6 +4791,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 +4852,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 +4865,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 +4929,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 +5013,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 +5074,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 +5104,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 +5295,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 +5396,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 +5473,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 +6263,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-xzq0ecpa.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -6210,6 +6739,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 +6759,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 +6797,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-b6avnx6d.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-xzq0ecpa.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -7022,230 +7566,6 @@ async function scanAgents(definitions, fs, execService) {
 class ExitPromptError extends Error {
   name = "ExitPromptError";
 }
-// src/commands/login.ts
-var stdoutLoginOutput = {
-  write: (message) => {
-    console.log(message);
-  }
-};
-var stderrLoginOutput = {
-  write: (message) => {
-    console.error(message);
-  }
-};
-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.saveAuthSession(probeUrl, probeClient, probeTokens);
-    await authStorage.clearAuthSession(probeUrl);
-    return null;
-  } catch (error2) {
-    await authStorage.clearAuthSession(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, output = stdoutLoginOutput) {
-  const { authService, authStorage, browserService, mcpUrl } = deps;
-  if (options.port !== undefined && (Number.isNaN(options.port) || options.port < 1 || options.port > 65535)) {
-    return {
-      status: "failed",
-      message: "Invalid port number. Must be between 1 and 65535."
-    };
-  }
-  const existing = await authStorage.loadTokens(mcpUrl);
-  if (existing && !options.force) {
-    const isExpired = existing.expiresAt && new Date(existing.expiresAt) < new Date;
-    if (!isExpired) {
-      return { status: "already_authenticated", message: "Already logged in." };
-    }
-    output.write(`Token expired. Starting new login...
-`);
-  } else if (existing && options.force) {
-    output.write(`Re-authenticating (--force flag)...
-`);
-  }
-  if (!existing) {
-    await authStorage.clearClient(mcpUrl);
-  }
-  const persistenceError = await preflightAuthPersistence(authStorage, mcpUrl);
-  if (persistenceError)
-    return persistenceError;
-  output.write("Discovering OAuth endpoints...");
-  const metadata = await authService.discoverEndpoints(mcpUrl);
-  let client = await authStorage.loadClient(mcpUrl);
-  let port;
-  let redirectUri;
-  if (client) {
-    if (options.port) {
-      redirectUri = `http://127.0.0.1:${options.port}/callback`;
-      if (redirectUri !== client.redirectUri) {
-        output.write("Registering CLI client with new port...");
-        const registration = await authService.registerClient({
-          registrationEndpoint: metadata.registrationEndpoint,
-          redirectUri
-        });
-        client = {
-          clientId: registration.clientId,
-          clientSecret: registration.clientSecret,
-          redirectUri,
-          registeredAt: new Date().toISOString()
-        };
-      }
-      port = options.port;
-    } else {
-      redirectUri = client.redirectUri;
-      const storedUrl = new URL(redirectUri);
-      port = Number(storedUrl.port) || randomPort();
-    }
-  } else {
-    port = options.port ?? randomPort();
-    redirectUri = `http://127.0.0.1:${port}/callback`;
-    output.write("Registering CLI client...");
-    const registration = await authService.registerClient({
-      registrationEndpoint: metadata.registrationEndpoint,
-      redirectUri
-    });
-    client = {
-      clientId: registration.clientId,
-      clientSecret: registration.clientSecret,
-      redirectUri,
-      registeredAt: new Date().toISOString()
-    };
-  }
-  const { verifier, challenge, state } = authService.generatePkceParams();
-  const authUrl = authService.buildAuthUrl({
-    authorizationEndpoint: metadata.authorizationEndpoint,
-    clientId: client.clientId,
-    redirectUri,
-    state,
-    codeChallenge: challenge
-  });
-  const serverPromise = authService.startCallbackServer(port, state);
-  if (options.browser === false) {
-    output.write(`Open this URL in your browser:
-`);
-    output.write(`  ${authUrl}
-`);
-  } else {
-    output.write("Opening browser...");
-    await browserService.open(authUrl);
-  }
-  output.write(`Waiting for authentication...
-`);
-  let timeoutId;
-  const timeoutPromise = new Promise((_, reject) => {
-    timeoutId = setTimeout(() => reject(new Error("Authentication timed out")), TIMEOUT_MS);
-  });
-  let callback;
-  try {
-    callback = await Promise.race([serverPromise, timeoutPromise]);
-    if (timeoutId)
-      clearTimeout(timeoutId);
-  } catch (error2) {
-    if (timeoutId)
-      clearTimeout(timeoutId);
-    const msg = error2 instanceof Error ? error2.message : "Authentication failed";
-    return { status: "failed", message: `${msg}.` };
-  }
-  if (callback.type !== "success") {
-    await new Promise((r) => setTimeout(r, 2000));
-    return {
-      status: "failed",
-      message: callback.message ?? "Authentication callback failed."
-    };
-  }
-  let tokenResponse;
-  try {
-    tokenResponse = await authService.exchangeCodeForTokens({
-      tokenEndpoint: metadata.tokenEndpoint,
-      clientId: client.clientId,
-      clientSecret: client.clientSecret,
-      code: callback.code,
-      codeVerifier: verifier,
-      redirectUri
-    });
-  } catch (error2) {
-    try {
-      await authStorage.clearClient(mcpUrl);
-    } catch {}
-    const msg = error2 instanceof Error ? error2.message : String(error2);
-    return {
-      status: "failed",
-      message: `Failed to complete authentication: ${msg}`
-    };
-  }
-  const expiresAt = new Date(Date.now() + tokenResponse.expiresIn * 1000).toISOString();
-  await authStorage.saveAuthSession(mcpUrl, client, {
-    accessToken: tokenResponse.accessToken,
-    refreshToken: tokenResponse.refreshToken,
-    expiresAt,
-    createdAt: new Date().toISOString()
-  });
-  const hours = Math.round(tokenResponse.expiresIn / 3600);
-  return {
-    status: "success",
-    message: `Logged in successfully. Token expires in ${hours} hour${hours !== 1 ? "s" : ""}.`
-  };
-}
-async function loginAction(options, deps) {
-  const result = await loginFlow(options, deps, stdoutLoginOutput);
-  if (result.status === "already_authenticated") {
-    console.log(`Already logged in.
-`);
-    console.log(`  Environment: ${deps.mcpUrl}
-`);
-    console.log("To re-authenticate, use `githits login --force`.");
-    return;
-  }
-  if (result.status === "failed") {
-    console.error(`${result.message}
-`);
-    console.log("Run `githits login` to try again.");
-    process.exit(1);
-  }
-  console.log(`Logged in successfully.
-`);
-  console.log(`  Environment: ${deps.mcpUrl}`);
-  console.log(result.message.replace("Logged in successfully. ", "  "));
-  console.log(`
-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.
-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 createAuthCommandDependencies();
-    await loginAction(options, deps);
-  });
-}
-
 // src/commands/init/init.ts
 async function verifyAgentConfigured(agent, fileSystemService, execService) {
   const postCheck = await scanAgents([agent], fileSystemService, execService);
@@ -7266,6 +7586,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 +7610,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 +7628,7 @@ async function initAction(options, deps) {
           throw err;
         }
       }
+      continuedWithoutAuth = true;
       console.log(`    Continuing without authentication...
 `);
     }
@@ -7329,6 +7652,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 +7729,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 +7748,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 +7987,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 +8019,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 +8975,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 +9044,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 +9085,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 +9891,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-xzq0ecpa.js");
   return createContainer2();
 }
 function parseTargetSpecs(specs) {
@@ -9585,8 +9970,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 +10011,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 +10078,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 +10094,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 +10209,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 +10323,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