Add shell completions and a man page #63
No files matched your search
@@ -242,6 +242,22 @@ candidate (before 27.1 the tags were dated, `v2026.10.15.2`).
|
||||
builds the same thing locally. A release candidate is published as a
|
||||
pre-release, so `releases/latest` stays on the last final release.
|
||||
|
||||
## Shell completions and a man page
|
||||
|
||||
The binary writes its own, so there is nothing extra to download. For
|
||||
completion of the commands, flags and their values:
|
||||
|
||||
inbuxa completions bash | sudo tee /etc/bash_completion.d/inbuxa >/dev/null
|
||||
inbuxa completions zsh > "${fpath[1]}/_inbuxa" # a directory on your $fpath
|
||||
inbuxa completions fish > ~/.config/fish/completions/inbuxa.fish
|
||||
|
||||
For the manual page:
|
||||
|
||||
inbuxa man | sudo tee /usr/share/man/man1/inbuxa.1 >/dev/null
|
||||
man inbuxa
|
||||
|
||||
Both are generated from the command list, so they match the binary you have.
|
||||
|
||||
## Building and testing
|
||||
|
||||
go build ./cmd/inbuxa
|
||||
|
||||
@@ -0,0 +1,354 @@
|
||||
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
|
||||
// SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// The command model below is the one source the completion scripts and the
|
||||
// man page are generated from, so a new command or flag reaches both at once.
|
||||
// It mirrors the flags each command's FlagSet defines in this file;
|
||||
// completions_test.go checks the top-level list against the usage text, which
|
||||
// catches a command added without a model entry.
|
||||
|
||||
type command struct {
|
||||
name string
|
||||
desc string // one line, for the shell's menu and the man page
|
||||
arg string // a positional the command takes: "url", "component", "shell"; "" for none
|
||||
flags []string // long flag names, without the leading dashes
|
||||
subs []command // subcommands, for relay and cluster
|
||||
}
|
||||
|
||||
// commands is every top-level command, in the order the usage text lists them.
|
||||
func commands() []command {
|
||||
install := []string{
|
||||
"domain", "mail-host", "console-host", "webmail-host", "email",
|
||||
"server", "console", "webmail", "proxy", "dir", "local",
|
||||
"acme-directory", "acme-ca-root", "install-deps", "key",
|
||||
"dry-run", "yes", "answers",
|
||||
}
|
||||
join := []string{
|
||||
"key", "console", "webmail", "domain", "console-host", "webmail-host",
|
||||
"email", "proxy", "dir", "local", "install-deps", "replace",
|
||||
"exempt-address", "acme-directory", "acme-ca-root", "dry-run", "yes",
|
||||
}
|
||||
return []command{
|
||||
{name: "install", desc: "Install or converge the suite on this machine", flags: install},
|
||||
{name: "join", desc: "Install the console and webmail here for a server at URL", arg: "url", flags: join},
|
||||
{name: "survey", desc: "Report what this machine is, as the installer sees it"},
|
||||
{name: "deps", desc: "Report what a shape needs, and with --install fix it", flags: []string{"server", "console", "webmail", "install"}},
|
||||
{name: "plan", desc: "Show what a topology file would change here", flags: []string{"f", "machine", "yes", "install-deps", "key"}},
|
||||
{name: "apply", desc: "Make this machine match a topology file", flags: []string{"f", "machine", "yes", "install-deps", "key"}},
|
||||
{name: "export", desc: "Write a topology file from what is here", flags: []string{"o"}},
|
||||
{name: "status", desc: "Report what is installed here, and whether it agrees"},
|
||||
{name: "doctor", desc: "Run a read-only health check of this install", flags: []string{"timeout"}},
|
||||
{name: "backup", desc: "Archive this machine's mail server to <dir>/backups", flags: []string{"yes"}},
|
||||
{name: "upgrade", desc: "Move what is here to the releases this installer installs", arg: "component", flags: []string{"dry-run", "yes", "no-backup", "check"}},
|
||||
{name: "uninstall", desc: "Remove the programs, keep the data", flags: []string{"dry-run", "yes", "purge"}},
|
||||
{name: "certs", desc: "Inspect or renew the mail server's certificate", flags: []string{"key", "mail-host", "email", "acme-directory", "dry-run"}},
|
||||
{name: "dns", desc: "Print the DNS records the domain needs", flags: []string{"refresh", "key", "domain"}},
|
||||
{name: "relay", desc: "Manage inbuxa Relay on a machine of its own", subs: []command{
|
||||
{name: "install", desc: "Install the relay here", flags: []string{"token", "dry-run", "yes"}},
|
||||
{name: "status", desc: "Report the relay's status (needs root)"},
|
||||
{name: "uninstall", desc: "Remove the relay", flags: []string{"purge", "discard-held", "dry-run", "yes"}},
|
||||
}},
|
||||
{name: "cluster", desc: "Join a cluster's data layer, or check it can be reached", subs: []command{
|
||||
{name: "doctor", desc: "Check this node can reach a cluster's data layer", flags: []string{"pg", "nats", "etcd", "patroni", "s3", "timeout"}},
|
||||
{name: "join", desc: "Point this node's server at a cluster's shared store", arg: "file", flags: []string{"f", "machine", "dry-run", "yes"}},
|
||||
}},
|
||||
{name: "version", desc: "Print this program's version"},
|
||||
{name: "completions", desc: "Output a shell completion script (bash, zsh or fish)", arg: "shell"},
|
||||
{name: "man", desc: "Output the manual page, in roff"},
|
||||
{name: "help", desc: "Show the help"},
|
||||
}
|
||||
}
|
||||
|
||||
// Flags whose value is one of a small fixed set, or a file, so the scripts can
|
||||
// offer the right thing after the flag.
|
||||
var (
|
||||
shapeFlags = map[string]bool{"server": true, "console": true, "webmail": true}
|
||||
proxyFlag = "proxy"
|
||||
fileFlags = map[string]bool{"f": true, "o": true, "answers": true, "acme-ca-root": true, "dir": true}
|
||||
)
|
||||
|
||||
const (
|
||||
shapeValues = "skip container host"
|
||||
proxyValues = "caddy snippets none"
|
||||
shellValues = "bash zsh fish"
|
||||
)
|
||||
|
||||
// flagToken renders a flag as it is typed: -f for a one-letter flag, --name
|
||||
// otherwise. Go's flag package accepts either form, but this matches the docs.
|
||||
func flagToken(name string) string {
|
||||
if len(name) == 1 {
|
||||
return "-" + name
|
||||
}
|
||||
return "--" + name
|
||||
}
|
||||
|
||||
func flagTokens(names []string) []string {
|
||||
out := make([]string, len(names))
|
||||
for i, n := range names {
|
||||
out[i] = flagToken(n)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// completionsCmd writes a shell completion script to standard output. The
|
||||
// shell is given as the one argument; the script is generated from the command
|
||||
// model so it stays in step with the commands and flags.
|
||||
func completionsCmd(args []string) int {
|
||||
if len(args) != 1 || args[0] == "-h" || args[0] == "--help" {
|
||||
fmt.Fprintln(os.Stderr, "usage: inbuxa completions bash|zsh|fish")
|
||||
fmt.Fprintln(os.Stderr, "\nInstall, for the current shell, with e.g.:")
|
||||
fmt.Fprintln(os.Stderr, " inbuxa completions bash | sudo tee /etc/bash_completion.d/inbuxa")
|
||||
fmt.Fprintln(os.Stderr, " inbuxa completions zsh > \"${fpath[1]}/_inbuxa\"")
|
||||
fmt.Fprintln(os.Stderr, " inbuxa completions fish > ~/.config/fish/completions/inbuxa.fish")
|
||||
if len(args) == 1 && (args[0] == "-h" || args[0] == "--help") {
|
||||
return 0
|
||||
}
|
||||
return 2
|
||||
}
|
||||
var s string
|
||||
switch args[0] {
|
||||
case "bash":
|
||||
s = bashCompletion()
|
||||
case "zsh":
|
||||
s = zshCompletion()
|
||||
case "fish":
|
||||
s = fishCompletion()
|
||||
default:
|
||||
fmt.Fprintf(os.Stderr, "inbuxa has no completions for %q: bash, zsh or fish\n", args[0])
|
||||
return 2
|
||||
}
|
||||
fmt.Print(s)
|
||||
return 0
|
||||
}
|
||||
|
||||
func topNames() []string {
|
||||
cs := commands()
|
||||
out := make([]string, len(cs))
|
||||
for i, c := range cs {
|
||||
out[i] = c.name
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// ---- bash ----
|
||||
|
||||
func bashCompletion() string {
|
||||
var b strings.Builder
|
||||
p := func(format string, a ...any) { fmt.Fprintf(&b, format+"\n", a...) }
|
||||
|
||||
p("# bash completion for inbuxa -- generated by `inbuxa completions bash`")
|
||||
p("_inbuxa() {")
|
||||
p(" local cur prev cmd sub i")
|
||||
p(" cur=\"${COMP_WORDS[COMP_CWORD]}\"")
|
||||
p(" prev=\"${COMP_WORDS[COMP_CWORD-1]}\"")
|
||||
p("")
|
||||
p(" # a value for the flag just typed")
|
||||
p(" case \"$prev\" in")
|
||||
p(" --server|--console|--webmail) COMPREPLY=( $(compgen -W %q -- \"$cur\") ); return;;", shapeValues)
|
||||
p(" --proxy) COMPREPLY=( $(compgen -W %q -- \"$cur\") ); return;;", proxyValues)
|
||||
p(" -f|-o|--answers|--acme-ca-root|--dir) COMPREPLY=( $(compgen -f -- \"$cur\") ); return;;")
|
||||
p(" esac")
|
||||
p("")
|
||||
p(" # the first word that is not a flag is the command")
|
||||
p(" cmd=\"\"")
|
||||
p(" for (( i=1; i<COMP_CWORD; i++ )); do")
|
||||
p(" case \"${COMP_WORDS[i]}\" in -*) ;; *) cmd=\"${COMP_WORDS[i]}\"; break;; esac")
|
||||
p(" done")
|
||||
p("")
|
||||
p(" if [ -z \"$cmd\" ]; then")
|
||||
p(" COMPREPLY=( $(compgen -W %q -- \"$cur\") ); return", strings.Join(topNames(), " "))
|
||||
p(" fi")
|
||||
p("")
|
||||
p(" case \"$cmd\" in")
|
||||
for _, c := range commands() {
|
||||
if len(c.subs) > 0 {
|
||||
p(" %s)", c.name)
|
||||
p(" sub=\"\"")
|
||||
p(" for (( i=2; i<COMP_CWORD; i++ )); do case \"${COMP_WORDS[i]}\" in -*) ;; *) sub=\"${COMP_WORDS[i]}\"; break;; esac; done")
|
||||
p(" case \"$sub\" in")
|
||||
for _, s := range c.subs {
|
||||
if len(s.flags) == 0 {
|
||||
p(" %s) COMPREPLY=() ;;", s.name)
|
||||
} else {
|
||||
p(" %s) COMPREPLY=( $(compgen -W %q -- \"$cur\") ) ;;", s.name, strings.Join(flagTokens(s.flags), " "))
|
||||
}
|
||||
}
|
||||
p(" *) COMPREPLY=( $(compgen -W %q -- \"$cur\") ) ;;", subNames(c))
|
||||
p(" esac ;;")
|
||||
continue
|
||||
}
|
||||
words := strings.Join(flagTokens(c.flags), " ")
|
||||
if c.arg == "shell" {
|
||||
words = shellValues // completions takes a shell name, not flags
|
||||
}
|
||||
if words == "" {
|
||||
p(" %s) COMPREPLY=() ;;", c.name)
|
||||
} else {
|
||||
p(" %s) COMPREPLY=( $(compgen -W %q -- \"$cur\") ) ;;", c.name, words)
|
||||
}
|
||||
}
|
||||
p(" esac")
|
||||
p("}")
|
||||
p("complete -F _inbuxa inbuxa")
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func subNames(c command) string {
|
||||
out := make([]string, len(c.subs))
|
||||
for i, s := range c.subs {
|
||||
out[i] = s.name
|
||||
}
|
||||
return strings.Join(out, " ")
|
||||
}
|
||||
|
||||
// ---- zsh ----
|
||||
|
||||
func zshCompletion() string {
|
||||
var b strings.Builder
|
||||
p := func(format string, a ...any) { fmt.Fprintf(&b, format+"\n", a...) }
|
||||
|
||||
p("#compdef inbuxa")
|
||||
p("# zsh completion for inbuxa -- generated by `inbuxa completions zsh`")
|
||||
p("_inbuxa() {")
|
||||
p(" local cmd sub i")
|
||||
p(" local -a top")
|
||||
p(" top=(")
|
||||
for _, c := range commands() {
|
||||
p(" %s", zshDescribe(c.name, c.desc))
|
||||
}
|
||||
p(" )")
|
||||
p("")
|
||||
p(" case \"${words[CURRENT-1]}\" in")
|
||||
p(" --server|--console|--webmail) compadd skip container host; return;;")
|
||||
p(" --proxy) compadd caddy snippets none; return;;")
|
||||
p(" -f|-o|--answers|--acme-ca-root|--dir) _files; return;;")
|
||||
p(" esac")
|
||||
p("")
|
||||
p(" cmd=\"\"")
|
||||
p(" for (( i=2; i<CURRENT; i++ )); do")
|
||||
p(" case \"${words[i]}\" in -*) ;; *) cmd=\"${words[i]}\"; break;; esac")
|
||||
p(" done")
|
||||
p("")
|
||||
p(" if [[ -z \"$cmd\" ]]; then _describe -t commands 'inbuxa command' top; return; fi")
|
||||
p("")
|
||||
p(" case \"$cmd\" in")
|
||||
for _, c := range commands() {
|
||||
if len(c.subs) > 0 {
|
||||
p(" %s)", c.name)
|
||||
p(" local -a subs")
|
||||
p(" subs=(")
|
||||
for _, s := range c.subs {
|
||||
p(" %s", zshDescribe(s.name, s.desc))
|
||||
}
|
||||
p(" )")
|
||||
p(" sub=\"\"")
|
||||
p(" for (( i=3; i<=CURRENT; i++ )); do case \"${words[i]}\" in -*) ;; \"\") ;; *) sub=\"${words[i]}\"; break;; esac; done")
|
||||
p(" case \"$sub\" in")
|
||||
for _, s := range c.subs {
|
||||
if len(s.flags) == 0 {
|
||||
p(" %s) ;;", s.name)
|
||||
} else {
|
||||
p(" %s) compadd -- %s ;;", s.name, strings.Join(flagTokens(s.flags), " "))
|
||||
}
|
||||
}
|
||||
p(" *) _describe -t commands '%s command' subs ;;", c.name)
|
||||
p(" esac ;;")
|
||||
continue
|
||||
}
|
||||
if c.arg == "shell" {
|
||||
p(" %s) compadd bash zsh fish ;;", c.name)
|
||||
continue
|
||||
}
|
||||
if len(c.flags) == 0 {
|
||||
p(" %s) ;;", c.name)
|
||||
} else {
|
||||
p(" %s) compadd -- %s ;;", c.name, strings.Join(flagTokens(c.flags), " "))
|
||||
}
|
||||
}
|
||||
p(" esac")
|
||||
p("}")
|
||||
p("_inbuxa \"$@\"")
|
||||
return b.String()
|
||||
}
|
||||
|
||||
// zshDescribe renders one 'name:description' entry for _describe. The colon in
|
||||
// the description is escaped so zsh does not read it as the separator, and the
|
||||
// whole is single-quoted with any apostrophe escaped the POSIX way ('\”) so a
|
||||
// word like "machine's" does not end the quote.
|
||||
func zshDescribe(name, desc string) string {
|
||||
body := name + ":" + strings.ReplaceAll(desc, ":", "\\:")
|
||||
return "'" + strings.ReplaceAll(body, "'", `'\''`) + "'"
|
||||
}
|
||||
|
||||
// ---- fish ----
|
||||
|
||||
func fishCompletion() string {
|
||||
var b strings.Builder
|
||||
p := func(format string, a ...any) { fmt.Fprintf(&b, format+"\n", a...) }
|
||||
|
||||
p("# fish completion for inbuxa -- generated by `inbuxa completions fish`")
|
||||
p("complete -c inbuxa -f")
|
||||
p("")
|
||||
p("# top-level commands")
|
||||
for _, c := range commands() {
|
||||
p("complete -c inbuxa -n __fish_use_subcommand -a %s -d %s", c.name, fishQuote(c.desc))
|
||||
}
|
||||
for _, c := range commands() {
|
||||
if len(c.subs) > 0 {
|
||||
p("")
|
||||
p("# %s subcommands", c.name)
|
||||
p("complete -c inbuxa -n '__fish_seen_subcommand_from %s; and not __fish_seen_subcommand_from %s' -a '%s'", c.name, subNames(c), subNames(c))
|
||||
for _, s := range c.subs {
|
||||
for _, fl := range s.flags {
|
||||
p("complete -c inbuxa -n '__fish_seen_subcommand_from %s; and __fish_seen_subcommand_from %s' %s", c.name, s.name, fishFlag(fl))
|
||||
}
|
||||
}
|
||||
continue
|
||||
}
|
||||
if c.arg == "shell" {
|
||||
p("complete -c inbuxa -n '__fish_seen_subcommand_from %s' -a 'bash zsh fish'", c.name)
|
||||
continue
|
||||
}
|
||||
if len(c.flags) == 0 {
|
||||
continue
|
||||
}
|
||||
p("")
|
||||
p("# %s flags", c.name)
|
||||
for _, fl := range c.flags {
|
||||
p("complete -c inbuxa -n '__fish_seen_subcommand_from %s' %s", c.name, fishFlag(fl))
|
||||
}
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
// fishFlag renders one flag for `complete`, with a value hint where the value
|
||||
// is a known set or a file.
|
||||
func fishFlag(name string) string {
|
||||
var spec string
|
||||
if len(name) == 1 {
|
||||
spec = "-s " + name
|
||||
} else {
|
||||
spec = "-l " + name
|
||||
}
|
||||
switch {
|
||||
case shapeFlags[name]:
|
||||
return spec + " -x -a 'skip container host'"
|
||||
case name == proxyFlag:
|
||||
return spec + " -x -a 'caddy snippets none'"
|
||||
case fileFlags[name]:
|
||||
return spec + " -r -F"
|
||||
}
|
||||
return spec
|
||||
}
|
||||
|
||||
func fishQuote(s string) string {
|
||||
return "'" + strings.ReplaceAll(s, "'", "\\'") + "'"
|
||||
}
|
||||
@@ -0,0 +1,163 @@
|
||||
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
|
||||
// SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"regexp"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// TestModelMatchesSwitch guards against a top-level command being added to the
|
||||
// dispatch in main() without a matching entry in the completion model (which
|
||||
// would leave it out of the scripts and the man page), and the reverse. It
|
||||
// reads the real `switch os.Args[1]` block, so the two cannot drift apart
|
||||
// unnoticed.
|
||||
func TestModelMatchesSwitch(t *testing.T) {
|
||||
src, err := os.ReadFile("main.go")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
lines := strings.Split(string(src), "\n")
|
||||
start := -1
|
||||
for i, l := range lines {
|
||||
if strings.Contains(l, "switch os.Args[1] {") {
|
||||
start = i
|
||||
break
|
||||
}
|
||||
}
|
||||
if start < 0 {
|
||||
t.Fatal("could not find the top-level switch in main.go")
|
||||
}
|
||||
caseRe := regexp.MustCompile(`"([^"]+)"`)
|
||||
inSwitch := map[string]bool{}
|
||||
for _, l := range lines[start+1:] {
|
||||
if l == "\t}" { // the switch's own closing brace, at one tab
|
||||
break
|
||||
}
|
||||
if !strings.HasPrefix(strings.TrimLeft(l, " "), "case ") && !strings.HasPrefix(l, "\tcase ") {
|
||||
continue
|
||||
}
|
||||
for _, m := range caseRe.FindAllStringSubmatch(l, -1) {
|
||||
tok := m[1]
|
||||
switch tok {
|
||||
case "-h", "--help": // these fold into "help"
|
||||
default:
|
||||
inSwitch[tok] = true
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(inSwitch) == 0 {
|
||||
t.Fatal("parsed no cases from the top-level switch")
|
||||
}
|
||||
|
||||
inModel := map[string]bool{}
|
||||
for _, c := range commands() {
|
||||
inModel[c.name] = true
|
||||
}
|
||||
for name := range inSwitch {
|
||||
if !inModel[name] {
|
||||
t.Errorf("command %q is dispatched in main() but missing from the completion model", name)
|
||||
}
|
||||
}
|
||||
for name := range inModel {
|
||||
if !inSwitch[name] {
|
||||
t.Errorf("command %q is in the completion model but not dispatched in main()", name)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestBashCompletion(t *testing.T) {
|
||||
s := bashCompletion()
|
||||
for _, want := range []string{
|
||||
"complete -F _inbuxa inbuxa",
|
||||
"install join survey", // the top-level list
|
||||
"--domain", // an install flag
|
||||
"--token", // a relay install flag
|
||||
"skip container host", // shape values
|
||||
"caddy snippets none", // proxy values
|
||||
"bash zsh fish", // completions' own argument
|
||||
} {
|
||||
if !strings.Contains(s, want) {
|
||||
t.Errorf("bash completion is missing %q", want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestZshCompletion(t *testing.T) {
|
||||
s := zshCompletion()
|
||||
for _, want := range []string{
|
||||
"#compdef inbuxa",
|
||||
"_describe",
|
||||
"compadd skip container host",
|
||||
"--exempt-address", // a join flag
|
||||
"--pg", // a cluster doctor flag
|
||||
} {
|
||||
if !strings.Contains(s, want) {
|
||||
t.Errorf("zsh completion is missing %q", want)
|
||||
}
|
||||
}
|
||||
// A description's colon must be escaped so zsh does not split on it.
|
||||
if strings.Contains(zshDescribe("x", "a:b"), ":b") && !strings.Contains(zshDescribe("x", "a:b"), "a\\:b") {
|
||||
t.Errorf("zshDescribe did not escape the colon: %q", zshDescribe("x", "a:b"))
|
||||
}
|
||||
}
|
||||
|
||||
func TestFishCompletion(t *testing.T) {
|
||||
s := fishCompletion()
|
||||
for _, want := range []string{
|
||||
"complete -c inbuxa -f",
|
||||
"__fish_use_subcommand -a install",
|
||||
"__fish_seen_subcommand_from relay", // relay sub gating
|
||||
"-a 'install status uninstall'", // relay subcommands
|
||||
"-l server -x -a 'skip container host'", // shape value hint
|
||||
"-l answers -r -F", // a file flag
|
||||
} {
|
||||
if !strings.Contains(s, want) {
|
||||
t.Errorf("fish completion is missing %q", want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Every command and flag in the model must appear somewhere in each script, so
|
||||
// nothing the model knows about is silently dropped by a generator.
|
||||
func TestEveryCommandAndFlagInEachScript(t *testing.T) {
|
||||
scripts := map[string]string{
|
||||
"bash": bashCompletion(),
|
||||
"zsh": zshCompletion(),
|
||||
"fish": fishCompletion(),
|
||||
}
|
||||
for shell, s := range scripts {
|
||||
for _, c := range commands() {
|
||||
if !strings.Contains(s, c.name) {
|
||||
t.Errorf("%s completion is missing command %q", shell, c.name)
|
||||
}
|
||||
for _, fl := range c.flags {
|
||||
if !strings.Contains(s, strings.TrimLeft(flagToken(fl), "-")) {
|
||||
t.Errorf("%s completion is missing flag %q of %q", shell, fl, c.name)
|
||||
}
|
||||
}
|
||||
for _, sub := range c.subs {
|
||||
if !strings.Contains(s, sub.name) {
|
||||
t.Errorf("%s completion is missing %q subcommand %q", shell, c.name, sub.name)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestCompletionsCmdArgs(t *testing.T) {
|
||||
if code := completionsCmd(nil); code != 2 {
|
||||
t.Errorf("no shell should exit 2, got %d", code)
|
||||
}
|
||||
if code := completionsCmd([]string{"powershell"}); code != 2 {
|
||||
t.Errorf("an unsupported shell should exit 2, got %d", code)
|
||||
}
|
||||
for _, sh := range []string{"bash", "zsh", "fish"} {
|
||||
if code := completionsCmd([]string{sh}); code != 0 {
|
||||
t.Errorf("%s should exit 0, got %d", sh, code)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -81,6 +81,8 @@ const usage = `inbuxa -- install the inbuxa suite on this machine
|
||||
inbuxa cluster join -f FILE
|
||||
point this node's server at the shared store in
|
||||
the file's cluster block and give it its role
|
||||
inbuxa completions SHELL a completion script for bash, zsh or fish
|
||||
inbuxa man the manual page, in roff (inbuxa man > inbuxa.1)
|
||||
inbuxa version this program's version
|
||||
|
||||
install flags:
|
||||
@@ -235,6 +237,10 @@ func main() {
|
||||
os.Exit(relayCmd(os.Args[2:]))
|
||||
case "cluster":
|
||||
os.Exit(clusterCmd(os.Args[2:]))
|
||||
case "completions":
|
||||
os.Exit(completionsCmd(os.Args[2:]))
|
||||
case "man":
|
||||
os.Exit(manCmd(os.Args[2:]))
|
||||
case "version":
|
||||
fmt.Println(version)
|
||||
case "-h", "--help", "help":
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
|
||||
// SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// manCmd writes the manual page, in roff, to standard output. It is generated
|
||||
// from the same command model as the completions, so `inbuxa man > inbuxa.1`
|
||||
// at release time stays in step with the commands. Install it with, e.g.,
|
||||
// `inbuxa man | sudo tee /usr/share/man/man1/inbuxa.1`.
|
||||
func manCmd(args []string) int {
|
||||
if len(args) > 0 && (args[0] == "-h" || args[0] == "--help") {
|
||||
fmt.Fprintln(os.Stderr, "usage: inbuxa man # writes the manual page in roff to stdout")
|
||||
return 0
|
||||
}
|
||||
if len(args) > 0 {
|
||||
fmt.Fprintln(os.Stderr, "inbuxa man takes no arguments")
|
||||
return 2
|
||||
}
|
||||
fmt.Print(manPage())
|
||||
return 0
|
||||
}
|
||||
|
||||
func manPage() string {
|
||||
var b strings.Builder
|
||||
p := func(format string, a ...any) { fmt.Fprintf(&b, format+"\n", a...) }
|
||||
|
||||
date := time.Now().UTC().Format("2006-01-02")
|
||||
p(".TH INBUXA 1 %q %q \"inbuxa manual\"", date, "inbuxa "+version)
|
||||
p(".SH NAME")
|
||||
p("inbuxa \\- install the inbuxa mail suite on this machine")
|
||||
p(".SH SYNOPSIS")
|
||||
p(".B inbuxa")
|
||||
p("[\\fICOMMAND\\fR] [\\fIFLAGS\\fR]")
|
||||
p(".SH DESCRIPTION")
|
||||
p("Run with no arguments, \\fBinbuxa\\fR opens an interface that fills in the")
|
||||
p("machine's own facts in front of you. Run with a command it does the same")
|
||||
p("work without asking. It installs the server, the console and the webmail,")
|
||||
p("each in a container or on the host, and looks after certificates, DNS and")
|
||||
p("upgrades afterwards.")
|
||||
p(".SH COMMANDS")
|
||||
for _, c := range commands() {
|
||||
head := c.name
|
||||
if c.arg == "url" {
|
||||
head += " URL"
|
||||
}
|
||||
if c.arg == "component" {
|
||||
head += " [component...]"
|
||||
}
|
||||
if len(c.subs) > 0 {
|
||||
head += " " + subBar(c)
|
||||
} else if len(c.flags) > 0 {
|
||||
head += " [flags]"
|
||||
}
|
||||
p(".TP")
|
||||
p(".B %s", roff(head))
|
||||
p("%s.", roff(strings.TrimRight(c.desc, ".")))
|
||||
if len(c.subs) > 0 {
|
||||
p(".RS")
|
||||
for _, s := range c.subs {
|
||||
p(".TP")
|
||||
p(".B %s", roff(s.name))
|
||||
desc := roff(strings.TrimRight(s.desc, "."))
|
||||
if len(s.flags) > 0 {
|
||||
desc += ". Flags: " + roff(strings.Join(flagTokens(s.flags), ", "))
|
||||
} else {
|
||||
desc += "."
|
||||
}
|
||||
p("%s", desc)
|
||||
}
|
||||
p(".RE")
|
||||
} else if len(c.flags) > 0 {
|
||||
p(".br")
|
||||
p("Flags: %s", roff(strings.Join(flagTokens(c.flags), ", ")))
|
||||
}
|
||||
}
|
||||
p(".SH FILES")
|
||||
p(".TP")
|
||||
p(".I /etc/inbuxa/install.json")
|
||||
p("What is installed on this machine, as inbuxa recorded it.")
|
||||
p(".SH SEE ALSO")
|
||||
p(".BR inbuxa\\-cli (1),")
|
||||
p(".BR inbuxa\\-migrate (1)")
|
||||
p(".PP")
|
||||
p("Full documentation at \\fIhttps://docs.inbuxa.org/\\fR, and verifying a")
|
||||
p("download at \\fIhttps://docs.inbuxa.org/install/verifying/\\fR.")
|
||||
p(".SH COPYRIGHT")
|
||||
p("Copyright \\(co 2026 Coffey Labs LLC. License AGPL\\-3.0\\-or\\-later.")
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func subBar(c command) string {
|
||||
out := make([]string, len(c.subs))
|
||||
for i, s := range c.subs {
|
||||
out[i] = s.name
|
||||
}
|
||||
return strings.Join(out, "|")
|
||||
}
|
||||
|
||||
// roff escapes text for a roff line: a backslash becomes \e, and a leading dash
|
||||
// of an option is written \- so it renders as a minus. Hyphens inside a word
|
||||
// render as hyphens, which is what we want for names like mail-host.
|
||||
func roff(s string) string {
|
||||
s = strings.ReplaceAll(s, "\\", "\\e")
|
||||
// Escape the leading dashes of option tokens so mandoc is happy.
|
||||
s = strings.ReplaceAll(s, "--", "\\-\\-")
|
||||
s = strings.ReplaceAll(s, " -", " \\-")
|
||||
return s
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
|
||||
// SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestManPage(t *testing.T) {
|
||||
m := manPage()
|
||||
for _, want := range []string{
|
||||
".TH INBUXA 1 ",
|
||||
".SH NAME",
|
||||
"inbuxa \\- install the inbuxa mail suite",
|
||||
".SH SYNOPSIS",
|
||||
".SH DESCRIPTION",
|
||||
".SH COMMANDS",
|
||||
".SH FILES",
|
||||
"/etc/inbuxa/install.json",
|
||||
".SH SEE ALSO",
|
||||
"inbuxa\\-cli (1)",
|
||||
"AGPL\\-3.0\\-or\\-later",
|
||||
} {
|
||||
if !strings.Contains(m, want) {
|
||||
t.Errorf("man page is missing %q", want)
|
||||
}
|
||||
}
|
||||
// Every command gets a .TP entry; check a representative spread.
|
||||
for _, name := range []string{"install", "join", "backup", "cluster", "relay", "completions", "man"} {
|
||||
if !strings.Contains(m, ".B "+name) {
|
||||
t.Errorf("man page has no entry for %q", name)
|
||||
}
|
||||
}
|
||||
// Option dashes are escaped for roff.
|
||||
if !strings.Contains(m, "\\-\\-domain") {
|
||||
t.Errorf("man page did not escape the dashes of --domain")
|
||||
}
|
||||
// No control line may start with a bare backslash-less stray; the page
|
||||
// must at least be non-trivial.
|
||||
if strings.Count(m, "\n") < 40 {
|
||||
t.Errorf("man page looks too short: %d lines", strings.Count(m, "\n"))
|
||||
}
|
||||
}
|
||||
|
||||
func TestManCmdArgs(t *testing.T) {
|
||||
if code := manCmd(nil); code != 0 {
|
||||
t.Errorf("man with no args should exit 0, got %d", code)
|
||||
}
|
||||
if code := manCmd([]string{"extra"}); code != 2 {
|
||||
t.Errorf("man with an argument should exit 2, got %d", code)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user