@arc-fusion/cli/MAINTAINERS.md

CLI for running Arc Fusion on your local machine

# Getting Started

Since this package is published to npm, the README.md is publicly available.

## Running the Application Locally

### System Requirements

The following dependencies are required for the `@arc-fusion/cli` to function properly:

- [node](https://nodejs.org/en/download/) - This should be the same version of Node as the PageBuilder Engine version you are using
- [npm](https://docs.npmjs.com/getting-started/installing-node) - This should be the default version provided by node
- [docker 17.06+](https://docs.docker.com/install/)

### Development

- Clone this repository: `git clone https://github.com/WPMedia/fusion-cli.git`
- Run `npm link` from inside this repository
- Create a new PageBuilder bundle in another directory (or download a test bundle)
- Run `npm link @arc-fusion/cli` from within that PageBuilder bundle directory
- When you run `npx fusion <command>` from inside your PageBuilder bundle, it will invoke your local CLI code, so any changes you make should be immediately reflected.

### Contributing

When you are done with your updates and ready to submit a PR, ensure that you create a changeset by running `npx changeset add`.  This will ensure that your PR does not automatically trigger a production release.

### Linking

If you are using another npm package and need to test local changes, you will need to use `npm link`. Follow the steps below to understand how to do this.

1. Make sure your node and npm version matches the version used by the `FUSION_RELEASE` image
2. Go to the folder containing your package and npm `npm link`
3. Go to the folder containing your bundle and run `npm link [package name]`
4. If this package is published, make sure it is in the `dependencies` object in your `package.json` file
5. If this package is not published, add it to the `devDependencies` object in your `package.json` file manually (don't use `npm i -D`), and save it
6. Start fusion via `npx fusion start`

## Deployment

Releases are automated via the `npm-deploy` GitHub Actions workflow using [Changesets](https://github.com/changesets/changesets) and OIDC authentication to npm (no npm token secrets required).

### Creating a changeset

Before submitting a PR that should trigger a release, run `npx changeset add` and follow the prompts to select a semver bump level and describe the change. This creates a markdown file in `.changeset/` that should be committed with your PR.

### Canary releases

When a PR **with a changeset** is merged to `master`, the `canary` job:

1. Detects pending changeset files — if none exist the job exits without publishing
2. Runs tests and builds
3. Creates a snapshot version (e.g. `3.3.0-canary-20260330181951`)
4. Publishes to npm with the `canary` and `beta` dist-tags via OIDC

Install a canary release with:

```sh
npm install @arc-fusion/cli@canary
```

PRs merged **without a changeset** do not trigger any publish.

### Production (stable) releases

Automated PR creation via `changesets/action` is disabled in this repo, so the "Version Packages" PR must be created manually:

1. Check out a new branch from `master`
2. Run `npx changeset version` — this consumes the pending changeset files, bumps `package.json`, and updates the changelog
3. Commit the resulting changes and push the branch
4. Open a PR titled **"Version Packages"** targeting `master`

When that PR is merged, the `release` job detects that there are no remaining changeset files and runs `changeset publish`, which publishes to npm with the `stable` dist-tag via OIDC.

### Dist-tags summary

| Tag | When | Install command |
|-----|------|-----------------|
| `canary` | Every PR merge with a changeset | `npm install @arc-fusion/cli@canary` |
| `beta` | Same as canary (alias) | `npm install @arc-fusion/cli@beta` |
| `stable` | "Version Packages" PR merge | `npm install @arc-fusion/cli@stable` |
| `latest` | "Version Packages" PR merge (npm default) | `npm install @arc-fusion/cli` |

## Architecture

The `@arc-fusion/cli` package is a CLI tool that orchestrates a local PageBuilder development stack using Docker.

![Fusion CLI Architecture Diagram](https://github.com/user-attachments/assets/28bbf52b-e02a-4eae-9ca3-e786e07029ee)

### Containers / Components

When the local PageBuilder stack is running via the `npx fusion start` command, the following Docker containers are created:

| CONTAINER          | DESCRIPTION   |
|--------------------|---------------|
| [fusion-data]      | This is the MongoDB service used by Editor and Engine (in localhost only) |
| [fusion-cache]     | This is the in-memory caching service used by engine to cache content from Content Sources |
| [fusion-cache-proxy] | This is the cache proxy layer used by engine that allows Lambda to interact with ElastiCache |
| [fusion-webpack]     | This is used to compile the React components in the customer’s bundle (features, chains, layouts, output types, content sources) |
| [fusion-themes]      | This is used to compile styles from Themes Blocks and Components, as well as custom styles in the customer's bundle |
| [fusion-engine]      | This is the rendering engine, which takes a Rendering object and renders HTML from the React components in the customer’s bundle |
| [fusion-resolver]    | This service is responsible for resolving a URL to a Page/Template and a Content Source |
| [fusion-origin]      | This service proxies requests to the `fusion-engine` and `fusion-admin` services |
| [fusion-admin]       | This service is the backend for PageBuilder Editor |
| [fusion-cli-api]     | This service uses `CONTENT_BASE` and `ARC_ACCESS_TOKEN` env variables to proxy to Arc services integrated into PageBuilder Editor during local development. |

## Testing

- Run `npm link` from this repository
- Run `npm link @arc-fusion/cli` from within a local PageBuilder bundle directory
- Run the command you need to test with `npx fusion <command>`


[fusion-data]: https://github.com/wpmedia/mongo-vandelay/
[fusion-cache]: https://hub.docker.com/_/memcached
[fusion-cache-proxy]: https://github.com/wpmedia/pagebuilder-cache-proxy
[fusion-webpack]: https://github.com/wpmedia/pagebuilder-compiler
[fusion-themes]: https://github.com/WPMedia/arc-themes-stylebuilder
[fusion-engine]: https://github.com/WPMedia/pagebuilder-engine
[fusion-resolver]: https://github.com/WPMedia/pagebuilder-resolver
[fusion-origin]: https://github.com/WPMedia/pagebuilder-origin
[fusion-admin]: https://github.com/WPMedia/pb-admin-api
[fusion-cli-api]: https://github.com/WPMedia/fusion-cli-api