fix(skill): include widget subcommands in generated skill files (#519)

## Summary

- `extractRouteGroupCommands` only processed direct `Command` children,
skipping nested `RouteMap` entries like `dashboard > widget`
- Added recursion so nested route maps (e.g. `sentry dashboard widget
add/edit/delete`) are included in generated SKILL.md and reference files
- Regenerated skill files with the fix applied

## Test plan

- [x] `bun run typecheck` passes
- [x] `bun run lint` passes
- [x] `bun test test/lib/introspect.test.ts test/commands/dashboard/
test/commands/help.test.ts` — 95 tests pass
- [x] `bun run generate:skill` produces `dashboards.md` with widget
commands
- [x] SKILL.md includes `sentry dashboard widget add/edit/delete`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: betegon

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

@@ -226,6 +226,9 @@ Manage Sentry dashboards
 - `sentry dashboard list <org/project>` — List dashboards
 - `sentry dashboard view <args...>` — View a dashboard
 - `sentry dashboard create <args...>` — Create a dashboard
+- `sentry dashboard widget add <args...>` — Add a widget to a dashboard
+- `sentry dashboard widget edit <args...>` — Edit a widget in a dashboard
+- `sentry dashboard widget delete <args...>` — Delete a widget from a dashboard
 
 → Full flags and examples: `references/dashboards.md`
 

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

@@ -85,4 +85,41 @@ sentry dashboard create 'Frontend Performance'
 sentry dashboard widget add 'Frontend Performance' "Error Count" --display big_number --query count
 ```
 
+### `sentry dashboard widget add <args...>`
+
+Add a widget to a dashboard
+
+**Flags:**
+- `-d, --display <value> - Display type (line, bar, table, big_number, ...)`
+- `--dataset <value> - Widget dataset (default: spans)`
+- `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
+- `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`
+- `-g, --group-by <value>... - Group-by column (repeatable)`
+- `-s, --sort <value> - Order by (prefix - for desc, e.g. -count)`
+- `-n, --limit <value> - Result limit`
+
+### `sentry dashboard widget edit <args...>`
+
+Edit a widget in a dashboard
+
+**Flags:**
+- `-i, --index <value> - Widget index (0-based)`
+- `-t, --title <value> - Widget title to match`
+- `--new-title <value> - New widget title`
+- `-d, --display <value> - Display type (line, bar, table, big_number, ...)`
+- `--dataset <value> - Widget dataset (default: spans)`
+- `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
+- `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`
+- `-g, --group-by <value>... - Group-by column (repeatable)`
+- `-s, --sort <value> - Order by (prefix - for desc, e.g. -count)`
+- `-n, --limit <value> - Result limit`
+
+### `sentry dashboard widget delete <args...>`
+
+Delete a widget from a dashboard
+
+**Flags:**
+- `-i, --index <value> - Widget index (0-based)`
+- `-t, --title <value> - Widget title to match`
+
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

src/lib/help.ts

@@ -281,12 +281,17 @@ function formatGroupHuman(group: RouteInfo): string {
     return lines.join("\n");
   }
 
-  const maxName = Math.max(
-    ...group.commands.map((c) => (c.path.split(" ").at(-1) ?? "").length)
-  );
+  // Strip "sentry <group> " prefix to get subcommand name.
+  // For nested routes like "sentry dashboard widget add", this yields "widget add".
+  const prefix = `sentry ${group.name} `;
+  const subName = (cmd: CommandInfo) =>
+    cmd.path.startsWith(prefix)
+      ? cmd.path.slice(prefix.length)
+      : (cmd.path.split(" ").at(-1) ?? "");
+
+  const maxName = Math.max(...group.commands.map((c) => subName(c).length));
   for (const cmd of group.commands) {
-    const name = cmd.path.split(" ").at(-1) ?? "";
-    lines.push(`    ${name.padEnd(maxName + 2)}${cmd.brief}`);
+    lines.push(`    ${subName(cmd).padEnd(maxName + 2)}${cmd.brief}`);
   }
 
   return lines.join("\n");

src/lib/introspect.ts

@@ -250,6 +250,11 @@ export function extractRouteGroupCommands(
       const path = `sentry ${routeName} ${subEntry.name.original}`;
       const examples = docExamples.get(path) ?? [];
       commands.push(buildCommandInfo(subTarget, path, examples));
+    } else if (isRouteMap(subTarget)) {
+      const nestedPrefix = `${routeName} ${subEntry.name.original}`;
+      commands.push(
+        ...extractRouteGroupCommands(subTarget, nestedPrefix, docExamples)
+      );
     }
   }
 
@@ -294,6 +299,9 @@ export function extractAllRoutes(routeMap: RouteMap): RouteInfo[] {
   return result;
 }
 
+/** Matches the "sentry " prefix at the start of a command path. */
+const SENTRY_PREFIX_RE = /^sentry /;
+
 /** Maximum number of fuzzy suggestions to include in an UnresolvedPath. */
 const MAX_SUGGESTIONS = 3;
 
@@ -369,40 +377,36 @@ export function resolveCommandPath(
     return null;
   }
 
-  // Only support exactly 2 levels deep (group + command).
-  // Extra segments (e.g. ["issue", "list", "extra"]) are rejected.
-  if (rest.length !== 1) {
+  // Recurse into the sub-route map with remaining path segments
+  const subResult = resolveCommandPath(target, rest);
+  if (!subResult) {
     return null;
   }
 
-  // Find the subcommand, with fuzzy fallback
-  const subName = rest[0];
-  if (subName === undefined) {
-    return null;
-  }
-  const visibleSubEntries = target.getAllEntries().filter((e) => !e.hidden);
-  const subEntry = visibleSubEntries.find((e) => e.name.original === subName);
+  // Prepend the parent route segment to all paths in the result
+  const parentPrefix = entry.name.original;
+  const prependPrefix = (p: string) =>
+    p.replace(SENTRY_PREFIX_RE, `sentry ${parentPrefix} `);
 
-  if (!subEntry) {
-    const subNames = visibleSubEntries.map((e) => e.name.original);
+  if (subResult.kind === "command") {
     return {
-      kind: "unresolved",
-      input: subName,
-      suggestions: fuzzyMatch(subName, subNames, {
-        maxResults: MAX_SUGGESTIONS,
-      }),
+      kind: "command",
+      info: { ...subResult.info, path: prependPrefix(subResult.info.path) },
     };
   }
-
-  if (isCommand(subEntry.target)) {
+  if (subResult.kind === "group") {
     return {
-      kind: "command",
-      info: buildCommandInfo(
-        subEntry.target,
-        `sentry ${entry.name.original} ${subEntry.name.original}`
-      ),
+      kind: "group",
+      info: {
+        ...subResult.info,
+        name: `${parentPrefix} ${subResult.info.name}`,
+        commands: subResult.info.commands.map((cmd) => ({
+          ...cmd,
+          path: prependPrefix(cmd.path),
+        })),
+      },
     };
   }
 
-  return null;
+  return subResult;
 }

test/commands/help.test.ts

@@ -146,6 +146,28 @@ describe("sentry help --json <group> <command>", () => {
   });
 });
 
+describe("sentry help --json nested routes (dashboard widget)", () => {
+  test("nested group has correct name and commands", async () => {
+    const output = await runHelp(["--json", "dashboard", "widget"]);
+    const parsed = JSON.parse(output);
+
+    expect(parsed).toHaveProperty("name", "dashboard widget");
+    expect(parsed).toHaveProperty("commands");
+    const paths = parsed.commands.map((c: { path: string }) => c.path);
+    expect(paths).toContain("sentry dashboard widget add");
+    expect(paths).toContain("sentry dashboard widget edit");
+    expect(paths).toContain("sentry dashboard widget delete");
+  });
+
+  test("nested command resolves with full path", async () => {
+    const output = await runHelp(["--json", "dashboard", "widget", "add"]);
+    const parsed = JSON.parse(output);
+
+    expect(parsed).toHaveProperty("path", "sentry dashboard widget add");
+    expect(parsed).toHaveProperty("flags");
+  });
+});
+
 describe("introspectCommand error cases", () => {
   // Error cases throw OutputError (which calls process.exit) through the
   // framework, so we test the introspection functions directly here.