feat(auth): Make bare sentry auth run login (getsentry#1380)

Co-authored-by: David Cramer <david@sentry.io>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>

Author: 4 people

README.md

@@ -52,7 +52,7 @@ bunx sentry --help
 
 ```bash
 # Authenticate with Sentry
-sentry auth login
+sentry auth
 
 # List issues (auto-detects project from your codebase)
 sentry issue list

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -284,8 +284,8 @@ npm install -g sentry
 ### Authentication
 
 ```bash
-sentry auth login
-sentry auth login --token YOUR_SENTRY_API_TOKEN
+sentry auth
+sentry auth --token YOUR_SENTRY_API_TOKEN
 sentry auth status
 sentry auth logout
 ```

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

@@ -26,19 +26,19 @@ Authenticate with Sentry
 **Examples:**
 
 ```bash
-sentry auth login
+sentry auth
 
-sentry auth login --token YOUR_SENTRY_API_TOKEN
+sentry auth --token YOUR_SENTRY_API_TOKEN
 
-sentry auth login --read-only
+sentry auth --read-only
 
-sentry auth login --scope project:read --scope org:read
-sentry auth login --scope project:read,event:read
+sentry auth --scope project:read --scope org:read
+sentry auth --scope project:read,event:read
 
-sentry auth login --url https://sentry.example.com
-SENTRY_URL=https://sentry.example.com sentry auth login
+sentry auth --url https://sentry.example.com
+SENTRY_URL=https://sentry.example.com sentry auth
 
-sentry auth login --token YOUR_TOKEN --url https://sentry.example.com
+sentry auth --token YOUR_TOKEN --url https://sentry.example.com
 ```
 
 ### `sentry auth logout`

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

@@ -236,6 +236,10 @@ Mark an issue as resolved
 **Flags:**
 - `-i, --in <value> - Resolve in a release, next release, or commit ('<version>' | '@next' | '@commit' | '@commit:<repo>@<sha>')`
 
+### `sentry issue unresolve <issue>`
+
+Reopen a resolved issue
+
 **Examples:**
 
 ```bash
@@ -265,10 +269,6 @@ sentry issue unresolve CLI-G5
 sentry issue reopen CLI-G5   # alias
 ```
 
-### `sentry issue unresolve <issue>`
-
-Reopen a resolved issue
-
 ### `sentry issue archive <issue>`
 
 Archive (ignore) an issue

script/generate-skill-markdown.ts

@@ -18,10 +18,20 @@ export function extractCommandPathFromHeading(
 export function matchExampleToCommand(
   code: string,
   commandPaths: readonly string[],
-  groupFallback: string
+  groupFallback: string,
+  defaultCommandPath?: string
 ): string | undefined {
-  return (
-    commandPaths.find((path) => code.includes(path)) ??
-    (code.includes(groupFallback) ? groupFallback : undefined)
-  );
+  // Prefer the longest path so `sentry auth login` wins over bare `sentry auth`
+  // when both would otherwise match via includes().
+  const byLengthDesc = [...commandPaths].sort((a, b) => b.length - a.length);
+  const matched = byLengthDesc.find((path) => code.includes(path));
+  if (matched) {
+    return matched;
+  }
+  if (!code.includes(groupFallback)) {
+    return;
+  }
+  // Bare group examples (`sentry auth`) belong on the default subcommand when
+  // one exists (login), not on a synthetic group-only path.
+  return defaultCommandPath ?? groupFallback;
 }

script/generate-skill.ts

@@ -60,6 +60,34 @@ import {
   isRouteMap,
 } from "../src/lib/introspect.js";
 
+/**
+ * Resolve the default subcommand name for a route map, if configured.
+ *
+ * Hidden dispatcher routes (e.g. auth's `default`) map bare group examples
+ * onto the user-facing command they primarily document (login).
+ */
+function findDefaultCommandName(routeMap: RouteMap): string | undefined {
+  if (!routeMap.getDefaultCommand) {
+    return;
+  }
+  const defaultCmd = routeMap.getDefaultCommand();
+  if (!defaultCmd) {
+    return;
+  }
+  for (const sub of routeMap.getAllEntries()) {
+    if (sub.target === defaultCmd) {
+      const name = sub.name.original;
+      // Auth uses a hidden "default" dispatcher; bare `sentry auth` examples
+      // document the login path.
+      if (name === "default") {
+        return "login";
+      }
+      return name;
+    }
+  }
+  return;
+}
+
 const SKILL_DIR = "plugins/sentry-cli/skills/sentry-cli";
 const OUTPUT_PATH = `${SKILL_DIR}/SKILL.md`;
 const REFERENCES_DIR = `${SKILL_DIR}/references`;
@@ -290,10 +318,10 @@ npm install -g sentry
 
 \`\`\`bash
 # OAuth login (recommended)
-sentry auth login
+sentry auth
 
 # Or use an API token
-sentry auth login --token YOUR_SENTRY_API_TOKEN
+sentry auth --token YOUR_SENTRY_API_TOKEN
 
 # Check auth status
 sentry auth status
@@ -341,10 +369,14 @@ function collectCommandPaths(
  */
 function associateCodeBlocks(
   tokens: Token[],
-  commandPaths: string[],
-  commandGroup: string,
-  examples: Map<string, string[]>
+  context: {
+    commandPaths: string[];
+    commandGroup: string;
+    examples: Map<string, string[]>;
+    defaultCommandPath?: string;
+  }
 ): void {
+  const { commandPaths, commandGroup, examples, defaultCommandPath } = context;
   const groupFallback = `sentry ${commandGroup}`;
   let currentCmd: string | null = null;
 
@@ -359,7 +391,12 @@ function associateCodeBlocks(
     if (currentCmd && examples.has(currentCmd)) {
       appendExample(examples, currentCmd, code);
     } else {
-      const target = matchExampleToCommand(code, commandPaths, groupFallback);
+      const target = matchExampleToCommand(
+        code,
+        commandPaths,
+        groupFallback,
+        defaultCommandPath
+      );
       if (target) {
         appendExample(examples, target, code);
       }
@@ -377,7 +414,8 @@ function associateCodeBlocks(
  * by matching code blocks to commands via heading context or content analysis.
  */
 async function loadCommandExamples(
-  commandGroup: string
+  commandGroup: string,
+  defaultCommandName?: string
 ): Promise<Map<string, string[]>> {
   const docContent = await loadDoc(`commands/${commandGroup}.md`);
   if (!docContent) {
@@ -387,7 +425,15 @@ async function loadCommandExamples(
   const tokens = marked.lexer(docContent);
   const examples = new Map<string, string[]>();
   const commandPaths = collectCommandPaths(tokens, examples);
-  associateCodeBlocks(tokens, commandPaths, commandGroup, examples);
+  const defaultCommandPath = defaultCommandName
+    ? `sentry ${commandGroup} ${defaultCommandName}`
+    : undefined;
+  associateCodeBlocks(tokens, {
+    commandPaths,
+    commandGroup,
+    examples,
+    defaultCommandPath,
+  });
   return examples;
 }
 
@@ -435,7 +481,13 @@ async function extractRoutes(routeMap: RouteMap): Promise<RouteInfo[]> {
     }
     const routeName = entry.name.original;
     const target = entry.target;
-    const docExamples = await loadCommandExamples(routeName);
+    const defaultCommandName = isRouteMap(target)
+      ? findDefaultCommandName(target)
+      : undefined;
+    const docExamples = await loadCommandExamples(
+      routeName,
+      defaultCommandName
+    );
     if (isRouteMap(target)) {
       result.push({
         name: routeName,