feat(cli): implement personality for application name-agnostic help manuals

cmd/version.go

@@ -24,3 +24,17 @@ func MockVersion(version string) (restore func()) {
 	Version = version
 	return func() { Version = old }
 }
+
+// PersonalityInfo contains information about the application identity.
+// These values will be used across the CLI.
+type PersonalityInfo struct {
+	// ProgramName represents the name of the application binary (i.e. pebble)
+	ProgramName string
+	// DisplayName represents the user-facing name of the application (i.e. Pebble)
+	DisplayName string
+}
+
+var Personality PersonalityInfo = PersonalityInfo{
+	ProgramName: "pebble",
+	DisplayName: "Pebble",
+}

internals/cli/cli.go

@@ -30,6 +30,7 @@ import (
 	"golang.org/x/crypto/ssh/terminal"
 
 	"github.com/canonical/pebble/client"
+	"github.com/canonical/pebble/cmd"
 	"github.com/canonical/pebble/internals/logger"
 )
 
@@ -179,8 +180,8 @@ func Parser(cli *client.Client) *flags.Parser {
 	}
 	flagopts := flags.Options(flags.PassDoubleDash)
 	parser := flags.NewParser(&optionsData, flagopts)
-	parser.ShortDescription = "Tool to interact with pebble"
-	parser.LongDescription = longPebbleDescription
+	parser.ShortDescription = fmt.Sprintf("Tool to interact with %s", cmd.Personality.DisplayName)
+	parser.LongDescription = longPebbleDescription()
 	// hide the unhelpful "[OPTIONS]" from help output
 	parser.Usage = ""
 	if version := parser.FindOptionByLongName("version"); version != nil {
@@ -333,7 +334,7 @@ func Run() error {
 		}
 	}()
 
-	logger.SetLogger(logger.New(os.Stderr, "[pebble] "))
+	logger.SetLogger(logger.New(os.Stderr, fmt.Sprintf("[%s] ", cmd.Personality.ProgramName)))
 
 	_, clientConfig.Socket = getEnvPaths()
 
