Add EnvSource config source and improve VS Code extension config loading

- Add EnvSource ConfigSource in SDK that maps SFCC_* env vars to
  NormalizedConfig fields (priority -10, opt-in via sourcesBefore)
- Extension now loads .env files and uses EnvSource for env var support
- Smart workspace folder detection scans for dw.json, .env with SFCC_*
  vars, and package.json b2c key in multi-root workspaces
- Add "Use as B2C Commerce Root" context menu on workspace folders to
  pin a specific folder, with "Reset to Auto-Detect" command to clear
- Pinned root persisted in workspace state, shown in status bar
- Add .env file watchers alongside existing dw.json watchers

Author: clavery

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

@@ -145,3 +145,4 @@ export {ConfigSourceRegistry, globalConfigSourceRegistry} from './config-source-
 
 // Config sources (for direct use)
 export {DwJsonSource} from './sources/dw-json-source.js';
+export {EnvSource} from './sources/env-source.js';

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

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Environment variable configuration source.
+ *
+ * Maps SFCC_* environment variables to NormalizedConfig fields.
+ * Not included in default sources — opt-in only via `sourcesBefore`.
+ *
+ * @internal This module is internal to the SDK. Use ConfigResolver instead.
+ */
+import type {AuthMethod} from '../../auth/types.js';
+import {getPopulatedFields} from '../mapping.js';
+import type {ConfigSource, ConfigLoadResult, NormalizedConfig, ResolveConfigOptions} from '../types.js';
+import {getLogger} from '../../logging/logger.js';
+
+/**
+ * Mapping of SFCC_* environment variable names to NormalizedConfig field names.
+ */
+const ENV_VAR_MAP: Record<string, keyof NormalizedConfig> = {
+  SFCC_SERVER: 'hostname',
+  SFCC_WEBDAV_SERVER: 'webdavHostname',
+  SFCC_CODE_VERSION: 'codeVersion',
+  SFCC_USERNAME: 'username',
+  SFCC_PASSWORD: 'password',
+  SFCC_CERTIFICATE: 'certificate',
+  SFCC_CERTIFICATE_PASSPHRASE: 'certificatePassphrase',
+  SFCC_SELFSIGNED: 'selfSigned',
+  SFCC_CLIENT_ID: 'clientId',
+  SFCC_CLIENT_SECRET: 'clientSecret',
+  SFCC_OAUTH_SCOPES: 'scopes',
+  SFCC_SHORTCODE: 'shortCode',
+  SFCC_TENANT_ID: 'tenantId',
+  SFCC_AUTH_METHODS: 'authMethods',
+  SFCC_ACCOUNT_MANAGER_HOST: 'accountManagerHost',
+  SFCC_SANDBOX_API_HOST: 'sandboxApiHost',
+};
+
+/** Fields that should be parsed as comma-separated arrays. */
+const ARRAY_FIELDS = new Set<keyof NormalizedConfig>(['scopes', 'authMethods']);
+
+/** Fields that should be parsed as booleans. */
+const BOOLEAN_FIELDS = new Set<keyof NormalizedConfig>(['selfSigned']);
+
+/**
+ * Configuration source that reads SFCC_* environment variables.
+ *
+ * Priority -10 (higher than dw.json at 0), matching CLI behavior where
+ * env vars override file-based config.
+ *
+ * Not added to default sources — opt-in only. The CLI handles env vars
+ * via oclif flag `env:` mappings; this source is for consumers like
+ * the VS Code extension that call `resolveConfig()` directly.
+ *
+ * @example
+ * ```typescript
+ * import { resolveConfig, EnvSource } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const config = resolveConfig({}, {
+ *   sourcesBefore: [new EnvSource()],
+ * });
+ * ```
+ *
+ * @internal
+ */
+export class EnvSource implements ConfigSource {
+  readonly name = 'EnvSource';
+  readonly priority = -10;
+
+  private readonly env: Record<string, string | undefined>;
+
+  /**
+   * @param env - Environment object to read from. Defaults to `process.env`.
+   */
+  constructor(env?: Record<string, string | undefined>) {
+    this.env = env ?? process.env;
+  }
+
+  load(_options: ResolveConfigOptions): ConfigLoadResult | undefined {
+    const logger = getLogger();
+    const config: NormalizedConfig = {};
+
+    for (const [envVar, configField] of Object.entries(ENV_VAR_MAP)) {
+      const value = this.env[envVar];
+      if (value === undefined || value === '') continue;
+
+      if (BOOLEAN_FIELDS.has(configField)) {
+        (config as Record<string, unknown>)[configField] = value === 'true' || value === '1';
+      } else if (ARRAY_FIELDS.has(configField)) {
+        (config as Record<string, unknown>)[configField] = value
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean) as string[] | AuthMethod[];
+      } else {
+        (config as Record<string, unknown>)[configField] = value;
+      }
+    }
+
+    const fields = getPopulatedFields(config);
+    if (fields.length === 0) {
+      logger.trace('[EnvSource] No SFCC_* environment variables found');
+      return undefined;
+    }
+
+    logger.trace({fields}, '[EnvSource] Loaded config from environment variables');
+
+    return {config, location: 'environment variables'};
+  }
+}

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

