fix: improve argument parsing for common user mistakes

Address 5 ResolutionError patterns from production Sentry issues:

- CLI-BG: Detect swapped view args (ID first, target second) and
  auto-correct with warning
- CLI-BB: Parse multi-slash args like org/project/issueId correctly
- CLI-BA: Normalize underscores to hyphens in project/org slugs
- CLI-B9: Auto-redirect to org-all when bare slug matches an org name
- CLI-B8: Detect issue short IDs in event/log/trace view and suggest
  the correct command

Technical changes:
- Add detectSwappedViewArgs(), looksLikeIssueShortId(), normalizeSlug()
  helpers to arg-parsing.ts
- Add parseMultiSlashIssueArg() for org/project/id patterns
- Change findProjectsBySlug() to return { projects, orgs } (was bare
  array) to enable org-slug matching without extra API calls
- Add orgAllFallback option to handleProjectSearch for auto-redirect
- Remove stderr parameter from resolveProjectBySlug and related
  functions — use Consola logger instead
- Update all view commands (event, log, trace) with swap detection
  and issue-short-ID suggestions

All 2726 unit tests pass. Typecheck and lint clean.

Author: BYK

AGENTS.md

@@ -648,6 +648,9 @@ mock.module("./some-module", () => ({
 
 ### Decision
 
+<!-- lore:019cc2ef-9be5-722d-bc9f-b07a8197eeed -->
+* **All view subcommands should use \<target> \<id> positional pattern**: All \`\* view\` subcommands (\`event view\`, \`log view\`, \`trace view\`, etc.) should follow a consistent \`\<target> \<id>\` positional argument pattern where target is the optional \`org/project\` specifier. During migration, use opportunistic argument swapping with a stderr warning when the user provides args in the wrong order. This follows the CLI UX auto-correction pattern: safe when input is already invalid, no ambiguity, and warning goes to stderr.
+
 <!-- lore:019c99d5-69f2-74eb-8c86-411f8512801d -->
 * **Raw markdown output for non-interactive terminals, rendered for TTY**: Markdown-first output pipeline: custom renderer in \`src/lib/formatters/markdown.ts\` walks \`marked\` tokens to produce ANSI-styled output. Commands build CommonMark using helpers (\`mdKvTable()\`, \`mdRow()\`, \`colorTag()\`, \`escapeMarkdownCell()\`, \`safeCodeSpan()\`) and pass through \`renderMarkdown()\`. \`isPlainOutput()\` precedence: \`SENTRY\_PLAIN\_OUTPUT\` > \`NO\_COLOR\` > \`FORCE\_COLOR\` > \`!isTTY\`. \`--json\` always outputs JSON. Colors defined in \`COLORS\` object in \`colors.ts\`. Tests run non-TTY so assertions match raw CommonMark; use \`stripAnsi()\` helper for rendered-mode assertions.
 
@@ -677,13 +680,16 @@ mock.module("./some-module", () => ({
 <!-- lore:019c9741-d78e-73b1-87c2-e360ef6c7475 -->
 * **useTestConfigDir without isolateProjectRoot causes DSN scanning of repo tree**: \`useTestConfigDir()\` creates temp dirs under \`.test-tmp/\` in the repo tree. Without \`{ isolateProjectRoot: true }\`, \`findProjectRoot\` walks up and finds the repo's \`.git\`, causing DSN detection to scan real source code and trigger network calls against test mocks (timeouts). Always pass \`isolateProjectRoot: true\` when tests exercise \`resolveOrg\`, \`detectDsn\`, or \`findProjectRoot\`.
 
+<!-- lore:019cc303-e397-75b9-9762-6f6ad108f50a -->
+* **Zod z.coerce.number() converts null to 0 silently**: Zod gotchas in this codebase: (1) \`z.coerce.number()\` passes input through \`Number()\`, so \`null\` silently becomes \`0\`. Be aware if \`null\` vs \`0\` distinction matters. (2) Zod v4 \`.default({})\` short-circuits — it returns the default value without parsing through inner schema defaults. So \`.object({ enabled: z.boolean().default(true) }).default({})\` returns \`{}\`, not \`{ enabled: true }\`. Fix: provide fully-populated default objects. This affected nested config sections in src/config.ts during the v3→v4 upgrade.
+
 ### Pattern
 
 <!-- lore:019c972c-9f11-7c0d-96ce-3f8cc2641175 -->
 * **Org-scoped SDK calls follow getOrgSdkConfig + unwrapResult pattern**: All org-scoped API calls in src/lib/api-client.ts: (1) call \`getOrgSdkConfig(orgSlug)\` for regional URL + SDK config, (2) spread into SDK function: \`{ ...config, path: { organization\_id\_or\_slug: orgSlug, ... } }\`, (3) pass to \`unwrapResult(result, errorContext)\`. Shared helpers \`resolveAllTargets\`/\`resolveOrgAndProject\` must NOT call \`fetchProjectId\` — commands that need it enrich targets themselves.
 
 <!-- lore:5ac4e219-ea1f-41cb-8e97-7e946f5848c0 -->
-* **PR workflow: wait for Seer and Cursor BugBot before resolving**: After pushing a PR in the getsentry/cli repo, the CI pipeline includes Seer Code Review and Cursor Bugbot as required or advisory checks. Both typically take 2-3 minutes. The workflow is: push → wait for all CI (including npm build jobs which test the actual bundle) → check for inline review comments from Seer/BugBot → fix if needed → repeat. Use \`gh pr checks \<PR> --watch\` to monitor. Review comments are fetched via \`gh api repos/OWNER/REPO/pulls/NUM/comments\` and \`gh api repos/OWNER/REPO/pulls/NUM/reviews\`.
+* **PR workflow: wait for Seer and Cursor BugBot before resolving**: After pushing a PR in the getsentry/cli repo, the CI pipeline includes Seer Code Review and Cursor Bugbot as advisory checks. Both typically take 2-3 minutes but may not trigger on draft PRs — only ready-for-review PRs reliably get bot reviews. The workflow is: push → wait for all CI (including npm build jobs which test the actual bundle) → check for inline review comments from Seer/BugBot → fix if needed → repeat. Use \`gh pr checks \<PR> --watch\` to monitor. Review comments are fetched via \`gh api repos/OWNER/REPO/pulls/NUM/comments\` and \`gh api repos/OWNER/REPO/pulls/NUM/reviews\`.
 
 <!-- lore:019cb162-d3ad-7b05-ab4f-f87892d517a6 -->
 * **Shared pagination infrastructure: buildPaginationContextKey and parseCursorFlag**: List commands with cursor pagination use \`buildPaginationContextKey(type, identifier, flags)\` for composite context keys and \`parseCursorFlag(value)\` accepting \`"last"\` magic value. Critical: \`resolveCursor()\` must be called inside the \`org-all\` override closure, not before \`dispatchOrgScopedList\` — otherwise cursor validation errors fire before the correct mode-specific error.

src/commands/event/view.ts

@@ -12,6 +12,8 @@ import {
   resolveEventInOrg,
 } from "../../lib/api-client.js";
 import {
+  detectSwappedViewArgs,
+  looksLikeIssueShortId,
   ProjectSpecificationType,
   parseOrgProjectArg,
   parseSlashSeparatedArg,
@@ -21,6 +23,7 @@ import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ResolutionError } from "../../lib/errors.js";
 import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
+import { logger } from "../../lib/logger.js";
 import { resolveEffectiveOrg } from "../../lib/region.js";
 import {
   resolveOrgAndProject,
@@ -88,6 +91,10 @@ const USAGE_HINT = "sentry event view <org>/<project> <event-id>";
 export function parsePositionalArgs(args: string[]): {
   eventId: string;
   targetArg: string | undefined;
+  /** Warning message if arguments appear to be in the wrong order */
+  warning?: string;
+  /** Suggestion when the user likely meant a different command */
+  suggestion?: string;
 } {
   if (args.length === 0) {
     throw new ContextError("Event ID", USAGE_HINT);
@@ -130,8 +137,19 @@ export function parsePositionalArgs(args: string[]): {
     return { eventId: first, targetArg: undefined };
   }
 
+  // Detect swapped args: user put ID first and target second
+  const swapWarning = detectSwappedViewArgs(first, second);
+  if (swapWarning) {
+    return { eventId: first, targetArg: second, warning: swapWarning };
+  }
+
+  // Detect issue short ID passed as first arg (e.g., "CAM-82X 95fd7f5a")
+  const suggestion = looksLikeIssueShortId(first)
+    ? `Did you mean: sentry issue view ${first}`
+    : undefined;
+
   // Two or more args - first is target, second is event ID
-  return { eventId: second, targetArg: first };
+  return { eventId: second, targetArg: first, suggestion };
 }
 
 /**
@@ -153,7 +171,6 @@ type ResolveTargetOptions = {
   parsed: ReturnType<typeof parseOrgProjectArg>;
   eventId: string;
   cwd: string;
-  stderr: { write(s: string): void };
 };
 
 /**
@@ -166,7 +183,7 @@ type ResolveTargetOptions = {
 export async function resolveEventTarget(
   options: ResolveTargetOptions
 ): Promise<ResolvedEventTarget | null> {
-  const { parsed, eventId, cwd, stderr } = options;
+  const { parsed, eventId, cwd } = options;
 
   switch (parsed.type) {
     case ProjectSpecificationType.Explicit: {
@@ -183,8 +200,7 @@ export async function resolveEventTarget(
       const resolved = await resolveProjectBySlug(
         parsed.projectSlug,
         USAGE_HINT,
-        `sentry event view <org>/${parsed.projectSlug} ${eventId}`,
-        stderr
+        `sentry event view <org>/${parsed.projectSlug} ${eventId}`
       );
       return {
         ...resolved,
@@ -199,7 +215,7 @@ export async function resolveEventTarget(
     }
 
     case ProjectSpecificationType.AutoDetect:
-      return resolveAutoDetectTarget(eventId, cwd, stderr);
+      return resolveAutoDetectTarget(eventId, cwd);
 
     default:
       return null;
@@ -244,8 +260,7 @@ export async function resolveOrgAllTarget(
 /** @internal Exported for testing */
 export async function resolveAutoDetectTarget(
   eventId: string,
-  cwd: string,
-  stderr: { write(s: string): void }
+  cwd: string
 ): Promise<ResolvedEventTarget | null> {
   const autoTarget = await resolveOrgAndProject({ cwd, usageHint: USAGE_HINT });
   if (autoTarget) {
@@ -254,10 +269,12 @@ export async function resolveAutoDetectTarget(
 
   const resolved = await findEventAcrossOrgs(eventId);
   if (resolved) {
-    stderr.write(
-      `Tip: Found event in ${resolved.org}/${resolved.project}. ` +
-        `Use: sentry event view ${resolved.org}/${resolved.project} ${eventId}\n`
-    );
+    logger
+      .withTag("event.view")
+      .warn(
+        `Found event in ${resolved.org}/${resolved.project}. ` +
+          `Use: sentry event view ${resolved.org}/${resolved.project} ${eventId}`
+      );
     return {
       org: resolved.org,
       project: resolved.project,
@@ -311,15 +328,26 @@ export const viewCommand = buildCommand({
   ): Promise<void> {
     const { stdout, cwd } = this;
 
+    const log = logger.withTag("event.view");
+
     // Parse positional args
-    const { eventId, targetArg } = parsePositionalArgs(args);
+    const { eventId, targetArg, warning, suggestion } =
+      parsePositionalArgs(args);
+    if (warning) {
+      log.warn(warning);
+    }
+    if (suggestion) {
+      log.warn(suggestion);
+    }
     const parsed = parseOrgProjectArg(targetArg);
+    if (parsed.type !== "auto-detect" && parsed.normalized) {
+      log.warn("Normalized slug (Sentry slugs use dashes, not underscores)");
+    }
 
     const target = await resolveEventTarget({
       parsed,
       eventId,
       cwd,
-      stderr: this.stderr,
     });
 
     if (!target) {

src/commands/issue/list.ts

@@ -354,9 +354,25 @@ async function resolveTargetsFromParsedArg(
 
     case "project-search": {
       // Find project across all orgs
-      const matches = await findProjectsBySlug(parsed.projectSlug);
+      const { projects: matches, orgs } = await findProjectsBySlug(
+        parsed.projectSlug
+      );
 
       if (matches.length === 0) {
+        // Check if the slug matches an organization — common mistake
+        const isOrg = orgs.some((o) => o.slug === parsed.projectSlug);
+        if (isOrg) {
+          throw new ResolutionError(
+            `'${parsed.projectSlug}'`,
+            "is an organization, not a project",
+            `sentry issue list ${parsed.projectSlug}/`,
+            [
+              `List projects: sentry project list ${parsed.projectSlug}/`,
+              `Specify a project: sentry issue list ${parsed.projectSlug}/<project>`,
+            ]
+          );
+        }
+
         throw new ResolutionError(
           `Project '${parsed.projectSlug}'`,
           "not found",

src/commands/issue/utils.ts

@@ -140,7 +140,7 @@ async function resolveProjectSearch(
   }
 
   // 2. Search for project across all accessible orgs
-  const projects = await findProjectsBySlug(projectSlug.toLowerCase());
+  const { projects } = await findProjectsBySlug(projectSlug.toLowerCase());
 
   if (projects.length === 0) {
     throw new ResolutionError(

src/commands/log/view.ts

@@ -7,13 +7,15 @@
 import type { SentryContext } from "../../context.js";
 import { getLog } from "../../lib/api-client.js";
 import {
+  detectSwappedViewArgs,
   parseOrgProjectArg,
   parseSlashSeparatedArg,
 } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ValidationError } from "../../lib/errors.js";
 import { formatLogDetails, writeJson } from "../../lib/formatters/index.js";
+import { logger } from "../../lib/logger.js";
 import {
   resolveOrgAndProject,
   resolveProjectBySlug,
@@ -40,6 +42,8 @@ const USAGE_HINT = "sentry log view <org>/<project> <log-id>";
 export function parsePositionalArgs(args: string[]): {
   logId: string;
   targetArg: string | undefined;
+  /** Warning message if arguments appear to be in the wrong order */
+  warning?: string;
 } {
   if (args.length === 0) {
     throw new ContextError("Log ID", USAGE_HINT);
@@ -64,6 +68,12 @@ export function parsePositionalArgs(args: string[]): {
     return { logId: first, targetArg: undefined };
   }
 
+  // Detect swapped args: user put ID first and target second
+  const swapWarning = detectSwappedViewArgs(first, second);
+  if (swapWarning) {
+    return { logId: first, targetArg: second, warning: swapWarning };
+  }
+
   // Two or more args - first is target, second is log ID
   return { logId: second, targetArg: first };
 }
@@ -140,10 +150,17 @@ export const viewCommand = buildCommand({
     ...args: string[]
   ): Promise<void> {
     const { stdout, cwd, setContext } = this;
+    const cmdLog = logger.withTag("log.view");
 
     // Parse positional args
-    const { logId, targetArg } = parsePositionalArgs(args);
+    const { logId, targetArg, warning } = parsePositionalArgs(args);
+    if (warning) {
+      cmdLog.warn(warning);
+    }
     const parsed = parseOrgProjectArg(targetArg);
+    if (parsed.type !== "auto-detect" && parsed.normalized) {
+      cmdLog.warn("Normalized slug (Sentry slugs use dashes, not underscores)");
+    }
 
     let target: ResolvedLogTarget | null = null;
 
@@ -159,8 +176,7 @@ export const viewCommand = buildCommand({
         target = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry log view <org>/${parsed.projectSlug} ${logId}`,
-          this.stderr
+          `sentry log view <org>/${parsed.projectSlug} ${logId}`
         );
         break;
 

src/commands/project/list.ts

@@ -485,7 +485,7 @@ export async function handleProjectSearch(
   projectSlug: string,
   flags: ListFlags
 ): Promise<void> {
-  const projects: ProjectWithOrg[] = await findProjectsBySlug(projectSlug);
+  const { projects } = await findProjectsBySlug(projectSlug);
   const filtered = filterByPlatform(projects, flags.platform);
 
   if (filtered.length === 0) {

src/commands/project/view.ts

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

src/commands/trace/view.ts

@@ -7,6 +7,7 @@
 import type { SentryContext } from "../../context.js";
 import { getDetailedTrace } from "../../lib/api-client.js";
 import {
+  detectSwappedViewArgs,
   parseOrgProjectArg,
   parseSlashSeparatedArg,
   spansFlag,
@@ -21,6 +22,7 @@ import {
   writeFooter,
   writeJson,
 } from "../../lib/formatters/index.js";
+import { logger } from "../../lib/logger.js";
 import {
   resolveOrgAndProject,
   resolveProjectBySlug,
@@ -48,6 +50,8 @@ const USAGE_HINT = "sentry trace view <org>/<project> <trace-id>";
 export function parsePositionalArgs(args: string[]): {
   traceId: string;
   targetArg: string | undefined;
+  /** Warning message if arguments appear to be in the wrong order */
+  warning?: string;
 } {
   if (args.length === 0) {
     throw new ContextError("Trace ID", USAGE_HINT);
@@ -72,6 +76,12 @@ export function parsePositionalArgs(args: string[]): {
     return { traceId: first, targetArg: undefined };
   }
 
+  // Detect swapped args: user put ID first and target second
+  const swapWarning = detectSwappedViewArgs(first, second);
+  if (swapWarning) {
+    return { traceId: first, targetArg: second, warning: swapWarning };
+  }
+
   // Two or more args - first is target, second is trace ID
   return { traceId: second, targetArg: first };
 }
@@ -151,10 +161,17 @@ export const viewCommand = buildCommand({
     ...args: string[]
   ): Promise<void> {
     const { stdout, cwd, setContext } = this;
+    const log = logger.withTag("trace.view");
 
     // Parse positional args
-    const { traceId, targetArg } = parsePositionalArgs(args);
+    const { traceId, targetArg, warning } = parsePositionalArgs(args);
+    if (warning) {
+      log.warn(warning);
+    }
     const parsed = parseOrgProjectArg(targetArg);
+    if (parsed.type !== "auto-detect" && parsed.normalized) {
+      log.warn("Normalized slug (Sentry slugs use dashes, not underscores)");
+    }
 
     let target: ResolvedTraceTarget | null = null;
 
@@ -170,8 +187,7 @@ export const viewCommand = buildCommand({
         target = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry trace view <org>/${parsed.projectSlug} ${traceId}`,
-          this.stderr
+          `sentry trace view <org>/${parsed.projectSlug} ${traceId}`
         );
         break;