refactor: generalize org listing cache into listOrganizations itself

Instead of patching findProjectsBySlug with a per-callsite cache check,
move the caching into listOrganizations() so all 12 callers benefit:

- Add org_name column to org_regions table (schema v9)
- Split listOrganizations into cached + uncached variants:
  - listOrganizations() returns from SQLite cache when populated
  - listOrganizationsUncached() always hits the API (for org list,
    auth status, resolveEffectiveOrg)
- Add getCachedOrganizations() to db/regions.ts
- Simplify findProjectsBySlug back to single-path (no getAllOrgRegions
  fast-path needed — listOrganizations handles it)
- Update org list and auth status to use uncached variant
- Update resolveEffectiveOrg to use uncached (it explicitly refreshes)

Author: BYK

AGENTS.md

@@ -5,7 +5,7 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { listOrganizations } from "../../lib/api-client.js";
+import { listOrganizationsUncached } from "../../lib/api-client.js";
 import { buildCommand } from "../../lib/command.js";
 import {
   type AuthConfig,
@@ -124,7 +124,7 @@ async function collectDefaults(): Promise<AuthStatusData["defaults"]> {
  */
 async function verifyCredentials(): Promise<AuthStatusData["verification"]> {
   try {
-    const orgs = await listOrganizations();
+    const orgs = await listOrganizationsUncached();
     return {
       success: true,
       organizations: orgs.map((o) => ({ name: o.name, slug: o.slug })),

src/commands/auth/status.ts

@@ -5,7 +5,7 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { listOrganizations } from "../../lib/api-client.js";
+import { listOrganizationsUncached } from "../../lib/api-client.js";
 import { buildCommand } from "../../lib/command.js";
 import { DEFAULT_SENTRY_HOST } from "../../lib/constants.js";
 import { getAllOrgRegions } from "../../lib/db/regions.js";
@@ -130,7 +130,7 @@ export const listCommand = buildCommand({
   async *func(this: SentryContext, flags: ListFlags) {
     applyFreshFlag(flags);
 
-    const orgs = await listOrganizations();
+    const orgs = await listOrganizationsUncached();
     const limitedOrgs = orgs.slice(0, flags.limit);
 
     // Check if user has orgs in multiple regions

src/commands/org/list.ts

@@ -56,6 +56,7 @@ export {
   getUserRegions,
   listOrganizations,
   listOrganizationsInRegion,
+  listOrganizationsUncached,
 } from "./api/organizations.js";
 export {
   createProject,

src/lib/api-client.ts

@@ -65,11 +65,44 @@ export async function listOrganizationsInRegion(
 }
 
 /**
- * List all organizations the user has access to across all regions.
- * Performs a fan-out to each region and combines results.
- * Also caches the region URL for each organization.
+ * List all organizations, returning cached data when available.
+ *
+ * On first call (cold cache), fetches from the API and populates the cache.
+ * On subsequent calls, returns organizations from the SQLite cache without
+ * any HTTP requests. This avoids the expensive getUserRegions() +
+ * listOrganizationsInRegion() fan-out (~800ms) on every command.
+ *
+ * Callers that need guaranteed-fresh data (e.g., `org list`, `auth status`)
+ * should use {@link listOrganizationsUncached} instead.
  */
 export async function listOrganizations(): Promise<SentryOrganization[]> {
+  const { getCachedOrganizations } = await import("../db/regions.js");
+
+  const cached = await getCachedOrganizations();
+  if (cached.length > 0) {
+    return cached.map((org) => ({
+      id: org.id,
+      slug: org.slug,
+      name: org.name,
+    }));
+  }
+
+  // Cache miss — fetch from API (also populates cache for next time)
+  return listOrganizationsUncached();
+}
+
+/**
+ * List all organizations by fetching from the API, bypassing the cache.
+ *
+ * Performs a fan-out to each region and combines results.
+ * Populates the org_regions cache with slug, region URL, org ID, and org name.
+ *
+ * Use this when you need guaranteed-fresh data (e.g., `org list`, `auth status`).
+ * Most callers should use {@link listOrganizations} instead.
+ */
+export async function listOrganizationsUncached(): Promise<
+  SentryOrganization[]
+> {
   const { setOrgRegions } = await import("../db/regions.js");
 
   // Self-hosted instances may not have the regions endpoint (404)
@@ -102,6 +135,7 @@ export async function listOrganizations(): Promise<SentryOrganization[]> {
     slug: r.org.slug,
     regionUrl: r.regionUrl,
     orgId: r.org.id,
+    orgName: r.org.name,
   }));
   await setOrgRegions(regionEntries);
 

src/lib/api/organizations.ts

@@ -18,7 +18,6 @@ import type {
   SentryProject,
 } from "../../types/index.js";
 
-import { getAllOrgRegions } from "../db/regions.js";
 import { type AuthGuardSuccess, withAuthGuard } from "../errors.js";
 import { logger } from "../logger.js";
 import { getApiBaseUrl } from "../sentry-client.js";
@@ -179,62 +178,35 @@ export async function findProjectsBySlug(
 ): Promise<ProjectSearchResult> {
   const isNumericId = isAllDigits(projectSlug);
 
-  /** Search for the project in a list of org slugs (parallel getProject per org). */
-  const searchOrgs = (orgSlugs: string[]) =>
-    Promise.all(
-      orgSlugs.map((orgSlug) =>
-        withAuthGuard(async () => {
-          const project = await getProject(orgSlug, projectSlug);
-          // The API accepts project_id_or_slug, so a numeric input could
-          // 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 };
-        })
-      )
-    );
-
-  const extractProjects = (
-    results: Awaited<ReturnType<typeof searchOrgs>>
-  ): ProjectWithOrg[] =>
-    results
-      .filter((r): r is AuthGuardSuccess<ProjectWithOrg | null> => r.ok)
-      .map((r) => r.value)
-      .filter((v): v is ProjectWithOrg => v !== null);
-
-  // Fast path: use cached org slugs to skip the expensive listOrganizations()
-  // round-trip (getUserRegions + listOrganizationsInRegion).
-  // The cache is expected to be complete: callers reach this function via the
-  // project-search format (e.g. "buybridge-5BS") whose short suffix only comes
-  // from `sentry issue list` output — which already called listOrganizations()
-  // and populated org_regions with all accessible orgs.
-  const cachedOrgRegions = await getAllOrgRegions();
-  const cachedSlugs = [...cachedOrgRegions.keys()];
-  if (cachedSlugs.length > 0) {
-    const cachedResults = await searchOrgs(cachedSlugs);
-    const cachedProjects = extractProjects(cachedResults);
-    if (cachedProjects.length > 0) {
-      return { projects: cachedProjects, orgs: [] };
-    }
-    // Fall through: project might be in a new org not yet cached
-  }
-
-  // Full listing: fetch all orgs from API, then skip already-searched cached orgs
+  // listOrganizations() returns from cache when populated, avoiding
+  // the expensive getUserRegions() + listOrganizationsInRegion() fan-out.
   const orgs = await listOrganizations();
-  const cachedSet = new Set(cachedSlugs);
-  const newOrgSlugs = orgs
-    .filter((o) => !cachedSet.has(o.slug))
-    .map((o) => o.slug);
-  const searchResults = await searchOrgs(newOrgSlugs);
+
+  // Direct lookup in parallel — one API call per org instead of paginating all projects
+  const searchResults = await Promise.all(
+    orgs.map((org) =>
+      withAuthGuard(async () => {
+        const project = await getProject(org.slug, projectSlug);
+        // The API accepts project_id_or_slug, so a numeric input could
+        // 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 };
+      })
+    )
+  );
 
   return {
-    projects: extractProjects(searchResults),
+    projects: searchResults
+      .filter((r): r is AuthGuardSuccess<ProjectWithOrg | null> => r.ok)
+      .map((r) => r.value)
+      .filter((v): v is ProjectWithOrg => v !== null),
     orgs,
   };
 }

src/lib/api/projects.ts

@@ -18,15 +18,17 @@ const TABLE = "org_regions";
 type OrgRegionRow = {
   org_slug: string;
   org_id: string | null;
+  org_name: string | null;
   region_url: string;
   updated_at: number;
 };
 
-/** Entry for batch-caching org regions with optional numeric ID. */
+/** Entry for batch-caching org regions with optional metadata. */
 export type OrgRegionEntry = {
   slug: string;
   regionUrl: string;
   orgId?: string;
+  orgName?: string;
 };
 
 /**
@@ -119,6 +121,9 @@ export async function setOrgRegions(entries: OrgRegionEntry[]): Promise<void> {
       if (entry.orgId) {
         row.org_id = entry.orgId;
       }
+      if (entry.orgName) {
+        row.org_name = entry.orgName;
+      }
       runUpsert(db, TABLE, row, ["org_slug"]);
     }
   })();
@@ -147,3 +152,35 @@ export async function getAllOrgRegions(): Promise<Map<string, string>> {
 
   return new Map(rows.map((row) => [row.org_slug, row.region_url]));
 }
+
+/** Cached org entry with the fields needed to reconstruct a SentryOrganization. */
+export type CachedOrg = {
+  slug: string;
+  id: string;
+  name: string;
+};
+
+/**
+ * Get all cached organizations with id, slug, and name.
+ *
+ * Returns organizations that have all three fields populated in the cache.
+ * Rows with missing `org_id` or `org_name` (from before schema v9) are
+ * excluded — callers should fall back to the API when the result is empty.
+ *
+ * @returns Array of cached org entries, or empty if cache is cold/incomplete
+ */
+export async function getCachedOrganizations(): Promise<CachedOrg[]> {
+  const db = getDatabase();
+  const rows = db
+    .query(
+      `SELECT org_slug, org_id, org_name FROM ${TABLE} WHERE org_id IS NOT NULL AND org_name IS NOT NULL`
+    )
+    .all() as Pick<OrgRegionRow, "org_slug" | "org_id" | "org_name">[];
+
+  return rows.map((row) => ({
+    slug: row.org_slug,
+    // org_id and org_name are guaranteed non-null by the WHERE clause
+    id: row.org_id as string,
+    name: row.org_name as string,
+  }));
+}

src/lib/db/regions.ts

@@ -15,7 +15,7 @@ import type { Database } from "bun:sqlite";
 import { stringifyUnknown } from "../errors.js";
 import { logger } from "../logger.js";
 
-export const CURRENT_SCHEMA_VERSION = 8;
+export const CURRENT_SCHEMA_VERSION = 9;
 
 /** Environment variable to disable auto-repair */
 const NO_AUTO_REPAIR_ENV = "SENTRY_CLI_NO_AUTO_REPAIR";
@@ -166,6 +166,7 @@ export const TABLE_SCHEMAS: Record<string, TableSchema> = {
     columns: {
       org_slug: { type: "TEXT", primaryKey: true },
       org_id: { type: "TEXT", addedInVersion: 8 },
+      org_name: { type: "TEXT", addedInVersion: 9 },
       region_url: { type: "TEXT", notNull: true },
       updated_at: {
         type: "INTEGER",
@@ -721,6 +722,11 @@ export function runMigrations(db: Database): void {
     addColumnIfMissing(db, "org_regions", "org_id", "TEXT");
   }
 
+  // Migration 8 -> 9: Add org_name column to org_regions for cached org listing
+  if (currentVersion < 9) {
+    addColumnIfMissing(db, "org_regions", "org_name", "TEXT");
+  }
+
   if (currentVersion < CURRENT_SCHEMA_VERSION) {
     db.query("UPDATE schema_version SET version = ?").run(
       CURRENT_SCHEMA_VERSION

src/lib/db/schema.ts

@@ -162,13 +162,13 @@ export async function resolveEffectiveOrg(orgSlug: string): Promise<string> {
     return fromCache;
   }
 
-  // Cache is cold or identifier is unknown — refresh the org list.
-  // listOrganizations() populates org_regions with slug, region, and org_id.
+  // Cache is cold or identifier is unknown — refresh the org list from API.
+  // listOrganizationsUncached() populates org_regions with slug, region, org_id, and name.
   // Any error (auth failure, network error, etc.) falls back to the original
   // slug; the downstream API call will produce a relevant error if needed.
   try {
-    const { listOrganizations } = await import("./api-client.js");
-    await listOrganizations();
+    const { listOrganizationsUncached } = await import("./api-client.js");
+    await listOrganizationsUncached();
   } catch {
     return orgSlug;
   }

src/lib/region.ts

@@ -81,7 +81,7 @@ describe("statusCommand.func", () => {
     getDefaultOrgSpy = spyOn(dbDefaults, "getDefaultOrganization");
     getDefaultProjectSpy = spyOn(dbDefaults, "getDefaultProject");
     getDbPathSpy = spyOn(dbIndex, "getDbPath");
-    listOrgsSpy = spyOn(apiClient, "listOrganizations");
+    listOrgsSpy = spyOn(apiClient, "listOrganizationsUncached");
 
     // Defaults that most tests override
     getUserInfoSpy.mockReturnValue(null);