Description of feature
docket knows the full shape of every task type it registers, and there is currently no way to get at that knowledge except by reading the generated Markdown.
buildParams in generate/docs.go already reflects over every entry in tasks.RegisteredTasks and reads the yaml, required, default, options, description, and sensitive tags off each field, normalising Go types into string / bool / int / list / dict along the way. It also picks up Doc(), Examples(), Requirements(), ExportSupport(), and Deprecation(). The problem is that the only thing it can do with the result is render a table into docs/tasks/<task>.md, so anything that wants the catalog has to scrape those pages or vendor the reflection.
The ask is a machine-readable form of the same data: every registered task key, its synopsis, requirements, deprecation, export-support status, and per-field type, required-ness, default, choices, description, and sensitivity. Whether that ships as a docket schema --json command or as a second output target on the existing generator is open - a command is more useful to something that already has the binary on hand, a generator target is cheaper and keeps the reflection in one place.
The 28 *_property tasks are worth deciding on either way. Their real schema is the map[string]PropertyKeys literal each one declares, which names every supported property, its report key per scope, and whether the value is a secret. validateProperty already produces a supported-property list from it for error messages. Emitting that map rather than a free-form property string is most of the value of the catalog for those tasks.
The immediate consumer is #407: any HCL schema needs the task catalog in a form something other than the docs generator can read. Editor tooling and recipe linters have the same problem today.
Description of feature
docket knows the full shape of every task type it registers, and there is currently no way to get at that knowledge except by reading the generated Markdown.
buildParamsingenerate/docs.goalready reflects over every entry intasks.RegisteredTasksand reads theyaml,required,default,options,description, andsensitivetags off each field, normalising Go types intostring/bool/int/list/dictalong the way. It also picks upDoc(),Examples(),Requirements(),ExportSupport(), andDeprecation(). The problem is that the only thing it can do with the result is render a table intodocs/tasks/<task>.md, so anything that wants the catalog has to scrape those pages or vendor the reflection.The ask is a machine-readable form of the same data: every registered task key, its synopsis, requirements, deprecation, export-support status, and per-field type, required-ness, default, choices, description, and sensitivity. Whether that ships as a
docket schema --jsoncommand or as a second output target on the existing generator is open - a command is more useful to something that already has the binary on hand, a generator target is cheaper and keeps the reflection in one place.The 28
*_propertytasks are worth deciding on either way. Their real schema is themap[string]PropertyKeysliteral each one declares, which names every supported property, its report key per scope, and whether the value is a secret.validatePropertyalready produces a supported-property list from it for error messages. Emitting that map rather than a free-formpropertystring is most of the value of the catalog for those tasks.The immediate consumer is #407: any HCL schema needs the task catalog in a form something other than the docs generator can read. Editor tooling and recipe linters have the same problem today.