refactor: address human reviewer feedback on span commands

- Move validateSpanId to shared hex-id.ts (reuses pattern from validateHexId)
  with automatic dash-stripping for span IDs
- Remove MIN_LIMIT constant — inline the value 1 in parseLimit call
- Add JSDoc to MAX_LIMIT explaining it's a CLI-side convention (1000)
  matching issue list, trace list, and log list caps
- Extract DEFAULT_SORT constant for sort flag default
- Remove '(default)' from sort brief — Stricli shows defaults automatically
- Update USAGE_HINT and fullDescription to use slash-separated format:
  sentry span list <org>/<project>/<trace-id>
- Update resolveProjectBySlug suggestion to slash format

Author: BYK

src/commands/span/list.ts

@@ -48,21 +48,31 @@ type SortValue = "time" | "duration";
 /** Accepted values for the --sort flag */
 const VALID_SORT_VALUES: SortValue[] = ["time", "duration"];
 
-/** Maximum allowed value for --limit flag */
+/**
+ * CLI-side upper bound for --limit.
+ *
+ * The Sentry Events API (spans dataset) accepts `per_page` up to 100 per
+ * request, but the CLI allows requesting up to 1000 as a convenience —
+ * the API client paginates internally when needed. This matches the cap
+ * used by `issue list`, `trace list`, and `log list`.
+ */
 const MAX_LIMIT = 1000;
 
-/** Minimum allowed value for --limit flag */
-const MIN_LIMIT = 1;
-
 /** Default number of spans to show */
 const DEFAULT_LIMIT = 25;
 
+/** Default sort order for span results */
+const DEFAULT_SORT: SortValue = "time";
+
 /** Usage hint for ContextError messages */
-const USAGE_HINT = "sentry span list [<org>/<project>] <trace-id>";
+const USAGE_HINT = "sentry span list [<org>/<project>/]<trace-id>";
 
 /**
  * Parse positional arguments for span list.
- * Handles: `<trace-id>` or `<target> <trace-id>`
+ * Handles: `<trace-id>` or `<org>/<project>/<trace-id>`
+ *
+ * Uses the standard `parseSlashSeparatedArg` pattern: the last `/`-separated
+ * segment is the trace ID, and everything before it is the org/project target.
  *
  * @param args - Positional arguments from CLI
  * @returns Parsed trace ID and optional target arg
@@ -104,7 +114,7 @@ export function parsePositionalArgs(args: string[]): {
  * Parse --limit flag, delegating range validation to shared utility.
  */
 function parseLimit(value: string): number {
-  return validateLimit(value, MIN_LIMIT, MAX_LIMIT);
+  return validateLimit(value, 1, MAX_LIMIT);
 }
 
 /**
@@ -171,16 +181,16 @@ export const listCommand = buildCommand({
     fullDescription:
       "List spans in a distributed trace with optional filtering and sorting.\n\n" +
       "Target specification:\n" +
-      "  sentry span list <trace-id>              # auto-detect from DSN or config\n" +
-      "  sentry span list <org>/<proj> <trace-id> # explicit org and project\n" +
-      "  sentry span list <project> <trace-id>    # find project across all orgs\n\n" +
+      "  sentry span list <trace-id>                       # auto-detect from DSN or config\n" +
+      "  sentry span list <org>/<project>/<trace-id>       # explicit org and project\n" +
+      "  sentry span list <project> <trace-id>             # find project across all orgs\n\n" +
       "The trace ID is the 32-character hexadecimal identifier.\n\n" +
       "Examples:\n" +
-      "  sentry span list <trace-id>                      # List spans in trace\n" +
-      "  sentry span list <trace-id> --limit 50           # Show more spans\n" +
-      '  sentry span list <trace-id> -q "op:db"           # Filter by operation\n' +
-      "  sentry span list <trace-id> --sort duration      # Sort by slowest first\n" +
-      '  sentry span list <trace-id> -q "duration:>100ms" # Spans slower than 100ms',
+      "  sentry span list <trace-id>                       # List spans in trace\n" +
+      "  sentry span list <trace-id> --limit 50            # Show more spans\n" +
+      '  sentry span list <trace-id> -q "op:db"            # Filter by operation\n' +
+      "  sentry span list <trace-id> --sort duration       # Sort by slowest first\n" +
+      '  sentry span list <trace-id> -q "duration:>100ms"  # Spans slower than 100ms',
   },
   output: {
     human: formatSpanListHuman,
@@ -200,7 +210,7 @@ export const listCommand = buildCommand({
       limit: {
         kind: "parsed",
         parse: parseLimit,
-        brief: `Number of spans (${MIN_LIMIT}-${MAX_LIMIT})`,
+        brief: `Number of spans (1-${MAX_LIMIT})`,
         default: String(DEFAULT_LIMIT),
       },
       query: {
@@ -213,8 +223,8 @@ export const listCommand = buildCommand({
       sort: {
         kind: "parsed",
         parse: parseSort,
-        brief: "Sort by: time (default), duration",
-        default: "time" as const,
+        brief: `Sort order: ${VALID_SORT_VALUES.join(", ")}`,
+        default: DEFAULT_SORT,
       },
       fresh: FRESH_FLAG,
     },
@@ -249,7 +259,7 @@ export const listCommand = buildCommand({
         target = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry span list <org>/${parsed.projectSlug} ${traceId}`
+          `sentry span list <org>/${parsed.projectSlug}/${traceId}`
         );
         break;
 

src/commands/span/view.ts

@@ -22,6 +22,7 @@ import {
 import { filterFields } from "../../lib/formatters/json.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { computeSpanDurationMs } from "../../lib/formatters/trace.js";
+import { validateSpanId } from "../../lib/hex-id.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -43,31 +44,10 @@ type ViewFlags = {
   readonly fields?: string[];
 };
 
-/** Regex for a 16-character hex span ID */
-const SPAN_ID_RE = /^[0-9a-f]{16}$/i;
-
 /** Usage hint for ContextError messages */
 const USAGE_HINT =
   "sentry span view [<org>/<project>/]<trace-id> <span-id> [<span-id>...]";
 
