repl

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 15, 2026 License: MIT Imports: 26 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

View Source
var BuiltinThemes = map[string]Theme{
	"default": {
		Name:   "Default",
		Styles: DefaultStyles(),
	},
	"dark": {
		Name: "Dark",
		Styles: Styles{
			Title: lipgloss.NewStyle().
				Bold(true).
				Foreground(lipgloss.Color("15")).
				Background(lipgloss.Color("236")).
				Padding(0, 1),

			Prompt: lipgloss.NewStyle().
				Foreground(lipgloss.Color("11")).
				Bold(true),

			Result: lipgloss.NewStyle().
				Foreground(lipgloss.Color("14")),

			Error: lipgloss.NewStyle().
				Foreground(lipgloss.Color("9")).
				Bold(true),

			Info: lipgloss.NewStyle().
				Foreground(lipgloss.Color("3")).
				Italic(true),

			HelpText: lipgloss.NewStyle().
				Foreground(lipgloss.Color("243")).
				Italic(true),
			CompletionPopup: lipgloss.NewStyle().
				Border(lipgloss.RoundedBorder()).
				BorderForeground(lipgloss.Color("241")).
				Padding(0, 1),
			CompletionItem: lipgloss.NewStyle().
				Foreground(lipgloss.Color("252")),
			CompletionSelected: lipgloss.NewStyle().
				Foreground(lipgloss.Color("11")).
				Bold(true),
		},
	},
	"light": {
		Name: "Light",
		Styles: Styles{
			Title: lipgloss.NewStyle().
				Bold(true).
				Foreground(lipgloss.Color("0")).
				Background(lipgloss.Color("252")).
				Padding(0, 1),

			Prompt: lipgloss.NewStyle().
				Foreground(lipgloss.Color("4")).
				Bold(true),

			Result: lipgloss.NewStyle().
				Foreground(lipgloss.Color("6")),

			Error: lipgloss.NewStyle().
				Foreground(lipgloss.Color("1")).
				Bold(true),

			Info: lipgloss.NewStyle().
				Foreground(lipgloss.Color("130")).
				Italic(true),

			HelpText: lipgloss.NewStyle().
				Foreground(lipgloss.Color("8")).
				Italic(true),
			CompletionPopup: lipgloss.NewStyle().
				Border(lipgloss.RoundedBorder()).
				BorderForeground(lipgloss.Color("246")).
				Padding(0, 1),
			CompletionItem: lipgloss.NewStyle().
				Foreground(lipgloss.Color("238")),
			CompletionSelected: lipgloss.NewStyle().
				Foreground(lipgloss.Color("4")).
				Bold(true),
		},
	},
}

BuiltinThemes provides predefined themes

Functions

func RegisterReplToTimelineTransformer added in v0.0.29

func RegisterReplToTimelineTransformer(bus *eventbus.Bus)

RegisterReplToTimelineTransformer subscribes to repl.events and publishes timeline lifecycle messages to ui.entities.

Types

type AutocompleteConfig added in v0.1.0

type AutocompleteConfig struct {
	// Enabled toggles REPL autocomplete integration.
	Enabled bool
	// Debounce is the delay after input edits before a completion request is sent.
	Debounce time.Duration
	// RequestTimeout bounds a single completion request.
	RequestTimeout time.Duration
	// TriggerKeys are optional explicit shortcut keys (for example "tab").
	TriggerKeys []string
	// AcceptKeys apply the selected completion while the popup is visible.
	AcceptKeys []string
	// FocusToggleKey switches between input and timeline focus.
	FocusToggleKey string
	// MaxSuggestions limits the number of rendered popup items.
	MaxSuggestions int
	// OverlayMaxWidth limits popup width in terminal cells.
	OverlayMaxWidth int
	// OverlayMaxHeight limits popup height in terminal rows.
	OverlayMaxHeight int
	// OverlayMinWidth keeps the popup readable when suggestions are short.
	OverlayMinWidth int
	// OverlayMargin leaves a gap between input anchor and popup.
	OverlayMargin int
	// OverlayPageSize controls page up/down steps; 0 means visible rows.
	OverlayPageSize int
	// OverlayOffsetX shifts popup horizontally before clamping to terminal bounds.
	OverlayOffsetX int
	// OverlayOffsetY shifts popup vertically before clamping to terminal bounds.
	OverlayOffsetY int
	// OverlayNoBorder renders completion popup without border chrome.
	OverlayNoBorder bool
	// OverlayPlacement controls vertical popup placement strategy.
	// Supported values: auto, above, below, bottom.
	OverlayPlacement CompletionOverlayPlacement
	// OverlayHorizontalGrow controls horizontal growth direction from anchor.
	// Supported values: right, left.
	OverlayHorizontalGrow CompletionOverlayHorizontalGrow
}

AutocompleteConfig controls autocomplete request and key-routing behavior.

func DefaultAutocompleteConfig added in v0.1.0

func DefaultAutocompleteConfig() AutocompleteConfig

DefaultAutocompleteConfig returns default autocomplete settings.

type Bridge added in v0.0.29

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

Bridge maps Evaluator events to timeline lifecycle messages via the Shell wrapper to ensure viewport refresh semantics are consistent.

func NewBridge added in v0.0.29

func NewBridge(sh *timeline.Shell) *Bridge

func (*Bridge) Complete added in v0.0.29

func (b *Bridge) Complete(id timeline.EntityID, result map[string]any)

func (*Bridge) Emit added in v0.0.29

func (b *Bridge) Emit(turnID, local, kind string, props map[string]any) timeline.EntityID

func (*Bridge) NewTurnID added in v0.0.29

func (b *Bridge) NewTurnID(seq int) string

func (*Bridge) Patch added in v0.0.29

func (b *Bridge) Patch(id timeline.EntityID, patch map[string]any)

type ClearHistoryMsg

type ClearHistoryMsg struct{}

ClearHistoryMsg is sent when history should be cleared

type CommandPaletteConfig added in v0.1.0

type CommandPaletteConfig struct {
	// Enabled toggles command palette integration.
	Enabled bool
	// OpenKeys open the palette from input mode.
	OpenKeys []string
	// CloseKeys close the palette while it is open.
	CloseKeys []string
	// SlashOpenEnabled enables slash-triggered palette open behavior.
	SlashOpenEnabled bool
	// SlashPolicy decides when slash should open the palette.
	// Supported values: empty-input, column-zero, provider.
	SlashPolicy CommandPaletteSlashPolicy
	// MaxVisibleItems limits visible rows rendered by the palette model.
	MaxVisibleItems int
	// OverlayPlacement controls where the command palette panel is anchored.
	// Supported values: center, top, bottom, left, right.
	OverlayPlacement CommandPaletteOverlayPlacement
	// OverlayMargin keeps space between the panel and viewport edge for docked placements.
	OverlayMargin int
	// OverlayOffsetX applies a horizontal shift before final viewport clamp.
	OverlayOffsetX int
	// OverlayOffsetY applies a vertical shift before final viewport clamp.
	OverlayOffsetY int
}

CommandPaletteConfig controls REPL command palette behavior.

func DefaultCommandPaletteConfig added in v0.1.0

func DefaultCommandPaletteConfig() CommandPaletteConfig

DefaultCommandPaletteConfig returns default command palette settings.

type CommandPaletteOverlayPlacement added in v0.1.0

type CommandPaletteOverlayPlacement string
const (
	CommandPaletteOverlayPlacementCenter CommandPaletteOverlayPlacement = "center"
	CommandPaletteOverlayPlacementTop    CommandPaletteOverlayPlacement = "top"
	CommandPaletteOverlayPlacementBottom CommandPaletteOverlayPlacement = "bottom"
	CommandPaletteOverlayPlacementLeft   CommandPaletteOverlayPlacement = "left"
	CommandPaletteOverlayPlacementRight  CommandPaletteOverlayPlacement = "right"
)

type CommandPaletteSlashOpenProvider added in v0.1.0

type CommandPaletteSlashOpenProvider interface {
	ShouldOpenCommandPaletteOnSlash(ctx context.Context, req CommandPaletteSlashRequest) (bool, error)
}

CommandPaletteSlashOpenProvider allows evaluators to decide slash-open behavior.

type CommandPaletteSlashPolicy added in v0.1.0

type CommandPaletteSlashPolicy string
const (
	CommandPaletteSlashPolicyEmptyInput CommandPaletteSlashPolicy = "empty-input"
	CommandPaletteSlashPolicyColumnZero CommandPaletteSlashPolicy = "column-zero"
	CommandPaletteSlashPolicyProvider   CommandPaletteSlashPolicy = "provider"
)

type CommandPaletteSlashRequest added in v0.1.0

type CommandPaletteSlashRequest struct {
	Input      string
	CursorByte int
}

CommandPaletteSlashRequest captures input context for provider-based slash-open decisions.

type CompletionOverlayHorizontalGrow added in v0.1.0

type CompletionOverlayHorizontalGrow string
const (
	CompletionOverlayHorizontalGrowRight CompletionOverlayHorizontalGrow = "right"
	CompletionOverlayHorizontalGrowLeft  CompletionOverlayHorizontalGrow = "left"
)

type CompletionOverlayPlacement added in v0.1.0

type CompletionOverlayPlacement string
const (
	CompletionOverlayPlacementAuto   CompletionOverlayPlacement = "auto"
	CompletionOverlayPlacementAbove  CompletionOverlayPlacement = "above"
	CompletionOverlayPlacementBelow  CompletionOverlayPlacement = "below"
	CompletionOverlayPlacementBottom CompletionOverlayPlacement = "bottom"
)

type CompletionReason added in v0.1.0

type CompletionReason = suggest.Reason

CompletionReason describes why a completion request was triggered.

const (
	CompletionReasonDebounce CompletionReason = suggest.ReasonDebounce
	CompletionReasonShortcut CompletionReason = suggest.ReasonShortcut
	CompletionReasonManual   CompletionReason = suggest.ReasonManual
)

type CompletionRequest added in v0.1.0

type CompletionRequest = suggest.Request

CompletionRequest captures the current input context for suggestion lookup.

type CompletionResult added in v0.1.0

type CompletionResult = suggest.Result

CompletionResult represents what should be shown and how to apply it.

type Config

type Config struct {
	Title                string
	Prompt               string
	Placeholder          string
	Width                int
	StartMultiline       bool
	EnableExternalEditor bool
	EnableHistory        bool
	MaxHistorySize       int
	// Autocomplete controls completion scheduling, shortcuts, and popup behavior.
	Autocomplete AutocompleteConfig
	// HelpBar controls contextual in-line help updates while typing.
	HelpBar HelpBarConfig
	// HelpDrawer controls keyboard-toggle contextual panel behavior.
	HelpDrawer HelpDrawerConfig
	// CommandPalette controls command discovery/dispatch overlay behavior.
	CommandPalette CommandPaletteConfig
}

Config holds REPL shell configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a sensible default configuration.

type EvaluationCompleteMsg

type EvaluationCompleteMsg struct {
	Input  string
	Output string
	Error  error
}

EvaluationCompleteMsg is sent when evaluation is complete

type Evaluator

type Evaluator interface {
	EvaluateStream(ctx context.Context, code string, emit func(Event)) error
	GetPrompt() string
	GetName() string
	SupportsMultiline() bool
	GetFileExtension() string
}

Evaluator executes code and streams events. Errors should be represented as events too (e.g., stderr or result with error annotation), with the returned error used for terminal failures.

type Event added in v0.0.29

type Event struct {
	Kind  EventKind
	Props map[string]any
}

Event carries a semantic payload for the UI.

type EventKind added in v0.0.29

type EventKind string

EventKind enumerates structured output kinds for the timeline.

const (
	EventInput          EventKind = "repl_input"           // recommended to be emitted by REPL shell
	EventResultMarkdown EventKind = "repl_result_markdown" // props: markdown|string in "markdown" or "text"
	EventStdout         EventKind = "repl_stdout"          // props: append|string or text
	EventStderr         EventKind = "repl_stderr"          // props: append|string or text, is_error=true
	EventLog            EventKind = "repl_log"             // props: level, message, metadata(optional), fields(optional)
	EventStructuredLog  EventKind = "repl_structured_log"  // props: level, message(optional), data|metadata|fields
	EventToolCalls      EventKind = "repl_tool_calls"
	EventProgress       EventKind = "repl_progress"
	EventPerf           EventKind = "repl_perf"
	EventTable          EventKind = "repl_table"
	EventDiff           EventKind = "repl_diff"
	EventShellCmd       EventKind = "repl_shell_cmd"
	EventInspector      EventKind = "repl_inspector"
)

type ExampleEvaluator

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

ExampleEvaluator is a simple evaluator for demonstration

func NewExampleEvaluator

func NewExampleEvaluator() *ExampleEvaluator

NewExampleEvaluator creates a new example evaluator

func (*ExampleEvaluator) Evaluate

func (e *ExampleEvaluator) Evaluate(ctx context.Context, code string) (string, error)

Evaluate implements the Evaluator interface

func (*ExampleEvaluator) EvaluateStream added in v0.0.29

func (e *ExampleEvaluator) EvaluateStream(ctx context.Context, code string, emit func(Event)) error

EvaluateStream adapts Evaluate to the streaming interface expected by the REPL timeline.

func (*ExampleEvaluator) GetFileExtension

func (e *ExampleEvaluator) GetFileExtension() string

GetFileExtension returns the file extension for external editor

func (*ExampleEvaluator) GetName

func (e *ExampleEvaluator) GetName() string

GetName returns the evaluator name

func (*ExampleEvaluator) GetPrompt

func (e *ExampleEvaluator) GetPrompt() string

GetPrompt returns the prompt string

func (*ExampleEvaluator) SupportsMultiline

func (e *ExampleEvaluator) SupportsMultiline() bool

SupportsMultiline returns true if multiline is supported

type ExternalEditorCompleteMsg

type ExternalEditorCompleteMsg struct {
	Content string
	Error   error
}

ExternalEditorCompleteMsg is sent when external editor is complete

type ExternalEditorMsg

type ExternalEditorMsg struct {
	Content string
}

ExternalEditorMsg is sent when external editor should be opened

type HelpBarConfig added in v0.1.0

type HelpBarConfig struct {
	// Enabled toggles REPL help bar integration.
	Enabled bool
	// Debounce is the delay after input edits before a help bar request is sent.
	Debounce time.Duration
	// RequestTimeout bounds a single help bar request.
	RequestTimeout time.Duration
}

HelpBarConfig controls contextual help bar request and rendering behavior.

func DefaultHelpBarConfig added in v0.1.0

func DefaultHelpBarConfig() HelpBarConfig

DefaultHelpBarConfig returns default contextual help bar settings.

type HelpBarPayload added in v0.1.0

type HelpBarPayload = contextbar.Payload

HelpBarPayload describes what the REPL help bar should render.

type HelpBarProvider added in v0.1.0

type HelpBarProvider interface {
	GetHelpBar(ctx context.Context, req HelpBarRequest) (HelpBarPayload, error)
}

HelpBarProvider resolves contextual help bar text for REPL input snapshots.

type HelpBarReason added in v0.1.0

type HelpBarReason = contextbar.Reason

HelpBarReason describes why a help bar request was triggered.

const (
	HelpBarReasonDebounce HelpBarReason = contextbar.ReasonDebounce
	HelpBarReasonShortcut HelpBarReason = contextbar.ReasonShortcut
	HelpBarReasonManual   HelpBarReason = contextbar.ReasonManual
)

type HelpBarRequest added in v0.1.0

type HelpBarRequest = contextbar.Request

HelpBarRequest captures current input context for help bar lookup.

type HelpDrawerConfig added in v0.1.0

