fix: support numeric project IDs in project slug resolution (#284)

## Summary

- Fixes **CLI-7W**: Users passing a numeric Sentry project ID (e.g.,
`sentry event view 7275560680 <event-id>`) got a confusing "Project not
found" error
- Also resolves **CLI-80** as already fixed by PR #279 (cursor format
validation)

## Changes

**`findProjectsBySlug` (api-client.ts):** When the input is all-digits,
accept the API result even when the returned slug differs from the
input. The Sentry API's `project_id_or_slug` parameter already resolves
numeric IDs — the CLI just wasn't accepting those results.

**`resolveProjectBySlug` (resolve-target.ts):** 
- When a numeric ID resolves successfully, prints a stderr hint: `Tip:
Resolved project ID 7275560680 to acme/frontend. Use the slug form for
faster lookups.`
- When resolution fails with an all-digit input, the error message says
"Numeric project IDs are not supported" instead of the generic "Check
that you have access"

**View commands:** Pass `this.stderr` to `resolveProjectBySlug` so the
hint can be displayed.

## Testing

- 2 new tests for `findProjectsBySlug`: numeric ID resolution accepted,
non-numeric slug mismatch still rejected
- 1 updated test for `project view` func (new `stderr` parameter)
- All 2010 tests pass

Author: BYK

src/commands/event/view.ts

