feat(completion): add completion install subcommand and wire it into installer.sh / npm

.gitignore

@@ -1,5 +1,6 @@
 internal/legacy/archives/*
 dist/
+npm/dist/
 php-*
 completion
 

Makefile

@@ -155,3 +155,18 @@ vendor-snapshot: check-vendor .goreleaser.vendor.yaml goreleaser internal/legacy
 .PHONY: goreleaser-check
 goreleaser-check:  goreleaser ## Check the goreleaser configs
 	PHP_VERSION=$(PHP_VERSION) goreleaser check --config=.goreleaser.yaml
+
+# ----- npm distribution -----
+# See npm/README.md.
+
+.PHONY: npm-pack
+npm-pack: ## Build npm tarballs from existing GoReleaser archives in dist/
+	bash npm/scripts/build.sh
+
+.PHONY: npm-publish
+npm-publish: ## Publish npm tarballs (requires npm auth). NPM_TAG=latest|next, DRY_RUN=1 to dry-run
+	bash npm/scripts/publish.sh
+
+.PHONY: npm-clean
+npm-clean: ## Remove npm/dist working directory
+	rm -rf npm/dist

README.md

@@ -37,6 +37,7 @@ The installer is configurable using the following environment variables:
 * `INSTALL_METHOD` - force a specific installation method, possible values are `brew` and `raw`
 * `INSTALL_DIR` - the installation directory for the `raw` installation method, for example you can use `INSTALL_DIR=$HOME/.local/bin` for a single user installation
 * `VERSION` - the version of the CLI to install, if you need a version other than the latest one
+* `INSTALL_NO_COMPLETION` - set to skip installing shell completion (the installer would otherwise run `upsun completion install` after the `raw` install path on bash and zsh)
 
 #### Installation configuration examples
 

commands/completion.go

@@ -2,49 +2,209 @@ package commands
 
 import (
 	"bytes"
+	"context"
 	"fmt"
+	"io"
+	"os"
 	"path/filepath"
 	"strings"
 
 	"github.com/spf13/cobra"
 
 	"github.com/upsun/cli/internal/config"
+	"github.com/upsun/cli/internal/file"
+)
+
+const (
+	shellBash = "bash"
+	shellZsh  = "zsh"
 )
 
 func newCompletionCommand(cnf *config.Config) *cobra.Command {
-	return &cobra.Command{
+	cmd := &cobra.Command{
 		Use:           "completion",
 		Short:         "Print the completion script for your shell",
 		Args:          cobra.MaximumNArgs(1),
 		SilenceErrors: true,
 		Run: func(cmd *cobra.Command, args []string) {
-			// The legacy 5.x CLI uses Symfony's native completion command.
-			completionArgs := []string{"completion"}
+			shell := ""
 			if len(args) > 0 {
-				completionArgs = append(completionArgs, args[0])
+				shell = args[0]
 			}
-			var b bytes.Buffer
-			c := makeLegacyCLIWrapper(cnf, &b, cmd.ErrOrStderr(), cmd.InOrStdin())
-
-			if err := c.Exec(cmd.Context(), completionArgs...); err != nil {
+			script, err := generateCompletionScript(cmd.Context(), cnf, shell, cmd.ErrOrStderr(), cmd.InOrStdin())
+			if err != nil {
 				exitWithError(err)
 			}
+			fmt.Fprintln(cmd.OutOrStdout(), script)
+		},
+	}
+	cmd.AddCommand(newCompletionInstallCommand(cnf))
+	return cmd
+}
+
+// generateCompletionScript runs the legacy CLI's completion command and
+// rewrites references to the Phar so the script invokes the wrapper binary.
+func generateCompletionScript(
+	ctx context.Context, cnf *config.Config, shell string, stderr io.Writer, stdin io.Reader,
+) (string, error) {
+	completionArgs := []string{"completion"}
+	if shell != "" {
+		completionArgs = append(completionArgs, shell)
+	}
+	var b bytes.Buffer
+	c := makeLegacyCLIWrapper(cnf, &b, stderr, stdin)
+	if err := c.Exec(ctx, completionArgs...); err != nil {
+		return "", err
+	}
+	pharPath, err := c.PharPath()
+	if err != nil {
+		return "", err
+	}
+	return strings.ReplaceAll(
+		strings.ReplaceAll(
+			b.String(),
+			pharPath,
+			cnf.Application.Executable,
+		),
+		filepath.Base(pharPath),
+		cnf.Application.Executable,
+	), nil
+}
+
+func newCompletionInstallCommand(cnf *config.Config) *cobra.Command {
+	var (
+		shellFlag string
+		pathFlag  string
+		printPath bool
+	)
+	cmd := &cobra.Command{
+		Use:   "install [shell]",
+		Short: "Install the shell completion script",
+		Long: `Install the shell completion script to the standard location for the detected shell.
+
+Supported shells: bash, zsh.
+
+The shell is detected from the SHELL environment variable. Override it with the
+--shell flag or by passing a positional argument.`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			shell := shellFlag
+			if shell == "" && len(args) > 0 {
+				shell = args[0]
+			}
+			if shell == "" {
+				shell = detectShell()
+			}
+			if shell == "" {
+				return fmt.Errorf("could not detect shell from $SHELL; pass the shell as an argument or via --shell")
+			}
+			switch shell {
+			case shellBash, shellZsh:
+			default:
+				return fmt.Errorf("unsupported shell %q (supported: bash, zsh)", shell)
+			}
+
+			target := pathFlag
+			if target == "" {
+				t, err := defaultCompletionPath(cnf.Application.Executable, shell)
+				if err != nil {
+					return err
+				}
+				target = t
+			}
+
+			if printPath {
+				fmt.Fprintln(cmd.OutOrStdout(), target)
+				return nil
+			}
 
-			pharPath, err := c.PharPath()
+			script, err := generateCompletionScript(cmd.Context(), cnf, shell, cmd.ErrOrStderr(), cmd.InOrStdin())
 			if err != nil {
-				exitWithError(err)
+				return err
+			}
+
+			if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+				return fmt.Errorf("failed to create %s: %w", filepath.Dir(target), err)
+			}
+			// Completion scripts must be world-readable so other users on multi-user
+			// systems can source them; they contain no secrets.
+			if err := file.Write(target, []byte(script), 0o644); err != nil {
+				return fmt.Errorf("failed to write %s: %w", target, err)
 			}
 
-			completions := strings.ReplaceAll(
-				strings.ReplaceAll(
-					b.String(),
-					pharPath,
-					cnf.Application.Executable,
-				),
-				filepath.Base(pharPath),
-				cnf.Application.Executable,
-			)
-			fmt.Fprintln(cmd.OutOrStdout(), completions)
+			fmt.Fprintf(cmd.OutOrStdout(), "Installed %s completion at %s\n", shell, target)
+			if note := postInstallNote(shell, target); note != "" {
+				fmt.Fprintln(cmd.OutOrStdout(), note)
+			}
+			return nil
 		},
 	}
+	cmd.Flags().StringVar(&shellFlag, "shell", "", "Shell to install completion for (bash or zsh)")
+	cmd.Flags().StringVar(&pathFlag, "path", "", "Path to write the completion file (overrides the default)")
+	cmd.Flags().BoolVar(&printPath, "print-path", false, "Print the target path without installing")
+	return cmd
+}
+
+// detectShell returns "bash" or "zsh" if $SHELL points at one of them, or "" otherwise.
+func detectShell() string {
+	sh := os.Getenv("SHELL")
+	if sh == "" {
+		return ""
+	}
+	switch filepath.Base(sh) {
+	case shellBash:
+		return shellBash
+	case shellZsh:
+		return shellZsh
+	}
+	return ""
+}
+
+// defaultCompletionPath returns the standard install location for the given shell,
+// matching what the deb/rpm/apk packages and Homebrew formula already use.
+func defaultCompletionPath(binary, shell string) (string, error) {
+	const (
+		systemBashDir = "/etc/bash_completion.d"
+		systemZshDir  = "/usr/local/share/zsh/site-functions"
+	)
+	isRoot := os.Geteuid() == 0
+	switch shell {
+	case shellBash:
+		if isRoot {
+			return filepath.Join(systemBashDir, binary), nil
+		}
+		dataHome := os.Getenv("XDG_DATA_HOME")
+		if dataHome == "" {
+			home, err := os.UserHomeDir()
+			if err != nil {
+				return "", fmt.Errorf("could not determine home directory: %w", err)
+			}
+			dataHome = filepath.Join(home, ".local", "share")
+		}
+		return filepath.Join(dataHome, "bash-completion", "completions", binary), nil
+	case shellZsh:
+		if isRoot {
+			return filepath.Join(systemZshDir, "_"+binary), nil
+		}
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("could not determine home directory: %w", err)
+		}
+		return filepath.Join(home, ".zsh", "completions", "_"+binary), nil
+	}
+	return "", fmt.Errorf("unsupported shell %q", shell)
+}
+
+// postInstallNote returns shell-specific instructions printed after a successful install.
+func postInstallNote(shell, target string) string {
+	switch shell {
+	case shellZsh:
+		dir := filepath.Dir(target)
+		return fmt.Sprintf("\nIf %[1]s is not already in your $fpath, add this to your ~/.zshrc:\n\n"+
+			"  fpath+=(%[1]s)\n  autoload -U compinit && compinit\n\n"+
+			"Then restart your shell, or run: exec zsh", dir)
+	case shellBash:
+		return "\nRestart your shell or run: source " + target
+	}
+	return ""
 }

commands/completion_test.go

@@ -0,0 +1,64 @@
+package commands
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestDetectShell(t *testing.T) {
+	cases := []struct {
+		shell string
+		want  string
+	}{
+		{"/bin/bash", "bash"},
+		{"/usr/local/bin/zsh", "zsh"},
+		{"/usr/bin/fish", ""},
+		{"", ""},
+	}
+	for _, c := range cases {
+		t.Run(c.shell, func(t *testing.T) {
+			t.Setenv("SHELL", c.shell)
+			assert.Equal(t, c.want, detectShell())
+		})
+	}
+}
+
+func TestDefaultCompletionPath(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("non-root user paths only")
+	}
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("XDG_DATA_HOME", "")
+
+	cases := []struct {
+		shell string
+		want  string
+	}{
+		{"bash", filepath.Join(home, ".local", "share", "bash-completion", "completions", "upsun")},
+		{"zsh", filepath.Join(home, ".zsh", "completions", "_upsun")},
+	}
+	for _, c := range cases {
+		t.Run(c.shell, func(t *testing.T) {
+			got, err := defaultCompletionPath("upsun", c.shell)
+			assert.NoError(t, err)
+			assert.Equal(t, c.want, got)
+		})
+	}
+
+	t.Run("xdg override", func(t *testing.T) {
+		xdg := filepath.Join(home, "xdg")
+		t.Setenv("XDG_DATA_HOME", xdg)
+		got, err := defaultCompletionPath("upsun", "bash")
+		assert.NoError(t, err)
+		assert.Equal(t, filepath.Join(xdg, "bash-completion", "completions", "upsun"), got)
+	})
+
+	t.Run("unsupported shell", func(t *testing.T) {
+		_, err := defaultCompletionPath("upsun", "fish")
+		assert.Error(t, err)
+	})
+}

installer.sh

@@ -24,6 +24,9 @@ set -eu
 # GitHub token check
 : "${GITHUB_TOKEN:=}"
 
+# Set to skip the post-install `upsun completion install` step
+: "${INSTALL_NO_COMPLETION:=}"
+
 # CI specifics
 : "${CI:=}"
 : "${BUILD_NUMBER:=}"
@@ -623,6 +626,30 @@ is_ci() {
     fi
 }
 
+install_completion() {
+    # apt/yum/apk/homebrew already drop completion files; only the raw path needs this.
+    if [ "raw" != "${INSTALL_METHOD}" ]; then
+        return
+    fi
+
+    if [ ! -z "${INSTALL_NO_COMPLETION}" ] || is_ci; then
+        return
+    fi
+
+    case "$(basename "${SHELL:-}")" in
+        bash|zsh) ;;
+        *) return ;;
+    esac
+
+    output "\nInstalling shell completion" "heading"
+    # $binary is either "upsun" (when dir_bin is in PATH) or a full path
+    # (set by check_directories), so it works as a command in both cases.
+    if ! call_user "$binary completion install"; then
+        add_footer_note "  ⚠ Could not install shell completion" \
+            "    Run later with: $binary completion install"
+    fi
+}
+
 install_raw() {
     # Start downloading the right version
     output "\nDownloading the $vendor_name CLI" "heading"
@@ -685,4 +712,5 @@ elif [ "apt" = "${INSTALL_METHOD}" ] || [ "yum" = "${INSTALL_METHOD}" ] || [ "ap
     fi
 fi
 install
+install_completion
 outro