feat: improve search freshness follow-ups

src/commands/search.test.ts

@@ -54,7 +54,9 @@ describe("searchAction", () => {
   }
 
   it("calls unified search service with parsed targets and filters", async () => {
-    const search = mock(() => Promise.resolve(defaultUnifiedSearchOutcome));
+    const search = mock((_: UnifiedSearchParams) =>
+      Promise.resolve(defaultUnifiedSearchOutcome),
+    );
     const deps = createDeps({
       codeNavigationService: createMockCodeNavigationService({ search }),
     });
@@ -86,7 +88,9 @@ describe("searchAction", () => {
   });
 
   it("passes repeatable --source values through as source filters", async () => {
-    const search = mock(() => Promise.resolve(defaultUnifiedSearchOutcome));
+    const search = mock((_: UnifiedSearchParams) =>
+      Promise.resolve(defaultUnifiedSearchOutcome),
+    );
     const deps = createDeps({
       codeNavigationService: createMockCodeNavigationService({ search }),
     });
@@ -109,6 +113,28 @@ describe("searchAction", () => {
     consoleSpy.mockRestore();
   });
 
+  it("preserves omitted repo refs for CLI discovery search targets", async () => {
+    const search = mock((_: UnifiedSearchParams) =>
+      Promise.resolve(defaultUnifiedSearchOutcome),
+    );
+    const deps = createDeps({
+      codeNavigationService: createMockCodeNavigationService({ search }),
+    });
+    const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+
+    await searchAction(
+      "router middleware",
+      { in: ["https://github.com/expressjs/express"] },
+      deps,
+    );
+
+    const call = search.mock.calls[0]?.[0];
+    expect(call?.targets[0]).toEqual({
+      repoUrl: "https://github.com/expressjs/express",
+    });
+    consoleSpy.mockRestore();
+  });
+
   it("uses the shared search default limit and preserves explicit limits", async () => {
     const search = mock((_: UnifiedSearchParams) =>
       Promise.resolve(defaultUnifiedSearchOutcome),

src/commands/search.ts

@@ -813,7 +813,9 @@ function formatUnifiedSearchMetadata(
 
   const lines: string[] = [];
   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 =
@@ -822,18 +824,11 @@ function formatUnifiedSearchMetadata(
       : 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/services/client-update-required-error.ts

@@ -14,18 +14,17 @@ export class ClientUpdateRequiredError extends Error {
 }
 
 export function isClientUpdateRequiredGraphQLError(input: {
-  message: string;
+  message?: string;
   code?: string;
 }): boolean {
-  if (input.code === "CLIENT_UPDATE_REQUIRED") {
-    return true;
-  }
-
-  const message = input.message;
-  if (!isGraphQLSchemaMismatchMessage(message)) {
-    return false;
-  }
+  return input.code === "CLIENT_UPDATE_REQUIRED";
+}
 
+export function isGraphQLSchemaMismatchError(input: {
+  message: string;
+  code?: string;
+}): boolean {
+  if (!isGraphQLSchemaMismatchMessage(input.message)) return false;
   return (
     !input.code ||
     input.code === "GRAPHQL_VALIDATION_FAILED" ||

src/services/code-navigation-service.test.ts

@@ -7,7 +7,6 @@ import {
   mock,
   spyOn,
 } from "bun:test";
-import { ClientUpdateRequiredError } from "./client-update-required-error.js";
 import {
   CodeNavigationBackendError,
   CodeNavigationFileNotFoundError,
@@ -668,6 +667,15 @@ describe("CodeNavigationServiceImpl", () => {
     expect(parsed.operation).toBe("search");
     expect(parsed.graphqlQuery).toContain("query UnifiedSearch(");
     expect(parsed.graphqlQuery).toContain("filters: $filters");
+    expect(parsed.graphqlQuery).toContain("requestedTargetLabel");
+    expect(parsed.graphqlQuery).toContain("freshTargetLabel");
+    expect(parsed.graphqlQuery).toContain("servedTargetLabel");
+    expect(parsed.graphqlQuery).toContain("freshness");
+    expect(parsed.graphqlQuery).toContain("requestedSources");
+    expect(parsed.graphqlQuery).toContain("targetMode");
+    expect(parsed.graphqlQuery).toContain("requestedTargets");
+    expect(parsed.graphqlQuery).toContain("resolvedRequested");
+    expect(parsed.graphqlQuery).toContain("requestedRefKind");
     expect(parsed.variables).toEqual({
       targets: [{ registry: "NPM", name: "express" }],
       query: "router middleware secret text",
@@ -761,7 +769,7 @@ describe("CodeNavigationServiceImpl", () => {
     }
   });
 
-  it("classifies GraphQL schema mismatch as ClientUpdateRequiredError", async () => {
+  it("classifies GraphQL schema mismatch as backend protocol error", async () => {
     mockFetch(() =>
       Promise.resolve(
         new Response(
@@ -787,7 +795,76 @@ describe("CodeNavigationServiceImpl", () => {
         targets: [{ registry: "NPM", packageName: "express" }],
         query: "middleware",
       }),
-    ).rejects.toBeInstanceOf(ClientUpdateRequiredError);
+    ).rejects.toMatchObject({
+      name: "CodeNavigationBackendError",
+      message: expect.stringContaining("Backend protocol mismatch"),
+    });
+  });
+
+  it("exposes GraphQL schema mismatch details when code-nav-wire debug is enabled", async () => {
+    process.env.GITHITS_DEBUG = "code-nav-wire";
+    const stderrSpy = spyOn(process.stderr, "write").mockImplementation(
+      () => true as never,
+    );
+    mockFetch(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            errors: [
+              {
+                message: 'Cannot query field "search" on type "Query".',
+                extensions: { code: "GRAPHQL_VALIDATION_FAILED" },
+              },
+            ],
+          }),
+          { status: 200 },
+        ),
+      ),
+    );
+    const service = new CodeNavigationServiceImpl(
+      BASE_URL,
+      createMockTokenProvider(),
+    );
+
+    await expect(
+      service.search({
+        targets: [{ registry: "NPM", packageName: "express" }],
+        query: "middleware",
+      }),
+    ).rejects.toMatchObject({
+      name: "CodeNavigationBackendError",
+      message: 'Cannot query field "search" on type "Query".',
+    });
+    stderrSpy.mockRestore();
+  });
+
+  it("honors explicit backend CLIENT_UPDATE_REQUIRED errors", async () => {
+    mockFetch(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            errors: [
+              {
+                message: "Client version is no longer supported.",
+                extensions: { code: "CLIENT_UPDATE_REQUIRED" },
+              },
+            ],
+          }),
+          { status: 200 },
+        ),
+      ),
+    );
+    const service = new CodeNavigationServiceImpl(
+      BASE_URL,
+      createMockTokenProvider(),
+    );
+
+    await expect(
+      service.search({
+        targets: [{ registry: "NPM", packageName: "express" }],
+        query: "middleware",
+      }),
+    ).rejects.toMatchObject({ name: "ClientUpdateRequiredError" });
   });
 
   it("sends grepRepo variables with the correct shape", async () => {