Distillation

Date: Sep 9, 2026

• 🔴 (14:17) In packages/cli/src/lib/list-command.ts, buildListCommand() now accepts the shared CommandDocumentation type imported from ./command.js; OrgListCommandDocs is now an alias of CommandDocumentation, allowing canonical command examples and other shared documentation metadata.
• 🔴 (14:17) In packages/cli/src/lib/mutate-command.ts, buildDeleteCommand() now accepts docs: CommandDocumentation, imported from ./command.js, instead of a local { brief; fullDescription? } type.
• 🔴 (14:17) User stated buildDeleteCommand() must always inject --yes unless the command already defines it. It injects -y unless already defined; injects --force/-f unless DeleteCommandOptions.noForceFlag opts out or the definitions already exist; and injects --dry-run unless DeleteCommandOptions.noDryRunFlag opts out or the flag already exists.
• 🔴 (14:17) /home/byk/Code/getsentry/cli-pr-1558/packages/cli/script/generate-command-docs.ts generates documentation by introspecting the CLI route tree and ENV_VAR_REGISTRY, combining generated reference/examples with hand-written fragments. Outputs are docs/src/content/docs/commands/{route}.md, docs/src/content/docs/commands/index.md, and docs/src/content/docs/configuration.md; generated output is gitignored, while docs/src/fragments/ is the committed source of truth for custom content.
• 🔴 (14:17) packages/cli/script/generate-command-docs.ts ensures src/generated/skill-content.ts exists before dynamically importing ../src/app.js: if absent, it creates src/generated/ and writes the exact stub export const SKILL_FILES: [string, string][] = [];\n. This avoids failure from the transitive agent-skills.ts → skill-content.ts import on fresh checkouts or CI; generate:skill later overwrites the stub.
• 🔴 (14:17) packages/cli/script/generate-command-docs.ts imports formatCommandExamples() from ./generate-skill-markdown.js, paths from ./paths.js, then dynamically loads routes, extractAllRoutes, and ENV_VAR_REGISTRY. Its output constants are DOCS_DIR = ${DOCS_CONTENT}/commands, FRAGMENTS_DIR = ${DOCS_FRAGMENTS}/commands, INDEX_PATH = ${DOCS_DIR}/index.md, and CONFIG_PATH = ${DOCS_CONTENT}/configuration.md.
• 🔴 (14:17) Generated documentation uses the separator <!-- GENERATED:END -->. Per-command tables exclude hidden flags and global flags in GLOBAL_FLAG_NAMES: json, fields, help, helpAll, and log-level. SKIP_ROUTES contains help.
• 🔴 (14:17) In generate-command-docs.ts, formatFlagRow() finds the first alias targeting a flag, renders syntax as -x, --name, appends <name> for non-variadic parsed/enum flags or <name>... for variadic flags, and appends (default: ${JSON.stringify(flag.default)}) only for defined non-boolean defaults when the brief does not already contain default:.
• 🔴 (14:17) In generate-command-docs.ts, escapeAngleBrackets() converts </> to </>. formatPositionalsTable() returns "" for no positionals and otherwise creates an **Arguments:** table with required syntax <placeholder> or optional syntax [<placeholder>], escaping angle brackets in each brief.
• 🔴 (14:17) In generate-command-docs.ts, formatFlagsTable() returns "" for no flags and otherwise creates an **Options:** table using formatFlagRow(). generateCommandSection() renders a ### heading from cmd.path plus cmd.positional, the command brief, optional argument and visible-option tables, and examples formatted by formatCommandExamples(cmd.examples).
• 🔴 (14:17) isStandaloneCommand(route) identifies a standalone route only when it has exactly 1 command whose path is sentry ${route.name}. generatePage() uses ## Usage for standalone commands and ## Commands for groups, emits YAML frontmatter, adds every command section, and ends with: All commands support \--json` for machine-readable output and `--fields` to select specific JSON fields.followed by<!-- GENERATED:END -->`.
• 🔴 (14:17) generate-command-docs.ts title capitalization special-cases api and cli through ACRONYMS, rendering them as API and CLI; other route names have only their first character uppercased.
• 🔴 (14:17) generateCommandsTable() preserves the route order returned by extractAllRoutes()—which reflects insertion order in app.ts’s buildRouteMap—and renders each entry as | [\${route.name}`](./${route.name}/) | ${route.brief} |`.
• 🔴 (14:17) generateEnvVarSection() renders each EnvVarEntry as a ### \VAR_NAME`section with its description and, whenexample !== undefined, a Bash block containing export ${entry.name}=${entry.example}`.
• 🔴 (14:17) generateConfigurationPage() emits Configuration frontmatter, explains that the CLI can use config files, environment variables, and a local database, notes project auto-detection and credential storage after sentry auth login, renders every ENV_VAR_REGISTRY entry under ## Environment Variables, and terminates generated content with <!-- GENERATED:END -->.
• 🔴 (14:17) In generate-command-docs.ts, readCustomContent(fragmentName) reads docs/src/fragments/commands/${fragmentName}.md, while readTopLevelFragment(fragmentName) reads docs/src/fragments/${fragmentName}.md; both return "" on any read failure.
• 🔴 (14:17) The documentation generator casts routes to RouteMap, filters out routes in SKIP_ROUTES, creates the command output directory recursively, removes the legacy ${DOCS_DIR}/cli directory with { recursive: true, force: true }, writes one ${route.name}.md page per visible route, appends matching custom fragments, builds commands/index.md, and builds configuration.md with the top-level configuration fragment.
• 🔴 (14:17) Generated commands/index.md uses title Commands, description Available commands in the Sentry CLI, intro The Sentry CLI provides commands for interacting with various Sentry resources., an ## Available Commands table, and <!-- GENERATED:END -->; the generator logs Generated ${generatedFiles.length} command doc pages + ${INDEX_PATH} + ${CONFIG_PATH}.
• 🔴 (14:17) /home/byk/Code/getsentry/cli-pr-1558/packages/cli/script/generate-skill-markdown.ts defines the exact heading matcher COMMAND_HEADING_RE = /^sentry\s+([^<[\s]+(?:\s+[^<[\s]+))(?:\s(?:<|[)[^]*)?$/`, which extracts a literal command path while stopping before positional usage.
• 🔴 (14:17) extractCommandPathFromHeading(heading) in packages/cli/script/generate-skill-markdown.ts returns sentry ${match[1]} when COMMAND_HEADING_RE matches, otherwise undefined.
• 🔴 (14:17) matchExampleToCommand(code, commandPaths, groupFallback, defaultCommandPath?) sorts command paths by descending length so a specific path such as sentry auth login wins over sentry auth, returns the first path included in the code, returns undefined when the group fallback is absent, and assigns a bare-group example to defaultCommandPath ?? groupFallback.
• 🔴 (14:17) formatCommandExamples(examples) in packages/cli/script/generate-skill-markdown.ts returns "" for no examples; otherwise it emits an **Examples:** section with one bash fence and joins canonical examples using exactly 1 blank line between entries (examples.join("\n\n")).