feat(profile): add transaction aliases for quick reference

Enable quick access to transactions via numeric indices or short aliases:

- `sentry profile list` now shows # and ALIAS columns
- `sentry profile view 1` - access by numeric index
- `sentry profile view i` - access by alias (last unique segment)

Implementation:
- Add transaction_aliases SQLite table (schema v5)
- Add TransactionAliasEntry type for cached aliases
- Add buildTransactionAliases() using existing alias algorithm
- Add resolveTransaction() with stale cache detection
- Update formatters to show alias columns

Aliases are fingerprinted by org:project:period and error with helpful
messages when stale (e.g., different period) or unknown.

Author: BYK

src/commands/profile/list.ts

@@ -9,6 +9,10 @@ import { buildCommand, numberParser } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { getProject, listProfiledTransactions } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
+import {
+  buildTransactionFingerprint,
+  setTransactionAliases,
+} from "../../lib/db/transaction-aliases.js";
 import { ContextError } from "../../lib/errors.js";
 import {
   divider,
@@ -19,7 +23,8 @@ import {
   writeJson,
 } from "../../lib/formatters/index.js";
 import { resolveOrgAndProject } from "../../lib/resolve-target.js";
-import type { Writer } from "../../types/index.js";
+import { buildTransactionAliases } from "../../lib/transaction-alias.js";
+import type { TransactionAliasEntry, Writer } from "../../types/index.js";
 
 type ListFlags = {
   readonly period: string;
@@ -160,6 +165,31 @@ export const listCommand = buildCommand({
 
     const orgProject = `${resolvedTarget.org}/${resolvedTarget.project}`;
 
+    // Build and store transaction aliases for later use with profile view
+    const transactionInputs = response.data
+      .filter((row) => row.transaction)
+      .map((row) => ({
+        transaction: row.transaction as string,
+        orgSlug: resolvedTarget.org,
+        projectSlug: resolvedTarget.project,
+      }));
+
+    const aliases = buildTransactionAliases(transactionInputs);
+
+    // Store aliases with fingerprint for cache validation
+    const fingerprint = buildTransactionFingerprint(
+      resolvedTarget.org,
+      resolvedTarget.project,
+      flags.period
+    );
+    setTransactionAliases(aliases, fingerprint);
+
+    // Build alias lookup map for formatting
+    const aliasMap = new Map<string, TransactionAliasEntry>();
+    for (const alias of aliases) {
+      aliasMap.set(alias.transaction, alias);
+    }
+
     // JSON output
     if (flags.json) {
       writeJson(stdout, response.data);
@@ -172,16 +202,18 @@ export const listCommand = buildCommand({
       return;
     }
 
-    // Human-readable output
+    // Human-readable output with aliases
+    const hasAliases = aliases.length > 0;
     stdout.write(`${formatProfileListHeader(orgProject, flags.period)}\n\n`);
-    stdout.write(`${formatProfileListTableHeader()}\n`);
-    stdout.write(`${divider(76)}\n`);
+    stdout.write(`${formatProfileListTableHeader(hasAliases)}\n`);
+    stdout.write(`${divider(82)}\n`);
 
     for (const row of response.data) {
-      stdout.write(`${formatProfileListRow(row)}\n`);
+      const alias = row.transaction ? aliasMap.get(row.transaction) : undefined;
+      stdout.write(`${formatProfileListRow(row, alias)}\n`);
     }
 
-    stdout.write(formatProfileListFooter());
+    stdout.write(formatProfileListFooter(hasAliases));
 
     if (resolvedTarget.detectedFrom) {
       stdout.write(`\n\nDetected from ${resolvedTarget.detectedFrom}\n`);

src/commands/profile/view.ts

@@ -20,6 +20,7 @@ import {
   hasProfileData,
 } from "../../lib/profile/analyzer.js";
 import { resolveOrgAndProject } from "../../lib/resolve-target.js";
+import { resolveTransaction } from "../../lib/resolve-transaction.js";
 import { buildProfileUrl } from "../../lib/sentry-urls.js";
 
 type ViewFlags = {
@@ -68,7 +69,8 @@ export const viewCommand = buildCommand({
       parameters: [
         {
           placeholder: "transaction",
-          brief: 'Transaction name (e.g., "/api/users", "POST /api/orders")',
+          brief:
+            'Transaction: index (1), alias (i), or full name ("/api/users")',
           parse: String,
         },
       ],
@@ -119,25 +121,36 @@ export const viewCommand = buildCommand({
   async func(
     this: SentryContext,
     flags: ViewFlags,
-    transactionName: string
+    transactionRef: string
   ): Promise<void> {
     const { stdout, cwd, setContext } = this;
 
-    // Resolve org and project
+    // Resolve org and project from flags or detection
     const target = await resolveOrgAndProject({
       org: flags.org,
       project: flags.project,
       cwd,
-      usageHint: `sentry profile view "${transactionName}" --org <org> --project <project>`,
+      usageHint: `sentry profile view "${transactionRef}" --org <org> --project <project>`,
     });
 
     if (!target) {
       throw new ContextError(
         "Organization and project",
-        `sentry profile view "${transactionName}" --org <org-slug> --project <project-slug>`
+        `sentry profile view "${transactionRef}" --org <org-slug> --project <project-slug>`
       );
     }
 
+    // Resolve transaction reference (alias, index, or full name)
+    // This may throw ContextError if alias is stale or not found
+    const resolved = resolveTransaction(transactionRef, {
+      org: target.org,
+      project: target.project,
+      period: flags.period,
+    });
+
+    // Use resolved transaction name for the rest of the command
+    const transactionName = resolved.transaction;
+
     // Set telemetry context
     setContext([target.org], [target.project]);
 

src/lib/db/schema.ts

@@ -4,7 +4,7 @@
 
 import type { Database } from "bun:sqlite";
 
-const CURRENT_SCHEMA_VERSION = 4;
+const CURRENT_SCHEMA_VERSION = 5;
 
 /** User identity for telemetry (single row, id=1) */
 const USER_INFO_TABLE = `
@@ -48,6 +48,25 @@ const PROJECT_ROOT_CACHE_TABLE = `
   )
 `;
 
+/** Transaction aliases for profile commands (1, i → full transaction name) */
+const TRANSACTION_ALIASES_TABLE = `
+  CREATE TABLE IF NOT EXISTS transaction_aliases (
+    idx INTEGER NOT NULL,
+    alias TEXT NOT NULL,
+    transaction_name TEXT NOT NULL,
+    org_slug TEXT NOT NULL,
+    project_slug TEXT NOT NULL,
+    fingerprint TEXT NOT NULL,
+    cached_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+    PRIMARY KEY (fingerprint, idx)
+  )
+`;
+
+const TRANSACTION_ALIASES_INDEX = `
+  CREATE INDEX IF NOT EXISTS idx_txn_alias_lookup 
+  ON transaction_aliases(alias, fingerprint)
+`;
+
 export function initSchema(db: Database): void {
   db.exec(`
     -- Schema version for future migrations
@@ -128,6 +147,8 @@ export function initSchema(db: Database): void {
     ${USER_INFO_TABLE};
     ${INSTANCE_INFO_TABLE};
     ${PROJECT_ROOT_CACHE_TABLE};
+    ${TRANSACTION_ALIASES_TABLE};
+    ${TRANSACTION_ALIASES_INDEX};
   `);
 
   const versionRow = db
@@ -205,6 +226,12 @@ export function runMigrations(db: Database): void {
     db.exec(PROJECT_ROOT_CACHE_TABLE);
   }
 
+  // Migration 4 -> 5: Add transaction_aliases table for profile commands
+  if (currentVersion < 5) {
+    db.exec(TRANSACTION_ALIASES_TABLE);
+    db.exec(TRANSACTION_ALIASES_INDEX);
+  }
+
   // Update schema version if needed
   if (currentVersion < CURRENT_SCHEMA_VERSION) {
     db.query("UPDATE schema_version SET version = ?").run(

src/lib/db/transaction-aliases.ts

@@ -0,0 +1,192 @@
+/**
+ * Transaction aliases storage for profile commands.
+ * Enables short references like "1" or "i" for transactions from `profile list`.
+ */
+
+import type { TransactionAliasEntry } from "../../types/index.js";
+import { getDatabase } from "./index.js";
+
+type TransactionAliasRow = {
+  idx: number;
+  alias: string;
+  transaction_name: string;
+  org_slug: string;
+  project_slug: string;
+  fingerprint: string;
+  cached_at: number;
+};
+
+/**
+ * Build a fingerprint for cache validation.
+ * Format: "orgSlug:projectSlug:period" or "orgSlug:*:period" for multi-project.
+ */
+export function buildTransactionFingerprint(
+  orgSlug: string,
+  projectSlug: string | null,
+  period: string
+): string {
+  return `${orgSlug}:${projectSlug ?? "*"}:${period}`;
+}
+
+/**
+ * Store transaction aliases from a profile list command.
+ * Replaces any existing aliases for the same fingerprint.
+ */
+export function setTransactionAliases(
+  aliases: TransactionAliasEntry[],
+  fingerprint: string
+): void {
+  const db = getDatabase();
+  const now = Date.now();
+
+  db.exec("BEGIN TRANSACTION");
+
+  try {
+    // Delete only aliases with the same fingerprint
+    db.query("DELETE FROM transaction_aliases WHERE fingerprint = ?").run(
+      fingerprint
+    );
+
+    const insertStmt = db.query(`
+      INSERT INTO transaction_aliases 
+      (idx, alias, transaction_name, org_slug, project_slug, fingerprint, cached_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    for (const entry of aliases) {
+      insertStmt.run(
+        entry.idx,
+        entry.alias.toLowerCase(),
+        entry.transaction,
+        entry.orgSlug,
+        entry.projectSlug,
+        fingerprint,
+        now
+      );
+    }
+
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+/**
+ * Look up transaction by numeric index.
+ * Returns null if not found or fingerprint doesn't match.
+ */
+export function getTransactionByIndex(
+  idx: number,
+  fingerprint: string
+): TransactionAliasEntry | null {
+  const db = getDatabase();
+
+  const row = db
+    .query(
+      "SELECT * FROM transaction_aliases WHERE idx = ? AND fingerprint = ?"
+    )
+    .get(idx, fingerprint) as TransactionAliasRow | undefined;
+
+  if (!row) {
+    return null;
+  }
+
+  return {
+    idx: row.idx,
+    alias: row.alias,
+    transaction: row.transaction_name,
+    orgSlug: row.org_slug,
+    projectSlug: row.project_slug,
+  };
+}
+
+/**
+ * Look up transaction by alias.
+ * Returns null if not found or fingerprint doesn't match.
+ */
+export function getTransactionByAlias(
+  alias: string,
+  fingerprint: string
+): TransactionAliasEntry | null {
+  const db = getDatabase();
+
+  const row = db
+    .query(
+      "SELECT * FROM transaction_aliases WHERE alias = ? AND fingerprint = ?"
+    )
+    .get(alias.toLowerCase(), fingerprint) as TransactionAliasRow | undefined;
+
+  if (!row) {
+    return null;
+  }
+
+  return {
+    idx: row.idx,
+    alias: row.alias,
+    transaction: row.transaction_name,
+    orgSlug: row.org_slug,
+    projectSlug: row.project_slug,
+  };
+}
+
+/**
+ * Get all cached aliases for a fingerprint.
+ */
+export function getTransactionAliases(
+  fingerprint: string
+): TransactionAliasEntry[] {
+  const db = getDatabase();
+
+  const rows = db
+    .query(
+      "SELECT * FROM transaction_aliases WHERE fingerprint = ? ORDER BY idx"
+    )
+    .all(fingerprint) as TransactionAliasRow[];
+
+  return rows.map((row) => ({
+    idx: row.idx,
+    alias: row.alias,
+    transaction: row.transaction_name,
+    orgSlug: row.org_slug,
+    projectSlug: row.project_slug,
+  }));
+}
+
+/**
+ * Check if an alias exists for a different fingerprint (stale check).
+ * Returns the stale fingerprint if found, null otherwise.
+ */
+export function getStaleFingerprint(alias: string): string | null {
+  const db = getDatabase();
+
+  const row = db
+    .query(
+      "SELECT fingerprint FROM transaction_aliases WHERE alias = ? LIMIT 1"
+    )
+    .get(alias.toLowerCase()) as { fingerprint: string } | undefined;
+
+  return row?.fingerprint ?? null;
+}
+
+/**
+ * Check if an index exists for a different fingerprint (stale check).
+ * Returns the stale fingerprint if found, null otherwise.
+ */
+export function getStaleIndexFingerprint(idx: number): string | null {
+  const db = getDatabase();
+
+  const row = db
+    .query("SELECT fingerprint FROM transaction_aliases WHERE idx = ? LIMIT 1")
+    .get(idx) as { fingerprint: string } | undefined;
+
+  return row?.fingerprint ?? null;
+}
+
+/**
+ * Clear all transaction aliases.
+ */
+export function clearTransactionAliases(): void {
+  const db = getDatabase();
+  db.query("DELETE FROM transaction_aliases").run();
+}