feat(cli): consolidate command surface and operation plans

Flatten Cobra command entrypoints, add structured plan and confirmation contracts, harden pgBackRest/PITR/log/fork/do workflows, and move command glue into cli/internal helpers.

Author: Vonng

cli/do/commands.go

@@ -0,0 +1,170 @@
+package do
+
+import (
+	"fmt"
+	"net"
+	"strconv"
+	"strings"
+)
+
+// RunPlaybooks runs a sequence of ansible playbook commands.
+func RunPlaybooks(inventory string, commands [][]string) error {
+	for _, command := range commands {
+		if err := RunPlaybook(inventory, command); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func BuildPgsqlAddCommands(cluster string, ips []string) ([][]string, error) {
+	if cluster == "" {
+		return nil, fmt.Errorf("pgsql cluster is required")
+	}
+	if len(ips) == 0 {
+		return [][]string{{"pgsql.yml", "-l", cluster}}, nil
+	}
+	target, exists, err := buildPgsqlInstancePatterns(cluster, ips)
+	if err != nil {
+		return nil, err
+	}
+	return [][]string{
+		{"pgsql.yml", "-l", target},
+		{"pgsql.yml", "-l", exists, "-t", "pg_service"},
+	}, nil
+}
+
+func BuildPgsqlRmCommands(cluster string, ips []string, uninstall bool) ([][]string, error) {
+	if cluster == "" {
+		return nil, fmt.Errorf("pgsql cluster is required")
+	}
+	selector := cluster
+	if len(ips) > 0 {
+		target, _, err := buildPgsqlInstancePatterns(cluster, ips)
+		if err != nil {
+			return nil, err
+		}
+		selector = target
+	}
+	command := []string{"pgsql-rm.yml", "-l", selector}
+	if uninstall {
+		command = append(command, "-e", "pg_rm_pkg=true")
+	}
+	return [][]string{command}, nil
+}
+
+func BuildNodeAddCommand(selectors []string) ([]string, error) {
+	selector, err := joinSelectors(selectors)
+	if err != nil {
+		return nil, err
+	}
+	return []string{"node.yml", "-l", selector}, nil
+}
+
+func BuildNodeRmCommand(selectors []string) ([]string, error) {
+	selector, err := joinSelectors(selectors)
+	if err != nil {
+		return nil, err
+	}
+	return []string{"node-rm.yml", "-l", selector}, nil
+}
+
+func BuildNodeRepoCommand(args []string) ([]string, error) {
+	if len(args) > 2 {
+		return nil, fmt.Errorf("node-repo accepts at most selector and module")
+	}
+	command := []string{"node.yml", "-t", "node_repo"}
+	if len(args) >= 1 && args[0] != "" {
+		command = append(command, "-l", args[0])
+	}
+	if len(args) == 2 && args[1] != "" {
+		command = append(command, "-e", fmt.Sprintf("node_repo_modules=%s", args[1]))
+	}
+	return command, nil
+}
+
+func BuildRedisAddCommands(selector string, ports []string) ([][]string, error) {
+	if selector == "" {
+		return nil, fmt.Errorf("redis selector is required")
+	}
+	if len(ports) == 0 {
+		return [][]string{{"redis.yml", "-l", selector}}, nil
+	}
+	if !isIPv4(selector) {
+		return nil, fmt.Errorf("redis instance operations require an IP selector")
+	}
+	commands := make([][]string, 0, len(ports))
+	for _, port := range ports {
+		if err := validateRedisPort(port); err != nil {
+			return nil, err
+		}
+		commands = append(commands, []string{"redis.yml", "-l", selector, "-e", fmt.Sprintf("redis_port=%s", port)})
+	}
+	return commands, nil
+}
+
+func BuildRedisRmCommands(selector string, ports []string, uninstall bool) ([][]string, error) {
+	if selector == "" {
+		return nil, fmt.Errorf("redis selector is required")
+	}
+	if len(ports) == 0 {
+		command := []string{"redis-rm.yml", "-l", selector}
+		if uninstall {
+			command = append(command, "-e", "redis_rm_pkg=true")
+		}
+		return [][]string{command}, nil
+	}
+	if !isIPv4(selector) {
+		return nil, fmt.Errorf("redis instance operations require an IP selector")
+	}
+	if uninstall {
+		return nil, fmt.Errorf("redis package uninstall is only supported for node or cluster removal")
+	}
+	commands := make([][]string, 0, len(ports))
+	for _, port := range ports {
+		if err := validateRedisPort(port); err != nil {
+			return nil, err
+		}
+		command := []string{"redis-rm.yml", "-l", selector, "-e", fmt.Sprintf("redis_port=%s", port)}
+		commands = append(commands, command)
+	}
+	return commands, nil
+}
+
+func buildPgsqlInstancePatterns(cluster string, ips []string) (string, string, error) {
+	target := "&" + cluster
+	existing := cluster
+	for _, ip := range ips {
+		if !isIPv4(ip) {
+			return "", "", fmt.Errorf("invalid ip address: %s", ip)
+		}
+		target = ip + "," + target
+		existing += ",!" + ip
+	}
+	return target, existing, nil
+}
+
+func joinSelectors(selectors []string) (string, error) {
+	if len(selectors) == 0 {
+		return "", fmt.Errorf("selector is required")
+	}
+	for _, selector := range selectors {
+		if selector == "" {
+			return "", fmt.Errorf("selector cannot be empty")
+		}
+	}
+	return strings.Join(selectors, ","), nil
+}
+
+func validateRedisPort(port string) error {
+	n, err := strconv.Atoi(port)
+	if err != nil || n < 1024 || n > 65535 {
+		return fmt.Errorf("invalid redis port: %s", port)
+	}
+	return nil
+}
+
+func isIPv4(value string) bool {
+	ip := net.ParseIP(value)
+	return ip != nil && ip.To4() != nil
+}

cli/do/do_test.go

@@ -0,0 +1,81 @@
+package do
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestBuildPgsqlAddCommandsAppendsReplicaAndRefreshesService(t *testing.T) {
+	commands, err := BuildPgsqlAddCommands("pg-test", []string{"10.10.10.12", "10.10.10.13"})
+	if err != nil {
+		t.Fatalf("BuildPgsqlAddCommands() error = %v", err)
+	}
+
+	want := [][]string{
+		{"pgsql.yml", "-l", "10.10.10.13,10.10.10.12,&pg-test"},
+		{"pgsql.yml", "-l", "pg-test,!10.10.10.12,!10.10.10.13", "-t", "pg_service"},
+	}
+	if !reflect.DeepEqual(commands, want) {
+		t.Fatalf("BuildPgsqlAddCommands() = %#v, want %#v", commands, want)
+	}
+}
+
+func TestBuildPgsqlRmCommandsRemovesReplicaInsteadOfCluster(t *testing.T) {
+	commands, err := BuildPgsqlRmCommands("pg-test", []string{"10.10.10.13"}, true)
+	if err != nil {
+		t.Fatalf("BuildPgsqlRmCommands() error = %v", err)
+	}
+
+	want := [][]string{
+		{"pgsql-rm.yml", "-l", "10.10.10.13,&pg-test", "-e", "pg_rm_pkg=true"},
+	}
+	if !reflect.DeepEqual(commands, want) {
+		t.Fatalf("BuildPgsqlRmCommands() = %#v, want %#v", commands, want)
+	}
+}
+
+func TestBuildNodeCommandsAcceptMultipleSelectors(t *testing.T) {
+	addCommand, err := BuildNodeAddCommand([]string{"10.10.10.10", "10.10.10.11"})
+	if err != nil {
+		t.Fatalf("BuildNodeAddCommand() error = %v", err)
+	}
+	if want := []string{"node.yml", "-l", "10.10.10.10,10.10.10.11"}; !reflect.DeepEqual(addCommand, want) {
+		t.Fatalf("BuildNodeAddCommand() = %#v, want %#v", addCommand, want)
+	}
+
+	rmCommand, err := BuildNodeRmCommand([]string{"pg-test", "10.10.10.11"})
+	if err != nil {
+		t.Fatalf("BuildNodeRmCommand() error = %v", err)
+	}
+	if want := []string{"node-rm.yml", "-l", "pg-test,10.10.10.11"}; !reflect.DeepEqual(rmCommand, want) {
+		t.Fatalf("BuildNodeRmCommand() = %#v, want %#v", rmCommand, want)
+	}
+}
+
+func TestBuildNodeRepoCommandRejectsTooManyArgs(t *testing.T) {
+	if _, err := BuildNodeRepoCommand([]string{"pg-test", "node", "extra"}); err == nil {
+		t.Fatal("BuildNodeRepoCommand() should reject more than two arguments")
+	}
+}
+
+func TestBuildRedisCommandsValidatePortsAndUninstall(t *testing.T) {
+	if _, err := BuildRedisAddCommands("redis-test", []string{"6379"}); err == nil {
+		t.Fatal("BuildRedisAddCommands() should require an IP selector when ports are specified")
+	}
+	if _, err := BuildRedisAddCommands("10.10.10.10", []string{"80"}); err == nil {
+		t.Fatal("BuildRedisAddCommands() should reject invalid redis port")
+	}
+
+	commands, err := BuildRedisRmCommands("10.10.10.10", nil, true)
+	if err != nil {
+		t.Fatalf("BuildRedisRmCommands() error = %v", err)
+	}
+	want := [][]string{{"redis-rm.yml", "-l", "10.10.10.10", "-e", "redis_rm_pkg=true"}}
+	if !reflect.DeepEqual(commands, want) {
+		t.Fatalf("BuildRedisRmCommands() = %#v, want %#v", commands, want)
+	}
+
+	if _, err := BuildRedisRmCommands("10.10.10.10", []string{"6379"}, true); err == nil {
+		t.Fatal("BuildRedisRmCommands() should reject --uninstall for per-port removal")
+	}
+}

cli/patroni/config_plan.go

@@ -0,0 +1,77 @@
+package patroni
+
+import (
+	"strings"
+
+	"pig/internal/output"
+)
+
+// BuildConfigPlan returns a side-effect-free primitive plan for Patroni DCS config changes.
+func BuildConfigPlan(action string, kvPairs []string) *output.Plan {
+	scope := "patroni"
+	setFlag := "-s"
+	if action == "pg" {
+		scope = "postgresql.parameters"
+		setFlag = "-p"
+	}
+
+	normalized := normalizeConfigPairs(kvPairs)
+	pairDetail := strings.Join(normalized, ", ")
+	if pairDetail == "" {
+		pairDetail = "no key=value pairs provided"
+	}
+
+	return &output.Plan{
+		Command:      buildConfigCommand(action, normalized),
+		Boundary:     "pt:dcs-config",
+		Confirmation: "recommended",
+		Actions: []output.Action{
+			{Step: 1, Description: "Validate key=value pairs for Patroni dynamic configuration"},
+			{Step: 2, Description: "Apply DCS config changes with patronictl edit-config --force"},
+			{Step: 3, Description: "Report whether PostgreSQL reload or restart should be considered"},
+		},
+		Affects: []output.Resource{
+			{Type: "dcs_config", Name: scope, Impact: "update", Detail: pairDetail},
+		},
+		Expected: "Patroni dynamic configuration is updated in DCS; members apply changes according to Patroni/PostgreSQL rules",
+		Risks: []string{
+			"DCS configuration mistakes can affect every cluster member.",
+			"Some PostgreSQL parameters require reload or restart before they take effect.",
+		},
+		Preconditions: []output.Check{
+			{Name: "config pairs", Status: "planned", Detail: pairDetail},
+			{Name: "patroni config", Status: "required", Detail: DefaultConfigPath},
+			{Name: "patronictl command", Status: "planned", Detail: "edit-config --force " + setFlag},
+		},
+		Verifications: []output.Check{
+			{Name: "show config", Status: "manual", Detail: "pig pt config show"},
+			{Name: "member state", Status: "manual", Detail: "pig pt list"},
+		},
+		NextActions: []output.NextAction{
+			{Command: "pig pt reload", Reason: "reload PostgreSQL configuration after DCS parameter changes", Required: false},
+			{Command: "pig pt restart --pending", Reason: "restart members only if Patroni marks pending restart", Required: false},
+			{Command: "pig pt config show", Reason: "verify DCS config after change", Required: false},
+		},
+	}
+}
+
+func buildConfigCommand(action string, kvPairs []string) string {
+	parts := []string{"pig", "pt", "config", action}
+	parts = append(parts, kvPairs...)
+	parts = append(parts, "--plan")
+	return strings.Join(parts, " ")
+}
+
+func normalizeConfigPairs(kvPairs []string) []string {
+	if len(kvPairs) == 0 {
+		return nil
+	}
+	pairs := make([]string, 0, len(kvPairs))
+	for _, pair := range kvPairs {
+		pair = strings.TrimSpace(pair)
+		if pair != "" {
+			pairs = append(pairs, pair)
+		}
+	}
+	return pairs
+}