site library support in libraries config

Extends libraries to accept {id, siteLibrary?} entries (mixed with strings).
b2c content list/export default --site-library from a matching entry; the
flag is now allowNo with no default so explicit values still win. The VS
Code Content Libraries tree auto-seeds every entry on activation. Adds
libraries, assetQuery, and realm rows to the documented package.json /
dw.json field tables.

Author: clavery

.changeset/site-library-config-support.md

@@ -0,0 +1,7 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-tooling-sdk': minor
+'b2c-vs-extension': minor
+---
+
+The `libraries` config field now accepts `{id, siteLibrary?}` objects in addition to bare strings (mixed forms allowed in the same array). This lets you mark site-private libraries in `dw.json` or `package.json` so `b2c content list` / `content export` can default `--site-library` based on which library you target, and the VS Code Content Libraries tree auto-loads every configured library on activation. To upgrade, optionally replace `"libraries": ["RefArch"]` with `"libraries": ["RefArch", {"id": "homepage", "siteLibrary": true}]`. The existing string-only form continues to work unchanged. Also adds `libraries`, `assetQuery`, and `realm` to the documented `package.json` allowed fields list (already supported in code).

docs/cli/content.md

@@ -53,7 +53,7 @@ In addition to [global flags](./index#global-flags):
 |------|-------------|---------|
 | `--library` | Library ID or site ID. Also configurable via `content-library` in dw.json. | |
 | `--output`, `-o` | Output directory | `content-<timestamp>` |
-| `--site-library` | Treat the library as a site-private library | `false` |
+| `--site-library` / `--no-site-library` | Treat the library as a site-private library. Defaults from a matching `libraries` config entry, otherwise `false` | from config |
 | `--asset-query`, `-q` | JSON dot-paths for static asset extraction (can be repeated) | `image.path` |
 | `--regex`, `-r` | Treat page IDs as regular expressions | `false` |
 | `--folder` | Filter by folder classification (can be repeated) | |
@@ -116,7 +116,7 @@ With `--json`, returns a structured result including the library tree, output pa
 
 ### Notes
 
-- 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
+- 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. You can also list libraries under `b2c.libraries` (mixed strings or `{id, siteLibrary?}` objects); when the resolved library matches an entry marked `siteLibrary: true`, `--site-library` defaults to true automatically. The CLI flag still wins when passed explicitly
 - Use `b2c content list` to discover available page IDs before exporting
 - 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
 - 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
@@ -141,7 +141,7 @@ In addition to [global flags](./index#global-flags):
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--library` | Library ID or site ID. Also configurable via `content-library` in dw.json. | |
-| `--site-library` | Treat the library as a site-private library | `false` |
+| `--site-library` / `--no-site-library` | Treat the library as a site-private library. Defaults from a matching `libraries` config entry, otherwise `false` | from config |
 | `--library-file` | Use a local library XML file instead of fetching from instance | |
 | `--type` | Filter by node type: `page`, `content`, or `component` | |
 | `--components` | Include components in table output | `false` |

docs/guide/configuration.md

@@ -258,8 +258,11 @@ For the full command reference with all flags, see [Setup Commands](/cli/setup).
 | `account-manager-host`   | Account Manager hostname for OAuth                                                                                                  |
 | `shortCode`              | SCAPI short code. Also accepts `short-code` or `scapi-shortcode`.                                                                   |
 | `content-library`        | Default content library ID for `content export` and `content list` commands                                                         |
+| `libraries`              | Library IDs for the WebDAV browser and Content Libraries tree. Accepts `string[]` or `[{id, siteLibrary?}]`; elements may be mixed  |
+| `asset-query`            | JSON dot-paths used to extract static asset URLs during content library parsing (default `["image.path"]`). Also accepts `assetQuery` |
 | `tenant-id`              | Organization/tenant ID for SCAPI                                                                                                    |
 | `sandbox-api-host`       | ODS (sandbox) API hostname                                                                                                          |
+| `realm`                  | Default ODS realm for sandbox operations                                                                                            |
 | `cip-host`               | CIP analytics host override                                                                                                         |
 | `mrtApiKey`              | MRT API key                                                                                                                         |
 | `mrtProject`             | MRT project slug                                                                                                                    |
@@ -319,15 +322,18 @@ You can store project-level defaults in your `package.json` file under the `b2c`
 
 Only non-sensitive, project-level fields can be configured in `package.json`. Both camelCase and kebab-case are accepted (e.g., `shortCode` or `short-code`):
 
-| Field                | Description                                                                 |
-| -------------------- | --------------------------------------------------------------------------- |
-| `shortCode`          | SCAPI short code                                                            |
-| `clientId`           | OAuth client ID (for implicit login discovery)                              |
-| `contentLibrary`     | Default content library ID for `content export` and `content list` commands |
-| `mrtProject`         | MRT project slug                                                            |
-| `mrtOrigin`          | MRT API origin URL override                                                 |
-| `accountManagerHost` | Account Manager hostname for OAuth                                          |
-| `sandboxApiHost`     | ODS (sandbox) API hostname                                                  |
+| Field                | Description                                                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `shortCode`          | SCAPI short code                                                                                                                         |
+| `clientId`           | OAuth client ID (for implicit login discovery)                                                                                           |
+| `contentLibrary`     | Default content library ID for `content export` and `content list` commands                                                              |
+| `libraries`          | Library IDs for the WebDAV browser and Content Libraries tree. Accepts `string[]` or `[{id, siteLibrary?}]`; elements may be mixed       |
+| `assetQuery`         | JSON dot-paths used to extract static asset URLs during content library parsing (default `["image.path"]`)                               |
+| `mrtProject`         | MRT project slug                                                                                                                         |
+| `mrtOrigin`          | MRT API origin URL override                                                                                                              |
+| `accountManagerHost` | Account Manager hostname for OAuth                                                                                                       |
+| `sandboxApiHost`     | ODS (sandbox) API hostname                                                                                                               |
+| `realm`              | Default ODS realm for sandbox operations                                                                                                 |
 
 ::: warning Security Note
 Sensitive fields like `hostname`, `password`, `clientSecret`, `username`, and `mrtApiKey` are intentionally **not** supported in `package.json`. These should be configured via `dw.json` (which should be in `.gitignore`), environment variables, or secure credential stores.
@@ -337,6 +343,30 @@ Sensitive fields like `hostname`, `password`, `clientSecret`, `username`, and `m
 `package.json` has the lowest priority of all configuration sources. Values from `dw.json`, environment variables, or CLI flags will always override `package.json` settings. This makes it ideal for project defaults that can be overridden per-environment.
 :::
 
+### Content Libraries Example
+
+The `libraries` field can list the content libraries your project works with so that the VS Code Content Libraries tree auto-loads them and `b2c content list/export` can default `--site-library` based on the entry.
+
+A bare string is treated as a shared library; an object can mark a library as site-private. Both forms can appear in the same array:
+
+```json
+{
+  "b2c": {
+    "libraries": [
+      "RefArch",
+      { "id": "homepage", "siteLibrary": true }
+    ]
+  }
+}
+```
+
+With this config:
+
+- `b2c content list --library homepage` calls the site-library API automatically (no need to pass `--site-library`).
+- `b2c content list --library RefArch` treats `RefArch` as a shared library.
+- `--site-library` / `--no-site-library` on the command line still wins over the config default.
+- The VS Code Content Libraries tree shows both entries on activation, with `homepage` marked `[site]`.
+
 ### Resolution Priority
 
 Configuration is resolved with the following precedence (highest to lowest):

packages/b2c-cli/src/commands/content/export.ts

@@ -5,6 +5,7 @@
  */
 import {Args, Flags, ux} from '@oclif/core';
 import {JobCommand} from '@salesforce/b2c-tooling-sdk/cli';
+import {resolveLibraryEntries} from '@salesforce/b2c-tooling-sdk/config';
 import {
   LibraryNode,
   exportContent,
@@ -36,15 +37,15 @@ export default class ContentExport extends JobCommand<typeof ContentExport> {
   static flags = {
     ...JobCommand.baseFlags,
     library: Flags.string({
-      description: 'Library ID or site ID (also configurable via dw.json "content-library")',
+      description: 'Library ID or site ID (also configurable via dw.json "content-library" or "libraries")',
     }),
     output: Flags.string({
       char: 'o',
       description: 'Output directory',
     }),
     'site-library': Flags.boolean({
-      description: 'Library is a site-private library',
-      default: false,
+      description: 'Library is a site-private library (defaults from a matching "libraries" config entry)',
+      allowNo: true,
     }),
     'asset-query': Flags.string({
       char: 'q',
@@ -106,11 +107,17 @@ export default class ContentExport extends JobCommand<typeof ContentExport> {
       this.error('At least one content ID is required.');
     }
 
-    const libraryId = flags.library ?? this.resolvedConfig.values.contentLibrary;
+    const libraryEntries = resolveLibraryEntries(this.resolvedConfig.values.libraries);
+    const libraryId = flags.library ?? this.resolvedConfig.values.contentLibrary ?? libraryEntries[0]?.id;
     if (!libraryId) {
       this.error('Library is required. Set via --library flag or "content-library" in dw.json.');
     }
 
+    const isSiteLibrary =
+      flags['site-library'] === undefined
+        ? (libraryEntries.find((e) => e.id === libraryId)?.siteLibrary ?? false)
+        : flags['site-library'];
+
     if (!flags['library-file']) {
       this.requireOAuthCredentials();
     }
@@ -121,7 +128,7 @@ export default class ContentExport extends JobCommand<typeof ContentExport> {
     if (flags['dry-run']) {
       const {library} = await this.operations.fetchContentLibrary(this.instance, libraryId, {
         libraryFile: flags['library-file'],
-        isSiteLibrary: flags['site-library'],
+        isSiteLibrary,
         assetQuery,
         keepOrphans: flags['keep-orphans'],
         waitOptions,
@@ -221,7 +228,7 @@ export default class ContentExport extends JobCommand<typeof ContentExport> {
     }
 
     const result = await this.operations.exportContent(this.instance, pageIds, libraryId, outputPath, {
-      isSiteLibrary: flags['site-library'],
+      isSiteLibrary,
       assetQuery,
       libraryFile: flags['library-file'],
       offline: flags.offline,

packages/b2c-cli/src/commands/content/list.ts

@@ -12,6 +12,7 @@ import {
   selectColumns,
   type ColumnDef,
 } from '@salesforce/b2c-tooling-sdk/cli';
+import {resolveLibraryEntries} from '@salesforce/b2c-tooling-sdk/config';
 import {fetchContentLibrary} from '@salesforce/b2c-tooling-sdk/operations/content';
 
 interface ContentListItem {
@@ -64,11 +65,11 @@ export default class ContentList extends JobCommand<typeof ContentList> {
   static flags = {
     ...JobCommand.baseFlags,
     library: Flags.string({
-      description: 'Library ID or site ID (also configurable via dw.json "content-library")',
+      description: 'Library ID or site ID (also configurable via dw.json "content-library" or "libraries")',
     }),
     'site-library': Flags.boolean({
-      description: 'Site-private library',
-      default: false,
+      description: 'Site-private library (defaults from a matching "libraries" config entry)',
+      allowNo: true,
     }),
     'library-file': Flags.string({
       description: 'Local XML file',
@@ -98,11 +99,17 @@ export default class ContentList extends JobCommand<typeof ContentList> {
   async run(): Promise<{data: ContentListItem[]}> {
     const {flags} = await this.parse(ContentList);
 
-    const libraryId = flags.library ?? this.resolvedConfig.values.contentLibrary;
+    const libraryEntries = resolveLibraryEntries(this.resolvedConfig.values.libraries);
+    const libraryId = flags.library ?? this.resolvedConfig.values.contentLibrary ?? libraryEntries[0]?.id;
     if (!libraryId) {
       this.error('Library is required. Set via --library flag or "content-library" in dw.json.');
     }
 
+    const isSiteLibrary =
+      flags['site-library'] === undefined
+        ? (libraryEntries.find((e) => e.id === libraryId)?.siteLibrary ?? false)
+        : flags['site-library'];
+
     if (!flags['library-file']) {
       this.requireOAuthCredentials();
     }
@@ -113,7 +120,7 @@ export default class ContentList extends JobCommand<typeof ContentList> {
 
     const {library} = await this.operations.fetchContentLibrary(instance, libraryId, {
       libraryFile: flags['library-file'],
-      isSiteLibrary: flags['site-library'],
+      isSiteLibrary,
       waitOptions,
     });
 

packages/b2c-cli/test/commands/content/list.test.ts

@@ -154,4 +154,72 @@ describe('content list', () => {
     expect(libraryId).to.equal('TestLib');
     expect(options.isSiteLibrary).to.equal(true);
   });
+
+  it('defaults --site-library from a matching libraries config entry', async () => {
+    const command: any = await createCommand({library: 'homepage'});
+    stubCommon(command);
+    sinon.stub(command, 'jsonEnabled').returns(true);
+    Object.defineProperty(command, 'resolvedConfig', {
+      value: {
+        values: {
+          libraries: ['RefArch', {id: 'homepage', siteLibrary: true}],
+        },
+      },
+      configurable: true,
+    });
+
+    const mockLibrary = createMockLibrary();
+    const fetchStub = sinon.stub(command.operations, 'fetchContentLibrary').resolves({library: mockLibrary});
+
+    await command.run();
+
+    const [, libraryId, options] = fetchStub.firstCall.args;
+    expect(libraryId).to.equal('homepage');
+    expect(options.isSiteLibrary).to.equal(true);
+  });
+
+  it('explicit --no-site-library overrides libraries config default', async () => {
+    const command: any = await createCommand({library: 'homepage', 'site-library': false});
+    stubCommon(command);
+    sinon.stub(command, 'jsonEnabled').returns(true);
+    Object.defineProperty(command, 'resolvedConfig', {
+      value: {
+        values: {
+          libraries: [{id: 'homepage', siteLibrary: true}],
+        },
+      },
+      configurable: true,
+    });
+
+    const mockLibrary = createMockLibrary();
+    const fetchStub = sinon.stub(command.operations, 'fetchContentLibrary').resolves({library: mockLibrary});
+
+    await command.run();
+
+    const options = fetchStub.firstCall.args[2];
+    expect(options.isSiteLibrary).to.equal(false);
+  });
+
+  it('falls back to first libraries entry when --library and contentLibrary unset', async () => {
+    const command: any = await createCommand({});
+    stubCommon(command);
+    sinon.stub(command, 'jsonEnabled').returns(true);
+    Object.defineProperty(command, 'resolvedConfig', {
+      value: {
+        values: {
+          libraries: [{id: 'RefArch'}, {id: 'homepage', siteLibrary: true}],
+        },
+      },
+      configurable: true,
+    });
+
+    const mockLibrary = createMockLibrary();
+    const fetchStub = sinon.stub(command.operations, 'fetchContentLibrary').resolves({library: mockLibrary});
+
+    await command.run();
+
+    const [, libraryId, options] = fetchStub.firstCall.args;
+    expect(libraryId).to.equal('RefArch');
+    expect(options.isSiteLibrary).to.equal(false);
+  });
 });

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

@@ -15,6 +15,7 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import type {AuthMethod} from '../auth/types.js';
 import {getLogger} from '../logging/logger.js';
+import type {LibraryEntry} from './types.js';
 import {normalizeConfigKeys} from './mapping.js';
 
 /**
@@ -83,8 +84,14 @@ export interface DwJsonConfig {
   contentLibrary?: string;
   /** Catalog IDs for WebDAV browsing */
   catalogs?: string[];
-  /** Library IDs for WebDAV browsing */
-  libraries?: string[];
+  /**
+   * Library IDs for WebDAV browsing and the Content Libraries tree.
+   *
+   * Accepts either a string array or a mixed array of strings and
+   * `{id, siteLibrary?}` objects. Object entries can mark individual
+   * libraries as site-private.
+   */
+  libraries?: (string | LibraryEntry)[];
   /** JSON dot-paths for asset extraction during content library parsing (defaults to ['image.path']) */
   assetQuery?: string[];
   /** Optional CIP analytics host override */

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

@@ -102,6 +102,7 @@ export {resolveConfig, ConfigResolver, createConfigResolver} from './resolver.js
 export type {
   MaybePromise,
   NormalizedConfig,
+  LibraryEntry,
   ConfigSource,
   ConfigLoadResult,
   ConfigSourceInfo,
@@ -116,7 +117,7 @@ export type {
 } from './types.js';
 
 // Instance creation utility (public API for CLI commands)
-export {createInstanceFromConfig, normalizeConfigKeys} from './mapping.js';
+export {createInstanceFromConfig, normalizeConfigKeys, resolveLibraryEntries} from './mapping.js';
 
 // Low-level dw.json API (still available for advanced use)
 export {