feat: improve unknown command UX with aliases, default routing, and suggestions

Address CLI-Q3 (183 events, 85 users) by adding three complementary
mechanisms for handling unrecognized commands:

- Add `defaultCommand: "view"` to all 8 route groups so bare IDs
  route directly (e.g., `sentry issue CLI-G5` → `sentry issue view`)
- Add `show` as alias for `view` on all route maps, `remove` for
  `delete` on project and widget routes
- Add synonym suggestion registry for mutation commands, old sentry-cli
  commands, and cross-route confusion patterns

Three edge cases handled in app.ts:
- Case A: bare route group (`sentry issue`) → usage hint
- Case B: multi-arg synonym (`sentry issue events CLI-AB`) → tip
- Case C: single-arg synonym (`sentry issue resolve`) → tip appended
  to domain error

Filed #632 (issue events) and #633 (event list) for missing commands.

Author: BYK

src/app.ts

@@ -6,6 +6,7 @@ import {
   buildRouteMap,
   text_en,
   UnexpectedPositionalError,
+  UnsatisfiedPositionalError,
 } from "@stricli/core";
 import { apiCommand } from "./commands/api.js";
 import { authRoute } from "./commands/auth/index.js";
@@ -36,6 +37,11 @@ import { traceRoute } from "./commands/trace/index.js";
 import { listCommand as traceListCommand } from "./commands/trace/list.js";
 import { trialRoute } from "./commands/trial/index.js";
 import { listCommand as trialListCommand } from "./commands/trial/list.js";
+import {
+  getCommandSuggestion,
+  getSynonymSuggestionFromArgv,
+  ROUTES_WITH_DEFAULT_VIEW,
+} from "./lib/command-suggestions.js";
 import { CLI_VERSION } from "./lib/constants.js";
 import {
   AuthError,
@@ -121,6 +127,46 @@ export const routes = buildRouteMap({
   },
 });
 