-/**
- * Validate that a string is a 16-character hexadecimal span ID.
- *
- * @param value - The string to validate
- * @returns The trimmed, lowercased span ID
- * @throws {ValidationError} If the format is invalid
- */
-export function validateSpanId(value: string): string {
-  const trimmed = value.trim().toLowerCase();
-  if (!SPAN_ID_RE.test(trimmed)) {
-    throw new ValidationError(
-      `Invalid span ID "${trimmed}". Expected a 16-character hexadecimal string.\n\n` +
-        "Example: a1b2c3d4e5f67890"
-    );
-  }
-  return trimmed;
-}
-
 /**
  * Parse positional arguments for span view.
  *

src/lib/hex-id.ts

@@ -1,15 +1,18 @@
 /**
  * Shared Hex ID Validation
  *
- * Provides regex and validation for 32-character hexadecimal identifiers
- * used across the CLI (log IDs, trace IDs, etc.).
+ * Provides regex and validation for hexadecimal identifiers used across
+ * the CLI (trace IDs, log IDs, span IDs, etc.).
  */
 
 import { ValidationError } from "./errors.js";
 
 /** Regex for a valid 32-character hexadecimal ID */
 export const HEX_ID_RE = /^[0-9a-f]{32}$/i;
 
+/** Regex for a valid 16-character hexadecimal span ID */
+export const SPAN_ID_RE = /^[0-9a-f]{16}$/i;
+
 /**
  * Regex for UUID format with dashes: 8-4-4-4-12 hex groups.
  * Users often copy trace/log IDs from tools that display them in UUID format.
@@ -61,3 +64,31 @@ export function validateHexId(value: string, label: string): string {
 
   return trimmed;
 }
+
+/**
+ * Validate that a string is a 16-character hexadecimal span ID.
+ * Trims whitespace and normalizes to lowercase before validation.
+ *
+ * Dashes are stripped automatically so users can paste IDs in dash-separated
+ * formats (e.g., from debugging tools that format span IDs with dashes).
+ *
+ * @param value - The string to validate
+ * @returns The trimmed, lowercased, validated span ID
+ * @throws {ValidationError} If the format is invalid
+ */
+export function validateSpanId(value: string): string {
+  const trimmed = value.trim().toLowerCase().replace(/-/g, "");
+
+  if (!SPAN_ID_RE.test(trimmed)) {
+    const display =
+      trimmed.length > MAX_DISPLAY_LENGTH
+        ? `${trimmed.slice(0, MAX_DISPLAY_LENGTH - 3)}...`
+        : trimmed;
+    throw new ValidationError(
+      `Invalid span ID "${display}". Expected a 16-character hexadecimal string.\n\n` +
+        "Example: a1b2c3d4e5f67890"
+    );
+  }
+
+  return trimmed;
+}

test/commands/span/view.test.ts

@@ -16,12 +16,12 @@ import {
 } from "bun:test";
 import {
   parsePositionalArgs,
-  validateSpanId,
   viewCommand,
 } from "../../../src/commands/span/view.js";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
 import * as apiClient from "../../../src/lib/api-client.js";
 import { ContextError, ValidationError } from "../../../src/lib/errors.js";
+import { validateSpanId } from "../../../src/lib/hex-id.js";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
 import * as resolveTarget from "../../../src/lib/resolve-target.js";