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

@@ -37,7 +37,8 @@ import {
   numberParser as stricliNumberParser,
 } from "@stricli/core";
 import type { Writer } from "../types/index.js";
-import { OutputError } from "./errors.js";
+import { CliError, OutputError } from "./errors.js";
+import { warning } from "./formatters/colors.js";
 import { parseFieldsList } from "./formatters/json.js";
 import {
   ClearScreen,
@@ -393,6 +394,56 @@ export function buildCommand<
     }
   }
 
+  /**
+   * When a command throws a {@link CliError} and a positional arg was
+   * `"help"`, the user likely intended `--help`. Show the command's
+   * help instead of the confusing error.
+   *
+   * Only fires as **error recovery** — if the command succeeds with a
+   * legitimate value like a project named "help", this never runs.
+   *
+   * Catches all {@link CliError} subtypes (AuthError, ResolutionError,
+   * ValidationError, ContextError, etc.) because any failure with "help"
+   * as input strongly signals the user wanted `--help`. For example,
+   * `sentry issue list help` may throw AuthError (not logged in) before
+   * ever reaching project resolution.
+   *
+   * Note: `-h` is NOT checked here because Stricli intercepts `-h` as
+   * a help flag during route scanning, before `func` is ever called.
+   *
+   * @returns `true` if help was shown and the error was recovered
+   */
+  async function maybeRecoverWithHelp(
+    err: unknown,
+    stdout: Writer,
+    ctx: { commandPrefix?: readonly string[]; stderr: Writer },
+    args: unknown[]
+  ): Promise<boolean> {
+    if (!(err instanceof CliError)) {
+      return false;
+    }
+    if (args.length === 0 || !args.some((a) => a === "help")) {
+      return false;
+    }
+    if (!ctx.commandPrefix) {
+      return false;
+    }
+    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 false;
+    }
+    ctx.stderr.write(
+      warning(
+        `Tip: use --help for help (e.g., sentry ${pathSegments.join(" ")} --help)\n\n`
+      )
+    );
+    stdout.write(`${formatHelpHuman(result)}\n`);
+    return true;
+  }
+
   // 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 (
@@ -468,6 +519,23 @@ export function buildCommand<
       if (!cleanFlags.json) {
         writeFinalization(stdout, undefined, false, renderer);
       }
+
+      // If a positional arg was "help" and the command failed with a
+      // resolution/validation error, the user likely meant --help.
+      // Show help as recovery instead of the confusing error.
+      const recovered = await maybeRecoverWithHelp(
+        err,
+        stdout,
+        this as unknown as {
+          commandPrefix?: readonly string[];
+          stderr: Writer;
+        },
+        args
+      );
+      if (recovered) {
+        return;
+      }
+
       handleOutputError(err);
     }
   };

test/lib/help-positional.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Tests for help-as-positional-arg error recovery in buildCommand.
+ *
+ * When a command throws a CliError and a positional arg was `"help"`,
+ * the buildCommand wrapper recovers by showing the command's help
+ * instead of the confusing error.
+ *
+ * This only fires as error recovery — if a command successfully resolves
+ * a legitimate value like a project named "help", the recovery never runs.
+ *
+ * Note: `-h` is NOT covered here because Stricli intercepts it as a help
+ * flag during route scanning, before the command's func is ever called.
+ *
+ * Tests run commands through Stricli's `run()` with `help` as a positional
+ * and verify help output is shown when resolution fails.
+ */
+
+import { describe, expect, 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;
+};
+
+/**
+ * Build a mock context with forCommand support.
+ *
+ * Stricli calls `forCommand({ prefix })` before running the command.
+ * We must provide it so `commandPrefix` is set on the context, enabling
+ * the help recovery logic in `buildCommand`.
+ */
+function buildMockContext(captured: {
+  stdout: string;
+  stderr: string;
+}): SentryContext & {
+  forCommand: (opts: { prefix: readonly string[] }) => SentryContext;
+} {
+  const stdoutWriter = {
+    write(data: string | Uint8Array) {
+      captured.stdout +=
+        typeof data === "string" ? data : new TextDecoder().decode(data);
+      return true;
+    },
+  };
+  const stderrWriter = {
+    write(data: string | Uint8Array) {
+      captured.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,
+  };
+
+  return {
+    ...baseContext,
+    forCommand: ({ prefix }: { prefix: readonly string[] }): SentryContext => ({
+      ...baseContext,
+      commandPrefix: prefix,
+    }),
+  };
+}
+
+/**
+ * Run a command through Stricli and capture stdout/stderr.
+ *
+ * Commands that hit resolution errors with "help" as a positional arg
+ * will be recovered by the buildCommand wrapper, which shows help output
+ * instead of the error.
+ */
+async function runCommand(args: string[]): Promise<CapturedOutput> {
+  const captured = { stdout: "", stderr: "" };
+  const mockContext = buildMockContext(captured);
+
+  try {
+    await run(app, args, mockContext);
+  } catch {
+    // Some commands may still throw (e.g., uncaught errors)
+  }
+
+  return captured;
+}
+
+describe("help recovery on ResolutionError", () => {
+  test("sentry issue list help → shows help for issue list", async () => {
+    // "help" is treated as a project slug, fails resolution → recovery shows help
+    const { stdout, stderr } = await runCommand(["issue", "list", "help"]);
+
+    expect(stdout).toContain("sentry issue list");
+    expect(stderr).toContain("--help");
+    expect(stderr).toContain("Tip");
+  });
+
+  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");
+  });
+
+  test("sentry span list help → shows help for span list", async () => {
+    const { stdout, stderr } = await runCommand(["span", "list", "help"]);
+
+    expect(stdout).toContain("sentry span list");
+    expect(stderr).toContain("--help");
+  });
+
+  test("stderr hint includes the correct command path", async () => {
+    const { stderr } = await runCommand(["issue", "list", "help"]);
+
+    expect(stderr).toContain("sentry issue list --help");
+  });
+});
+
+describe("help recovery on ValidationError", () => {
+  test("sentry trace view help → shows help for trace view", async () => {
+    // "help" fails hex ID validation → ValidationError → recovery shows help
+    const { stdout, stderr } = await runCommand(["trace", "view", "help"]);
+
+    expect(stdout).toContain("sentry trace view");
+    expect(stderr).toContain("--help");
+  });
+
+  test("sentry log view help → shows help for log view", async () => {
+    const { stdout, stderr } = await runCommand(["log", "view", "help"]);
+
+    expect(stdout).toContain("sentry log view");
+    expect(stderr).toContain("--help");
+  });
+});
+
+describe("help command unchanged", () => {
+  test("sentry help still shows branded help", async () => {
+    const { stdout, stderr } = await runCommand(["help"]);
+
+    // Custom help command shows branded output — no recovery needed
+    expect(stdout).toContain("sentry");
+    // Should NOT have the recovery tip
+    expect(stderr).not.toContain("Tip");
+  });
+
+  test("sentry help issue list still shows introspected help", async () => {
+    const { stdout, stderr } = await runCommand(["help", "issue", "list"]);
+
+    expect(stdout).toContain("sentry issue list");
+    // Should NOT have the recovery tip — this is the normal help path
+    expect(stderr).not.toContain("Tip");
+  });
+});