fix: proxy subcommand names from plural aliases instead of misinterpreting as targets

When `sentry projects list` passes "list" as a positional arg to the
project list command, it was interpreted as a project slug search,
producing confusing "No project 'list' found" errors.

Now all list commands intercept known subcommand names before parsing
the positional target. If a match is found, the target is treated as
auto-detect (as if no target was given) and a gentle hint is printed
to stderr: "Tip: use the singular form (e.g. `sentry project list`)."

The subcommand names are dynamically extracted from the Stricli route
map at runtime — no hardcoded lists. This keeps the set in sync as
commands are added or renamed.

Fixes CLI-7G

Author: BYK

src/commands/issue/list.ts

@@ -58,6 +58,7 @@ import {
   type ResolvedTarget,
   resolveAllTargets,
 } from "../../lib/resolve-target.js";
+import { interceptSubcommand } from "../../lib/route-subcommands.js";
 import { getApiBaseUrl } from "../../lib/sentry-client.js";
 import type {
   ProjectAliasEntry,
@@ -766,7 +767,8 @@ export const listCommand = buildCommand({
   ): Promise<void> {
     const { stdout, stderr, cwd, setContext } = this;
 
-    const parsed = parseOrgProjectArg(target);
+    const resolved = interceptSubcommand(target, stderr);
+    const parsed = parseOrgProjectArg(resolved);
 
     // Validate --limit range. Auto-pagination handles the API's 100-per-page
     // cap transparently, but we cap the total at MAX_LIMIT for practical CLI

src/commands/log/list.ts

@@ -20,6 +20,7 @@ import {
 } from "../../lib/formatters/index.js";
 import { TARGET_PATTERN_NOTE } from "../../lib/list-command.js";
 import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
+import { interceptSubcommand } from "../../lib/route-subcommands.js";
 import { getUpdateNotification } from "../../lib/version-check.js";
 import type { SentryLog, Writer } from "../../types/index.js";
 
@@ -297,8 +298,9 @@ export const listCommand = buildCommand({
     const { stdout, stderr, cwd, setContext } = this;
 
     // Resolve org/project from positional arg, config, or DSN auto-detection
+    const resolved = interceptSubcommand(target, stderr);
     const { org, project } = await resolveOrgProjectFromArg(
-      target,
+      resolved,
       cwd,
       COMMAND_NAME
     );

src/commands/project/list.ts

@@ -51,6 +51,7 @@ import {
   type ListCommandMeta,
 } from "../../lib/org-list.js";
 import { resolveAllTargets } from "../../lib/resolve-target.js";
+import { interceptSubcommand } from "../../lib/route-subcommands.js";
 import { getApiBaseUrl } from "../../lib/sentry-client.js";
 import type { SentryProject, Writer } from "../../types/index.js";
 
@@ -642,9 +643,10 @@ export const listCommand = buildCommand({
     flags: ListFlags,
     target?: string
   ): Promise<void> {
-    const { stdout, cwd } = this;
+    const { stdout, stderr, cwd } = this;
 
-    const parsed = parseOrgProjectArg(target);
+    const resolved = interceptSubcommand(target, stderr);
+    const parsed = parseOrgProjectArg(resolved);
 
     await dispatchOrgScopedList({
       config: projectListMeta,

src/commands/trace/list.ts

@@ -16,6 +16,7 @@ import {
 } from "../../lib/formatters/index.js";
 import { TARGET_PATTERN_NOTE } from "../../lib/list-command.js";
 import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
+import { interceptSubcommand } from "../../lib/route-subcommands.js";
 
 type ListFlags = {
   readonly limit: number;
@@ -123,11 +124,12 @@ export const listCommand = buildCommand({
     flags: ListFlags,
     target?: string
   ): Promise<void> {
-    const { stdout, cwd, setContext } = this;
+    const { stdout, stderr, cwd, setContext } = this;
 
     // Resolve org/project from positional arg, config, or DSN auto-detection
+    const resolved = interceptSubcommand(target, stderr);
     const { org, project } = await resolveOrgProjectFromArg(
-      target,
+      resolved,
       cwd,
       COMMAND_NAME
     );

src/lib/list-command.ts

@@ -18,6 +18,7 @@ import type { SentryContext } from "../context.js";
 import { parseOrgProjectArg } from "./arg-parsing.js";
 import { buildCommand, numberParser } from "./command.js";
 import { dispatchOrgScopedList, type OrgListConfig } from "./org-list.js";
+import { interceptSubcommand } from "./route-subcommands.js";
 
 // ---------------------------------------------------------------------------
 // Level A: shared parameter / flag definitions
@@ -173,8 +174,9 @@ export function buildOrgListCommand<TEntity, TWithOrg>(
       },
       target?: string
     ): Promise<void> {
-      const { stdout, cwd } = this;
-      const parsed = parseOrgProjectArg(target);
+      const { stdout, stderr, cwd } = this;
+      const resolved = interceptSubcommand(target, stderr);
+      const parsed = parseOrgProjectArg(resolved);
       await dispatchOrgScopedList({ config, stdout, cwd, flags, parsed });
     },
   });

src/lib/route-subcommands.ts

@@ -0,0 +1,87 @@
+/**
+ * Lazily extracts subcommand names from the Stricli route map.
+ *
+ * Used to detect when a user types `sentry projects list` where "list"
+ * is passed as a positional arg to the projects (→ project list) command.
+ * The set is derived dynamically from the actual route definitions so it
+ * stays in sync as commands are added or renamed.
+ *
+ * Uses lazy initialization to avoid circular dependency issues: this module
+ * lazily imports `routes` from `app.ts` on first call, after all modules
+ * have loaded.
+ */
+
+import { warning } from "./formatters/colors.js";
+
+let _subcommands: Set<string> | undefined;
+
+/**
+ * Return the set of subcommand names registered under any Stricli route map.
+ *
+ * Walks all top-level entries in the route map. For each entry that is itself
+ * a route map (has `getAllEntries`), collects its child command names.
+ *
+ * Cached after first call.
+ */
+export function getRouteSubcommands(): Set<string> {
+  if (_subcommands) {
+    return _subcommands;
+  }
+
+  // Lazy require to break the circular dependency:
+  // route-subcommands → app → commands → list-command → route-subcommands
+  const { routes } = require("../app.js") as {
+    routes: {
+      getAllEntries: () => readonly {
+        name: { original: string };
+        target: unknown;
+      }[];
+    };
+  };
+
+  _subcommands = new Set<string>();
+
+  for (const entry of routes.getAllEntries()) {
+    const target = entry.target as unknown as Record<string, unknown>;
+    if (typeof target?.getAllEntries === "function") {
+      const children = (
+        target.getAllEntries as () => readonly { name: { original: string } }[]
+      )();
+      for (const child of children) {
+        _subcommands.add(child.name.original);
+      }
+    }
+  }
+
+  return _subcommands;
+}
+
+/**
+ * Check if a positional target arg is actually a subcommand name (e.g.
+ * "list" from `sentry projects list`).
+ *
+ * When a plural alias like `sentry projects` maps directly to the list
+ * command, Stricli passes extra tokens as positional args. If the token
+ * matches a known subcommand name, we treat it as if no target was given
+ * (auto-detect) and print a gentle hint to stderr.
+ *
+ * @returns The original target, or `undefined` if it was a subcommand name.
+ */
+export function interceptSubcommand(
+  target: string | undefined,
+  stderr: { write(s: string): void }
+): string | undefined {
+  if (!target) {
+    return target;
+  }
+  const trimmed = target.trim();
+  if (trimmed && getRouteSubcommands().has(trimmed)) {
+    stderr.write(
+      warning(
+        `Tip: use the singular form (e.g. \`sentry project ${trimmed}\`) for subcommands.\n`
+      )
+    );
+    return;
+  }
+  return target;
+}

test/lib/route-subcommands.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Tests for route-subcommands and interceptSubcommand.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { interceptSubcommand } from "../../src/lib/route-subcommands.js";
+import { getRouteSubcommands } from "../../src/lib/route-subcommands.js";
+
+describe("getRouteSubcommands", () => {
+  test("returns a non-empty set", () => {
+    const subs = getRouteSubcommands();
+    expect(subs.size).toBeGreaterThan(0);
+  });
+
+  test("contains known subcommand names from routes", () => {
+    const subs = getRouteSubcommands();
+    // These exist because issue route has list/view/explain/plan
+    expect(subs.has("list")).toBe(true);
+    expect(subs.has("view")).toBe(true);
+    expect(subs.has("explain")).toBe(true);
+    expect(subs.has("plan")).toBe(true);
+  });
+
+  test("does not contain top-level command names", () => {
+    const subs = getRouteSubcommands();
+    expect(subs.has("issue")).toBe(false);
+    expect(subs.has("project")).toBe(false);
+    expect(subs.has("api")).toBe(false);
+  });
+
+  test("returns the same cached set on repeat calls", () => {
+    const a = getRouteSubcommands();
+    const b = getRouteSubcommands();
+    expect(a).toBe(b);
+  });
+});
+
+describe("interceptSubcommand", () => {
+  function makeStderr(): { write(s: string): void; output: string } {
+    let output = "";
+    return {
+      write(s: string) {
+        output += s;
+      },
+      get output() {
+        return output;
+      },
+    };
+  }
+
+  test("returns undefined and writes hint for known subcommand", () => {
+    const stderr = makeStderr();
+    const result = interceptSubcommand("list", stderr);
+    expect(result).toBeUndefined();
+    expect(stderr.output).toContain("Tip:");
+    expect(stderr.output).toContain("singular form");
+  });
+
+  test("returns target unchanged for normal project names", () => {
+    const stderr = makeStderr();
+    const result = interceptSubcommand("my-project", stderr);
+    expect(result).toBe("my-project");
+    expect(stderr.output).toBe("");
+  });
+
+  test("returns target unchanged for org/project patterns", () => {
+    const stderr = makeStderr();
+    const result = interceptSubcommand("sentry/cli", stderr);
+    expect(result).toBe("sentry/cli");
+    expect(stderr.output).toBe("");
+  });
+
+  test("returns undefined/empty unchanged (no hint)", () => {
+    const stderr = makeStderr();
+    expect(interceptSubcommand(undefined, stderr)).toBeUndefined();
+    expect(stderr.output).toBe("");
+
+    expect(interceptSubcommand("", stderr)).toBe("");
+    expect(stderr.output).toBe("");
+  });
+
+  test("includes the subcommand name in the hint", () => {
+    const stderr = makeStderr();
+    interceptSubcommand("view", stderr);
+    expect(stderr.output).toContain("view");
+  });
+
+  test("handles 'explain' and 'plan' subcommands", () => {
+    const stderr1 = makeStderr();
+    expect(interceptSubcommand("explain", stderr1)).toBeUndefined();
+    expect(stderr1.output).toContain("Tip:");
+
+    const stderr2 = makeStderr();
+    expect(interceptSubcommand("plan", stderr2)).toBeUndefined();
+    expect(stderr2.output).toContain("Tip:");
+  });
+});