feat(commands): add buildRouteMap wrapper with standard subcommand aliases

BYK · BYK · commit a17e0ef875b9 · 2026-04-08T15:59:47.000Z
Introduce `src/lib/route-map.ts` as the single entry point for building
route maps — analogous to how `src/lib/command.ts` wraps Stricli's
`buildCommand`. The wrapper auto-injects standard aliases based on which
route keys exist:

  list   → ls
  view   → show
  delete → remove, rm
  create → new

All 16 command group index.ts files and app.ts now import from the
wrapper instead of @stricli/core directly. Manual aliases that are
covered by the standard set have been removed.

Also update `getSubcommandsForRoute()` in list-command.ts to collect
subcommand aliases so plural+alias combos like `sentry issues ls` are
properly intercepted.
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md b/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md
@@ -42,7 +42,7 @@ View a dashboard
 - `-w, --web - Open in browser`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-r, --refresh <value> - Auto-refresh interval in seconds (default: 60, min: 10)`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07"`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08"`
 
 **Examples:**
 
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/event.md b/plugins/sentry-cli/skills/sentry-cli/references/event.md
@@ -28,7 +28,7 @@ List events for an issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/issue.md b/plugins/sentry-cli/skills/sentry-cli/references/issue.md
@@ -19,7 +19,7 @@ List issues in a project
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-n, --limit <value> - Maximum number of issues to list - (default: "25")`
 - `-s, --sort <value> - Sort by: date, new, freq, user - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "90d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "90d")`
 - `-c, --cursor <value> - Pagination cursor (use "next" for next page, "prev" for previous)`
 - `--compact - Single-line rows for compact output (auto-detects if omitted)`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
