render

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
  • func DetectHints(m map[string]any) []Hint
• type Options
  • func (o Options) ColorEnabled() bool
• 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

func AnnotateUnixSeconds(raw string) string

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

func EnableWatch(cmd *cobra.Command)

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

func EnableWatchTree(cmd *cobra.Command)

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

func RenderJSON(w io.Writer, input any, opts Options) error

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

func RenderKV(w io.Writer, input any, opts Options) error

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

func RenderTable(w io.Writer, records []map[string]any, opts Options) error

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

func Watch(ctx context.Context, out, errOut io.Writer, interval time.Duration, fn WatchFn) error

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.

func WriteHint

func WriteHint(w io.Writer, h Hint, opts Options) error

WriteHint emits a single hint line to w. When colour is enabled the line is wrapped in the ANSI dim sequence.

func WriteHints

func WriteHints(w io.Writer, hints []Hint, opts Options) error

WriteHints emits multiple hints preserving order; a nil slice is a no-op.

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

func DetectHints(m map[string]any) []Hint

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

func (o Options) ColorEnabled() bool

ColorEnabled returns whether colour output should be emitted given the current options.

type WatchFn

type WatchFn func(ctx context.Context) (string, error)

WatchFn is the data source a watcher polls. It should return an already-rendered output string for the current snapshot. Any error is logged to the watcher's Err writer but does not terminate the loop unless the context has been cancelled.