@@ -9,5 +9,6 @@
  * @internal This module is internal to the SDK. Use ConfigResolver instead.
  */
 export {DwJsonSource} from './dw-json-source.js';
+export {EnvSource} from './env-source.js';
 export {MobifySource} from './mobify-source.js';
 export {PackageJsonSource} from './package-json-source.js';

packages/b2c-tooling-sdk/test/config/env-source.test.ts

@@ -0,0 +1,259 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import {expect} from 'chai';
+import {EnvSource, ConfigResolver, DwJsonSource} from '@salesforce/b2c-tooling-sdk/config';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+describe('config/EnvSource', () => {
+  describe('string mapping', () => {
+    it('maps SFCC_SERVER to hostname', () => {
+      const source = new EnvSource({SFCC_SERVER: 'test.demandware.net'});
+      const result = source.load({});
+      expect(result).to.not.be.undefined;
+      expect(result!.config.hostname).to.equal('test.demandware.net');
+    });
+
+    it('maps SFCC_WEBDAV_SERVER to webdavHostname', () => {
+      const source = new EnvSource({SFCC_WEBDAV_SERVER: 'webdav.example.com'});
+      const result = source.load({});
+      expect(result!.config.webdavHostname).to.equal('webdav.example.com');
+    });
+
+    it('maps SFCC_CODE_VERSION to codeVersion', () => {
+      const source = new EnvSource({SFCC_CODE_VERSION: 'v1'});
+      const result = source.load({});
+      expect(result!.config.codeVersion).to.equal('v1');
+    });
+
+    it('maps SFCC_USERNAME to username', () => {
+      const source = new EnvSource({SFCC_USERNAME: 'user@example.com'});
+      const result = source.load({});
+      expect(result!.config.username).to.equal('user@example.com');
+    });
+
+    it('maps SFCC_PASSWORD to password', () => {
+      const source = new EnvSource({SFCC_PASSWORD: 'secret'});
+      const result = source.load({});
+      expect(result!.config.password).to.equal('secret');
+    });
+
+    it('maps SFCC_CERTIFICATE to certificate', () => {
+      const source = new EnvSource({SFCC_CERTIFICATE: '/path/to/cert.p12'});
+      const result = source.load({});
+      expect(result!.config.certificate).to.equal('/path/to/cert.p12');
+    });
+
+    it('maps SFCC_CERTIFICATE_PASSPHRASE to certificatePassphrase', () => {
+      const source = new EnvSource({SFCC_CERTIFICATE_PASSPHRASE: 'pass123'});
+      const result = source.load({});
+      expect(result!.config.certificatePassphrase).to.equal('pass123');
+    });
+
+    it('maps SFCC_CLIENT_ID to clientId', () => {
+      const source = new EnvSource({SFCC_CLIENT_ID: 'my-client'});
+      const result = source.load({});
+      expect(result!.config.clientId).to.equal('my-client');
+    });
+
+    it('maps SFCC_CLIENT_SECRET to clientSecret', () => {
+      const source = new EnvSource({SFCC_CLIENT_SECRET: 'my-secret'});
+      const result = source.load({});
+      expect(result!.config.clientSecret).to.equal('my-secret');
+    });
+
+    it('maps SFCC_SHORTCODE to shortCode', () => {
+      const source = new EnvSource({SFCC_SHORTCODE: 'abc123'});
+      const result = source.load({});
+      expect(result!.config.shortCode).to.equal('abc123');
+    });
+
+    it('maps SFCC_TENANT_ID to tenantId', () => {
+      const source = new EnvSource({SFCC_TENANT_ID: 'abcd_prd'});
+      const result = source.load({});
+      expect(result!.config.tenantId).to.equal('abcd_prd');
+    });
+
+    it('maps SFCC_ACCOUNT_MANAGER_HOST to accountManagerHost', () => {
+      const source = new EnvSource({SFCC_ACCOUNT_MANAGER_HOST: 'account.demandware.com'});
+      const result = source.load({});
+      expect(result!.config.accountManagerHost).to.equal('account.demandware.com');
+    });
+
+    it('maps SFCC_SANDBOX_API_HOST to sandboxApiHost', () => {
+      const source = new EnvSource({SFCC_SANDBOX_API_HOST: 'admin.dx.commercecloud.salesforce.com'});
+      const result = source.load({});
+      expect(result!.config.sandboxApiHost).to.equal('admin.dx.commercecloud.salesforce.com');
+    });
+  });
+
+  describe('boolean parsing', () => {
+    it('parses SFCC_SELFSIGNED=true as boolean true', () => {
+      const source = new EnvSource({SFCC_SELFSIGNED: 'true'});
+      const result = source.load({});
+      expect(result!.config.selfSigned).to.be.true;
+    });
+
+    it('parses SFCC_SELFSIGNED=1 as boolean true', () => {
+      const source = new EnvSource({SFCC_SELFSIGNED: '1'});
+      const result = source.load({});
+      expect(result!.config.selfSigned).to.be.true;
+    });
+
+    it('parses SFCC_SELFSIGNED=false as boolean false', () => {
+      const source = new EnvSource({SFCC_SELFSIGNED: 'false'});
+      const result = source.load({});
+      expect(result!.config.selfSigned).to.be.false;
+    });
+
+    it('parses SFCC_SELFSIGNED=0 as boolean false', () => {
+      const source = new EnvSource({SFCC_SELFSIGNED: '0'});
+      const result = source.load({});
+      expect(result!.config.selfSigned).to.be.false;
+    });
+  });
+
+  describe('array parsing', () => {
+    it('parses SFCC_OAUTH_SCOPES as comma-separated array', () => {
+      const source = new EnvSource({SFCC_OAUTH_SCOPES: 'mail,roles,openid'});
+      const result = source.load({});
+      expect(result!.config.scopes).to.deep.equal(['mail', 'roles', 'openid']);
+    });
+
+    it('trims whitespace in comma-separated values', () => {
+      const source = new EnvSource({SFCC_OAUTH_SCOPES: ' mail , roles , openid '});
+      const result = source.load({});
+      expect(result!.config.scopes).to.deep.equal(['mail', 'roles', 'openid']);
+    });
+
+    it('filters empty values in comma-separated arrays', () => {
+      const source = new EnvSource({SFCC_OAUTH_SCOPES: 'mail,,roles,'});
+      const result = source.load({});
+      expect(result!.config.scopes).to.deep.equal(['mail', 'roles']);
+    });
+
+    it('parses SFCC_AUTH_METHODS as comma-separated array', () => {
+      const source = new EnvSource({SFCC_AUTH_METHODS: 'client-credentials,implicit'});
+      const result = source.load({});
+      expect(result!.config.authMethods).to.deep.equal(['client-credentials', 'implicit']);
+    });
+  });
+
+  describe('empty/undefined handling', () => {
+    it('returns undefined when no SFCC_* vars are set', () => {
+      const source = new EnvSource({});
+      const result = source.load({});
+      expect(result).to.be.undefined;
+    });
+
+    it('skips empty string values', () => {
+      const source = new EnvSource({SFCC_SERVER: '', SFCC_CLIENT_ID: 'my-client'});
+      const result = source.load({});
+      expect(result).to.not.be.undefined;
+      expect(result!.config.hostname).to.be.undefined;
+      expect(result!.config.clientId).to.equal('my-client');
+    });
+
+    it('skips undefined values', () => {
+      const source = new EnvSource({SFCC_SERVER: undefined, SFCC_CLIENT_ID: 'my-client'});
+      const result = source.load({});
+      expect(result!.config.hostname).to.be.undefined;
+      expect(result!.config.clientId).to.equal('my-client');
+    });
+
+    it('ignores non-SFCC environment variables', () => {
+      const source = new EnvSource({HOME: '/home/user', PATH: '/usr/bin', SFCC_SERVER: 'test.demandware.net'});
+      const result = source.load({});
+      expect(result!.config.hostname).to.equal('test.demandware.net');
+      expect(Object.keys(result!.config)).to.have.length(1);
+    });
+  });
+
+  describe('metadata', () => {
+    it('has name EnvSource', () => {
+      const source = new EnvSource({});
+      expect(source.name).to.equal('EnvSource');
+    });
+
+    it('has priority -10', () => {
+      const source = new EnvSource({});
+      expect(source.priority).to.equal(-10);
+    });
+
+    it('reports location as environment variables', () => {
+      const source = new EnvSource({SFCC_SERVER: 'test.demandware.net'});
+      const result = source.load({});
+      expect(result!.location).to.equal('environment variables');
+    });
+  });
+
+  describe('integration with ConfigResolver', () => {
+    let tempDir: string;
+    let originalCwd: string;
+
+    beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'env-source-test-'));
+      originalCwd = process.cwd();
+      process.chdir(tempDir);
+    });
+
+    afterEach(() => {
+      process.chdir(originalCwd);
+      if (fs.existsSync(tempDir)) {
+        fs.rmSync(tempDir, {recursive: true, force: true});
+      }
+    });
+
+    it('EnvSource overrides DwJsonSource values (priority -10 < 0)', () => {
+      // Create dw.json with a hostname
+      fs.writeFileSync(path.join(tempDir, 'dw.json'), JSON.stringify({hostname: 'dw.demandware.net'}));
+
+      // EnvSource with different hostname
+      const envSource = new EnvSource({SFCC_SERVER: 'env.demandware.net'});
+      const resolver = new ConfigResolver([envSource, new DwJsonSource()]);
+      const {config} = resolver.resolve();
+
+      // EnvSource should win (priority -10 < 0)
+      expect(config.hostname).to.equal('env.demandware.net');
+    });
+
+    it('DwJsonSource fills gaps not covered by EnvSource', () => {
+      // dw.json provides code-version
+      fs.writeFileSync(
+        path.join(tempDir, 'dw.json'),
+        JSON.stringify({hostname: 'dw.demandware.net', 'code-version': 'v2'}),
+      );
+
+      // EnvSource provides only hostname
+      const envSource = new EnvSource({SFCC_SERVER: 'env.demandware.net'});
+      const resolver = new ConfigResolver([envSource, new DwJsonSource()]);
+      const {config} = resolver.resolve();
+
+      expect(config.hostname).to.equal('env.demandware.net');
+      expect(config.codeVersion).to.equal('v2');
+    });
+  });
+
+  describe('defaults to process.env', () => {
+    it('reads from process.env when no env param given', () => {
+      const original = process.env.SFCC_SERVER;
+      try {
+        process.env.SFCC_SERVER = 'from-process-env.demandware.net';
+        const source = new EnvSource();
+        const result = source.load({});
+        expect(result).to.not.be.undefined;
+        expect(result!.config.hostname).to.equal('from-process-env.demandware.net');
+      } finally {
+        if (original === undefined) {
+          delete process.env.SFCC_SERVER;
+        } else {
+          process.env.SFCC_SERVER = original;
+        }
+      }
+    });
+  });
+});