bango

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2026 License: MIT Imports: 5 Imported by: 0

README

bango

A tool describes a screen as JSON. bango draws it — in a terminal, in Neovim, in a browser — and the tool's own actions come along as data.

mytool status --bango | bango
git-branches | bango
bango -- mia panel dashboard

bango is Swahili for a signboard: the thing you pin notices to.

Install

go install github.com/emusoi/bango/cmd/bango@latest

The renderer is one binary. A producer needs nothing installed — it emits JSON, and SPEC.md is the whole contract.

Twenty lines of shell

#!/bin/sh
git for-each-ref --sort=-committerdate refs/heads/ \
  --format='%(refname:short)%09%(committerdate:relative)%09%(subject)' |
jq -Rs '{
  bango: 1, id: "branches", title: "branches",
  sections: [{ id: "all", label: "recent first",
    rows: (split("\n") | map(select(length > 0)) | map(split("\t") | {
      id: .[0],
      fields: [
        {name:"branch", value:.[0], kind:"ref"},
        {name:"age",    value:.[1], kind:"time"},
        {name:"subject",value:.[2]}],
      actions: ["checkout","delete"]})) }],
  actions: {
    checkout: {key:"⏎", label:"checkout", verb:"git", args:["switch","{row}"]},
    delete:   {key:"dd", label:"delete",  verb:"git", args:["branch","-d","{row}"],
               confirm:"delete {row}?"}}}'
$ ./git-branches | bango          # picks, prints the branch, runs nothing
$ bango -- ./git-branches         # picks, and runs the checkout

The two modes

select is the default and the only behaviour for anything arriving on stdin. bango draws, you pick, it prints the choice and exits. It executes nothing, so a panel from a pipe, a file or an agent is safe to render.

drive — bango -- CMD — runs the command you named, renders it, and runs its actions, re-running the producer after each one.

Argv is executed only when you typed the program that produced it.

Remote

ssh box mytool panel dash | bango           # read it; nothing can run
bango --via-ssh fedora -- mia api dashboard --bango
bango --via 'docker exec -i web' -- mytool panel dash

A transport covers the producer and its actions together, so what you act on runs where the panel came from. --via passes argv straight through; --via-ssh shell-quotes every argument, because sshd runs what it gets through a shell.

In a browser

bango --serve 127.0.0.1:0 --watch 5 -- mia api dashboard --bango
http://127.0.0.1:59065/?t=31c073d0…

The same document, rendered as a page, updating over server-sent events, with the panel's actions as buttons. Loopback only, a token on every request, Host and Origin both checked, and --read-only when you want the screen without the verbs.

Writing a producer

Any language. The document is the contract and jq is a perfectly good producer. In Go:

import "github.com/emusoi/bango"

p := bango.Panel{
    Version: bango.Version, ID: "items", Title: "items",
    Sections: []bango.Section{{ID: "all", Rows: rows}},
}

The package is types, validation and a relative-time helper. It has no dependencies and does not render.

Writing a renderer

Read SPEC.md, then make fixtures/ reproduce. The fixtures are the conformance suite and the specification's tests.

What it is not

Not a widget toolkit, not a layout engine, not a forms library, not a TUI framework. It describes a titled set of sections containing rows with actions, and refuses everything else.

MIT.

Panels of panels

An action whose command prints a panel pushes it; q pops back. examples/launcher is a repository menu in twenty-five lines of shell:

$ bango -- examples/launcher
this repository
   branches
   working tree

That is one mechanism, not a second kind of action: run a command, and if what comes back is a panel, render it.

License

MIT. See LICENSE.

Documentation

Index

Constants

View Source
const Version = 1

Variables

This section is empty.

Functions

func Elapsed

func Elapsed(d time.Duration) string

func Fit

func Fit(value string, kind Kind, width int) string

func Matches

func Matches(row Row, query string) bool

func Render

func Render(p Panel, style Style) []string

func ShellJoin

func ShellJoin(argv []string) string

func ShellQuote

func ShellQuote(arg string) string

func Since

func Since(t time.Time) string

func Validate

func Validate(p *Panel) error

func ValidateTargets

func ValidateTargets(p *Panel) error

Types

type Action

