Distillation

🔴 (09:33) In packages/cli/src/lib/command.ts, SentryCommandFunction requires async generators returning CommandReturn | void; non-streaming commands yield one CommandOutput<T>, streaming commands render each yield immediately, JSON-capable streaming commands must yield one aggregate value when callers need one parseable JSON document because chunks are pretty-printed rather than JSONL, and void commands may return without yielding. 🔴 (09:33) Hints in packages/cli/src/lib/command.ts live exclusively on the generator return value and never on individual yields. 🔴 (09:33) buildCommand() is the required command builder for all Sentry CLI commands; importing buildCommand directly from @stricli/core bypasses telemetry and global flag handling. 🔴 (09:33) buildCommand() injects hidden global --log-level, --verbose, --org, and --project flags unless a command owns the corresponding flag; injected flags are stripped before the command function runs, while a command-owned verbose, org, or project is passed through. 🔴 (09:33) The --log-level flag key is always stripped, including if the command defined it itself; ALWAYS_STRIP = new Set([LOG_LEVEL_KEY]). 🔴 (09:33) applyLoggingFlags() gives --log-level priority over --verbose; --verbose maps to debug, and if neither is supplied the environment/default logging level remains unchanged. 🔴 (09:33) Hidden compatibility flags --org and --project are intended to recover older sentry-cli syntax commonly generated by LLMs; applyOrgProjectFlags() trims their values and writes non-empty values to SENTRY_ORG and SENTRY_PROJECT, overwriting existing environment variables because explicit CLI flags have highest-priority intent. 🔴 (09:33) applyOrgProjectFlags() ignores empty or whitespace-only compatibility values and does not map a compatibility flag when the command owns its corresponding org or project flag. 🔴 (09:33) --json and --fields are injected when an output config exists; a command-owned json definition is retained, but --fields is always injected when output: { human: ... }. 🔴 (09:33) --fields accepts comma-separated dot-notation paths, is silently ignored without --json, and is pre-parsed by cleanRawFlags() from a raw string into string[] before the command function receives it. 🔴 (09:33) If output.schema exists, buildFieldsFlag() appends available field names to the --fields brief, enrichDocsWithSchema() appends formatted JSON field documentation to fullDescription, and the built command receives a non-standard __jsonSchema property for introspection. 🔴 (09:33) Authentication in buildCommand() defaults to required; missing credentials cause AuthError("not_authenticated"), while auth: false opts out and auth: "dsn" skips both the bearer-token guard and .sentryclirc URL trust check. 🔴 (09:33) .sentryclirc URL trust validation is deferred until command execution via dynamically imported assertRcUrlTrusted(this.cwd); it is skipped when skipRcUrlCheck: true or auth: "dsn". 🔴 (09:33) handleYieldedValue() ignores void, undefined, errors, and other unbranded values; it renders only CommandOutput instances when both an output config and renderer exist. 🔴 (09:33) ClearScreen tokens are deferred until the next render to avoid flashing, ignored in plain or JSON output, and otherwise produce the clear prefix \x1b[H\x1b[J. 🔴 (09:33) Environment-based machine output sets cleanFlags.json = true when an output config exists and this.env.SENTRY_OUTPUT_FORMAT === "json". 🔴 (09:33) Interactive prompts are disabled when parsed json, yes, or dry-run is exactly true; checking parsed flags avoids confusing command-specific aliases such as list -n for limit with init -n for dry-run. 🔴 (09:33) The wrapper manually iterates generators with .next() rather than for await...of so it can capture the final CommandReturn; execution is traced as withTracing("exec", "cli.command.exec", ...) and final rendering as withTracing("render", "cli.command.render", ...). 🔴 (09:33) After successful generator completion, appendCacheHint(returned.hint) adds cache-age messaging such as “cached · 3m ago · use -f to refresh”; bare return; paths receive no footer. 🔴 (09:33) writeFinalization() suppresses all finalization in JSON mode, otherwise prefers renderer.finalize(hint) and falls back to writeFooter(stdout, hint). 🔴 (09:33) On errors, human-mode renderer finalization runs first with no hint to close streaming state; JSON mode skips this to avoid corrupting machine-readable output. 🔴 (09:33) maybeRecoverWithHelp() treats positional "help", "--h", or "-help" as likely mistaken help syntax only after a CliError; it excludes OutputError, requires ctx.commandPrefix, dynamically imports ./help.js, writes a warning tip to stderr, and writes formatted command help to stdout. 🔴 (09:33) OutputError with non-null/undefined data is rendered through the normal CommandOutput pipeline and then re-thrown so bin.ts and index.ts can preserve its exit code. 🔴 (09:33) buildCommand() attaches __rawFunc = originalFunc so internal dispatchers such as bare sentry auth can invoke a subcommand without re-entering telemetry, authentication, rc-trust, or output handling. 🔴 (09:33) In packages/cli/src/lib/introspect.ts, tuple positionals use <placeholder> for required parameters and [<placeholder>] for optional parameters; variadic arrays render as <placeholder...>, while extractPositionals() marks array positionals optional and records their placeholder with .... 🔴 (09:33) buildCommandInfo() uses __primaryUsage before derived positional syntax, maps structured __examples to # <description>\n<command>, and otherwise falls back to externally supplied documentation examples. 🔴 (09:33) Introspection omits hidden route entries, recursively traverses nested route maps, extracts hidden/default/optional/variadic flag metadata, and limits fuzzy unresolved-path suggestions to MAX_SUGGESTIONS = 3.