feat: add --json flag to help command for agent introspection

Add structured JSON output to the help command so AI agents can discover
CLI commands at runtime without relying on static docs.

New features:
- `sentry help --json` — emit full command tree as JSON
- `sentry help --json <group>` — emit route group metadata
- `sentry help --json <group> <cmd>` — emit specific command metadata
- Framework-injected flags (help, helpAll, log-level, verbose) are
  stripped from JSON output

Architecture:
- Extract shared route-tree introspection into src/lib/introspect.ts
- Consolidate duplicated type guards from help.ts and generate-skill.ts
- generate-skill.ts now imports from introspect.ts (no functional change)

Tests: 33 unit + 12 property-based + 10 integration tests

Author: BYK

AGENTS.md

@@ -13,6 +13,18 @@
  */
 
 import { routes } from "../src/app.js";
+import type {
+  CommandInfo,
+  FlagInfo,
+  RouteInfo,
+  RouteMap,
+} from "../src/lib/introspect.js";
+import {
+  buildCommandInfo,
+  extractRouteGroupCommands,
+  isCommand,
+  isRouteMap,
+} from "../src/lib/introspect.js";
 
 const OUTPUT_PATH = "plugins/sentry-cli/skills/sentry-cli/SKILL.md";
 const DOCS_PATH = "docs/src/content/docs";
