perf(api): pass ?collapse=organization on project detail fetches (#818)

## Summary

Cuts ~400-500ms off `GET /api/0/projects/{org}/{project}/` by asking the
server to skip full-org serialization. The collapsed response carries
only `{id, slug}` for `organization` instead of the full payload
(feature flags, options, etc).

Colleague flagged this optimization noting the UI already benefits —
every CLI hot path that fetches project details can ride the same win.

## Hot paths that benefit

- DSN auto-detect (numeric `orgId/projectId` → slug resolution)
- Explicit `<org>/<project>` target validation in `resolveTarget`
- `findProjectsBySlug` (one `getProject` per accessible org, multiplying
the saving)
- `project view`, `project delete`, `dashboard create`, `release list`,
`trace view`, `init`, and others

All project detail fetches in the CLI funnel through `getProject()` in
`src/lib/api/projects.ts`, so a single change covers everything.

## Handling the trimmed response

The collapsed payload drops `organization.name`. Four call sites
displayed it:

- `src/lib/resolve-target.ts` — three DSN resolution paths + one
cache-seed after explicit target validation
- `src/lib/dsn/resolver.ts` — DSN → ResolvedProject
- `src/lib/formatters/human.ts` — `project view`'s `Organization:` row

All now use a new `resolveOrgDisplayName(orgSlug, explicitName?)` helper
with the fallback chain:

1. Explicit `name` if the server returned it (self-hosted / older Sentry
ignore `collapse` and return the full payload — handled transparently)
2. `getCachedOrganizations()` lookup — populated on login and every
org-fanout operation
3. Slug itself as last resort

The cosmetic "name → slug" degradation only surfaces on cold-cache +
collapse-honoring server, which is vanishingly rare (every auth flow
warms the cache).

## JSON output shape stays stable

`sentry project view --json` previously returned the full `organization`
object (including `name`, feature flags, `options`). Since
`getProject()` now collapses the server response, `project view` gains a
`jsonTransform` that re-hydrates `organization.name` via
`resolveOrgDisplayName()` before serialization. Downstream agents and
scripts that scrape `.organization.name` continue to see a value.

When the server returns `name` (self-hosted / ignores `collapse`), the
transform preserves it as-is. When absent, it falls back through the
cached org list to the slug. Feature flags and `options` are no longer
returned — this is a deliberate tradeoff, as those fields aren't
documented stable CLI output and dropping them is where the perf win
comes from.

## Response cache invalidation is now prefix-based

The response cache keys by full URL (including sorted query params via
`buildCacheKey`/`normalizeUrl`). Pre-PR,
`invalidateCachedResponse(baseUrl)` would match the cached entry
exactly. Post-PR, cached entries live under
`baseUrl?collapse=organization`, so an exact-match invalidation would
silently miss — `project delete` → `project view` would serve
pre-deletion data.

`invalidateProjectCaches` switches to
`invalidateCachedResponsesMatching` (prefix sweep) to catch the
collapsed variant plus any future query-param additions. The trailing
slash on `buildApiUrl` output guarantees the prefix can't collide with
sibling projects (`projects/acme/frontend/` does not prefix-match
`projects/acme/frontend-old/`).

Side effect: sub-resources like `/projects/acme/frontend/keys/` and
`/projects/acme/frontend/trace-items/...` also get swept on `project
delete`. This is desirable — those children would 404 after the parent
is gone anyway.

## Tests

Added to `test/lib/api-client.test.ts`:
- `getProject sends ?collapse=organization query parameter` — asserts
the outgoing URL carries the query param.
- `getProject tolerates collapsed response missing organization.name` —
confirms no blow-up when `name` is absent.
- 4 `resolveOrgDisplayName` cases: explicit name wins / cache fallback /
slug fallback / empty-string falsy handling.

Added to `test/lib/formatters/human.details.test.ts`:
- `falls back to org slug when collapsed response omits name` —
module-level `useTestConfigDir` ensures an empty `org_regions` table,
regex-match asserts the slug appears in **both** the display-name and
parens positions (stray cached name would fail).

Added to `test/commands/project/view.func.test.ts`:
- `JSON output re-hydrates organization.name when API response omits it`
— exercises the new `jsonTransform` slug-fallback path.
- `JSON output preserves organization.name when API response includes
it` — self-hosted / older-Sentry compat.
- `JSON output still strips detectedFrom (human-only field)` —
regression guard for the `jsonExclude` → `jsonTransform` switch.
- `JSON output honours --fields filter` — confirms field filtering still
works on top of the transform.

## Verification

- `bun run typecheck` ✓
- `bun run lint` ✓ (only a pre-existing unrelated warning)
- `bun run test:unit` → 5676 pass / 0 fail (+4 new from follow-up)
- `bun run test:isolated` → 138 pass / 0 fail

## Follow-ups (out of scope)

- Team detail (`retrieveATeam`) has the same `?collapse=organization`
support per the SDK types — same perf win available for `team list` etc.
- Similar-shape audit on other endpoints returning nested org payloads.

Author: BYK

src/commands/project/view.ts

@@ -6,7 +6,11 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { getProject, tryGetPrimaryDsn } from "../../lib/api-client.js";
+import {
+  getProject,
+  resolveOrgDisplayName,
+  tryGetPrimaryDsn,
+} from "../../lib/api-client.js";
 import {
   ProjectSpecificationType,
   parseOrgProjectArg,
@@ -15,6 +19,7 @@ import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { AuthError, ContextError, withAuthGuard } from "../../lib/errors.js";
 import { divider, formatProjectDetails } from "../../lib/formatters/index.js";
+import { filterFields } from "../../lib/formatters/json.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import {
   applyFreshFlag,
@@ -179,6 +184,50 @@ async function fetchAllProjectDetails(
   return { projects, dsns, targets: validTargets };
 }
 
+/**
+ * Re-hydrate `organization.name` on a project entry.
+ *
+ * `getProject()` passes `?collapse=organization` so the server returns
+ * only `{id, slug}` for `organization` (~400-500ms faster). For JSON
+ * consumers that scrape `.organization.name`, we refill the field from
+ * the cached organizations list (or the slug as last resort) so the
+ * JSON output shape stays stable across CLI versions.
+ */
+function hydrateOrganizationName(entry: ProjectViewEntry): ProjectViewEntry {
+  if (!entry.organization || entry.organization.name) {
+    return entry;
+  }
+  return {
+    ...entry,
+    organization: {
+      ...entry.organization,
+      name: resolveOrgDisplayName(entry.organization.slug),
+    },
+  };
+}
+
+/**
+ * Build the JSON payload: strip `detectedFrom` (human-only), re-hydrate
+ * `organization.name`, and apply `--fields` filtering.
+ *
+ * Replaces the simpler `jsonExclude: ["detectedFrom"]` config so we can
+ * also restore `organization.name` that the collapsed API response omits.
+ */
+function jsonTransformProjectView(
+  entries: ProjectViewEntry[],
+  fields?: string[]
+): unknown {
+  const hydrated = entries.map((entry) => {
+    const { detectedFrom: _detectedFrom, ...rest } =
+      hydrateOrganizationName(entry);
+    return rest;
+  });
+  if (fields && fields.length > 0) {
+    return hydrated.map((item) => filterFields(item, fields));
+  }
+  return hydrated;
+}
+
 /**
  * Format project view entries for human-readable terminal output.
  *
@@ -221,7 +270,7 @@ export const viewCommand = buildCommand({
   },
   output: {
     human: formatProjectViewHuman,
-    jsonExclude: ["detectedFrom"],
+    jsonTransform: jsonTransformProjectView,
   },
   parameters: {
     positional: {

src/lib/api-client.ts

@@ -97,6 +97,7 @@ export {
   matchesWordBoundary,
   type ProjectSearchResult,
   type ProjectWithOrg,
+  resolveOrgDisplayName,
   tryGetPrimaryDsn,
 } from "./api/projects.js";
 export {

src/lib/api/projects.ts

@@ -26,10 +26,7 @@ import { getCachedOrganizations } from "../db/regions.js";
 import { type AuthGuardSuccess, withAuthGuard } from "../errors.js";
 import { logger } from "../logger.js";
 import { resolveOrgRegion } from "../region.js";
-import {
-  invalidateCachedResponse,
-  invalidateCachedResponsesMatching,
-} from "../response-cache.js";
+import { invalidateCachedResponsesMatching } from "../response-cache.js";
 import { getApiBaseUrl } from "../sentry-client.js";
 import { buildProjectUrl } from "../sentry-urls.js";
 import { isAllDigits } from "../utils.js";
@@ -229,6 +226,12 @@ export async function deleteProject(
  * Flush the project-detail GET and the org-wide project list so
  * follow-up `project list` / `project view` reads don't see the
  * deleted project. Never throws.
+ *
+ * Uses prefix-matching on the project detail URL rather than an exact
+ * match because `getProject()` appends `?collapse=organization`, and
+ * the response cache keys entries by the full URL (including query
+ * string). A prefix sweep catches the collapsed variant plus any
+ * future query-parameter additions.
  */
 async function invalidateProjectCaches(
   orgSlug: string,
@@ -237,7 +240,7 @@ async function invalidateProjectCaches(
   try {
     const regionUrl = await resolveOrgRegion(orgSlug);
     await Promise.all([
-      invalidateCachedResponse(
+      invalidateCachedResponsesMatching(
         buildApiUrl(regionUrl, "projects", orgSlug, projectSlug)
       ),
       invalidateCachedResponsesMatching(
@@ -453,25 +456,73 @@ export async function findProjectByDsnKey(
 /**
  * Get a specific project.
  * Uses region-aware routing for multi-region support.
+ *
+ * Passes `?collapse=organization` so the server skips full-org
+ * serialization (~400-500ms faster). The response's `organization` field
+ * is trimmed to `{id, slug}` — no `name`, feature flags, or options.
+ * Callers needing a display name should use `resolveOrgDisplayName()`
+ * which falls back to the cached organizations list.
+ *
+ * Self-hosted or older Sentry versions that don't recognize `collapse`
+ * silently ignore the query param and return the full `organization`
+ * payload, so this is safe for all deployments.
  */
 export async function getProject(
   orgSlug: string,
   projectSlug: string
 ): Promise<SentryProject> {
   const config = await getOrgSdkConfig(orgSlug);
 
-  const result = await retrieveAProject({
+  // `collapse` is server-supported but not in the OpenAPI spec, so the
+  // SDK types `query` as `never` on `RetrieveAProjectData`. Double-cast
+  // via `unknown` to bypass the stricter argument type while still
+  // sending the param at runtime. Same intent as the `per_page` cast
+  // used above.
+  const result = (await retrieveAProject({
     ...config,
     path: {
       organization_id_or_slug: orgSlug,
       project_id_or_slug: projectSlug,
     },
-  });
+    query: { collapse: "organization" },
+  } as unknown as Parameters<typeof retrieveAProject>[0])) as
+    | { data: unknown; error: undefined }
+    | { data: undefined; error: unknown };
 
   const data = unwrapResult(result, "Failed to get project");
   return data as unknown as SentryProject;
 }
 
+/**
+ * Resolve an organization's display name from the best available source.
+ *
+ * `getProject()` passes `?collapse=organization` so the server skips
+ * full-org serialization (~400-500ms faster). Collapsed responses omit
+ * `organization.name`, so callers that want a human-friendly label must
+ * fall back to cached org metadata.
+ *
+ * Resolution order:
+ * 1. Explicit `name` if present (self-hosted or Sentry versions that
+ *    ignore the `collapse` query param still return the full payload).
+ * 2. The locally cached organizations list (populated by login and every
+ *    org-fanout operation).
+ * 3. The slug itself — always a valid human identifier, worst case.
+ *
+ * @param orgSlug - Organization slug (required for cache lookup)
+ * @param explicitName - The `organization.name` from an API response, if any
+ * @returns A display-ready organization name (never empty)
+ */
+export function resolveOrgDisplayName(
+  orgSlug: string,
+  explicitName?: string
+): string {
+  if (explicitName) {
+    return explicitName;
+  }
+  const cached = getCachedOrganizations().find((o) => o.slug === orgSlug);
+  return cached?.name ?? orgSlug;
+}
+
 /**
  * Get project keys (DSNs) for a project.
  * Uses region-aware routing for multi-region support.

src/lib/dsn/resolver.ts

@@ -9,6 +9,7 @@ import {
   findProjectByDsnKey,
   listOrganizations,
   listProjects,
+  resolveOrgDisplayName,
 } from "../api-client.js";
 import { getCachedDsn, updateCachedResolution } from "../db/dsn-cache.js";
 import { getDsnSourceDescription } from "./detector.js";
@@ -65,7 +66,10 @@ export async function resolveProject(
 
     const resolved: ResolvedProjectInfo = {
       orgSlug: project.organization.slug,
-      orgName: project.organization.name,
+      orgName: resolveOrgDisplayName(
+        project.organization.slug,
+        project.organization.name
+      ),
       projectSlug: project.slug,
       projectName: project.name,
     };

src/lib/formatters/human.ts

@@ -28,6 +28,7 @@ import type {
   TraceSpan,
   Writer,
 } from "../../types/index.js";
+import { resolveOrgDisplayName } from "../api-client.js";
 import { withSerializeSpan } from "../telemetry.js";
 import { type FixabilityTier, muted } from "./colors.js";
 import {
@@ -1537,9 +1538,13 @@ export function formatProjectDetails(
     kvRows.push(["Created", new Date(project.dateCreated).toLocaleString()]);
   }
   if (project.organization) {
+    const orgName = resolveOrgDisplayName(
+      project.organization.slug,
+      project.organization.name
+    );
     kvRows.push([
       "Organization",
-      `${escapeMarkdownInline(project.organization.name)} (${safeCodeSpan(project.organization.slug)})`,
+      `${escapeMarkdownInline(orgName)} (${safeCodeSpan(project.organization.slug)})`,
     ]);
   }
   if (project.firstEvent) {

src/lib/resolve-target.ts

@@ -24,6 +24,7 @@ import {
   getProject,
   listOrganizations,
   listProjects,
+  resolveOrgDisplayName,
 } from "./api-client.js";
 import { type ParsedOrgProject, parseOrgProjectArg } from "./arg-parsing.js";
 import { getDefaultOrganization, getDefaultProject } from "./db/defaults.js";
@@ -193,9 +194,13 @@ export async function resolveFromDsn(
   const projectInfo = await getProject(dsn.orgId, dsn.projectId);
 
   if (projectInfo.organization) {
+    const orgName = resolveOrgDisplayName(
+      projectInfo.organization.slug,
+      projectInfo.organization.name
+    );
     setCachedProject(dsn.orgId, dsn.projectId, {
       orgSlug: projectInfo.organization.slug,
-      orgName: projectInfo.organization.name,
+      orgName,
       projectSlug: projectInfo.slug,
       projectName: projectInfo.name,
       projectId: projectInfo.id,
@@ -205,7 +210,7 @@ export async function resolveFromDsn(
       org: projectInfo.organization.slug,
       project: projectInfo.slug,
       projectId: toNumericId(projectInfo.id),
-      orgDisplay: projectInfo.organization.name,
+      orgDisplay: orgName,
       projectDisplay: projectInfo.name,
       detectedFrom,
     };
@@ -333,9 +338,13 @@ export async function resolveDsnByPublicKey(
     }
 
     if (projectInfo.organization) {
+      const orgName = resolveOrgDisplayName(
+        projectInfo.organization.slug,
+        projectInfo.organization.name
+      );
       setCachedProjectByDsnKey(dsn.publicKey, {
         orgSlug: projectInfo.organization.slug,
-        orgName: projectInfo.organization.name,
+        orgName,
         projectSlug: projectInfo.slug,
         projectName: projectInfo.name,
         projectId: projectInfo.id,
@@ -345,7 +354,7 @@ export async function resolveDsnByPublicKey(
         org: projectInfo.organization.slug,
         project: projectInfo.slug,
         projectId: toNumericId(projectInfo.id),
-        orgDisplay: projectInfo.organization.name,
+        orgDisplay: orgName,
         projectDisplay: projectInfo.name,
         detectedFrom,
         packagePath: dsn.packagePath,
@@ -402,9 +411,13 @@ async function resolveDsnToTarget(
     const projectInfo = await getProject(orgId, dsnProjectId);
 
     if (projectInfo.organization) {
+      const orgName = resolveOrgDisplayName(
+        projectInfo.organization.slug,
+        projectInfo.organization.name
+      );
       setCachedProject(orgId, dsnProjectId, {
         orgSlug: projectInfo.organization.slug,
-        orgName: projectInfo.organization.name,
+        orgName,
         projectSlug: projectInfo.slug,
         projectName: projectInfo.name,
         projectId: projectInfo.id,
@@ -414,7 +427,7 @@ async function resolveDsnToTarget(
         org: projectInfo.organization.slug,
         project: projectInfo.slug,
         projectId: toNumericId(projectInfo.id),
-        orgDisplay: projectInfo.organization.name,
+        orgDisplay: orgName,
         projectDisplay: projectInfo.name,
         detectedFrom,
         packagePath,
@@ -880,7 +893,10 @@ export async function fetchProjectId(
     try {
       setCachedProject(project_.organization.id, project_.id, {
         orgSlug: project_.organization.slug,
-        orgName: project_.organization.name,
+        orgName: resolveOrgDisplayName(
+          project_.organization.slug,
+          project_.organization.name
+        ),
         projectSlug: project_.slug,
         projectName: project_.name,
         projectId: project_.id,

src/types/sentry.ts

@@ -58,11 +58,19 @@ export type SentryProject = Partial<SdkProjectListItem> & {
   id: string;
   slug: string;
   name: string;
-  /** Organization context (present in detail responses, absent in list) */
+  /**
+   * Organization context (present in detail responses, absent in list).
+   *
+   * `name` is optional because `getProject()` passes `?collapse=organization`
+   * to skip full-org serialization on the server (~400-500ms faster). The
+   * collapsed payload only carries `{id, slug}`. Callers needing a display
+   * name should use `resolveOrgDisplayName()` which falls back to the
+   * cached organizations list.
+   */
   organization?: {
     id: string;
     slug: string;
-    name: string;
+    name?: string;
     [key: string]: unknown;
   };
   /** Project status (returned by API but not in the OpenAPI spec) */