fix: show nav hints on empty pages, extract hint builders to reduce complexity

- Dashboard: buildHint now shows -c prev/-c next even when results are empty
- Trace/span: empty-page branches now show -c prev when hasPrev is true
- Extract buildNavHint helper in trace/list.ts to stay under complexity limit

Author: BYK

src/commands/dashboard/list.ts

@@ -337,23 +337,26 @@ function buildHint(
   result: DashboardListResult,
   orgSlug: string
 ): string | undefined {
-  if (result.dashboards.length === 0) {
-    return;
-  }
   const filterArg = result.titleFilter ? ` '${result.titleFilter}'` : "";
   const navParts: string[] = [];
   if (result.hasMore) {
     navParts.push(
-      `Next page: sentry dashboard list ${orgSlug}/${filterArg} -c next`
+      `Next: sentry dashboard list ${orgSlug}/${filterArg} -c next`
     );
   }
   if (result.hasPrev) {
     navParts.push(
-      `Prev page: sentry dashboard list ${orgSlug}/${filterArg} -c prev`
+      `Prev: sentry dashboard list ${orgSlug}/${filterArg} -c prev`
     );
   }
   const nav = navParts.length > 0 ? ` ${navParts.join(" | ")}` : "";
   const url = buildDashboardsListUrl(orgSlug);
+
+  if (result.dashboards.length === 0) {
+    // Empty results — show nav hint if prev/next exist, otherwise nothing
+    return nav ? `No dashboards found.${nav}` : undefined;
+  }
+
   return `Showing ${result.dashboards.length} dashboard(s).${nav}\nDashboards: ${url}`;
 }
 

src/commands/span/list.ts

