Add --env & deprecate --env-branch flag (#1841)

- Adding --env flag to standardize how we refer to environments in the CLI
  - pass in an environment's handle you can view from running env list
  - remove existing --env flag which was used to identify environment by name (used only by env push__unstable)
  - deprecate --env-branch from env pull, env push__unstable, deploy, preview, dev-vite, dev

.changeset/lovely-donkeys-destroy.md

@@ -0,0 +1,10 @@
+---
+'@shopify/cli-hydrogen': minor
+---
+
+`--env` flag has deprecated the `--env-branch` flag for several Hydrogen CLI commands
+
+- `--env` will allow the user to provide an environment's handle when performing Hydrogen CLI commands
+  - Run `env list` to display all the environments and its associated handles
+- All Hydrogen CLI commands that contain the `--env-branch` flag will also contain the `--env` flag
+- `--env-branch` flag will be deprecated on all Hydrogen CLI commands

packages/cli/oclif.manifest.json

@@ -261,10 +261,24 @@
       "args": {},
       "description": "Builds and deploys a Hydrogen storefront to Oxygen.",
       "flags": {
+        "env": {
+          "description": "Specifies the environment to perform the operation using its handle. Run `env list` to view an environment's handle ",
+          "exclusive": [
+            "env-branch"
+          ],
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "env-branch": {
-          "description": "Environment branch (tag) for environment to deploy to.",
+          "deprecated": {
+            "to": "env",
+            "message": "--env-branch is deprecated. Use --env instead."
+          },
+          "description": "Specifies the environment to perform the operation using its Git branch name.",
+          "env": "SHOPIFY_HYDROGEN_ENVIRONMENT_BRANCH",
           "name": "env-branch",
-          "required": false,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -494,9 +508,22 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "env": {
+          "description": "Specifies the environment to perform the operation using its handle. Run `env list` to view an environment's handle ",
+          "exclusive": [
+            "env-branch"
+          ],
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "env-branch": {
-          "char": "e",
-          "description": "Specifies the environment to pull variables from using its Git branch name.",
+          "deprecated": {
+            "to": "env",
+            "message": "--env-branch is deprecated. Use --env instead."
+          },
+          "description": "Specifies the environment to perform the operation using its Git branch name.",
           "env": "SHOPIFY_HYDROGEN_ENVIRONMENT_BRANCH",
           "name": "env-branch",
           "hasDynamicHelp": false,
@@ -624,9 +651,22 @@
           "multiple": false,
           "type": "option"
         },
+        "env": {
+          "description": "Specifies the environment to perform the operation using its handle. Run `env list` to view an environment's handle ",
+          "exclusive": [
+            "env-branch"
+          ],
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "env-branch": {
-          "char": "e",
-          "description": "Specifies the environment to pull variables from using its Git branch name.",
+          "deprecated": {
+            "to": "env",
+            "message": "--env-branch is deprecated. Use --env instead."
+          },
+          "description": "Specifies the environment to perform the operation using its Git branch name.",
           "env": "SHOPIFY_HYDROGEN_ENVIRONMENT_BRANCH",
           "name": "env-branch",
           "hasDynamicHelp": false,
@@ -980,9 +1020,22 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "env": {
+          "description": "Specifies the environment to perform the operation using its handle. Run `env list` to view an environment's handle ",
+          "exclusive": [
+            "env-branch"
+          ],
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "env-branch": {
-          "char": "e",
-          "description": "Specifies the environment to pull variables from using its Git branch name.",
+          "deprecated": {
+            "to": "env",
+            "message": "--env-branch is deprecated. Use --env instead."
+          },
+          "description": "Specifies the environment to perform the operation using its Git branch name.",
           "env": "SHOPIFY_HYDROGEN_ENVIRONMENT_BRANCH",
           "name": "env-branch",
           "hasDynamicHelp": false,
@@ -1316,9 +1369,22 @@
       "args": {},
       "description": "Populate your .env with variables from your Hydrogen storefront.",
       "flags": {
+        "env": {
+          "description": "Specifies the environment to perform the operation using its handle. Run `env list` to view an environment's handle ",
+          "exclusive": [
+            "env-branch"
+          ],
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "env-branch": {
-          "char": "e",
-          "description": "Specifies the environment to pull variables from using its Git branch name.",
+          "deprecated": {
+            "to": "env",
+            "message": "--env-branch is deprecated. Use --env instead."
+          },
+          "description": "Specifies the environment to perform the operation using its Git branch name.",
           "env": "SHOPIFY_HYDROGEN_ENVIRONMENT_BRANCH",
           "name": "env-branch",
           "hasDynamicHelp": false,
@@ -1364,8 +1430,10 @@
       "description": "Push environment variables from the local .env file to your linked Hydrogen storefront.",
       "flags": {
         "env": {
-          "description": "Specifies an environment's name when using remote environment variables.",
-          "env": "SHOPIFY_HYDROGEN_ENVIRONMENT_NAME",
+          "description": "Specifies the environment to perform the operation using its handle. Run `env list` to view an environment's handle ",
+          "exclusive": [
+            "env-branch"
+          ],
           "name": "env",
           "hasDynamicHelp": false,
           "multiple": false,

packages/cli/src/commands/hydrogen/deploy.test.ts

@@ -221,6 +221,92 @@ describe('deploy', () => {
     });
   });
 
+  it('calls createDeploy against a environment selected by env', async () => {
+    vi.mocked(getOxygenDeploymentData).mockResolvedValue({
+      oxygenDeploymentToken: 'some-encoded-token',
+      environments: [
+        {
+          name: 'Production',
+          handle: 'production',
+          branch: 'main',
+          type: 'PRODUCTION',
+        },
+        {name: 'Preview', handle: 'preview', branch: null, type: 'PREVIEW'},
+        {name: 'Staging', handle: 'staging', branch: 'stage-1', type: 'CUSTOM'},
+      ],
+    });
+
+    await runDeploy({
+      ...deployParams,
+      env: 'staging',
+    });
+
+    expect(vi.mocked(createDeploy)).toHaveBeenCalledWith({
+      config: {
+        ...expectedConfig,
+        environmentTag: 'stage-1',
+      },
+      hooks: expectedHooks,
+      logger: deploymentLogger,
+    });
+    expect(vi.mocked(renderSuccess)).toHaveBeenCalled;
+  });
+
+  it('calls createDeploy against a environment selected by envBranch', async () => {
+    vi.mocked(getOxygenDeploymentData).mockResolvedValue({
+      oxygenDeploymentToken: 'some-encoded-token',
+      environments: [
+        {
+          name: 'Production',
+          handle: 'production',
+          branch: 'main',
+          type: 'PRODUCTION',
+        },
+        {name: 'Preview', handle: 'preview', branch: null, type: 'PREVIEW'},
+        {name: 'Staging', handle: 'staging', branch: 'stage-1', type: 'CUSTOM'},
+      ],
+    });
+
+    await runDeploy({
+      ...deployParams,
+      envBranch: 'stage-1',
+    });
+
+    expect(vi.mocked(createDeploy)).toHaveBeenCalledWith({
+      config: {
+        ...expectedConfig,
+        environmentTag: 'stage-1',
+      },
+      hooks: expectedHooks,
+      logger: deploymentLogger,
+    });
+    expect(vi.mocked(renderSuccess)).toHaveBeenCalled;
+  });
+
+  it("errors when the env provided doesn't match any environment", async () => {
+    await expect(
+      runDeploy({
+        ...deployParams,
+        env: 'fake-handle',
+      }),
+    ).rejects.toThrowError('Environment not found');
+  });
+
+  it('errors when env is provided while running in CI', async () => {
+    vi.mocked(ciPlatform).mockReturnValue({
+      isCI: true,
+      name: 'github',
+      metadata: {},
+    });
+
+    await expect(
+      runDeploy({
+        ...deployParams,
+        env: 'fake-handle',
+      }),
+    ).rejects.toThrowError("Can't specify an environment handle in CI");
+  });
+
   it('errors when there are uncommited changes', async () => {
     vi.mocked(ensureIsClean).mockRejectedValue(
       new GitDirectoryNotCleanError('Uncommitted changes'),
@@ -328,8 +414,13 @@ describe('deploy', () => {
     vi.mocked(getOxygenDeploymentData).mockResolvedValue({
       oxygenDeploymentToken: 'some-encoded-token',
       environments: [
-        {name: 'Production', branch: 'main', type: 'PRODUCTION'},
-        {name: 'Preview', branch: null, type: 'PREVIEW'},
+        {
+          name: 'Production',
+          handle: 'production',
+          branch: 'main',
+          type: 'PRODUCTION',
+        },
+        {name: 'Preview', handle: 'preview', branch: null, type: 'PREVIEW'},
       ],
     });
 
@@ -358,8 +449,13 @@ describe('deploy', () => {
       vi.mocked(getOxygenDeploymentData).mockResolvedValue({
         oxygenDeploymentToken: 'some-encoded-token',
         environments: [
-          {name: 'Production', branch: 'main', type: 'PRODUCTION'},
-          {name: 'Preview', branch: null, type: 'PREVIEW'},
+          {
+            name: 'Production',
+            handle: 'production',
+            branch: 'main',
+            type: 'PRODUCTION',
+          },
+          {name: 'Preview', handle: 'preview', branch: null, type: 'PREVIEW'},
         ],
       });
 

packages/cli/src/commands/hydrogen/deploy.ts

@@ -32,6 +32,10 @@ import {
   parseToken,
 } from '@shopify/oxygen-cli/deploy';
 
+import {
+  findEnvironmentByBranchOrThrow,
+  findEnvironmentOrThrow,
+} from '../../lib/common.js';
 import {commonFlags, flagsToCamelObject} from '../../lib/flags.js';
 import {getOxygenDeploymentData} from '../../lib/get-oxygen-deployment-data.js';
 import {OxygenDeploymentData} from '../../lib/graphql/admin/get-oxygen-data.js';
@@ -54,10 +58,8 @@ export const deploymentLogger: Logger = (
 export default class Deploy extends Command {
   static description = 'Builds and deploys a Hydrogen storefront to Oxygen.';
   static flags: any = {
-    'env-branch': Flags.string({
-      description: 'Environment branch (tag) for environment to deploy to.',
-      required: false,
-    }),
+    ...commonFlags.env,
+    ...commonFlags.envBranch,
     'env-file': Flags.string({
       description:
         'Path to an environment file to override existing environment variables for the deployment.',
@@ -161,7 +163,6 @@ export default class Deploy extends Command {
     return {
       ...camelFlags,
       defaultEnvironment: flags.preview,
-      environmentTag: flags['env-branch'],
       environmentFile: flags['env-file'],
       path: flags.path ? resolvePath(flags.path) : process.cwd(),
     } as OxygenDeploymentOptions;
@@ -172,7 +173,8 @@ interface OxygenDeploymentOptions {
   authBypassToken: boolean;
   buildCommand?: string;
   defaultEnvironment: boolean;
-  environmentTag?: string;
+  env?: string;
+  envBranch?: string;
   environmentFile?: string;
   force: boolean;
   noVerify: boolean;
@@ -218,7 +220,8 @@ export async function runDeploy(
     authBypassToken: generateAuthBypassToken,
     buildCommand,
     defaultEnvironment,
-    environmentTag,
+    env: envHandle,
+    envBranch,
     environmentFile,
     force: forceOnUncommitedChanges,
     noVerify,
@@ -295,6 +298,15 @@ export async function runDeploy(
     );
   }
 
+  let userProvidedEnvironmentTag: string | null = null;
+
+  if (isCI && envHandle) {
+    throw new AbortError(
+      "Can't specify an environment handle in CI",
+      'Environments are automatically picked up by the current Git branch.',
+    );
+  }
+
   if (!isCI) {
     deploymentData = await getOxygenDeploymentData({
       root,
@@ -306,6 +318,15 @@ export async function runDeploy(
     }
 
     token = token || deploymentData.oxygenDeploymentToken;
+
+    if (envHandle) {
+      userProvidedEnvironmentTag = findEnvironmentOrThrow(
+        deploymentData.environments || [],
+        envHandle,
+      ).branch;
+    } else if (envBranch) {
+      userProvidedEnvironmentTag = envBranch;
+    }
   }
 
   if (!token) {
@@ -322,7 +343,7 @@ export async function runDeploy(
   if (
     !isCI &&
     !defaultEnvironment &&
-    !environmentTag &&
+    !userProvidedEnvironmentTag &&
     deploymentData?.environments
   ) {
     if (deploymentData.environments.length > 1) {
@@ -386,7 +407,9 @@ export async function runDeploy(
     defaultEnvironment: defaultEnvironment || isPreview,
     deploymentToken: parseToken(token as string),
     environmentTag:
-      environmentTag || deploymentEnvironmentTag || fallbackEnvironmentTag,
+      userProvidedEnvironmentTag ||
+      deploymentEnvironmentTag ||
+      fallbackEnvironmentTag,
     generateAuthBypassToken,
     verificationMaxDuration: 180,
     metadata: {