[env] add clone command (#376)

CHANGELOG.md

@@ -1,6 +1,10 @@
 CHANGELOG
 =========
 
+## 0.9.3
+- Add command to clone environments.
+  [#376](https://github.com/pulumi/esc/pull/376)
+
 ## 0.9.2
 
 - Add commands to manage environment tags.

cmd/esc/cli/cli_test.go

@@ -523,6 +523,39 @@ func (c *testPulumiClient) CreateEnvironmentWithProject(ctx context.Context, org
 	return nil
 }
 
+func (c *testPulumiClient) CloneEnvironment(
+	ctx context.Context,
+	orgName, projectName, envName string,
+	destEnv client.CloneEnvironmentRequest,
+) error {
+	srcEnvName := path.Join(orgName, projectName, envName)
+	srcEnv, ok := c.environments[srcEnvName]
+	if !ok {
+		return errors.New("source env not found")
+	}
+	if destEnv.Project == "" {
+		destEnv.Project = projectName
+	}
+	destEnvName := path.Join(orgName, destEnv.Project, destEnv.Name)
+	if _, ok := c.environments[destEnvName]; ok {
+		return errors.New("already exists")
+	}
+	testDestEnv := &testEnvironment{
+		revisions: []*testEnvironmentRevision{srcEnv.revisions[len(srcEnv.revisions)-1]},
+	}
+	if destEnv.PreserveHistory {
+		testDestEnv.revisions = srcEnv.revisions
+	}
+	if destEnv.PreserveEnvironmentTags {
+		testDestEnv.tags = srcEnv.tags
+	}
+	if destEnv.PreserveRevisionTags {
+		testDestEnv.revisionTags = srcEnv.revisionTags
+	}
+	c.environments[destEnvName] = testDestEnv
+	return nil
+}
+
 func (c *testPulumiClient) GetEnvironment(
 	ctx context.Context,
 	orgName string,

cmd/esc/cli/client/apitype.go

@@ -59,6 +59,16 @@ func diagsErrorString(envDiags []EnvironmentDiagnostic) string {
 	return diags.String()
 }
 
+type CloneEnvironmentRequest struct {
+	Project                 string `json:"project,omitempty"`
+	Name                    string `json:"name"`
+	Version                 int    `json:"version,omitempty"`
+	PreserveHistory         bool   `json:"preserveHistory,omitempty"`
+	PreserveAccess          bool   `json:"preserveAccess,omitempty"`
+	PreserveEnvironmentTags bool   `json:"preserveEnvironmentTags,omitempty"`
+	PreserveRevisionTags    bool   `json:"preserveRevisionTags,omitempty"`
+}
+
 type EnvironmentRevisionRetracted struct {
 	Replacement int       `json:"replacement"`
 	At          time.Time `json:"at"`

cmd/esc/cli/client/client.go

@@ -81,9 +81,13 @@ type Client interface {
 
 	// Deprecated: Use CreateEnvironmentWithProject instead
 	CreateEnvironment(ctx context.Context, orgName, envName string) error
+
 	// CreateEnvironment creates an environment named projectName/envName in orgName.
 	CreateEnvironmentWithProject(ctx context.Context, orgName, projectName, envName string) error
 
+	// CloneEnvironment clones an source environment into a new destination environment.
+	CloneEnvironment(ctx context.Context, orgName, srcEnvProject, srcEnvName string, destEnv CloneEnvironmentRequest) error
+
 	// GetEnvironment returns the YAML + ETag for the environment envName in org orgName. If decrypt is
 	// true, any { fn::secret: { ciphertext: "..." } } constructs in the definition will be decrypted and
 	// replaced with { fn::secret: "plaintext" }.
@@ -469,6 +473,15 @@ func (pc *client) CreateEnvironmentWithProject(ctx context.Context, orgName, pro
 	return pc.restCall(ctx, http.MethodPost, path, nil, req, nil)
 }
 
+func (pc *client) CloneEnvironment(
+	ctx context.Context,
+	orgName, srcEnvProject, srcEnvName string,
+	destEnv CloneEnvironmentRequest,
+) error {
+	path := fmt.Sprintf("/api/esc/environments/%v/%v/%v/clone", orgName, srcEnvProject, srcEnvName)
+	return pc.restCall(ctx, http.MethodPost, path, nil, destEnv, nil)
+}
+
 func (pc *client) GetEnvironment(
 	ctx context.Context,
 	orgName string,

cmd/esc/cli/env.go

@@ -19,6 +19,19 @@ import (
 	"github.com/pulumi/pulumi/sdk/v3/go/common/util/cmdutil"
 )
 
+type ambiguousIdentifierError struct {
+	legacyRef environmentRef
+	ref       environmentRef
+}
+
+func (e ambiguousIdentifierError) Error() string {
+	return fmt.Sprintf(
+		"ambiguous path provided\n\nEnvironments found at both '%s' and '%s'.\nPlease specify the full path as <org-name>/<project-name>/<env-name>",
+		e.ref.String(),
+		e.legacyRef.String(),
+	)
+}
+
 type envCommand struct {
 	esc *escCommand
 
@@ -51,6 +64,7 @@ func newEnvCmd(esc *escCommand) *cobra.Command {
 	cmd.PersistentFlags().StringVar(&env.envNameFlag, "env", "", "The name of the environment to operate on.")
 
 	cmd.AddCommand(newEnvInitCmd(env))
+	cmd.AddCommand(newEnvCloneCmd(env))
 	cmd.AddCommand(newEnvEditCmd(env))
 	cmd.AddCommand(newEnvGetCmd(env))
 	cmd.AddCommand(newEnvDiffCmd(env))
@@ -71,6 +85,7 @@ type environmentRef struct {
 	envName     string
 	version     string
 
+	isUsingLegacyID  bool
 	hasAmbiguousPath bool
 }
 
@@ -98,13 +113,16 @@ func (cmd *envCommand) parseRef(refStr string) environmentRef {
 	hasAmbiguousPath := false
 	orgName = cmd.esc.account.DefaultOrg
 	projectName = client.DefaultProject
+	isUsingLegacyID := false
 
 	parts := strings.Split(refStr, "/")
 
 	switch l := len(parts); {
 	case l == 1:
 		// <environment-name>
 		envNameAndVersion = parts[0]
+
+		isUsingLegacyID = true
 	case l == 2:
 		// <project-name>/<env-name> or <org-name>/<env-name>
 		// We assume the former, and this will be disambiguated later.
@@ -129,6 +147,7 @@ func (cmd *envCommand) parseRef(refStr string) environmentRef {
 		projectName:      projectName,
 		envName:          envName,
 		version:          version,
+		isUsingLegacyID:  isUsingLegacyID,
 		hasAmbiguousPath: hasAmbiguousPath,
 	}
 }
@@ -193,6 +212,7 @@ func (cmd *envCommand) getNewEnvRef(
 		projectName:      client.DefaultProject,
 		envName:          ref.envName,
 		version:          ref.version,
+		isUsingLegacyID:  true,
 		hasAmbiguousPath: ref.hasAmbiguousPath,
 	}
 
@@ -255,6 +275,7 @@ func (cmd *envCommand) getExistingEnvRefWithRelative(
 		projectName:      client.DefaultProject,
 		envName:          ref.envName,
 		version:          ref.version,
+		isUsingLegacyID:  true,
 		hasAmbiguousPath: ref.hasAmbiguousPath,
 	}
 
@@ -267,11 +288,10 @@ func (cmd *envCommand) getExistingEnvRefWithRelative(
 
 	// Require unambiguous path if both paths exist
 	if exists && existsLegacyPath {
-		return ref, fmt.Errorf(
-			"ambiguous path provided\n\nEnvironments found at both '%s' and '%s'.\nPlease specify the full path as <org-name>/<project-name>/<env-name>",
-			ref.String(),
-			legacyRef.String(),
-		)
+		return ref, ambiguousIdentifierError{
+			legacyRef: legacyRef,
+			ref:       ref,
+		}
 	}
 
 	if existsLegacyPath {

cmd/esc/cli/env_clone.go

@@ -0,0 +1,108 @@
+// Copyright 2024, Pulumi Corporation.
+
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/pulumi/esc/cmd/esc/cli/client"
+	"github.com/spf13/cobra"
+)
+
+func newEnvCloneCmd(env *envCommand) *cobra.Command {
+	var (
+		preserveHistory         bool
+		preserveAccess          bool
+		preserveEnvironmentTags bool
+		preserveRevisionTags    bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "clone [<org-name>/]<src-project-name>/<src-environment-name> [<dest-project-name>/]<dest-environment-name>",
+		Args:  cobra.ExactArgs(2),
+		Short: "Clone an existing environment into a new environment.",
+		Long: "Clone an existing environment into a new environment.\n" +
+			"\n" +
+			"This command clones an existing environment with the given identifier into a new environment.\n" +
+			"If a project is omitted from the new environment identifier the new environment will be created\n" +
+			"within the same project as the environment being cloned.\n",
+		SilenceUsage: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := context.Background()
+
+			if err := env.esc.getCachedClient(ctx); err != nil {
+				return err
+			}
+
+			ref, args, err := env.getExistingEnvRef(ctx, args)
+			// An error will arise if an environment reference is ambiguous and can't be
+			// resolved to a single environment. The ref for the non-legacy environment will
+			// also be returned in this case.
+			// If the original ref is using a legacy ID of just env name return an error
+			// Otherwise we will ignore any conflict errors and assume the user meant <project-name>/<env-name>
+			var ambiguousIdErr ambiguousIdentifierError
+			if err != nil && !errors.As(err, &ambiguousIdErr) {
+				return err
+			}
+
+			if ref.isUsingLegacyID {
+				return errors.New("referring to an environment name ('env' or 'org/env') without a project is not supported")
+			}
+
+			if ref.version != "" {
+				return errors.New("the clone command does not accept versions")
+			}
+
+			var destProject string
+			destName := args[0]
+			if project, name, hasDelimiter := strings.Cut(args[0], "/"); hasDelimiter {
+				destProject = project
+				destName = name
+			}
+
+			destEnv := client.CloneEnvironmentRequest{
+				Project:                 destProject,
+				Name:                    destName,
+				PreserveHistory:         preserveHistory,
+				PreserveAccess:          preserveAccess,
+				PreserveEnvironmentTags: preserveEnvironmentTags,
+				PreserveRevisionTags:    preserveRevisionTags,
+			}
+			if err := env.esc.client.CloneEnvironment(ctx, ref.orgName, ref.projectName, ref.envName, destEnv); err != nil {
+				return fmt.Errorf("cloning environment: %w", err)
+			}
+
+			if destProject == "" {
+				destProject = ref.projectName
+			}
+			fmt.Fprintf(
+				env.esc.stdout,
+				"Environment %s/%s/%s cloned into %s/%s/%s.\n",
+				ref.orgName, ref.projectName, ref.envName,
+				ref.orgName, destProject, destName,
+			)
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&preserveHistory,
+		"preserve-history", false,
+		"preserve history of the environment being cloned")
+
+	cmd.Flags().BoolVar(&preserveAccess,
+		"preserve-access", false,
+		"preserve the same team access on the environment being cloned")
+
+	cmd.Flags().BoolVar(&preserveEnvironmentTags,
+		"preserve-env-tags", false,
+		"preserve any tags on the environment being cloned")
+
+	cmd.Flags().BoolVar(&preserveRevisionTags,
+		"preserve-rev-tags", false,
+		"preserve any tags on the environment revisions being cloned")
+
+	return cmd
+}

cmd/esc/cli/env_diff.go

@@ -51,7 +51,7 @@ func newEnvDiffCmd(env *envCommand) *cobra.Command {
 				baseRef.version = "latest"
 			}
 
-			compareRef := environmentRef{baseRef.orgName, baseRef.projectName, baseRef.envName, "latest", baseRef.hasAmbiguousPath}
+			compareRef := environmentRef{baseRef.orgName, baseRef.projectName, baseRef.envName, "latest", baseRef.isUsingLegacyID, baseRef.hasAmbiguousPath}
 			if len(args) != 0 {
 				compareRef, err = env.getExistingEnvRefWithRelative(ctx, args[0], &baseRef)
 				if err != nil {

cmd/esc/cli/testdata/env-clone-conflict.yaml

@@ -0,0 +1,38 @@
+run: |
+  esc env clone default/src a
+error: exit status 1
+environments:
+  test-user/default/a: {}
+  test-user/default/src:
+    revisions:
+      - yaml:
+          values: {}
+      - yaml:
+          values:
+            string: hello, world!
+        tags:
+          - stable
+      - yaml:
+          imports:
+            - a
+            - b
+          values:
+            # comment
+            "null": null
+            boolean: true
+            number: 42
+            string: esc
+            array: [hello, world]
+            object: {hello: world}
+            open:
+              fn::open::test: echo
+            secret:
+              fn::secret:
+                ciphertext: ZXNjeAAAAAHz5ePy5fTB4+Pl8/PL5fnJxPD7
+    tags:
+      team: pulumi
+stdout: |
+  > esc env clone default/src a
+stderr: |
+  > esc env clone default/src a
+  Error: cloning environment: already exists

cmd/esc/cli/testdata/env-clone-not-found.yaml

@@ -0,0 +1,38 @@
+run: |
+  esc env clone not/found dest
+error: exit status 1
+environments:
+  test-user/default/a: {}
+  test-user/default/src:
+    revisions:
+      - yaml:
+          values: {}
+      - yaml:
+          values:
+            string: hello, world!
+        tags:
+          - stable
+      - yaml:
+          imports:
+            - a
+            - b
+          values:
+            # comment
+            "null": null
+            boolean: true
+            number: 42
+            string: esc
+            array: [hello, world]
+            object: {hello: world}
+            open:
+              fn::open::test: echo
+            secret:
+              fn::secret:
+                ciphertext: ZXNjeAAAAAHz5ePy5fTB4+Pl8/PL5fnJxPD7
+    tags:
+      team: pulumi
+stdout: |
+  > esc env clone not/found dest
+stderr: |
+  > esc env clone not/found dest
+  Error: cloning environment: source env not found