@@ -355,11 +356,11 @@ func Run() error {
 				return nil
 			case flags.ErrUnknownCommand:
 				sub := os.Args[1]
-				sug := "pebble help"
+				sug := cmd.Personality.ProgramName + " help"
 				if len(xtra) > 0 {
 					sub = xtra[0]
 					if x := parser.Command.Active; x != nil && x.Name != "help" {
-						sug = "pebble help " + x.Name
+						sug = cmd.Personality.ProgramName + " help " + x.Name
 					}
 				}
 				return fmt.Errorf("unknown command %q, see '%s'.", sub, sug)
@@ -403,7 +404,7 @@ func errorToMessage(e error) (normalMessage string, err error) {
 		}
 	case client.ErrorKindSystemRestart:
 		isError = false
-		msg = "pebble is about to reboot the system"
+		msg = fmt.Sprintf("%s is about to reboot the system", cmd.Personality.ProgramName)
 	case client.ErrorKindNoDefaultServices:
 		msg = "no default services"
 	default:

internals/cli/cmd_enter.go

@@ -10,7 +10,7 @@ import (
 
 const shortEnterHelp = "Run subcommand under a container environment"
 const longEnterHelp = `
-The enter command facilitates the use of Pebble as an entrypoint for containers.
+The enter command facilitates the use of the daemon as an entrypoint for containers.
 When used without a subcommand it mimics the behavior of the run command
 alone, while if used with a subcommand it runs that subcommand in the most
 appropriate environment taking into account its purpose.
@@ -160,7 +160,7 @@ func (cmd *cmdEnter) Execute(args []string) error {
 	case runStop = <-runReadyCh:
 	case runPanic := <-runResultCh:
 		if runPanic == nil {
-			panic("internal error: pebble daemon stopped early")
+			panic("internal error: daemon stopped early")
 		}
 		panic(runPanic)
 	}

internals/cli/cmd_exec.go

@@ -71,7 +71,7 @@ stderr are output locally.
 To avoid confusion, exec options may be separated from the command and its
 arguments using "--", for example:
 
-pebble exec --timeout 10s -- echo -n foo bar
+	exec --timeout 10s -- echo -n foo bar
 `
 
 func (cmd *cmdExec) Execute(args []string) error {

internals/cli/cmd_help.go

@@ -23,6 +23,7 @@ import (
 	"unicode/utf8"
 
 	"github.com/canonical/go-flags"
+	"github.com/canonical/pebble/cmd"
 )
 
 var shortHelpHelp = "Show help about a command"
@@ -101,11 +102,11 @@ type manfixer struct {
 func (w *manfixer) Write(buf []byte) (int, error) {
 	if !w.done {
 		w.done = true
-		if bytes.HasPrefix(buf, []byte(".TH pebble 1 ")) {
+		if bytes.HasPrefix(buf, []byte(fmt.Sprintf(".TH %s 1 ", cmd.Personality.ProgramName))) {
 			// io.Writer.Write must not modify the buffer, even temporarily
-			n, _ := w.Buffer.Write(buf[:9])
+			n, _ := w.Buffer.Write(buf[:5+len(cmd.Personality.ProgramName)])
 			w.Buffer.Write([]byte{'8'})
-			m, err := w.Buffer.Write(buf[10:])
+			m, err := w.Buffer.Write(buf[6+len(cmd.Personality.ProgramName):])
 			return n + m + 1, err
 		}
 	}
@@ -119,40 +120,40 @@ func (w *manfixer) flush() {
 	io.Copy(Stdout, strings.NewReader(str))
 }
 
-func (cmd cmdHelp) Execute(args []string) error {
+func (rcmd cmdHelp) Execute(args []string) error {
 	if len(args) > 0 {
 		return ErrExtraArgs
 	}
-	if cmd.Manpage {
+	if rcmd.Manpage {
 		// you shouldn't try to to combine --man with --all nor a
 		// subcommand, but --man is hidden so no real need to check.
 		out := &manfixer{}
-		cmd.parser.WriteManPage(out)
+		rcmd.parser.WriteManPage(out)
 		out.flush()
 		return nil
 	}
-	if cmd.All {
-		if len(cmd.Positional.Subs) > 0 {
+	if rcmd.All {
+		if len(rcmd.Positional.Subs) > 0 {
 			return fmt.Errorf("help accepts a command, or '--all', but not both.")
 		}
-		printLongHelp(cmd.parser)
+		printLongHelp(rcmd.parser)
 		return nil
 	}
 
-	var subcmd = cmd.parser.Command
-	for _, subname := range cmd.Positional.Subs {
+	var subcmd = rcmd.parser.Command
+	for _, subname := range rcmd.Positional.Subs {
 		subcmd = subcmd.Find(subname)
 		if subcmd == nil {
-			sug := "pebble help"
-			if x := cmd.parser.Command.Active; x != nil && x.Name != "help" {
-				sug = "pebble help " + x.Name
+			sug := cmd.Personality.ProgramName + " help"
+			if x := rcmd.parser.Command.Active; x != nil && x.Name != "help" {
+				sug = cmd.Personality.ProgramName + " help " + x.Name
 			}
 			return fmt.Errorf("unknown command %q, see '%s'.", subname, sug)
 		}
 		// this makes "pebble help foo" work the same as "pebble foo --help"
-		cmd.parser.Command.Active = subcmd
+		rcmd.parser.Command.Active = subcmd
 	}
-	if subcmd != cmd.parser.Command {
+	if subcmd != rcmd.parser.Command {
 		return &flags.Error{Type: flags.ErrHelp}
 	}
 	return &flags.Error{Type: flags.ErrCommandRequired}
@@ -167,7 +168,7 @@ type helpCategory struct {
 // helpCategories helps us by grouping commands
 var helpCategories = []helpCategory{{
 	Label:       "Run",
-	Description: "run pebble",
+	Description: "run the daemon",
 	Commands:    []string{"run", "help", "version"},
 }, {
 	Label:       "Plan",
@@ -191,37 +192,35 @@ var helpCategories = []helpCategory{{
 	Commands:    []string{"warnings", "okay"},
 }}
 
-var (
-	longPebbleDescription = strings.TrimSpace(`
-Pebble lets you control services and perform management actions on
-the system that is running them.
-`)
-	pebbleUsage               = "Usage: pebble <command> [<options>...]"
-	pebbleHelpCategoriesIntro = "Commands can be classified as follows:"
-	pebbleHelpAllFooter       = "Set the PEBBLE environment variable to override the configuration directory \n" +
-		"(which defaults to " + defaultPebbleDir + "). Set PEBBLE_SOCKET to override \n" +
-		"the unix socket used for the API (defaults to $PEBBLE/.pebble.socket).\n" +
-		"\n" +
-		"For more information about a command, run 'pebble help <command>'."
-	pebbleHelpFooter = "For a short summary of all commands, run 'pebble help --all'."
-)
+func longPebbleDescription() string {
+	return fmt.Sprintf(strings.TrimSpace(`
+%s lets you control services and perform management actions on the
+system that is running them
+	`), cmd.Personality.DisplayName)
+}
 
 func printHelpHeader() {
-	fmt.Fprintln(Stdout, longPebbleDescription)
+	fmt.Fprintln(Stdout, longPebbleDescription())
 	fmt.Fprintln(Stdout)
-	fmt.Fprintln(Stdout, pebbleUsage)
+	fmt.Fprintf(Stdout, "Usage: %s <command> [<options>...]\n", cmd.Personality.ProgramName)
 	fmt.Fprintln(Stdout)
-	fmt.Fprintln(Stdout, pebbleHelpCategoriesIntro)
+	fmt.Fprintln(Stdout, `Commands can be classified as follows:`)
 }
 
 func printHelpAllFooter() {
 	fmt.Fprintln(Stdout)
-	fmt.Fprintln(Stdout, pebbleHelpAllFooter)
+	fmt.Fprintf(Stdout, strings.TrimSpace(`
+Set the PEBBLE environment variable to override the configuration directory
+(which defaults to %s). Set PEBBLE_SOCKET to override
+the unix socket used for the API (defaults to $PEBBLE/.pebble.socket).
+
+For more information about a command, run '%s help <command>'.
+	`)+"\n", defaultPebbleDir, cmd.Personality.ProgramName)
 }
 
 func printHelpFooter() {
 	printHelpAllFooter()
-	fmt.Fprintln(Stdout, pebbleHelpFooter)
+	fmt.Fprintf(Stdout, "For a short summary of all commands, run '%s help --all'.\n", cmd.Personality.ProgramName)
 }
 
 // this is called when the Execute returns a flags.Error with ErrCommandRequired

internals/cli/cmd_help_test.go

@@ -56,7 +56,7 @@ func (s *PebbleSuite) TestHelpMan(c *C) {
 
 	err := cli.RunMain()
 	c.Assert(err, Equals, nil)
-	c.Check(s.Stdout(), Matches, `(?s)\.TH.*\.SH NAME.*pebble \\- Tool to interact with pebble.*`)
+	c.Check(s.Stdout(), Matches, `(?s)\.TH.*\.SH NAME.*pebble \\- Tool to interact with Pebble.*`)
 	c.Check(s.Stderr(), Equals, "")
 }
 

internals/cli/cmd_plan.go

@@ -26,8 +26,9 @@ type cmdPlan struct {
 
 var shortPlanHelp = "Show the plan with layers combined"
 var longPlanHelp = `
-The plan command prints out the effective configuration of pebble in YAML
-format. Layers are combined according to the override rules defined in them.
+The plan command prints out the effective configuration of the service manager
+in YAML format. Layers are combined according to the override rules defined in
+them.
 `
 
 func (cmd *cmdPlan) Execute(args []string) error {

internals/cli/cmd_run.go

@@ -31,16 +31,16 @@ import (
 	"github.com/canonical/pebble/internals/systemd"
 )
 
-var shortRunHelp = "Run the pebble environment"
+var shortRunHelp = "Run the daemon"
 var longRunHelp = `
-The run command starts pebble and runs the configured environment.
+The run command starts the daemon and runs the configured environment.
 
 Additional arguments may be provided to the service command with the --args option, which
-must be terminated with ";" unless there are no further Pebble options.  These arguments
+must be terminated with ";" unless there are no further program options.  These arguments
 are appended to the end of the service command, and replace any default arguments defined
 in the service plan. For example:
 
-    $ pebble run --args myservice --port 8080 \; --hold
+    run --args myservice --port 8080 \; --hold
 `
 
 type sharedRunEnterOpts struct {
@@ -52,7 +52,7 @@ type sharedRunEnterOpts struct {
 }
 
 var sharedRunEnterOptsHelp = map[string]string{
-	"create-dirs": "Create pebble directory on startup if it doesn't exist",
+	"create-dirs": "Create state directory on startup if it doesn't exist",
 	"hold":        "Do not start default services automatically",
 	"http":        `Start HTTP API listening on this address (e.g., ":4000")`,
 	"verbose":     "Log all output from services to stdout",
@@ -90,7 +90,7 @@ func (rcmd *cmdRun) run(ready chan<- func()) {
 			// This exit code must be in system'd SuccessExitStatus.
 			panic(&exitStatus{42})
 		}
-		fmt.Fprintf(os.Stderr, "cannot run pebble: %v\n", err)
+		fmt.Fprintf(os.Stderr, "cannot run %s: %v\n", cmd.Personality.ProgramName, err)
 		panic(&exitStatus{1})
 	}
 }

internals/cli/cmd_signal.go

@@ -36,7 +36,7 @@ var longSignalHelp = `
 The signal command sends a signal to one or more running services. The signal
 name must be uppercase, for example:
 
-pebble signal HUP mysql nginx
+	signal HUP mysql nginx
 `
 
 func (cmd *cmdSignal) Execute(args []string) error {

internals/cli/cmd_warnings.go

@@ -28,6 +28,7 @@ import (
 	"github.com/canonical/x-go/strutil/quantity"
 
 	"github.com/canonical/pebble/client"
+	"github.com/canonical/pebble/cmd"
 	"github.com/canonical/pebble/internals/osutil"
 )
 
@@ -45,7 +46,7 @@ var shortWarningsHelp = "List warnings"
 var longWarningsHelp = `
 The warnings command lists the warnings that have been reported to the system.
 
-Once warnings have been listed with 'pebble warnings', 'pebble okay' may be used to
+Once warnings have been listed with 'warnings', 'okay' may be used to
 silence them. A warning that's been silenced in this way will not be listed
 again unless it happens again, _and_ a cooldown time has passed.
 
@@ -54,7 +55,7 @@ Warnings expire automatically, and once expired they are forgotten.
 
 var shortOkayHelp = "Acknowledge warnings"
 var longOkayHelp = `
-The okay command acknowledges the warnings listed with 'pebble warnings'.
+The okay command acknowledges the warnings listed with 'warnings'.
 
 Once acknowledged, a warning won't appear again unless it reoccurs and
 sufficient time has passed.
@@ -211,7 +212,7 @@ func lastWarningTimestamp() (time.Time, error) {
 	f, err := os.Open(warnFilename(user.HomeDir))
 	if err != nil {
 		if os.IsNotExist(err) {
-			return time.Time{}, fmt.Errorf("you must have looked at the warnings before acknowledging them. Try 'pebble warnings'.")
+			return time.Time{}, fmt.Errorf("you must have looked at the warnings before acknowledging them. Try '%s warnings'.", cmd.Personality.ProgramName)
 		}
 		return time.Time{}, fmt.Errorf("cannot open timestamp file: %v", err)
 	}
@@ -235,9 +236,9 @@ func maybePresentWarnings(count int, timestamp time.Time) {
 		return
 	}
 
-	format := "WARNING: There are %d new warnings. See 'pebble warnings'.\n"
+	format := "WARNING: There are %d new warnings. See '%s warnings'.\n"
 	if count == 1 {
-		format = "WARNING: There is %d new warning. See 'pebble warnings'.\n"
+		format = "WARNING: There is %d new warning. See '%s warnings'.\n"
 	}
-	fmt.Fprintf(Stderr, format, count)
+	fmt.Fprintf(Stderr, format, count, cmd.Personality.ProgramName)
 }