@fluentcommerce/ai-skills 0.1.0

package/content/cli/skills/fluent-module-deploy/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: fluent-module-deploy
+description: Deploy Fluent Commerce modules (reference, extension, or data) to target retailers. Use when deploying, installing, or pushing modules to environments. Triggers on "deploy module", "install module", "push module", "module install".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <module-path> [--profile name] [--retailer ref]
+---
+
+# Module Deployment
+
+Deploy modules to Fluent Commerce environments with validation and verification.
+
+## Planning Gate
+
+**Before deploying any module, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.**
+
+**Module-deploy specific emphasis — ensure these are covered:**
+
+1. **Business Context (Section 1)** — what change this deployment delivers
+2. **Scope (Section 2)** — module name, version, type (reference/extension/data)
+3. **Impacted rulesets (Section 4.3)** — new rules being registered, existing rules being updated
+4. **Settings (Section 4.4)** — settings required by new/changed rules
+5. **Impacted workflows (Section 4.1)** — workflows that reference rules in this module
+6. **Impacted retailers (Section 4.8)** — profile, retailer ref, environment (sandbox/UAT/prod)
+7. **Deployment Sequence (Section 9)** — pre-checks (validation, build, tests) → deploy → verify
+8. **Rollback Plan (Section 10)** — previous module version to restore if deployment fails
+
+**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-module-deploy-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before running `fluent module install`. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+## When to Use
+
+- Deploying reference modules from Fluent repository
+- Installing custom extension modules
+- Promoting modules across environments (dev -> UAT -> prod)
+- Installing data modules
+
+## Prerequisites
+
+- [ ] Active profile set (`fluent profile use <name>`)
+- [ ] Module source available (name, URL, or local path)
+- [ ] Dependencies installed
+- [ ] Configuration values ready (if module requires config)
+- [ ] Module validation passed (check `accounts/<PROFILE>/analysis/module-validate/<name>.report.json` — `summary.status` should be `READY_FOR_BUILD`). Run `/fluent-module-validate` if report is missing or stale.
+
+## Cross-Platform Command Notes
+
+- Fluent CLI syntax is the same on macOS, Linux, and Windows.
+- Prefer `rg` for placeholder scans (`rg` works in Bash, zsh, and PowerShell).
+- For manifest existence checks, prefer reading `module.json` directly over shell-specific `ls` checks.
+
+## Module Type Detection
+
+Determine the module type before deploying -- each type has a different validation and deployment flow:
+
+| Type | Detection | Deployment Flow |
+|------|-----------|----------------|
+| **Reference** | Name is `core`, `fulfilment`, `order`, `inventory`, or a URL source | describe -> check deps -> config -> install |
+| **Extension** | Local path with `plugins/` directory | validate -> build -> package -> install from local ZIP |
+| **Data** | Local path with `resources/assets/` but no `plugins/` | validate module.json -> install from local path |
+
+**Reference module dependency order (mandatory):**
+
+| # | Module | Dependencies |
+|---|--------|-------------|
+| 1 | `core` | None (install first) |
+| 2 | `fulfilment` | core |
+| 3 | `order` | core + fulfilment |
+| 4 | `inventory` | core |
+| 5 | Custom extensions | Varies (check module.json `dependencies`) |
+
+Installing out of order will result in "dependency not installed" errors. Always verify dependencies via `fluent module list` before installing.
+
+## Deployment Workflow
+
+### Step 0: Verify CLI Available
+
+```bash
+fluent --version
+```
+
+If CLI is not found, **STOP**. The Fluent CLI is required for all module deployment operations (`fluent module install`, `fluent module list`, `fluent module config`). There is no MCP or REST API fallback for module deployment.
+
+### Step 1: Validate Prerequisites
+
+```bash
+# Check active context
+fluent profile active
+
+# Expected output:
+# Active profile: <profile-name>
+# Active retailer: <retailer-ref>
+```
+
+### Step 1.5: Validate Module Structure (local modules only)
+
+For local module paths (extension or data modules), run structural validation before deploying:
+
+**1. Check validation report:**
+
+Read `accounts/<PROFILE>/analysis/module-validate/<module-name>.report.json` if it exists.
+
+- If `summary.status == "READY_FOR_BUILD"` -- proceed
+- If `summary.status == "NEEDS_FIXES"` -- **STOP**. List the FAIL items from the report. Run `/fluent-module-validate` to refresh if the report is stale.
+- If report is missing -- **WARN** the user and recommend running `/fluent-module-validate` first. Ask for explicit confirmation before proceeding without validation.
+
+**2. Inline minimum checks** (always, regardless of report):
+
+- `resources/module.json` exists and parses as valid JSON
+- Has `name` field (non-empty string)
+- Has `version` field (matches semver `^\d+\.\d+\.\d+(-SNAPSHOT)?$`)
+- For **extension modules**: `plugins/pom.xml` exists, version in module.json matches parent POM version
+- For **data modules**: `resources/assets/` directory exists with at least one asset folder
+
+### Step 2: Verify Module
+
+**For reference modules:**
+```bash
+fluent module describe <module-name>
+```
+
+**For local modules:**
+- Read `<module-path>/resources/module.json` directly and confirm it parses as JSON.
+- Confirm the module type matches expectations (extension has `plugins/`, data has `resources/assets/`).
+
+### Step 3: Check Dependencies
+
+```bash
+# List installed modules
+fluent module list -p <profile-name>
+
+# Compare with module.json dependencies
+```
+
+If dependencies missing: install them first!
+
+**For reference modules**, enforce the dependency order:
+- Before `fulfilment`: verify `core` is installed
+- Before `order`: verify `core` AND `fulfilment` are installed
+- Before `inventory`: verify `core` is installed
+- Before custom extensions: verify all declared dependencies from `module.json` are installed
+
+### Step 4: Generate Configuration (if needed)
+
+```bash
+fluent module config <module-source> \
+  --retailer <retailer-ref> \
+  --profile <profile-name>
+```
+
+Output: `module.config.<retailer>.<module-name>.json`
+
+**Check for unreplaced tokens:**
+```bash
+rg '\[\[.*\]\]' module.config.*.json
+```
+
+```powershell
+# PowerShell
+Select-String -Path "module.config.*.json" -Pattern '\[\[.*\]\]'
+```
+
+### Step 5: Install Module
+
+**Basic installation:**
+```bash
+fluent module install <module-source> \
+  --retailer <retailer-ref> \
+  --profile <profile-name>
+```
+
+**With configuration:**
+```bash
+fluent module install <module-source> \
+  --config module.config.<retailer>.<module>.json \
+  --retailer <retailer-ref> \
+  --profile <profile-name>
+```
+
+**With filters:**
+```bash
+# Exclude workflows (useful for multi-retailer installs to avoid overwriting customizations)
+fluent module install <module> \
+  --exclude workflows \
+  --retailer <retailer-ref> \
+  --profile <profile-name>
+
+# Exclude multiple asset types
+fluent module install <module> \
+  --exclude workflows \
+  --exclude settings \
+  --retailer <retailer-ref> \
+  --profile <profile-name>
+
+# Include only a specific workflow
+fluent module install <module> \
+  --include workflows/fc-workflow-order-hd.json \
+  --retailer <retailer-ref> \
+  --profile <profile-name>
+```
+
+Filter paths match the module ZIP structure. Common filterable assets:
+- `workflows` — all workflow JSON files
+- `settings` — all Fluent Settings
+- `rules` — plugin JARs
+- `workflows/<specific-file>.json` — single workflow
+
+**Force reinstall:**
+```bash
+fluent module install <module> --force \
+  --retailer <retailer-ref> \
+  --profile <profile-name>
+```
+
+### Step 6: Verify Installation
+
+```bash
+# Check module installed
+fluent module list -p <profile-name>
+
+# Check workflows deployed
+fluent workflow list -p <profile-name> -r <retailer-ref>
+```
+
+## Common Module Sources
+
+| Type | Example |
+|------|---------|
+| Reference | `core`, `order`, `fulfilment`, `inventory` |
+| URL | `https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest` |
+| Local | `dist/my-module-1.0.0/`, `./my-extension.zip` |
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| No active profile | `fluent profile use <name> --retailer <ref>` |
+| Module not found | Check spelling, verify path exists |
+| Dependencies not met | Install required modules first |
+| Config missing keys | Edit config file, add missing values |
+| Module already installed | Use `--force` to reinstall |
+| Workflow conflicts | Use `--exclude workflows` |
+
+## Version Bumping (Custom Modules)
+
+**Any content change requires a version bump** — Java code, workflow JSONs, settings, or resources. Deploying the same version number results in `"already uploaded: Active - nothing more to do"` for the plugin JAR, and makes it impossible to track which version introduced a change.
+
+### When to Bump
+
+| Changed | Bump Required? | Reason |
+|---------|---------------|--------|
+| Java rule code | **YES** | JAR filename includes version; CLI skips upload if same version exists |
+| Workflow JSON in `resources/workflows/` | **YES** | Module version is the audit trail for what's deployed |
+| Settings in `resources/assets/settings/` | **YES** | Traceability — which version introduced the setting |
+| Any file in `resources/` | **YES** | Everything is packaged into the versioned ZIP |
+| Re-deploy unchanged content | NO | Use `--force` flag if re-install is truly needed |
+
+### Files to Keep in Sync
+
+For **extension modules** (with Java plugins), bump ALL of these:
+
+1. `resources/module.json` (`"version"` field)
+2. Parent `plugins/pom.xml` (top-level `<version>`)
+3. Each child module `pom.xml` (`types/`, `util/`, `rules/`)
+
+**All must match.** The CLI uses `module.json` version for the module-level check, while Maven uses the POM version for the JAR filename (`fc-module-<name>-<VERSION>.jar`). A mismatch causes the JAR upload to be silently skipped while the module version appears bumped.
+
+For **data modules** (no plugins), only `resources/module.json` needs bumping.
+
+### Bump Procedure
+
+```bash
+# 1. Bump module.json (edit manually or via script)
+# 2. Bump all POM files in one command:
+cd plugins/ && mvn versions:set -DnewVersion=<NEW_VERSION> -DgenerateBackupPoms=false
+
+# 3. Verify no files still reference the old version:
+grep -r "<OLD_VERSION>" plugins/*/pom.xml resources/module.json
+```
+
+After bumping, rebuild with Maven and repackage via the module build script.
+
+## Config Token Reference
+
+Common `[[placeholder]]` tokens in module config files:
+
+| Token | Description | Example |
+|-------|-------------|---------|
+| `[[retailer.id]]` | Target retailer's numeric ID | `5` |
+| `[[productCatalogue.ref]]` | Product catalogue reference | `PC:MASTER:5` |
+| `[[network.ref.hd]]` | HD fulfilment network | `B2C_HD_1` |
+| `[[network.ref.cc]]` | CC fulfilment network | `B2C_CC_1` |
+| `[[virtualCatalogue.ref]]` | Virtual catalogue | `BASE:1` |
+| `[[inventoryCatalogue.ref]]` | Inventory catalogue | `DEFAULT:1` |
+| `[[order.validation.gracePeriodSeconds]]` | Grace period timeout | `3600` |
+
+**Check for unreplaced tokens before deploying:**
+```bash
+rg '\[\[.*\]\]' module.config.*.json
+```
+
+```powershell
+# PowerShell
+Select-String -Path "module.config.*.json" -Pattern '\[\[.*\]\]'
+```
+
+## Config Prefix System
+
+Module config files use a prefix system to scope variable values:
+
+| Prefix | Applies To | Example |
+|--------|-----------|---------|
+| `default:` | All assets (workflows, settings, data) | `"default:carrier.ref": "CARRIER_STD"` |
+| `workflow:<type>:<subtype>:` | Specific workflow only | `"workflow:order:hd:network.ref": "NET_HD"` |
+| `setting:` | Settings only | `"setting:mySettingKey": "value"` |
+
+**Specificity rules:** More colons = higher specificity = wins. For `ORDER::HD`, the key `workflow:order:hd:network.ref` (2 levels) overrides `workflow:order:network.ref` (1 level) which overrides `default:network.ref` (0 levels).
+
+**Built-in auto-injected variables** (no config needed): `account.id`, `retailer.id`, `retailer.ref`, `retailer.name`.
+
+**Unresolved tokens** are left as-is -- the CLI does not error on missing variable values during substitution. Always scan for `[[...]]` tokens before deploying.
+
+## Post-Deploy: Workflow Deployment
+
+After deploying a module that includes new custom rules, workflows referencing those rules can now be deployed:
+
+1. Use `/fluent-workflow-deploy` to upload individual workflow definitions
+2. Or include workflows in the module itself (`resources/assets/workflows/`)
+3. Verify rules are registered: `plugin.list({ name: "<RuleName>" })`
+
+**Deployment order:** Module (registers rules) -> Workflows (reference rules) -> Settings (referenced by rules) -> E2E test
+
+## Best Practices
+
+1. **Always verify active profile** before installing
+2. **Verify CLI is available** (`fluent --version`) before any deployment
+3. **Test in dev** before promoting to production
+4. **Use `--exclude workflows`** for multi-retailer installations
+5. **Generate fresh config** for each environment
+6. **Check dependencies** before installation (especially reference module order)
+7. **Bump version** for every custom module redeploy
+8. **Check for unreplaced `[[...]]` tokens** before deploying config
+9. **Run `/fluent-module-validate`** before deploying local modules
+10. **Deploy module before workflows** if workflows reference new custom rules
+
+## Rollback
+
+To rollback a module deployment, redeploy the previous version of the module ZIP. The Fluent CLI does not have a built-in rollback command -- keep previous module ZIPs archived for recovery.

