Skip to content

Commit ee735bb

Browse files
claveryclavery
authored
feat(cap): list, tasks, pull commands and UX improvements (#370)
* cap wip * wip: cap support checkpoint - list command, job log viewer, VS Code integration * feat(cap): add list, tasks, and pull commands with improved UX - cap list: export and parse commerce_feature_states for installed features - cap tasks: show config tasks with clickable BM links - cap pull: download and extract app source packages from instance or GitHub - Standardize --site-id flag across all cap commands (--site as alias) - cap uninstall: auto-resolve domain from feature state (drop --domain) - cap install: keep archive by default, upload to Impex/commerce-apps/ - Fix sites API select query (*) -> (**) and null XML parse handling - Remove stub fixture fallback from list operation - Export all CAP operations and types from SDK main index - Update CLI docs, skill, and add changeset * fix: CI failures — VS Extension onProgress→onPoll, exclude fixture .tsx from typecheck * chore: update bundled XSDs from DWAPP-26.5 docs archive New schemas: commercefeaturestate, storefronts Updated: abtest, bmext, library, order, pagemetatag, search2, sort
1 parent 60d2322 commit ee735bb

63 files changed

Lines changed: 4991 additions & 57 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
'@salesforce/b2c-cli': minor
3+
'@salesforce/b2c-tooling-sdk': minor
4+
'b2c-vs-extension': minor
5+
---
6+
7+
Add `cap` command topic for Commerce App Package (CAP) management.
8+
9+
New commands:
10+
- `b2c cap validate` — validates CAP structure, manifest, and cartridge rules locally
11+
- `b2c cap package` — packages a CAP directory into a distributable `.zip`
12+
- `b2c cap install` — installs a CAP on an instance via WebDAV + `sfcc-install-commerce-app` job
13+
- `b2c cap uninstall` — uninstalls a CAP via `sfcc-uninstall-commerce-app` job
14+
15+
New SDK exports in `@salesforce/b2c-tooling-sdk/operations/cap`: `validateCap`, `commerceAppInstall`, `commerceAppUninstall`, `commerceAppPackage`.
16+
17+
The VS Code extension gains CAP directory detection (badge decoration) and an "Install Commerce App (CAP)" context menu action.

‎.changeset/cap-support-commands.md‎

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

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ const guidesSidebar = [
7373
{text: 'Security', link: '/guide/security'},
7474
{text: 'Storefront Next', link: '/guide/storefront-next'},
7575
{text: 'MRT Utilities', link: '/guide/mrt-utilities'},
76+
{text: 'Commerce Apps (CAPs)', link: '/guide/commerce-apps'},
7677
],
7778
},
7879
{
@@ -103,6 +104,7 @@ const referenceSidebar = [
103104
{text: 'Auth', link: '/cli/auth'},
104105
{text: 'BM Roles', link: '/cli/bm-roles'},
105106
{text: 'CIP', link: '/cli/cip'},
107+
{text: 'CAP (Commerce Apps)', link: '/cli/cap'},
106108
{text: 'Code', link: '/cli/code'},
107109
{text: 'Content', link: '/cli/content'},
108110
{text: 'Custom APIs', link: '/cli/custom-apis'},

‎docs/cli/cap.md‎

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
---
2+
description: Commands for validating, packaging, installing, uninstalling, and listing Commerce App Packages (CAPs) and commerce features.
3+
---
4+
5+
# Commerce App (CAP) Commands
6+
7+
Commands for managing Commerce App Packages (CAPs) — the standard format for distributing B2C Commerce integrations — and listing commerce features installed on an instance.
8+
9+
## Overview
10+
11+
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.
12+
13+
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.
14+
15+
## Authentication
16+
17+
Install, uninstall, list, and tasks commands require OAuth authentication with OCAPI permissions and WebDAV access.
18+
19+
### Required OCAPI Permissions
20+
21+
Configure these resources in Business Manager under **Administration** > **Site Development** > **Open Commerce API Settings**:
22+
23+
| Resource | Methods | Commands |
24+
|----------|---------|----------|
25+
| `/jobs/*/executions` | POST | `cap install`, `cap uninstall`, `cap list`, `cap tasks` |
26+
| `/jobs/*/executions/*` | GET | `cap install`, `cap uninstall`, `cap list`, `cap tasks` |
27+
| `/sites` | GET | `cap list` (when no `--site-id` specified) |
28+
29+
### WebDAV Access
30+
31+
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.
32+
33+
---
34+
35+
## b2c cap validate
36+
37+
Validate the structure and manifest of a Commerce App Package (CAP).
38+
39+
### Usage
40+
41+
```bash
42+
b2c cap validate PATH
43+
```
44+
45+
### Arguments
46+
47+
| Argument | Description |
48+
|----------|-------------|
49+
| `PATH` | Path to a CAP directory or `.zip` file |
50+
51+
### Flags
52+
53+
| Flag | Description |
54+
|------|-------------|
55+
| `--json` | Output result as JSON |
56+
57+
### Validation Checks
58+
59+
**Errors** (blocking — must fix before install):
60+
61+
- `commerce-app.json` must exist and be valid JSON
62+
- Manifest must include `id`, `name`, `version`, `domain` fields
63+
- `version` must be a valid semver string
64+
- `app-configuration/tasksList.json` must exist as a valid JSON array
65+
- Each task must have `taskNumber`, `name`, `description`, `link`
66+
- At least one of `cartridges/`, `storefront-next/`, or `impex/` must be present
67+
- No `pipeline/` directories in cartridges
68+
- No `*.ds` pipeline descriptor files
69+
- Site cartridges (`cartridges/site_cartridges/`) must not contain `controllers/`
70+
- `README.md` must exist
71+
72+
**Warnings** (advisory):
73+
74+
- `icons/icon.png` is recommended for marketplace listing
75+
- `impex/uninstall/` is recommended for clean removal
76+
77+
### Examples
78+
79+
```bash
80+
# Validate a local CAP directory
81+
b2c cap validate ./commerce-avalara-tax-app-v0.2.5
82+
83+
# Validate a zipped CAP
84+
b2c cap validate ./commerce-avalara-tax-app-v0.2.5.zip
85+
86+
# Machine-readable output
87+
b2c cap validate ./commerce-avalara-tax-app-v0.2.5 --json
88+
```
89+
90+
---
91+
92+
## b2c cap package
93+
94+
Package a Commerce App directory into a distributable `.zip` file.
95+
96+
### Usage
97+
98+
```bash
99+
b2c cap package PATH [--output PATH]
100+
```
101+
102+
### Arguments
103+
104+
| Argument | Description |
105+
|----------|-------------|
106+
| `PATH` | Path to the CAP source directory |
107+
108+
### Flags
109+
110+
| Flag | Short | Description |
111+
|------|-------|-------------|
112+
| `--output PATH` | `-o` | Output path (directory or `.zip` filename). Defaults to current directory. |
113+
| `--json` | | Output result as JSON |
114+
115+
### Examples
116+
117+
```bash
118+
# Package to current directory
119+
b2c cap package ./commerce-avalara-tax-app-v0.2.5
120+
121+
# Package to a specific output directory
122+
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist
123+
124+
# Package with explicit zip filename
125+
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip
126+
```
127+
128+
---
129+
130+
## b2c cap install
131+
132+
Install a Commerce App Package on a B2C Commerce instance.
133+
134+
### Usage
135+
136+
```bash
137+
b2c cap install PATH --site-id SITE_ID
138+
```
139+
140+
### Arguments
141+
142+
| Argument | Description |
143+
|----------|-------------|
144+
| `PATH` | Path to a CAP directory or `.zip` file |
145+
146+
### Flags
147+
148+
| Flag | Short | Description |
149+
|------|-------|-------------|
150+
| `--site-id SITE_ID` | `-s` | **Required.** Site ID to install the app on |
151+
| `--clean-archive` | | Delete the uploaded zip from the instance after install |
152+
| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
153+
| `--skip-validate` | | Skip CAP structure validation before install |
154+
| `--json` | | Output result as JSON |
155+
156+
### Install Process
157+
158+
1. Validates the CAP structure (unless `--skip-validate`)
159+
2. Packages the directory into a zip if a directory is provided
160+
3. Uploads the zip to WebDAV at `Impex/commerce-apps/{id}-v{version}.zip`
161+
4. Executes the `sfcc-install-commerce-app` system job
162+
5. Waits for job completion
163+
6. Archive is kept on the instance by default (use `--clean-archive` to remove)
164+
165+
### Examples
166+
167+
```bash
168+
# Install from a local directory
169+
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch
170+
171+
# Install from a zip
172+
b2c cap install ./commerce-avalara-tax-app-v0.2.5.zip --site-id RefArch
173+
174+
# Install without running validation first
175+
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate
176+
177+
# Remove the uploaded archive after install
178+
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --clean-archive
179+
```
180+
181+
---
182+
183+
## b2c cap uninstall
184+
185+
Uninstall a Commerce App from a B2C Commerce instance. Looks up the app's domain automatically from the commerce feature state.
186+
187+
### Usage
188+
189+
```bash
190+
b2c cap uninstall APP_NAME --site-id SITE_ID
191+
```
192+
193+
### Arguments
194+
195+
| Argument | Description |
196+
|----------|-------------|
197+
| `APP_NAME` | App ID to uninstall (from `commerce-app.json` `"id"` field, e.g. `avalara-tax`) |
198+
199+
### Flags
200+
201+
| Flag | Short | Description |
202+
|------|-------|-------------|
203+
| `--site-id SITE_ID` | `-s` | **Required.** Site ID to uninstall the app from |
204+
| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
205+
| `--json` | | Output result as JSON |
206+
207+
### Examples
208+
209+
```bash
210+
# Uninstall Avalara Tax from a site
211+
b2c cap uninstall avalara-tax --site-id RefArch
212+
```
213+
214+
---
215+
216+
## b2c cap list
217+
218+
List commerce features installed on a B2C Commerce instance. Exports the `commerce_feature_states` data unit from each site and parses the results.
219+
220+
### Usage
221+
222+
```bash
223+
b2c cap list [--site-id SITE_IDS]
224+
```
225+
226+
### Flags
227+
228+
| Flag | Short | Description |
229+
|------|-------|-------------|
230+
| `--site-id SITE_IDS` | `-s` | Site IDs to query (comma-separated). If omitted, queries all sites. |
231+
| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
232+
| `--local` | `-l` | List locally detected Commerce App Packages (no instance required) |
233+
| `--json` | | Output result as JSON |
234+
235+
### Table Columns
236+
237+
| Column | Description |
238+
|--------|-------------|
239+
| Site ID | Site the feature is installed on (includes `Sites-` prefix) |
240+
| Name | Feature name (e.g. `avalara-tax`) |
241+
| Type | `ISV_APP`, `NATIVE_APP`, `NATIVE_FEATURE`, or `CUSTOM_FEATURE` |
242+
| Source | `CUSTOM` (uploaded via WebDAV) or `REGISTRY` (from App Registry) |
243+
| Install Status | e.g. `INSTALLED` |
244+
| Config Status | e.g. `NOT_CONFIGURED`, `CONFIGURED` |
245+
| Version | Feature version if available |
246+
| Installed At | Installation timestamp |
247+
248+
### JSON Output
249+
250+
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).
251+
252+
### Examples
253+
254+
```bash
255+
# List all installed features across all sites
256+
b2c cap list
257+
258+
# List features for specific sites
259+
b2c cap list --site-id RefArch,SiteGenesis
260+
261+
# Machine-readable output with full details
262+
b2c cap list --json
263+
264+
# List locally detected CAP directories
265+
b2c cap list --local
266+
```
267+
268+
---
269+
270+
## b2c cap tasks
271+
272+
List configuration tasks for an installed Commerce App, with clickable links to Business Manager pages.
273+
274+
### Usage
275+
276+
```bash
277+
b2c cap tasks APP_NAME --site-id SITE_ID
278+
```
279+
280+
### Arguments
281+
282+
| Argument | Description |
283+
|----------|-------------|
284+
| `APP_NAME` | Commerce App feature name (e.g. `avalara-tax`) |
285+
286+
### Flags
287+
288+
| Flag | Short | Description |
289+
|------|-------|-------------|
290+
| `--site-id SITE_ID` | `-s` | **Required.** Site ID to query |
291+
| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
292+
| `--json` | | Output result as JSON |
293+
294+
### Examples
295+
296+
```bash
297+
# Show configuration tasks for an installed app
298+
b2c cap tasks avalara-tax --site-id RefArch
299+
300+
# Get tasks as JSON (includes full feature state)
301+
b2c cap tasks avalara-tax --site-id RefArch --json
302+
```
303+
304+
---
305+
306+
## b2c cap pull
307+
308+
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.
309+
310+
Useful for deploying cartridges to a code version or working with Storefront Next extensions locally.
311+
312+
### Usage
313+
314+
```bash
315+
b2c cap pull [APP_NAME] [--site-id SITE_ID] [--output DIR]
316+
```
317+
318+
### Arguments
319+
320+
| Argument | Description |
321+
|----------|-------------|
322+
| `APP_NAME` | *(optional)* Commerce App feature name to pull (e.g. `avalara-tax`). If omitted, pulls all registry apps. |
323+
324+
### Flags
325+
326+
| Flag | Short | Description |
327+
|------|-------|-------------|
328+
| `--site-id SITE_ID` | `-s` | Site ID to query for installed apps. If omitted, queries all sites. |
329+
| `--output DIR` | `-o` | Output directory (default: `./commerce-apps`) |
330+
| `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
331+
| `--json` | | Output result as JSON |
332+
333+
### Examples
334+
335+
```bash
336+
# Pull all registry apps to ./commerce-apps
337+
b2c cap pull
338+
339+
# Pull a specific app by name
340+
b2c cap pull avalara-tax
341+
342+
# Pull to a custom output directory
343+
b2c cap pull --output ./my-apps
344+
345+
# Pull apps installed on a specific site
346+
b2c cap pull --site-id RefArch
347+
```

0 commit comments

Comments
 (0)