# Deployment and Promotion Runbook

> [!CAUTION]
> **🧪 EXPERIMENTAL — LABS PROJECT**
> This package is not production-ready. No stability guarantees, no support, no warranty. See [README](../README.md) for full disclaimer.

Direct-cutover runbook for promoting Fluent Commerce module changes across environments (`dev -> staging -> prod`) with clear artifacts, commands, verification, and rollback.

## Who This Is For

- Release managers promoting module/workflow changes.
- Engineers running manual deployments or CI/CD deployments.
- Teams that need a single, practical guide for what to run and what gets created.

## Direct-Cutover Scope

- This runbook assumes a direct cutover approach.
- Use one current module version and one current workflow version per environment.
- Promotions move forward environment by environment with explicit verification gates.

## Promotion Models

Use one model consistently for a release:

- **Single-retailer model:** deploy all assets directly to one retailer.
- **Global + operational model:** deploy master data first to the global retailer, then deploy operational assets to operational retailers.

## Required Inputs

| Input | Example |
|---|---|
| Profile | `MY_PROFILE` |
| Retailer ref | `MY_RETAILER` |
| Module ZIP | `dist/my-module-1.2.4.zip` |
| Config file | `module.config.MY_RETAILER.dev.json` |
| Environment-specific config files | `module.config.MY_RETAILER.staging.json`, `module.config.MY_RETAILER.prod.json` |

## Artifacts Created During Promotion

| Stage | Artifact | Path |
|---|---|---|
| Build | Module package | `dist/<module-name>-<version>.zip` |
| Config prep | Environment config files | `module.config.<RETAILER>.<env>.json` |
| Pre-deploy backup | Workflow JSON backups | `backup/<timestamp>/<RETAILER>/*.json` |
| Diagnostics (`flow-run`) | Machine-readable diagnostics report | `.fluent-ai-skills/flow-run-report-<timestamp>.json` |
| Deployment | Live environment changes (module assets) | Fluent platform (workflows, rules, settings, data assets based on include/exclude) |
| Verification | CLI output + workflow/event checks | Terminal/CI logs |

## Step-by-Step Promotion

### 1) Build the release artifact

From your module source repo:

```bash
cd plugins
mvn clean install
cd ..
./scripts/build-module.sh
```

Expected output:

- `dist/<module-name>-<version>.zip`

### 2) Validate environment context

```bash
fluent profile active
fluent module list -p <PROFILE>
fluent workflow list -p <PROFILE> -r <RETAILER_REF>
```

Confirm you are targeting the correct profile and retailer before deployment.

### 3) Back up current workflows

```bash
TS=$(date +%Y%m%d-%H%M%S)
mkdir -p "backup/$TS/<RETAILER_REF>"
fluent workflow download --profile <PROFILE> --retailer <RETAILER_REF> -w all -o "backup/$TS/<RETAILER_REF>/"
```

Windows note: workflow files are typically saved with sanitized names such as `ORDER__HD.json`.

### 4) Run diagnostics-only gate

```bash
npx @fluentcommerce/ai-skills flow-run \
  --profile <PROFILE> \
  --retailer <RETAILER_REF> \
  --module dist/<module-name>-<version>.zip \
  --config module.config.<RETAILER_REF>.<env>.json
```

Expected artifact:

- `.fluent-ai-skills/flow-run-report-<timestamp>.json`

### 5) Deploy

Use one of the following:

- **Guarded deploy via flow-run**

```bash
npx @fluentcommerce/ai-skills flow-run \
  --profile <PROFILE> \
  --retailer <RETAILER_REF> \
  --module dist/<module-name>-<version>.zip \
  --config module.config.<RETAILER_REF>.<env>.json \
  --deploy --yes
```

- **Direct CLI deploy**

```bash
fluent module install dist/<module-name>-<version>.zip \
  --profile <PROFILE> \
  --retailer <RETAILER_REF> \
  --config module.config.<RETAILER_REF>.<env>.json \
  --force
```

### 6) Post-deploy verification

```bash
fluent module list -p <PROFILE>
fluent workflow list -p <PROFILE> -r <RETAILER_REF>
```

Then run your smoke checks/E2E checks for the changed flows.

## Environment Promotion Sequence

Promote in this order:

```text
dev -> staging -> prod
```

For each environment:

1. Use the environment's profile/secrets.
2. Use that environment's config file (`module.config.<RETAILER>.<env>.json`).
3. Run diagnostics gate.
4. Deploy.
5. Verify.
6. Proceed to the next environment only after successful verification.