@@ -319,20 +319,23 @@ async function handleTraceMode(
   const flatSpans = spanItems.map(spanListItemToFlatSpan);
   const hasMore = !!nextCursor;
 
+  const navParts: string[] = [];
+  if (hasPrev) {
+    navParts.push(`Prev: ${tracePrevPageHint(org, project, traceId, flags)}`);
+  }
+  if (hasMore) {
+    navParts.push(`Next: ${traceNextPageHint(org, project, traceId, flags)}`);
+  }
+  const nav = navParts.join(" | ");
+
   let hint: string | undefined;
-  if (flatSpans.length === 0 && hasMore) {
-    hint = `Try the next page: ${traceNextPageHint(org, project, traceId, flags)}`;
+  if (flatSpans.length === 0 && nav) {
+    hint = `No spans on this page. ${nav}`;
   } else if (flatSpans.length > 0) {
     const countText = `Showing ${flatSpans.length} span${flatSpans.length === 1 ? "" : "s"}.`;
-    if (hasMore && hasPrev) {
-      hint = `${countText} Prev: ${tracePrevPageHint(org, project, traceId, flags)} | Next: ${traceNextPageHint(org, project, traceId, flags)}`;
-    } else if (hasMore) {
-      hint = `${countText} Next page: ${traceNextPageHint(org, project, traceId, flags)}`;
-    } else if (hasPrev) {
-      hint = `${countText} Prev: ${tracePrevPageHint(org, project, traceId, flags)}`;
-    } else {
-      hint = `${countText} Use 'sentry span view ${traceId} <span-id>' to view span details.`;
-    }
+    hint = nav
+      ? `${countText} ${nav}`
+      : `${countText} Use 'sentry span view ${traceId} <span-id>' to view span details.`;
   }
 
   return {
@@ -394,20 +397,23 @@ async function handleProjectMode(
   const flatSpans = spanItems.map(spanListItemToFlatSpan);
   const hasMore = !!nextCursor;
 
+  const navParts2: string[] = [];
+  if (hasPrev) {
+    navParts2.push(`Prev: ${projectPrevPageHint(org, project, flags)}`);
+  }
+  if (hasMore) {
+    navParts2.push(`Next: ${projectNextPageHint(org, project, flags)}`);
+  }
+  const nav2 = navParts2.join(" | ");
+
   let hint: string | undefined;
-  if (flatSpans.length === 0 && hasMore) {
-    hint = `Try the next page: ${projectNextPageHint(org, project, flags)}`;
+  if (flatSpans.length === 0 && nav2) {
+    hint = `No spans on this page. ${nav2}`;
   } else if (flatSpans.length > 0) {
     const countText = `Showing ${flatSpans.length} span${flatSpans.length === 1 ? "" : "s"}.`;
-    if (hasMore && hasPrev) {
-      hint = `${countText} Prev: ${projectPrevPageHint(org, project, flags)} | Next: ${projectNextPageHint(org, project, flags)}`;
-    } else if (hasMore) {
-      hint = `${countText} Next page: ${projectNextPageHint(org, project, flags)}`;
-    } else if (hasPrev) {
-      hint = `${countText} Prev: ${projectPrevPageHint(org, project, flags)}`;
-    } else {
-      hint = `${countText} Use 'sentry span view <trace-id> <span-id>' to view span details.`;
-    }
+    hint = nav2
+      ? `${countText} ${nav2}`
+      : `${countText} Use 'sentry span view <trace-id> <span-id>' to view span details.`;
   }
 
   return {

src/commands/trace/list.ts

@@ -117,6 +117,24 @@ function prevPageHint(
   return appendTraceFlags(`sentry trace list ${org}/${project} -c prev`, flags);
 }
 
+/** Build a combined nav hint string from prev/next hints. */
+function buildNavHint(opts: {
+  hasMore: boolean;
+  hasPrev: boolean;
+  org: string;
+  project: string;
+  flags: Pick<ListFlags, "sort" | "query" | "period">;
+}): string {
+  const parts: string[] = [];
+  if (opts.hasPrev) {
+    parts.push(`Prev: ${prevPageHint(opts.org, opts.project, opts.flags)}`);
+  }
+  if (opts.hasMore) {
+    parts.push(`Next: ${nextPageHint(opts.org, opts.project, opts.flags)}`);
+  }
+  return parts.join(" | ");
+}
+
 /**
  * Parse --limit flag, delegating range validation to shared utility.
  */
@@ -293,20 +311,15 @@ export const listCommand = buildListCommand("trace", {
     const hasMore = !!nextCursor;
 
     // Build footer hint based on result state
+    const nav = buildNavHint({ hasMore, hasPrev, org, project, flags });
     let hint: string | undefined;
-    if (traces.length === 0 && hasMore) {
-      hint = `Try the next page: ${nextPageHint(org, project, flags)}`;
+    if (traces.length === 0 && nav) {
+      hint = `No traces on this page. ${nav}`;
     } else if (traces.length > 0) {
       const countText = `Showing ${traces.length} trace${traces.length === 1 ? "" : "s"}.`;
-      if (hasMore && hasPrev) {
-        hint = `${countText} Prev: ${prevPageHint(org, project, flags)} | Next: ${nextPageHint(org, project, flags)}`;
-      } else if (hasMore) {
-        hint = `${countText} Next page: ${nextPageHint(org, project, flags)}`;
-      } else if (hasPrev) {
-        hint = `${countText} Prev: ${prevPageHint(org, project, flags)}`;
-      } else {
-        hint = `${countText} Use 'sentry trace view <TRACE_ID>' to view the full span tree.`;
-      }
+      hint = nav
+        ? `${countText} ${nav}`
+        : `${countText} Use 'sentry trace view <TRACE_ID>' to view the full span tree.`;
     }
 
     yield new CommandOutput({

test/commands/trace/list.test.ts

@@ -378,7 +378,7 @@ describe("listCommand.func", () => {
     );
 
     const output = stdoutWrite.mock.calls.map((c) => c[0]).join("");
-    expect(output).toContain("Next page:");
+    expect(output).toContain("Next:");
     expect(output).toContain("-c next");
   });
 
@@ -394,7 +394,7 @@ describe("listCommand.func", () => {
     );
 
     const output = stdoutWrite.mock.calls.map((c) => c[0]).join("");
-    expect(output).not.toContain("Next page:");
+    expect(output).not.toContain("Next:");
     expect(output).toContain("sentry trace view");
   });
 
@@ -482,7 +482,7 @@ describe("listCommand.func", () => {
     );
 
     const output = stdoutWrite.mock.calls.map((c) => c[0]).join("");
-    expect(output).toContain("Next page:");
+    expect(output).toContain("Next:");
     expect(output).toContain("-c next");
     expect(output).toContain("--sort duration");
   });