fix(event-view): validate event ID format before API call (CLI-156) (#751)

## Summary

- Add `validateHexId()` to event view command, matching trace/log view
behavior — malformed event IDs are now caught before making API calls
- Add flag-like string detection in `validateHexId()` — inputs starting
with `-` (e.g., `--h`, `--verbose`) produce a targeted hint instead of
the generic "doesn't look like a hex ID" message
- Extend `maybeRecoverWithHelp` to recognize `--h` and `-help` as
help-seeking tokens, showing actual help output on error

Fixes [CLI-156](https://sentry.sentry.io/issues/7410782826/)

## Context

When a user types `sentry event --h` (a common typo for `--help` or
`-h`), Stricli doesn't recognize `--h` as a help flag — it only handles
`--help` and `-h`. Its long-flag regex also requires 2+ chars after
`--`, so `--h` isn't treated as a flag at all. It falls through as a
positional argument to `event view` (the default command). Unlike `trace
view` and `log view` which call `validateHexId()`, event view had no
format validation before API calls, so `--h` was sent as an event ID,
producing a confusing `ResolutionError: Event '--h' not found`.

## Changes

| File | Change |
|------|--------|
| `src/lib/hex-id.ts` | New `FLAG_LIKE_RE`/`HELP_FLAG_RE` regexes;
flag-like detection branch before existing span-ID and slug hints |
| `src/commands/event/view.ts` | `validateHexId(eventId, "event ID")` in
`func()` after parsing, before resolution; skips sentinels from issue
URL/short ID paths |
| `src/lib/command.ts` | `maybeRecoverWithHelp` now also matches `"--h"`
and `"-help"` in positional args |
| `test/lib/hex-id.test.ts` | 4 new tests for flag-like detection (help
hint, generic flag hint, precedence over slug hint) |
| `test/commands/event/view.test.ts` | 2 new `viewCommand.func` tests
for `--h` and non-hex IDs; updated existing func tests to use valid
32-char hex IDs |

Author: BYK

src/commands/event/view.ts

@@ -32,7 +32,7 @@ import {
 import { formatEventDetails } from "../../lib/formatters/index.js";
 import { filterFields } from "../../lib/formatters/json.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
-import { HEX_ID_RE, normalizeHexId } from "../../lib/hex-id.js";
+import { HEX_ID_RE, normalizeHexId, validateHexId } from "../../lib/hex-id.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -737,11 +737,20 @@ export const viewCommand = buildCommand({
     const log = logger.withTag("event.view");
 
     // Parse positional args
-    const { eventId, targetArg, warning, issueId, issueShortId } =
+    let { eventId, targetArg, warning, issueId, issueShortId } =
       parsePositionalArgs(args);
     if (warning) {
       log.warn(warning);
     }
+
+    // Validate event ID format early (before API calls) when the ID came
+    // from user input. Skip when the ID is a sentinel from issue URL/short
+    // ID detection — those paths resolve the event through issue lookup.
+    // Capture the normalized return value (lowercased, UUID dashes stripped).
+    if (eventId !== LATEST_EVENT_SENTINEL && !issueId && !issueShortId) {
+      eventId = validateHexId(eventId, "event ID");
+    }
+
     const parsed = parseOrgProjectArg(targetArg);
 
     // Handle issue-based shortcuts (issue URLs and short IDs) before

src/lib/command.ts

@@ -485,8 +485,8 @@ export function buildCommand<
 
   /**
    * When a command throws a {@link CliError} and a positional arg was
-   * `"help"`, the user likely intended `--help`. Show the command's
-   * help instead of the confusing error.
+   * `"help"`, `"--h"`, or `"-help"`, the user likely intended `--help`.
+   * Show the command's help instead of the confusing error.
    *
    * Only fires as **error recovery** — if the command succeeds with a
    * legitimate value like a project named "help", this never runs.
@@ -511,7 +511,10 @@ export function buildCommand<
     if (!(err instanceof CliError) || err instanceof OutputError) {
       return false;
     }
-    if (args.length === 0 || !args.some((a) => a === "help")) {
+    if (
+      args.length === 0 ||
+      !args.some((a) => a === "help" || a === "--h" || a === "-help")
+    ) {
       return false;
     }
     if (!ctx.commandPrefix) {

src/lib/hex-id.ts

@@ -27,6 +27,12 @@ const MAX_DISPLAY_LENGTH = 40;
 /** Matches any character that is NOT a lowercase hex digit (used for slug detection in error hints) */
 const NON_HEX_RE = /[^0-9a-f]/;
 
+/** Matches strings starting with a dash — likely CLI flags that Stricli didn't recognize */
+const FLAG_LIKE_RE = /^-/;
+
+/** Matches common help flag typos (e.g., "--h", "-h", "--help", "-help") */
+const HELP_FLAG_RE = /^--?h(elp)?$/;
+
 /**
  * Normalize a potential hex ID: trim, lowercase, strip UUID dashes.
  * Does NOT validate — call this before checking {@link HEX_ID_RE}.
@@ -77,8 +83,18 @@ export function validateHexId(value: string, label: string): string {
       `Invalid ${label} "${display}". Expected a 32-character hexadecimal string.\n\n` +
       "Example: abc123def456abc123def456abc123de";
 
-    // Detect common misidentified entity types and add helpful hints
-    if (SPAN_ID_RE.test(normalized)) {
+    // Detect common misidentified entity types and add helpful hints.
+    // Flag-like check first — strings starting with "-" are almost certainly
+    // CLI flags that Stricli didn't recognize (e.g., "--h" instead of "-h").
+    if (FLAG_LIKE_RE.test(normalized)) {
+      if (HELP_FLAG_RE.test(normalized)) {
+        message +=
+          "\n\nThis looks like a help flag. Use --help or -h for help.";
+      } else {
+        message +=
+          "\n\nThis looks like a CLI flag, not a hex ID. Check flag syntax with --help.";
+      }
+    } else if (SPAN_ID_RE.test(normalized)) {
       // 16-char hex looks like a span ID
       message +=
         "\n\nThis looks like a span ID (16 characters). " +

test/commands/event/view.test.ts

@@ -787,8 +787,9 @@ describe("viewCommand.func", () => {
   let openInBrowserSpy: ReturnType<typeof spyOn>;
   let resolveProjectBySlugSpy: ReturnType<typeof spyOn>;
 
+  const VALID_EVENT_ID = "abc123def456abc123def456abc123de";
   const sampleEvent: SentryEvent = {
-    eventID: "abc123def456",
+    eventID: VALID_EVENT_ID,
     title: "Error: test",
     metadata: {},
     contexts: {},
@@ -833,11 +834,11 @@ describe("viewCommand.func", () => {
 
     const { context } = createMockContext();
     const func = await viewCommand.loader();
-    // "abc123def456" has no slash, "test-org/test-proj" has slash → swap detected
+    // Valid 32-char hex has no slash, "test-org/test-proj" has slash → swap detected
     await func.call(
       context,
       { json: true, web: false, spans: 0 },
-      "abc123def456",
+      VALID_EVENT_ID,
       "test-org/test-proj"
     );
 
@@ -904,13 +905,45 @@ describe("viewCommand.func", () => {
       context,
       { json: true, web: false, spans: 0 },
       "test_org/test_proj",
-      "abc123def456"
+      VALID_EVENT_ID
     );
 
     // parseOrgProjectArg normalizes "test_org/test_proj" → "test-org/test-proj"
     // and sets normalized=true, triggering the warning path (line 343-345)
     expect(getEventSpy).toHaveBeenCalled();
   });
+
+  test("throws ValidationError for flag-like event ID (--h)", async () => {
+    const { context } = createMockContext();
+    const func = await viewCommand.loader();
+
+    try {
+      await func.call(context, { json: false, web: false, spans: 0 }, "--h");
+      expect.unreachable("Should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ValidationError);
+      const msg = (error as ValidationError).message;
+      expect(msg).toContain("event ID");
+      expect(msg).toContain("looks like a help flag");
+    }
+  });
+
+  test("throws ValidationError for non-hex event ID", async () => {
+    const { context } = createMockContext();
+    const func = await viewCommand.loader();
+
+    try {
+      await func.call(
+        context,
+        { json: false, web: false, spans: 0 },
+        "not-a-hex-id"
+      );
+      expect.unreachable("Should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ValidationError);
+      expect((error as ValidationError).message).toContain("event ID");
+    }
+  });
 });
 
 describe("fetchEventWithContext", () => {

test/e2e/event.test.ts

@@ -52,7 +52,7 @@ describe("sentry event view", () => {
       "event",
       "view",
       `${TEST_ORG}/${TEST_PROJECT}`,
-      "abc123",
+      "abc123def456abc123def456abc123de",
     ]);
 
     expect(result.exitCode).toBe(1);
@@ -62,12 +62,27 @@ describe("sentry event view", () => {
   test("requires org and project without DSN", async () => {
     await ctx.setAuthToken(TEST_TOKEN);
 
-    const result = await ctx.run(["event", "view", "abc123"]);
+    const result = await ctx.run([
+      "event",
+      "view",
+      "abc123def456abc123def456abc123de",
+    ]);
 
     expect(result.exitCode).toBe(1);
     expect(result.stderr + result.stdout).toMatch(/organization|project/i);
   });
 
+  test("rejects invalid event ID format", async () => {
+    await ctx.setAuthToken(TEST_TOKEN);
+
+    const result = await ctx.run(["event", "view", "abc123"]);
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr + result.stdout).toMatch(
+      /invalid event id|32-character hexadecimal/i
+    );
+  });
+
   test("handles non-existent event", async () => {
     await ctx.setAuthToken(TEST_TOKEN);
 
@@ -76,7 +91,7 @@ describe("sentry event view", () => {
       "event",
       "view",
       `${TEST_ORG}/${TEST_PROJECT}`,
-      "nonexistent123",
+      "abc123def456abc123def456abc123de",
     ]);
 
     expect(result.exitCode).toBe(1);

test/lib/hex-id.test.ts

@@ -136,6 +136,54 @@ describe("validateHexId", () => {
     }
   });
 
+  test("error hints help flag for --h input", () => {
+    try {
+      validateHexId("--h", "event ID");
+      expect.unreachable("Should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ValidationError);
+      const msg = (error as ValidationError).message;
+      expect(msg).toContain("looks like a help flag");
+      expect(msg).toContain("--help or -h");
+    }
+  });
+
+  test("error hints help flag for -help input", () => {
+    try {
+      validateHexId("-help", "trace ID");
+      expect.unreachable("Should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ValidationError);
+      const msg = (error as ValidationError).message;
+      expect(msg).toContain("looks like a help flag");
+    }
+  });
+
+  test("error hints generic flag for --verbose input", () => {
+    try {
+      validateHexId("--verbose", "log ID");
+      expect.unreachable("Should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ValidationError);
+      const msg = (error as ValidationError).message;
+      expect(msg).toContain("looks like a CLI flag");
+      expect(msg).toContain("--help");
+    }
+  });
+
+  test("flag-like detection takes precedence over slug hint", () => {
+    try {
+      validateHexId("--my-flag", "event ID");
+      expect.unreachable("Should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ValidationError);
+      const msg = (error as ValidationError).message;
+      expect(msg).toContain("looks like a CLI flag");
+      // Should NOT suggest project slug
+      expect(msg).not.toContain("doesn't look like a hex ID");
+    }
+  });
+
   test("no extra hint for random-length hex (not a span ID)", () => {
     try {
       validateHexId("abc123", "log ID");