Skip to content

Commit 59fe546

Browse files
claveryclavery
authored
feat: add content export and content list commands (#117)
* feat: add content export and content list commands Add `b2c content export` and `b2c content list` commands for working with Page Designer content libraries on B2C Commerce instances. SDK (operations/content module): - Library class: parse library XML into a mutable tree of pages, components, content assets, and static asset references - Filter/traverse/reset with hidden-state flags for efficient filtering - Generator-based iteration via nodes() and callback-based traverse() - Asset query extraction with wildcard (*) support for array traversal - toXMLString() serialization back to importable XML - getTreeString() with optional colorize function for terminal output - fetchContentLibrary(): fetch and parse from instance or local file - exportContent(): filter, download assets via WebDAV, write to disk CLI commands: - content export: export pages/content/components with their trees and static assets to a timestamped output directory (content-YYYYMMDDHHmmss) - content list: list/filter library content in table or tree view - Supports --library flag (also configurable via dw.json content-library or package.json b2c.contentLibrary) - Variadic positional args for content IDs (pages, content assets, or components) - Component IDs are promoted to root level for standalone export - Colored tree output via oclif ux.colorize (bold pages, cyan components, green assets, dim connectors) - Smart summary with separate counts per type - --dry-run, --regex, --folder, --offline, --library-file flags - --json structured output for both commands Config system: - Added contentLibrary to NormalizedConfig, DwJsonConfig, mapping, and PackageJsonSource allowlist Documentation and skills: - CLI reference docs (docs/cli/content.md) - Configuration guide updates for content-library field - VitePress sidebar entry - b2c-content user-facing skill * fix: resolve lint and formatting errors in content export command
1 parent 7452f6c commit 59fe546

File tree

26 files changed

+3558
-2
lines changed

26 files changed

+3558
-2
lines changed

‎.changeset/content-library-export.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@salesforce/b2c-cli': minor
3+
'@salesforce/b2c-tooling-sdk': minor
4+
---
5+
6+
Add `content export` and `content list` commands for exporting Page Designer pages with components and static assets from content libraries. Supports filtering by page ID (exact or regex), folder classification, offline mode, and dry-run preview.

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ const guideSidebar = [
6666
items: [
6767
{ text: 'Overview', link: '/cli/' },
6868
{ text: 'Code Commands', link: '/cli/code' },
69+
{ text: 'Content Commands', link: '/cli/content' },
6970
{ text: 'Job Commands', link: '/cli/jobs' },
7071
{ text: 'Logs Commands', link: '/cli/logs' },
7172
{ text: 'Sites Commands', link: '/cli/sites' },

‎docs/cli/content.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
description: Commands for exporting and listing Page Designer content from B2C Commerce content libraries.
3+
---
4+
5+
# Content Commands
6+
7+
Commands for working with Page Designer content libraries on B2C Commerce instances.
8+
9+
## Authentication
10+
11+
Content commands require OAuth authentication:
12+
13+
| Operation | Auth Required |
14+
|-----------|--------------|
15+
| `content export` | OAuth (OCAPI for export job + WebDAV for assets) |
16+
| `content list` | OAuth (OCAPI for export job) |
17+
18+
```bash
19+
export SFCC_CLIENT_ID=your-client-id
20+
export SFCC_CLIENT_SECRET=your-client-secret
21+
```
22+
23+
Both commands also support a `--library-file` flag for offline use with a local XML file, which skips authentication entirely.
24+
25+
For complete setup instructions, see the [Authentication Guide](/guide/authentication).
26+
27+
---
28+
29+
## b2c content export
30+
31+
Export Page Designer pages with their component trees and static assets from a content library.
32+
33+
The command fetches the library XML from the instance (via a site archive export job), parses the page/component tree structure, filters by the specified page IDs, downloads referenced static assets via WebDAV, and writes the result to a local directory as a re-importable site archive.
34+
35+
### Usage
36+
37+
```bash
38+
b2c content export [PAGES...] --library <library-id>
39+
```
40+
41+
### Arguments
42+
43+
| Argument | Description | Required |
44+
|----------|-------------|----------|
45+
| `PAGES` | One or more content IDs to export (pages, content assets, or components) | Yes |
46+
47+
### Flags
48+
49+
In addition to [global flags](./index#global-flags):
50+
51+
| Flag | Description | Default |
52+
|------|-------------|---------|
53+
| `--library` | Library ID or site ID. Also configurable via `content-library` in dw.json. | |
54+
| `--output`, `-o` | Output directory | `content-<timestamp>` |
55+
| `--site-library` | Treat the library as a site-private library | `false` |
56+
| `--asset-query`, `-q` | JSON dot-paths for static asset extraction (can be repeated) | `image.path` |
57+
| `--regex`, `-r` | Treat page IDs as regular expressions | `false` |
58+
| `--folder` | Filter by folder classification (can be repeated) | |
59+
| `--offline` | Skip asset downloads | `false` |
60+
| `--library-file` | Use a local library XML file instead of fetching from instance | |
61+
| `--keep-orphans` | Include orphan components (not linked to any page) in export | `false` |
62+
| `--show-tree` | Display tree structure of exported content | `true` |
63+
| `--timeout` | Export job timeout in seconds | |
64+
| `--dry-run` | Preview export without downloading assets or writing files | `false` |
65+
66+
### Examples
67+
68+
```bash
69+
# Export a single page from a shared library
70+
b2c content export homepage --library SharedLibrary --server my-sandbox.demandware.net
71+
72+
# Export multiple pages
73+
b2c content export homepage about-us contact --library SharedLibrary
74+
75+
# Export pages matching a regex pattern
76+
b2c content export "hero-.*" "promo-.*" --library SharedLibrary --regex
77+
78+
# Export a specific component by ID
79+
b2c content export hero-banner --library SharedLibrary
80+
81+
# Export from a site-private library
82+
b2c content export homepage --library RefArch --site-library -o ./export
83+
84+
# Preview what would be exported without downloading
85+
b2c content export homepage --library SharedLibrary --dry-run
86+
87+
# Export with JSON output
88+
b2c content export homepage --library SharedLibrary --json
89+
90+
# Export from a local XML file (no instance connection needed)
91+
b2c content export homepage --library SharedLibrary --library-file ./library.xml --offline
92+
93+
# Filter by folder classification
94+
b2c content export homepage --library SharedLibrary --folder seasonal --folder holiday
95+
96+
# Custom asset extraction paths
97+
b2c content export homepage --library SharedLibrary -q "image.path" -q "video.url"
98+
99+
# Using environment variables and dw.json config
100+
export SFCC_SERVER=my-sandbox.demandware.net
101+
export SFCC_CLIENT_ID=your-client-id
102+
export SFCC_CLIENT_SECRET=your-client-secret
103+
b2c content export homepage
104+
```
105+
106+
### Output
107+
108+
The command displays:
109+
110+
1. A tree visualization of the exported content (pages, components, and assets)
111+
2. Asset download progress with success/failure indicators
112+
3. A summary line listing counts by type, e.g.: `Exported: 2 pages, 1 content asset, 5 components, 3 static assets to ./export`
113+
114+
With `--json`, returns a structured result including the library tree, output path, downloaded/failed asset lists, and counts.
115+
116+
### Notes
117+
118+
- The `--library` flag can be set in `dw.json` as `content-library` or in `package.json` under `b2c.contentLibrary` to avoid passing it every time
119+
- Use `b2c content list` to discover available page IDs before exporting
120+
- You can export pages, content assets, or individual components by their content ID. When a component ID is specified, it is promoted to the root of the export with its full child tree
121+
- The `--asset-query` flag specifies JSON dot-notation paths within component data to extract static asset references. The default `image.path` covers the common Page Designer image component pattern
122+
- Use `*` in asset query paths to traverse arrays (e.g., `slides.*.image.path`)
123+
124+
---
125+
126+
## b2c content list
127+
128+
List pages and content items in a content library. Useful for discovering page IDs before running an export.
129+
130+
### Usage
131+
132+
```bash
133+
b2c content list --library <library-id>
134+
```
135+
136+
### Flags
137+
138+
In addition to [global flags](./index#global-flags):
139+
140+
| Flag | Description | Default |
141+
|------|-------------|---------|
142+
| `--library` | Library ID or site ID. Also configurable via `content-library` in dw.json. | |
143+
| `--site-library` | Treat the library as a site-private library | `false` |
144+
| `--library-file` | Use a local library XML file instead of fetching from instance | |
145+
| `--type` | Filter by node type: `page`, `content`, or `component` | |
146+
| `--components` | Include components in table output | `false` |
147+
| `--tree` | Show tree structure instead of table | `false` |
148+
| `--timeout` | Job timeout in seconds | |
149+
150+
### Examples
151+
152+
```bash
153+
# List all content in a library
154+
b2c content list --library SharedLibrary --server my-sandbox.demandware.net
155+
156+
# List only pages
157+
b2c content list --library SharedLibrary --type page
158+
159+
# List including components
160+
b2c content list --library SharedLibrary --components
161+
162+
# Show tree structure
163+
b2c content list --library SharedLibrary --tree
164+
165+
# List from a site-private library
166+
b2c content list --library RefArch --site-library
167+
168+
# List from a local XML file
169+
b2c content list --library SharedLibrary --library-file ./library.xml
170+
171+
# JSON output
172+
b2c content list --library SharedLibrary --json
173+
```
174+
175+
### Output
176+
177+
Default table output:
178+
179+
```
180+
ID TYPE TYPE ID CHILDREN
181+
homepage PAGE page.storePage 5
182+
about-us PAGE page.storePage 3
183+
footer CONTENT 2
184+
```
185+
186+
With `--components`, components are included in the table output alongside pages and content items.
187+
188+
With `--tree`, displays a hierarchical tree visualization:
189+
190+
```
191+
homepage (typeId: page.storePage)
192+
├── component.heroBanner (hero-banner)
193+
│ └── /images/hero.jpg (STATIC ASSET)
194+
└── component.productGrid (product-grid)
195+
about-us (typeId: page.storePage)
196+
└── component.textBlock (text-block)
197+
└── /images/about.png (STATIC ASSET)
198+
footer-content (CONTENT ASSET)
199+
```
200+
201+
Pages show `id (typeId: type)`, components show `typeId (id)`, content assets show `id (CONTENT ASSET)`, and static assets show `path (STATIC ASSET)`. The tree uses color when output to a terminal: page names are bold, component type IDs are cyan, asset paths are green, and tree connectors are dim.
202+
203+
With `--json`, returns `{ data: [...] }` with each item containing `id`, `type`, `typeId`, and `children` count.

‎docs/guide/configuration.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ If no instance is specified, the config with `"active": true` is used.
168168
| `auth-methods` | Authentication methods in priority order (array of strings) |
169169
| `account-manager-host` | Account Manager hostname for OAuth |
170170
| `shortCode` | SCAPI short code. Also accepts `short-code` or `scapi-shortcode`. |
171+
| `content-library` | Default content library ID for `content export` and `content list` commands |
171172
| `tenant-id` | Organization/tenant ID for SCAPI |
172173
| `sandbox-api-host` | ODS (sandbox) API hostname |
173174
| `mrtApiKey` | MRT API key |
@@ -232,6 +233,7 @@ Only non-sensitive, project-level fields can be configured in `package.json`. Bo
232233
|-------|-------------|
233234
| `shortCode` | SCAPI short code |
234235
| `clientId` | OAuth client ID (for implicit login discovery) |
236+
| `contentLibrary` | Default content library ID for `content export` and `content list` commands |
235237
| `mrtProject` | MRT project slug |
236238
| `mrtOrigin` | MRT API origin URL override |
237239
| `accountManagerHost` | Account Manager hostname for OAuth |

‎packages/b2c-cli/package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,9 @@
104104
"code": {
105105
"description": "Deploy and manage code versions on instances\n\nDocs: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/code.html"
106106
},
107+
"content": {
108+
"description": "Export and manage Page Designer content libraries"
109+
},
107110
"docs": {
108111
"description": "Search and read Script API documentation"
109112
},

0 commit comments

Comments
 (0)