@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/docs/FLOW_RUN.md

@@ -1,142 +1,142 @@
-# flow-run Command Reference
-
-`flow-run` provides a structured execution pipeline for Fluent Commerce diagnostics and optional module deployment.
-
-It is designed as a practical first step toward autonomous operations:
-
-- run deterministic preflight checks
-- validate local config readiness
-- verify Fluent CLI context and environment access
-- optionally deploy a module with explicit confirmation
-- output a JSON report for auditing and automation
-
-## Behavior Summary
-
-By default, `flow-run` performs **read-only diagnostics**.
-
-Write operations occur only when both flags are present:
-
-- `--deploy`
-- `--yes`
-
-## Prerequisites
-
-- Node.js 18+
-- Fluent CLI installed and available on `PATH`
-- active Fluent profile/session configured (or explicit profile provided)
-- optional: `.mcp.json` in the project root if MCP readiness checks are required
-
-## 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 |
-| `--help` | Show command help |
-
-## Examples
-
-Diagnostics-only run:
-
-```bash
-npx @fluentcommerce/ai-skills flow-run \
-  --profile YOUR_PROFILE \
-  --retailer YOUR_RETAILER_REF \
-  --module dist/your-module.zip \
-  --config config/module.config.YOUR_RETAILER_REF.json
-```
-
-Deploy run with explicit confirmation:
-
-```bash
-npx @fluentcommerce/ai-skills flow-run \
-  --profile YOUR_PROFILE \
-  --retailer YOUR_RETAILER_REF \
-  --module dist/your-module.zip \
-  --config config/module.config.YOUR_RETAILER_REF.json \
-  --deploy \
-  --yes
-```
-
-Deploy while protecting workflows:
-
-```bash
-npx @fluentcommerce/ai-skills flow-run \
-  --profile YOUR_PROFILE \
-  --retailer YOUR_RETAILER_REF \
-  --module dist/module.zip \
-  --deploy \
-  --yes \
-  --exclude-workflows
-```
-
-## What Gets Checked
-
-Local checks:
-
-- `.mcp.json` presence and server key validation
-- unresolved placeholder detection in MCP env values (`YOUR_*`, `your-*`, `[[...]]`)
-- unresolved placeholder detection in module config (`[[...]]`)
-
-Fluent CLI checks:
-
-- `fluent --version`
-- `fluent profile active`
-- optional `fluent module describe <module>`
-- optional `fluent module list -p <profile>`
-- optional `fluent workflow list -p <profile> -r <retailer>`
-
-Optional deploy checks:
-
-- `fluent module install ...`
-- post-deploy module/workflow list verification
-
-## Report Output
-
-Default report path:
-
-```text
-./.fluent-ai-skills/flow-run-report-<timestamp>.json
-```
-
-Each report includes:
-
-- command metadata (`cwd`, timestamp, package version, options)
-- check-by-check status (`passed`, `warning`, `failed`, `skipped`)
-- command execution details (exit code, duration, sanitized stdout/stderr)
-- summary totals and overall outcome
-- recommendations
-
-## Exit Behavior
-
-- exits `0` when no failing checks remain
-- exits non-zero when any **failed** checks are present
-- warnings do not fail the process
-
-## Current Limits
-
-`flow-run` currently orchestrates deterministic CLI and config checks, but it does not yet:
-
-- auto-generate/repair workflow JSON or rulesets
-- run MCP GraphQL/event tools directly end-to-end
-- auto-classify root cause from workflowlog/error payloads
-- auto-create version bump commits or publish artifacts
-- execute environment-specific business smoke tests autonomously
-
-Use this command as a stable baseline for guarded execution and structured evidence collection.
+# flow-run Command Reference
+
+`flow-run` provides a structured execution pipeline for Fluent Commerce diagnostics and optional module deployment.
+
+It is designed as a practical first step toward autonomous operations:
+
+- run deterministic preflight checks
+- validate local config readiness
+- verify Fluent CLI context and environment access
+- optionally deploy a module with explicit confirmation
+- output a JSON report for auditing and automation
+
+## Behavior Summary
+
+By default, `flow-run` performs **read-only diagnostics**.
+
+Write operations occur only when both flags are present:
+
+- `--deploy`
+- `--yes`
+
+## Prerequisites
+
+- Node.js 18+
+- Fluent CLI installed and available on `PATH`
+- active Fluent profile/session configured (or explicit profile provided)
+- optional: `.mcp.json` in the project root if MCP readiness checks are required
+
+## 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 |
+| `--help` | Show command help |
+
+## Examples
+
+Diagnostics-only run:
+
+```bash
+npx @fluentcommerce/ai-skills flow-run \
+  --profile YOUR_PROFILE \
+  --retailer YOUR_RETAILER_REF \
+  --module dist/your-module.zip \
+  --config config/module.config.YOUR_RETAILER_REF.json
+```
+
+Deploy run with explicit confirmation:
+
+```bash
+npx @fluentcommerce/ai-skills flow-run \
+  --profile YOUR_PROFILE \
+  --retailer YOUR_RETAILER_REF \
+  --module dist/your-module.zip \
+  --config config/module.config.YOUR_RETAILER_REF.json \
+  --deploy \
+  --yes
+```
+
+Deploy while protecting workflows:
+
+```bash
+npx @fluentcommerce/ai-skills flow-run \
+  --profile YOUR_PROFILE \
+  --retailer YOUR_RETAILER_REF \
+  --module dist/module.zip \
+  --deploy \
+  --yes \
+  --exclude-workflows
+```
+
+## What Gets Checked
+
+Local checks:
+
+- `.mcp.json` presence and server key validation
+- unresolved placeholder detection in MCP env values (`YOUR_*`, `your-*`, `[[...]]`)
+- unresolved placeholder detection in module config (`[[...]]`)
+
+Fluent CLI checks:
+
+- `fluent --version`
+- `fluent profile active`
+- optional `fluent module describe <module>`
+- optional `fluent module list -p <profile>`
+- optional `fluent workflow list -p <profile> -r <retailer>`
+
+Optional deploy checks:
+
+- `fluent module install ...`
+- post-deploy module/workflow list verification
+
+## Report Output
+
+Default report path:
+
+```text
+./.fluent-ai-skills/flow-run-report-<timestamp>.json
+```
+
+Each report includes:
+
+- command metadata (`cwd`, timestamp, package version, options)
+- check-by-check status (`passed`, `warning`, `failed`, `skipped`)
+- command execution details (exit code, duration, sanitized stdout/stderr)
+- summary totals and overall outcome
+- recommendations
+
+## Exit Behavior
+
+- exits `0` when no failing checks remain
+- exits non-zero when any **failed** checks are present
+- warnings do not fail the process
+
+## Current Limits
+
+`flow-run` currently orchestrates deterministic CLI and config checks, but it does not yet:
+
+- auto-generate/repair workflow JSON or rulesets
+- run MCP GraphQL/event tools directly end-to-end
+- auto-classify root cause from workflowlog/error payloads
+- auto-create version bump commits or publish artifacts
+- execute environment-specific business smoke tests autonomously
+
+Use this command as a stable baseline for guarded execution and structured evidence collection.