Skip to content

Commit 758709b

Browse files
claveryclavery
committed
code operations wip
1 parent b08b5d1 commit 758709b

File tree

26 files changed

+2312
-86
lines changed

26 files changed

+2312
-86
lines changed

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
- TypeDoc and vitepress will generate documentation from these comments in the `./docs/api` folder
1717
- module level jsdocs will be used for organization; for example packages/b2c-tooling/src/auth/index.ts barrel file has the module level docs for the `auth` module
1818
- see the typedoc.json file for configuration options including the entry points for documentation generation
19+
- update the docs/ markdown files (non-generated) for user guides and CLI reference when updating major CLI functionalty or adding new commands
1920

2021
## Logging
2122

‎_TODO.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
2+
# Benefits over sfcc-ci
3+
4+
- stateless auth by default
5+
- modern node (Typescript, async/await, etc)
6+
- separate CLI and SDK packages
7+
- structured logging, json output on all commands
8+
- specific errors (no more webdav generic error)
9+
- localization support
10+
- command organization
11+
- for instance separating AM management into it's own topic (client, user, role)
12+
13+
# Config
14+
15+
- [ ] package.json support
16+
17+
18+
# Auth
19+
20+
- [ ] implicit
21+
- [ ] JWT
22+
23+
# Commands
24+
25+
- [ ] code
26+
- [ ] jobs
27+
- [ ] mrt
28+
- [ ] validate
29+
- XML: libxmljs optional dependency?
30+
- JSON schema

‎docs/cli/code.md‎

Lines changed: 265 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,68 @@
22

33
Commands for managing cartridge code on B2C Commerce instances.
44