package/content/cli/skills/fluent-profile/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: fluent-profile
+description: Manage Fluent CLI profiles for connecting to Fluent Commerce accounts. Use for creating, updating, switching, listing, or exporting profiles. Triggers on "create profile", "switch profile", "list profiles", "export profile", "fluent profile".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <operation> [profile-name]
+---
+
+# Profile Management
+
+Manage Fluent CLI profiles for connecting to Fluent Commerce accounts.
+
+## When to Use
+
+- Creating new connection to Fluent account
+- Switching between environments (dev/UAT/prod)
+- Exporting credentials for Postman
+- Managing multiple accounts
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `fluent profile create` | Create new profile |
+| `fluent profile list` | List all profiles |
+| `fluent profile use` | Set active profile |
+| `fluent profile active` | Show current profile |
+| `fluent profile update` | Modify profile |
+| `fluent profile export` | Export for Postman |
+| `fluent profile clear` | Clear active context |
+
+## Operations
+
+### 1. Create Profile
+
+**Required information:**
+- Profile name (e.g., `cli-b2c`, `prod-au`)
+- Account ID
+- Base URL
+- Username & password
+- Client secret
+
+```bash
+fluent profile create <profile-name> \
+  --id <account-id> \
+  --base-url <base-url> \
+  --username <username> \
+  --password <password> \
+  --client-secret <client-secret>
+```
+
+**Example:**
+```bash
+fluent profile create cli-b2c \
+  --id ABC123 \
+  --base-url https://abc123.sandbox.api.fluentretail.com \
+  --username admin_user \
+  --password secret123 \
+  --client-secret abc123xyz
+```
+
+### 2. List Profiles
+
+```bash
+fluent profile list
+```
+
+**Output:**
+```
+PROFILE NAME       ACCOUNT ID    BASE URL
+cli-b2c            ABC123        https://abc123.sandbox.api.fluentretail.com
+prod-au            XYZ789        https://xyz789.api.fluentretail.com
+```
+
+### 3. Set Active Profile
+
+**Profile only:**
+```bash
+fluent profile use <profile-name>
+```
+
+**Profile + retailer:**
+```bash
+fluent profile use <profile-name> --retailer <retailer-ref>
+```
+
+### 4. Check Active Profile
+
+```bash
+fluent profile active
+```
+
+**Output:**
+```
+Active profile: cli-b2c
+Active retailer: b2c
+```
+
+### 5. Update Profile
+
+**Add user:**
+```bash
+fluent profile update <profile-name> \
+  --username <new-username> \
+  --password <new-password>
+```
+
+**Add retailer:**
+```bash
+fluent profile update <profile-name> \
+  --retailer <retailer-ref> \
+  --id <retailer-id> \
+  --username <retailer-admin> \
+  --password <password>
+```
+
+**Switch active user:**
+```bash
+fluent profile update <profile-name> --user <username>
+```
+
+### 6. Export Profile (Postman)
+
+```bash
+fluent profile export <profile-name> \
+  --format postman \
+  --retailer <retailer-ref>
+```
+
+**Output:** `postman.<profile>.<retailer>.environment.json`
+
+**Import into Postman:**
+1. Open Postman -> Environments -> Import
+2. Select exported file
+3. Environment ready for API testing
+
+### 7. Clear Active Profile
+
+```bash
+fluent profile clear
+```
+
+### 8. Purge Sessions
+
+Clean up old session files:
+```bash
+fluent profile purge-sessions
+```
+
+## Profile Storage
+
+Profiles stored in: `~/.fluentcommerce/<profile-name>/`
+
+```
+~/.fluentcommerce/
+├── cli-b2c/
+│   ├── profile.json
+│   ├── user.admin_user.json
+│   └── retailer.b2c.json
+└── .sessions/
+    └── <session-files>
+```
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| Profile already exists | Use different name or update existing |
+| Profile not found | Check name with `profile list` |
+| Authentication failed | Verify credentials, update profile |
+| No active profile | Use `profile use <name>` |
+| Retailer not found | Add with `profile update` |
+
+## Security Best Practices
+
+1. **Never log passwords** - Use `[REDACTED]` in any output
+2. **Protect profile directory** - `~/.fluentcommerce/` contains credentials
+3. **Environment-specific profiles** - Don't mix dev/prod
+4. **Handle exports carefully** - Postman files contain plain-text credentials
+5. **Rotate credentials regularly** - Update profiles with new passwords