fix: improve error quality and prevent token leak in telemetry (#279)

## Summary

Fixes three of the highest-impact issues from the 0.11.0 release
(sourced from Sentry production data).

### fix(issue): actionable error when issue not found by numeric ID
(CLI-N)
**118 events / 41 users**

`getIssue()` surfaces a bare 404 as a generic message with no indication
of which ID failed. Users often confuse numeric Sentry group IDs (which
require access) with short-ID suffixes (which are human-readable).

Now `resolveIssue()` catches the 404 in both the `numeric` and
`explicit-org-numeric` cases and re-throws a `ContextError` with:
- The exact ID that wasn't found
- A note that access may be missing or the issue may be deleted
- A suggestion to try the `<project>-<id>` short-ID format

### fix(telemetry): redact `--token` value from telemetry tags (CLI-19)
**Security — token values were being sent to Sentry**

`setFlagContext()` in `telemetry.ts` was forwarding the raw value of
every flag as a `flag.<name>` tag. For `sentry auth login --token
sntrys_...`, this meant the actual API token was appearing in the
`flag.token` tag on every telemetry event.

Adds a `SENSITIVE_FLAGS` set (currently: `token`) and replaces those tag
values with `[REDACTED]` before the tag is set.

### fix(issue list): validate `--cursor` format before hitting the API
(CLI-7H/7P/7B)
**21 events / 12 users — 400 Bad Request from API**

`--cursor 100` (a plain integer) was forwarded directly to the API,
which rejects it. Cursor values are opaque strings like
`1735689600:0:0`. Plain-integer inputs are now rejected at parse time
with a message explaining the expected format.

Note: the `--limit` part of this bug is already addressed on main via
auto-pagination (#274).

Author: BYK

.gitignore

@@ -40,6 +40,9 @@ docs/dist
 docs/node_modules
 docs/.astro
 
+# local planning notes (not for version control)
+.plans
+
 # IntelliJ based IDEs
 .idea
 

src/commands/issue/list.ts

@@ -83,6 +83,9 @@ const VALID_SORT_VALUES: SortValue[] = ["date", "new", "freq", "user"];
 /** Usage hint for ContextError messages */
 const USAGE_HINT = "sentry issue list <org>/<project>";
 
+/** Matches strings that are all digits — used to detect invalid cursor values */
+const ALL_DIGITS_RE = /^\d+$/;
+
 /**
  * Maximum --limit value (user-facing ceiling for practical CLI response times).
  * Auto-pagination can theoretically fetch more, but 1000 keeps responses reasonable.
@@ -733,7 +736,21 @@ export const listCommand = buildCommand({
       json: LIST_JSON_FLAG,
       cursor: {
         kind: "parsed",
-        parse: String,
+        parse: (value: string) => {
+          // "last" is the magic keyword to resume from the saved cursor
+          if (value === "last") {
+            return value;
+          }
+          // Sentry pagination cursors are opaque strings like "1735689600:0:0".
+          // Plain integers are not valid cursors — catch this early so the user
+          // gets a clear error rather than a cryptic 400 from the API.
+          if (ALL_DIGITS_RE.test(value)) {
+            throw new Error(
+              `'${value}' is not a valid cursor. Cursors look like "1735689600:0:0". Use "last" to continue from the previous page.`
+            );
+          }
+          return value;
+        },
         // Issue-specific cursor brief: cursor only works in <org>/ mode
         brief:
           'Pagination cursor — only for <org>/ mode (use "last" to continue)',

src/commands/issue/utils.ts

@@ -14,7 +14,7 @@ import {
 import { parseIssueArg } from "../../lib/arg-parsing.js";
 import { getProjectByAlias } from "../../lib/db/project-aliases.js";
 import { detectAllDsns } from "../../lib/dsn/index.js";
-import { ContextError } from "../../lib/errors.js";
+import { ApiError, ContextError } from "../../lib/errors.js";
 import { getProgressMessage } from "../../lib/formatters/seer.js";
 import { expandToFullShortId, isShortSuffix } from "../../lib/issue-id.js";
 import { poll } from "../../lib/polling.js";
@@ -255,8 +255,21 @@ export async function resolveIssue(
   switch (parsed.type) {
     case "numeric": {
       // Direct fetch by numeric ID - no org context
-      const issue = await getIssue(parsed.id);
-      return { org: undefined, issue };
+      try {
+        const issue = await getIssue(parsed.id);
+        return { org: undefined, issue };
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+          // Improve on the generic "Issue not found" message by including the ID
+          // and suggesting the short-ID format, since users often confuse numeric
+          // group IDs with short-ID suffixes.
+          throw new ContextError(`Issue ${parsed.id}`, commandHint, [
+            `No issue with numeric ID ${parsed.id} found — you may not have access, or it may have been deleted.`,
+            `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.id}`,
+          ]);
+        }
+        throw err;
+      }
     }
 
     case "explicit": {
@@ -268,8 +281,18 @@ export async function resolveIssue(
 
     case "explicit-org-numeric": {
       // Org + numeric ID
-      const issue = await getIssue(parsed.numericId);
-      return { org: parsed.org, issue };
+      try {
+        const issue = await getIssue(parsed.numericId);
+        return { org: parsed.org, issue };
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+          throw new ContextError(`Issue ${parsed.numericId}`, commandHint, [
+            `No issue with numeric ID ${parsed.numericId} found in org '${parsed.org}' — you may not have access, or it may have been deleted.`,
+            `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.numericId}`,
+          ]);
+        }
+        throw err;
+      }
     }
 
     case "explicit-org-suffix":

src/lib/telemetry.ts

@@ -362,6 +362,12 @@ export function setOrgProjectContext(orgs: string[], projects: string[]): void {
   }
 }
 
+/**
+ * Flag names whose values must never be sent to telemetry.
+ * Values for these flags are replaced with "[REDACTED]" regardless of content.
+ */
+const SENSITIVE_FLAGS = new Set(["token"]);
+
 /**
  * Set command flags as telemetry tags.
  *
@@ -373,6 +379,9 @@ export function setOrgProjectContext(orgs: string[], projects: string[]): void {
  * - String/number flags: only when defined and non-empty
  * - Array flags: only when non-empty
  *
+ * Sensitive flags (e.g., `--token`) have their values replaced with
+ * "[REDACTED]" to prevent secrets from reaching telemetry.
+ *
  * Call this at the start of command func() to instrument flag usage.
  *
  * @param flags - The parsed flags object from Stricli
@@ -410,6 +419,12 @@ export function setFlagContext(flags: Record<string, unknown>): void {
     // Convert camelCase to kebab-case for consistency with CLI flag names
     const kebabKey = key.replace(/([A-Z])/g, "-$1").toLowerCase();
 
+    // Redact sensitive flag values (e.g., API tokens) — never send secrets to telemetry
+    if (SENSITIVE_FLAGS.has(kebabKey)) {
+      Sentry.setTag(`flag.${kebabKey}`, "[REDACTED]");
+      continue;
+    }
+
     // Set the tag with flag. prefix
     // For booleans, just set "true"; for other types, convert to string
     const tagValue =

test/commands/issue/list.test.ts

@@ -635,3 +635,30 @@ describe("issue list: org-all mode (cursor pagination)", () => {
     );
   });
 });
+
+describe("issue list: cursor flag parse validation", () => {
+  // Access the parse function directly from the command's flag definition.
+  // This tests the validation without needing a full command invocation.
+  const parseCursor = (
+    listCommand.parameters.flags!.cursor as { parse: (v: string) => string }
+  ).parse;
+
+  test('accepts "last" keyword', () => {
+    expect(parseCursor("last")).toBe("last");
+  });
+
+  test("accepts valid opaque cursor strings", () => {
+    expect(parseCursor("1735689600:0:0")).toBe("1735689600:0:0");
+    expect(parseCursor("1735689600:0:1")).toBe("1735689600:0:1");
+    expect(parseCursor("abc:def:ghi")).toBe("abc:def:ghi");
+  });
+
+  test("rejects plain integer cursors with descriptive error", () => {
+    expect(() => parseCursor("100")).toThrow("not a valid cursor");
+    expect(() => parseCursor("100")).toThrow("1735689600:0:0");
+  });
+
+  test("error message includes the invalid value passed", () => {
+    expect(() => parseCursor("5000")).toThrow("'5000'");
+  });
+});

test/commands/issue/utils.test.ts

@@ -9,11 +9,13 @@ import {
   buildCommandHint,
   ensureRootCauseAnalysis,
   pollAutofixState,
+  resolveIssue,
   resolveOrgAndIssueId,
 } from "../../../src/commands/issue/utils.js";
 import { DEFAULT_SENTRY_URL } from "../../../src/lib/constants.js";
 import { setAuthToken } from "../../../src/lib/db/auth.js";
 import { setOrgRegion } from "../../../src/lib/db/regions.js";
+import { ContextError } from "../../../src/lib/errors.js";
 import { useTestConfigDir } from "../../helpers.js";
 
 describe("buildCommandHint", () => {
@@ -1267,3 +1269,97 @@ describe("ensureRootCauseAnalysis", () => {
     expect(stderrOutput).toContain("root cause analysis");
   });
 });
+
+describe("resolveIssue: numeric 404 error handling", () => {
+  const getResolveIssueConfigDir = useTestConfigDir("test-resolve-issue-");
+
+  let savedFetch: typeof globalThis.fetch;
+
+  beforeEach(async () => {
+    savedFetch = globalThis.fetch;
+    await setAuthToken("test-token");
+    await setOrgRegion("my-org", DEFAULT_SENTRY_URL);
+  });
+
+  afterEach(() => {
+    globalThis.fetch = savedFetch;
+  });
+
+  test("numeric 404 throws ContextError with ID and short-ID hint", async () => {
+    // @ts-expect-error - partial mock
+    globalThis.fetch = async () =>
+      new Response(JSON.stringify({ detail: "Issue not found" }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+      });
+
+    const err = await resolveIssue({
+      issueArg: "123456789",
+      cwd: getResolveIssueConfigDir(),
+      command: "view",
+    }).catch((e) => e);
+
+    expect(err).toBeInstanceOf(ContextError);
+    // Message includes the numeric ID
+    expect(String(err)).toContain("123456789");
+    // Suggests the short-ID format
+    expect(String(err)).toContain("project>-123456789");
+  });
+
+  test("numeric non-404 error propagates unchanged", async () => {
+    // @ts-expect-error - partial mock
+    globalThis.fetch = async () =>
+      new Response(JSON.stringify({ detail: "Internal Server Error" }), {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      });
+
+    await expect(
+      resolveIssue({
+        issueArg: "123456789",
+        cwd: getResolveIssueConfigDir(),
+        command: "view",
+      })
+    ).rejects.not.toBeInstanceOf(ContextError);
+  });
+
+  test("explicit-org-numeric 404 throws ContextError with org and ID", async () => {
+    // @ts-expect-error - partial mock
+    globalThis.fetch = async () =>
+      new Response(JSON.stringify({ detail: "Issue not found" }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+      });
+
+    const err = await resolveIssue({
+      issueArg: "my-org/999999999",
+      cwd: getResolveIssueConfigDir(),
+      command: "view",
+    }).catch((e) => e);
+
+    expect(err).toBeInstanceOf(ContextError);
+    // Message includes the numeric ID
+    expect(String(err)).toContain("999999999");
+    // Message mentions the org
+    expect(String(err)).toContain("my-org");
+    // Suggests the short-ID format
+    expect(String(err)).toContain("project>-999999999");
+  });
+
+  test("explicit-org-numeric non-404 error propagates unchanged", async () => {
+    // @ts-expect-error - partial mock
+    globalThis.fetch = async () =>
+      new Response(JSON.stringify({ detail: "Unauthorized" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      });
+
+    await expect(
+      resolveIssue({
+        issueArg: "my-org/999999999",
+        cwd: getResolveIssueConfigDir(),
+        command: "view",
+      })
+    ).rejects.not.toBeInstanceOf(ContextError);
+  });
+});

test/lib/telemetry.test.ts

@@ -411,6 +411,27 @@ describe("setFlagContext", () => {
     expect(setTagSpy).toHaveBeenCalledTimes(1);
     expect(setTagSpy).toHaveBeenCalledWith("flag.long-flag", "x".repeat(200));
   });
+
+  test("redacts sensitive flag values (token)", () => {
+    setFlagContext({
+      token: "sntrys_eyJpYXQiOjE3MDAwMDAwMDAsImF1dGhUb2tlbiI6InNlY3JldCJ9",
+    });
+    expect(setTagSpy).toHaveBeenCalledTimes(1);
+    expect(setTagSpy).toHaveBeenCalledWith("flag.token", "[REDACTED]");
+  });
+
+  test("still sets the tag when token flag is present (presence is useful signal)", () => {
+    setFlagContext({ token: "any-token-value" });
+    // The tag is set (so we know --token was used), but the value is redacted
+    expect(setTagSpy).toHaveBeenCalledWith("flag.token", "[REDACTED]");
+  });
+
+  test("does not redact non-sensitive flags alongside token", () => {
+    setFlagContext({ token: "secret", format: "json" });
+    expect(setTagSpy).toHaveBeenCalledTimes(2);
+    expect(setTagSpy).toHaveBeenCalledWith("flag.token", "[REDACTED]");
+    expect(setTagSpy).toHaveBeenCalledWith("flag.format", "json");
+  });
 });
 
 describe("setArgsContext", () => {