Generate CLI output schemas from command output types

Cerrado
  • ¿Algo no está bien?
#1,824 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Ya se ha fusionado un pull request relacionado.

  • #1830 de @sentry-junior — fusionado

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
12/100
Tipo de issue
Refactorización
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
typescript
Área
cli, tooling

Línea de trabajo

Start with packages/cli/src/commands/alert/output-schemas.ts to see how API fields and hand-written CLI fields are declared alongside the TypeScript output types. The existing completion-target and command-api generators are the model for any build step, and packages/cli/AGENTS.md is where the new declaration convention would be documented. This is design work, and PR #1830 is already open against it, so pick it up only after confirming with maintainers which option is chosen.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

CLI

Problem

Command output schemas (OutputConfig.schema) drive --fields completion, the JSON field tables in --help, and the generated skill references. Since #1783, the fields that come from the Sentry API are taken from the generated @sentry/api/valibot response schemas (for example packages/cli/src/commands/alert/output-schemas.ts). Fields the CLI adds itself are still written by hand, next to a TypeScript output type that describes the same data:

  • target context: org, project, orgSlug, targetProject
  • status and result flags: the alert status label, deleted, dryRun (DryRunOutputField)
  • computed values: dsn, url, dashboard period/fetchedAt, widget data

So every command declares its JSON output twice: once as the TypeScript type its func yields and output.human consumes, and once as a valibot schema. Nothing checks that the two agree. The schema is documentation only (nothing validates output against it), so drift goes unnoticed. A field added to the type silently stops completing, and a renamed field keeps completing a path that no longer exists. Raised by @BYK in https://github.com/getsentry/toolkit/pull/1783#discussion_r4448809546 ("Shouldn't this be auto-generated?").

Goal

One source of truth per command's JSON output: the API part from @sentry/api, and the CLI-added part derived from the command's output type instead of written by hand.

Options

  1. Generate schemas from TypeScript types at build time. Add a generate:* step, like the existing completion-target and command-api generators, that reads each command's declared output type and emits a valibot (or plain field-path) description. Candidates: the TS compiler API, or a types-to-schema tool. Descriptions would come from TSDoc on the type's properties.
    • Pros: types stay the source of truth, and descriptions sit next to the fields.
    • Cons: output types are often inferred or built from Pick/intersections over SDK types. The generator has to resolve those, and it has to know which type belongs to which command.
  2. Invert it: schema first, types derived. Write the CLI-added entries once as valibot and derive the TS type with InferOutput<typeof Schema>, so func's return type and output.human's parameter come from the schema.
    • Pros: no new generator, and the compiler enforces that the two agree.
    • Cons: valibot becomes the authoring format for output types, which means touching many commands.
  3. Keep both, add a type-level check. Keep hand-written schemas, but add a compile-time assertion per command, e.g. Expect<Equal<keyof InferOutput<typeof Schema>, keyof Output>>, or a test that compares field paths.
    • Pros: smallest change.
    • Cons: still two copies to maintain, and only drift is caught.

Option 2 looks like the best fit for buildCommand. Option 1 is worth it only if descriptions can come from TSDoc reliably.

Dependencies

  • Descriptions for API fields need the upstream change from the #1783 plan: @sentry/api's generated valibot has no v.description() actions today, so the CLI wraps generated fields in pipe(field, description(...)) by hand. Until that lands, this issue only covers the CLI-added fields.
  • Related: #1387 (migrate fully to @sentry/api SDK types), and #1808 / the sentry-cli/json-transform-uses-fields lint rule (jsonTransform must apply fields).

Done when

  • No command's output schema writes out by hand a field that also exists in its TypeScript output type, or a test/compile error fails when they diverge.
  • --fields completion, --help field tables and the skill references keep working unchanged, and the generated docs don't change unexpectedly.
  • packages/cli/AGENTS.md documents how to declare output for a new command.

via @BYK.

--

View Session in Sentry

Lenguaje dominante
TypeScript
Estrellas
957
Forks
174
Merge medio
22 h 56 min
PR fusionados (30 d)
345

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de getsentry/toolkit

Todos los issues de getsentry/toolkit

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.