+/**
+ * Detect when the user typed a bare route group with no subcommand (e.g., `sentry issue`).
+ *
+ * With `defaultCommand: "view"` on route groups, Stricli routes to the view
+ * command which then fails with UnsatisfiedPositionalError because no issue ID
+ * was provided. Returns a usage hint string, or undefined if this isn't the
+ * bare-route-group case.
+ */
+function detectBareRouteGroup(ansiColor: boolean): string | undefined {
+  const args = process.argv.slice(2);
+  const nonFlags = args.filter((t) => !t.startsWith("-"));
+  if (
+    nonFlags.length <= 1 &&
+    nonFlags[0] &&
+    ROUTES_WITH_DEFAULT_VIEW.has(nonFlags[0])
+  ) {
+    const route = nonFlags[0];
+    const msg = `Usage: sentry ${route} <command> [args]\nRun "sentry ${route} --help" to see available commands`;
+    return ansiColor ? warning(msg) : msg;
+  }
+  return;
+}
+
+/**
+ * Detect when a plural alias received extra positional args and suggest the
+ * singular form. E.g., `sentry projects view cli` → `sentry project view cli`.
+ */
+function detectPluralAliasMisuse(ansiColor: boolean): string | undefined {
+  const args = process.argv.slice(2);
+  const firstArg = args[0];
+  if (firstArg && firstArg in PLURAL_TO_SINGULAR) {
+    const singular = PLURAL_TO_SINGULAR[firstArg];
+    const rest = args.slice(1).join(" ");
+    return ansiColor
+      ? warning(`\nDid you mean: sentry ${singular} ${rest}\n`)
+      : `\nDid you mean: sentry ${singular} ${rest}\n`;
+  }
+  return;
+}
+
 /**
  * Custom error formatting for CLI errors.
  *
@@ -134,23 +180,65 @@ const customText: ApplicationText = {
     exc: unknown,
     ansiColor: boolean
   ): string => {
-    // When a plural alias receives extra positional args (e.g. `sentry projects view cli`),
-    // Stricli throws UnexpectedPositionalError because the list command only accepts 1 arg.
-    // Detect this and suggest the singular form.
+    // Case A: bare route group with no subcommand (e.g., `sentry issue`)
+    if (exc instanceof UnsatisfiedPositionalError) {
+      const bareHint = detectBareRouteGroup(ansiColor);
+      if (bareHint) {
+        return bareHint;
+      }
+    }
+
+    // Case B + plural alias: extra args that Stricli can't consume
     if (exc instanceof UnexpectedPositionalError) {
-      const args = process.argv.slice(2);
-      const firstArg = args[0];
-      if (firstArg && firstArg in PLURAL_TO_SINGULAR) {
-        const singular = PLURAL_TO_SINGULAR[firstArg];
-        const rest = args.slice(1).join(" ");
-        const hint = ansiColor
-          ? warning(`\nDid you mean: sentry ${singular} ${rest}\n`)
-          : `\nDid you mean: sentry ${singular} ${rest}\n`;
-        return `${text_en.exceptionWhileParsingArguments(exc, ansiColor)}${hint}`;
+      const pluralHint = detectPluralAliasMisuse(ansiColor);
+      if (pluralHint) {
+        return `${text_en.exceptionWhileParsingArguments(exc, ansiColor)}${pluralHint}`;
+      }
+
+      // With defaultCommand: "view", unknown tokens like "events" fill the
+      // positional slot, then extra args (e.g., CLI-AB) trigger this error.
+      // Check if the first non-route token is a known synonym.
+      const synonymHint = getSynonymSuggestionFromArgv();
+      if (synonymHint) {
+        const tip = ansiColor
+          ? warning(`\nTip: ${synonymHint}`)
+          : `\nTip: ${synonymHint}`;
+        return `${text_en.exceptionWhileParsingArguments(exc, ansiColor)}${tip}`;
       }
     }
+
     return text_en.exceptionWhileParsingArguments(exc, ansiColor);
   },
+  noCommandRegisteredForInput: ({ input, corrections, ansiColor }): string => {
+    // Default error message from Stricli (e.g., "No command registered for `info`")
+    const base = text_en.noCommandRegisteredForInput({
+      input,
+      corrections,
+      ansiColor,
+    });
+
+    // Check for known synonym suggestions on routes without defaultCommand
+    // (e.g., `sentry cli info` → suggest `sentry auth status`).
+    // Routes WITH defaultCommand won't reach here — their unknown tokens
+    // are consumed as positional args and handled by Cases A/B/C above.
+    const args = process.argv.slice(2);
+    const nonFlags = args.filter((t) => !t.startsWith("-"));
+    const routeContext = nonFlags[0] ?? "";
+    const suggestion = getCommandSuggestion(routeContext, input);
+    if (suggestion) {
+      const hint = suggestion.explanation
+        ? `${suggestion.explanation}: ${suggestion.command}`
+        : suggestion.command;
+      // Stricli wraps our return value in bold-red ANSI codes.
+      // Reset before applying warning() color so the tip is yellow, not red.
+      const formatted = ansiColor
+        ? `\n\x1B[39m\x1B[22m${warning(`Tip: ${hint}`)}`
+        : `\nTip: ${hint}`;
+      return `${base}${formatted}`;
+    }
+
+    return base;
+  },
   exceptionWhileRunningCommand: (exc: unknown, ansiColor: boolean): string => {
     // OutputError: data was already rendered to stdout — just re-throw
     // so the exit code propagates without Stricli printing an error message.
@@ -174,6 +262,17 @@ const customText: ApplicationText = {
 
     if (exc instanceof CliError) {
       const prefix = ansiColor ? errorColor("Error:") : "Error:";
+      // Case C: With defaultCommand: "view", unknown tokens like "events" are
+      // silently consumed as the positional arg. The view command fails at the
+      // domain level (e.g., ResolutionError). Check argv for a known synonym
+      // and append the suggestion to the error.
+      const synonymHint = getSynonymSuggestionFromArgv();
+      if (synonymHint) {
+        const tip = ansiColor
+          ? warning(`Tip: ${synonymHint}`)
+          : `Tip: ${synonymHint}`;
+        return `${prefix} ${exc.format()}\n${tip}`;
+      }
       return `${prefix} ${exc.format()}`;
     }
     if (exc instanceof Error) {

src/commands/dashboard/index.ts

@@ -11,6 +11,8 @@ export const dashboardRoute = buildRouteMap({
     create: createCommand,
     widget: widgetRoute,
   },
+  defaultCommand: "view",
+  aliases: { show: "view" },
   docs: {
     brief: "Manage Sentry dashboards",
     fullDescription:

src/commands/dashboard/widget/index.ts

@@ -9,6 +9,7 @@ export const widgetRoute = buildRouteMap({
     edit: editCommand,
     delete: deleteCommand,
   },
+  aliases: { remove: "delete" },
   docs: {
     brief: "Manage dashboard widgets",
     fullDescription:

src/commands/event/index.ts

@@ -5,6 +5,8 @@ export const eventRoute = buildRouteMap({
   routes: {
     view: viewCommand,
   },
+  defaultCommand: "view",
+  aliases: { show: "view" },
   docs: {
     brief: "View Sentry events",
     fullDescription:

src/commands/issue/index.ts

@@ -11,6 +11,8 @@ export const issueRoute = buildRouteMap({
     plan: planCommand,
     view: viewCommand,
   },
+  defaultCommand: "view",
+  aliases: { show: "view" },
   docs: {
     brief: "Manage Sentry issues",
     fullDescription:

src/commands/log/index.ts

@@ -13,6 +13,8 @@ export const logRoute = buildRouteMap({
     list: listCommand,
     view: viewCommand,
   },
+  defaultCommand: "view",
+  aliases: { show: "view" },
   docs: {
     brief: "View Sentry logs",
     fullDescription:

src/commands/org/index.ts

@@ -7,6 +7,8 @@ export const orgRoute = buildRouteMap({
     list: listCommand,
     view: viewCommand,
   },
+  defaultCommand: "view",
+  aliases: { show: "view" },
   docs: {
     brief: "Work with Sentry organizations",
     fullDescription:

src/commands/project/index.ts

@@ -11,6 +11,8 @@ export const projectRoute = buildRouteMap({
     list: listCommand,
     view: viewCommand,
   },
+  defaultCommand: "view",
+  aliases: { show: "view", remove: "delete" },
   docs: {
     brief: "Work with Sentry projects",
     fullDescription:

src/commands/span/index.ts

@@ -13,6 +13,8 @@ export const spanRoute = buildRouteMap({
     list: listCommand,
     view: viewCommand,
   },
+  defaultCommand: "view",
+  aliases: { show: "view" },
   docs: {
     brief: "List and view spans in projects or traces",
     fullDescription:

src/commands/trace/index.ts

@@ -15,6 +15,8 @@ export const traceRoute = buildRouteMap({
     view: viewCommand,
     logs: logsCommand,
   },
+  defaultCommand: "view",
+  aliases: { show: "view" },
   docs: {
     brief: "View distributed traces",
     fullDescription: