Skip to content

fix(cligen): document response timestamp fields as their actual --json output type - #148

Merged
ysyneu merged 1 commit into
mainfrom
feat/cligen-timestamp-desc
Aug 14, 2026
Merged

fix(cligen): document response timestamp fields as their actual --json output type#148
ysyneu merged 1 commit into
mainfrom
feat/cligen-timestamp-desc

Conversation

@ysyneu

@ysyneu ysyneu commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Problem

cligen's generated response-field help documents each field's OpenAPI wire
type — correct for the wire format, but not for what the CLI's --json
actually prints. 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
(falling back to the bare integer 0 when unset) instead of the wire
integer epoch. The generated help was calling these fields (integer) with
descriptions 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 --help before this change:

- created_at (integer) (required) — Timestamp of the operation in Unix epoch milliseconds.

Actual --json output for that field is a quoted local-time RFC3339 string,
not an integer.

Fix

cligen now reflects the Go type the SDK method actually decodes each
response 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 is
Timestamp/TimestampMilli gets its documented type corrected to string
and 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 int64 on 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 --data
value or flag must supply there, so there's nothing to correct on that side.

After the fix:

- created_at (string) (required) — Timestamp of the operation in Unix epoch milliseconds. CLI `--json` renders this as an RFC3339 string in the process's local timezone (NOT UTC, and NOT the wire integer); an unset value stays the bare integer 0.

Scope of the regenerated output

Running go run ./internal/cmd/cligen with the fixed generator changed:

  • All internal/cli/zz_generated_*.go command files that expose an affected
    response field (36 files) — this is regenerated output, not a hand edit.
  • 130 distinct Service.Method entries in the responseHelpBySDKMethod map
    (zz_generated_response_help.go), which curated commands (like
    audit search) also read from.
  • 22 skills/flashduty/reference/*.md cards, re-synced via make gen-cards
    since their GENERATED:* fences embed the same response-field help text
    (skilldoc check went from 22 stale fences to cards OK after 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's
genAuditLogsSearchCmd is generated and has a registration call site
(genAddLeaf(gAudit, genAuditLogsSearchCmd())), but its command is always
silently dropped at startup: the curated audit.go's newAuditSearchCmd()
registers a search command under the same audit group first, and
genAddLeaf skips 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, not
unique 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-existing
    failures either way)
  • make fmt — no additional changes
  • go run ./internal/cmd/skilldoc checkcards OK after make gen-cards
  • Built the CLI and ran fduty audit search --help to confirm the rendered
    output shown above

…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.
@ysyneu
ysyneu merged commit 1aa83c1 into main Aug 14, 2026
12 checks passed
@ysyneu
ysyneu deleted the feat/cligen-timestamp-desc branch August 14, 2026 05:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant