Refactor ConfigSource API for better encapsulation (#54)

* better logging in config sources for debugging

* Refactor ConfigSource API for better encapsulation

- Change loadDwJson() to return {config, path} for proper path tracking
- Make internal utilities internal (remove mapDwJsonToNormalizedConfig,
  mergeConfigsWithProtection, getPopulatedFields from exports)
- Remove deprecated 'sources' option from ResolveConfigOptions
- CLI commands now use ResolvedB2CConfig directly with .values.* access
- SDK command classes use factory methods (createB2CInstance(),
  createMrtAuth(), etc.) instead of manual construction
- Fix replaceDefaultSources option to work without sourcesAfter

BREAKING CHANGE: loadConfig() now returns ResolvedB2CConfig instead of
NormalizedConfig. Access config values via .values.* property.

* debugging logging

* Improve structured logging with proper fields and messages

Add missing structured fields to log calls while preserving
human-readable messages with interpolated values. This makes
logs both machine-parseable and human-friendly.

Changes:
- Add jobId, executionId, path fields to job operations
- Add cartridgeName, codeVersionId fields to code operations
- Add method, url fields to client logging
- Add headerName, keyPreview, username, port fields to auth
- Change reserved 'hostname' field to 'server' in watch.ts

* change interface of config sources for clarity

* dw json should not return config on invalid instance name

* update docs

* config loading options for plugins

* fix account-manager-host flag default overriding dw.json config

The oclif flag had a default value that was always passed as an
override to config resolution, preventing dw.json values from being
used. Remove the default from the flag and rely on the existing
fallback in the accountManagerHost getter.

Author: clavery

docs/guide/extending.md

@@ -151,29 +151,28 @@ export default hook;
 // src/sources/my-custom-source.ts
 import type {
   ConfigSource,
-  NormalizedConfig,
+  ConfigLoadResult,
   ResolveConfigOptions
 } from '@salesforce/b2c-tooling-sdk/config';
 
 export class MyCustomSource implements ConfigSource {
   readonly name = 'my-custom-source';
 
-  load(options: ResolveConfigOptions): NormalizedConfig | undefined {
+  load(options: ResolveConfigOptions): ConfigLoadResult | undefined {
     // Load config from your custom source
     // Return undefined if source is not available
 
     return {
-      hostname: 'example.sandbox.us03.dx.commercecloud.salesforce.com',
-      clientId: 'your-client-id',
-      clientSecret: 'your-client-secret',
-      codeVersion: 'version1',
+      config: {
+        hostname: 'example.sandbox.us03.dx.commercecloud.salesforce.com',
+        clientId: 'your-client-id',
+        clientSecret: 'your-client-secret',
+        codeVersion: 'version1',
+      },
+      // Location is used for diagnostics - can be a file path, keychain entry, URL, etc.
+      location: '/path/to/config/source',
     };
   }
-
-  // Optional: return path for diagnostics
-  getPath(): string | undefined {
-    return '/path/to/config/source';
-  }
 }
 ```
 

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

@@ -38,10 +38,10 @@ export default class CodeActivate extends InstanceCommand<typeof CodeActivate> {
     this.requireOAuthCredentials();
 
     const codeVersionArg = this.args.codeVersion;
-    const hostname = this.resolvedConfig.hostname!;
+    const hostname = this.resolvedConfig.values.hostname!;
 
     // Get code version from arg, flag, or config
-    const codeVersion = codeVersionArg ?? this.resolvedConfig.codeVersion;
+    const codeVersion = codeVersionArg ?? this.resolvedConfig.values.codeVersion;
 
     if (this.flags.reload) {
       // Reload mode - re-activate the code version

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

@@ -55,7 +55,7 @@ export default class CodeDelete extends InstanceCommand<typeof CodeDelete> {
     this.requireOAuthCredentials();
 
     const codeVersion = this.args.codeVersion;
-    const hostname = this.resolvedConfig.hostname!;
+    const hostname = this.resolvedConfig.values.hostname!;
 
     // Confirm deletion unless --force is used
     if (!this.flags.force) {

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

@@ -51,8 +51,8 @@ export default class CodeDeploy extends CartridgeCommand<typeof CodeDeploy> {
     this.requireWebDavCredentials();
     this.requireOAuthCredentials();
 
-    const hostname = this.resolvedConfig.hostname!;
-    let version = this.resolvedConfig.codeVersion;
+    const hostname = this.resolvedConfig.values.hostname!;
+    let version = this.resolvedConfig.values.codeVersion;
 
     // If no code version specified, discover the active one
     if (!version) {
@@ -102,7 +102,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.log(
+    this.logger?.info(
+      {path: this.cartridgePath, server: hostname, codeVersion: version},
       t('commands.code.deploy.deploying', 'Deploying {{path}} to {{hostname}} ({{version}})', {
         path: this.cartridgePath,
         hostname,
@@ -112,7 +113,7 @@ export default class CodeDeploy extends CartridgeCommand<typeof CodeDeploy> {
 
     // Log found cartridges
     for (const c of cartridges) {
-      this.logger?.debug(`  ${c.name} (${c.src})`);
+      this.logger?.debug({cartridgeName: c.name, path: c.src}, `  ${c.name}`);
     }
 
     try {
@@ -141,7 +142,8 @@ export default class CodeDeploy extends CartridgeCommand<typeof CodeDeploy> {
         reloaded,
       };
 
-      this.log(
+      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,

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

@@ -47,7 +47,7 @@ export default class CodeList extends InstanceCommand<typeof CodeList> {
   async run(): Promise<CodeVersionResult> {
     this.requireOAuthCredentials();
 
-    const hostname = this.resolvedConfig.hostname!;
+    const hostname = this.resolvedConfig.values.hostname!;
 
     this.log(t('commands.code.list.fetching', 'Fetching code versions from {{hostname}}...', {hostname}));
 

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

@@ -31,8 +31,8 @@ export default class CodeWatch extends CartridgeCommand<typeof CodeWatch> {
     this.requireWebDavCredentials();
     this.requireOAuthCredentials();
 
-    const hostname = this.resolvedConfig.hostname!;
-    const version = this.resolvedConfig.codeVersion;
+    const hostname = this.resolvedConfig.values.hostname!;
+    const version = this.resolvedConfig.values.codeVersion;
 
     this.log(t('commands.code.watch.starting', 'Starting watcher for {{path}}', {path: this.cartridgePath}));
     this.log(t('commands.code.watch.target', 'Target: {{hostname}}', {hostname}));

packages/b2c-cli/src/commands/docs/download.ts

@@ -46,7 +46,7 @@ export default class DocsDownload extends InstanceCommand<typeof DocsDownload> {
 
     this.log(
       t('commands.docs.download.downloading', 'Downloading documentation from {{hostname}}...', {
-        hostname: this.resolvedConfig.hostname,
+        hostname: this.resolvedConfig.values.hostname,
       }),
     );
 

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

@@ -117,7 +117,7 @@ export default class JobExport extends JobCommand<typeof JobExport> {
       'show-log': showLog,
     } = this.flags;
 
-    const hostname = this.resolvedConfig.hostname!;
+    const hostname = this.resolvedConfig.values.hostname!;
 
     // Build data units configuration
     const dataUnits = this.buildDataUnits({

packages/b2c-cli/src/commands/job/import.ts

@@ -63,7 +63,7 @@ export default class JobImport extends JobCommand<typeof JobImport> {
     const {target} = this.args;
     const {'keep-archive': keepArchive, remote, timeout, 'show-log': showLog} = this.flags;
 
-    const hostname = this.resolvedConfig.hostname!;
+    const hostname = this.resolvedConfig.values.hostname!;
 
     // Create lifecycle context
     const context = this.createContext('job:import', {

packages/b2c-cli/src/commands/job/run.ts

@@ -82,7 +82,7 @@ export default class JobRun extends JobCommand<typeof JobRun> {
       parameters: rawBody ? undefined : parameters,
       body: rawBody,
       wait,
-      hostname: this.resolvedConfig.hostname,
+      hostname: this.resolvedConfig.values.hostname,
     });
 
     // Run beforeOperation hooks - check for skip
@@ -100,7 +100,7 @@ export default class JobRun extends JobCommand<typeof JobRun> {
     this.log(
       t('commands.job.run.executing', 'Executing job {{jobId}} on {{hostname}}...', {
         jobId,
-        hostname: this.resolvedConfig.hostname!,
+        hostname: this.resolvedConfig.values.hostname!,
       }),
     );