@karmaniverous/get-dotenv 5.2.1 → 5.2.2

package/dist/plugins-demo.mjs

@@ -0,0 +1,328 @@
+import { execa, execaCommand } from 'execa';
+
+// Minimal tokenizer for shell-off execution:
+// Splits by whitespace while preserving quoted segments (single or double quotes).
+const tokenize = (command) => {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const c = command.charAt(i);
+        if (quote) {
+            if (c === quote) {
+                // Support doubled quotes inside a quoted segment (Windows/PowerShell style):
+                // "" -> " and '' -> '
+                const next = command.charAt(i + 1);
+                if (next === quote) {
+                    cur += quote;
+                    i += 1; // skip the second quote
+                }
+                else {
+                    // end of quoted segment
+                    quote = null;
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+        else {
+            if (c === '"' || c === "'") {
+                quote = c;
+            }
+            else if (/\s/.test(c)) {
+                if (cur) {
+                    out.push(cur);
+                    cur = '';
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+};
+
+const dbg = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:run]', ...args);
+    }
+};
+// Strip repeated symmetric outer quotes (single or double) until stable.
+// This is safe for argv arrays passed to execa (no quoting needed) and avoids
+// passing quote characters through to Node (e.g., for `node -e "<code>"`).
+// Handles stacked quotes from shells like PowerShell: """code""" -> code.
+const stripOuterQuotes = (s) => {
+    let out = s;
+    // Repeatedly trim only when the entire string is wrapped in matching quotes.
+    // Stop as soon as the ends are asymmetric or no quotes remain.
+    while (out.length >= 2) {
+        const a = out.charAt(0);
+        const b = out.charAt(out.length - 1);
+        const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+        if (!symmetric)
+            break;
+        out = out.slice(1, -1);
+    }
+    return out;
+};
+// Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
+// expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
+const sanitizeEnv = (env) => {
+    if (!env)
+        return undefined;
+    const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+const runCommand = async (command, shell, opts) => {
+    if (shell === false) {
+        let file;
+        let args = [];
+        if (Array.isArray(command)) {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
+        else {
+            const tokens = tokenize(command);
+            file = tokens[0];
+            args = tokens.slice(1);
+        }
+        if (!file)
+            return 0;
+        dbg('exec (plain)', { file, args, stdio: opts.stdio });
+        // Build options without injecting undefined properties (exactOptionalPropertyTypes).
+        const envSan = sanitizeEnv(opts.env);
+        const plainOpts = {};
+        if (opts.cwd !== undefined)
+            plainOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            plainOpts.env = envSan;
+        if (opts.stdio !== undefined)
+            plainOpts.stdio = opts.stdio;
+        const result = await execa(file, args, plainOpts);
+        if (opts.stdio === 'pipe' && result.stdout) {
+            process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
+        }
+        const exit = result?.exitCode;
+        dbg('exit (plain)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+    else {
+        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        dbg('exec (shell)', {
+            shell: typeof shell === 'string' ? shell : 'custom',
+            stdio: opts.stdio,
+            command: commandStr,
+        });
+        const envSan = sanitizeEnv(opts.env);
+        const shellOpts = { shell };
+        if (opts.cwd !== undefined)
+            shellOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            shellOpts.env = envSan;
+        if (opts.stdio !== undefined)
+            shellOpts.stdio = opts.stdio;
+        const result = await execaCommand(commandStr, shellOpts);
+        const out = result?.stdout;
+        if (opts.stdio === 'pipe' && out) {
+            process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
+        }
+        const exit = result?.exitCode;
+        dbg('exit (shell)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+};
+
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
+    };
+    return plugin;
+};
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+/**
+ * Resolve a command string from the {@link Scripts} table.
+ * A script may be expressed as a string or an object with a `cmd` property.
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @returns Resolved command string (falls back to the provided command).
+ */
+const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
+    ? scripts[command].cmd
+    : (scripts?.[command] ?? command);
+/**
+ * Resolve the shell setting for a given command:
+ * - If the script entry is an object, prefer its `shell` override.
+ * - Otherwise use the provided `shell` (string | boolean).
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @param shell - Global shell preference (string | boolean).
+ */
+const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
+    ? (scripts[command].shell ?? false)
+    : (shell ?? false);
+
+/**
+ * Demo plugin (educational).
+ *
+ * Purpose
+ * - Showcase how to build a plugin for the GetDotenv CLI host.
+ * - Demonstrate:
+ *   - Accessing the resolved dotenv context (ctx).
+ *   - Executing child processes with explicit env injection.
+ *   - Resolving commands via scripts and honoring per-script shell overrides.
+ *   - Thin adapters: business logic stays minimal; use shared helpers.
+ *
+ * Key host APIs used:
+ * - definePlugin: declare a plugin with setup and optional afterResolve.
+ * - cli.ns(name): create a namespaced subcommand under the root CLI.
+ * - cli.getCtx(): access \{ optionsResolved, dotenv, plugins?, pluginConfigs? \}.
+ *
+ * Design notes
+ * - We use the shared runCommand() helper so behavior matches the built-in
+ *   cmd/batch plugins (env sanitization, plain vs shell execution, stdio).
+ * - We inject ctx.dotenv into child env explicitly to avoid bleeding prior
+ *   secrets from process.env when exclusions are set (e.g., --exclude-private).
+ * - We resolve scripts and shell using shared helpers to honor overrides:
+ *   resolveCommand(scripts, input) and resolveShell(scripts, input, shell).
+ *
+ * Usage (examples)
+ *   getdotenv demo ctx
+ *   getdotenv demo run --print APP_SETTING
+ *   getdotenv demo script echo OK
+ *   getdotenv --trace demo run --print ENV_SETTING
+ */
+const demoPlugin = () => definePlugin({
+    id: 'demo',
+    setup(cli) {
+        const logger = console;
+        const ns = cli
+            .ns('demo')
+            .description('Educational demo of host/plugin features (context, child exec, scripts/shell)');
+        /**
+         * demo ctx
+         * Print a summary of the current dotenv context.
+         *
+         * Notes:
+         * - The host resolves context once per invocation in a preSubcommand hook
+         *   (added by enhanceGetDotenvCli.passOptions() in the shipped CLI).
+         * - ctx.dotenv contains the final merged values after overlays/dynamics.
+         */
+        ns.command('ctx')
+            .description('Print a summary of the current dotenv context')
+            .action(() => {
+            const ctx = cli.getCtx();
+            const dotenv = ctx?.dotenv ?? {};
+            const keys = Object.keys(dotenv).sort();
+            const sample = keys.slice(0, 5);
+            logger.log('[demo] Context summary:');
+            logger.log(`- keys: ${keys.length.toString()}`);
+            logger.log(`- sample keys: ${sample.join(', ') || '(none)'}`);
+            logger.log('- tip: use "--trace [keys...]" for per-key diagnostics');
+        });
+        /**
+         * demo run [--print KEY]
+         * Execute a small child process that prints a dotenv value.
+         *
+         * Design:
+         * - Use shell-off + argv array to avoid cross-platform quoting pitfalls.
+         * - Inject ctx.dotenv explicitly into the child env.
+         * - Inherit stdio so output streams live (works well outside CI).
+         *
+         * Tip:
+         * - For deterministic capture in CI, run with "--capture" (or set
+         *   GETDOTENV_STDIO=pipe). The shipped CLI honors both.
+         */
+        ns.command('run')
+            .description('Run a small child process under the current dotenv (shell-off)')
+            .option('--print <key>', 'dotenv key to print', 'APP_SETTING')
+            .action(async (opts) => {
+            const key = typeof opts.print === 'string' && opts.print.length > 0
+                ? opts.print
+                : 'APP_SETTING';
+            // Build a minimal node -e payload via argv array (avoid quoting issues).
+            const code = `console.log(process.env.${key} ?? "")`;
+            const ctx = cli.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            // Inherit stdio for an interactive demo. Use --capture for CI.
+            await runCommand(['node', '-e', code], false, {
+                env: { ...process.env, ...dotenv },
+                stdio: 'inherit',
+            });
+        });
+        /**
+         * demo script [command...]
+         * Resolve and execute a command using the current scripts table and
+         * shell preference (with per-script overrides).
+         *
+         * How it works:
+         * - We read the merged CLI options persisted by the shipped CLI’s
+         *   passOptions() hook on the current command instance’s parent.
+         * - resolveCommand resolves a script name → cmd or passes through a raw
+         *   command string.
+         * - resolveShell chooses the appropriate shell:
+         *    scripts[name].shell ?? global shell (string|boolean).
+         */
+        ns.command('script')
+            .description('Resolve a command via scripts and execute it with the proper shell')
+            .argument('[command...]')
+            .action(async (commandParts, _opts, thisCommand) => {
+            // Safely access the parent’s merged options (installed by passOptions()).
+            const parent = thisCommand.parent;
+            const bag = (parent?.getDotenvCliOptions ?? {});
+            const input = Array.isArray(commandParts)
+                ? commandParts.map(String).join(' ')
+                : '';
+            if (!input) {
+                logger.log('[demo] Please provide a command or script name, e.g. "echo OK" or "git-status".');
+                return;
+            }
+            const resolved = resolveCommand(bag?.scripts, input);
+            const shell = resolveShell(bag?.scripts, input, bag?.shell);
+            // Compose child env (parent + ctx.dotenv). This mirrors cmd/batch behavior.
+            const ctx = cli.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            await runCommand(resolved, shell, {
+                env: { ...process.env, ...dotenv },
+                stdio: 'inherit',
+            });
+        });
+    },
+    /**
+     * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
+     * For the demo we just log once to hint where such logic would live.
+     */
+    afterResolve(_cli, ctx) {
+        const keys = Object.keys(ctx.dotenv);
+        if (keys.length > 0) {
+            // Keep noise low; a single-line breadcrumb is sufficient for the demo.
+            console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+        }
+    },
+});
+
+export { demoPlugin };

package/package.json

@@ -120,6 +120,26 @@
         "default": "./dist/plugins-init.cjs"
       }
     },
+    "./plugins/cmd": {
+      "import": {
+        "types": "./dist/plugins-cmd.d.mts",
+        "default": "./dist/plugins-cmd.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins-cmd.d.cts",
+        "default": "./dist/plugins-cmd.cjs"
+      }
+    },
+    "./plugins/demo": {
+      "import": {
+        "types": "./dist/plugins-demo.d.mts",
+        "default": "./dist/plugins-demo.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins-demo.d.cts",
+        "default": "./dist/plugins-demo.cjs"
+      }
+    },
     "./config": {
       "import": {
         "types": "./dist/config.d.mts",
@@ -225,5 +245,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "5.2.1"
+  "version": "5.2.2"
 }