diff --git a/README.md b/README.md index b6815e4..bbac1bf 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/cmd/inbuxa/completions.go b/cmd/inbuxa/completions.go new file mode 100644 index 0000000..97adadc --- /dev/null +++ b/cmd/inbuxa/completions.go @@ -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 /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 0 { + p(" %s)", c.name) + p(" sub=\"\"") + p(" for (( i=2; i 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, "'", "\\'") + "'" +} diff --git a/cmd/inbuxa/completions_test.go b/cmd/inbuxa/completions_test.go new file mode 100644 index 0000000..ecb6721 --- /dev/null +++ b/cmd/inbuxa/completions_test.go @@ -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) + } + } +} diff --git a/cmd/inbuxa/main.go b/cmd/inbuxa/main.go index 3acad04..c22aa91 100644 --- a/cmd/inbuxa/main.go +++ b/cmd/inbuxa/main.go @@ -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": diff --git a/cmd/inbuxa/man.go b/cmd/inbuxa/man.go new file mode 100644 index 0000000..75c4036 --- /dev/null +++ b/cmd/inbuxa/man.go @@ -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 +} diff --git a/cmd/inbuxa/man_test.go b/cmd/inbuxa/man_test.go new file mode 100644 index 0000000..415622a --- /dev/null +++ b/cmd/inbuxa/man_test.go @@ -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) + } +}