fix: improve error quality and prevent secrets leaking in telemetry

Three fixes targeting the highest-impact issues from the 0.11.0 release:

- fix(issue): include issue ID in 'not found' error and suggest short-ID
  format (CLI-N, 118 events / 41 users). Catches 404 from getIssue() in
  both the 'numeric' and 'explicit-org-numeric' resolveIssue() cases and
  re-throws a ContextError with the ID and a hint to try <project>-<id>.

- fix(telemetry): redact --token value from telemetry tags (CLI-19,
  security). setFlagContext() now replaces values of sensitive flags
  (currently: token) with '[REDACTED]' before calling Sentry.setTag().

- fix(issue list): validate --cursor format early (CLI-7H/7P/7B). Cursor
  values that are plain integers are now rejected at parse time with a
  message explaining the expected format. The --limit issue 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 =