feat: scope docker-options to specific procfile processes

Adds a `--process` flag (repeatable) to docker-options:add/remove/clear/list and the new docker-options:list subcommand for querying a single process+phase pair. Process scoping is supported only for the deploy phase since build runs once per app and run covers ad-hoc commands and cron tasks where no Procfile process type is available. Storage moves from `$DOKKU_ROOT/$APP/DOCKER_OPTIONS_*` files to property lists under `/var/lib/dokku/config/docker-options/$APP/{processType}.{phase}`, with `_default_` as the sentinel for app-wide options. The install trigger migrates pre-existing DOCKER_OPTIONS_* files into property lists once and renames them to `.migrated`; a global marker makes re-runs strictly no-op. The legacy docker-args-{build,deploy,run} bash triggers are reimplemented in Go alongside a new docker-args-process-deploy trigger that surfaces per-process options to the scheduler. The :report command exposes one dynamic flag per configured `process.deploy` pair (e.g. `--docker-options-deploy.web`) and supports `--format json`. There is no `--global` flag; omitting `--process` keeps the historical default behaviour, since `--global` elsewhere in dokku means "across all apps". Closes #2441.

plugins/docker-options/internal-functions.go

@@ -3,11 +3,31 @@ package dockeroptions
 import (
 	"errors"
 	"fmt"
+	"path/filepath"
 	"strings"
+
+	"github.com/dokku/dokku/plugins/common"
 )
 
 var availablePhases = []string{"build", "deploy", "run"}
 
+// processScopedPhases lists the phases that may be scoped via --process.
+// Only deploy is scoped: build runs once per app (no process-type concept) and
+// run is invoked for ad-hoc commands and cron tasks where the caller does not
+// supply a Procfile process type.
+var processScopedPhases = map[string]bool{
+	"deploy": true,
+}
+
+func isValidPhase(phase string) bool {
+	for _, p := range availablePhases {
+		if p == phase {
+			return true
+		}
+	}
+	return false
+}
+
 func parsePhases(phasesArg string) ([]string, error) {
 	if phasesArg == "" {
 		return nil, nil
@@ -15,14 +35,7 @@ func parsePhases(phasesArg string) ([]string, error) {
 
 	phases := strings.Split(phasesArg, ",")
 	for _, phase := range phases {
-		valid := false
-		for _, allowed := range availablePhases {
-			if phase == allowed {
-				valid = true
-				break
-			}
-		}
-		if !valid {
+		if !isValidPhase(phase) {
 			return nil, fmt.Errorf("Phase(s) must be one of [%s]", strings.Join(availablePhases, " "))
 		}
 	}
@@ -30,16 +43,55 @@ func parsePhases(phasesArg string) ([]string, error) {
 	return phases, nil
 }
 
-// ErrIfReservedFlagsUsed returns a not-yet-implemented error when --process or --global are passed.
-// Both flags are reserved for the upcoming process-scoped docker options work (issue #2441).
-func ErrIfReservedFlagsUsed(processes []string, global bool) error {
-	if len(processes) == 0 && !global {
+// ValidateProcessFlag rejects invalid combinations of --process and the
+// supplied phases. When processes is empty the call applies to the default
+// scope and any phase is allowed.
+func ValidateProcessFlag(processes []string, phases []string) error {
+	if len(processes) == 0 {
 		return nil
 	}
 
-	if len(processes) > 0 && global {
-		return errors.New("--process and --global flags are mutually exclusive")
+	for _, processType := range processes {
+		if processType == "" {
+			return errors.New("--process value must not be empty")
+		}
+		if processType == DefaultProcessType {
+			return fmt.Errorf("%q is reserved and cannot be used as a --process value", DefaultProcessType)
+		}
 	}
 
-	return errors.New("--process and --global flags are reserved for a future release and not yet implemented")
+	for _, phase := range phases {
+		if !processScopedPhases[phase] {
+			return fmt.Errorf("--process is only supported for the deploy phase, got %q", phase)
+		}
+	}
+
+	return nil
+}
+
+// WarnIfProcessNotInProcfile emits a warning (without failing) when the named
+// process type is not present in the app's current Procfile. The check is
+// best-effort: if the Procfile or procfile-util are unavailable, the function
+// returns silently.
+func WarnIfProcessNotInProcfile(appName, processType string) {
+	procfilePath := filepath.Join(common.GetAppDataDirectory("ps", appName), "Procfile")
+	if !common.FileExists(procfilePath) {
+		return
+	}
+
+	result, err := common.CallExecCommand(common.ExecCommandInput{
+		Command: "procfile-util",
+		Args:    []string{"list", "--procfile", procfilePath},
+	})
+	if err != nil || result.ExitCode != 0 {
+		return
+	}
+
+	for _, line := range strings.Split(strings.TrimSpace(result.StdoutContents()), "\n") {
+		if strings.TrimSpace(line) == processType {
+			return
+		}
+	}
+
+	common.LogWarn(fmt.Sprintf("Process type %q is not declared in the Procfile for %s", processType, appName))
 }