bom

README

bom

A Fyne-based GUI wrapper library that turns any CLI TUI application into a native desktop app. It embeds a terminal emulator widget, launches your TUI binary inside it, and packages as a normal .app / .exe / desktop entry.

Named after the Portuguese word bom (good) — because a good app should just work when you click it.

How It Works

bom has two roles:

1. Code generation: bom.Generate() renders a main.go.tmpl template with your app's metadata, producing a self-contained main.go for the Fyne wrapper binary.
2. Runtime: bom.Run() resolves the CLI binary, opens a Fyne window with a terminal emulator widget, and launches the TUI inside it.

The generated main.go imports bom as a library, embeds the CLI binary via //go:embed, and calls bom.Run().

Project Structure

bom/
├── bom.go          # library: Generate(), Run(), Config, resolution logic
├── main.go.tmpl    # template for generated host main.go
├── go.mod
└── README.md

Template

main.go.tmpl uses Go's text/template syntax. The template variables are:

Variable	Example	Description
{{.CLIBinaryName}}	estreia	CLI binary name
{{.AppID}}	com.curiosa.estreia	Fyne app ID and data directory path
{{.AppName}}	Estreia	Window title
{{.WindowWidth}}	900	Initial window width
{{.WindowHeight}}	600	Initial window height

Usage from a Build Tool

A build tool (e.g. forja) calls bom.Generate() to produce the host project's main.go, then compiles it:

src, err := bom.Generate(bom.TemplateData{
    CLIBinaryName: "estreia",
    AppID:         "com.curiosa.estreia",
    AppName:       "Estreia",
    WindowWidth:   "900",
    WindowHeight:  "600",
})
// write src to cmd/gui/main.go

CLI Binary Resolution

At runtime, bom finds the TUI binary through a priority chain:

1. Environment variable — {APPNAME}_CLI_PATH (e.g. ESTREIA_CLI_PATH=/usr/local/bin/estreia)
2. Extracted copy — previously extracted to the app data directory, verified by SHA-256 checksum
3. On $PATH — for workflows where CLI and GUI are installed separately
4. Embedded binary — extracted on first run for a single-file distribution

Embedded Binary Naming

The generated main.go expects CLI binaries in an embedded/ directory alongside it:

embedded/{name}-{GOOS}-{GOARCH}[.exe]

Examples:

• embedded/estreia-linux-amd64
• embedded/estreia-darwin-arm64
• embedded/estreia-windows-amd64.exe

Dependencies

• Fyne v2 — GUI toolkit
• fyne-io/terminal — terminal emulator widget
• fyne-cross — cross-platform packaging (optional, requires Docker)

Documentation

Overview

Package bom provides a Fyne GUI wrapper library that turns any CLI TUI application into a native desktop app. It has two roles:

1. At build time: generate a customized main.go for the host project from an embedded template via Generate().
2. At runtime: resolve the CLI binary and launch it inside a Fyne terminal emulator widget via Run().

Index

• func Generate(data TemplateData) (string, error)
• func Run(cfg Config) error
• type Config
• type TemplateData

Functions

func Generate

func Generate(data TemplateData) (string, error)

Generate renders the main.go template with the given data and returns the resulting Go source as a string.

func Run

func Run(cfg Config) error

Run launches the Fyne wrapper. It does not return until the window is closed.

Types

type Config

type Config struct {
	// CLIBinaryName is the name of the CLI binary to launch (required).
	CLIBinaryName string

	// AppID is the application identifier, e.g. "com.curiosa.estreia".
	AppID string

	// AppName is the window title. Defaults to CLIBinaryName.
	AppName string

	// WindowWidth and WindowHeight set the initial window size.
	WindowWidth  float32
	WindowHeight float32

	// EmbeddedBinaries is the embedded filesystem from the host project
	// containing CLI binaries. May be nil if only PATH/env resolution
	// is desired.
	EmbeddedBinaries *embed.FS

	// EmbeddedDir is the directory prefix inside EmbeddedBinaries.
	// Defaults to "embedded".
	EmbeddedDir string
}

Config holds the runtime wrapper configuration.

type TemplateData

type TemplateData struct {
	CLIBinaryName string // e.g. "estreia"
	AppID         string // e.g. "com.curiosa.estreia"
	AppName       string // e.g. "Estreia"
	WindowWidth   string // e.g. "900"
	WindowHeight  string // e.g. "600"
	ModulePath    string // e.g. "codeberg.org/curiosa/estreia"
}

TemplateData holds the values substituted into main.go.tmpl.