fix(api): use numeric project ID to avoid "not actively selected" error (#312)

## Summary

`sentry issue list sentry/sentry` failed with "Project(s) sentry do not
exist or are not actively selected" because `listIssuesPaginated` passed
the project as `project:sentry` in the search query string. The Sentry
Issues API only searches within "actively selected" projects for that
syntax.

When we have the numeric project ID, we now use the `project` query
param (`Array<number>`) instead, which selects the project directly and
bypasses the "actively selected" requirement.

## Changes

Thread numeric `projectId` through `ResolvedTarget` → API calls:

- **`project_cache` schema**: add `project_id` column (schema v7) so
cached lookups also return the ID
- **`ResolvedTarget`**: add `projectId?: number`, populated from all
resolution paths (explicit targets via `getProject`, DSN detection,
cache hits, directory inference)
- **`listIssuesPaginated`**: when `projectId` is provided, use `project:
[id]` query param instead of `project:<slug>` search syntax; fall back
to slug when ID is unavailable
- **`listIssuesAllPages` / `fetchIssuesForTarget`**: pass `projectId`
through

For explicit targets (`sentry issue list org/project`), the `getProject`
call also serves as early validation — typos now fail with a clear 404
instead of a confusing "not actively selected" error from the issues
endpoint.

## Test plan

- New unit tests for `projectId` in `listIssuesPaginated` (3 tests)
- All existing tests pass (113 tests across api-client, resolve-target,
schema)
- Manual: `sentry issue list sentry/sentry -n 5` now returns issues (was
failing)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Burak Yigit Kaya <byk@sentry.io>

Author: 3 people

AGENTS.md

@@ -10,6 +10,7 @@ import { buildOrgAwareAliases } from "../../lib/alias.js";
 import {
   API_MAX_PER_PAGE,
   findProjectsBySlug,
+  getProject,
   type IssuesPage,
   listIssuesAllPages,
   listIssuesPaginated,
@@ -55,8 +56,10 @@ import {
 } from "../../lib/org-list.js";
 import { withProgress } from "../../lib/polling.js";
 import {
+  fetchProjectId,
   type ResolvedTarget,
   resolveAllTargets,
+  toNumericId,
 } from "../../lib/resolve-target.js";
 import { getApiBaseUrl } from "../../lib/sentry-client.js";
 import type {
@@ -282,29 +285,54 @@ async function resolveTargetsFromParsedArg(
   cwd: string
 ): Promise<TargetResolutionResult> {
   switch (parsed.type) {
-    case "auto-detect":
+    case "auto-detect": {
       // Use existing resolution logic (DSN detection, config defaults)
-      return resolveAllTargets({ cwd, usageHint: USAGE_HINT });
+      const result = await resolveAllTargets({ cwd, usageHint: USAGE_HINT });
+      // DSN-detected and directory-inferred targets already carry a projectId.
+      // Env var / config-default paths return targets without one, so enrich
+      // them now using the project API. Any failure silently falls back to
+      // slug-based querying — the target was already resolved, so we never
+      // surface a ResolutionError here (that's only for the explicit case).
+      result.targets = await Promise.all(
+        result.targets.map(async (t) => {
+          if (t.projectId !== undefined) {
+            return t;
+          }
+          try {
+            const info = await getProject(t.org, t.project);
+            const id = toNumericId(info.id);
+            return id !== undefined ? { ...t, projectId: id } : t;
+          } catch {
+            return t;
+          }
+        })
+      );
+      return result;
+    }
 
-    case "explicit":
-      // Single explicit target
+    case "explicit": {
+      // Single explicit target — fetch project ID for API query param
+      const projectId = await fetchProjectId(parsed.org, parsed.project);
       return {
         targets: [
           {
             org: parsed.org,
             project: parsed.project,
+            projectId,
             orgDisplay: parsed.org,
             projectDisplay: parsed.project,
           },
         ],
       };
+    }
 
     case "org-all": {
       // List all projects in the specified org
       const projects = await listProjects(parsed.org);
       const targets: ResolvedTarget[] = projects.map((p) => ({
         org: parsed.org,
         project: p.slug,
+        projectId: toNumericId(p.id),
         orgDisplay: parsed.org,
         projectDisplay: p.name,
       }));
@@ -341,6 +369,7 @@ async function resolveTargetsFromParsedArg(
       const targets: ResolvedTarget[] = matches.map((m) => ({
         org: m.orgSlug,
         project: m.slug,
+        projectId: toNumericId(m.id),
         orgDisplay: m.orgSlug,
         projectDisplay: m.name,
       }));
@@ -386,7 +415,7 @@ async function fetchIssuesForTarget(
     const { issues, nextCursor } = await listIssuesAllPages(
       target.org,
       target.project,
-      options
+      { ...options, projectId: target.projectId }
     );
     return {
       success: true,
@@ -928,19 +957,22 @@ async function handleResolvedTargets(
   }
 
   const validResults: IssueListResult[] = [];
-  const failures: Error[] = [];
+  const failures: { target: ResolvedTarget; error: Error }[] = [];
 
-  for (const result of results) {
+  for (let i = 0; i < results.length; i++) {
+    // biome-ignore lint/style/noNonNullAssertion: index within bounds
+    const result = results[i]!;
     if (result.success) {
       validResults.push(result.data);
     } else {
-      failures.push(result.error);
+      // biome-ignore lint/style/noNonNullAssertion: index within bounds
+      failures.push({ target: activeTargets[i]!, error: result.error });
     }
   }
 
   if (validResults.length === 0 && failures.length > 0) {
     // biome-ignore lint/style/noNonNullAssertion: guarded by failures.length > 0
-    const first = failures[0]!;
+    const { error: first } = failures[0]!;
     const prefix = `Failed to fetch issues from ${targets.length} project(s)`;
 
     // Propagate ApiError so telemetry sees the original status code
@@ -997,20 +1029,27 @@ async function handleResolvedTargets(
       hasMore: hasMoreToShow,
     };
     if (failures.length > 0) {
-      output.errors = failures.map((e) =>
+      output.errors = failures.map(({ target: t, error: e }) =>
         e instanceof ApiError
-          ? { status: e.status, message: e.message }
-          : { message: e.message }
+          ? {
+              project: `${t.org}/${t.project}`,
+              status: e.status,
+              message: e.message,
+            }
+          : { project: `${t.org}/${t.project}`, message: e.message }
       );
     }
     writeJson(stdout, output);
     return;
   }
 
   if (failures.length > 0) {
+    const failedNames = failures
+      .map(({ target: t }) => `${t.org}/${t.project}`)
+      .join(", ");
     stderr.write(
       muted(
-        `\nNote: Failed to fetch issues from ${failures.length} project(s). Showing results from ${validResults.length} project(s).\n`
+        `\nNote: Failed to fetch issues from ${failedNames}. Showing results from ${validResults.length} project(s).\n`
       )
     );
   }

src/commands/issue/list.ts

@@ -1050,12 +1050,19 @@ export async function listIssuesPaginated(
     perPage?: number;
     sort?: IssueSort;
     statsPeriod?: string;
+    /** Numeric project ID. When provided, uses the `project` query param
+     *  instead of `project:<slug>` search syntax, avoiding "not actively
+     *  selected" errors. */
+    projectId?: number;
   } = {}
 ): Promise<PaginatedResponse<SentryIssue[]>> {
-  // Only add project filter when projectSlug is non-empty; an empty slug would
-  // produce "project:" (a truthy string that .filter(Boolean) won't remove),
-  // sending a malformed query to the API for org-wide listing.
-  const projectFilter = projectSlug ? `project:${projectSlug}` : "";
+  // When we have a numeric project ID, use the `project` query param (Array<number>)
+  // instead of `project:<slug>` in the search query. The API's `project` param
+  // selects the project directly, bypassing the "actively selected" requirement.
+  let projectFilter = "";
+  if (!options.projectId && projectSlug) {
+    projectFilter = `project:${projectSlug}`;
+  }
   const fullQuery = [projectFilter, options.query].filter(Boolean).join(" ");
 
   const config = await getOrgSdkConfig(orgSlug);
@@ -1064,6 +1071,7 @@ export async function listIssuesPaginated(
     ...config,
     path: { organization_id_or_slug: orgSlug },
     query: {
+      project: options.projectId ? [options.projectId] : undefined,
       // Convert empty string to undefined so the SDK omits the param entirely;
       // sending `query=` causes the Sentry API to behave differently than
       // omitting the parameter.
@@ -1116,6 +1124,8 @@ export async function listIssuesAllPages(
     limit: number;
     sort?: IssueSort;
     statsPeriod?: string;
+    /** Numeric project ID for direct project selection via query param. */
+    projectId?: number;
     /** Resume pagination from this cursor instead of starting from the beginning. */
     startCursor?: string;
     /** Called after each page is fetched. Useful for progress indicators. */
@@ -1141,6 +1151,7 @@ export async function listIssuesAllPages(
       perPage,
       sort: options.sort,
       statsPeriod: options.statsPeriod,
+      projectId: options.projectId,
     });
 
     allResults.push(...response.data);

src/lib/api-client.ts

@@ -12,6 +12,7 @@ type ProjectCacheRow = {
   org_name: string;
   project_slug: string;
   project_name: string;
+  project_id?: string;
   cached_at: number;
   last_accessed: number;
 };
@@ -30,6 +31,7 @@ function rowToCachedProject(row: ProjectCacheRow): CachedProject {
     orgName: row.org_name,
     projectSlug: row.project_slug,
     projectName: row.project_name,
+    projectId: row.project_id,
     cachedAt: row.cached_at,
   };
 }
@@ -78,6 +80,7 @@ export async function setCachedProject(
       org_name: info.orgName,
       project_slug: info.projectSlug,
       project_name: info.projectName,
+      project_id: info.projectId ?? null,
       cached_at: now,
       last_accessed: now,
     },
@@ -124,6 +127,7 @@ export async function setCachedProjectByDsnKey(
       org_name: info.orgName,
       project_slug: info.projectSlug,
       project_name: info.projectName,
+      project_id: info.projectId ?? null,
       cached_at: now,
       last_accessed: now,
     },

src/lib/db/project-cache.ts

@@ -14,7 +14,7 @@
 import type { Database } from "bun:sqlite";
 import { stringifyUnknown } from "../errors.js";
 
-export const CURRENT_SCHEMA_VERSION = 6;
+export const CURRENT_SCHEMA_VERSION = 7;
 
 /** Environment variable to disable auto-repair */
 const NO_AUTO_REPAIR_ENV = "SENTRY_CLI_NO_AUTO_REPAIR";
@@ -85,6 +85,7 @@ export const TABLE_SCHEMAS: Record<string, TableSchema> = {
       org_name: { type: "TEXT", notNull: true },
       project_slug: { type: "TEXT", notNull: true },
       project_name: { type: "TEXT", notNull: true },
+      project_id: { type: "TEXT", addedInVersion: 7 },
       cached_at: {
         type: "INTEGER",
         notNull: true,
@@ -708,6 +709,11 @@ export function runMigrations(db: Database): void {
     db.exec(EXPECTED_TABLES.pagination_cursors as string);
   }
 
+  // Migration 6 -> 7: Add project_id column to project_cache for numeric project filtering
+  if (currentVersion < 7) {
+    addColumnIfMissing(db, "project_cache", "project_id", "TEXT");
+  }
+
   if (currentVersion < CURRENT_SCHEMA_VERSION) {
     db.query("UPDATE schema_version SET version = ?").run(
       CURRENT_SCHEMA_VERSION