refactor(log): use server-side sorting instead of client-side reversal

Move sort direction to the API layer (LogSortDirection in api/logs.ts)
and pass it through to both listLogs() and listTraceLogs() endpoints
instead of reversing arrays client-side. Rename parseSort to
parseLogSort to avoid collision with per-command parseSort functions
in trace/span/issue list commands.

Author: BYK

src/commands/log/list.ts

@@ -9,12 +9,12 @@
 // biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
 import * as Sentry from "@sentry/node-core/light";
 import type { SentryContext } from "../../context.js";
-import { listLogs, listTraceLogs } from "../../lib/api-client.js";
 import {
-  parseSort,
-  type SortDirection,
-  validateLimit,
-} from "../../lib/arg-parsing.js";
+  type LogSortDirection,
+  listLogs,
+  listTraceLogs,
+} from "../../lib/api-client.js";
+import { parseLogSort, validateLimit } from "../../lib/arg-parsing.js";
 import { AuthError, stringifyUnknown } from "../../lib/errors.js";
 import {
   buildLogRowCells,
@@ -50,7 +50,7 @@ type ListFlags = {
   readonly query?: string;
   readonly follow?: number;
   readonly period?: string;
-  readonly sort: SortDirection;
+  readonly sort: LogSortDirection;
   readonly json: boolean;
   readonly fresh: boolean;
   readonly fields?: string[];
@@ -180,21 +180,19 @@ async function executeSingleFetch(
     query: flags.query,
     limit: flags.limit,
     statsPeriod: period,
+    sort: flags.sort,
   });
 
   if (logs.length === 0) {
     return { result: { logs: [], hasMore: false }, hint: "No logs found." };
   }
 
-  // API returns newest first. Reverse only when user wants oldest-first.
-  const ordered = flags.sort === "oldest" ? [...logs].reverse() : logs;
-
   const hasMore = logs.length >= flags.limit;
   const countText = `Showing ${logs.length} log${logs.length === 1 ? "" : "s"}.`;
   const tip = hasMore ? " Use --limit to show more, or -f to follow." : "";
 
   return {
-    result: { logs: ordered, hasMore },
+    result: { logs, hasMore },
     hint: `${countText}${tip}`,
   };
 }
@@ -440,6 +438,7 @@ async function executeTraceSingleFetch(
     query: flags.query,
     limit: flags.limit,
     statsPeriod: period,
+    sort: flags.sort,
   });
 
   if (logs.length === 0) {
@@ -451,14 +450,12 @@ async function executeTraceSingleFetch(
     };
   }
 
-  const ordered = flags.sort === "oldest" ? [...logs].reverse() : logs;
-
   const hasMore = logs.length >= flags.limit;
   const countText = `Showing ${logs.length} log${logs.length === 1 ? "" : "s"} for trace ${traceId}.`;
   const tip = hasMore ? " Use --limit to show more." : "";
 
   return {
-    result: { logs: ordered, traceId, hasMore },
+    result: { logs, traceId, hasMore },
     hint: `${countText}${tip}`,
   };
 }
@@ -645,7 +642,7 @@ export const listCommand = buildListCommand(
         },
         sort: {
           kind: "parsed",
-          parse: parseSort,
+          parse: parseLogSort,
           brief: 'Sort order: "newest" (default) or "oldest"',
           default: "newest",
         },

src/commands/trace/logs.ts

@@ -5,12 +5,8 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { listTraceLogs } from "../../lib/api-client.js";
-import {
-  parseSort,
-  type SortDirection,
-  validateLimit,
-} from "../../lib/arg-parsing.js";
+import { type LogSortDirection, listTraceLogs } from "../../lib/api-client.js";
+import { parseLogSort, validateLimit } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { filterFields } from "../../lib/formatters/json.js";
@@ -35,7 +31,7 @@ type LogsFlags = {
   readonly period: string;
   readonly limit: number;
   readonly query?: string;
-  readonly sort: SortDirection;
+  readonly sort: LogSortDirection;
   readonly fresh: boolean;
   readonly fields?: string[];
 };
@@ -154,7 +150,7 @@ export const logsCommand = buildCommand({
       },
       sort: {
         kind: "parsed",
-        parse: parseSort,
+        parse: parseLogSort,
         brief: 'Sort order: "newest" (default) or "oldest"',
         default: "newest",
       },
@@ -192,19 +188,18 @@ export const logsCommand = buildCommand({
           statsPeriod: flags.period,
           limit: flags.limit,
           query: flags.query,
+          sort: flags.sort,
         })
     );
 
-    // API returns newest-first. Reverse only when user wants oldest-first.
-    const ordered = flags.sort === "oldest" ? [...logs].reverse() : logs;
-    const hasMore = ordered.length >= flags.limit;
+    const hasMore = logs.length >= flags.limit;
 
     const emptyMessage =
       `No logs found for trace ${traceId} in the last ${flags.period}.\n\n` +
       `Try a longer period: sentry trace logs --period 30d ${traceId}`;
 
     return yield new CommandOutput({
-      logs: ordered,
+      logs,
       traceId,
       hasMore,
       emptyMessage,

src/lib/api-client.ts

@@ -60,6 +60,7 @@ export {
 } from "./api/issues.js";
 export {
   getLogs,
+  type LogSortDirection,
   listLogs,
   listTraceLogs,
 } from "./api/logs.js";

src/lib/api/logs.ts

@@ -26,6 +26,14 @@ import {
   unwrapResult,
 } from "./infrastructure.js";
 
+/** Sort direction for log queries: newest-first or oldest-first. */
+export type LogSortDirection = "newest" | "oldest";
+
+/** Map CLI sort direction to Sentry API sort parameter. */
+function toApiSort(sort: LogSortDirection | undefined): string {
+  return sort === "oldest" ? "timestamp" : "-timestamp";
+}
+
 /** Fields to request from the logs API */
 const LOG_FIELDS = [
   "sentry.item_id",
@@ -43,6 +51,8 @@ type ListLogsOptions = {
   limit?: number;
   /** Time period for logs (e.g., "90d", "10m") */
   statsPeriod?: string;
+  /** Sort direction: "newest" (default) or "oldest" */
+  sort?: LogSortDirection;
   /** Only return logs after this timestamp_precise value (for streaming) */
   afterTimestamp?: number;
 };
@@ -84,7 +94,7 @@ export async function listLogs(
       query: fullQuery || undefined,
       per_page: options.limit || API_MAX_PER_PAGE,
       statsPeriod: options.statsPeriod ?? "14d",
-      sort: "-timestamp",
+      sort: toApiSort(options.sort),
     },
   });
 
@@ -193,6 +203,8 @@ type ListTraceLogsOptions = {
    * logs exist for the trace. Defaults to "14d".
    */
   statsPeriod?: string;
+  /** Sort direction: "newest" (default) or "oldest" */
+  sort?: LogSortDirection;
 };
 
 /**
@@ -208,8 +220,8 @@ type ListTraceLogsOptions = {
  *
  * @param orgSlug - Organization slug
  * @param traceId - The 32-character hex trace ID
- * @param options - Optional query/limit/statsPeriod overrides
- * @returns Array of trace log entries, ordered newest-first
+ * @param options - Optional query/limit/statsPeriod/sort overrides
+ * @returns Array of trace log entries
  */
 export async function listTraceLogs(
   orgSlug: string,
@@ -227,7 +239,7 @@ export async function listTraceLogs(
         statsPeriod: options.statsPeriod ?? "14d",
         per_page: options.limit ?? API_MAX_PER_PAGE,
         query: options.query,
-        sort: "-timestamp",
+        sort: toApiSort(options.sort),
       },
       schema: TraceLogsResponseSchema,
     }

src/lib/arg-parsing.ts

@@ -6,6 +6,7 @@
  * project list) and single-item commands (issue view, explain, plan).
  */
 
+import type { LogSortDirection } from "./api/logs.js";
 import { ContextError, ValidationError } from "./errors.js";
 import { validateResourceId } from "./input-validation.js";
 import { logger } from "./logger.js";
@@ -262,23 +263,25 @@ export function validateLimit(value: string, min = 1, max = 1000): number {
 }
 
 // ---------------------------------------------------------------------------
