logstream

README

Log Stream

Bounded, color-coded log view that tails like tail -f.

Install

glyph add log-stream

This copies log-stream.go (and its test file) into your repo at the path your glyph.json aliases declare. After install, the file is yours: edit it, refactor it, rename it. There is no log-stream library to keep in sync.

Hello, world

package main

import (
	"fmt"

	logstream "github.com/truffle-dev/glyph/components/log-stream"
	"github.com/truffle-dev/glyph/components/theme"
)

func main() {
	s := logstream.New(theme.Default).
		WithSize(96, 16).
		WithMinLevel(logstream.LevelInfo)
	s = s.Append(logstream.Entry{
		Level:   logstream.LevelWarn,
		Source:  "auth",
		Message: "deprecated token format",
	})
	fmt.Println(s.View())
}

API surface

Package: logstream

Types

• Level
• Entry
• Stream

Functions and methods

• String
• New
• WithCapacity
• WithSize
• WithMinLevel
• WithTimestamps
• WithTimeFormat
• Append
• Clear
• Entries
• Offset
• Init
• Update
• View

Dependencies

• glyph component theme (installed automatically)
• github.com/charmbracelet/bubbletea@v1.3.10
• github.com/charmbracelet/lipgloss@v1.1.0
• github.com/muesli/reflow@v0.3.0

Notes

Call Append(Entry{Time, Level, Source, Message}) on every new log line. The view auto-tails unless the user has scrolled up. WithCapacity caps the ring; WithMinLevel hides entries below the threshold (the buffer is unchanged).

See also

• examples/showcase — single-binary TUI composing the seven main surfaces
• components/log-stream/story — runnable story binary (go run -tags glyph_story ./components/log-stream/story/)
• registry manifest — the JSON contract glyph add reads

License

MIT, same as the rest of glyph.

Documentation

Overview

Package logstream renders a bounded, scrollable log view. Entries are color-coded by level. The view sticks to the tail like `tail -f` unless the user scrolls up; new entries appended while scrolled up do not jump the viewport.

Index

• type Entry
• type Level
  • func (l Level) String() string
• type Stream
  • func New(t theme.Theme) Stream
  • func (s Stream) Append(e Entry) Stream
  • func (s Stream) Clear() Stream
  • func (s Stream) Entries() []Entry
  • func (s Stream) Init() tea.Cmd
  • func (s Stream) Offset() int
  • func (s Stream) TotalLines() int
  • func (s Stream) Update(msg tea.Msg) (Stream, tea.Cmd)
  • func (s Stream) View() string
  • func (s Stream) WithCapacity(n int) Stream
  • func (s Stream) WithMinLevel(l Level) Stream
  • func (s Stream) WithSize(w, h int) Stream
  • func (s Stream) WithTimeFormat(f string) Stream
  • func (s Stream) WithTimestamps(show bool) Stream

Types

type Entry

type Entry struct {
	Time    time.Time
	Level   Level
	Source  string // optional component / module name
	Message string
}

Entry is one log line.

type Level

type Level int

Level is the severity of a log entry. Higher values are more severe.

const (
	LevelDebug Level = iota
	LevelInfo
	LevelWarn
	LevelError
)

func (Level) String

func (l Level) String() string

String returns the four-char label rendered in the level column.

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream is a Bubble Tea model that renders a windowed view of entries.

func New

func New(t theme.Theme) Stream

New constructs a Stream with capacity 1000, INFO minimum level, and timestamps enabled.

func (Stream) Append

func (s Stream) Append(e Entry) Stream

Append adds an entry. If the buffer exceeds capacity, the oldest drops. If the viewport is at the tail (offset == 0), it stays at the tail. Otherwise the offset is preserved so the user sees the same content.

func (Stream) Clear

func (s Stream) Clear() Stream

Clear empties the buffer and resets the offset to the tail.

func (Stream) Entries

func (s Stream) Entries() []Entry

Entries returns the current buffer (copy).

func (Stream) Init

func (s Stream) Init() tea.Cmd

Init implements tea.Model.

func (Stream) Offset

func (s Stream) Offset() int

Offset returns the current scroll offset, in lines from the tail.

func (Stream) TotalLines

func (s Stream) TotalLines() int

TotalLines is the count of post-wrap lines currently in the buffer after level filtering.

func (Stream) Update

func (s Stream) Update(msg tea.Msg) (Stream, tea.Cmd)

Update handles scroll keys. Up/Down moves one line, PgUp/PgDn moves a window, Home jumps to the top of buffered history, End returns to tail.

func (Stream) View

func (s Stream) View() string

View renders the visible window. Lines below the tail are blank-padded to preserve the configured height.

func (Stream) WithCapacity

func (s Stream) WithCapacity(n int) Stream

WithCapacity caps the ring buffer. When exceeded, oldest entries drop. Minimum capacity is 1.

func (Stream) WithMinLevel

func (s Stream) WithMinLevel(l Level) Stream

WithMinLevel drops entries below the given severity from the view. The underlying ring is unchanged.

func (Stream) WithSize

func (s Stream) WithSize(w, h int) Stream

WithSize sets the rendered width and visible-row height.

func (Stream) WithTimeFormat

func (s Stream) WithTimeFormat(f string) Stream

WithTimeFormat overrides the timestamp format. Default is "15:04:05".

func (Stream) WithTimestamps

func (s Stream) WithTimestamps(show bool) Stream

WithTimestamps toggles the leading timestamp column.