feat(trial): add sentry trial list/start commands

- Add standalone trial commands: sentry trial list, sentry trial start
- Rename getSeerTrialStatus → getProductTrials (returns ProductTrial[])
- Rename startSeerTrial → startProductTrial (generic category param)
- Add src/lib/trials.ts with trial name mapping and status helpers
- Add swap detection for trial start args (org/name order)
- Update SeerError messages to hint at trial commands
- Refactor seer-trial.ts to use shared trial infrastructure
- Fix getTrialDisplayName bug: add getDisplayNameForTrialName for CLI names
- Add comprehensive tests (80 tests across 5 files)

Author: BYK

AGENTS.md

@@ -643,6 +643,9 @@ mock.module("./some-module", () => ({
 <!-- lore:019c972c-9f0f-75cd-9e24-9bdbb1ac03d6 -->
 * **Numeric issue ID resolution returns org:undefined despite API success**: Numeric issue ID resolution in \`resolveNumericIssue()\`: (1) try DSN/env/config for org, (2) if found use \`getIssueInOrg(org, id)\` with region routing, (3) else fall back to unscoped \`getIssue(id)\`, (4) extract org from \`issue.permalink\` via \`parseSentryUrl\` as final fallback. \`parseSentryUrl\` handles path-based (\`/organizations/{org}/...\`) and subdomain-style URLs. \`matchSubdomainOrg()\` filters region subdomains by requiring slug length > 2. Self-hosted uses path-based only.
 
+<!-- lore:019ce0bb-f35d-7380-b661-8dc56f9938cf -->
+* **Seer trial prompt uses middleware layering in bin.ts error handling chain**: The CLI's error recovery middlewares in \`bin.ts\` are layered: \`main() → executeWithAutoAuth() → executeWithSeerTrialPrompt() → runCommand()\`. Seer trial prompts (for \`no\_budget\`/\`not\_enabled\` errors) are caught by the inner wrapper; auth errors bubble up to the outer wrapper. After successful auth login retry, the retry also goes through \`executeWithSeerTrialPrompt\` (not \`runCommand\` directly) so the full middleware chain applies. Trial check API: \`GET /api/0/customers/{org}/\` → \`productTrials\[]\` (prefer \`seerUsers\`, fallback \`seerAutofix\`). Start trial: \`PUT /api/0/customers/{org}/product-trial/\`. The \`/customers/\` endpoint is getsentry SaaS-only; self-hosted 404s gracefully. \`ai\_disabled\` errors are excluded (admin's explicit choice). \`startSeerTrial\` accepts \`category\` from the trial object — don't hardcode it.
+
 ### Decision
 
 <!-- lore:019c99d5-69f2-74eb-8c86-411f8512801d -->

src/app.ts

@@ -28,6 +28,8 @@ import { teamRoute } from "./commands/team/index.js";
 import { listCommand as teamListCommand } from "./commands/team/list.js";
 import { traceRoute } from "./commands/trace/index.js";
 import { listCommand as traceListCommand } from "./commands/trace/list.js";
+import { trialRoute } from "./commands/trial/index.js";
+import { listCommand as trialListCommand } from "./commands/trial/list.js";
 import { CLI_VERSION } from "./lib/constants.js";
 import {
   AuthError,
@@ -49,6 +51,7 @@ const PLURAL_TO_SINGULAR: Record<string, string> = {
   teams: "team",
   logs: "log",
   traces: "trace",
+  trials: "trial",
 };
 
 /** Top-level route map containing all CLI commands */
@@ -65,6 +68,7 @@ export const routes = buildRouteMap({
     event: eventRoute,
     log: logRoute,
     trace: traceRoute,
+    trial: trialRoute,
     init: initCommand,
     api: apiCommand,
     issues: issueListCommand,
@@ -74,6 +78,7 @@ export const routes = buildRouteMap({
     teams: teamListCommand,
     logs: logListCommand,
     traces: traceListCommand,
+    trials: trialListCommand,
     whoami: whoamiCommand,
   },
   defaultCommand: "help",

src/commands/trial/index.ts

@@ -0,0 +1,15 @@
+import { buildRouteMap } from "@stricli/core";
+import { listCommand } from "./list.js";
+import { startCommand } from "./start.js";
+
+export const trialRoute = buildRouteMap({
+  routes: {
+    list: listCommand,
+    start: startCommand,
+  },
+  docs: {
+    brief: "Manage product trials",
+    fullDescription: "List and start product trials for your organization.",
+    hideRoute: {},
+  },
+});

src/commands/trial/list.ts

@@ -0,0 +1,160 @@
+/**
+ * sentry trial list
+ *
+ * List product trials available to an organization, including
+ * active trials with time remaining and expired trials.
+ */
+
+import type { SentryContext } from "../../context.js";
+import { getProductTrials } from "../../lib/api-client.js";
+import { buildCommand } from "../../lib/command.js";
+import { ContextError } from "../../lib/errors.js";
+import { colorTag } from "../../lib/formatters/markdown.js";
+import { type Column, writeTable } from "../../lib/formatters/table.js";
+import { resolveOrg } from "../../lib/resolve-target.js";
+import {
+  getDaysRemaining,
+  getTrialDisplayName,
+  getTrialFriendlyName,
+  getTrialStatus,
+  type TrialStatus,
+} from "../../lib/trials.js";
+import type { Writer } from "../../types/index.js";
+
+type ListFlags = {
+  readonly json: boolean;
+  readonly fields?: string[];
+};
+
+/**
+ * Enriched trial entry for display.
+ * Adds derived fields (name, displayName, status, daysRemaining) to the raw API data.
+ */
+type TrialListEntry = {
+  /** CLI-friendly name (e.g., "seer") */
+  name: string;
+  /** Human-readable product name (e.g., "Seer") */
+  displayName: string;
+  /** API category name (e.g., "seerUsers") */
+  category: string;
+  /** Derived status */
+  status: TrialStatus;
+  /** Days remaining for active trials, null otherwise */
+  daysRemaining: number | null;
+  /** Raw isStarted flag from API */
+  isStarted: boolean;
+  /** Trial length in days, null if not set */
+  lengthDays: number | null;
+  /** ISO date string when trial started, null if not started */
+  startDate: string | null;
+  /** ISO date string when trial ends, null if not started */
+  endDate: string | null;
+};
+
+/** Status display labels with color indicators */
+const STATUS_LABELS: Record<TrialStatus, string> = {
+  available: `${colorTag("cyan", "○")} Available`,
+  active: `${colorTag("green", "●")} Active`,
+  expired: `${colorTag("muted", "−")} Expired`,
+};
+
+/**
+ * Format trial list as a human-readable table.
+ */
+function formatTrialListHuman(entries: TrialListEntry[]): string {
+  if (entries.length === 0) {
+    return "No product trials found for this organization.";
+  }
+
+  const columns: Column<TrialListEntry>[] = [
+    { header: "NAME", value: (t) => t.name },
+    { header: "PRODUCT", value: (t) => t.displayName },
+    { header: "STATUS", value: (t) => STATUS_LABELS[t.status] ?? t.status },
+    {
+      header: "DAYS LEFT",
+      value: (t) => {
+        if (t.status === "active" && t.daysRemaining !== null) {
+          return t.daysRemaining === 0
+            ? colorTag("yellow", "<1")
+            : String(t.daysRemaining);
+        }
+        return colorTag("muted", "—");
+      },
+      align: "right",
+    },
+    {
+      header: "CATEGORY",
+      value: (t) => colorTag("muted", t.category),
+    },
+  ];
+
+  const parts: string[] = [];
+  const buffer: Writer = { write: (s) => parts.push(s) };
+  writeTable(buffer, entries, columns);
+  return parts.join("").trimEnd();
+}
+
+export const listCommand = buildCommand({
+  docs: {
+    brief: "List product trials",
+    fullDescription:
+      "List product trials for an organization, including available,\n" +
+      "active, and expired trials.\n\n" +
+      "Examples:\n" +
+      "  sentry trial list\n" +
+      "  sentry trial list my-org\n" +
+      "  sentry trial list --json",
+  },
+  output: {
+    json: true,
+    human: formatTrialListHuman,
+    jsonExclude: ["displayName"],
+  },
+  parameters: {
+    positional: {
+      kind: "tuple" as const,
+      parameters: [
+        {
+          placeholder: "org",
+          brief: "Organization slug (auto-detected if omitted)",
+          parse: String,
+          optional: true as const,
+        },
+      ],
+    },
+  },
+  async func(this: SentryContext, _flags: ListFlags, org?: string) {
+    const resolved = await resolveOrg({
+      org,
+      cwd: this.cwd,
+    });
+
+    if (!resolved) {
+      throw new ContextError("Organization", "sentry trial list", [
+        "sentry trial list <org>",
+      ]);
+    }
+
+    const trials = await getProductTrials(resolved.org);
+
+    const entries: TrialListEntry[] = trials.map((t) => ({
+      name: getTrialFriendlyName(t.category),
+      displayName: getTrialDisplayName(t.category),
+      category: t.category,
+      status: getTrialStatus(t),
+      daysRemaining: getDaysRemaining(t),
+      isStarted: t.isStarted,
+      lengthDays: t.lengthDays,
+      startDate: t.startDate,
+      endDate: t.endDate,
+    }));
+
+    const hints: string[] = [];
+    const hasAvailable = entries.some((e) => e.status === "available");
+    if (hasAvailable) {
+      hints.push("Tip: Use 'sentry trial start <name>' to start a trial");
+    }
+
+    return { data: entries, hint: hints.join("\n") || undefined };
+  },
+});

src/commands/trial/start.ts

@@ -0,0 +1,160 @@
+/**
+ * sentry trial start
+ *
+ * Start a product trial for an organization.
+ * Supports swap detection: `sentry trial start my-org seer` works
+ * the same as `sentry trial start seer my-org`.
+ */
+
+import type { SentryContext } from "../../context.js";
+import { getProductTrials, startProductTrial } from "../../lib/api-client.js";
+import { detectSwappedTrialArgs } from "../../lib/arg-parsing.js";
+import { buildCommand } from "../../lib/command.js";
+import { ContextError, ValidationError } from "../../lib/errors.js";
+import { success } from "../../lib/formatters/colors.js";
+import { logger } from "../../lib/logger.js";
+import { resolveOrg } from "../../lib/resolve-target.js";
+import {
+  findAvailableTrial,
+  getDisplayNameForTrialName,
+  getTrialDisplayName,
+  getValidTrialNames,
+  isTrialName,
+} from "../../lib/trials.js";
+
+const VALID_NAMES = getValidTrialNames();
+const NAMES_LIST = VALID_NAMES.join(", ");
+
+/**
+ * Parse the positional args for `trial start`, handling swapped order.
+ *
+ * Expected: `<name> [org]`
+ * Also accepted: `<org> <name>` (detected and auto-corrected)
+ *
+ * @returns Parsed name and optional org, plus any warning message
+ */
+function parseTrialStartArgs(
+  first: string,
+  second?: string
+): { name: string; org?: string; warning?: string } {
+  if (!second) {
+    // Single arg — must be a trial name
+    return { name: first };
+  }
+
+  // Two args — check for swapped order
+  const swapped = detectSwappedTrialArgs(first, second, isTrialName);
+  if (swapped) {
+    return { name: swapped.name, org: swapped.org, warning: swapped.warning };
+  }
+
+  // Normal order: first=name, second=org
+  return { name: first, org: second };
+}
+
+export const startCommand = buildCommand({
+  docs: {
+    brief: "Start a product trial",
+    fullDescription:
+      "Start a product trial for an organization.\n\n" +
+      `Valid trial names: ${NAMES_LIST}\n\n` +
+      "Examples:\n" +
+      "  sentry trial start seer\n" +
+      "  sentry trial start seer my-org\n" +
+      "  sentry trial start replays\n" +
+      "  sentry trial start --json seer",
+  },
+  output: { json: true, human: formatStartResult },
+  parameters: {
+    positional: {
+      kind: "tuple" as const,
+      parameters: [
+        {
+          placeholder: "name",
+          brief: `Trial name (${NAMES_LIST})`,
+          parse: String,
+        },
+        {
+          placeholder: "org",
+          brief: "Organization slug (auto-detected if omitted)",
+          parse: String,
+          optional: true as const,
+        },
+      ],
+    },
+  },
+  async func(
+    this: SentryContext,
+    _flags: unknown,
+    first: string,
+    second?: string
+  ) {
+    const log = logger.withTag("trial");
+    const parsed = parseTrialStartArgs(first, second);
+
+    if (parsed.warning) {
+      log.warn(parsed.warning);
+    }
+
+    // Validate trial name
+    if (!isTrialName(parsed.name)) {
+      throw new ValidationError(
+        `Unknown trial name: '${parsed.name}'. Valid names: ${NAMES_LIST}`,
+        "name"
+      );
+    }
+
+    // Resolve organization
+    const resolved = await resolveOrg({
+      org: parsed.org,
+      cwd: this.cwd,
+    });
+
+    if (!resolved) {
+      throw new ContextError("Organization", "sentry trial start", [
+        "sentry trial start <name> <org>",
+      ]);
+    }
+
+    const orgSlug = resolved.org;
+
+    // Fetch trials and find an available one
+    const trials = await getProductTrials(orgSlug);
+    const trial = findAvailableTrial(trials, parsed.name);
+
+    if (!trial) {
+      const displayName = getDisplayNameForTrialName(parsed.name);
+      throw new ValidationError(
+        `No ${displayName} trial available for organization '${orgSlug}'.`,
+        "name"
+      );
+    }
+
+    // Start the trial
+    await startProductTrial(orgSlug, trial.category);
+
+    return {
+      data: {
+        name: parsed.name,
+        category: trial.category,
+        organization: orgSlug,
+        lengthDays: trial.lengthDays,
+        started: true,
+      },
+      hint: undefined,
+    };
+  },
+});
+
+/** Format start result as human-readable output */
+function formatStartResult(data: {
+  name: string;
+  category: string;
+  organization: string;
+  lengthDays: number | null;
+  started: boolean;
+}): string {
+  const displayName = getTrialDisplayName(data.category);
+  const daysText = data.lengthDays ? ` (${data.lengthDays} days)` : "";
+  return `${success("✓")} ${displayName} trial started for ${data.organization}!${daysText}`;
+}