feat(cap): list, tasks, pull commands and UX improvements

.changeset/cap-commerce-app-packages.md

@@ -0,0 +1,17 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-tooling-sdk': minor
+'b2c-vs-extension': minor
+---
+
+Add `cap` command topic for Commerce App Package (CAP) management.
+
+New commands:
+- `b2c cap validate` — validates CAP structure, manifest, and cartridge rules locally
+- `b2c cap package` — packages a CAP directory into a distributable `.zip`
+- `b2c cap install` — installs a CAP on an instance via WebDAV + `sfcc-install-commerce-app` job
+- `b2c cap uninstall` — uninstalls a CAP via `sfcc-uninstall-commerce-app` job
+
+New SDK exports in `@salesforce/b2c-tooling-sdk/operations/cap`: `validateCap`, `commerceAppInstall`, `commerceAppUninstall`, `commerceAppPackage`.
+
+The VS Code extension gains CAP directory detection (badge decoration) and an "Install Commerce App (CAP)" context menu action.

.changeset/cap-support-commands.md

@@ -0,0 +1,14 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-tooling-sdk': minor
+'@salesforce/b2c-dx-docs': patch
+---
+
+Add `cap list`, `cap tasks`, and `cap pull` commands for managing installed Commerce Apps
+
+- `cap list` exports and parses `commerce_feature_states` to show installed features with type, source, status, and version
+- `cap tasks` displays configuration tasks for an installed app with clickable Business Manager links
+- `cap pull` downloads and extracts installed app source packages for cartridge deployment or Storefront Next development
+- Standardize all cap commands to use `--site-id` flag (with `--site` as alias)
+- `cap uninstall` no longer requires `--domain` — looks it up automatically from the feature state
+- `cap install` now keeps the archive on the instance by default (use `--clean-archive` to remove)

docs/.vitepress/config.mts

