feat: add cartridges config option and improve deploy command output

Add `cartridges` config key (with `cartridgesPath` alias) to dw.json,
env vars (SFCC_CARTRIDGES), and NormalizedConfig. Supports comma or
colon-separated strings and arrays. Falls back from `-c` flag to config
value in CartridgeCommand. Deploy command now logs cartridge list,
delete step, and summary to stdout.

Author: clavery

.changeset/cartridges-config-option.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Add `cartridges` config option to specify which cartridges to deploy/watch. Supports comma or colon-separated strings, or arrays in dw.json. Also accepts `cartridgesPath` as an alias. The `-c` flag still takes precedence when provided.

packages/b2c-cli/src/commands/code/deploy.ts

@@ -134,9 +134,8 @@ export default class CodeDeploy extends CartridgeCommand<typeof CodeDeploy> {
       this.error(t('commands.code.deploy.noCartridges', 'No cartridges found in {{path}}', {path: this.cartridgePath}));
     }
 
-    this.logger?.info(
-      {path: this.cartridgePath, server: hostname, codeVersion: version},
-      t('commands.code.deploy.deploying', 'Deploying {{path}} to {{hostname}} ({{version}})', {
+    this.log(
+      t('commands.code.deploy.deploying', 'Deploying {{path}} to {{hostname}} ({{version}})...', {
         path: this.cartridgePath,
         hostname,
         version,
@@ -145,12 +144,13 @@ export default class CodeDeploy extends CartridgeCommand<typeof CodeDeploy> {
 
     // Log found cartridges
     for (const c of cartridges) {
-      this.logger?.debug({cartridgeName: c.name, path: c.src}, `  ${c.name}`);
+      this.log(`  ${c.name} (${c.src})`);
     }
 
     try {
       // Optionally delete existing cartridges first
       if (this.flags.delete) {
+        this.log(t('commands.code.deploy.deleting', 'Deleting existing cartridges...'));
         await this.operations.deleteCartridges(this.instance, cartridges);
       }
 
@@ -174,12 +174,15 @@ export default class CodeDeploy extends CartridgeCommand<typeof CodeDeploy> {
         reloaded,
       };
 
-      this.logger?.info(
-        {codeVersion: result.codeVersion, cartridgeCount: result.cartridges.length},
-        t('commands.code.deploy.summary', 'Deployed {{count}} cartridge(s) to {{codeVersion}}', {
-          count: result.cartridges.length,
-          codeVersion: result.codeVersion,
-        }),
+      this.log(
+        t(
+          'commands.code.deploy.summary',
+          'Deployed {{count}} cartridge(s) to version "{{codeVersion}}" successfully!',
+          {
+            count: result.cartridges.length,
+            codeVersion: result.codeVersion,
+          },
+        ),
       );
 
       if (result.reloaded) {

packages/b2c-tooling-sdk/src/cli/cartridge-command.ts

@@ -107,11 +107,15 @@ export abstract class CartridgeCommand<T extends typeof Command> extends Instanc
   }
 
   /**
-   * Gets the cartridge filter options from flags.
+   * Gets the cartridge filter options from flags, falling back to
+   * the `cartridges` config value (from dw.json or env) when no
+   * `-c` / `--cartridge` flag is provided.
    */
   protected get cartridgeOptions(): FindCartridgesOptions {
+    const flagCartridges = this.flags.cartridge as string[] | undefined;
+    const configCartridges = this.resolvedConfig?.values.cartridges;
     return {
-      include: this.flags.cartridge as string[] | undefined,
+      include: flagCartridges ?? configCartridges,
       exclude: this.flags['exclude-cartridge'] as string[] | undefined,
     };
   }

packages/b2c-tooling-sdk/src/config/dw-json.ts

@@ -75,6 +75,8 @@ export interface DwJsonConfig {
   sandboxApiHost?: string;
   /** Default ODS realm for sandbox operations */
   realm?: string;
+  /** Cartridge names to include in deploy/watch (string with colon/comma separators, or array) */
+  cartridges?: string | string[];
   /** Default content library ID for content export/list commands */
   contentLibrary?: string;
   /** Optional CIP analytics host override */

packages/b2c-tooling-sdk/src/config/mapping.ts

@@ -44,6 +44,7 @@ export const CONFIG_KEY_ALIASES: Record<string, string> = {
   'secure-server': 'webdavHostname',
   secureHostname: 'webdavHostname',
   passphrase: 'certificatePassphrase',
+  cartridgesPath: 'cartridges',
   cloudOrigin: 'mrtOrigin',
   selfsigned: 'selfSigned',
   'oauth-scopes': 'oauthScopes',
@@ -103,6 +104,20 @@ export function normalizeConfigKeys(raw: Record<string, unknown>): Record<string
  * // { hostname: 'example.com', codeVersion: 'v1' }
  * ```
  */
+/**
+ * Parses a cartridges value that may be a colon-separated string,
+ * comma-separated string, or already an array.
+ */
+function parseCartridges(value: string | string[] | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (Array.isArray(value)) return value.length > 0 ? value : undefined;
+  const items = value
+    .split(/[,:]/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
 export function mapDwJsonToNormalizedConfig(json: DwJsonConfig): NormalizedConfig {
   return {
     hostname: json.hostname,
@@ -120,6 +135,7 @@ export function mapDwJsonToNormalizedConfig(json: DwJsonConfig): NormalizedConfi
     tenantId: json.tenantId,
     sandboxApiHost: json.sandboxApiHost,
     realm: json.realm,
+    cartridges: parseCartridges(json.cartridges),
     contentLibrary: json.contentLibrary,
     cipHost: json.cipHost,
     instanceName: json.name,
@@ -204,6 +220,9 @@ export function mapNormalizedConfigToDwJson(config: Partial<NormalizedConfig>, n
   if (config.accountManagerHost !== undefined) {
     result.accountManagerHost = config.accountManagerHost;
   }
+  if (config.cartridges !== undefined) {
+    result.cartridges = config.cartridges;
+  }
   if (config.cipHost !== undefined) {
     result.cipHost = config.cipHost;
   }
@@ -328,6 +347,7 @@ export function mergeConfigsWithProtection(
       accountManagerHost: overrides.accountManagerHost ?? base.accountManagerHost,
       shortCode: overrides.shortCode ?? base.shortCode,
       tenantId: overrides.tenantId ?? base.tenantId,
+      cartridges: overrides.cartridges ?? base.cartridges,
       contentLibrary: overrides.contentLibrary ?? base.contentLibrary,
       cipHost: overrides.cipHost ?? base.cipHost,
       sandboxApiHost: overrides.sandboxApiHost ?? base.sandboxApiHost,

packages/b2c-tooling-sdk/src/config/sources/env-source.ts

@@ -33,6 +33,7 @@ const ENV_VAR_MAP: Record<string, keyof NormalizedConfig> = {
   SFCC_OAUTH_SCOPES: 'scopes',
   SFCC_SHORTCODE: 'shortCode',
   SFCC_TENANT_ID: 'tenantId',
+  SFCC_CARTRIDGES: 'cartridges',
   SFCC_AUTH_METHODS: 'authMethods',
   SFCC_ACCOUNT_MANAGER_HOST: 'accountManagerHost',
   SFCC_SANDBOX_API_HOST: 'sandboxApiHost',
@@ -48,7 +49,7 @@ const ENV_VAR_MAP: Record<string, keyof NormalizedConfig> = {
 };
 
 /** Fields that should be parsed as comma-separated arrays. */
-const ARRAY_FIELDS = new Set<keyof NormalizedConfig>(['scopes', 'authMethods']);
+const ARRAY_FIELDS = new Set<keyof NormalizedConfig>(['scopes', 'authMethods', 'cartridges']);
 
 /** Fields that should be parsed as booleans. */
 const BOOLEAN_FIELDS = new Set<keyof NormalizedConfig>(['selfSigned']);

packages/b2c-tooling-sdk/src/config/types.ts

@@ -87,6 +87,10 @@ export interface NormalizedConfig {
   /** MRT API origin URL override */
   mrtOrigin?: string;
 
+  // Cartridges
+  /** Cartridge names to include in deploy/watch operations */
+  cartridges?: string[];
+
   // Content
   /** Default content library ID for content export/list commands */
   contentLibrary?: string;