Add esc env settings command with get and set subcommands (#595)

* Add `esc env settings` command with `get` and `set` subcommands

 Fixes pulumi/pulumi-service#33364

 Adds `esc env settings get` and `esc env settings set` commands to manage environment settings.

 Currently supports the `deletion-protected` setting, which prevents environments from being deleted when set to `true`. The default remains `false` for new environments.

 ### Usage

 ```bash
 # Get all settings
 $ esc env settings get myorg/myproject/prod
 deletion-protected true

 # Get a specific setting
 $ esc env settings get myorg/myproject/prod deletion-protected
 true

 # Set deletion protection
 $ esc env settings set myorg/myproject/prod deletion-protected true
 true
 ```

 The `get` command returns all settings in space-separated format when no setting name is provided, or just the value when a specific setting is requested. The `set` command works with single key-value pairs.

 ### Implementation

 The implementation uses Go generics to keep setting implementations fully typed—each setting implements `Setting[T]` with its concrete type (e.g., `bool`). Settings are wrapped with `settingBox[T]` at registration time to convert them to `UntypedSetting` for homogeneous storage in the registry map.

 ### Test Script

 The following script tests the deletion protection functionality end-to-end:

 ```bash
 #!/usr/bin/env bash

 set -ex

 # Test script for environment settings (deletion protection)
 #
 # Required environment variables:
 #   PULUMI_ACCESS_TOKEN - Access token for the review stack
 #   PULUMI_API          - Backend API URL (e.g., https://api-fnune-review.review-stacks.pulumi-dev.io)
 #
 # Usage:
 #   export PULUMI_ACCESS_TOKEN="your-token-here"
 #   export PULUMI_API="https://api-fnune-review.review-stacks.pulumi-dev.io"
 #   ./esc login $PULUMI_API
 #   ./test.sh
 #
 # You can test with any of these environments from the review stack:
 #   pulumi_local/2025-08-18-test-nocode1/dev
 #   pulumi_local/csharp-documented-test-no-code/dev
 #   pulumi_local/fearless-copper-fossa-nocode4/dev
 #   pulumi_local/innovative-rhenium-pangolin/dev
 #   pulumi_local/inspiring-ruby-quokka-nocode3/dev

 if [ -z "$PULUMI_ACCESS_TOKEN" ]; then
   echo "Error: PULUMI_ACCESS_TOKEN is not set"
   exit 1
 fi

 if [ -z "$PULUMI_API" ]; then
   echo "Error: PULUMI_API is not set"
   exit 1
 fi

 ENV_NAME="${1:-pulumi_local/2025-08-18-test-nocode1/dev}"

 echo "Building esc CLI..."
 go build -o ./esc ./cmd/esc

 echo ""
 echo "Testing environment settings commands with: $ENV_NAME"
 echo "Backend: $PULUMI_API"
 echo ""

 echo "=== Test 1: Get all settings ==="
 ./esc env settings get "$ENV_NAME"
 echo ""

 echo "=== Test 2: Get deletion-protected setting ==="
 ./esc env settings get "$ENV_NAME" deletion-protected
 echo ""

 echo "=== Test 3: Enable deletion protection ==="
 ./esc env settings set "$ENV_NAME" deletion-protected true
 echo ""

 echo "=== Test 4: Verify deletion protection is enabled ==="
 ./esc env settings get "$ENV_NAME" deletion-protected
 echo ""

 echo "=== Test 5: Attempt to delete protected environment (should fail) ==="
 if ./esc env rm "$ENV_NAME" --yes 2>&1 | tee /dev/stderr | grep -q "deletion protection is enabled"; then
   echo "✓ Deletion correctly blocked"
 else
   echo "✗ Deletion should have been blocked"
   exit 1
 fi
 echo ""

 echo "=== Test 6: Disable deletion protection ==="
 ./esc env settings set "$ENV_NAME" deletion-protected false
 echo ""

 echo "=== Test 7: Verify deletion protection is disabled ==="
 ./esc env settings get "$ENV_NAME" deletion-protected
 echo ""

 echo "=== Test 8: Test invalid value (should fail) ==="
 if ./esc env settings set "$ENV_NAME" deletion-protected invalid 2>&1 | tee /dev/stderr | grep -q "expected true or false"; then
   echo "✓ Invalid value correctly rejected"
 else
   echo "✗ Invalid value should have been rejected"
   exit 1
 fi
 echo ""

 echo "=== Test 9: Test unknown setting (should fail) ==="
 if ./esc env settings get "$ENV_NAME" unknown-setting 2>&1 | tee /dev/stderr | grep -q "unknown setting name"; then
   echo "✓ Unknown setting correctly rejected"
 else
   echo "✗ Unknown setting should have been rejected"
   exit 1
 fi
 echo ""

 echo "All tests passed! ✓"
 ```

* Add minimal enforcement of interface compatibility with env set/get

* Stop masking 409s unrelated to del protection, add comment about parsing

Author: fnune

CHANGELOG_PENDING.md

@@ -1,6 +1,11 @@
 ### Improvements
 
 - Added support for Open Approvals [#592](https://github.com/pulumi/esc/pull/592)
+- Added deletion protection for environments:
+  - Use `esc env settings set [<org-name>/][<project-name>/]<environment-name> deletion-protected true` to enable deletion protection
+  - Use `esc env settings get [<org-name>/][<project-name>/]<environment-name> [deletion-protected]` to check the current status
+  - When enabled, environments cannot be deleted until protection is disabled
+  - Deletion protection is disabled by default for new environments
 
 ### Bug Fixes
 

cmd/esc/cli/cli_test.go

@@ -272,9 +272,10 @@ type testEnvironmentRevision struct {
 }
 
 type testEnvironment struct {
-	revisions    []*testEnvironmentRevision
-	revisionTags map[string]int
-	tags         map[string]string
+	revisions         []*testEnvironmentRevision
+	revisionTags      map[string]int
+	tags              map[string]string
+	deletionProtected bool
 }
 
 func (env *testEnvironment) latest() *testEnvironmentRevision {
@@ -737,9 +738,13 @@ func (c *testPulumiClient) SubmitChangeRequest(
 
 func (c *testPulumiClient) DeleteEnvironment(ctx context.Context, orgName, projectName, envName string) error {
 	name := path.Join(orgName, projectName, envName)
-	if _, ok := c.environments[name]; !ok {
+	env, ok := c.environments[name]
+	if !ok {
 		return errors.New("not found")
 	}
+	if env.deletionProtected {
+		return &apitype.ErrorResponse{Code: http.StatusConflict, Message: "environment is deletion protected"}
+	}
 	delete(c.environments, name)
 	return nil
 }
@@ -1196,6 +1201,40 @@ func (c *testPulumiClient) CreateEnvironmentOpenRequest(
 	}, nil
 }
 
+func (c *testPulumiClient) GetEnvironmentSettings(
+	ctx context.Context,
+	orgName string,
+	projectName string,
+	envName string,
+) (*client.EnvironmentSettings, error) {
+	name := path.Join(orgName, projectName, envName)
+	env, ok := c.environments[name]
+	if !ok {
+		return nil, errors.New("not found")
+	}
+	return &client.EnvironmentSettings{
+		DeletionProtected: env.deletionProtected,
+	}, nil
+}
+
+func (c *testPulumiClient) PatchEnvironmentSettings(
+	ctx context.Context,
+	orgName string,
+	projectName string,
+	envName string,
+	req client.PatchEnvironmentSettingsRequest,
+) error {
+	name := path.Join(orgName, projectName, envName)
+	env, ok := c.environments[name]
+	if !ok {
+		return errors.New("not found")
+	}
+	if req.DeletionProtected != nil {
+		env.deletionProtected = *req.DeletionProtected
+	}
+	return nil
+}
+
 type testExec struct {
 	fs       testFS
 	environ  map[string]string

cmd/esc/cli/client/apitype.go

@@ -241,3 +241,11 @@ type GetDefaultOrganizationResponse struct {
 	// Can be an empty string, if the user is a member of no organizations
 	Organization string `json:"gitHubLogin"`
 }
+
+type EnvironmentSettings struct {
+	DeletionProtected bool `json:"deletionProtected"`
+}
+
+type PatchEnvironmentSettingsRequest struct {
+	DeletionProtected *bool `json:"deletionProtected,omitempty"`
+}

cmd/esc/cli/client/client.go

@@ -387,6 +387,23 @@ type Client interface {
 		grantExpirationSeconds int,
 		accessDurationSeconds int,
 	) (*CreateEnvironmentOpenRequestResponse, error)
+
+	// GetEnvironmentSettings returns settings for the given environment.
+	GetEnvironmentSettings(
+		ctx context.Context,
+		orgName string,
+		projectName string,
+		envName string,
+	) (*EnvironmentSettings, error)
+
+	// PatchEnvironmentSettings updates settings for the given environment.
+	PatchEnvironmentSettings(
+		ctx context.Context,
+		orgName string,
+		projectName string,
+		envName string,
+		req PatchEnvironmentSettingsRequest,
+	) error
 }
 
 type client struct {
@@ -1303,6 +1320,32 @@ func (pc *client) CreateEnvironmentOpenRequest(
 	return &resp, nil
 }
 
+func (pc *client) GetEnvironmentSettings(
+	ctx context.Context,
+	orgName string,
+	projectName string,
+	envName string,
+) (*EnvironmentSettings, error) {
+	path := fmt.Sprintf("/api/esc/environments/%v/%v/%v/settings", orgName, projectName, envName)
+	var resp EnvironmentSettings
+	err := pc.restCall(ctx, http.MethodGet, path, nil, nil, &resp)
+	if err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
+func (pc *client) PatchEnvironmentSettings(
+	ctx context.Context,
+	orgName string,
+	projectName string,
+	envName string,
+	req PatchEnvironmentSettingsRequest,
+) error {
+	path := fmt.Sprintf("/api/esc/environments/%v/%v/%v/settings", orgName, projectName, envName)
+	return pc.restCall(ctx, http.MethodPatch, path, nil, req, nil)
+}
+
 type httpCallOptions struct {
 	// RetryPolicy defines the policy for retrying requests by httpClient.Do.
 	//

cmd/esc/cli/env.go

@@ -71,6 +71,7 @@ func newEnvCmd(esc *escCommand) *cobra.Command {
 	cmd.AddCommand(newEnvVersionCmd(env))
 	cmd.AddCommand(newEnvLsCmd(env))
 	cmd.AddCommand(newEnvTagCmd((env)))
+	cmd.AddCommand(newEnvSettingsCmd(env))
 	cmd.AddCommand(newEnvRmCmd(env))
 	cmd.AddCommand(newEnvOpenCmd(env))
 	cmd.AddCommand(newEnvOpenRequestCmd(env))

cmd/esc/cli/env_rm.go

@@ -6,12 +6,15 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/http"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 	"gopkg.in/yaml.v3"
 
 	"github.com/pulumi/esc/syntax/encoding"
+	"github.com/pulumi/pulumi/sdk/v3/go/common/apitype"
 	"github.com/pulumi/pulumi/sdk/v3/go/common/diag/colors"
 	"github.com/pulumi/pulumi/sdk/v3/go/common/resource"
 	"github.com/pulumi/pulumi/sdk/v3/go/common/util/cmdutil"
@@ -64,6 +67,10 @@ func newEnvRmCmd(env *envCommand) *cobra.Command {
 
 				err = env.esc.client.DeleteEnvironment(ctx, ref.orgName, ref.projectName, ref.envName)
 				if err != nil {
+					var errResp *apitype.ErrorResponse
+					if errors.As(err, &errResp) && errResp.Code == http.StatusConflict && strings.Contains(errResp.Message, "protect") {
+						return fmt.Errorf("cannot delete environment: deletion protection is enabled. Disable deletion protection with 'esc env settings set %s deletion-protected false' before deleting", envSlug)
+					}
 					return err
 				}
 

cmd/esc/cli/env_setting_deletion_protected.go

@@ -0,0 +1,40 @@
+// Copyright 2025, Pulumi Corporation.
+
+package cli
+
+import (
+	"fmt"
+
+	"github.com/pulumi/esc/cmd/esc/cli/client"
+)
+
+const settingDeletionProtected settingName = "deletion-protected"
+
+type DeletionProtectedSetting struct{}
+
+func (s *DeletionProtectedSetting) KebabName() string {
+	return "deletion-protected"
+}
+
+func (s *DeletionProtectedSetting) HelpText() string {
+	return "Enable or disable deletion protection"
+}
+
+// ValidateValue accepts only "true" and "false" strings, unlike the general env {get,set} commands
+// which parse YAML and accept broader boolean values like "yes", "no", "on", "off", etc.
+// This restriction maintains compatibility while limiting the accepted subset to a well-defined
+// interface that can be reliably parsed and validated.
+func (s *DeletionProtectedSetting) ValidateValue(raw string) (bool, error) {
+	if raw != "true" && raw != "false" {
+		return false, fmt.Errorf("invalid value for %s: %s (expected true or false)", s.KebabName(), raw)
+	}
+	return raw == "true", nil
+}
+
+func (s *DeletionProtectedSetting) GetValue(settings *client.EnvironmentSettings) bool {
+	return settings.DeletionProtected
+}
+
+func (s *DeletionProtectedSetting) SetValue(req *client.PatchEnvironmentSettingsRequest, value bool) {
+	req.DeletionProtected = &value
+}

cmd/esc/cli/env_setting_deletion_protected_test.go

@@ -0,0 +1,61 @@
+// Copyright 2025, Pulumi Corporation.
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/pulumi/esc/cmd/esc/cli/client"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestDeletionProtectedSetting(t *testing.T) {
+	s := &DeletionProtectedSetting{}
+
+	t.Run("ValidateValue", func(t *testing.T) {
+		t.Run("valid true", func(t *testing.T) {
+			value, err := s.ValidateValue("true")
+			assert.NoError(t, err)
+			assert.Equal(t, true, value)
+		})
+
+		t.Run("valid false", func(t *testing.T) {
+			value, err := s.ValidateValue("false")
+			assert.NoError(t, err)
+			assert.Equal(t, false, value)
+		})
+
+		t.Run("invalid value", func(t *testing.T) {
+			_, err := s.ValidateValue("yes")
+			assert.Error(t, err)
+			assert.Contains(t, err.Error(), "invalid value for deletion-protected")
+		})
+
+		t.Run("case sensitive", func(t *testing.T) {
+			_, err := s.ValidateValue("True")
+			assert.Error(t, err)
+		})
+	})
+
+	t.Run("GetSetValue", func(t *testing.T) {
+		t.Run("true", func(t *testing.T) {
+			req := &client.PatchEnvironmentSettingsRequest{}
+			s.SetValue(req, true)
+			assert.NotNil(t, req.DeletionProtected)
+			assert.True(t, *req.DeletionProtected)
+
+			settings := &client.EnvironmentSettings{DeletionProtected: true}
+			assert.Equal(t, true, s.GetValue(settings))
+		})
+
+		t.Run("false", func(t *testing.T) {
+			req := &client.PatchEnvironmentSettingsRequest{}
+			s.SetValue(req, false)
+			assert.NotNil(t, req.DeletionProtected)
+			assert.False(t, *req.DeletionProtected)
+
+			settings := &client.EnvironmentSettings{DeletionProtected: false}
+			assert.Equal(t, false, s.GetValue(settings))
+		})
+	})
+}

cmd/esc/cli/env_settings.go

@@ -0,0 +1,27 @@
+// Copyright 2025, Pulumi Corporation.
+
+package cli
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func newEnvSettingsCmd(env *envCommand) *cobra.Command {
+	registry := NewEnvSettingsRegistry()
+
+	cmd := &cobra.Command{
+		Use:   "settings",
+		Short: "Manage environment settings",
+		Long: "Manage environment settings\n" +
+			"\n" +
+			"This command manages environment settings such as deletion protection.\n" +
+			"\n" +
+			"Subcommands exist for reading and updating settings.",
+		Args: cobra.NoArgs,
+	}
+
+	cmd.AddCommand(newEnvSettingsGetCmd(env, registry))
+	cmd.AddCommand(newEnvSettingsSetCmd(env, registry))
+
+	return cmd
+}

cmd/esc/cli/env_settings_contract_test.go

@@ -0,0 +1,71 @@
+// Copyright 2025, Pulumi Corporation.
+
+package cli
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSettingsFlagsAreSubsetOfEnvFlags(t *testing.T) {
+	tests := []struct {
+		parent []string
+		subset []string
+	}{
+		{parent: []string{"env", "set"}, subset: []string{"env", "settings", "set"}},
+		{parent: []string{"env", "get"}, subset: []string{"env", "settings", "get"}},
+	}
+
+	esc := New(&Options{})
+
+	for _, tt := range tests {
+		t.Run(tt.subset[len(tt.subset)-1], func(t *testing.T) {
+			parentCmd := findCommand(esc, tt.parent)
+			subsetCmd := findCommand(esc, tt.subset)
+
+			require.NotNil(t, parentCmd)
+			require.NotNil(t, subsetCmd)
+
+			parentFlags := getFlagNames(parentCmd)
+			subsetFlags := getFlagNames(subsetCmd)
+
+			for _, flag := range subsetFlags {
+				assert.Contains(t, parentFlags, flag,
+					"%s has flag --%s which doesn't exist in %s. "+
+						"If this is a deliberate product decision, update or remove this test.",
+					strings.Join(tt.subset, " "), flag, strings.Join(tt.parent, " "))
+			}
+		})
+	}
+}
+
+func getFlagNames(cmd *cobra.Command) []string {
+	var names []string
+	cmd.Flags().VisitAll(func(f *pflag.Flag) {
+		names = append(names, f.Name)
+	})
+	return names
+}
+
+func findCommand(root *cobra.Command, path []string) *cobra.Command {
+	cmd := root
+	for _, part := range path {
+		found := false
+		for _, subCmd := range cmd.Commands() {
+			if subCmd.Name() == part {
+				cmd = subCmd
+				found = true
+				break
+			}
+		}
+		if !found {
+			return nil
+		}
+	}
+	return cmd
+}