type Action struct {
	Key     string   `json:"key"`
	Label   string   `json:"label"`
	Verb    string   `json:"verb,omitempty"`
	Args    []string `json:"args,omitempty"`
	Input   string   `json:"input,omitempty"`
	Choices []string `json:"choices,omitempty"`
	Confirm string   `json:"confirm,omitempty"`
	Panel   string   `json:"panel,omitempty"`
	Global  bool     `json:"global,omitempty"`
	Retry   []Retry  `json:"retry,omitempty"`
	Help    string   `json:"help,omitempty"`
}

func (Action) RetryFor

func (a Action) RetryFor(refusal string) (Retry, bool)

type Column

type Column struct {
	Name  string
	Kind  Kind
	Width int
}

func Columns

func Columns(rows []Row, width int) []Column

type Field

type Field struct {
	Name  string `json:"name"`
	Value string `json:"value"`
	Kind  Kind   `json:"kind,omitempty"`
}

type Invalid

type Invalid struct {
	Path   string
	Reason string
}

func (Invalid) Error

func (e Invalid) Error() string

type Kind

type Kind string
const (
	KindText  Kind = "text"
	KindPath  Kind = "path"
	KindCount Kind = "count"
	KindTime  Kind = "time"
	KindRef   Kind = "ref"
)

func (Kind) Known

func (k Kind) Known() bool

type Line

type Line struct {
	Row     Row
	Depth   int
	Section string
	Header  bool
	Label   string
}

func Lines

func Lines(p Panel, folded map[string]bool) []Line

type Mark

type Mark string
const (
	MarkNone     Mark = ""
	MarkHere     Mark = "here"
	MarkNew      Mark = "new"
	MarkWorking  Mark = "working"
	MarkWaiting  Mark = "waiting"
	MarkDone     Mark = "done"
	MarkDirty    Mark = "dirty"
	MarkBlocked  Mark = "blocked"
	MarkDetached Mark = "detached"
)

func (Mark) Glyph

func (m Mark) Glyph(ascii bool) string

func (Mark) Known

func (m Mark) Known() bool

type Panel

type Panel struct {
	Version  int               `json:"bango"`
	ID       string            `json:"id"`
	Title    string            `json:"title"`
	Subtitle string            `json:"subtitle,omitempty"`
	Empty    string            `json:"empty,omitempty"`
	Hints    []string          `json:"hints,omitempty"`
	Order    []string          `json:"order,omitempty"`
	Sections []Section         `json:"sections"`
	Actions  map[string]Action `json:"actions,omitempty"`
}

func Filter

func Filter(p Panel, query string) Panel

func (Panel) ActionNames

func (p Panel) ActionNames() []string

func (Panel) Find

func (p Panel) Find(id string) (Row, bool)

func (Panel) Rows

func (p Panel) Rows() []Row

type Retry

type Retry struct {
	When  string   `json:"when"`
	Label string   `json:"label"`
	Verb  string   `json:"verb"`
	Args  []string `json:"args,omitempty"`
}

type Row

type Row struct {
	ID       string   `json:"id"`
	Mark     Mark     `json:"mark,omitempty"`
	Fields   []Field  `json:"fields"`
	Note     string   `json:"note,omitempty"`
	Actions  []string `json:"actions,omitempty"`
	Facts    []string `json:"facts,omitempty"`
	Preview  []string `json:"preview,omitempty"`
	Children []Row    `json:"children,omitempty"`
	Dim      bool     `json:"dim,omitempty"`
	Target   string   `json:"target,omitempty"`
}

func Keep

func Keep(row Row, query string) (Row, bool)

func (Row) TargetID

func (r Row) TargetID() string

type Section

type Section struct {
	ID        string `json:"id"`
	Label     string `json:"label,omitempty"`
	Rows      []Row  `json:"rows"`
	Collapsed bool   `json:"collapsed,omitempty"`
}

type Style

type Style struct {
	Width  int
	Height int
	ASCII  bool
	Cursor string
	Folded map[string]bool
	Query  string
}

type Transport

type Transport struct {
	Prefix []string
	Shell  bool
}

func Local

func Local() Transport

func Via

func Via(prefix []string) Transport

func ViaSSH

func ViaSSH(host string, extra ...string) Transport

func (Transport) Argv

func (t Transport) Argv(verb string, args []string) []string

func (Transport) Remote

func (t Transport) Remote() bool

Directories

Path Synopsis
cmd
bango command

Jump to

Keyboard shortcuts

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