Distillation

🔴 (09:33) packages/cli/script/generate-skill.ts generates 3 artifact groups from Stricli route metadata and docs: plugins/sentry-cli/skills/sentry-cli/SKILL.md, per-route plugins/sentry-cli/skills/sentry-cli/references/*.md, and docs/public/.well-known/skills/index.json. 🔴 (09:33) packages/cli/script/generate-skill.ts bootstraps missing src/generated/skill-content.ts before dynamically importing ../src/app.js; it creates src/generated/ recursively and writes export const SKILL_FILES: ReadonlyMap<string, string> = new Map();\n to avoid the app.ts → agent-skills.ts → skill-content.ts fresh-checkout module-resolution failure. 🔴 (09:33) findDefaultCommandName() in packages/cli/script/generate-skill.ts resolves a route map’s default command by object identity; the hidden subcommand name "default" is specially mapped to "login" so bare sentry auth documentation examples attach to sentry auth login. 🔴 (09:33) Skill generation paths/constants are SKILL_DIR = "plugins/sentry-cli/skills/sentry-cli", OUTPUT_PATH = \${SKILL_DIR}/SKILL.md`, REFERENCES_DIR = `${SKILL_DIR}/references`, INDEX_JSON_PATH = `${DOCS_PUBLIC}/.well-known/skills/index.json`, and DOCS_PATH = DOCS_CONTENT. 🔴 (09:33) getPackageVersion()readspackage.jsonas UTF-8 and returnspkg.versionfor generated YAML frontmatter. 🔴 (09:33) The generated skill description is exactly: “Guide for using the Sentry CLI to interact with Sentry from the command line. Use when the user asks about viewing issues, events, projects, organizations, making API calls, or authenticating with Sentry via CLI.” 🔴 (09:33) Preferred skill route ordering is["help", "auth", "org", "project", "issue", "event", "api"]; routes absent from this list receive sort order 999, preserving comparator equality rather than explicitly alphabetizing them. 🔴 (09:33) GLOBAL_FLAG_NAMESinpackages/cli/script/generate-skill.tscontains"json", "fields", "help", "helpAll", and "log-level"; these are excluded from compact/per-command visible flags and documented globally instead. 🔴 (09:33) Markdown preprocessing in packages/cli/script/generate-skill.tsusesFRONTMATTER_REGEX = /^---\n[\s\S]?\n---\n/, CODE_BLOCK_REGEX = /(\w*)\n([\s\S]*?)/g, and PACKAGE_MANAGER_REGEX = /<PackageManagerCode[\s\S]?npm="([^"]+)"/; stripMdxComponents()removes one-line imports/exports, self-closing capitalized JSX components, paired capitalized JSX components, and collapses 3-or-more newlines to 2. 🔴 (09:33)extractSection()finds a named Markdown heading at levels 1–6 and returns content through the next heading of the same or higher level;extractCodeBlocks()returns trimmed{ code, lang }records and can filter by exact language. 🔴 (09:33)loadDoc(relativePath)reads${DOCS_CONTENT}/${relativePath}, returns nullwhen inaccessible, and otherwise strips YAML frontmatter plus MDX/Astro components. 🔴 (09:33)loadPrerequisites()reads${DOCS_CONTENT}/getting-started.mdx, states that the CLI must be installed and authenticated, extracts the "Install Script"and"Authentication"sections, combines bash blocks, and extracts the npm command from<PackageManagerCode ... npm="...">. 🔴 (09:33) The fallback prerequisites in getDefaultPrerequisites()prescribe: install withcurl https://cli.sentry.dev/install -fsS | bashornpm install -g sentry; authenticate with recommended OAuth via sentry author API token viasentry auth --token YOUR_SENTRY_API_TOKEN; verify with sentry auth status. 🔴 (09:33) Skill example extraction uses marked.lexer(): collectCommandPaths()recognizes only depth-3 headings parsed byextractCommandPathFromHeading(), initializes each discovered command path in a Map<string, string[]>, and associateCodeBlocks()processes onlybashcode tokens. 🔴 (09:33)associateCodeBlocks()first assigns bash blocks under a recognized current depth-3 command heading; otherwise it callsmatchExampleToCommand(code, commandPaths, `sentry ${commandGroup}`, defaultCommandPath)for content-based matching. 🔴 (09:33)loadCommandExamples(commandGroup, defaultCommandName?)readscommands/${commandGroup}.md; if a default is supplied, it constructs sentry ${commandGroup} ${defaultCommandName}as the fallback default command path, and returns an empty map when the doc is absent. 🔴 (09:33)loadCommandsOverview()extracts"Global Options", "JSON Output", and "Opening in Browser"fromcommands/index.md; loadAgentGuidance()loadsagent-guidance.md. 🔴 (09:33) extractRoutes()skips hidden top-level entries, loads examples once per visible route, usesextractRouteGroupCommands()for nested route maps, and usesbuildCommandInfo(target, `sentry ${routeName}`, examples)for standalone commands. 🔴 (09:33) Skill flag formatting renders aliases as-<alias>, --<name>; non-variadic parsed/enum flags append <value>, variadic flags append <value>..., briefs follow with - , and non-boolean defaults render as (default: ${JSON.stringify(flag.default)}). 🔴 (09:33) getVisibleFlags()excludes flags that are hidden or included inGLOBAL_FLAG_NAMES. 🔴 (09:33) generateFullCommandDoc()emits a depth-3 command signature, brief, visible flag list, optional JSON-field table, and formatted examples fromformatCommandExamples(); JSON field types and descriptions escape |as|. 🔴 (09:33) JSON-field documentation tells users: JSON Fields (use `--json --fields` to select specific fields):and uses columnsField, Type, and Description. 🔴 (09:33) Generated reference titles uppercase recognized acronyms from TITLE_ACRONYMS = new Set(["api", "cli"]); other route names only have their first character uppercased. 🔴 (09:33) generateReferenceFile()creates one reference file per route with YAML fieldsname: sentry-cli-${refName}, package version, route-brief description, requires.bins: ["sentry"], and requires.auth: true; it includes every full command document and ends with the statement that all commands support --json, --fields, --help, --log-level, and --verbose. 🔴 (09:33) The compact SKILL.mdcommand reference skips the"help"route, emits each command as- `<signature>` — <brief>, and links each route to references/<file>using a 1:1 route-to-reference-file mapping. 🔴 (09:33) Supplementary skill sections use documentation-derived global options, JSON output guidance, and browser-opening guidance when available; fallbacks state that most commands support--jsonand that view commands support-wor--web`.

🔴 (09:34) packages/cli/script/generate-command-docs.ts generates one gitignored command page per visible route at docs/src/content/docs/commands/{route}.md, with committed hand-written fragments supplying custom examples/guides. 🔴 (09:34) readCustomContent(fragmentName) reads ${FRAGMENTS_DIR}/${fragmentName}.md, while readTopLevelFragment(fragmentName) reads ${FRAGMENTS_ROOT}/${fragmentName}.md; both return "" on any read failure. 🔴 (09:34) packages/cli/script/generate-command-docs.ts casts routes to RouteMap, calls extractAllRoutes(routeMap), and filters out names in SKIP_ROUTES. 🔴 (09:34) Command-doc generation creates DOCS_DIR recursively and removes the legacy ${DOCS_DIR}/cli directory with rmSync(..., { recursive: true, force: true }) because generation now uses cli.md. 🔴 (09:34) For each route, generate-command-docs.ts writes ${DOCS_DIR}/${route.name}.md; generated page content is followed directly by the route fragment when present, otherwise followed by a newline, and each path is tracked in generatedFiles. 🔴 (09:34) The generated commands index has frontmatter title: Commands and description: Available commands in the Sentry CLI, introduces the CLI as providing commands for interacting with Sentry resources, adds ## Available Commands, inserts generateCommandsTable(routeInfos), and appends GENERATED_END_MARKER before optional commands/index.md fragment content. 🔴 (09:34) Configuration documentation is generated with generateConfigurationPage(ENV_VAR_REGISTRY) and then appended with the top-level configuration fragment before writing CONFIG_PATH. 🔴 (09:34) generate-command-docs.ts reports the exact runtime count using Generated ${generatedFiles.length} command doc pages + ${INDEX_PATH} + ${CONFIG_PATH}.

🔴 (09:34) packages/cli/script/check-fragments.ts validates 5 conditions: every documented route has a command fragment plus index.md; every command fragment maps to a route or index; fragments contain neither frontmatter nor the generated marker; required top-level fragments exist; and multi-command route fragments cover all subcommands. 🔴 (09:34) packages/cli/script/check-fragments.ts supports tsx script/check-fragments.ts for subcommand-coverage warnings and tsx script/check-fragments.ts --strict to treat missing subcommand coverage as errors. 🔴 (09:34) On a fresh checkout, check-fragments.ts ensures src/generated/skill-content.ts exists before importing ../src/app.js; its stub is export const SKILL_FILES: [string, string][] = [];\n, which differs from the ReadonlyMap<string, string> stub in generate-skill.ts. 🔴 (09:34) Fragment validation uses FRAGMENTS_DIR = \${DOCS_FRAGMENTS}/commands`, GENERATED_END_MARKER = "<!-- GENERATED:END -->", SKIP_ROUTES = new Set(["help"]), MD_EXTENSION_RE = /.md$/, and detects strict mode with process.argv.includes("--strict"). 🔴 (09:34) Expected command fragments are every visible extractAllRoutes(routeMap)route except"help", plus "index"; failure to read the fragments directory logs ERROR: Fragment directory not found: ${FRAGMENTS_DIR}and exits with status 1. 🔴 (09:34) A missing expected file producesMissing fragment: ${FRAGMENTS_DIR}/${name}.md (route "${name}" exists but has no fragment file); an unmatched file produces Stale fragment: ${FRAGMENTS_DIR}/${name}.md (no matching route found — delete it or add the route). 🔴 (09:34) Fragment content is rejected as frontmatter when it includes "---\ntitle:"or starts with"---\n"; it is also rejected if it contains <!-- GENERATED:END -->. 🔴 (09:34) REQUIRED_TOP_LEVEL_FRAGMENTS = ["configuration"]; a missing file at ${DOCS_FRAGMENTS}/configuration.mdis a validation error because it is required for generatedconfiguration.md. 🔴 (09:34) Subcommand-coverage checks strip fenced code blocks using FENCED_CODE_BLOCK_RE = /^({3,}|~{3,}).*\n[\s\S]*?\n\1\s*$/gm before matching headings, preventing bash comments inside code fences from being interpreted as Markdown headings. 🔴 (09:34) fragmentMentionsSubcommand() accepts coverage through 3 mechanisms in order: 1. the complete command.path such as sentry dashboard revisions anywhere in content, including prose/backticks/code; 2. for a default command, a bare sentry <route> matched with a boundary-aware regex; 3. a level 1–4 heading outside fenced code blocks containing the leaf subcommand name. 🔴 (09:34) The bare-default-route regex intentionally avoids counting sentry issue events as coverage for bare sentry issue. 🔴 (09:34) getMultiCommandRoutes() omits standalone routes only when they have at most 1 command and route.commands[0]?.path === \sentry ${route.name}`; all other routes are checked for subcommand coverage. 🔴 (09:34) findDefaultInRouteMap()finds a route’s default command by comparing the object returned bytarget.getDefaultCommand()against eachsub.target; unlike skill generation’s auth-specific logic, it returns the original subcommand name without mapping "default"to"login". 🔴 (09:34) During coverage validation, commands with non-empty cmd.examplesare skipped; for remaining commands, the script derives the subpath aftersentry <route>, compares its leaf to the route’s default command name, and records uncovered subpaths. 🔴 (09:34) A missing-coverage diagnostic lists the fragment path, every undocumented subcommand joined by , , and a hint using the first missing command: add a heading or code example for each (e.g., "sentry ${routeName} ${missing[0]}"). 🔴 (09:34) Missing subcommand coverage is accumulated in warningsnormally orerrorsunder--strict; warnings are printed with ⚠, errors with ✗, and any errors cause process.exit(1). 🔴 (09:34) Successful fragment validation reports All ${actualFragments.size} command fragment files valid (${routeNames.size} routes + index)andAll ${REQUIRED_TOP_LEVEL_FRAGMENTS.length} top-level fragment(s) valid`.