5+
## b2c code list
6+
7+
List all code versions on a B2C Commerce instance.
8+
9+
### Usage
10+
11+
```bash
12+
b2c code list
13+
```
14+
15+
### Flags
16+
17+
Uses [global instance and authentication flags](./index#global-flags).
18+
19+
### Examples
20+
21+
```bash
22+
# List code versions on an instance
23+
b2c code list --server my-sandbox.demandware.net --client-id xxx --client-secret yyy
24+
25+
# Output as JSON
26+
b2c code list --json
27+
28+
# Using environment variables
29+
export SFCC_SERVER=my-sandbox.demandware.net
30+
export SFCC_CLIENT_ID=your-client-id
31+
export SFCC_CLIENT_SECRET=your-client-secret
32+
b2c code list
33+
```
34+
35+
### Output
36+
37+
The command displays a table of code versions with:
38+
39+
- Code version ID
40+
- Active status
41+
- Rollback status
42+
- Last modification time
43+
- Number of cartridges
44+
45+
Example output:
46+
47+
```
48+
ID Active Rollback Last Modified Cartridges
49+
────────────────────────────────────────────────────────────────────────────────────
50+
version1 Yes No 11/29/2024, 2:30:00 PM 15
51+
version2 No Yes 11/28/2024, 10:15:00 AM 15
52+
staging No No 11/25/2024, 9:00:00 AM 12
53+
```
54+
55+
### Authentication
56+
57+
This command requires OAuth authentication. Provide `--client-id` and `--client-secret` or set the corresponding `SFCC_CLIENT_ID` and `SFCC_CLIENT_SECRET` environment variables.
58+
59+
---
60+
561
## b2c code deploy
662

763
Deploy cartridges to a B2C Commerce instance.
864

65+
This command finds cartridges in the specified directory (by looking for `.project` files), creates a zip archive, uploads it via WebDAV, and optionally reloads the code version.
66+
967
### Usage
1068

1169
```bash
@@ -16,24 +74,42 @@ b2c code deploy [CARTRIDGEPATH]
1674

1775
| Argument | Description | Default |
1876
|----------|-------------|---------|
19-
| `CARTRIDGEPATH` | Path to cartridges directory | `./cartridges` |
77+
| `CARTRIDGEPATH` | Path to search for cartridges | `.` (current directory) |
2078

2179
### Flags
2280

2381
In addition to [global flags](./index#global-flags):
2482

25-
| Flag | Short | Description |
26-
|------|-------|-------------|
27-
| `--code-version` | `-v` | Code version to deploy to (required) |
83+
| Flag | Short | Description | Default |
84+
|------|-------|-------------|---------|
85+
| `--reload` | `-r` | Reload (re-activate) code version after deploy | `false` |
86+
| `--delete` | | Delete existing cartridges before upload | `false` |
87+
| `--cartridge` | `-c` | Include specific cartridge(s) (can be repeated) | |
88+
| `--exclude-cartridge` | `-x` | Exclude specific cartridge(s) (can be repeated) | |
2889

2990
### Examples
3091

3192
```bash
32-
# Deploy from default ./cartridges directory
93+
# Deploy all cartridges from current directory
3394
b2c code deploy --server my-sandbox.demandware.net --code-version v1
3495

35-
# Deploy from custom path
36-
b2c code deploy ./my-cartridges --server my-sandbox.demandware.net --code-version v1
96+
# Deploy from a specific directory
97+
b2c code deploy ./my-project --server my-sandbox.demandware.net --code-version v1
98+
99+
# Deploy and reload the code version
100+
b2c code deploy --reload
101+
102+
# Deploy specific cartridges only
103+
b2c code deploy -c app_storefront_base -c plugin_applepay
104+
105+
# Deploy all except certain cartridges
106+
b2c code deploy -x test_cartridge -x int_debug
107+
108+
# Delete existing cartridges before upload
109+
b2c code deploy --delete
110+
111+
# Delete and reload
112+
b2c code deploy --delete --reload
37113

38114
# Using environment variables
39115
export SFCC_SERVER=my-sandbox.demandware.net
@@ -43,11 +119,189 @@ export SFCC_PASSWORD=my-access-key
43119
b2c code deploy
44120
```
45121

122+
### Cartridge Discovery
123+
124+
Cartridges are discovered by searching for `.project` files (Eclipse project markers commonly used in SFCC development). The directory containing the `.project` file is considered a cartridge.
125+
126+
### Authentication
127+
128+
This command requires both WebDAV and OAuth authentication:
129+
130+
- **WebDAV** (for file upload): Basic Auth (`--username`/`--password`) or OAuth
131+
- **OAuth** (for code version reload): `--client-id` and `--client-secret`
132+
133+
Basic authentication is recommended for WebDAV operations due to better performance.
134+
135+
---
136+
137+
## b2c code activate
138+
139+
Activate a code version on a B2C Commerce instance, or reload the current active version.
140+
141+
### Usage
142+
143+
```bash
144+
b2c code activate [CODEVERSION]
145+
```
146+
147+
### Arguments
148+
149+
| Argument | Description | Required |
150+
|----------|-------------|----------|
151+
| `CODEVERSION` | Code version ID to activate | No (required unless `--reload`) |
152+
153+
### Flags
154+
155+
In addition to [global flags](./index#global-flags):
156+
157+
| Flag | Short | Description | Default |
158+
|------|-------|-------------|---------|
159+
| `--reload` | `-r` | Reload the code version (toggle activation to force reload) | `false` |
160+
161+
### Examples
162+
163+
```bash
164+
# Activate a specific code version
165+
b2c code activate v2 --server my-sandbox.demandware.net
166+
167+
# Reload the current active code version (forces code refresh)
168+
b2c code activate --reload
169+
170+
# Reload a specific code version
171+
b2c code activate v1 --reload
172+
173+
# Using --code-version flag instead of argument
174+
b2c code activate --code-version v2
175+
```
176+
177+
### Reload vs Activate
178+
179+
- **Activate**: Sets the specified code version as the active version
180+
- **Reload**: Forces the instance to reload the code by temporarily activating a different version, then re-activating the target version
181+
182+
Use `--reload` when you've made changes via WebDAV and need the instance to pick up the changes without deploying again.
183+
184+
### Authentication
185+
186+
This command requires OAuth authentication. Provide `--client-id` and `--client-secret` or set the corresponding environment variables.
187+
188+
---
189+
190+
## b2c code delete
191+
192+
Delete a code version from a B2C Commerce instance.
193+
194+
### Usage
195+
196+
```bash
197+
b2c code delete CODEVERSION
198+
```
199+
200+
### Arguments
201+
202+
| Argument | Description | Required |
203+
|----------|-------------|----------|
204+
| `CODEVERSION` | Code version ID to delete | Yes |
205+
206+
### Flags
207+
208+
In addition to [global flags](./index#global-flags):
209+
210+
| Flag | Short | Description | Default |
211+
|------|-------|-------------|---------|
212+
| `--force` | `-f` | Skip confirmation prompt | `false` |
213+
214+
### Examples
215+
216+
```bash
217+
# Delete a code version (with confirmation prompt)
218+
b2c code delete old-version --server my-sandbox.demandware.net
219+
220+
# Delete without confirmation
221+
b2c code delete old-version --force
222+
```
223+
224+
### Notes
225+
226+
- You cannot delete the currently active code version
227+
- The command will prompt for confirmation unless `--force` is used
228+
229+
### Authentication
230+
231+
This command requires OAuth authentication. Provide `--client-id` and `--client-secret` or set the corresponding environment variables.
232+
233+
---
234+
235+
## b2c code watch
236+
237+
Watch cartridge directories and automatically upload changes to a B2C Commerce instance.
238+
239+
This command monitors cartridge files for changes and uploads them in real-time, making it ideal for development workflows.
240+
241+
### Usage
242+
243+
```bash
244+
b2c code watch [CARTRIDGEPATH]
245+
```
246+
247+
### Arguments
248+
249+
| Argument | Description | Default |
250+
|----------|-------------|---------|
251+
| `CARTRIDGEPATH` | Path to search for cartridges | `.` (current directory) |
252+
253+
### Flags
254+
255+
In addition to [global flags](./index#global-flags):
256+
257+
| Flag | Short | Description |
258+
|------|-------|-------------|
259+
| `--cartridge` | `-c` | Include specific cartridge(s) (can be repeated) |
260+
| `--exclude-cartridge` | `-x` | Exclude specific cartridge(s) (can be repeated) |
261+
262+
### Examples
263+
264+
```bash
265+
# Watch all cartridges in current directory
266+
b2c code watch --server my-sandbox.demandware.net --code-version v1
267+
268+
# Watch cartridges in a specific directory
269+
b2c code watch ./my-project
270+
271+
# Watch only specific cartridges
272+
b2c code watch -c app_storefront_base -c plugin_applepay
273+
274+
# Exclude certain cartridges from watching
275+
b2c code watch -x test_cartridge
276+
277+
# Using environment variables
278+
export SFCC_SERVER=my-sandbox.demandware.net
279+
export SFCC_CODE_VERSION=v1
280+
export SFCC_USERNAME=my-user
281+
export SFCC_PASSWORD=my-access-key
282+
b2c code watch
283+
```
284+
285+
### Behavior
286+
287+
- **File changes** (`add`, `change`): Batched and uploaded as a zip archive
288+
- **File deletions** (`unlink`): Deleted from the remote server
289+
- **Debouncing**: Rapid changes are batched together (default 100ms delay)
290+
- **Error handling**: Continues watching after upload errors with rate limiting
291+
292+
Press `Ctrl+C` to stop watching.
293+
294+
### Environment Variables
295+
296+
| Variable | Description |
297+
|----------|-------------|
298+
| `SFCC_UPLOAD_DEBOUNCE_TIME` | Debounce time in milliseconds (default: 100) |
299+
46300
### Authentication
47301

48-
This command supports both Basic Authentication and OAuth:
302+
This command requires both WebDAV and OAuth authentication:
49303

50-
- **Basic Auth** (recommended for WebDAV): Provide `--username` and `--password`
51-
- **OAuth**: Provide `--client-id` and `--client-secret`
304+
- **WebDAV** (for file upload): Basic Auth (`--username`/`--password`) or OAuth
305+
- **OAuth** (for determining active code version): `--client-id` and `--client-secret`
52306

53-
Basic authentication is preferred for WebDAV operations due to better performance.
307+
Basic authentication is recommended for WebDAV operations due to better performance.

0 commit comments

Comments
 (0)