Documentation
¶
Overview ¶
Package pulse renders a wake build to a terminal as the "Pulse" TUI: a pre-painted skeleton of one row per planned step that updates each row in place as steps progress, plus a pinned progress strip and throughput sparkline beneath. Written without third-party styling libraries.
Index ¶
- Constants
- Variables
- type Artifact
- type Colour
- type Profile
- type Reporter
- func (r *Reporter) Artifact(a report.Artifact)
- func (r *Reporter) BuildCanceled(_ time.Duration)
- func (r *Reporter) BuildEnd(dur time.Duration, ok bool)
- func (r *Reporter) BuildStart(verb, target string, total int)
- func (r *Reporter) Debug(d report.DebugLine)
- func (r *Reporter) Level() report.Verbosity
- func (r *Reporter) ParallelStepEnd(id StepID, status report.Status, dur time.Duration)
- func (r *Reporter) ParallelStepFailed(id StepID, f report.Failure)
- func (r *Reporter) ParallelStepInfo(id StepID, msg string)
- func (r *Reporter) ParallelStepStart(name, label string) StepID
- func (r *Reporter) StepCommand(id StepID, cmd string)
- func (r *Reporter) StepEnd(id StepID, status report.Status, dur time.Duration)
- func (r *Reporter) StepFailed(id StepID, f report.Failure)
- func (r *Reporter) StepInfo(id StepID, msg string)
- func (r *Reporter) StepOutput(id StepID, line string)
- func (r *Reporter) StepStart(name, label string) StepID
- type StepID
Constants ¶
const ( GlyphOK = "✓" GlyphFail = "✗" GlyphCached = "⊙" GlyphSkipped = "·" GlyphArrow = "›" GlyphBullet = "•" GlyphActive = "◆" GlyphQueued = "◇" GlyphCrit = "◀" GlyphRule = "━" // header signature rule // Progress bar: thick horizontal lines, with a transition glyph between // filled and empty so the bar reads as one continuous stroke rather than // two abutting blocks. The leading "╾" gives the head a soft point. BarFilled = "━" BarHead = "╾" BarEmpty = "─" // Sparkline scale: 8 evenly-stepped block heights. SparkRunes = "▁▂▃▄▅▆▇█" // Sub-cell horizontal block fill (eighths): each glyph is one cell wide // but increases left-anchored fill in 1/8 increments. Used by the // fine-grained progress bar so the head advances smoothly even when the // overall ratio changes by tiny amounts. HEighths = " ▏▎▍▌▋▊▉█" )
Block-element glyphs we use for visuals. Single-cell, monospace-safe, supported by every font shipped with a terminal emulator. We deliberately avoid emoji (variable width, inconsistent fonts) and the heavier box-drawing patterns; the wake TUI's identity is "calm Unicode, not maximalist".
Variables ¶
var ( // Accent — electric blue, used for the verb, the spinner, and the // progress-bar fill. The TUI's only deliberately attention-grabbing colour. Accent = Colour{True: "7d9eff", X256: 111, Ansi: 94} // Success — muted green, used for ✓ glyph and the success summary. Success = Colour{True: "7ec682", X256: 114, Ansi: 92} // Failure — desaturated red, used for ✗ and panel borders. Bold-adjacent // without being alarming; we let typography (bold) carry the urgency. Failure = Colour{True: "e06c75", X256: 167, Ansi: 91} // Warning — straw yellow, used for partial-success notes. Warning = Colour{True: "e5c07b", X256: 179, Ansi: 93} // Cached — soft cyan, used for cache hits to differentiate them from // "ran but quick" successes. Cached = Colour{True: "8ec5d8", X256: 109, Ansi: 96} // Dim — neutral grey for chrome (counters, separators, "→"). Dim = Colour{True: "6e7785", X256: 244, Ansi: 90} // Subtle — slightly brighter than Dim; for the second-most-important text // in a row (a "1.2s" beside a step name). Subtle = Colour{True: "9aa5b8", X256: 248, Ansi: 37} )
Palette — the wake brand. Picked for legibility on both dark and light terminals at all three tiers. The Accent is the only brand-saturated colour; everything else stays in muted territory so the UI reads as calm.
Functions ¶
This section is empty.
Types ¶
type Artifact ¶
Artifact is re-exported from the report package so call sites that reference *pulse.Reporter need only one import.
type Colour ¶
type Colour struct {
True string // 24-bit hex without leading '#', e.g. "7d9eff"
X256 uint8 // 256-colour palette index
Ansi uint8 // 30–37 / 90–97 base
}
Colour describes one logical UI colour at three render tiers. The reporter picks the highest tier the active profile supports. Callers should not build Colour values directly — use the predefined palette members below.
type Profile ¶
type Profile int
Profile is what the terminal can render. We fall through TrueColor → 256 → 16-colour ANSI → no colour at all, picking the richest profile the terminal advertises. Terminals routinely lie about this (tmux historically claims less than it can render; some CI systems claim more) but TERM/COLORTERM/ NO_COLOR are the conventions, so we follow them.
func DetectProfile ¶
DetectProfile returns the colour profile the receiving terminal advertises. f is the output stream; if it isn't a TTY the profile is forced to None. NO_COLOR (any value) forces None regardless.
type Reporter ¶
type Reporter struct {
// contains filtered or unexported fields
}
Reporter renders a wake build as the "Pulse" TUI.
In Normal verbosity it uses **skeleton mode**: at BuildStart it pre-paints one row per planned step (all in "pending" state), and each StepStart / StepEnd updates that row in place. The terminal never scrolls during the build — the skeleton stays anchored, pending rows fill in as active rows fill in as completed rows, and the end-of-build summary unfolds beneath.
In Verbose / Debug verbosities it falls back to **scrollback mode** (the original Buck2-Superconsole shape): completed step lines promote into the scrollback above a pinned region that holds only the in-flight step(s) and the progress strip. Interleaved StepCommand / StepOutput / Debug lines need the scrolling history to make sense.
Pulse implements report.Reporter. The serial path matches the existing termui contract exactly — one in-flight step at a time. The parallel path is exposed through the additional methods on this concrete type so callers that drive multiple workers can hand each its own step ID. Mixing the two in the same build is supported.
func New ¶
New builds a Reporter writing to w at the given verbosity. It auto-detects whether w is a terminal and whether colour is permitted (TERM, COLORTERM, NO_COLOR), and degrades to plain one-line-per-step output if not.
func (*Reporter) Artifact ¶
Artifact registers one build output for display in the end-of-build summary. Satisfies the report.Reporter interface. If a.Size is 0, the path is stat()ed to fill in the size; a non-zero size short-circuits the stat (useful for tests and demos). Safe to call concurrently with step lifecycle methods.
func (*Reporter) BuildCanceled ¶ added in v3.1.0
BuildCanceled removes the live build without turning expected generation cancellation into a failed-build summary.
func (*Reporter) BuildEnd ¶
BuildEnd closes the build and prints the summary.
In scrollback mode the pinned region is erased so the summary can take its place. In skeleton mode the settled skeleton stays exactly where it was drawn (so the user keeps seeing the per-step ledger), and the summary unfolds below it.
func (*Reporter) BuildStart ¶
BuildStart begins the build. Prints the header to scrollback, decides whether to use skeleton mode, pre-paints the skeleton if so, and starts the redraw ticker.
func (*Reporter) Debug ¶
Debug renders one diagnostic line. We rely on the existing termui-style "BADGE subject → arrow k=v" layout; it reads well above the pinned region.
func (*Reporter) ParallelStepEnd ¶
func (*Reporter) ParallelStepFailed ¶
func (*Reporter) ParallelStepInfo ¶
func (*Reporter) ParallelStepStart ¶
ParallelStepStart, ParallelStepInfo, ParallelStepEnd, ParallelStepFailed were earlier concrete-type aliases of the now-id-returning interface methods; with StepStart returning a StepID directly, callers use the standard interface for both serial and parallel flows.
func (*Reporter) StepCommand ¶
StepCommand prints the command above the pinned region (Verbose only).
func (*Reporter) StepFailed ¶
StepFailed closes the named step with a failure. Passing `0` for the duration lets finishLocked derive it from the step's own startedAt; the previous `time.Since(r.buildStart)` form measured the wrong interval — a step that started 200 ms in and ran for 50 ms would otherwise report a duration of 250 ms in the summary.
func (*Reporter) StepOutput ¶
StepOutput prints one captured output line above the pinned region (Verbose).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ansi is a tiny pure-stdlib set of ANSI helpers, just enough to render the wake build TUI without pulling in a styling library.
|
Package ansi is a tiny pure-stdlib set of ANSI helpers, just enough to render the wake build TUI without pulling in a styling library. |