@shopify/oxygen-cli 1.0.2

package/README.md

@@ -0,0 +1,91 @@
+# Oxygen-cli
+
+`@shopify/oxygen-cli` is a command-line tool for deploying your Oxygen projects. It provides a simple a way to deploy your Oxygen applications, including workers and assets, to the Oxygen platform.
+
+## Getting Started
+
+The oxygen-cli can be run locally, or it can be used from within CI/CD environments such as Github Actions.
+
+The common route to launch oxygen-cli's `deploy` command locally is through [hydrogen-cli](https://www.npmjs.com/package/@shopify/hydrogen-cli). When this is installed globally, the command is available via the `h2 deploy`.
+
+You can also install oxygen-cli as plugin for [@shopify/cli](https://www.npmjs.com/package/@shopify/cli). When this is installed globally, running the following will install oxygen-cli:
+
+```
+shopify plugins install @shopify/oxygen-cli
+```
+
+The CLI will now expose its commands under `shopify oxygen`.
+
+Finally, it is also possible to install the oxygen-cli independently, which is preferable when run from within a CI/CD environment.
+
+```
+npm install -g @shopify/oxygen-cli
+```
+
+The CLI can then be activated using the command `oxygen-cli`.
+
+## Command overview
+
+- `oxygen deploy` command initiates a deployment to Oxygen.
+
+```
+oxygen:deploy [options]
+```
+
+### Options
+
+- -t, --token <token>: (required) Oxygen deployment token. Can also be set using the `OXYGEN_DEPLOYMENT_TOKEN` environment variable (see below).
+- -r, --rootPath <rootPath>: Root path (defaults to the current working directory).
+- -e, --environmentTag <environmentTag>: Tag of the environment to deploy to. Defaults to branch name in supported CI environments (see below).
+- -w, --workerFolder <workerFolder>: Worker folder (default: `dist/worker/`).
+- -a, --assetsFolder <assetsFolder>: Assets folder (default: `dist/client/`).
+- -o, --workerOnly: Worker only deployment.
+- -s, --skipBuild: Skip running build command.
+- -b, --buildCommand <buildCommand>: Build command (default: `yarn build`).
+- --metadataUrl <metadataUrl>: URL that links to the deployment.
+- --metadataUser <metadataUser>: User that initiated the deployment.
+- --metadataVersion <metadataVersion>: A version identifier for the deployment.
+
+**Note**: All metadata options (--metadataUrl, --metadataUser, and --metadataVersion) have a maximum character limit of 90.
+
+### Example:
+
+```
+oxygen:deploy -t my-deployment-token -e staging --rootPath="/my-project" --workerOnly
+```
+
+This command will deploy your Oxygen project to the staging environment with the provided deployment token and root path. No static assets will be uploaded.
+
+The `environmentTag` option and the `metadata` options serve as overrides for values that can be retrieved from supported CI environments, see the section on environment variables below.
+
+## Environment variables
+
+The Oxygen deployment token can be specified with the `token` option. Alternatively, you can use the environment variable `OXYGEN_DEPLOYMENT_TOKEN` for this. In CI environments this is recommended. For example, when using CircleCI you can define a custom environment variable in your project settings which holds the token. The `OXYGEN_DEPLOYMENT_TOKEN` can then be populated with this variable's value in your `config.yml` file:
+
+```
+environment:
+  OXYGEN_DEPLOYMENT_TOKEN: ${YOUR_ENV_VARIABLE}
+```
+
+When run from a supported CI/CD environment, the tool will automatically retrieve metadata from relevant environment variables. Metadata describes the author making the deployment (user), the version (commit Sha) and the deployment URL (workflow URL).
+
+The following environment variables are relevant, depending on your environment:
+
+|- | Bitbucket | CircleCI | Github | Gitlab |
+|- | --------- | --------| ------ | ------ |
+| User | BITBUCKET_COMMIT_AUTHOR | CIRCLE_USERNAME | GITHUB_ACTOR | GITLAB_USER_LOGIN |
+| Version | BITBUCKET_COMMIT | CIRCLE_SHA1 | GITHUB_SHA | CI_COMMIT_SHA |
+| URL | BITBUCKET_BUILD_URL | CIRCLE_BUILD_URL | `${GITHUB_SERVER_URL}${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}` | CI_PROJECT_URL |
+
+These values can be overruled by the command line flags `metadataUser`, `metadataUrl` and `metadataVersion` respectively.
+
+The tag of the environment to deploy to, will be derived from the following variables:
+
+| Service | Branch |
+| ------- | ------ |
+| Bitbucket | BITBUCKET_BRANCH |
+| CircleCI | CIRCLE_BRANCH |
+| Github | GITHUB_REF_NAME |
+| Gitlab | CI_COMMIT_REF_NAME |
+
+The `environmentTag` command line option can be used to override this, and is required when the tool is run from outside a supported CI environment.

package/dist/commands/oxygen/deploy.d.ts

@@ -0,0 +1,26 @@
+import * as _oclif_core_lib_interfaces_parser_js from '@oclif/core/lib/interfaces/parser.js';
+import { Command } from '@oclif/core';
+import { DeployConfig } from '../../deploy/types.js';
+
+declare class Deploy extends Command {
+    static description: string;
+    static hidden: boolean;
+    static flags: {
+        token: _oclif_core_lib_interfaces_parser_js.OptionFlag<string, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        rootPath: _oclif_core_lib_interfaces_parser_js.OptionFlag<string, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        environmentTag: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        workerFolder: _oclif_core_lib_interfaces_parser_js.OptionFlag<string, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        assetsFolder: _oclif_core_lib_interfaces_parser_js.OptionFlag<string, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        workerOnly: _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
+        skipBuild: _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
+        buildCommand: _oclif_core_lib_interfaces_parser_js.OptionFlag<string, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        metadataUrl: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        metadataUser: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        metadataVersion: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+    };
+    static hasCustomBuildCommand: boolean;
+    run(): Promise<void>;
+}
+declare function runInit(options: DeployConfig): void;
+
+export { Deploy, runInit };

package/dist/commands/oxygen/deploy.js

@@ -0,0 +1,121 @@
+import { Command, Flags } from '@oclif/core';
+import { consoleError } from '@shopify/cli-kit/node/output';
+import { normalizePath } from '@shopify/cli-kit/node/path';
+import { createDeploy } from '../../deploy/index.js';
+import { deployDefaults, parseToken, verifyConfig, getBuildCommandFromLockFile } from '../../utils/utils.js';
+
+class Deploy extends Command {
+  static description = "Creates a deployment to Oxygen";
+  static hidden = false;
+  static flags = {
+    token: Flags.string({
+      char: "t",
+      description: "Oxygen deployment token",
+      env: "OXYGEN_DEPLOYMENT_TOKEN",
+      required: true
+    }),
+    rootPath: Flags.string({
+      char: "r",
+      description: "Root path",
+      default: "./",
+      required: false
+    }),
+    environmentTag: Flags.string({
+      char: "e",
+      description: "Tag of the environment to deploy to",
+      required: false
+    }),
+    workerFolder: Flags.string({
+      char: "w",
+      description: "Worker folder",
+      default: String(deployDefaults.workerDirDefault),
+      required: false
+    }),
+    assetsFolder: Flags.string({
+      char: "a",
+      description: "Assets folder",
+      default: String(deployDefaults.assetsDirDefault),
+      required: false
+    }),
+    workerOnly: Flags.boolean({
+      char: "o",
+      description: "Worker only deployment",
+      default: false,
+      required: false
+    }),
+    skipBuild: Flags.boolean({
+      char: "s",
+      description: "Skip running build command",
+      required: false,
+      default: false
+    }),
+    buildCommand: Flags.string({
+      char: "b",
+      description: "Build command",
+      required: false,
+      default: String(deployDefaults.buildCommandDefault),
+      parse: (input) => {
+        this.hasCustomBuildCommand = true;
+        return Promise.resolve(input);
+      }
+    }),
+    metadataUrl: Flags.string({
+      description: "URL that links to the deployment",
+      required: false,
+      env: "OXYGEN_METADATA_URL"
+    }),
+    metadataUser: Flags.string({
+      description: "User that initiated the deployment",
+      required: false,
+      env: "OXYGEN_METADATA_USER"
+    }),
+    metadataVersion: Flags.string({
+      description: "A version identifier for the deployment",
+      required: false,
+      env: "OXYGEN_METADATA_VERSION"
+    })
+  };
+  static hasCustomBuildCommand = false;
+  async run() {
+    try {
+      const { flags } = await this.parse(Deploy);
+      const deploymentUrl = (
+        // eslint-disable-next-line no-process-env
+        process.env.UNSAFE_OXYGEN_DEPLOYMENT_URL || "https://oxygen.shopifyapps.com"
+      );
+      const config = {
+        assetsDir: normalizePath(flags.assetsFolder),
+        buildCommand: flags.buildCommand,
+        deploymentToken: parseToken(flags.token),
+        environmentTag: flags.environmentTag,
+        deploymentUrl,
+        metadata: {
+          url: flags.metadataUrl,
+          user: flags.metadataUser,
+          version: flags.metadataVersion
+        },
+        rootPath: normalizePath(flags.rootPath),
+        skipBuild: flags.skipBuild,
+        workerDir: normalizePath(flags.workerFolder),
+        workerOnly: flags.workerOnly
+      };
+      await verifyConfig({ config });
+      if (!Deploy.hasCustomBuildCommand && !config.skipBuild) {
+        config.buildCommand = getBuildCommandFromLockFile(config);
+      }
+      runInit(config);
+    } catch (error) {
+      if (error instanceof Error) {
+        consoleError(error.message);
+      } else {
+        console.error(error);
+      }
+      this.exit(1);
+    }
+  }
+}
+function runInit(options) {
+  createDeploy(options);
+}
+
+export { Deploy, runInit };

package/dist/deploy/build-cancel.d.ts

@@ -0,0 +1,6 @@
+import { DeployConfig } from './types.js';
+import { BuildCancelResponse } from './graphql/build-cancel.js';
+
+declare function buildCancel(config: DeployConfig, buildId: string, reason: string): Promise<BuildCancelResponse>;
+
+export { buildCancel };

package/dist/deploy/build-cancel.js

@@ -0,0 +1,36 @@
+import { graphqlRequest } from '@shopify/cli-kit/node/api/graphql';
+import { AbortError } from '@shopify/cli-kit/node/error';
+import { outputInfo } from '@shopify/cli-kit/node/output';
+import { Header, errorHandler } from '../utils/utils.js';
+import { BuildCancelQuery } from './graphql/build-cancel.js';
+
+async function buildCancel(config, buildId, reason) {
+  const variables = {
+    buildId,
+    reason
+  };
+  try {
+    const response = await graphqlRequest({
+      query: BuildCancelQuery,
+      api: "Oxygen",
+      url: `${config.deploymentUrl}/api/v2/admin/graphql`,
+      token: config.deploymentToken.accessToken,
+      addedHeaders: {
+        [Header.OxygenNamespaceHandle]: config.deploymentToken.namespace
+      },
+      variables
+    });
+    if (response.buildCancel.userErrors.length >= 1) {
+      throw new AbortError(
+        `Failed to cancel build: ${response.buildCancel.userErrors[0]?.message}`
+      );
+    }
+    outputInfo(`Build with id ${buildId} cancelled.`);
+    return response.buildCancel;
+  } catch (error) {
+    errorHandler(error);
+    throw error;
+  }
+}
+
+export { buildCancel };

package/dist/deploy/build-cancel.test.d.ts

@@ -0,0 +1,2 @@
+
+export { }

package/dist/deploy/build-cancel.test.js

@@ -0,0 +1,73 @@
+import { AbortError } from '@shopify/cli-kit/node/error';
+import { graphqlRequest } from '@shopify/cli-kit/node/api/graphql';
+import { vi, describe, test, expect } from 'vitest';
+import { createTestConfig } from '../utils/test-helper.js';
+import { Header } from '../utils/utils.js';
+import { buildCancel } from './build-cancel.js';
+
+vi.mock("@shopify/cli-kit/node/api/graphql");
+vi.mock("@shopify/cli-kit/node/output", () => {
+  return {
+    outputInfo: vi.fn()
+  };
+});
+const testConfig = createTestConfig("/tmp/deploymentRoot/");
+describe("BuildCancel", () => {
+  test("should cancel a build", async () => {
+    const response = {
+      buildCancel: {
+        userErrors: []
+      }
+    };
+    vi.mocked(graphqlRequest).mockResolvedValueOnce(response);
+    const cancelResponse = await buildCancel(testConfig, "build-1", "because");
+    expect(cancelResponse).toEqual(response.buildCancel);
+    expect(graphqlRequest).toHaveBeenCalledWith({
+      query: expect.any(String),
+      api: "Oxygen",
+      url: `${testConfig.deploymentUrl}/api/v2/admin/graphql`,
+      token: testConfig.deploymentToken.accessToken,
+      variables: {
+        buildId: "build-1",
+        reason: "because"
+      },
+      addedHeaders: {
+        [Header.OxygenNamespaceHandle]: `${testConfig.deploymentToken.namespace}`
+      }
+    });
+  });
+  test("should throw AbortError when buildCancel fails with error", async () => {
+    const response = {
+      buildCancel: {
+        userErrors: [
+          {
+            message: "Cannot cancel build."
+          }
+        ]
+      }
+    };
+    vi.mocked(graphqlRequest).mockResolvedValueOnce(response);
+    await expect(buildCancel(testConfig, "build-1", "because")).rejects.toThrow(
+      new AbortError(
+        `Failed to cancel build: ${response.buildCancel.userErrors[0]?.message}`
+      )
+    );
+  });
+  test("should throw AbortError when unauthorized", async () => {
+    const error = {
+      statusCode: 401
+    };
+    vi.mocked(graphqlRequest).mockRejectedValueOnce(error);
+    try {
+      await expect(
+        buildCancel(testConfig, "build-1", "because")
+      ).rejects.toThrow(
+        new AbortError(
+          "You are not authorized to perform this action. Please check your deployment token."
+        )
+      );
+    } catch (err) {
+      expect(error).toBeInstanceOf(AbortError);
+    }
+  });
+});

package/dist/deploy/build-initiate.d.ts

@@ -0,0 +1,6 @@
+import { DeployConfig, EnvironmentInput } from './types.js';
+import { BuildInitiateResponse } from './graphql/build-initiate.js';
+
+declare function buildInitiate(config: DeployConfig, environment?: EnvironmentInput, labels?: string[]): Promise<BuildInitiateResponse>;
+
+export { buildInitiate };

package/dist/deploy/build-initiate.js

@@ -0,0 +1,38 @@
+import { graphqlRequest } from '@shopify/cli-kit/node/api/graphql';
+import { AbortError } from '@shopify/cli-kit/node/error';
+import { outputCompleted } from '@shopify/cli-kit/node/output';
+import { Header, errorHandler } from '../utils/utils.js';
+import { BuildInitiateQuery } from './graphql/build-initiate.js';
+
+async function buildInitiate(config, environment, labels = []) {
+  const variables = {
+    environment,
+    labels
+  };
+  try {
+    const response = await graphqlRequest({
+      query: BuildInitiateQuery,
+      api: "Oxygen",
+      url: `${config.deploymentUrl}/api/v2/admin/graphql`,
+      token: config.deploymentToken.accessToken,
+      variables,
+      addedHeaders: {
+        [Header.OxygenNamespaceHandle]: config.deploymentToken.namespace
+      }
+    });
+    if (response.buildInitiate.userErrors.length >= 1) {
+      throw new AbortError(
+        `Failed to create build. ${response.buildInitiate.userErrors[0]?.message}`
+      );
+    }
+    outputCompleted(
+      `Build initiated successfully with id ${response.buildInitiate.build.id}.`
+    );
+    return response.buildInitiate;
+  } catch (error) {
+    errorHandler(error);
+    throw error;
+  }
+}
+
+export { buildInitiate };

package/dist/deploy/build-initiate.test.d.ts

@@ -0,0 +1,2 @@
+
+export { }

package/dist/deploy/build-initiate.test.js

@@ -0,0 +1,81 @@
+import { AbortError } from '@shopify/cli-kit/node/error';
+import { graphqlRequest } from '@shopify/cli-kit/node/api/graphql';
+import { outputCompleted } from '@shopify/cli-kit/node/output';
+import { vi, describe, test, expect } from 'vitest';
+import { Header } from '../utils/utils.js';
+import { createTestConfig } from '../utils/test-helper.js';
+import { buildInitiate } from './build-initiate.js';
+
+vi.mock("@shopify/cli-kit/node/api/graphql");
+vi.mock("@shopify/cli-kit/node/output");
+const testConfig = createTestConfig("/tmp/deploymentRoot/");
+describe("BuildInitiate", () => {
+  test("should initiate a build", async () => {
+    const response = {
+      buildInitiate: {
+        build: {
+          id: "build-1"
+        },
+        userErrors: []
+      }
+    };
+    vi.mocked(graphqlRequest).mockResolvedValueOnce(response);
+    const initiateResponse = await buildInitiate(
+      testConfig,
+      {
+        tag: testConfig.environmentTag
+      },
+      []
+    );
+    expect(initiateResponse).toEqual(response.buildInitiate);
+    expect(graphqlRequest).toHaveBeenCalledWith({
+      query: expect.any(String),
+      api: "Oxygen",
+      url: `${testConfig.deploymentUrl}/api/v2/admin/graphql`,
+      token: testConfig.deploymentToken.accessToken,
+      variables: { environment: { tag: testConfig.environmentTag }, labels: [] },
+      addedHeaders: {
+        [Header.OxygenNamespaceHandle]: `${testConfig.deploymentToken.namespace}`
+      }
+    });
+    expect(outputCompleted).toHaveBeenCalledWith(
+      "Build initiated successfully with id build-1."
+    );
+  });
+  test("should throw AbortError when build initiation fails due to user errors", async () => {
+    const response = {
+      buildInitiate: {
+        userErrors: [
+          {
+            message: "Error: cannot proceed with build."
+          }
+        ]
+      }
+    };
+    vi.mocked(graphqlRequest).mockResolvedValueOnce(response);
+    await expect(
+      buildInitiate(testConfig, { tag: "preview" }, [])
+    ).rejects.toThrow(
+      new AbortError(
+        `Failed to create build. ${response.buildInitiate.userErrors[0]?.message}`
+      )
+    );
+  });
+  test("should throw AbortError when unauthorized", async () => {
+    const error = {
+      statusCode: 401
+    };
+    vi.mocked(graphqlRequest).mockRejectedValueOnce(error);
+    try {
+      await expect(
+        buildInitiate(testConfig, { tag: "preview" }, [])
+      ).rejects.toThrow(
+        new AbortError(
+          "You are not authorized to perform this action. Please check your deployment token."
+        )
+      );
+    } catch (err) {
+      expect(error).toBeInstanceOf(AbortError);
+    }
+  });
+});

package/dist/deploy/build-project.d.ts

@@ -0,0 +1,5 @@
+import { DeployConfig } from './types.js';
+
+declare function buildProject(config: DeployConfig, assetPath?: string): Promise<void>;
+
+export { buildProject };

package/dist/deploy/build-project.js

@@ -0,0 +1,32 @@
+import { spawn } from 'child_process';
+
+async function buildProject(config, assetPath) {
+  const assetPathEnvironment = assetPath ? { HYDROGEN_ASSET_BASE_URL: assetPath } : {};
+  await new Promise((resolve, reject) => {
+    const buildCommand = spawn(config.buildCommand, [], {
+      stdio: "inherit",
+      env: {
+        // eslint-disable-next-line no-process-env
+        ...process.env,
+        ...assetPathEnvironment
+      },
+      cwd: config.rootPath,
+      shell: true
+    });
+    if (buildCommand.stdout) {
+      buildCommand.stdout.on("data", (data) => {
+        console.log(`stdout: ${data}`);
+      });
+    }
+    buildCommand.on("close", (code) => {
+      if (code !== 0) {
+        reject(code);
+      }
+      resolve(code);
+    });
+  }).catch((error) => {
+    throw new Error(`Build failed with error code: ${error}`);
+  });
+}
+
+export { buildProject };

package/dist/deploy/build-project.test.d.ts

@@ -0,0 +1,2 @@
+
+export { }

package/dist/deploy/build-project.test.js

@@ -0,0 +1,53 @@
+import { spawn } from 'child_process';
+import { vi, test, expect } from 'vitest';
+import { createTestConfig } from '../utils/test-helper.js';
+import { buildProject } from './build-project.js';
+
+let returnCode = 0;
+vi.mock("child_process", () => {
+  const spawn2 = vi.fn();
+  spawn2.mockImplementation(() => {
+    return {
+      stdout: {
+        on: () => {
+        }
+      },
+      on: (event, callback) => {
+        if (event === "close") {
+          return callback(returnCode);
+        }
+      }
+    };
+  });
+  return { spawn: spawn2 };
+});
+const testConfig = createTestConfig("rootFolder");
+test("BuildProject builds the project successfully", async () => {
+  const config = {
+    ...testConfig,
+    buildCommand: "npm run build"
+  };
+  const assetPath = "https://example.com/assets";
+  await buildProject(config, assetPath);
+  expect(spawn).toBeCalledWith("npm run build", [], {
+    cwd: "rootFolder",
+    shell: true,
+    stdio: "inherit",
+    env: {
+      // eslint-disable-next-line no-process-env
+      ...process.env,
+      HYDROGEN_ASSET_BASE_URL: "https://example.com/assets"
+    }
+  });
+});
+test("should throw error on build command failure", async () => {
+  returnCode = 1;
+  ({
+    ...testConfig,
+    buildCommand: "yarn build"
+  });
+  const assetPath = "https://example.com/assets";
+  await expect(() => buildProject(testConfig, assetPath)).rejects.toThrow(
+    "Build failed with error code: 1"
+  );
+});

package/dist/deploy/deployment-cancel.d.ts

@@ -0,0 +1,6 @@
+import { DeployConfig } from './types.js';
+import { DeploymentCancelResponse } from './graphql/deployment-cancel.js';
+
+declare function deploymentCancel(config: DeployConfig, deploymentId: string, reason: string): Promise<DeploymentCancelResponse>;
+
+export { deploymentCancel };

package/dist/deploy/deployment-cancel.js

@@ -0,0 +1,36 @@
+import { graphqlRequest } from '@shopify/cli-kit/node/api/graphql';
+import { AbortError } from '@shopify/cli-kit/node/error';
+import { outputInfo } from '@shopify/cli-kit/node/output';
+import { Header, errorHandler } from '../utils/utils.js';
+import { DeploymentCancelQuery } from './graphql/deployment-cancel.js';
+
+async function deploymentCancel(config, deploymentId, reason) {
+  const variables = {
+    deploymentId,
+    reason
+  };
+  try {
+    const response = await graphqlRequest({
+      query: DeploymentCancelQuery,
+      api: "Oxygen",
+      url: `${config.deploymentUrl}/api/v2/admin/graphql`,
+      token: config.deploymentToken.accessToken,
+      variables,
+      addedHeaders: {
+        [Header.OxygenNamespaceHandle]: config.deploymentToken.namespace
+      }
+    });
+    if (response.deploymentCancel.userErrors.length >= 1) {
+      throw new AbortError(
+        `Failed to cancel deployment: ${response.deploymentCancel.userErrors[0]?.message}`
+      );
+    }
+    outputInfo(`Deployment with id ${deploymentId} cancelled.`);
+    return response.deploymentCancel;
+  } catch (error) {
+    errorHandler(error);
+    throw error;
+  }
+}
+
+export { deploymentCancel };

package/dist/deploy/deployment-cancel.test.d.ts

@@ -0,0 +1,2 @@
+
+export { }