## Global + Operational Retailer Order

When using a global retailer pattern, deploy in this order:

1. **Global retailer data** (products, locations, inventory, core settings)
2. **Rules** (plugin JAR assets)
3. **Operational retailers** (workflows, workflow-fragments, settings, controls)

Reason:

- Operational retailers depend on global references.
- Workflows depend on rules being installed first.

## Selective Deployment Recipes

Deploy only specific assets when needed:

```bash
# Workflows + settings only
fluent module install dist/<module>.zip --profile <PROFILE> --retailer <RETAILER_REF> \
  --include workflows settings --force

# Exclude workflows
fluent module install dist/<module>.zip --profile <PROFILE> --retailer <RETAILER_REF> \
  --exclude workflows --force

# Data-only deployment
fluent module install dist/<module>.zip --profile <PROFILE> --retailer <RETAILER_REF> \
  --include locations products inventory --force
```

`--include` and `--exclude` are mutually exclusive in a single command.

## Rollback Playbook

If a release fails after deployment, use one of these:

### Option A: Redeploy previous module version

```bash
fluent module install dist/<module-name>-<previous-version>.zip \
  --profile <PROFILE> \
  --retailer <RETAILER_REF> \
  --force
```

### Option B: Restore workflow backup

1. Use workflow backups created in `backup/<timestamp>/<RETAILER_REF>/`.
2. Re-upload the required workflow JSON (for example via your workflow deployment process or REST upload).

Keep versioned release ZIPs and workflow backups for every promotion wave.

## CI/CD Implementation Pattern

Use environment-gated pipeline stages:

- `deploy-dev` -> `deploy-staging` -> `deploy-prod`
- Require manual approval on production environment.
- Store secrets per environment (do not reuse dev credentials in prod).

## Release Checklist

- [ ] Correct profile and retailer confirmed.
- [ ] New module ZIP built and versioned.
- [ ] Environment-specific config file selected.
- [ ] Workflow backup completed.
- [ ] Diagnostics report generated and reviewed.
- [ ] Deployment completed successfully.
- [ ] Post-deploy verification passed.
- [ ] Rollback artifacts (previous ZIP + workflow backups) available.

---

## Appendix: `flow-run` Command Reference

`flow-run` provides a structured execution pipeline for Fluent Commerce diagnostics and optional module deployment — a practical first step toward autonomous operations.

### Behavior

By default, `flow-run` performs **read-only diagnostics**. Write operations occur only when both `--deploy` and `--yes` flags are present.

### Usage

```bash
npx @fluentcommerce/ai-skills flow-run [options]
```

### Options

| Option | Description |
|---|---|
| `--profile <name>` | Fluent profile used for module/workflow checks |
| `--retailer <ref>` | Retailer ref used for workflow checks and deploy |
| `--module <name-or-path>` | Module package path/name for describe/install |
| `--config <file>` | Config file to scan for unresolved `[[...]]` placeholders |
| `--deploy` | Enables `fluent module install` step |
| `--yes` | Mandatory confirmation with `--deploy` |
| `--exclude-workflows` | Adds `--exclude workflows` to deploy command |
| `--force` | Adds `--force` to deploy command |
| `--report <path>` | Custom JSON report output path |
| `--official-server-name <n>` | MCP official server key in `.mcp.json` (default `fluent-mcp`) |
| `--extn-server-name <n>` | MCP extension server key in `.mcp.json` (default `fluent-mcp-extn`) |
| `--skip-mcp-check` | Skip `.mcp.json` validation |

### What Gets Checked

**Local checks:** `.mcp.json` presence and server key validation, unresolved placeholder detection in MCP env values and module config.

**Fluent CLI checks:** `fluent --version`, `fluent profile active`, optional `fluent module describe/list`, optional `fluent workflow list`.

**Optional deploy checks:** `fluent module install`, post-deploy module/workflow list verification.

### Report Output

Default path: `./.fluent-ai-skills/flow-run-report-<timestamp>.json`. Each report includes command metadata, check-by-check status, execution details, summary totals, and recommendations. Exits `0` when no failing checks; non-zero when any **failed** checks are present.

### Current Limits

`flow-run` does not yet auto-generate/repair workflow JSON, run MCP GraphQL/event tools end-to-end, auto-classify root cause from errors, auto-create version bump commits, or execute business smoke tests autonomously.