type HelpDrawerConfig struct {
	// Enabled toggles REPL help drawer integration.
	Enabled bool
	// ToggleKeys open/close the drawer while typing.
	ToggleKeys []string
	// CloseKeys close the drawer while it is visible.
	CloseKeys []string
	// RefreshShortcuts trigger an immediate drawer refresh while visible.
	RefreshShortcuts []string
	// PinShortcuts toggle pin mode (freeze typing-triggered refresh).
	PinShortcuts []string
	// Debounce is the delay after input edits before a drawer refresh is sent.
	Debounce time.Duration
	// RequestTimeout bounds a single drawer request.
	RequestTimeout time.Duration
	// Dock controls where the drawer is anchored.
	// Supported values: above-repl, right, left, bottom.
	Dock HelpDrawerDock
	// WidthPercent controls drawer width as percentage of terminal width.
	WidthPercent int
	// HeightPercent controls drawer height as percentage of terminal height.
	HeightPercent int
	// Margin keeps space between the drawer and the terminal edge/anchor.
	Margin int
	// PrefetchWhenHidden keeps requests running while drawer is hidden.
	PrefetchWhenHidden bool
}

HelpDrawerConfig controls keyboard-toggled contextual help drawer behavior.

func DefaultHelpDrawerConfig added in v0.1.0

func DefaultHelpDrawerConfig() HelpDrawerConfig

DefaultHelpDrawerConfig returns default help drawer settings.

type HelpDrawerDock added in v0.1.0

type HelpDrawerDock string
const (
	HelpDrawerDockAboveRepl HelpDrawerDock = "above-repl"
	HelpDrawerDockRight     HelpDrawerDock = "right"
	HelpDrawerDockLeft      HelpDrawerDock = "left"
	HelpDrawerDockBottom    HelpDrawerDock = "bottom"
)

type HelpDrawerDocument added in v0.1.0

type HelpDrawerDocument = contextpanel.Document

HelpDrawerDocument describes what the REPL help drawer should render.

type HelpDrawerProvider added in v0.1.0

type HelpDrawerProvider interface {
	GetHelpDrawer(ctx context.Context, req HelpDrawerRequest) (HelpDrawerDocument, error)
}

HelpDrawerProvider resolves contextual rich help for REPL input snapshots.

type HelpDrawerRequest added in v0.1.0

type HelpDrawerRequest = contextpanel.Request

HelpDrawerRequest captures current input context for rich help drawer lookup.

type HelpDrawerTrigger added in v0.1.0

type HelpDrawerTrigger = contextpanel.Trigger

HelpDrawerTrigger describes why a help drawer request was triggered.

const (
	HelpDrawerTriggerToggleOpen    HelpDrawerTrigger = contextpanel.TriggerToggleOpen
	HelpDrawerTriggerTyping        HelpDrawerTrigger = contextpanel.TriggerTyping
	HelpDrawerTriggerManualRefresh HelpDrawerTrigger = contextpanel.TriggerManualRefresh
)

type History

type History = inputhistory.History

History aliases the shared input history state manager.

func NewHistory

func NewHistory(maxSize int) *History

NewHistory keeps backward-compatible constructor usage inside repl.

type HistoryEntry

type HistoryEntry = inputhistory.HistoryEntry

HistoryEntry aliases the shared input history entry type.

type HistoryNavigationMsg

type HistoryNavigationMsg struct {
	Direction string // "up" or "down"
	Entry     string
}

HistoryNavigationMsg is sent when history navigation occurs

type InputCompleter added in v0.1.0

type InputCompleter interface {
	CompleteInput(ctx context.Context, req CompletionRequest) (CompletionResult, error)
}

InputCompleter resolves completion suggestions for REPL input snapshots.

type KeyMap added in v0.1.0

