refactor(formatters): extract shared number formatters, add sort aliases and session sparklines

- Extract compactFormatter, formatNumber, fmtPct, fmtCount, appendUnitSuffix,
  formatWithUnit, formatCompactWithUnit into src/lib/formatters/numbers.ts
- Update dashboard.ts to import from shared module (no behavior change)
- Delete src/commands/release/format.ts — replaced by shared module
- Add sort aliases: stable_sessions/cfs → crash_free_sessions,
  stable_users/cfu → crash_free_users
- Add SESSIONS sparkline column to release list table using health stats
  time-series data (same [timestamp, count] format as issue stats)
- Drop COMMITS column from list to make room for sparkline

Author: BYK

plugins/sentry-cli/skills/sentry-cli/references/release.md

@@ -17,7 +17,7 @@ List releases with adoption and health metrics
 
 **Flags:**
 - `-n, --limit <value> - Maximum number of releases to list - (default: "25")`
-- `-s, --sort <value> - Sort order: date, sessions, users, crash_free_sessions, crash_free_users - (default: "date")`
+- `-s, --sort <value> - Sort: date, sessions, users, crash_free_sessions (cfs), crash_free_users (cfu) - (default: "date")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

src/commands/release/format.ts

@@ -13,7 +13,9 @@ import {
 } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
 import { escapeMarkdownCell } from "../../lib/formatters/markdown.js";
+import { fmtPct } from "../../lib/formatters/numbers.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
+import { sparkline } from "../../lib/formatters/sparkline.js";
 import { type Column, formatTable } from "../../lib/formatters/table.js";
 import { formatRelativeTime } from "../../lib/formatters/time-utils.js";
 import {
@@ -28,7 +30,6 @@ import {
   type ListResult,
   type OrgListConfig,
 } from "../../lib/org-list.js";
-import { fmtPct } from "./format.js";
 
 export const PAGINATION_KEY = "release-list";
 
@@ -43,20 +44,40 @@ const VALID_SORT_VALUES: ReleaseSortValue[] = [
   "crash_free_users",
 ];
 
+/**
+ * Short aliases for sort values.
+ *
+ * Accepted alongside the canonical API values for convenience:
+ * - `stable_sessions` / `cfs` → `crash_free_sessions`
+ * - `stable_users` / `cfu` → `crash_free_users`
+ */
+const SORT_ALIASES: Record<string, ReleaseSortValue> = {
+  stable_sessions: "crash_free_sessions",
+  stable_users: "crash_free_users",
+  cfs: "crash_free_sessions",
+  cfu: "crash_free_users",
+};
+
 const DEFAULT_SORT: ReleaseSortValue = "date";
 
 /**
  * Parse and validate the `--sort` flag value.
  *
- * @throws Error when value is not one of the accepted sort keys
+ * Accepts canonical API values and short aliases.
+ * @throws Error when value is not recognized
  */
 function parseSortFlag(value: string): ReleaseSortValue {
   if (VALID_SORT_VALUES.includes(value as ReleaseSortValue)) {
     return value as ReleaseSortValue;
   }
-  throw new Error(
-    `Invalid sort value. Must be one of: ${VALID_SORT_VALUES.join(", ")}`
+  const alias = SORT_ALIASES[value];
+  if (alias) {
+    return alias;
+  }
+  const allAccepted = [...VALID_SORT_VALUES, ...Object.keys(SORT_ALIASES)].join(
+    ", "
   );
+  throw new Error(`Invalid sort value. Must be one of: ${allAccepted}`);
 }
 
 /**
@@ -69,6 +90,29 @@ function getHealthData(release: OrgReleaseResponse) {
   return release.projects?.find((p) => p.healthData?.hasHealthData)?.healthData;
 }
 
+/**
+ * Extract session time-series data points from health stats.
+ *
+ * The `stats` object follows the same `{ "<period>": [[ts, count], ...] }`
+ * shape as issue stats. Takes the first available key.
+ */
+function extractSessionPoints(stats?: Record<string, unknown>): number[] {
+  if (!stats) {
+    return [];
+  }
+  const key = Object.keys(stats)[0];
+  if (!key) {
+    return [];
+  }
+  const buckets = stats[key];
+  if (!Array.isArray(buckets)) {
+    return [];
+  }
+  return buckets.map((b: unknown) =>
+    Array.isArray(b) && b.length >= 2 ? Number(b[1]) || 0 : 0
+  );
+}
+
 const RELEASE_COLUMNS: Column<ReleaseWithOrg>[] = [
   { header: "ORG", value: (r) => r.orgSlug || "" },
   {
@@ -89,12 +133,24 @@ const RELEASE_COLUMNS: Column<ReleaseWithOrg>[] = [
     value: (r) => fmtPct(getHealthData(r)?.crashFreeSessions),
     align: "right",
   },
+  {
+    header: "SESSIONS",
+    value: (r) => {
+      const health = getHealthData(r);
+      if (!health) {
+        return "";
+      }
+      const points = extractSessionPoints(
+        health.stats as Record<string, unknown> | undefined
+      );
+      return points.length > 0 ? sparkline(points) : "";
+    },
+  },
   {
     header: "ISSUES",
     value: (r) => String(r.newGroups ?? 0),
     align: "right",
   },
-  { header: "COMMITS", value: (r) => String(r.commitCount ?? 0) },
   { header: "DEPLOYS", value: (r) => String(r.deployCount ?? 0) },
 ];
 
@@ -168,8 +224,8 @@ export const listCommand = buildListCommand("release", {
       "  date                 # by creation date (default)\n" +
       "  sessions             # by total sessions\n" +
       "  users                # by total users\n" +
-      "  crash_free_sessions  # by crash-free session rate\n" +
-      "  crash_free_users     # by crash-free user rate\n\n" +
+      "  crash_free_sessions  # by crash-free session rate (aliases: stable_sessions, cfs)\n" +
+      "  crash_free_users     # by crash-free user rate (aliases: stable_users, cfu)\n\n" +
       "Target specification:\n" +
       "  sentry release list               # auto-detect from DSN or config\n" +
       "  sentry release list <org>/        # list all releases in org (paginated)\n" +
@@ -199,7 +255,7 @@ export const listCommand = buildListCommand("release", {
         kind: "parsed" as const,
         parse: parseSortFlag,
         brief:
-          "Sort order: date, sessions, users, crash_free_sessions, crash_free_users",
+          "Sort: date, sessions, users, crash_free_sessions (cfs), crash_free_users (cfu)",
         default: DEFAULT_SORT,
       },
     },

src/commands/release/list.ts

@@ -19,6 +19,7 @@ import {
   renderMarkdown,
   safeCodeSpan,
 } from "../../lib/formatters/markdown.js";
+import { fmtCount, fmtPct } from "../../lib/formatters/numbers.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { formatRelativeTime } from "../../lib/formatters/time-utils.js";
 import {
@@ -27,7 +28,6 @@ import {
   FRESH_FLAG,
 } from "../../lib/list-command.js";
 import { resolveOrg } from "../../lib/resolve-target.js";
-import { fmtCount, fmtPct } from "./format.js";
 import { parseReleaseArg } from "./parse.js";
 
 /** Format a crash-free rate with color coding (green ≥ 99, yellow ≥ 95, red < 95). */

src/commands/release/view.ts

@@ -330,24 +330,15 @@ function calcGlyphWidth(formatted: string, glyphW: number): number {
 }
 
 // ---------------------------------------------------------------------------
-// Number formatting
+// Number formatting — shared helpers live in numbers.ts, dashboard-only
+// helpers remain here.
 // ---------------------------------------------------------------------------
 
-const compactFormatter = new Intl.NumberFormat("en-US", {
-  notation: "compact",
-  maximumFractionDigits: 1,
-});
-
-const standardFormatter = new Intl.NumberFormat("en-US", {
-  maximumFractionDigits: 2,
-});
-
-function formatNumber(value: number): string {
-  if (Math.abs(value) >= 1_000_000) {
-    return compactFormatter.format(value);
-  }
-  return standardFormatter.format(value);
-}
+import {
+  compactFormatter,
+  formatCompactWithUnit,
+  formatWithUnit,
+} from "./numbers.js";
 
 /**
  * Format a value as a short Y-axis tick label (max ~4 chars).
@@ -376,32 +367,6 @@ function formatBigNumberValue(value: number): string {
   return Math.round(value).toString();
 }
 
-/** Append unit suffix to a pre-formatted number string. */
-function appendUnitSuffix(formatted: string, unit?: string | null): string {
-  if (!unit || unit === "none" || unit === "null") {
-    return formatted;
-  }
-  if (unit === "millisecond") {
-    return `${formatted}ms`;
-  }
-  if (unit === "second") {
-    return `${formatted}s`;
-  }
-  if (unit === "byte") {
-    return `${formatted}B`;
-  }
-  return `${formatted} ${unit}`;
-}
-
-function formatWithUnit(value: number, unit?: string | null): string {
-  return appendUnitSuffix(formatNumber(value), unit);
-}
-
-/** Format a number with unit using compact notation (K/M/B). */
-function formatCompactWithUnit(value: number, unit?: string | null): string {
-  return appendUnitSuffix(compactFormatter.format(Math.round(value)), unit);
-}
-
 // ---------------------------------------------------------------------------
 // Sort helper: descending by value, "Other" always last
 // ---------------------------------------------------------------------------

src/lib/formatters/dashboard.ts

@@ -10,6 +10,7 @@ export * from "./human.js";
 export * from "./json.js";
 export * from "./log.js";
 export * from "./markdown.js";
+export * from "./numbers.js";
 export * from "./output.js";
 export * from "./seer.js";
 export * from "./sparkline.js";

src/lib/formatters/index.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared number formatting utilities.
+ *
+ * Provides compact notation (K/M/B), percentage formatting, and unit
+ * suffixing used across dashboard, release, and other command formatters.
+ *
+ * Uses `Intl.NumberFormat` for locale-aware compact notation.
+ */
+
+/**
+ * Compact notation formatter: 52000 → "52K", 1.2M, etc.
+ * One fractional digit maximum.
+ */
+export const compactFormatter = new Intl.NumberFormat("en-US", {
+  notation: "compact",
+  maximumFractionDigits: 1,
+});
+
+/**
+ * Standard notation formatter with thousands separators.
+ * Two fractional digits maximum: 1234.5 → "1,234.5".
+ */
+export const standardFormatter = new Intl.NumberFormat("en-US", {
+  maximumFractionDigits: 2,
+});
+
+/**
+ * Format a number with standard notation, switching to compact above 1M.
+ *
+ * - Below 1M: standard grouping (e.g., "52,000", "1,234.5")
+ * - At or above 1M: compact (e.g., "1.2M", "52M")
+ *
+ * @example formatNumber(1234)    // "1,234"
+ * @example formatNumber(1500000) // "1.5M"
+ */
+export function formatNumber(value: number): string {
+  if (Math.abs(value) >= 1_000_000) {
+    return compactFormatter.format(value);
+  }
+  return standardFormatter.format(value);
+}
+
+/**
+ * Format a number in compact notation (always uses K/M/B suffixes).
+ *
+ * @example formatCompactCount(500)     // "500"
+ * @example formatCompactCount(52000)   // "52K"
+ * @example formatCompactCount(1200000) // "1.2M"
+ */
+export function formatCompactCount(value: number): string {
+  return compactFormatter.format(value);
+}
+
+/**
+ * Append a unit suffix to a pre-formatted number string.
+ *
+ * Handles common Sentry unit names: "millisecond" → "ms",
+ * "second" → "s", "byte" → "B". Unknown units are appended with a space.
+ * Returns the number unchanged for "none"/"null"/empty units.
+ */
+export function appendUnitSuffix(
+  formatted: string,
+  unit?: string | null
+): string {
+  if (!unit || unit === "none" || unit === "null") {
+    return formatted;
+  }
+  if (unit === "millisecond") {
+    return `${formatted}ms`;
+  }
+  if (unit === "second") {
+    return `${formatted}s`;
+  }
+  if (unit === "byte") {
+    return `${formatted}B`;
+  }
+  return `${formatted} ${unit}`;
+}
+
+/**
+ * Format a number with its unit, using standard/compact notation.
+ *
+ * @example formatWithUnit(1234, "millisecond") // "1,234ms"
+ * @example formatWithUnit(1500000, "byte")     // "1.5MB"
+ */
+export function formatWithUnit(value: number, unit?: string | null): string {
+  return appendUnitSuffix(formatNumber(value), unit);
+}
+
+/**
+ * Format a number with its unit, always using compact notation.
+ *
+ * @example formatCompactWithUnit(52000, "byte") // "52KB"
+ */
+export function formatCompactWithUnit(
+  value: number,
+  unit?: string | null
+): string {
+  return appendUnitSuffix(compactFormatter.format(Math.round(value)), unit);
+}
+
+/**
+ * Format a percentage value with one decimal place, or "—" when absent.
+ *
+ * @example fmtPct(42.3) // "42.3%"
+ * @example fmtPct(null) // "—"
+ */
+export function fmtPct(value: number | null | undefined): string {
+  if (value === null || value === undefined) {
+    return "—";
+  }
+  return `${value.toFixed(1)}%`;
+}
+
+/**
+ * Format an integer count in compact notation, or "—" when absent.
+ *
+ * Values below 1000 are shown as-is. Above that, uses K/M/B suffixes.
+ *
+ * @example fmtCount(500)     // "500"
+ * @example fmtCount(52000)   // "52K"
+ * @example fmtCount(1200000) // "1.2M"
+ * @example fmtCount(null)    // "—"
+ */
+export function fmtCount(value: number | null | undefined): string {
+  if (value === null || value === undefined) {
+    return "—";
+  }
+  return compactFormatter.format(value);
+}