Skip to content

termforge v0.1.0

Latest

Choose a tag to compare

@yairgd yairgd released this 16 Sep 19:47
· 28 commits to main since this release

termforge v0.1.0

First tagged release of termforge: a Vim-inspired terminal application framework for Go, built on tcell. Extracted from gdbforge, where this code grew in-tree as internal/termui and its supporting packages.

Highlights

  • Windowing — recursive binary split tree, drag-to-resize separators, equalalways rebalancing, named leaf marks, tabs; Tab.Content is a Layout interface with SplitLayout as the tiling implementation
  • Chrome — CmdWidget command 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
    10|- Input — interaction modes, multi-key sequence trie (<C-w>h), mouse focus / selection / resize, CLIPBOARD and PRIMARY integration
  • Panes — DocumentView and ScrollDocument over a line buffer, TableWidget for columnar lists, CompositeTerminal for 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 — ptyx PTY sessions and TTY allocation, execcli to run a command on a PTY, devport serial helper, CoalesceRunner burst scheduler, ChildProcCtl process-group supervision
  • Domain-free by construction — nothing about GDB, Delve or MCP came along, and scripts/check_imports.sh enforces that platform stays 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 — a MkDocs site at https://yairgd.github.io/termforge/, a Taskfile, and GitHub Actions for build / vet / test / import guardrails plus docs publishing

The one API change made during extraction

20|The framework used to hardcode debugger prompt strings, and branched its own scroll logic on them:
var gdbConsolePrompts = []string{"(gdb) ", "(dlv) "}

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
    30|    Strip:   []string{"(gdb) ", "(dlv) ", "> "},
})

termforge ships no default prompt vocabulary.

Install

go get github.com/yairgd/termforge@v0.1.0
    40|go run github.com/yairgd/termforge/cmd/demo@v0.1.0   # runnable example

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.

Notes

  • Pre-1.0, so the API can still move. This surface was shaped by a single consumer;
    50| it will be revised against the second one rather than frozen now.
  • tcell appears in the public API — Widget.HandleEvent(ev tcell.Event) and
    KeyHandler func(ev *tcell.EventKey) bool expose 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.
  • No history before the extraction. termforge starts at its initial commit, so
    git blame does not reach back into gdbforge.