Documentation
¶
Overview ¶
Package render formats Heimdall REST + CometBFT responses for CLI output. It supports three modes — key/value (default), table (list-like payloads), and JSON (with the normalizations described in HEIMDALLCAST_REQUIREMENTS.md §4.2).
Callers pass in an already-decoded map/slice/json.RawMessage; the renderers do not talk to the network.
Index ¶
- Constants
- Variables
- func AnnotateUnixSeconds(raw string) string
- func EnableWatch(cmd *cobra.Command)
- func EnableWatchTree(cmd *cobra.Command)
- func RenderJSON(w io.Writer, input any, opts Options) error
- func RenderKV(w io.Writer, input any, opts Options) error
- func RenderTable(w io.Writer, records []map[string]any, opts Options) error
- func Watch(ctx context.Context, out, errOut io.Writer, interval time.Duration, fn WatchFn) error
- func WriteHint(w io.Writer, h Hint, opts Options) error
- func WriteHints(w io.Writer, hints []Hint, opts Options) error
- type Hint
- type Options
- type WatchFn
Constants ¶
const WatchFlag = "watch"
WatchFlag is the name of the per-command duration flag added by EnableWatch. Exported so tests can set it directly via cmd.Flags().
Variables ¶
var ( HintIsOldRenamed = Hint{ Key: "is-old-renamed", Body: "note: upstream `is_old` renamed to `is_current` in this tool (upstream naming was misleading)", } HintL1NotConfigured = Hint{ Key: "l1-not-configured", Body: "hint: this node does not have `eth_rpc_url` configured; L1 replay checks will fail until it is set", } HintBufferEmpty = Hint{ Key: "buffer-empty", Body: "hint: the buffer is empty (no checkpoint in flight) - this is not an error", } HintMilestoneOutOfRange = Hint{ Key: "milestone-range", Body: "hint: milestone numbers are 1-indexed and bounded by `milestone count`", } HintPaginationLimit = Hint{ Key: "pagination-limit", Body: "hint: list endpoints require `pagination.limit` (try --limit)", } )
Hints the command packages can reference by name. Centralised so the wording stays consistent across subcommands.
Functions ¶
func AnnotateUnixSeconds ¶
AnnotateUnixSeconds formats a unix-second timestamp like cast does: the integer, a human UTC string, and a coarse "ago" relative time. Returns the input unchanged if it cannot be parsed as a positive integer.
1776640801 (2026-04-19 23:20:01 UTC, 2h 4m ago)
func EnableWatch ¶
EnableWatch decorates cmd with a `--watch DURATION` flag and wraps cmd.RunE so the command repeats its output at the requested interval until the context is cancelled. The first iteration always runs; if --watch is zero (unset), the wrapper is a no-op and the original RunE is invoked verbatim.
Between iterations the watcher clears the terminal with the standard VT100 sequence, matching `watch(1)` behaviour. When the command is not attached to a TTY the separator is a plain divider line, so piping `polycli heimdall <cmd> --watch 5s | cat` stays readable.
The wrapper captures the original RunE once and is idempotent: a second call on the same command is a no-op. Usage strings document the flag so it surfaces in `--help` output.
func EnableWatchTree ¶
EnableWatchTree recursively applies EnableWatch to cmd and every descendant that has a RunE. Parents-only (pure umbrella) commands are skipped because they do not print anything loopable.
func RenderJSON ¶
RenderJSON emits input as pretty-printed JSON with bytes normalization applied (unless opts.Raw). input is expected to be the result of json.Unmarshal into any / map / slice.
func RenderKV ¶
RenderKV emits a map[string]any as right-aligned key/value pairs, one per line (matches requirements §4.1). Nested objects are rendered inline as JSON on the value line.
func RenderTable ¶
RenderTable emits a list of records as a simple column-aligned table. The column set is the union of keys in the records in iteration order of the first record.
func Watch ¶
Watch polls fn at interval, printing the output to out whenever it changes. Always exits cleanly on ctx cancellation; guarantees timer cleanup per CLAUDE.md.
The first snapshot is always printed. Subsequent snapshots are printed only when they differ from the previous output.
Types ¶
type Hint ¶
type Hint struct {
// Key identifies the hint for logging / tests. Not rendered.
Key string
// Body is the hint text. Rendered in gray when color is enabled.
Body string
}
Hint is a short explanatory line rendered in gray after an otherwise confusing response. Source catalogues the misleading cases from HEIMDALLCAST_REQUIREMENTS.md §4.5.
func DetectHints ¶
DetectHints scans a rendered KV map for the well-known footguns and returns the hints that apply. Does not mutate the input.
type Options ¶
type Options struct {
// JSON forces JSON output.
JSON bool
// Raw suppresses the bytes->0x-hex normalization for JSON output.
Raw bool
// Fields restricts output to these JSON paths (repeatable --field).
Fields []string
// Color mode: auto|always|never.
Color string
// IsTTY is set by the caller when stdout is a terminal. Combined
// with Color=auto this decides whether to emit ANSI colour codes.
IsTTY bool
}
Options controls output formatting.
func (Options) ColorEnabled ¶
ColorEnabled returns whether colour output should be emitted given the current options.
Source Files