-// Sort direction parsing (shared by log list, trace logs)
+// Log sort direction parsing (shared by log list, trace logs)
 // ---------------------------------------------------------------------------
 
-/** Sort direction for log output */
-export type SortDirection = "newest" | "oldest";
-
-const VALID_SORT_DIRECTIONS: readonly SortDirection[] = ["newest", "oldest"];
+const VALID_LOG_SORT_DIRECTIONS: readonly LogSortDirection[] = [
+  "newest",
+  "oldest",
+];
 
 /**
- * Parse --sort flag value.
+ * Parse --sort flag value for log commands.
  * @throws Error if value is not "newest" or "oldest"
  */
-export function parseSort(value: string): SortDirection {
-  if (!VALID_SORT_DIRECTIONS.includes(value as SortDirection)) {
-    throw new Error(`--sort must be "newest" or "oldest", got "${value}"`);
+export function parseLogSort(value: string): LogSortDirection {
+  if (!VALID_LOG_SORT_DIRECTIONS.includes(value as LogSortDirection)) {
+    throw new Error(
+      `Invalid sort value. Must be one of: ${VALID_LOG_SORT_DIRECTIONS.join(", ")}`
+    );
   }
-  return value as SortDirection;
+  return value as LogSortDirection;
 }
 
 /** Default span depth when no value is provided */

test/commands/log/list.test.ts

@@ -289,24 +289,24 @@ describe("listCommand.func — standard mode", () => {
     expect(parsed.data[2]["sentry.item_id"]).toBe("item001");
   });
 
-  test("outputs JSON in oldest-first order with sort=oldest", async () => {
-    const newestFirst = [...sampleLogs].reverse();
-    listLogsSpy.mockResolvedValue(newestFirst);
+  test("passes sort=oldest to API when requested", async () => {
+    listLogsSpy.mockResolvedValue(sampleLogs);
     resolveOrgProjectSpy.mockResolvedValue({ org: ORG, project: PROJECT });
 
-    const { context, stdoutWrite } = createMockContext();
+    const { context } = createMockContext();
     const func = await listCommand.loader();
     await func.call(
       context,
       { ...BATCH_FLAGS, sort: "oldest" },
       `${ORG}/${PROJECT}`
     );
 
-    const output = stdoutWrite.mock.calls.map((c) => c[0]).join("");
-    const parsed = JSON.parse(output);
-    // sort=oldest reverses to chronological order
-    expect(parsed.data[0]["sentry.item_id"]).toBe("item001");
-    expect(parsed.data[2]["sentry.item_id"]).toBe("item003");
+    // sort=oldest is passed to API for server-side sorting
+    expect(listLogsSpy).toHaveBeenCalledWith(
+      ORG,
+      PROJECT,
+      expect.objectContaining({ sort: "oldest" })
+    );
   });
 
   test("shows 'No logs found' for empty result (human mode)", async () => {
@@ -388,6 +388,7 @@ describe("listCommand.func — standard mode", () => {
       query: "level:error",
       limit: 50,
       statsPeriod: "30d",
+      sort: "newest",
     });
   });
 
@@ -539,14 +540,15 @@ describe("listCommand.func — trace mode", () => {
     const func = await listCommand.loader();
     await func.call(
       context,
-      { json: false, limit: 50, query: "level:error" },
+      { json: false, limit: 50, query: "level:error", sort: "newest" },
       TRACE_ID
     );
 
     expect(listTraceLogsSpy).toHaveBeenCalledWith(ORG, TRACE_ID, {
       query: "level:error",
       limit: 50,
       statsPeriod: "14d",
+      sort: "newest",
     });
   });
 
@@ -700,6 +702,7 @@ describe("listCommand.func — period flag", () => {
       query: undefined,
       limit: 100,
       statsPeriod: "14d",
+      sort: "newest",
     });
   });
 
@@ -716,6 +719,7 @@ describe("listCommand.func — period flag", () => {
       query: undefined,
       limit: 100,
       statsPeriod: "30d",
+      sort: "newest",
     });
   });
 });