@@ -26,61 +38,9 @@ const CODE_BLOCK_REGEX = /```(\w*)\n([\s\S]*?)```/g;
 /** Regex to extract npm command from PackageManagerCode Astro component (handles multi-line) */
 const PACKAGE_MANAGER_REGEX = /<PackageManagerCode[\s\S]*?npm="([^"]+)"/;
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Types for Stricli Route Introspection
-//
-// Note: While @stricli/core exports RouteMap and Command types, they require
-// complex generic parameters (CommandContext) and don't export internal types
-// like RouteMapEntry or FlagParameter. These simplified types are purpose-built
-// for introspection and documentation generation.
-// ─────────────────────────────────────────────────────────────────────────────
-
-type RouteMapEntry = {
-  name: { original: string };
-  target: RouteTarget;
-  hidden: boolean;
-};
-
-type RouteTarget = RouteMap | Command;
-
-type RouteMap = {
-  brief: string;
-  fullDescription?: string;
-  getAllEntries: () => RouteMapEntry[];
-};
-
-type Command = {
-  brief: string;
-  fullDescription?: string;
-  parameters: {
-    positional?: PositionalParams;
-    flags?: Record<string, FlagDef>;
-    aliases?: Record<string, string>;
-  };
-};
-
-type PositionalParams =
-  | { kind: "tuple"; parameters: PositionalParam[] }
-  | { kind: "array"; parameter: PositionalParam };
-
-type PositionalParam = {
-  brief?: string;
-  placeholder?: string;
-};
-
-type FlagDef = {
-  kind: "boolean" | "parsed";
-  brief?: string;
-  default?: unknown;
-  optional?: boolean;
-  variadic?: boolean;
-  placeholder?: string;
-  hidden?: boolean;
-};
-
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 // Markdown Parsing Utilities
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 
 /**
  * Strip YAML frontmatter from markdown content
@@ -175,9 +135,9 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 // Documentation Loading
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 
 /**
  * Load and parse a documentation file
@@ -398,132 +358,13 @@ async function loadCommandsOverview(): Promise<{
   };
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Route Introspection
-// ─────────────────────────────────────────────────────────────────────────────
-
-function isRouteMap(target: RouteTarget): target is RouteMap {
-  return "getAllEntries" in target;
-}
-
-function isCommand(target: RouteTarget): target is Command {
-  return "parameters" in target && !("getAllEntries" in target);
-}
-
-type CommandInfo = {
-  path: string;
-  brief: string;
-  fullDescription?: string;
-  flags: FlagInfo[];
-  positional: string;
-  aliases: Record<string, string>;
-  examples: string[];
-};
-
-type FlagInfo = {
-  name: string;
-  brief: string;
-  kind: "boolean" | "parsed";
-  default?: unknown;
-  optional: boolean;
-  variadic: boolean;
-  hidden: boolean;
-};
-
-type RouteInfo = {
-  name: string;
-  brief: string;
-  commands: CommandInfo[];
-};
-
-/**
- * Extract positional parameter placeholder string
- */
-function getPositionalString(params?: PositionalParams): string {
-  if (!params) {
-    return "";
-  }
-
-  if (params.kind === "tuple") {
-    return params.parameters
-      .map((p, i) => `<${p.placeholder ?? `arg${i}`}>`)
-      .join(" ");
-  }
-
-  if (params.kind === "array") {
-    const placeholder = params.parameter.placeholder ?? "args";
-    return `<${placeholder}...>`;
-  }
-
-  return "";
-}
-
-/**
- * Extract flag information from a command
- */
-function extractFlags(flags: Record<string, FlagDef> | undefined): FlagInfo[] {
-  if (!flags) {
-    return [];
-  }
-
-  return Object.entries(flags).map(([name, def]) => ({
-    name,
-    brief: def.brief ?? "",
-    kind: def.kind,
-    default: def.default,
-    optional: def.optional ?? def.kind === "boolean",
-    variadic: def.variadic ?? false,
-    hidden: def.hidden ?? false,
-  }));
-}
-
-/**
- * Build a CommandInfo from a Command
- */
-function buildCommandInfo(
-  cmd: Command,
-  path: string,
-  examples: string[] = []
-): CommandInfo {
-  return {
-    path,
-    brief: cmd.brief,
-    fullDescription: cmd.fullDescription,
-    flags: extractFlags(cmd.parameters.flags),
-    positional: getPositionalString(cmd.parameters.positional),
-    aliases: cmd.parameters.aliases ?? {},
-    examples,
-  };
-}
-
-/**
- * Extract commands from a route group
- */
-function extractRouteGroupCommands(
-  routeMap: RouteMap,
-  routeName: string,
-  docExamples: Map<string, string[]>
-): CommandInfo[] {
-  const commands: CommandInfo[] = [];
-
-  for (const subEntry of routeMap.getAllEntries()) {
-    if (subEntry.hidden) {
-      continue;
-    }
-
-    const subTarget = subEntry.target;
-    if (isCommand(subTarget)) {
-      const path = `sentry ${routeName} ${subEntry.name.original}`;
-      const examples = docExamples.get(path) ?? [];
-      commands.push(buildCommandInfo(subTarget, path, examples));
-    }
-  }
-
-  return commands;
-}
+// ---------------------------------------------------------------------------
+// Route Introspection (with async doc loading)
+// ---------------------------------------------------------------------------
 
 /**
- * Walk the route tree and extract command information
+ * Walk the route tree and extract command information with doc examples.
+ * This is the async version that loads documentation examples from disk.
  */
 async function extractRoutes(routeMap: RouteMap): Promise<RouteInfo[]> {
   const result: RouteInfo[] = [];
@@ -559,9 +400,9 @@ async function extractRoutes(routeMap: RouteMap): Promise<RouteInfo[]> {
   return result;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 // Markdown Generation
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 
 /**
  * Generate the front matter for the skill file
@@ -782,9 +623,9 @@ async function generateSkillMarkdown(routeMap: RouteMap): Promise<string> {
   return sections.join("\n");
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 // Main
-// ─────────────────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
 
 const content = await generateSkillMarkdown(routes as unknown as RouteMap);
 await Bun.write(OUTPUT_PATH, content);

script/generate-skill.ts

@@ -3,23 +3,34 @@
  *
  * Provides help information for the CLI.
  * - `sentry help` or `sentry` (no args): Shows branded help with banner
- * - `sentry help <command>`: Shows Stricli's detailed help (--helpAll) for that command
+ * - `sentry help <command>`: Shows detailed help for that command
+ * - `sentry help --json`: Emits full command tree as structured JSON
+ * - `sentry help --json <command>`: Emits specific command/group metadata as JSON
  */
 
-import { run } from "@stricli/core";
 import type { SentryContext } from "../context.js";
 import { buildCommand } from "../lib/command.js";
+import { OutputError } from "../lib/errors.js";
 import { CommandOutput } from "../lib/formatters/output.js";
-import { printCustomHelp } from "../lib/help.js";
+import {
+  formatHelpHuman,
+  introspectAllCommands,
+  introspectCommand,
+  printCustomHelp,
+} from "../lib/help.js";
 
 export const helpCommand = buildCommand({
   docs: {
     brief: "Display help for a command",
     fullDescription:
       "Display help information. Run 'sentry help' for an overview, " +
-      "or 'sentry help <command>' for detailed help on a specific command.",
+      "or 'sentry help <command>' for detailed help on a specific command. " +
+      "Use --json for machine-readable output suitable for AI agents.",
+  },
+  output: {
+    human: formatHelpHuman,
+    jsonExclude: ["_banner"] as const,
   },
-  output: { human: (s: string) => s.trimEnd() },
   parameters: {
     flags: {},
     positional: {
@@ -33,15 +44,21 @@ export const helpCommand = buildCommand({
   },
   // biome-ignore lint/complexity/noBannedTypes: Stricli requires empty object for commands with no flags
   async *func(this: SentryContext, _flags: {}, ...commandPath: string[]) {
-    // No args: show branded help
     if (commandPath.length === 0) {
-      return yield new CommandOutput(await printCustomHelp());
+      // Yield the full command tree. Attach the branded banner for human display;
+      // jsonExclude strips _banner from JSON output.
+      const tree = introspectAllCommands();
+      const banner = await printCustomHelp();
+      return yield new CommandOutput({ ...tree, _banner: banner });
     }
 
-    // With args: re-invoke with --helpAll to show full help including hidden items
-    // Use dynamic imports to avoid circular dependency (app.ts imports helpCommand)
-    const { app } = await import("../app.js");
-    const { buildContext } = await import("../context.js");
-    await run(app, [...commandPath, "--helpAll"], buildContext(this.process));
+    // Resolve the command path and yield the result.
+    // This ensures --json mode always gets structured output.
+    const result = introspectCommand(commandPath);
+    if ("error" in result) {
+      // OutputError renders through the output system but exits non-zero
+      throw new OutputError(result);
+    }
+    return yield new CommandOutput(result);
   },
 });