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

@@ -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/event/view.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/list.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/issue/utils.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/log/view.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/list.ts

@@ -229,8 +229,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/project/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;
 

src/commands/trace/view.ts

@@ -868,18 +868,30 @@ export async function listRepositoriesPaginated(
   );
 }
 
+/** Result of searching for projects by slug across all organizations. */
+export type ProjectSearchResult = {
+  /** Matching projects with their org context */
+  projects: ProjectWithOrg[];
+  /** All organizations fetched during the search — reuse for fallback checks */
+  orgs: SentryOrganization[];
+};
+
 /**
  * Search for projects matching a slug across all accessible organizations.
  *
  * Used for `sentry issue list <project-name>` when no org is specified.
  * Searches all orgs the user has access to and returns matches.
  *
+ * Returns both the matching projects and the full org list that was fetched,
+ * so callers can check whether a slug matches an organization without an
+ * additional API call (useful for "did you mean org/?" fallbacks).
+ *
  * @param projectSlug - Project slug to search for (exact match)
- * @returns Array of matching projects with their org context
+ * @returns Matching projects and the org list used during search
  */
 export async function findProjectsBySlug(
   projectSlug: string
-): Promise<ProjectWithOrg[]> {
+): Promise<ProjectSearchResult> {
   const orgs = await listOrganizations();
   const isNumericId = isAllDigits(projectSlug);
 
@@ -903,7 +915,10 @@ export async function findProjectsBySlug(
     )
   );
 
-  return searchResults.filter((r): r is ProjectWithOrg => r !== null);
+  return {
+    projects: searchResults.filter((r): r is ProjectWithOrg => r !== null),
+    orgs,
+  };
 }
 
 /**