@@ -78,7 +78,7 @@ List events for a specific issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/log.md b/plugins/sentry-cli/skills/sentry-cli/references/log.md
@@ -19,7 +19,7 @@ List logs from a project
 - `-n, --limit <value> - Number of log entries (1-1000) - (default: "100")`
 - `-q, --query <value> - Filter query (Sentry search syntax)`
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07"`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08"`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`
 - `--fresh - Bypass cache, re-detect projects, and fetch fresh data`
 
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/span.md b/plugins/sentry-cli/skills/sentry-cli/references/span.md
@@ -19,7 +19,7 @@ List spans in a project or trace
 - `-n, --limit <value> - Number of spans (<=1000) - (default: "25")`
 - `-q, --query <value> - Filter spans (e.g., "op:db", "duration:>100ms", "project:backend")`
 - `-s, --sort <value> - Sort order: date, duration - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/trace.md b/plugins/sentry-cli/skills/sentry-cli/references/trace.md
@@ -19,7 +19,7 @@ List recent traces in a project
 - `-n, --limit <value> - Number of traces (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
@@ -78,7 +78,7 @@ View logs associated with a trace
 
 **Flags:**
 - `-w, --web - Open trace in browser`
-- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "14d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "14d")`
 - `-n, --limit <value> - Number of log entries (<=1000) - (default: "100")`
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`
diff --git a/src/app.ts b/src/app.ts
@@ -3,7 +3,6 @@ import * as Sentry from "@sentry/node-core/light";
 import {
   type ApplicationText,
   buildApplication,
-  buildRouteMap,
   text_en,
   UnexpectedPositionalError,
   UnsatisfiedPositionalError,
@@ -55,6 +54,7 @@ import {
 } from "./lib/errors.js";
 import { error as errorColor, warning } from "./lib/formatters/colors.js";
 import { isRouteMap, type RouteMap } from "./lib/introspect.js";
+import { buildRouteMap } from "./lib/route-map.js";
 
 /**
  * Plural alias → singular route name mapping.
diff --git a/src/commands/auth/index.ts b/src/commands/auth/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { loginCommand } from "./login.js";
 import { logoutCommand } from "./logout.js";
 import { refreshCommand } from "./refresh.js";
diff --git a/src/commands/cli/index.ts b/src/commands/cli/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { feedbackCommand } from "./feedback.js";
 import { fixCommand } from "./fix.js";
 import { setupCommand } from "./setup.js";
diff --git a/src/commands/dashboard/index.ts b/src/commands/dashboard/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { createCommand } from "./create.js";
 import { listCommand } from "./list.js";
 import { viewCommand } from "./view.js";
@@ -12,7 +12,6 @@ export const dashboardRoute = buildRouteMap({
     widget: widgetRoute,
   },
   defaultCommand: "view",
-  aliases: { show: "view" },
   docs: {
     brief: "Manage Sentry dashboards",
     fullDescription:
diff --git a/src/commands/dashboard/widget/index.ts b/src/commands/dashboard/widget/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../../lib/route-map.js";
 import { addCommand } from "./add.js";
 import { deleteCommand } from "./delete.js";
 import { editCommand } from "./edit.js";
@@ -9,7 +9,6 @@ export const widgetRoute = buildRouteMap({
     edit: editCommand,
     delete: deleteCommand,
   },
-  aliases: { remove: "delete" },
   docs: {
     brief: "Manage dashboard widgets",
     fullDescription:
diff --git a/src/commands/event/index.ts b/src/commands/event/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 import { viewCommand } from "./view.js";
 
@@ -8,7 +8,6 @@ export const eventRoute = buildRouteMap({
     list: listCommand,
   },
   defaultCommand: "view",
-  aliases: { show: "view" },
   docs: {
     brief: "View and list Sentry events",
     fullDescription:
diff --git a/src/commands/issue/index.ts b/src/commands/issue/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { eventsCommand } from "./events.js";
 import { explainCommand } from "./explain.js";
 import { listCommand } from "./list.js";
@@ -14,7 +14,6 @@ export const issueRoute = buildRouteMap({
     view: viewCommand,
   },
   defaultCommand: "view",
-  aliases: { show: "view" },
   docs: {
     brief: "Manage Sentry issues",
     fullDescription:
diff --git a/src/commands/log/index.ts b/src/commands/log/index.ts
@@ -4,7 +4,7 @@
  * View and stream logs from Sentry projects.
  */
 
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 import { viewCommand } from "./view.js";
 
@@ -14,7 +14,6 @@ export const logRoute = buildRouteMap({
     view: viewCommand,
   },
   defaultCommand: "view",
-  aliases: { show: "view" },
   docs: {
     brief: "View Sentry logs",
     fullDescription:
diff --git a/src/commands/org/index.ts b/src/commands/org/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 import { viewCommand } from "./view.js";
 
@@ -8,7 +8,6 @@ export const orgRoute = buildRouteMap({
     view: viewCommand,
   },
   defaultCommand: "view",
-  aliases: { show: "view" },
   docs: {
     brief: "Work with Sentry organizations",
     fullDescription:
diff --git a/src/commands/project/index.ts b/src/commands/project/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { createCommand } from "./create.js";
 import { deleteCommand } from "./delete.js";
 import { listCommand } from "./list.js";
@@ -12,7 +12,6 @@ export const projectRoute = buildRouteMap({
     view: viewCommand,
   },
   defaultCommand: "view",
-  aliases: { show: "view", remove: "delete" },
   docs: {
     brief: "Work with Sentry projects",
     fullDescription:
diff --git a/src/commands/release/index.ts b/src/commands/release/index.ts
@@ -4,7 +4,7 @@
  * Route map for release management commands.
  */
 
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { createCommand } from "./create.js";
 import { deleteCommand } from "./delete.js";
 import { deployCommand } from "./deploy.js";
diff --git a/src/commands/repo/index.ts b/src/commands/repo/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 
 export const repoRoute = buildRouteMap({
diff --git a/src/commands/sourcemap/index.ts b/src/commands/sourcemap/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { injectCommand } from "./inject.js";
 import { uploadCommand } from "./upload.js";
 
diff --git a/src/commands/span/index.ts b/src/commands/span/index.ts
@@ -4,7 +4,7 @@
  * List and explore individual spans within distributed traces or across projects.
  */
 
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 import { viewCommand } from "./view.js";
 
@@ -14,7 +14,6 @@ export const spanRoute = buildRouteMap({
     view: viewCommand,
   },
   defaultCommand: "view",
-  aliases: { show: "view" },
   docs: {
     brief: "List and view spans in projects or traces",
     fullDescription:
diff --git a/src/commands/team/index.ts b/src/commands/team/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 
 export const teamRoute = buildRouteMap({
diff --git a/src/commands/trace/index.ts b/src/commands/trace/index.ts
@@ -4,7 +4,7 @@
  * View and explore distributed traces from Sentry projects.
  */
 
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 import { logsCommand } from "./logs.js";
 import { viewCommand } from "./view.js";
@@ -16,7 +16,6 @@ export const traceRoute = buildRouteMap({
     logs: logsCommand,
   },
   defaultCommand: "view",
-  aliases: { show: "view" },
   docs: {
     brief: "View distributed traces",
     fullDescription:
diff --git a/src/commands/trial/index.ts b/src/commands/trial/index.ts
@@ -1,4 +1,4 @@
-import { buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "../../lib/route-map.js";
 import { listCommand } from "./list.js";
 import { startCommand } from "./start.js";
 
diff --git a/src/lib/list-command.ts b/src/lib/list-command.ts
@@ -341,32 +341,44 @@ let _subcommandsByRoute: Map<string, Set<string>> | undefined;
  * Lazily walks the Stricli route map on first call. Uses `require()` to break
  * the circular dependency: list-command → app → commands → list-command.
  */
+/** Entry shape returned by Stricli's getAllEntries() */
+type RouteEntry = {
+  name: { original: string };
+  aliases: readonly string[];
+  target: unknown;
+};
+
+/** Collect all subcommand names and aliases from a route group's children. */
+function collectChildNames(parent: {
+  getAllEntries: () => readonly RouteEntry[];
+}): Set<string> {
+  const names = new Set<string>();
+  for (const child of parent.getAllEntries()) {
+    names.add(child.name.original);
+    for (const alias of child.aliases) {
+      names.add(alias);
+    }
+  }
+  return names;
+}
+
 function getSubcommandsForRoute(routeName: string): Set<string> {
   if (!_subcommandsByRoute) {
     _subcommandsByRoute = new Map();
 
     const { routes } = require("../app.js") as {
-      routes: {
-        getAllEntries: () => readonly {
-          name: { original: string };
-          target: unknown;
-        }[];
-      };
+      routes: { getAllEntries: () => readonly RouteEntry[] };
     };
 
     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 };
-          }[]
-        )();
-        const names = new Set<string>();
-        for (const child of children) {
-          names.add(child.name.original);
-        }
-        _subcommandsByRoute.set(entry.name.original, names);
+        _subcommandsByRoute.set(
+          entry.name.original,
+          collectChildNames(
+            target as { getAllEntries: () => readonly RouteEntry[] }
+          )
+        );
       }
     }
   }
diff --git a/src/lib/route-map.ts b/src/lib/route-map.ts
@@ -0,0 +1,66 @@
+/**
+ * Drop-in replacement for `@stricli/core`'s `buildRouteMap`.
+ *
+ * Analogous to how `buildCommand` in `./command.ts` wraps Stricli's version,
+ * this is the **only** place that should import `buildRouteMap` from
+ * `@stricli/core`. All other files import from here.
+ */
+
+import {
+  type CommandContext,
+  type RouteMap,
+  type RouteMapBuilderArguments,
+  buildRouteMap as stricliRouteMap,
+} from "@stricli/core";
+
+/**
+ * Standard subcommand aliases, auto-injected when the matching route key
+ * exists. Each entry maps a canonical route name to the set of short-form
+ * aliases that should resolve to it.
+ */
+const STANDARD_ALIASES = new Map<string, ReadonlySet<string>>([
+  ["list", new Set(["ls"])],
+  ["view", new Set(["show"])],
+  ["delete", new Set(["remove", "rm"])],
+  ["create", new Set(["new"])],
+]);
+
+/**
+ * Build a route map with standard subcommand aliases auto-injected.
+ *
+ * | Route    | Auto-aliases   |
+ * |----------|----------------|
+ * | `list`   | `ls`           |
+ * | `view`   | `show`         |
+ * | `delete` | `remove`, `rm` |
+ * | `create` | `new`          |
+ *
+ * Manually specified aliases in `args.aliases` take precedence over
+ * auto-generated ones. Aliases that would collide with actual route
+ * names are silently skipped.
+ */
+export function buildRouteMap<
+  R extends string,
+  CONTEXT extends CommandContext = CommandContext,
+>(args: RouteMapBuilderArguments<R, CONTEXT>): RouteMap<CONTEXT> {
+  const routeKeys = new Set(Object.keys(args.routes));
+  const autoAliases: Record<string, string> = {};
+
+  for (const [routeName, aliases] of STANDARD_ALIASES) {
+    if (routeKeys.has(routeName)) {
+      for (const alias of aliases) {
+        if (!routeKeys.has(alias)) {
+          autoAliases[alias] = routeName;
+        }
+      }
+    }
+  }
+
+  return stricliRouteMap({
+    ...args,
+    aliases: {
+      ...autoAliases,
+      ...args.aliases,
+    } as RouteMapBuilderArguments<R, CONTEXT>["aliases"],
+  });
+}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { buildRouteMap } from "@stricli/core";`
	`1`	`+import { buildRouteMap } from "../../lib/route-map.js";`
`2`	`2`	`import { loginCommand } from "./login.js";`
`3`	`3`	`import { logoutCommand } from "./logout.js";`
`4`	`4`	`import { refreshCommand } from "./refresh.js";`