Skip to content

Commit 8592727

Browse files
claveryclavery
authored
Scaffolding framework for B2C Commerce components (#102)
* initial scaffolding work * wip scaffolding * refactoring scaffolding * scaffolding improvements * scaffolding wip * scaffolding docs and fix for working directory * service scaffold and cleanup * scaffold refactor * scaffold docs: add service scaffold and SDK programmatic API - Add service scaffold to built-in scaffolds tables - Document SDK programmatic API for non-CLI usage (MCP, IDE integrations) - Add scaffold module to typedoc entry points for API reference generation * add changeset for scaffolding framework * Remove b2c-cli references from scaffold post-instructions Use generic operation descriptions instead of specific CLI commands to keep scaffold content tool-agnostic. * Fix lint errors in scaffold commands Use export...from syntax for re-exports per unicorn/prefer-export-from rule.
1 parent 05fd75d commit 8592727

70 files changed

Lines changed: 8815 additions & 0 deletions

Some content is hidden

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

‎.changeset/scaffolding-framework.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 scaffolding framework for generating B2C Commerce components from templates. Includes 7 built-in scaffolds (cartridge, controller, hook, service, custom-api, job-step, page-designer-component) and support for custom project/user scaffolds. SDK provides programmatic API for IDE integrations and MCP servers.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,4 @@ dw.json
3030
dw.json*
3131
.env
3232
.config/wt.toml
33+
.b2c/

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ const guideSidebar = [
1515
text: 'Guides',
1616
items: [
1717
{ text: 'Authentication Setup', link: '/guide/authentication' },
18+
{ text: 'Scaffolding', link: '/guide/scaffolding' },
1819
{ text: 'IDE Support', link: '/guide/ide-support' },
1920
{ text: 'Security', link: '/guide/security' },
2021
],
@@ -42,6 +43,7 @@ const guideSidebar = [
4243
{ text: 'Custom APIs', link: '/cli/custom-apis' },
4344
{ text: 'SCAPI Schemas', link: '/cli/scapi-schemas' },
4445
{ text: 'Setup Commands', link: '/cli/setup' },
46+
{ text: 'Scaffold Commands', link: '/cli/scaffold' },
4547
{ text: 'Auth Commands', link: '/cli/auth' },
4648
{ text: 'Logging', link: '/cli/logging' },
4749
],

‎docs/api-readme.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ The SDK is organized into focused submodules that can be imported individually:
2929
├── /operations/mrt # Managed Runtime bundle operations
3030
├── /operations/ods # On-demand sandbox utilities
3131
│
32+
├── /scaffold # Scaffold discovery, generation, and validation
3233
├── /docs # B2C Script API documentation search
3334
└── /schemas # OpenAPI schema utilities
3435
```

‎docs/cli/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ These flags are available on all commands that interact with B2C instances:
4949
- [SLAS Commands](./slas) - Manage Shopper Login and Access Service (SLAS) API clients
5050
- [Custom APIs](./custom-apis) - SCAPI Custom API endpoint status
5151

52+
### Development
53+
54+
- [Scaffold Commands](./scaffold) - Generate cartridges, controllers, hooks, and more from templates
55+
5256
### Account Management
5357

5458
- [Account Manager Commands](./account-manager) - Manage Account Manager users, roles, and organizations

‎docs/cli/scaffold.md‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
---
2+
description: B2C CLI scaffold commands for generating cartridges, controllers, hooks, custom APIs, and other B2C Commerce components from templates.
3+
---
4+
5+
# Scaffold Commands
6+
7+
The `b2c scaffold` commands help you generate B2C Commerce components from templates (scaffolds). Built-in scaffolds include cartridges, controllers, hooks, custom APIs, job steps, and Page Designer components.
8+
9+
## Commands Overview
10+
11+
| Command | Description |
12+
|---------|-------------|
13+
| `b2c scaffold list` | List available scaffolds |
14+
| `b2c scaffold generate <id>` | Generate files from a scaffold |
15+
| `b2c scaffold info <id>` | Show scaffold details and parameters |
16+
| `b2c scaffold search <query>` | Search scaffolds by name/tags |
17+
| `b2c scaffold init <name>` | Create a custom scaffold |
18+
| `b2c scaffold validate <path>` | Validate a scaffold manifest |
19+
20+
## b2c scaffold list
21+
22+
List available project scaffolds with optional filtering.
23+
24+
### Usage
25+
26+
```bash
27+
b2c scaffold list [--category <category>] [--source <source>]
28+
```
29+
30+
### Flags
31+
32+
| Flag | Description |
33+
|------|-------------|
34+
| `--category`, `-c` | Filter by category: `cartridge`, `custom-api`, `page-designer`, `job`, `metadata` |
35+
| `--source`, `-s` | Filter by source: `built-in`, `user`, `project`, `plugin` |
36+
| `--columns` | Columns to display (comma-separated) |
37+
| `--extended`, `-x` | Show all columns including description and tags |
38+
39+
### Output
40+
41+
Default columns: `id`, `displayName`, `category`, `source`
42+
43+
Extended columns (with `-x`): adds `description`, `tags`, `path`
44+
45+
### Examples
46+
47+
```bash
48+
# list all available scaffolds
49+
b2c scaffold list
50+
51+
# list only cartridge scaffolds
52+
b2c scaffold list --category cartridge
53+
54+
# list project-local scaffolds
55+
b2c scaffold list --source project
56+
57+
# show extended information
58+
b2c scaffold list -x
59+
```
60+
61+
## b2c scaffold generate
62+
63+
Generate files from a scaffold template. You can also use the shorthand `b2c scaffold <id>`.
64+
65+
### Usage
66+
67+
```bash
68+
b2c scaffold generate <scaffoldId> [--name <name>] [--option key=value] [--output <dir>]
69+
b2c scaffold <scaffoldId> # shorthand
70+
```
71+
72+
### Arguments
73+
74+
| Argument | Description |
75+
|----------|-------------|
76+
| `scaffoldId` | ID of the scaffold to generate (required) |
77+
78+
### Flags
79+
80+
| Flag | Description |
81+
|------|-------------|
82+
| `--name`, `-n` | Primary name parameter (shorthand for `--option name=VALUE`) |
83+
| `--output`, `-o` | Output directory (defaults to scaffold default or current directory) |
84+
| `--option` | Parameter value in `key=value` format (repeatable) |
85+
| `--dry-run` | Preview files without writing them |
86+
| `--force`, `-f` | Skip prompts, use defaults, and overwrite existing files |
87+
88+
### Examples
89+
90+
```bash
91+
# generate a cartridge interactively
92+
b2c scaffold generate cartridge
93+
94+
# generate with name specified
95+
b2c scaffold cartridge --name app_custom
96+
97+
# generate with multiple options
98+
b2c scaffold generate controller --option controllerName=Account --option cartridgeName=app_custom
99+
100+
# preview what would be generated
101+
b2c scaffold generate cartridge --name app_custom --dry-run
102+
103+
# skip all prompts and use defaults
104+
b2c scaffold generate cartridge --name app_custom --force
105+
106+
# generate to a specific directory
107+
b2c scaffold generate cartridge --name app_custom --output ./src/cartridges
108+
```
109+
110+
## b2c scaffold info
111+
112+
Show detailed information about a scaffold including its parameters and usage.
113+
114+
### Usage
115+
116+
```bash
117+
b2c scaffold info <scaffoldId>
118+
```
119+
120+
### Arguments
121+
122+
| Argument | Description |
123+
|----------|-------------|
124+
| `scaffoldId` | ID of the scaffold to get info for (required) |
125+
126+
### Output
127+
128+
Displays:
129+
- Scaffold ID, category, source, and description
130+
- Tags (if any)
131+
- Parameters with types, requirements, defaults, and conditions
132+
- Usage example with required parameters
133+
- Post-generation instructions (if any)
134+
135+
### Examples
136+
137+
```bash
138+
# show info for the cartridge scaffold
139+
b2c scaffold info cartridge
140+
141+
# show info for the controller scaffold
142+
b2c scaffold info controller
143+
```
144+
145+
## b2c scaffold search
146+
147+
Search for scaffolds by name, description, or tags.
148+
149+
### Usage
150+
151+
```bash
152+
b2c scaffold search <query> [--category <category>]
153+
```
154+
155+
### Arguments
156+
157+
| Argument | Description |
158+
|----------|-------------|
159+
| `query` | Search query (required) |
160+
161+
### Flags
162+
163+
| Flag | Description |
164+
|------|-------------|
165+
| `--category`, `-c` | Filter results by category |
166+
167+
### Examples
168+
169+
```bash
170+
# search for scaffolds related to API
171+
b2c scaffold search api
172+
173+
# search within a specific category
174+
b2c scaffold search template --category page-designer
175+
```
176+
177+
## b2c scaffold init
178+
179+
Create a new custom scaffold template.
180+
181+
### Usage
182+
183+
```bash
184+
b2c scaffold init [name] [--project | --user | --output <dir>]
185+
```
186+
187+
### Arguments
188+
189+
| Argument | Description |
190+
|----------|-------------|
191+
| `name` | Name for the new scaffold (kebab-case, optional - prompts if not provided) |
192+
193+
### Flags
194+
195+
| Flag | Description |
196+
|------|-------------|
197+
| `--project` | Create in project scaffolds directory (`.b2c/scaffolds/`) |
198+
| `--user` | Create in user scaffolds directory (`~/.b2c/scaffolds/`) |
199+
| `--output`, `-o` | Custom output directory for the scaffold |
200+
| `--force`, `-f` | Overwrite existing scaffold if it exists |
201+
202+
### Examples
203+
204+
```bash
205+
# create a project-local scaffold interactively
206+
b2c scaffold init --project
207+
208+
# create a user scaffold with a specific name
209+
b2c scaffold init my-component --user
210+
211+
# create a scaffold in a custom directory
212+
b2c scaffold init my-scaffold --output ./custom-scaffolds
213+
```
214+
215+
## b2c scaffold validate
216+
217+
Validate a custom scaffold manifest and templates.
218+
219+
### Usage
220+
221+
```bash
222+
b2c scaffold validate <path> [--strict]
223+
```
224+
225+
### Arguments
226+
227+
| Argument | Description |
228+
|----------|-------------|
229+
| `path` | Path to the scaffold directory (required) |
230+
231+
### Flags
232+
233+
| Flag | Description |
234+
|------|-------------|
235+
| `--strict` | Treat warnings as errors |
236+
237+
### Validation Checks
238+
239+
- Manifest structure (scaffold.json)
240+
- Required fields and types
241+
- Parameter definitions and validation patterns
242+
- Template file existence
243+
- Orphaned template files
244+
- EJS syntax in templates
245+
246+
### Examples
247+
248+
```bash
249+
# validate a custom scaffold
250+
b2c scaffold validate ./.b2c/scaffolds/my-scaffold
251+
252+
# validate with strict mode
253+
b2c scaffold validate ./my-scaffold --strict
254+
```
255+
256+
## Built-in Scaffolds
257+
258+
| Scaffold | Category | Description |
259+
|----------|----------|-------------|
260+
| `cartridge` | cartridge | B2C cartridge with standard directory structure |
261+
| `controller` | cartridge | SFRA controller with route handlers and middleware |
262+
| `hook` | cartridge | Hook implementation with hooks.json registration |
263+
| `service` | cartridge | B2C web service using LocalServiceRegistry |
264+
| `custom-api` | cartridge | Custom SCAPI endpoint with OAS 3.0 schema |
265+
| `job-step` | cartridge | Custom job step with steptypes.json registration |
266+
| `page-designer-component` | cartridge | Page Designer component with meta/script/template |
267+
268+
Use `b2c scaffold info <id>` to see the parameters for each scaffold.

0 commit comments

Comments
 (0)