@@ -206,7 +206,8 @@ export const viewCommand = buildCommand({
         const resolved = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry event view <org>/${parsed.projectSlug} ${eventId}`
+          `sentry event view <org>/${parsed.projectSlug} ${eventId}`,
+          this.stderr
         );
         target = {
           ...resolved,

src/commands/log/view.ts

@@ -160,7 +160,8 @@ export const viewCommand = buildCommand({
         target = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry log view <org>/${parsed.projectSlug} ${logId}`
+          `sentry log view <org>/${parsed.projectSlug} ${logId}`,
+          this.stderr
         );
         break;
 

src/commands/project/view.ts

@@ -265,7 +265,8 @@ export const viewCommand = buildCommand({
         const resolved = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry project view <org>/${parsed.projectSlug}`
+          `sentry project view <org>/${parsed.projectSlug}`,
+          this.stderr
         );
         resolvedTargets = [
           {

src/commands/trace/view.ts

@@ -170,7 +170,8 @@ export const viewCommand = buildCommand({
         target = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry trace view <org>/${parsed.projectSlug} ${traceId}`
+          `sentry trace view <org>/${parsed.projectSlug} ${traceId}`,
+          this.stderr
         );
         break;
 

src/lib/api-client.ts

@@ -790,15 +790,21 @@ export async function findProjectsBySlug(
   projectSlug: string
 ): Promise<ProjectWithOrg[]> {
   const orgs = await listOrganizations();
+  const isNumericId = isAllDigits(projectSlug);
 
   // Direct lookup in parallel — one API call per org instead of paginating all projects
   const searchResults = await Promise.all(
     orgs.map(async (org) => {
       try {
         const project = await getProject(org.slug, projectSlug);
         // The API accepts project_id_or_slug, so a numeric input could
-        // resolve by ID. Verify the returned slug actually matches.
-        if (project.slug !== projectSlug) {
+        // resolve by ID instead of slug. When the input is all digits,
+        // accept the match (the user passed a numeric project ID).
+        // For non-numeric inputs, verify the slug actually matches to
+        // avoid false positives from coincidental ID collisions.
+        // Note: Sentry enforces that project slugs must start with a letter,
+        // so an all-digits input can only ever be a numeric ID, never a slug.
+        if (!isNumericId && project.slug !== projectSlug) {
           return null;
         }
         return { ...project, orgSlug: org.slug };

src/lib/resolve-target.ts

@@ -38,6 +38,8 @@ import {
   getDsnSourceDescription,
 } from "./dsn/index.js";
 import { AuthError, ContextError, ValidationError } from "./errors.js";
+import { warning } from "./formatters/colors.js";
+import { isAllDigits } from "./utils.js";
 
 /**
  * Resolved organization and project target for API calls.
@@ -786,12 +788,15 @@ export async function resolveOrg(
 export async function resolveProjectBySlug(
   projectSlug: string,
   usageHint: string,
-  disambiguationExample?: string
+  disambiguationExample?: string,
+  stderr?: { write(s: string): void }
 ): Promise<{ org: string; project: string }> {
   const found = await findProjectsBySlug(projectSlug);
   if (found.length === 0) {
     throw new ContextError(`Project "${projectSlug}"`, usageHint, [
-      "Check that you have access to a project with this slug",
+      isAllDigits(projectSlug)
+        ? "No project with this ID was found — check the ID or use the project slug instead"
+        : "Check that you have access to a project with this slug",
     ]);
   }
   if (found.length > 1) {
@@ -805,6 +810,17 @@ export async function resolveProjectBySlug(
     );
   }
   const foundProject = found[0] as (typeof found)[0];
+
+  // When a numeric project ID resolved successfully, hint about using the slug
+  if (stderr && isAllDigits(projectSlug) && foundProject.slug !== projectSlug) {
+    stderr.write(
+      warning(
+        `Tip: Resolved project ID ${projectSlug} to ${foundProject.orgSlug}/${foundProject.slug}. ` +
+          "Use the slug form for faster lookups.\n"
+      )
+    );
+  }
+
   return {
     org: foundProject.orgSlug,
     project: foundProject.slug,

test/commands/event/view.test.ts

@@ -5,7 +5,15 @@
  * in src/commands/event/view.ts
  */
 
-import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
 import { parsePositionalArgs } from "../../../src/commands/event/view.js";
 import type { ProjectWithOrg } from "../../../src/lib/api-client.js";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
@@ -327,4 +335,61 @@ describe("resolveProjectBySlug", () => {
       expect(result.project).toBe("web-frontend");
     });
   });
+
+  describe("numeric project ID", () => {
+    test("uses numeric-ID-specific error when not found", async () => {
+      findProjectsBySlugSpy.mockResolvedValue([]);
+
+      try {
+        await resolveProjectBySlug("7275560680", HINT);
+        expect.unreachable("Should have thrown");
+      } catch (error) {
+        expect(error).toBeInstanceOf(ContextError);
+        const message = (error as ContextError).message;
+        expect(message).toContain('Project "7275560680"');
+        expect(message).toContain("No project with this ID was found");
+      }
+    });
+
+    test("writes stderr hint when numeric ID resolves to a different slug", async () => {
+      findProjectsBySlugSpy.mockResolvedValue([
+        {
+          slug: "my-frontend",
+          orgSlug: "acme",
+          id: "7275560680",
+          name: "Frontend",
+        },
+      ] as ProjectWithOrg[]);
+      const stderrWrite = mock(() => true);
+      const stderr = { write: stderrWrite };
+
+      const result = await resolveProjectBySlug(
+        "7275560680",
+        HINT,
+        undefined,
+        stderr
+      );
+
+      expect(result).toEqual({ org: "acme", project: "my-frontend" });
+      expect(stderrWrite).toHaveBeenCalledTimes(1);
+      const hint = stderrWrite.mock.calls[0][0] as string;
+      expect(hint).toContain("7275560680");
+      expect(hint).toContain("acme/my-frontend");
+    });
+
+    test("does not write hint when stderr is not provided", async () => {
+      findProjectsBySlugSpy.mockResolvedValue([
+        {
+          slug: "my-frontend",
+          orgSlug: "acme",
+          id: "7275560680",
+          name: "Frontend",
+        },
+      ] as ProjectWithOrg[]);
+
+      // Should not throw even without stderr
+      const result = await resolveProjectBySlug("7275560680", HINT);
+      expect(result).toEqual({ org: "acme", project: "my-frontend" });
+    });
+  });
 });

test/commands/project/view.func.test.ts

@@ -170,7 +170,8 @@ describe("viewCommand.func", () => {
     expect(resolveProjectBySlugSpy).toHaveBeenCalledWith(
       "frontend",
       "sentry project view <org>/<project>",
-      "sentry project view <org>/frontend"
+      "sentry project view <org>/frontend",
+      context.stderr
     );
     const output = stdoutWrite.mock.calls.map((c) => c[0]).join("");
     const parsed = JSON.parse(output);

test/lib/api-client.test.ts

@@ -729,6 +729,99 @@ describe("findProjectsBySlug", () => {
     expect(results).toHaveLength(1);
     expect(results[0].orgSlug).toBe("acme");
   });
+
+  test("resolves numeric project ID when slug differs", async () => {
+    const { findProjectsBySlug } = await import("../../src/lib/api-client.js");
+
+    globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+      const req = new Request(input, init);
+      const url = req.url;
+
+      // Regions endpoint
+      if (url.includes("/users/me/regions/")) {
+        return new Response(
+          JSON.stringify({
+            regions: [{ name: "us", url: "https://us.sentry.io" }],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+
+      // Organizations list
+      if (url.includes("/organizations/") && !url.includes("/projects/")) {
+        return new Response(
+          JSON.stringify([{ id: "1", slug: "acme", name: "Acme Corp" }]),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+
+      // getProject for acme/7275560680 - API resolves by numeric ID,
+      // returns project with a different slug
+      if (url.includes("/projects/acme/7275560680/")) {
+        return new Response(
+          JSON.stringify({
+            id: "7275560680",
+            slug: "frontend",
+            name: "Frontend",
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+
+      return new Response(JSON.stringify({ detail: "Not found" }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+
+    // Numeric ID should resolve even though returned slug differs
+    const results = await findProjectsBySlug("7275560680");
+    expect(results).toHaveLength(1);
+    expect(results[0].slug).toBe("frontend");
+    expect(results[0].orgSlug).toBe("acme");
+  });
+
+  test("rejects non-numeric input when returned slug differs", async () => {
+    const { findProjectsBySlug } = await import("../../src/lib/api-client.js");
+
+    globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+      const req = new Request(input, init);
+      const url = req.url;
+
+      if (url.includes("/users/me/regions/")) {
+        return new Response(
+          JSON.stringify({
+            regions: [{ name: "us", url: "https://us.sentry.io" }],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+
+      if (url.includes("/organizations/") && !url.includes("/projects/")) {
+        return new Response(
+          JSON.stringify([{ id: "1", slug: "acme", name: "Acme Corp" }]),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+
+      // API returns project with different slug (coincidental ID match)
+      if (url.includes("/projects/acme/wrong-slug/")) {
+        return new Response(
+          JSON.stringify({ id: "999", slug: "actual-slug", name: "Actual" }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+
+      return new Response(JSON.stringify({ detail: "Not found" }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+
+    // Non-numeric input with slug mismatch should be rejected
+    const results = await findProjectsBySlug("wrong-slug");
+    expect(results).toHaveLength(0);
+  });
 });
 
 describe("listTeamsPaginated", () => {