The --help-json output is the documented contract for agent integration (AGENTS.md), but extractMailCommands in internal/cli/help.go covers only a subset of what MailCmd actually defines.
Missing entirely:
mail downloadmail attachmentsmail watchmail replymail forwardmail thread
An agent reading the schema cannot discover these commands or their flags, so they are effectively invisible to the integration path the project is built around.
Surfaced during the 0.2.6 security review. Not a vulnerability, which is why it was not fixed in that round — but it undercuts the --help-json guarantee.
Worth considering while fixing: the schema is hand-maintained in parallel with the Kong structs in cli.go, which is why it drifts. #16 added three flags without updating it, and #21 added --force to mail download, which has no entry at all. Generating the schema from the Kong AST — or a test asserting every cmd:"" field has a schema entry — would stop the drift at the source rather than requiring reviewers to catch it each time.
The
--help-jsonoutput is the documented contract for agent integration (AGENTS.md), butextractMailCommandsininternal/cli/help.gocovers only a subset of whatMailCmdactually defines.Missing entirely:
mail downloadmail attachmentsmail watchmail replymail forwardmail threadAn agent reading the schema cannot discover these commands or their flags, so they are effectively invisible to the integration path the project is built around.
Surfaced during the 0.2.6 security review. Not a vulnerability, which is why it was not fixed in that round — but it undercuts the
--help-jsonguarantee.Worth considering while fixing: the schema is hand-maintained in parallel with the Kong structs in
cli.go, which is why it drifts. #16 added three flags without updating it, and #21 added--forcetomail download, which has no entry at all. Generating the schema from the Kong AST — or a test asserting everycmd:""field has a schema entry — would stop the drift at the source rather than requiring reviewers to catch it each time.