@karmaniverous/get-dotenv 5.2.0 → 5.2.2

package/README.md

@@ -1,4 +1,4 @@
-> **_Load, expand, and compose environment variables from a deterministic dotenv cascade, then execute commands under that context. Use `get-dotenv` as a library, a CLI, or a plugin-first host to build dotenv-aware tooling with cross‑platform shell control, CI‑friendly capture, and clear diagnostics._**
+> Load, expand, and compose environment variables from a deterministic dotenv cascade, then execute commands under that context. Use `get-dotenv` as a library, a CLI, or a plugin-first host to build dotenv-aware tooling with cross‑platform shell control, CI‑friendly capture, and clear diagnostics.
 
 # get-dotenv
 
@@ -132,6 +132,42 @@ Options can be passed programmatically or set in a `getdotenv.config.json` file
 
 See the [child CLI example repo](https://github.com/karmaniverous/get-dotenv-child#configuration) for an extensive discussion of the various config options and how & where to set them.
 
+## CLI embedding (createCli)
+
+Prefer the named factory when you want to embed the get‑dotenv CLI in your own tool. It wires the plugin‑first host with the included plugins and returns a small runner.
+
+```ts
+#!/usr/bin/env node
+import { createCli } from '@karmaniverous/get-dotenv';
+
+// Build a CLI and run with your argv; alias appears in help.
+await createCli({
+  alias: 'mycli',
+  // Optional: override the help header (otherwise “mycli v<version>” is used).
+  branding: 'mycli v1.2.3',
+}).run(process.argv.slice(2));
+```
+
+Notes:
+
+- The host resolves dotenv context once per invocation and exposes subcommands: cmd, batch, aws, and init (see Guides below).
+- Use `--trace [keys...]` and `--redact` for diagnostics without altering runtime values.
+- Default shells are normalized across platforms: `/bin/bash` on POSIX and `powershell.exe` on Windows (overridable per‑script or globally).
+- Help/exit behavior (important for embedding and tests):
+  - To keep `-h/--help` deterministic across ESM/CJS and avoid Commander’s default `process.exit`, `createCli().run(['-h'])` prints help and returns without exiting the process.
+  - Because help is printed before the internal `brand()` call runs, the optional branding header may be omitted when `-h/--help` is used at the top level. If you need a branded header, prefer `mycli help` (which runs through normal parsing) or construct and brand a host directly (see “Branding the host CLI” in Guides).
+- Interop matrix (embedding in different module systems):
+  - ESM dynamic:
+    ```ts
+    const { createCli } = await import('@karmaniverous/get-dotenv');
+    await createCli({ alias: 'mycli' }).run(['-h']);
+    ```
+  - CommonJS require (using built outputs for smoke checks):
+    ```js
+    const { createCli } = require('@karmaniverous/get-dotenv/dist/index.cjs');
+    createCli({ alias: 'mycli' }).run(['-h']);
+    ```
+
 ## Dynamic Processing
 
 This package supports the full [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) syntax, with some internal performance improvements. Dynamic variables can be authored in JS or TS.

package/dist/getdotenv.cli.mjs

@@ -3691,19 +3691,167 @@ const initPlugin = (opts = {}) => definePlugin({
     },
 });
 
