refactor: extract shared pagination infrastructure from duplicated code

Extract two pieces of duplicated pagination logic into shared infrastructure:

1. Add buildPaginationContextKey() to src/lib/db/pagination.ts - a generalized
   context key builder that encodes host, type, scope, and optional key-value
   params. Rewrite buildOrgContextKey() to delegate to it.

2. Add parseCursorFlag() to src/lib/list-command.ts - extracts the cursor flag
   validation logic (reject bare integers, accept 'last' keyword and opaque
   cursor strings). Update LIST_CURSOR_FLAG to use it.

Simplify trace/list.ts:
- Remove local ALL_DIGITS_RE, buildContextKey(), and inline cursor parse fn
- Use buildPaginationContextKey() and LIST_CURSOR_FLAG instead
- Remove unused escapeContextKeyValue and getApiBaseUrl imports

Simplify issue/list.ts:
- Remove local ALL_DIGITS_RE constant
- Replace inline cursor parse function with parseCursorFlag
- Replace manual context key construction in handleOrgAllIssues with
  buildPaginationContextKey()
- Keep escapeContextKeyValue and getApiBaseUrl imports (still used by
  buildMultiTargetContextKey)

Add tests for both new functions.

Author: BYK

AGENTS.md

@@ -632,7 +632,7 @@ mock.module("./some-module", () => ({
 * **cli.sentry.dev is served from gh-pages branch via GitHub Pages**: \`cli.sentry.dev\` is served from gh-pages branch via GitHub Pages. Craft's gh-pages target runs \`git rm -r -f .\` before extracting docs — persist extra files via \`postReleaseCommand\` in \`.craft.yml\`. Install script supports \`--channel nightly\`, downloading from the \`nightly\` release tag directly. version.json is only used by upgrade/version-check flow.
 
 <!-- lore:2c3eb7ab-1341-4392-89fd-d81095cfe9c4 -->
-* **npm bundle requires Node.js >= 22 due to node:sqlite polyfill**: The Sentry CLI npm package (dist/bin.cjs) requires Node.js >= 22 because the bun:sqlite polyfill uses Node.js 22's built-in \`node:sqlite\` module. The \`require('node:sqlite')\` happens during module loading (via esbuild's inject option) — before any user code runs. package.json declares \`engines: { node: '>=22' }\` but pnpm/npm don't enforce this by default. A runtime version guard in the esbuild banner catches this early with a clear error message pointing users to either upgrade Node.js or use the standalone binary (\`curl -fsSL https://cli.sentry.dev/install | bash\`).
+* **npm bundle requires Node.js >= 22 due to node:sqlite polyfill**: The npm package (dist/bin.cjs) requires Node.js >= 22 because the bun:sqlite polyfill uses \`node:sqlite\`. A runtime version guard in the esbuild banner catches this early. When writing esbuild banner strings in TS template literals, double-escape: \`\\\\\\\n\` in TS → \`\\\n\` in output → newline at runtime. Single \`\\\n\` produces a literal newline inside a JS string, causing SyntaxError.
 
 <!-- lore:019c972c-9f0f-75cd-9e24-9bdbb1ac03d6 -->
 * **Numeric issue ID resolution returns org:undefined despite API success**: Numeric issue ID resolution in \`resolveNumericIssue()\`: (1) try DSN/env/config for org, (2) if found use \`getIssueInOrg(org, id)\` with region routing, (3) else fall back to unscoped \`getIssue(id)\`, (4) extract org from \`issue.permalink\` via \`parseSentryUrl\` as final fallback. The \`explicit-org-numeric\` case uses \`getIssueInOrg\`. \`resolveOrgAndIssueId\` no longer throws for bare numeric IDs when permalink contains the org slug.
@@ -653,9 +653,6 @@ mock.module("./some-module", () => ({
 <!-- lore:019c9e98-7af4-7e25-95f4-fc06f7abf564 -->
 * **Bun binary build requires SENTRY\_CLIENT\_ID env var**: The build script (\`script/bundle.ts\`) requires \`SENTRY\_CLIENT\_ID\` environment variable and exits with code 1 if missing. When building locally, use \`bun run --env-file=.env.local build\` or set the env var explicitly. The binary build (\`bun run build\`) also needs it. Without it you get: \`Error: SENTRY\_CLIENT\_ID environment variable is required.\`
 
-<!-- lore:4729229d-36b9-4118-b90b-ea8151e6928f -->
-* **Esbuild banner template literal double-escape for newlines**: When using esbuild's \`banner\` option with a TypeScript template literal containing string literals that need \`\n\` escape sequences: use \`\\\\\\\n\` in the TS source. The chain is: TS template literal \`\\\\\\\n\` → esbuild banner output \`\\\n\` → JS runtime interprets as newline. Using only \`\\\n\` in the TS source produces a literal newline character inside a JS double-quoted string, which is a SyntaxError. This applies to any esbuild banner/footer that injects JS strings containing escape sequences. Discovered in script/bundle.ts for the Node.js version guard error message.
-
 <!-- lore:019c992d-8e38-7148-91db-baa5029eb2c3 -->
 * **ghcr.io blob download: curl -L breaks because auth header leaks to Azure redirect**: ghcr.io gotchas: (1) \`curl -L\` with Authorization header fails on blob downloads because curl forwards the auth header to the Azure redirect target (404). Fix: two-step curl — extract redirect URL without following, then fetch without auth. (2) New GHCR packages default to private. Anonymous pulls fail until manually made public via GitHub UI package settings. This is a one-time step per package.
 

src/commands/issue/list.ts

@@ -18,6 +18,7 @@ import {
 } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
 import {
+  buildPaginationContextKey,
   clearPaginationCursor,
   escapeContextKeyValue,
   resolveOrgCursor,
@@ -47,6 +48,7 @@ import {
   LIST_BASE_ALIASES,
   LIST_JSON_FLAG,
   LIST_TARGET_POSITIONAL,
+  parseCursorFlag,
   targetPatternExplanation,
 } from "../../lib/list-command.js";
 import {
@@ -87,9 +89,6 @@ const VALID_SORT_VALUES: SortValue[] = ["date", "new", "freq", "user"];
 /** Usage hint for ContextError messages */
 const USAGE_HINT = "sentry issue list <org>/<project>";
 
-/** Matches strings that are all digits — used to detect invalid cursor values */
-const ALL_DIGITS_RE = /^\d+$/;
-
 /**
  * Maximum --limit value (user-facing ceiling for practical CLI response times).
  * Auto-pagination can theoretically fetch more, but 1000 keeps responses reasonable.
@@ -748,11 +747,11 @@ type OrgAllIssuesOptions = {
 async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
   const { stdout, stderr, org, flags, setContext } = options;
   // Encode sort + query in context key so cursors from different searches don't collide.
-  const escapedQuery = flags.query
-    ? escapeContextKeyValue(flags.query)
-    : undefined;
-  const escapedPeriod = escapeContextKeyValue(flags.period ?? "90d");
-  const contextKey = `host:${getApiBaseUrl()}|type:org:${org}|sort:${flags.sort}|period:${escapedPeriod}${escapedQuery ? `|q:${escapedQuery}` : ""}`;
+  const contextKey = buildPaginationContextKey("org", org, {
+    sort: flags.sort,
+    period: flags.period ?? "90d",
+    q: flags.query,
+  });
   const cursor = resolveOrgCursor(flags.cursor, PAGINATION_KEY, contextKey);
 
   setContext([org], []);
@@ -1172,21 +1171,7 @@ export const listCommand = buildListCommand("issue", {
       json: LIST_JSON_FLAG,
       cursor: {
         kind: "parsed",
-        parse: (value: string) => {
-          // "last" is the magic keyword to resume from the saved cursor
-          if (value === "last") {
-            return value;
-          }
-          // Sentry pagination cursors are opaque strings like "1735689600:0:0".
-          // Plain integers are not valid cursors — catch this early so the user
-          // gets a clear error rather than a cryptic 400 from the API.
-          if (ALL_DIGITS_RE.test(value)) {
-            throw new Error(
-              `'${value}' is not a valid cursor. Cursors look like "1735689600:0:0". Use "last" to continue from the previous page.`
-            );
-          }
-          return value;
-        },
+        parse: parseCursorFlag,
         brief:
           'Pagination cursor for <org>/ or multi-target modes (use "last" to continue)',
         optional: true,

src/commands/trace/list.ts

@@ -8,8 +8,8 @@ import type { SentryContext } from "../../context.js";
 import { listTransactions } from "../../lib/api-client.js";
 import { validateLimit } from "../../lib/arg-parsing.js";
 import {
+  buildPaginationContextKey,
   clearPaginationCursor,
-  escapeContextKeyValue,
   resolveOrgCursor,
   setPaginationCursor,
 } from "../../lib/db/pagination.js";
@@ -20,10 +20,10 @@ import {
 } from "../../lib/formatters/index.js";
 import {
   buildListCommand,
+  LIST_CURSOR_FLAG,
   TARGET_PATTERN_NOTE,
 } from "../../lib/list-command.js";
 import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
-import { getApiBaseUrl } from "../../lib/sentry-client.js";
 
 type ListFlags = {
   readonly limit: number;
@@ -53,31 +53,6 @@ const COMMAND_NAME = "trace list";
 /** Command key for pagination cursor storage */
 export const PAGINATION_KEY = "trace-list";
 
-/** Matches strings that are all digits — used to detect invalid cursor values */
-const ALL_DIGITS_RE = /^\d+$/;
-
-/**
- * Build a context key for pagination cursor storage.
- *
- * Encodes the API host, org, project, sort, and query so cursors from
- * different searches are never mixed.
- */
-function buildContextKey(
-  org: string,
-  project: string,
-  flags: Pick<ListFlags, "sort" | "query">
-): string {
-  const host = getApiBaseUrl();
-  const escapedQuery = flags.query
-    ? escapeContextKeyValue(flags.query)
-    : undefined;
-  return (
-    `host:${host}|type:trace:${org}/${project}` +
-    `|sort:${flags.sort}` +
-    (escapedQuery ? `|q:${escapedQuery}` : "")
-  );
-}
-
 /** Build the CLI hint for fetching the next page, preserving active flags. */
 function nextPageHint(org: string, project: string, flags: ListFlags): string {
   const base = `sentry trace list ${org}/${project} -c last`;
@@ -160,22 +135,7 @@ export const listCommand = buildListCommand("trace", {
         brief: "Sort by: date, duration",
         default: "date" as const,
       },
-      cursor: {
-        kind: "parsed",
-        parse: (value: string) => {
-          if (value === "last") {
-            return value;
-          }
-          if (ALL_DIGITS_RE.test(value)) {
-            throw new Error(
-              `'${value}' is not a valid cursor. Cursors look like "1735689600:0:0". Use "last" to continue from the previous page.`
-            );
-          }
-          return value;
-        },
-        brief: 'Pagination cursor (use "last" to continue from previous page)',
-        optional: true,
-      },
+      cursor: LIST_CURSOR_FLAG,
       json: {
         kind: "boolean",
         brief: "Output as JSON",
@@ -200,7 +160,10 @@ export const listCommand = buildListCommand("trace", {
     setContext([org], [project]);
 
     // Build context key and resolve cursor for pagination
-    const contextKey = buildContextKey(org, project, flags);
+    const contextKey = buildPaginationContextKey("trace", `${org}/${project}`, {
+      sort: flags.sort,
+      q: flags.query,
+    });
     const cursor = resolveOrgCursor(flags.cursor, PAGINATION_KEY, contextKey);
 
     const { data: traces, nextCursor } = await listTransactions(org, project, {

src/lib/db/pagination.ts

@@ -118,6 +118,44 @@ export function escapeContextKeyValue(value: string): string {
   return value.replaceAll("|", "%7C");
 }
 
+/**
+ * Build a composite context key for pagination cursor storage.
+ *
+ * Encodes the API host, a type discriminant, a scope string, and optional
+ * key-value params (sort, query, period, platform, …) so cursors from
+ * different searches are never mixed.
+ *
+ * @param type  - Discriminant for the kind of listing (e.g. "org", "trace", "multi")
+ * @param scope - Scoping string (e.g. org slug, "org/project", sorted target fingerprint)
+ * @param params - Optional extra segments. Only defined values are included;
+ *   each value is escaped via {@link escapeContextKeyValue}.
+ * @returns Composite context key string
+ *
+ * @example
+ * // Simple org-scoped key (equivalent to legacy buildOrgContextKey)
+ * buildPaginationContextKey("org", "my-org")
+ * // → "host:https://sentry.io|type:org:my-org"
+ *
+ * // Trace list with sort + query
+ * buildPaginationContextKey("trace", "my-org/my-project", { sort: "date", q: "GET" })
+ * // → "host:https://sentry.io|type:trace:my-org/my-project|sort:date|q:GET"
+ */
+export function buildPaginationContextKey(
+  type: string,
+  scope: string,
+  params?: Record<string, string | undefined>
+): string {
+  let key = `host:${getApiBaseUrl()}|type:${type}:${scope}`;
+  if (params) {
+    for (const [name, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        key += `|${name}:${escapeContextKeyValue(value)}`;
+      }
+    }
+  }
+  return key;
+}
+
 /**
  * Build a context key for org-scoped pagination cursor storage.
  *
@@ -128,7 +166,7 @@ export function escapeContextKeyValue(value: string): string {
  * @returns Composite context key string
  */
 export function buildOrgContextKey(org: string): string {
-  return `host:${getApiBaseUrl()}|type:org:${org}`;
+  return buildPaginationContextKey("org", org);
 }
 
 /**

src/lib/list-command.ts

@@ -83,6 +83,34 @@ export const LIST_JSON_FLAG = {
   default: false,
 } as const;
 
+/** Matches strings that are all digits — used to detect invalid cursor values */
+const ALL_DIGITS_RE = /^\d+$/;
+
+/**
+ * Parse and validate a `--cursor` flag value.
+ *
+ * Accepts the magic `"last"` keyword (resume from stored cursor) and opaque
+ * Sentry cursor strings (e.g. `"1735689600:0:0"`). Rejects bare integers
+ * early — they are never valid cursors and would produce a cryptic 400 from
+ * the API.
+ *
+ * Shared by {@link LIST_CURSOR_FLAG} and commands that define their own
+ * cursor flag with a custom `brief`.
+ *
+ * @throws Error when value is a bare integer
+ */
+export function parseCursorFlag(value: string): string {
+  if (value === "last") {
+    return value;
+  }
+  if (ALL_DIGITS_RE.test(value)) {
+    throw new Error(
+      `'${value}' is not a valid cursor. Cursors look like "1735689600:0:0". Use "last" to continue from the previous page.`
+    );
+  }
+  return value;
+}
+
 /**
  * The `--cursor` / `-c` flag shared by all list commands.
  *
@@ -91,7 +119,7 @@ export const LIST_JSON_FLAG = {
  */
 export const LIST_CURSOR_FLAG = {
   kind: "parsed" as const,
-  parse: String,
+  parse: parseCursorFlag,
   brief: 'Pagination cursor (use "last" to continue from previous page)',
   optional: true as const,
 };

test/lib/db/pagination.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Unit tests for pagination context key builders.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  buildOrgContextKey,
+  buildPaginationContextKey,
+} from "../../../src/lib/db/pagination.js";
+
+describe("buildPaginationContextKey", () => {
+  test("builds simple org-scoped key", () => {
+    const key = buildPaginationContextKey("org", "my-org");
+    expect(key).toContain("type:org:my-org");
+    expect(key).toMatch(/^host:.+\|type:org:my-org$/);
+  });
+
+  test("includes optional params when defined", () => {
+    const key = buildPaginationContextKey("trace", "my-org/my-proj", {
+      sort: "date",
+      q: "GET /api",
+    });
+    expect(key).toContain("type:trace:my-org/my-proj");
+    expect(key).toContain("|sort:date");
+    expect(key).toContain("|q:GET /api");
+  });
+
+  test("omits undefined params", () => {
+    const key = buildPaginationContextKey("trace", "my-org/my-proj", {
+      sort: "date",
+      q: undefined,
+    });
+    expect(key).toContain("|sort:date");
+    expect(key).not.toContain("|q:");
+  });
+
+  test("escapes pipe characters in param values", () => {
+    const key = buildPaginationContextKey("org", "my-org", {
+      q: "a|b",
+    });
+    expect(key).toContain("|q:a%7Cb");
+    expect(key).not.toContain("|q:a|b");
+  });
+});
+
+describe("buildOrgContextKey", () => {
+  test("delegates to buildPaginationContextKey", () => {
+    const orgKey = buildOrgContextKey("test-org");
+    const directKey = buildPaginationContextKey("org", "test-org");
+    expect(orgKey).toBe(directKey);
+  });
+});

test/lib/list-command.test.ts

@@ -15,6 +15,7 @@ import {
   LIST_JSON_FLAG,
   LIST_TARGET_POSITIONAL,
   type OrgListCommandDocs,
+  parseCursorFlag,
 } from "../../src/lib/list-command.js";
 import type { OrgListConfig } from "../../src/lib/org-list.js";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
@@ -43,10 +44,12 @@ describe("LIST_JSON_FLAG", () => {
 });
 
 describe("LIST_CURSOR_FLAG", () => {
-  test("is an optional parsed string flag", () => {
+  test("is an optional parsed flag with cursor validation", () => {
     expect(LIST_CURSOR_FLAG.kind).toBe("parsed");
     expect(LIST_CURSOR_FLAG.optional).toBe(true);
-    expect(LIST_CURSOR_FLAG.parse).toBe(String);
+    expect(LIST_CURSOR_FLAG.parse("last")).toBe("last");
+    expect(LIST_CURSOR_FLAG.parse("1735689600:0:0")).toBe("1735689600:0:0");
+    expect(() => LIST_CURSOR_FLAG.parse("12345")).toThrow("not a valid cursor");
     expect(LIST_CURSOR_FLAG.brief).toContain('"last"');
   });
 });
@@ -83,6 +86,32 @@ describe("LIST_BASE_ALIASES", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// parseCursorFlag: shared cursor validation
+// ---------------------------------------------------------------------------
+
+describe("parseCursorFlag", () => {
+  test("passes through 'last' keyword", () => {
+    expect(parseCursorFlag("last")).toBe("last");
+  });
+
+  test("passes through valid cursor strings", () => {
+    expect(parseCursorFlag("1735689600:0:0")).toBe("1735689600:0:0");
+    expect(parseCursorFlag("abc:def:0")).toBe("abc:def:0");
+  });
+
+  test("rejects bare integer strings", () => {
+    expect(() => parseCursorFlag("12345")).toThrow("not a valid cursor");
+    expect(() => parseCursorFlag("0")).toThrow("not a valid cursor");
+    expect(() => parseCursorFlag("999999999")).toThrow("not a valid cursor");
+  });
+
+  test("accepts strings with digits and other characters", () => {
+    expect(parseCursorFlag("123abc")).toBe("123abc");
+    expect(parseCursorFlag("abc123")).toBe("abc123");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // buildOrgListCommand: integration with dispatchOrgScopedList
 // ---------------------------------------------------------------------------