refactor: address review comments — shared escaping utility and deduplicated handler

- Extract escapeContextKeyValue() into db/pagination.ts as shared utility
  for pipe-delimiter escaping in context keys (was inline in issue/list.ts
  and project/list.ts).
- Deduplicate handleResolvedTargets overrides in issue/list.ts: single
  resolveAndHandle function reused across auto-detect, explicit, and
  project-search modes instead of three identical closures.
- Add explanatory comments for fullQuery || undefined in api-client.ts
  and for 'Project' ContextError resource in org-list.ts handleProjectSearch.

Author: BYK

src/commands/issue/list.ts

@@ -13,10 +13,14 @@ import {
   listIssuesPaginated,
   listProjects,
 } from "../../lib/api-client.js";
-import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
+import {
+  type ParsedOrgProject,
+  parseOrgProjectArg,
+} from "../../lib/arg-parsing.js";
 import { buildCommand } from "../../lib/command.js";
 import {
   clearPaginationCursor,
+  escapeContextKeyValue,
   resolveOrgCursor,
   setPaginationCursor,
 } from "../../lib/db/pagination.js";
@@ -407,8 +411,9 @@ type OrgAllIssuesOptions = {
 async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
   const { stdout, org, flags, setContext } = options;
   // Encode sort + query in context key so cursors from different searches don't collide.
-  // Pipe chars in user query are escaped to prevent delimiter injection.
-  const escapedQuery = flags.query?.replaceAll("|", "%7C");
+  const escapedQuery = flags.query
+    ? escapeContextKeyValue(flags.query)
+    : undefined;
   const contextKey = `host:${getApiBaseUrl()}|type:org:${org}|sort:${flags.sort}${escapedQuery ? `|q:${escapedQuery}` : ""}`;
   const cursor = resolveOrgCursor(flags.cursor, PAGINATION_KEY, contextKey);
 
@@ -685,40 +690,29 @@ export const listCommand = buildCommand({
 
     const parsed = parseOrgProjectArg(target);
 
+    // Shared handler for modes that resolve targets (auto-detect, explicit, project-search).
+    // Each mode's narrowed ParsedVariant<K> is a subtype of ParsedOrgProject,
+    // so passing it to handleResolvedTargets (which accepts the full union) is safe.
+    const resolveAndHandle = (p: ParsedOrgProject) =>
+      handleResolvedTargets({
+        stdout,
+        stderr,
+        parsed: p,
+        flags,
+        cwd,
+        setContext,
+      });
+
     await dispatchOrgScopedList({
       config: issueListMeta,
       stdout,
       cwd,
       flags,
       parsed,
       overrides: {
-        "auto-detect": (p) =>
-          handleResolvedTargets({
-            stdout,
-            stderr,
-            parsed: p,
-            flags,
-            cwd,
-            setContext,
-          }),
-        explicit: (p) =>
-          handleResolvedTargets({
-            stdout,
-            stderr,
-            parsed: p,
-            flags,
-            cwd,
-            setContext,
-          }),
-        "project-search": (p) =>
-          handleResolvedTargets({
-            stdout,
-            stderr,
-            parsed: p,
-            flags,
-            cwd,
-            setContext,
-          }),
+        "auto-detect": resolveAndHandle,
+        explicit: resolveAndHandle,
+        "project-search": resolveAndHandle,
         "org-all": (p) =>
           handleOrgAllIssues({ stdout, org: p.org, flags, setContext }),
       },

src/commands/project/list.ts

@@ -27,6 +27,7 @@ import { buildCommand } from "../../lib/command.js";
 import { getDefaultOrganization } from "../../lib/db/defaults.js";
 import {
   clearPaginationCursor,
+  escapeContextKeyValue,
   resolveOrgCursor,
   setPaginationCursor,
 } from "../../lib/db/pagination.js";
@@ -216,9 +217,8 @@ export function buildContextKey(
   }
   if (flags.platform) {
     // Normalize to lowercase since platform filtering is case-insensitive.
-    // Escape pipe chars to prevent delimiter injection.
     parts.push(
-      `platform:${flags.platform.toLowerCase().replaceAll("|", "%7C")}`
+      `platform:${escapeContextKeyValue(flags.platform.toLowerCase())}`
     );
   }
   return parts.join("|");

src/lib/api-client.ts

@@ -1037,6 +1037,9 @@ export function listIssuesPaginated(
     `/organizations/${orgSlug}/issues/`,
     {
       params: {
+        // Convert empty string to undefined so ky omits the param entirely;
+        // sending `query=` causes the Sentry API to behave differently than
+        // omitting the parameter.
         query: fullQuery || undefined,
         cursor: options.cursor,
         per_page: options.perPage ?? 25,
@@ -1228,6 +1231,9 @@ export async function listTransactions(
         dataset: "transactions",
         field: TRANSACTION_FIELDS,
         project: isNumericProject ? projectSlug : undefined,
+        // Convert empty string to undefined so ky omits the param entirely;
+        // sending `query=` causes the Sentry API to behave differently than
+        // omitting the parameter.
         query: fullQuery || undefined,
         per_page: options.limit || 10,
         statsPeriod: options.statsPeriod ?? "7d",

src/lib/db/pagination.ts

@@ -103,6 +103,21 @@ export function clearPaginationCursor(
   ).run(commandKey, context);
 }
 
+/**
+ * Escape a user-provided value for safe inclusion in a context key.
+ *
+ * Context keys use `|` as a segment delimiter. If user input (e.g., a search
+ * query or platform filter) contains `|`, it must be escaped to prevent
+ * delimiter injection that could cause cache collisions between different
+ * query combinations.
+ *
+ * @param value - Raw user-provided string
+ * @returns Escaped string with `|` replaced by `%7C`
+ */
+export function escapeContextKeyValue(value: string): string {
+  return value.replaceAll("|", "%7C");
+}
+
 /**
  * Build a context key for org-scoped pagination cursor storage.
  *

src/lib/org-list.ts

@@ -521,6 +521,9 @@ export async function handleProjectSearch<TEntity, TWithOrg>(
       writeJson(stdout, []);
       return;
     }
+    // Use "Project" as the resource name (not config.entityName) because the
+    // error is about a project lookup failure, not the entity being listed.
+    // e.g., "Project is missing" not "Team is missing".
     throw new ContextError(
       "Project",
       `No project '${projectSlug}' found in any accessible organization.\n\n` +