fix(help): show help when user passes help as positional arg (#CLI-MN)

When users type `sentry log list help` (or similar) intending to see
help, the bare word "help" was parsed as a project slug positional
argument, causing confusing errors like "Project 'help' not found".

Intercept `help` and `-h` in positional args inside the `buildCommand`
wrapper so it applies to ALL commands. When detected, show the
command's help via the existing introspection system (same output as
`sentry help <command>`) and print a yellow tip about `--help`.

Changes:
- Store `commandPrefix` on `SentryContext` (set by Stricli's
  `forCommand` callback) so `buildCommand` knows which command is
  running
- Add `maybeShowHelpAndExit()` in `buildCommand` that detects help
  tokens in positional args and renders help via `introspectCommand()`
- Dynamic import of `help.js` avoids circular dependency

Fixes CLI-MN

Author: BYK

src/context.ts

@@ -20,6 +20,14 @@ export interface SentryContext extends CommandContext {
   readonly stdout: Writer;
   readonly stderr: Writer;
   readonly stdin: NodeJS.ReadStream & { fd: 0 };
+  /**
+   * Command path segments set by Stricli's `forCommand` callback.
+   *
+   * Contains the full prefix including the program name, e.g.,
+   * `["sentry", "issue", "list"]`. Used by `buildCommand` to show
+   * help when a user passes `help` as a positional argument.
+   */
+  readonly commandPrefix?: readonly string[];
 }
 
 /**
@@ -47,7 +55,7 @@ export function buildContext(process: NodeJS.Process, span?: Span) {
     ...baseContext,
     forCommand: ({ prefix }: { prefix: readonly string[] }): SentryContext => {
       setCommandSpanName(span, prefix.join("."));
-      return baseContext;
+      return { ...baseContext, commandPrefix: prefix };
     },
   };
 }

src/lib/command.ts

@@ -38,6 +38,7 @@ import {
 } from "@stricli/core";
 import type { Writer } from "../types/index.js";
 import { OutputError } from "./errors.js";
+import { warning } from "./formatters/colors.js";
 import { parseFieldsList } from "./formatters/json.js";
 import {
   ClearScreen,
@@ -393,6 +394,44 @@ export function buildCommand<
     }
   }
 
+  /**
+   * Check if positional args contain a bare `help` or `-h` token and, if so,
+   * display the command's help and exit.
+   *
+   * Users intuitively type `sentry issue list help` expecting help output.
+   * Stricli only recognizes `--help`/`-h` as a flag during route scanning,
+   * so bare `"help"` flows through as a positional and causes confusing
+   * errors (e.g., "Project 'help' not found"). When detected, show the
+   * command's help via the introspection system — same output as
+   * `sentry help <command>`.
+   */
+  async function maybeShowHelpAndExit(
+    stdout: Writer,
+    ctx: { commandPrefix?: readonly string[]; stderr: Writer },
+    args: unknown[]
+  ): Promise<void> {
+    if (args.length === 0 || !args.some((a) => a === "help" || a === "-h")) {
+      return;
+    }
+    if (!ctx.commandPrefix) {
+      return;
+    }
+    const pathSegments = ctx.commandPrefix.slice(1); // strip "sentry" prefix
+    // Dynamic import to avoid circular: command.ts → help.ts → app.ts → commands → command.ts
+    const { introspectCommand, formatHelpHuman } = await import("./help.js");
+    const result = introspectCommand(pathSegments);
+    if ("error" in result) {
+      return;
+    }
+    ctx.stderr.write(
+      warning(
+        `Tip: use --help for help (e.g., sentry ${pathSegments.join(" ")} --help)\n\n`
+      )
+    );
+    stdout.write(`${formatHelpHuman(result)}\n`);
+    process.exit(0);
+  }
+
   // Wrap func to intercept logging flags, capture telemetry, then call original.
   // The wrapper is an async function that iterates the generator returned by func.
   const wrappedFunc = async function (
@@ -413,6 +452,15 @@ export function buildCommand<
 
     const stdout = (this as unknown as { stdout: Writer }).stdout;
 
+    await maybeShowHelpAndExit(
+      stdout,
+      this as unknown as {
+        commandPrefix?: readonly string[];
+        stderr: Writer;
+      },
+      args
+    );
+
     // Reset per-invocation state
     pendingClear = false;
 

test/lib/help-positional.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Tests for help-as-positional-arg interception in buildCommand.
+ *
+ * When users type `sentry issue list help` (bare `help` as a positional
+ * argument), the buildCommand wrapper detects it and shows the command's
+ * help via the introspection system instead of treating it as a target.
+ *
+ * These tests run commands through Stricli's `run()` with `help` as a
+ * trailing positional and verify the output matches the introspection
+ * system's help text.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { run } from "@stricli/core";
+import { app } from "../../src/app.js";
+import type { SentryContext } from "../../src/context.js";
+import { useTestConfigDir } from "../helpers.js";
+
+useTestConfigDir("help-positional-");
+
+/** Captured output from a command run */
+type CapturedOutput = {
+  stdout: string;
+  stderr: string;
+};
+
+/** Original process.exit before mocking */
+let originalExit: typeof process.exit;
+
+/** Whether process.exit was called */
+let exitCalled: { code: number | undefined } | undefined;
+
+beforeEach(() => {
+  exitCalled = undefined;
+  originalExit = process.exit;
+  // Mock process.exit to prevent actually exiting during tests.
+  // Throws to stop execution (like the real process.exit would).
+  process.exit = mock((code?: number) => {
+    exitCalled = { code: code ?? 0 };
+    throw new Error(`process.exit(${code})`);
+  }) as typeof process.exit;
+});
+
+afterEach(() => {
+  process.exit = originalExit;
+});
+
+/**
+ * Run a command through Stricli and capture stdout/stderr.
+ *
+ * Since the help interception calls `process.exit(0)`, this catches
+ * the mock exit error and returns the captured output.
+ */
+async function runCommand(args: string[]): Promise<CapturedOutput> {
+  let stdout = "";
+  let stderr = "";
+
+  const stdoutWriter = {
+    write(data: string | Uint8Array) {
+      stdout +=
+        typeof data === "string" ? data : new TextDecoder().decode(data);
+      return true;
+    },
+  };
+  const stderrWriter = {
+    write(data: string | Uint8Array) {
+      stderr +=
+        typeof data === "string" ? data : new TextDecoder().decode(data);
+      return true;
+    },
+  };
+
+  const baseContext: SentryContext = {
+    process,
+    env: process.env,
+    cwd: process.cwd(),
+    homeDir: "/tmp",
+    configDir: "/tmp",
+    stdout: stdoutWriter,
+    stderr: stderrWriter,
+    stdin: process.stdin,
+  };
+
+  // Stricli calls forCommand({ prefix }) before running the command.
+  // We must provide it so commandPrefix is set on the context.
+  const mockContext = {
+    ...baseContext,
+    forCommand: ({ prefix }: { prefix: readonly string[] }): SentryContext => ({
+      ...baseContext,
+      commandPrefix: prefix,
+    }),
+  };
+
+  try {
+    await run(app, args, mockContext);
+  } catch {
+    // process.exit mock throws — expected
+  }
+
+  return { stdout, stderr };
+}
+
+describe("help as positional argument", () => {
+  test("sentry issue list help → shows help for issue list", async () => {
+    const { stdout, stderr } = await runCommand(["issue", "list", "help"]);
+
+    // Should show command help output (from introspection)
+    expect(stdout).toContain("sentry issue list");
+    // Should show the tip about --help
+    expect(stderr).toContain("--help");
+    expect(stderr).toContain("Tip");
+    // Should exit with code 0
+    expect(exitCalled).toEqual({ code: 0 });
+  });
+
+  test("sentry log list help → shows help for log list", async () => {
+    const { stdout, stderr } = await runCommand(["log", "list", "help"]);
+
+    expect(stdout).toContain("sentry log list");
+    expect(stderr).toContain("--help");
+    expect(exitCalled).toEqual({ code: 0 });
+  });
+
+  test("sentry trace view help → shows help for trace view", async () => {
+    const { stdout, stderr } = await runCommand(["trace", "view", "help"]);
+
+    expect(stdout).toContain("sentry trace view");
+    expect(stderr).toContain("--help");
+    expect(exitCalled).toEqual({ code: 0 });
+  });
+
+  test("sentry project list help → shows help for project list", async () => {
+    const { stdout, stderr } = await runCommand(["project", "list", "help"]);
+
+    expect(stdout).toContain("sentry project list");
+    expect(stderr).toContain("--help");
+    expect(exitCalled).toEqual({ code: 0 });
+  });
+
+  test("sentry issue view help → shows help for issue view", async () => {
+    const { stdout, stderr } = await runCommand(["issue", "view", "help"]);
+
+    expect(stdout).toContain("sentry issue view");
+    expect(stderr).toContain("--help");
+    expect(exitCalled).toEqual({ code: 0 });
+  });
+
+  test("stderr hint includes the correct command path", async () => {
+    const { stderr } = await runCommand(["span", "list", "help"]);
+
+    expect(stderr).toContain("sentry span list --help");
+  });
+});
+
+describe("help command unchanged", () => {
+  test("sentry help still shows branded help", async () => {
+    const { stdout } = await runCommand(["help"]);
+
+    // Custom help command shows branded output
+    expect(stdout).toContain("sentry");
+    // Should NOT have exited via our interception
+    expect(exitCalled).toBeUndefined();
+  });
+
+  test("sentry help issue list still shows introspected help", async () => {
+    const { stdout } = await runCommand(["help", "issue", "list"]);
+
+    expect(stdout).toContain("sentry issue list");
+    // Should NOT have exited via our interception
+    expect(exitCalled).toBeUndefined();
+  });
+});