@@ -73,6 +73,7 @@ const guidesSidebar = [
       {text: 'Security', link: '/guide/security'},
       {text: 'Storefront Next', link: '/guide/storefront-next'},
       {text: 'MRT Utilities', link: '/guide/mrt-utilities'},
+      {text: 'Commerce Apps (CAPs)', link: '/guide/commerce-apps'},
     ],
   },
   {
@@ -103,6 +104,7 @@ const referenceSidebar = [
       {text: 'Auth', link: '/cli/auth'},
       {text: 'BM Roles', link: '/cli/bm-roles'},
       {text: 'CIP', link: '/cli/cip'},
+      {text: 'CAP (Commerce Apps)', link: '/cli/cap'},
       {text: 'Code', link: '/cli/code'},
       {text: 'Content', link: '/cli/content'},
       {text: 'Custom APIs', link: '/cli/custom-apis'},

docs/cli/cap.md

@@ -0,0 +1,347 @@
+---
+description: Commands for validating, packaging, installing, uninstalling, and listing Commerce App Packages (CAPs) and commerce features.
+---
+
+# Commerce App (CAP) Commands
+
+Commands for managing Commerce App Packages (CAPs) — the standard format for distributing B2C Commerce integrations — and listing commerce features installed on an instance.
+
+## Overview
+
+A Commerce App Package bundles cartridges, IMPEX data, and Storefront Next extensions into a single installable unit. See the [Commerce Apps guide](/guide/commerce-apps) for full workflow details.
+
+The `cap list` and `cap tasks` commands work with the broader commerce feature state system, which tracks all installed features including ISV apps, native apps, native features, and custom features.
+
+## Authentication
+
+Install, uninstall, list, and tasks commands require OAuth authentication with OCAPI permissions and WebDAV access.
+
+### Required OCAPI Permissions
+
+Configure these resources in Business Manager under **Administration** > **Site Development** > **Open Commerce API Settings**:
+
+| Resource | Methods | Commands |
+|----------|---------|----------|
+| `/jobs/*/executions` | POST | `cap install`, `cap uninstall`, `cap list`, `cap tasks` |
+| `/jobs/*/executions/*` | GET | `cap install`, `cap uninstall`, `cap list`, `cap tasks` |
+| `/sites` | GET | `cap list` (when no `--site-id` specified) |
+
+### WebDAV Access
+
+The `cap install` command uploads the CAP zip to WebDAV (`Impex/commerce-apps/`) before triggering the install job. The `cap list`, `cap tasks`, and `cap uninstall` commands download site archive exports via WebDAV.
+
+---
+
+## b2c cap validate
+
+Validate the structure and manifest of a Commerce App Package (CAP).
+
+### Usage
+
+```bash
+b2c cap validate PATH
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `PATH` | Path to a CAP directory or `.zip` file |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output result as JSON |
+
+### Validation Checks
+
+**Errors** (blocking — must fix before install):
+
+- `commerce-app.json` must exist and be valid JSON
+- Manifest must include `id`, `name`, `version`, `domain` fields
+- `version` must be a valid semver string
+- `app-configuration/tasksList.json` must exist as a valid JSON array
+- Each task must have `taskNumber`, `name`, `description`, `link`
+- At least one of `cartridges/`, `storefront-next/`, or `impex/` must be present
+- No `pipeline/` directories in cartridges
+- No `*.ds` pipeline descriptor files
+- Site cartridges (`cartridges/site_cartridges/`) must not contain `controllers/`
+- `README.md` must exist
+
+**Warnings** (advisory):
+
+- `icons/icon.png` is recommended for marketplace listing
+- `impex/uninstall/` is recommended for clean removal
+
+### Examples
+
+```bash
+# Validate a local CAP directory
+b2c cap validate ./commerce-avalara-tax-app-v0.2.5
+
+# Validate a zipped CAP
+b2c cap validate ./commerce-avalara-tax-app-v0.2.5.zip
+
+# Machine-readable output
+b2c cap validate ./commerce-avalara-tax-app-v0.2.5 --json
+```
+
+---
+
+## b2c cap package
+
+Package a Commerce App directory into a distributable `.zip` file.
+
+### Usage
+
+```bash
+b2c cap package PATH [--output PATH]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `PATH` | Path to the CAP source directory |
+
+### Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output PATH` | `-o` | Output path (directory or `.zip` filename). Defaults to current directory. |
+| `--json` | | Output result as JSON |
+
+### Examples
+
+```bash
+# Package to current directory
+b2c cap package ./commerce-avalara-tax-app-v0.2.5
+
+# Package to a specific output directory
+b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist
+
+# Package with explicit zip filename
+b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip
+```
+
+---
+
+## b2c cap install
+
+Install a Commerce App Package on a B2C Commerce instance.
+
+### Usage
+
+```bash
+b2c cap install PATH --site-id SITE_ID
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `PATH` | Path to a CAP directory or `.zip` file |
+
+### Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--site-id SITE_ID` | `-s` | **Required.** Site ID to install the app on |
+| `--clean-archive` | | Delete the uploaded zip from the instance after install |
+| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
+| `--skip-validate` | | Skip CAP structure validation before install |
+| `--json` | | Output result as JSON |
+
+### Install Process
+
+1. Validates the CAP structure (unless `--skip-validate`)
+2. Packages the directory into a zip if a directory is provided
+3. Uploads the zip to WebDAV at `Impex/commerce-apps/{id}-v{version}.zip`
+4. Executes the `sfcc-install-commerce-app` system job
+5. Waits for job completion
+6. Archive is kept on the instance by default (use `--clean-archive` to remove)
+
+### Examples
+
+```bash
+# Install from a local directory
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch
+
+# Install from a zip
+b2c cap install ./commerce-avalara-tax-app-v0.2.5.zip --site-id RefArch
+
+# Install without running validation first
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate
+
+# Remove the uploaded archive after install
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --clean-archive
+```
+
+---
+
+## b2c cap uninstall
+
+Uninstall a Commerce App from a B2C Commerce instance. Looks up the app's domain automatically from the commerce feature state.
+
+### Usage
+
+```bash
+b2c cap uninstall APP_NAME --site-id SITE_ID
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `APP_NAME` | App ID to uninstall (from `commerce-app.json` `"id"` field, e.g. `avalara-tax`) |
+
+### Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--site-id SITE_ID` | `-s` | **Required.** Site ID to uninstall the app from |
+| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
+| `--json` | | Output result as JSON |
+
+### Examples
+
+```bash
+# Uninstall Avalara Tax from a site
+b2c cap uninstall avalara-tax --site-id RefArch
+```
+
+---
+
+## b2c cap list
+
+List commerce features installed on a B2C Commerce instance. Exports the `commerce_feature_states` data unit from each site and parses the results.
+
+### Usage
+
+```bash
+b2c cap list [--site-id SITE_IDS]
+```
+
+### Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--site-id SITE_IDS` | `-s` | Site IDs to query (comma-separated). If omitted, queries all sites. |
+| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
+| `--local` | `-l` | List locally detected Commerce App Packages (no instance required) |
+| `--json` | | Output result as JSON |
+
+### Table Columns
+
+| Column | Description |
+|--------|-------------|
+| Site ID | Site the feature is installed on (includes `Sites-` prefix) |
+| Name | Feature name (e.g. `avalara-tax`) |
+| Type | `ISV_APP`, `NATIVE_APP`, `NATIVE_FEATURE`, or `CUSTOM_FEATURE` |
+| Source | `CUSTOM` (uploaded via WebDAV) or `REGISTRY` (from App Registry) |
+| Install Status | e.g. `INSTALLED` |
+| Config Status | e.g. `NOT_CONFIGURED`, `CONFIGURED` |
+| Version | Feature version if available |
+| Installed At | Installation timestamp |
+
+### JSON Output
+
+With `--json`, returns the full feature state including `configTasks` (parsed JSON array of configuration steps) and `installationMetadata` (parsed JSON with job details, cartridge mappings, and IMPEX uninstall data).
+
+### Examples
+
+```bash
+# List all installed features across all sites
+b2c cap list
+
+# List features for specific sites
+b2c cap list --site-id RefArch,SiteGenesis
+
+# Machine-readable output with full details
+b2c cap list --json
+
+# List locally detected CAP directories
+b2c cap list --local
+```
+
+---
+
+## b2c cap tasks
+
+List configuration tasks for an installed Commerce App, with clickable links to Business Manager pages.
+
+### Usage
+
+```bash
+b2c cap tasks APP_NAME --site-id SITE_ID
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `APP_NAME` | Commerce App feature name (e.g. `avalara-tax`) |
+
+### Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--site-id SITE_ID` | `-s` | **Required.** Site ID to query |
+| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
+| `--json` | | Output result as JSON |
+
+### Examples
+
+```bash
+# Show configuration tasks for an installed app
+b2c cap tasks avalara-tax --site-id RefArch
+
+# Get tasks as JSON (includes full feature state)
+b2c cap tasks avalara-tax --site-id RefArch --json
+```
+
+---
+
+## b2c cap pull
+
+Pull installed Commerce App source packages from a B2C Commerce instance. By default, pulls all registry-sourced apps. Optionally specify a single app by name.
+
+Useful for deploying cartridges to a code version or working with Storefront Next extensions locally.
+
+### Usage
+
+```bash
+b2c cap pull [APP_NAME] [--site-id SITE_ID] [--output DIR]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `APP_NAME` | *(optional)* Commerce App feature name to pull (e.g. `avalara-tax`). If omitted, pulls all registry apps. |
+
+### Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--site-id SITE_ID` | `-s` | Site ID to query for installed apps. If omitted, queries all sites. |
+| `--output DIR` | `-o` | Output directory (default: `./commerce-apps`) |
+| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
+| `--json` | | Output result as JSON |
+
+### Examples
+
+```bash
+# Pull all registry apps to ./commerce-apps
+b2c cap pull
+
+# Pull a specific app by name
+b2c cap pull avalara-tax
+
+# Pull to a custom output directory
+b2c cap pull --output ./my-apps
+
+# Pull apps installed on a specific site
+b2c cap pull --site-id RefArch
+```