type KeyMap struct {
	Quit       key.Binding `keymap-mode:"*"`
	ToggleHelp key.Binding `keymap-mode:"*"`

	ToggleFocus key.Binding `keymap-mode:"*"`

	Submit      key.Binding `keymap-mode:"input"`
	HistoryPrev key.Binding `keymap-mode:"input"`
	HistoryNext key.Binding `keymap-mode:"input"`

	CompletionTrigger   key.Binding `keymap-mode:"input"`
	CompletionAccept    key.Binding `keymap-mode:"input"`
	CompletionPrev      key.Binding `keymap-mode:"input"`
	CompletionNext      key.Binding `keymap-mode:"input"`
	CompletionPageUp    key.Binding `keymap-mode:"input"`
	CompletionPageDown  key.Binding `keymap-mode:"input"`
	CompletionCancel    key.Binding `keymap-mode:"input"`
	HelpDrawerToggle    key.Binding `keymap-mode:"input"`
	HelpDrawerClose     key.Binding `keymap-mode:"input"`
	HelpDrawerRefresh   key.Binding `keymap-mode:"input"`
	HelpDrawerPin       key.Binding `keymap-mode:"input"`
	CommandPaletteOpen  key.Binding `keymap-mode:"input"`
	CommandPaletteClose key.Binding `keymap-mode:"input"`

	TimelinePrev      key.Binding `keymap-mode:"timeline"`
	TimelineNext      key.Binding `keymap-mode:"timeline"`
	TimelineEnterExit key.Binding `keymap-mode:"timeline"`
	CopyCode          key.Binding `keymap-mode:"timeline"`
	CopyText          key.Binding `keymap-mode:"timeline"`
}

KeyMap defines REPL key bindings with mode tags for help rendering.

func NewKeyMap added in v0.1.0

func NewKeyMap(
	autocompleteCfg AutocompleteConfig,
	helpDrawerCfg HelpDrawerConfig,
	commandPaletteCfg CommandPaletteConfig,
	focusToggleKey string,
) KeyMap

NewKeyMap returns REPL key bindings derived from config.

func (KeyMap) FullHelp added in v0.1.0

func (k KeyMap) FullHelp() [][]key.Binding

func (KeyMap) ShortHelp added in v0.1.0

func (k KeyMap) ShortHelp() []key.Binding

type Model

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

Model is a timeline-first REPL shell: timeline transcript + input line.

func NewModel

func NewModel(evaluator Evaluator, config Config, pub message.Publisher) *Model

NewModel constructs a new REPL shell with timeline transcript.

func NewModelWithContext added in v0.1.0

func NewModelWithContext(ctx context.Context, evaluator Evaluator, config Config, pub message.Publisher) *Model

NewModelWithContext constructs a REPL model whose internal app context derives from ctx. Passing nil uses context.Background().

func (*Model) Init

func (m *Model) Init() tea.Cmd

Init subscribes to evaluator events.

func (*Model) Update

func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update handles TUI events.

func (*Model) View

func (m *Model) View() string

type MultilineModeToggleMsg

type MultilineModeToggleMsg struct {
	Enabled bool
}

MultilineModeToggleMsg is sent when multiline mode is toggled

type PaletteCommand added in v0.1.0

type PaletteCommand struct {
	ID          string
	Name        string
	Description string
	Category    string
	Keywords    []string
	Enabled     func(*Model) bool
	Action      func(*Model) tea.Cmd
}

PaletteCommand describes a REPL command that can be executed from the command palette.

type PaletteCommandProvider added in v0.1.0

type PaletteCommandProvider interface {
	ListPaletteCommands(ctx context.Context) ([]PaletteCommand, error)
}

PaletteCommandProvider allows evaluators to contribute commands to the REPL command palette.

type PaletteCommandRegistry added in v0.1.0

type PaletteCommandRegistry interface {
	List(ctx context.Context, m *Model) ([]PaletteCommand, error)
}

PaletteCommandRegistry composes built-in and evaluator-contributed commands.

type QuitMsg

type QuitMsg struct{}

QuitMsg is sent when the REPL should quit

type SlashCommandMsg

type SlashCommandMsg struct {
	Command string
	Args    []string
}

SlashCommandMsg is sent when a slash command is executed

type Styles

type Styles struct {
	Title              lipgloss.Style
	Prompt             lipgloss.Style
	Result             lipgloss.Style
	Error              lipgloss.Style
	Info               lipgloss.Style
	HelpText           lipgloss.Style
	CompletionPopup    lipgloss.Style
	CompletionItem     lipgloss.Style
	CompletionSelected lipgloss.Style
}

Styles defines the visual styling for the REPL

func DefaultStyles

func DefaultStyles() Styles

DefaultStyles returns the default styling configuration

type Theme

type Theme struct {
	Name   string
	Styles Styles
}

Theme represents a color theme for the REPL

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL