Changelog¶
Release history for termforge. Each version is a Go module release, resolvable with
go get github.com/yairgd/termforge@vX.Y.Z; tags are listed on the
10|GitHub releases page.
Unreleased¶
Services: local by default, token, loopback listener¶
service.Service.Remote— only services markedRemoteare served over REST and MCP; the rest stay callable from Lua and in-process code. Behavior change: a service is no longer served remotely unless it setsRemote: true.service.WithToken(bearer check) andservice.ListenLoopback(loopback-only listener);service.Args.Int.
Ctrl-C hook (CompositeTerminal.SetInterruptHandler)¶
A host whose program cannot be signalled (an embedded interpreter, not a child process) can
make Ctrl-C call a function instead of sending ^C: term.SetInterruptHandler(lua.Interrupt).
A selection is still copied first. The Lua pane in the demo uses it.
Detachable sessions (termforge/detach)¶
A program can keep running when its terminal goes away and be attached again from another
terminal, without tmux: myapp --session NAME, Ctrl-] to detach, --attach NAME,
--sessions. The app opts in with one call, detach.Handle("myapp"), at the top of main;
the demo does. See Detachable sessions.
Embedded Lua (termforge/lua)¶
A C Lua 5.4 interpreter built into the module through cgo, with Lua's own REPL running on
a PTY so a CompositeTerminal shows it like any other program, and a plugin API to call Go
from Lua. See Embedded Lua. The demo gains a third tab with a pixel matrix driven
from the console (mat.plot, mat.line). It is opt-in: go build -tags lua (needs a C
compiler; Lua and the linenoise line editor are vendored, no system library); the default
build stays pure Go.
App chrome is a layout¶
The App held a flat widget slice and handed the application a HandleResize hook to
assign rects into it by index. Both consumers wrote the same three lines against w[0],
w[1], w[2], behind a len(w) < 3 guard that silently skipped layout whenever the
registration order changed. Chrome is now a WidgetsList — the flat Layout
implementation, the counterpart of WidgetTree one level up — and placement is stated
where the widget is registered:
app.AddWidget(tabWidget) // fills the rows the fixed ones leave over
app.AddRowWidget(completionBar, 1) // full-width band, in registration order
app.AddRowWidget(cmdWidget, 1)
app.AddFloatingWidget(help, helpRect) // rect recomputed per frame, owns no rows
BuildLayout stacks the rows top to bottom and gives the fill widget what is left, so the
usual banding — workspace H-2, wildmenu on row H-2, cmdline on row H-1 — falls out of
the registration order instead of being arithmetic in every app. Geometry is rebuilt on
every frame and on every UpdateCanvas, which also fixes the negative rect the old code
handed the workspace on a canvas shorter than the bands.
Upgrading¶
AppApi.HandleResizeis gone. Delete the method.UpdateCanvasreallocates the grid and the layouts recompute from the new canvas, so there is nothing left for an app to do on a resize.App.Widgets(),WidgetNodeandWidgetNode.SetRectare gone. Rect assignment becomes theAdd*call that matches the placement, and widget hit-testing becomesApp.WidgetRect:
// before — in HandleResize
w := app.Widgets()
w[2].SetRect(c.ChildRect(0, c.H()-1, c.W(), 1))
// before — hit test
for _, n := range app.Widgets() {
if n.Widget() == cmdWidget {
r = n.Rect()
}
}
// after — in setup
app.AddRowWidget(cmdWidget, 1)
// after — hit test
r := app.WidgetRect(cmdWidget)
NewAppallocates the canvas. It callsUpdateCanvasitself, so the startupHandleResize()an app made afterInitcan be dropped.- Rows always reserve their height, painted or not — the same as the hand-written bands, but there is no "collapse when inactive" placement yet.
v0.1.0¶
First tagged release: a Vim-inspired terminal application framework for Go on top of
tcell, extracted from
gdbforge, where this code grew in-tree as
internal/termui and its supporting packages.
Highlights¶
20|- **Windowing** — recursive binary split tree, drag-to-resize separators, `equalalways` rebalancing, named leaf marks, tabs; `Tab.Content` is a `Layout` interface with `WidgetTree` as the tiling implementation.
- Chrome —
CmdWidgetcommand line, wildmenu completion bar, per-pane status lines — all ordinary widgets, no popup compositor. - Commands — hierarchical command tree, incremental parser, builder DSL, prefix completion, rest-args leaves, dynamic completion callbacks.
- Input — interaction modes, multi-key sequence trie (
<C-w>h), mouse focus / selection / resize, CLIPBOARD and PRIMARY integration. - Panes —
DocumentViewandScrollDocumentover a line buffer,TableWidgetfor columnar lists,CompositeTerminalfor PTY-backed child processes,LoggerWidget. - Rendering — widgets draw in local coordinates through
Canvas→Grid→ tcell, against an off-screen grid with a single front buffer. - Plumbing —
ptyxPTY sessions and TTY allocation,execclito run a command on a PTY,devportserial helper,CoalesceRunnerburst scheduler,ChildProcCtlprocess-group supervision. - Domain-free by construction — nothing about GDB, Delve or MCP came along, and
scripts/check_imports.shenforces thatplatformstays the dependency-free base and that no termforge package imports a consuming application. - Example application —
cmd/demo: four panes in a nested split tree, a:command line with Tab completion, a floating help window, and mouse-driven focus, resize, scrolling and selection — with no debugger in it. - Docs and CI — this documentation site, a Taskfile, and GitHub Actions for build / vet / test / import guardrails plus docs publishing. 30|
The one API change made during extraction¶
The framework used to hardcode debugger prompt strings, and branched its own scroll logic on them. A terminal pane now takes that vocabulary from the application, so Home/End versus scrollback navigation is application policy rather than framework knowledge:
term.SetPromptPrefixes(termforge.PromptPrefixes{
Console: []string{"(gdb) ", "(dlv) "}, // rows where Home/End edit the line
Strip: []string{"(gdb) ", "(dlv) ", "> "},
40|})
termforge ships no default prompt vocabulary. See Input for where this sits in the dispatch order.
Adopting v0.1.0¶
- Six direct dependencies:
tcell/v2,creack/pty,gitpod-io/xterm-go,golang.design/x/clipboard,golang.org/x/sys,go.bug.st/serial. No debugger, no syntax highlighter, no Lua interpreter. 50|- Pre-1.0, so the API can still move. This surface was shaped by a single consumer; it will be revised against the second one rather than frozen now. - tcell appears in the public API —
Widget.HandleEvent(ev tcell.Event)andKeyHandler func(ev *tcell.EventKey) boolexpose it deliberately. Abstracting over one implementation would produce the wrong abstraction, so this is documented as a limitation rather than presented as a design goal. See UI Architecture. - No history before the extraction. termforge starts at its initial commit, so
git blamedoes not reach back into gdbforge.