@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/docs/DEPLOYMENT_PROMOTION_RUNBOOK.md

@@ -0,0 +1,218 @@
+# Deployment and Promotion Runbook
+
+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 | `HMDEV` |
+| Retailer ref | `HM_TEST` |
+| Module ZIP | `dist/my-module-1.2.4.zip` |
+| Config file | `module.config.HM_TEST.dev.json` |
+| Environment-specific config files | `module.config.HM_TEST.staging.json`, `module.config.HM_TEST.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.
+