npm package: @octopusdeploy/step-package-cli
Description: ``` npm i --save-dev @octopusdeploy/step-package-cli ```
Author: Octopus Deploy
Latest version: 4.0.5

# Octopus Step Packages: CLI

```
npm i --save-dev @octopusdeploy/step-package-cli
```

The Step Package CLI provides a set of tools to build, pack and publish step packages in a consistent manner, so that once built they are in a format that is guaranteed to work with Octopus Server.

## Build

The build command:

- Loads package id and version information from the `package.json` file located via the `packageDirectory` parameter
- Locates convention-based step package contents by scanning for a `metadata.json` file located via the `sourceDirectory` parameter and looking for contents relative to it
- Will build the required `node` components (executor.js, validator.js) within the step package in `CommonJS` format
- Will build the required `browser` components (ui.js) within the step package in `ESM` format
- Will generate the required JsonSchema (inputs.json) from the default exported type in `inputs.ts`
- Will package the built contents into a `zip` file located in the `outputDirectory`

## Publish

The publish command:

- Unzips one or more built step packages to be published via the `packagePath` parameter. A glob pattern can be used to process multiple packages.
- Loads the metadata from the package to construct a package manifest
- Uploads the manifest and package contents to the feed designated by the `feedUrl` parameter, using the `apiKey` parameter for authentication to the feed.
- If a package already exists in the feed a 409 Conflict error will be returned, this can be ignored using the `ignoreExistingPackageErrors` flag.

## Execution Environment

Why `CommonJS` for node and `ESM` for the browser? Because [ESM in node is currently painful](https://github.com/OctopusDeploy/step-bootstrapper/blob/main/README.md#execution-environment).

## Conventions

Step Packages are expected to follow these conventions:

- There is a `metadata.json` file that adheres to either the [Step Metadata Schema](https://github.com/OctopusDeploy/step-api/blob/53382d758f428c82cf9771279e3f731fca594bf1/packages/build/src/step-metadata.json) or the [Target Metadata Schema](https://github.com/OctopusDeploy/step-api/blob/53382d758f428c82cf9771279e3f731fca594bf1/packages/build/src/deployment-target-metadata.json)
- The executor is the default export of `executor.ts`
- The validator is the default export of `validator.ts`
- The UI is the default export of `ui.ts`
- The input type schema root is the default export of `input.ts`
- A logo is available as `logo.svg`
- All the above files are located alongside `metadata.json` in a single directory.

Multiple steps and deployment targets may exist in a Step Package, but they must exist in separate directories within it. See the [Step Package Template Repository](https://github.com/OctopusDeploy/step-package-template) for a sample repository structure.

Code within the step package can be broken down into an arbitrary number of `ts` files, but the expected root files listed above must exist at the step root directory, and they must contain the expected default exports.

If these conventions are not followed, the CLI build will fail.

## Additional Configuration

If a step package needs to supply additional configuration to esbuild (for example, to specify some external packages to ignore), it can provide a `step-package.json`, and declare a subset of the options available on `esbuild.BuildOptions`. This configuration will be contributed to the build of all of the components within the step package.