fix: add org-slug pre-check to dispatchOrgScopedList (CLI-9A) (#485)

## Problem

When a user runs `sentry project list ftmo` (intending to list projects
in org "ftmo"), the CLI classifies the bare slug as a project-search and
makes N API calls to `getProject()` across all orgs. When no project
matches, it throws a confusing `ContextError: Project is required` — 190
occurrences affecting 98 users
([CLI-9A](https://sentry.sentry.io/issues/CLI-9A)).

## Fix

Adds a centralized org-cache pre-check in `dispatchOrgScopedList` via a
new `orgSlugMatchBehavior` option on `DispatchOptions`:

- **`"redirect"`**: Convert to org-all mode with a warning (used by
`project list`, `team list`, `repo list`)
- **`"error"`**: Throw a `ResolutionError` with actionable hints (for
commands like `issue list` that can't auto-redirect)
- **`undefined`** (default): No pre-check — fully backward compatible

The check uses SQLite-cached orgs (`getCachedOrganizations()`) so it's
O(1) and avoids the expensive N API calls entirely. If the cache is
cold/stale, falls through to the handler's own org-slug check as a
safety net.

### Why centralize instead of patching individual handlers?

The bug existed because `project/list.ts` had a custom
`handleProjectSearch` that was missing the org-match check present in
the shared handler (`org-list.ts`). By moving the check into
`dispatchOrgScopedList` itself, no handler can forget it.

## Changes

- `src/lib/org-list.ts` — `orgSlugMatchBehavior` option +
`resolveOrgSlugMatch()` helper
- `src/commands/project/list.ts` — Opt in with `orgSlugMatchBehavior:
"redirect"`
- `src/lib/list-command.ts` — Opt in for `buildOrgListCommand` commands
(team/repo list)
- `AGENTS.md` — Document the pattern for future list commands
- `test/lib/org-list.test.ts` — 6 new tests covering redirect, error,
fallthrough, and cache-miss scenarios

Fixes CLI-9A

Author: BYK

AGENTS.md

@@ -469,6 +469,7 @@ Key rules when writing overrides:
 - Commands with extra fields (e.g., `stderr`, `setContext`) spread the context and add them: `(ctx) => handle({ ...ctx, flags, stderr, setContext })`. Override `ctx.flags` with the command-specific flags type when needed.
 - `resolveCursor()` must be called **inside** the `org-all` override closure, not before `dispatchOrgScopedList`, so that `--cursor` validation errors fire correctly for non-org-all modes.
 - `handleProjectSearch` errors must use `"Project"` as the `ContextError` resource, not `config.entityName`.
+- Always set `orgSlugMatchBehavior` on `dispatchOrgScopedList` to declare how bare-slug org matches are handled. Use `"redirect"` for commands where listing all entities in the org makes sense (e.g., `project list`, `team list`). Use `"error"` for commands with custom per-project logic that can't auto-redirect (e.g., `issue list`). The pre-check uses cached orgs to avoid N API calls — individual handlers don't need their own org-slug fallback.
 
 3. **Standalone list commands** (e.g., `span list`, `trace list`) that don't use org-scoped dispatch wire pagination directly in `func()`. See the "List Command Pagination" section above for the pattern.
 

src/commands/project/list.ts

@@ -644,6 +644,7 @@ export const listCommand = buildListCommand("project", {
       cwd,
       flags,
       parsed,
+      orgSlugMatchBehavior: "redirect",
       overrides: {
         "auto-detect": (ctx) => handleAutoDetect(ctx.cwd, flags),
         explicit: (ctx) =>

src/lib/list-command.ts

@@ -579,6 +579,7 @@ export function buildOrgListCommand<TEntity, TWithOrg>(
         cwd,
         flags,
         parsed,
+        orgSlugMatchBehavior: "redirect",
       });
       yield new CommandOutput(result);
       // Only forward hint to the footer when items exist — empty results

src/lib/org-list.ts

@@ -839,8 +839,63 @@ export type DispatchOptions<TEntity = unknown, TWithOrg = unknown> = {
    * `issue list`) can list those mode types here to bypass the guard.
    */
   allowCursorInModes?: readonly ParsedOrgProject["type"][];
+  /**
+   * Behavior when a project-search slug matches a cached organization.
+   *
+   * Before cursor validation and handler dispatch, the dispatcher checks
+   * whether the bare slug matches a cached org. This prevents commands
+   * from accidentally treating an org slug as a project name.
+   *
+   * - `"redirect"` (default): Convert to org-all mode with a warning log.
+   *   The existing org-all handler runs naturally.
+   * - `"error"`: Throw a {@link ResolutionError} with actionable hints.
+   *   Use this when org-all redirect is inappropriate (e.g., issue list
+   *   has custom per-project query logic that doesn't support org-all).
+   *
+   * Cache-only: if the cache is cold or stale, the check is skipped and
+   * the handler's own org-slug check serves as a safety net.
+   */
+  orgSlugMatchBehavior?: "redirect" | "error";
 };
 
+/**
+ * Pre-check: when a bare slug matches a cached organization, redirect to
+ * org-all mode or throw an error before handler dispatch. This prevents
+ * commands from accidentally treating an org slug as a project name (CLI-9A).
+ *
+ * Cache-only: if the cache is cold or stale, returns the original parsed
+ * value and the handler's own org-slug check serves as a safety net.
+ */
+async function resolveOrgSlugMatch(
+  parsed: ParsedOrgProject & { type: "project-search" },
+  behavior: "redirect" | "error",
+  config: ListCommandMeta
+): Promise<ParsedOrgProject> {
+  const slug = parsed.projectSlug;
+  const { getCachedOrganizations } = await import("./db/regions.js");
+  const cachedOrgs = await getCachedOrganizations();
+  const matchingOrg = cachedOrgs.find((o) => o.slug === slug);
+  if (!matchingOrg) {
+    return parsed;
+  }
+  if (behavior === "error") {
+    throw new ResolutionError(
+      `'${slug}'`,
+      "is an organization, not a project",
+      `${config.commandPrefix} ${slug}/`,
+      [
+        `List projects: sentry project list ${slug}/`,
+        `Specify a project: ${config.commandPrefix} ${slug}/<project>`,
+      ]
+    );
+  }
+  log.warn(
+    `'${slug}' is an organization, not a project. ` +
+      `Listing all ${config.entityPlural} in '${slug}'.`
+  );
+  return { type: "org-all", org: matchingOrg.slug };
+}
+
 /**
  * Validate the cursor flag and dispatch to the correct mode handler.
  *
@@ -859,14 +914,27 @@ export async function dispatchOrgScopedList<TEntity, TWithOrg>(
 ): Promise<ListResult<any>> {
   const { config, cwd, flags, parsed, overrides } = options;
 
+  let effectiveParsed: ParsedOrgProject = parsed;
+
+  if (
+    effectiveParsed.type === "project-search" &&
+    options.orgSlugMatchBehavior
+  ) {
+    effectiveParsed = await resolveOrgSlugMatch(
+      effectiveParsed,
+      options.orgSlugMatchBehavior,
+      config
+    );
+  }
+
   const cursorAllowedModes: readonly ParsedOrgProject["type"][] = [
     "org-all",
     ...(options.allowCursorInModes ?? []),
   ];
-  if (flags.cursor && !cursorAllowedModes.includes(parsed.type)) {
+  if (flags.cursor && !cursorAllowedModes.includes(effectiveParsed.type)) {
     const hint =
-      parsed.type === "project-search"
-        ? `\n\nDid you mean '${config.commandPrefix} ${parsed.projectSlug}/'? ` +
+      effectiveParsed.type === "project-search"
+        ? `\n\nDid you mean '${config.commandPrefix} ${effectiveParsed.projectSlug}/'? ` +
           `A bare name searches for a project — add a trailing slash to list an org's ${config.entityPlural}.`
         : "";
     throw new ValidationError(
@@ -877,11 +945,13 @@ export async function dispatchOrgScopedList<TEntity, TWithOrg>(
     );
   }
 
-  let effectiveParsed: ParsedOrgProject = parsed;
-  if (parsed.type === "explicit" || parsed.type === "org-all") {
-    const effectiveOrg = await resolveEffectiveOrg(parsed.org);
-    if (effectiveOrg !== parsed.org) {
-      effectiveParsed = { ...parsed, org: effectiveOrg };
+  if (
+    effectiveParsed.type === "explicit" ||
+    effectiveParsed.type === "org-all"
+  ) {
+    const effectiveOrg = await resolveEffectiveOrg(effectiveParsed.org);
+    if (effectiveOrg !== effectiveParsed.org) {
+      effectiveParsed = { ...effectiveParsed, org: effectiveOrg };
     }
   }
 

test/lib/org-list.test.ts

@@ -21,6 +21,8 @@ import * as apiClient from "../../src/lib/api-client.js";
 import * as defaults from "../../src/lib/db/defaults.js";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
 import * as paginationDb from "../../src/lib/db/pagination.js";
+// biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
+import * as regions from "../../src/lib/db/regions.js";
 import {
   AuthError,
   ResolutionError,
@@ -901,4 +903,171 @@ describe("dispatchOrgScopedList", () => {
     localSetPaginationSpy.mockRestore();
     localClearPaginationSpy.mockRestore();
   });
+
+  // -------------------------------------------------------------------------
+  // orgSlugMatchBehavior pre-check
+  // -------------------------------------------------------------------------
+
+  describe("orgSlugMatchBehavior", () => {
+    let getCachedOrgsSpy: ReturnType<typeof spyOn>;
+
+    beforeEach(() => {
+      getCachedOrgsSpy = spyOn(
+        regions,
+        "getCachedOrganizations"
+      ).mockResolvedValue([]);
+    });
+
+    afterEach(() => {
+      getCachedOrgsSpy.mockRestore();
+    });
+
+    test("redirect converts project-search to org-all when slug matches cached org", async () => {
+      getCachedOrgsSpy.mockResolvedValue([
+        { slug: "acme-corp", id: "1", name: "Acme Corp" },
+      ]);
+
+      const items: FakeEntity[] = [{ id: "1", name: "Widget A" }];
+      const config = makeConfig({
+        listPaginated: mock(() =>
+          Promise.resolve({ data: items, nextCursor: undefined })
+        ),
+      });
+
+      const result = await dispatchOrgScopedList({
+        config,
+        cwd: "/tmp",
+        flags: { limit: 10, json: true },
+        parsed: { type: "project-search", projectSlug: "acme-corp" },
+        orgSlugMatchBehavior: "redirect",
+      });
+
+      // Should have redirected to org-all → listPaginated called
+      expect(config.listPaginated).toHaveBeenCalled();
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0].orgSlug).toBe("acme-corp");
+    });
+
+    test("error throws ResolutionError when slug matches cached org", async () => {
+      getCachedOrgsSpy.mockResolvedValue([
+        { slug: "acme-corp", id: "1", name: "Acme Corp" },
+      ]);
+
+      const config = makeConfig();
+
+      await expect(
+        dispatchOrgScopedList({
+          config,
+          cwd: "/tmp",
+          flags: { limit: 10, json: false },
+          parsed: { type: "project-search", projectSlug: "acme-corp" },
+          orgSlugMatchBehavior: "error",
+        })
+      ).rejects.toThrow(ResolutionError);
+    });
+
+    test("error message includes actionable hints", async () => {
+      getCachedOrgsSpy.mockResolvedValue([
+        { slug: "acme-corp", id: "1", name: "Acme Corp" },
+      ]);
+
+      const config = makeConfig();
+
+      try {
+        await dispatchOrgScopedList({
+          config,
+          cwd: "/tmp",
+          flags: { limit: 10, json: false },
+          parsed: { type: "project-search", projectSlug: "acme-corp" },
+          orgSlugMatchBehavior: "error",
+        });
+        expect.unreachable("should have thrown");
+      } catch (e) {
+        expect(e).toBeInstanceOf(ResolutionError);
+        const err = e as ResolutionError;
+        expect(err.message).toContain("is an organization, not a project");
+        expect(err.message).toContain("acme-corp/");
+      }
+    });
+
+    test("no orgSlugMatchBehavior skips pre-check and calls handler", async () => {
+      getCachedOrgsSpy.mockResolvedValue([
+        { slug: "acme-corp", id: "1", name: "Acme Corp" },
+      ]);
+
+      const handler = mock(() =>
+        Promise.resolve({ items: [] } as ListResult<FakeWithOrg>)
+      );
+
+      await dispatchOrgScopedList({
+        config: META_ONLY,
+        cwd: "/tmp",
+        flags: { limit: 10, json: false },
+        parsed: { type: "project-search", projectSlug: "acme-corp" },
+        overrides: {
+          "auto-detect": handler,
+          explicit: handler,
+          "project-search": handler,
+          "org-all": handler,
+        },
+      });
+
+      // Without orgSlugMatchBehavior, the project-search handler runs
+      expect(handler).toHaveBeenCalledTimes(1);
+      // getCachedOrganizations should NOT have been called
+      expect(getCachedOrgsSpy).not.toHaveBeenCalled();
+    });
+
+    test("redirect with no cache match falls through to project-search handler", async () => {
+      getCachedOrgsSpy.mockResolvedValue([
+        { slug: "other-org", id: "2", name: "Other Org" },
+      ]);
+
+      const handler = mock(() =>
+        Promise.resolve({ items: [] } as ListResult<FakeWithOrg>)
+      );
+
+      await dispatchOrgScopedList({
+        config: META_ONLY,
+        cwd: "/tmp",
+        flags: { limit: 10, json: false },
+        parsed: { type: "project-search", projectSlug: "acme-corp" },
+        orgSlugMatchBehavior: "redirect",
+        overrides: {
+          "auto-detect": handler,
+          explicit: handler,
+          "project-search": handler,
+          "org-all": handler,
+        },
+      });
+
+      // No cache match → project-search handler still called
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    test("redirect with empty cache falls through to project-search handler", async () => {
+      getCachedOrgsSpy.mockResolvedValue([]);
+
+      const handler = mock(() =>
+        Promise.resolve({ items: [] } as ListResult<FakeWithOrg>)
+      );
+
+      await dispatchOrgScopedList({
+        config: META_ONLY,
+        cwd: "/tmp",
+        flags: { limit: 10, json: false },
+        parsed: { type: "project-search", projectSlug: "acme-corp" },
+        orgSlugMatchBehavior: "redirect",
+        overrides: {
+          "auto-detect": handler,
+          explicit: handler,
+          "project-search": handler,
+          "org-all": handler,
+        },
+      });
+
+      // Empty cache → project-search handler still called
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
 });