-// Shipped CLI rebased on plugin-first host.
-const program = new GetDotenvCli('getdotenv');
-// Brand the shipped CLI so help shows the package version (e.g., "getdotenv v5.0.0").
-await program.brand({
-    importMetaUrl: import.meta.url,
-    description: 'Base CLI.',
+const cmdCommand = new Command()
+    .name('cmd')
+    .description('execute command, conflicts with --command option (default subcommand)')
+    .enablePositionalOptions()
+    .passThroughOptions()
+    .argument('[command...]')
+    .action(async (commandParts, _options, thisCommand) => {
+    if (!thisCommand.parent)
+        throw new Error(`unable to resolve parent command`);
+    if (!thisCommand.parent.parent)
+        throw new Error(`unable to resolve root command`);
+    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent.parent;
+    const raw = thisCommand.parent.opts();
+    const ignoreErrors = !!raw.ignoreErrors;
+    const globs = typeof raw.globs === 'string' ? raw.globs : '*';
+    const list = !!raw.list;
+    const pkgCwd = !!raw.pkgCwd;
+    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
+    // Execute command.
+    const args = Array.isArray(commandParts) ? commandParts : [];
+    // When no positional tokens are provided (e.g., option form `-c/--command`),
+    // the preSubcommand hook handles execution. Avoid a duplicate call here.
+    if (args.length === 0)
+        return;
+    const command = args.map(String).join(' ');
+    await execShellCommandBatch({
+        command: resolveCommand(getDotenvCliOptions.scripts, command),
+        getDotenvCliOptions,
+        globs,
+        ignoreErrors,
+        list,
+        logger,
+        pkgCwd,
+        rootPath,
+        // execa expects string | boolean | URL for `shell`. We normalize earlier;
+        // scripts[name].shell overrides take precedence and may be boolean or string.
+        shell: resolveShell(getDotenvCliOptions.scripts, command, getDotenvCliOptions.shell),
+    });
+});
+
+new Command()
+    .name('batch')
+    .description('Batch command execution across multiple working directories.')
+    .enablePositionalOptions()
+    .passThroughOptions()
+    .option('-p, --pkg-cwd', 'use nearest package directory as current working directory')
+    .option('-r, --root-path <string>', 'path to batch root directory from current working directory', './')
+    .option('-g, --globs <string>', 'space-delimited globs from root path', '*')
+    .option('-c, --command <string>', 'command executed according to the base --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv)
+    .option('-l, --list', 'list working directories without executing command')
+    .option('-e, --ignore-errors', 'ignore errors and continue with next path')
+    .hook('preSubcommand', async (thisCommand) => {
+    if (!thisCommand.parent)
+        throw new Error(`unable to resolve root command`);
+    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent;
+    const raw = thisCommand.opts();
+    const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
+    const ignoreErrors = !!raw.ignoreErrors;
+    const globs = typeof raw.globs === 'string' ? raw.globs : '*';
+    const list = !!raw.list;
+    const pkgCwd = !!raw.pkgCwd;
+    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
+    const argCount = thisCommand.args.length;
+    if (typeof commandOpt === 'string' && argCount > 0) {
+        logger.error(`--command option conflicts with cmd subcommand.`);
+        process.exit(0);
+    }
+    // Execute command.
+    if (typeof commandOpt === 'string')
+        await execShellCommandBatch({
+            command: resolveCommand(getDotenvCliOptions.scripts, commandOpt),
+            getDotenvCliOptions,
+            globs,
+            ignoreErrors,
+            list,
+            logger,
+            pkgCwd,
+            rootPath,
+            // execa expects string | boolean | URL for `shell`. We normalize earlier;
+            // scripts[name].shell overrides take precedence and may be boolean or string.
+            shell: resolveShell(getDotenvCliOptions.scripts, commandOpt, getDotenvCliOptions.shell),
+        });
+})
+    .addCommand(cmdCommand, { isDefault: true });
+
+new Command()
+    .name('cmd')
+    .description('Batch execute command according to the --shell option, conflicts with --command option (default subcommand)')
+    .configureHelp({ showGlobalOptions: true })
+    .enablePositionalOptions()
+    .passThroughOptions()
+    .argument('[command...]')
+    .action(async (commandParts, _options, thisCommand) => {
+    const args = Array.isArray(commandParts) ? commandParts : [];
+    if (args.length === 0)
+        return;
+    if (!thisCommand.parent)
+        throw new Error('parent command not found');
+    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent;
+    const command = args.map(String).join(' ');
+    const cmd = resolveCommand(getDotenvCliOptions.scripts, command);
+    if (getDotenvCliOptions.debug)
+        logger.log('\n*** command ***\n', `'${cmd}'`);
+    await execaCommand(cmd, {
+        env: {
+            ...process.env,
+            getDotenvCliOptions: JSON.stringify(getDotenvCliOptions),
+        },
+        // execa expects string | boolean | URL; we normalize in generator
+        // and allow script-level overrides.
+        shell: resolveShell(getDotenvCliOptions.scripts, command, getDotenvCliOptions.shell),
+        stdio: 'inherit',
+    });
 });
-program
-    .attachRootOptions({ loadProcess: false })
-    .use(cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }))
-    .use(batchPlugin())
-    .use(awsPlugin())
-    .use(demoPlugin())
-    .use(initPlugin())
-    .passOptions({ loadProcess: false });
-await program.parseAsync();
+
+function createCli(opts = {}) {
+    const alias = typeof opts.alias === 'string' && opts.alias.length > 0
+        ? opts.alias
+        : 'getdotenv';
+    const program = new GetDotenvCli(alias);
+    // Install base root flags and included plugins; resolve context once per run.
+    program
+        .attachRootOptions({ loadProcess: false })
+        .use(cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }))
+        .use(batchPlugin())
+        .use(awsPlugin())
+        .use(demoPlugin())
+        .use(initPlugin())
+        .passOptions({ loadProcess: false });
+    // Tests-only: avoid process.exit during help/version flows under Vitest.
+    const underTests = process.env.GETDOTENV_TEST === '1' ||
+        typeof process.env.VITEST_WORKER_ID === 'string';
+    if (underTests) {
+        program.exitOverride((err) => {
+            const code = err?.code;
+            if (code === 'commander.helpDisplayed' || code === 'commander.version')
+                return;
+            throw err;
+        });
+    }
+    return {
+        async run(argv) {
+            // Always short-circuit help to avoid Commander-triggered process.exit
+            // across environments (CJS/ESM) and to return immediately under dynamic
+            // ESM without performing extra IO. Prints help and returns.
+            if (argv.some((a) => a === '-h' || a === '--help')) {
+                program.outputHelp();
+                return;
+            }
+            await program.brand({
+                name: alias,
+                importMetaUrl: import.meta.url,
+                description: 'Base CLI.',
+                ...(typeof opts.branding === 'string' && opts.branding.length > 0
+                    ? { helpHeader: opts.branding }
+                    : {}),
+            });
+            await program.parseAsync(['node', alias, ...argv]);
+        },
+    };
+}
+
+// Delegate to the canonical host factory.
+await createCli({ alias: 'getdotenv' }).run(process.argv.slice(2));