more flexible options for config source plugins

Author: clavery

docs/guide/extending.md

@@ -155,6 +155,41 @@ export class MyCustomSource implements ConfigSource {
 }
 ```
 
+### Plugin Configuration
+
+Plugins cannot add flags to commands they don't own (this is an oclif limitation). Instead, plugins should accept configuration via environment variables:
+
+```bash
+# Configure the example plugin's env file location
+export B2C_ENV_FILE_PATH=/path/to/custom/.env.b2c
+b2c code deploy
+```
+
+**Plugin authors should:**
+
+1. Document supported environment variables in your plugin README
+2. Use sensible defaults when env vars are not set
+3. Access the `flags` property in hook options for future extensibility
+
+**Hook Options:**
+
+The hook receives a `flags` property containing all parsed CLI flags from the current command:
+
+```typescript
+const hook: ConfigSourcesHook = async function(options) {
+  // Access parsed flags (read-only)
+  this.debug(`Debug mode: ${options.flags?.debug}`);
+
+  // Use env vars for plugin-specific configuration
+  const customPath = process.env.MY_PLUGIN_CONFIG_PATH;
+
+  return {
+    sources: [new MySource(customPath)],
+    priority: 'after',
+  };
+};
+```
+
 ### NormalizedConfig Fields
 
 Your `ConfigSource` can return any of these configuration fields:

packages/b2c-plugin-example-config/src/sources/env-file-source.ts

@@ -16,7 +16,18 @@ import type {ConfigSource, NormalizedConfig, ResolveConfigOptions} from '@salesf
 /**
  * ConfigSource implementation that loads from .env.b2c files.
  *
- * Supports the following environment variables:
+ * ## Configuration
+ *
+ * Set `B2C_ENV_FILE_PATH` to override the default file location:
+ *
+ * ```bash
+ * export B2C_ENV_FILE_PATH=/path/to/custom/.env.b2c
+ * b2c code deploy
+ * ```
+ *
+ * ## Supported Fields
+ *
+ * The .env.b2c file supports the following environment variables:
  * - HOSTNAME: B2C instance hostname
  * - WEBDAV_HOSTNAME: Separate WebDAV hostname (optional)
  * - CODE_VERSION: Code version
@@ -47,12 +58,23 @@ export class EnvFileSource implements ConfigSource {
   /**
    * Load configuration from .env.b2c file.
    *
+   * File location priority:
+   * 1. B2C_ENV_FILE_PATH environment variable (explicit override)
+   * 2. .env.b2c in startDir (from options)
+   * 3. .env.b2c in current working directory
+   *
    * @param options - Resolution options (startDir used for file lookup)
    * @returns Parsed configuration or undefined if file not found
    */
   load(options: ResolveConfigOptions): NormalizedConfig | undefined {
-    const searchDir = options.startDir ?? process.cwd();
-    this.envFilePath = join(searchDir, '.env.b2c');
+    // Check for explicit path override via environment variable
+    const envOverride = process.env.B2C_ENV_FILE_PATH;
+    if (envOverride) {
+      this.envFilePath = envOverride;
+    } else {
+      const searchDir = options.startDir ?? process.cwd();
+      this.envFilePath = join(searchDir, '.env.b2c');
+    }
 
     if (!existsSync(this.envFilePath)) {
       return undefined;

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

@@ -196,6 +196,7 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
     const hookOptions: ConfigSourcesHookOptions = {
       instance: this.flags.instance,
       configPath: this.flags.config,
+      flags: this.flags as Record<string, unknown>,
       resolveOptions: {
         instance: this.flags.instance,
         configPath: this.flags.config,

packages/b2c-tooling-sdk/src/cli/hooks.ts

@@ -48,6 +48,14 @@ export interface ConfigSourcesHookOptions {
   configPath?: string;
   /** Full ResolveConfigOptions for advanced sources that need more context */
   resolveOptions: ResolveConfigOptions;
+  /**
+   * All parsed CLI flags from the current command.
+   *
+   * Plugins can check for flags they care about. Note that plugins cannot
+   * add flags to commands - they can only read flags that the CLI defines.
+   * For plugin-specific configuration, use environment variables instead.
+   */
+  flags?: Record<string, unknown>;
   /** Index signature for oclif hook compatibility */
   [key: string]: unknown;
 }