fix: three bug fixes from Sentry telemetry (CLI-SC, CLI-QZ, CLI-WD) (#664)

## Summary

Three independent bug fixes discovered from Sentry telemetry data, each
in a separate commit.

---

### 1. fix(span-view): detect bare span ID and show helpful ContextError
(CLI-SC)

**Sentry Issue:** [CLI-SC](https://sentry.sentry.io/issues/CLI-SC) — 7
users, 12 events

**Root cause:** When a user runs `sentry span view <span-id>` with only
a 16-char span ID, the code falls through to `validateTraceId()` which
throws a confusing "Invalid trace ID" error.

**Reproduction:** `sentry span view c38bb3754a4ac6d8`

**Fix:** Added early detection in `parsePositionalArgs()` for a single
bare arg matching span ID format (16-char hex). Throws a targeted
`ContextError` with actionable suggestions instead of the misleading
`ValidationError`.

---

### 2. fix(routing): add 'events' plural alias for 'event' route
(CLI-QZ)

**Sentry Issue:** [CLI-QZ](https://sentry.sentry.io/issues/CLI-QZ) — 47
users, 113 events

**Root cause:** Users typing `sentry events list <issue-id>` get an
unhelpful `OutputError` because `events` isn't a registered route. Every
other resource noun has a plural alias (`issues`, `projects`, `teams`,
etc.) but `events` was missing.

**Reproduction:** `sentry events list FULLPHYSIO-WEB-3C`

**Fix:** Added `events` as a route alias for `eventRoute` (like
`sourcemaps` → `sourcemapRoute`) and added `events: "event"` to
`PLURAL_TO_SINGULAR` so the plural hint system suggests the correct
singular form.

---

### 3. fix(platforms): match middle components in platform suggestions
(CLI-WD)

**Sentry Issue:** [CLI-WD](https://sentry.sentry.io/issues/CLI-WD) — 2
users, 2 events

**Root cause:** When a user types `javascript-cloudflare`, the
suggestion system fails to suggest `node-cloudflare-workers` and
`node-cloudflare-pages` because `cloudflare` appears as a middle
component between dashes, not as a prefix or suffix.

**Reproduction:** `sentry project create <name> javascript-cloudflare`

**Fix:** Added middle-component matching in `findSwapMatches()` so that
components appearing between dashes in valid platform names are also
found.

<div><a
href="https://cursor.com/agents/bc-03af229b-5278-4c3c-acd4-8be47d1b4288"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/95624600-485e-4461-829e-6b76f086c473"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: Burak Yigit Kaya <byk@sentry.io>

Author: 4 people

src/app.ts

@@ -60,6 +60,7 @@ import { isRouteMap, type RouteMap } from "./lib/introspect.js";
  */
 const PLURAL_TO_SINGULAR: Record<string, string> = {
   dashboards: "dashboard",
+  events: "event",
   issues: "issue",
   orgs: "org",
   projects: "project",
@@ -87,6 +88,7 @@ export const routes = buildRouteMap({
     team: teamRoute,
     issue: issueRoute,
     event: eventRoute,
+    events: eventRoute,
     log: logRoute,
     sourcemap: sourcemapRoute,
     sourcemaps: sourcemapRoute,
@@ -117,6 +119,7 @@ export const routes = buildRouteMap({
       "It provides commands for authentication, viewing issues, and making API calls.",
     hideRoute: {
       dashboards: true,
+      events: true,
       issues: true,
       orgs: true,
       projects: true,
@@ -244,7 +247,7 @@ const customText: ApplicationText = {
         return `${text_en.exceptionWhileParsingArguments(exc, ansiColor)}${pluralHint}`;
       }
 
-      // With defaultCommand: "view", unknown tokens like "events" fill the
+      // With defaultCommand: "view", unknown tokens like "metrics" 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();
@@ -305,7 +308,7 @@ const customText: ApplicationText = {
       throw exc;
     }
 
-    // Case C: With defaultCommand: "view", unknown tokens like "events" are
+    // Case C: With defaultCommand: "view", unknown tokens like "metrics" 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 show the suggestion — skip Sentry capture since these are known

src/commands/span/view.ts

@@ -130,6 +130,20 @@ export function parsePositionalArgs(args: string[]): {
     }
   }
 
+  // Single bare arg that looks like a span ID (16-char hex, no slashes):
+  // the user forgot the trace ID. Give a targeted ContextError instead of the
+  // confusing "Invalid trace ID" from validateTraceId(). (CLI-SC)
+  if (args.length === 1 && !first.includes("/")) {
+    const normalized = first.trim().toLowerCase().replace(/-/g, "");
+    if (SPAN_ID_RE.test(normalized)) {
+      throw new ContextError("Trace ID and span ID", USAGE_HINT, [
+        `'${first}' looks like a span ID (16 characters), not a trace ID`,
+        `Provide the trace ID first: sentry span view <trace-id> ${normalized}`,
+        `Use 'sentry trace list' to find trace IDs`,
+      ]);
+    }
+  }
+
   // First arg is trace target (possibly with org/project prefix)
   const traceTarget = parseSlashSeparatedTraceTarget(first, USAGE_HINT);
 

src/lib/platforms.ts

@@ -208,11 +208,15 @@ function findSwapMatches(invalid: string): string[] {
   const suffixPrefix = `${suffix}-`;
   // Try suffix as a component in other platforms (e.g. "*-hono" for suffix "hono")
   const suffixSuffix = `-${suffix}`;
+  // Also match suffix as a middle component (e.g. "cloudflare" in "node-cloudflare-workers")
+  const suffixMiddle = `-${suffix}-`;
   for (const p of VALID_PLATFORMS) {
     if (p.startsWith(suffixPrefix) && p !== swapped) {
       results.push(p);
     } else if (p.endsWith(suffixSuffix) && p !== invalid) {
       results.push(p);
+    } else if (p.includes(suffixMiddle)) {
+      results.push(p);
     }
   }
 

test/commands/span/view.test.ts

@@ -222,6 +222,32 @@ describe("parsePositionalArgs", () => {
         ValidationError
       );
     });
+
+    test("throws ContextError for bare span ID without trace ID (CLI-SC)", () => {
+      expect(() => parsePositionalArgs(["a1b2c3d4e5f67890"])).toThrow(
+        ContextError
+      );
+    });
+
+    test("bare span ID error identifies the input and suggests correct usage", () => {
+      try {
+        parsePositionalArgs(["A1B2C3D4E5F67890"]);
+        expect.unreachable("Should have thrown");
+      } catch (error) {
+        expect(error).toBeInstanceOf(ContextError);
+        const msg = (error as ContextError).message;
+        expect(msg).toContain("looks like a span ID");
+        expect(msg).toContain("sentry span view <trace-id> a1b2c3d4e5f67890");
+        expect(msg).toContain("sentry trace list");
+      }
+    });
+
+    test("bare span ID with dashes is still detected (CLI-SC)", () => {
+      // Some tools format span IDs with dashes
+      expect(() => parsePositionalArgs(["a1b2-c3d4-e5f6-7890"])).toThrow(
+        ContextError
+      );
+    });
   });
 });
 

test/lib/platforms.test.ts

@@ -68,6 +68,12 @@ describe("suggestPlatform", () => {
     expect(results).toContain("javascript-react");
   });
 
+  test("suggests middle-component match: javascript-cloudflare → node-cloudflare-* (CLI-WD)", () => {
+    const results = suggestPlatform("javascript-cloudflare");
+    expect(results).toContain("node-cloudflare-pages");
+    expect(results).toContain("node-cloudflare-workers");
+  });
+
   test("returns empty array for garbage input", () => {
     expect(suggestPlatform("xyzgarbage")).toEqual([]);
   });