fix(cligen): document response timestamp fields as their actual --json output type - #148
Merged
Conversation
…n output type Generated response-field help was sourced only from the OpenAPI spec, which describes the wire type (a plain integer epoch). Several response fields decode into go-flashduty's Timestamp/TimestampMilli types, which implement a custom MarshalJSON that renders a quoted RFC3339 string in the process's local timezone instead of the wire integer (falling back to the bare integer 0 when unset). --help was therefore describing a shape the CLI's --json never actually prints. cligen now reflects the Go type the SDK method actually decodes each response field into (not just the request type, as before) and threads it alongside the schema walk that builds response help. A field whose Go type is Timestamp/TimestampMilli has its documented type corrected to string and an accurate rendering note appended, while a same-named field that is genuinely a plain int64 on both the wire and the SDK struct (e.g. AlertRuleAudit's created_at) is left untouched — the fix is keyed off the actual decoded Go type, not the field name. Request-side field help is unaffected: the wire type is also what a --data / flag value must supply there, so no correction is needed on that side. Regenerated all zz_generated_*.go command files and re-synced the skills/flashduty GENERATED fences that embed the affected response shapes.
This was referenced Aug 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
cligen's generated response-field help documents each field's OpenAPI wiretype — correct for the wire format, but not for what the CLI's
--jsonactually prints. Several response fields decode into go-flashduty's
Timestamp/TimestampMillitypes, which implement a customMarshalJSONthat renders a quoted RFC3339 string in the process's local timezone
(falling back to the bare integer
0when unset) instead of the wireinteger epoch. The generated help was calling these fields
(integer)withdescriptions like "Timestamp of the operation in Unix epoch milliseconds",
which is true of the wire format but false of what a user actually gets from
--json.Example,
fduty audit search --helpbefore this change:Actual
--jsonoutput for that field is a quoted local-time RFC3339 string,not an integer.
Fix
cligennow reflects the Go type the SDK method actually decodes eachresponse field into — not just the request type, as it already did — and
threads that type alongside the schema walk that builds response help
(
internal/cmd/cligen/main.go). A field whose decoded Go type isTimestamp/TimestampMilligets its documented type corrected tostringand an accurate note about the actual rendering appended; the match is keyed
off the real decoded Go type of that specific field on that specific
response struct, not the field's name, so a same-named field that is
genuinely a plain
int64on the wire (e.g.AlertRuleAudit.created_at,returned by
rule-audits) is left documented as(integer), unchanged.Request-side field help is untouched: the wire type is also what a
--datavalue or flag must supply there, so there's nothing to correct on that side.
After the fix:
Scope of the regenerated output
Running
go run ./internal/cmd/cligenwith the fixed generator changed:internal/cli/zz_generated_*.gocommand files that expose an affectedresponse field (36 files) — this is regenerated output, not a hand edit.
Service.Methodentries in theresponseHelpBySDKMethodmap(
zz_generated_response_help.go), which curated commands (likeaudit search) also read from.skills/flashduty/reference/*.mdcards, re-synced viamake gen-cardssince their
GENERATED:*fences embed the same response-field help text(
skilldoc checkwent from 22 stale fences tocards OKafter the sync).No hand-maintained file was edited to fix a specific field description;
every changed file is generator output.
Also verified, not changed in this PR
While tracing this, found that
internal/cli/zz_generated_audit_logs.go'sgenAuditLogsSearchCmdis generated and has a registration call site(
genAddLeaf(gAudit, genAuditLogsSearchCmd())), but its command is alwayssilently dropped at startup: the curated
audit.go'snewAuditSearchCmd()registers a
searchcommand under the sameauditgroup first, andgenAddLeafskips adding a leaf when a same-named command already exists.So the generated twin is built at every run but never reachable by a user —
this is the documented curated-wins behavior of
genAddLeaf/genGroup, notunique to audit. Leaving this as-is; out of scope here.
Testing
go build ./...go vet ./...go test ./...— green before and after this change (no pre-existingfailures either way)
make fmt— no additional changesgo run ./internal/cmd/skilldoc check—cards OKaftermake gen-cardsfduty audit search --helpto confirm the renderedoutput shown above