@karmaniverous/get-dotenv 4.6.0-0 → 5.0.0-0

package/dist/getdotenv.cli.mjs

@@ -1,14 +1,434 @@
 #!/usr/bin/env node
 import { Command, Option } from 'commander';
-import { execaCommand } from 'execa';
-import { globby } from 'globby';
-import { packageDirectory } from 'package-directory';
-import path, { join } from 'path';
 import fs from 'fs-extra';
-import url, { fileURLToPath } from 'url';
-import { createHash } from 'crypto';
+import { packageDirectory } from 'package-directory';
+import path, { join, extname } from 'path';
+import { z } from 'zod';
+import url, { fileURLToPath, pathToFileURL } from 'url';
+import YAML from 'yaml';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
+import { createHash } from 'crypto';
+import { execa, execaCommand } from 'execa';
+import { globby } from 'globby';
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'readline/promises';
+
+// Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
+const baseRootOptionDefaults = {
+    dotenvToken: '.env',
+    loadProcess: true,
+    logger: console,
+    paths: './',
+    pathsDelimiter: ' ',
+    privateToken: 'local',
+    scripts: {
+        'git-status': {
+            cmd: 'git branch --show-current && git status -s -u',
+            shell: true,
+        },
+    },
+    shell: true,
+    vars: '',
+    varsAssignor: '=',
+    varsDelimiter: ' ',
+    // tri-state flags default to unset unless explicitly provided
+    // (debug/log/exclude* resolved via flag utils)
+};
+
+const baseGetDotenvCliOptions = baseRootOptionDefaults;
+
+/** @internal */
+const isPlainObject = (value) => value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype;
+const mergeInto = (target, source) => {
+    for (const [key, sVal] of Object.entries(source)) {
+        if (sVal === undefined)
+            continue; // do not overwrite with undefined
+        const tVal = target[key];
+        if (isPlainObject(tVal) && isPlainObject(sVal)) {
+            target[key] = mergeInto({ ...tVal }, sVal);
+        }
+        else if (isPlainObject(sVal)) {
+            target[key] = mergeInto({}, sVal);
+        }
+        else {
+            target[key] = sVal;
+        }
+    }
+    return target;
+};
+/**
+ * Perform a deep defaults-style merge across plain objects. *
+ * - Only merges plain objects (prototype === Object.prototype).
+ * - Arrays and non-objects are replaced, not merged.
+ * - `undefined` values are ignored and do not overwrite prior values.
+ *
+ * @typeParam T - The resulting shape after merging all layers.
+ * @param layers - Zero or more partial layers in ascending precedence order.
+ * @returns The merged object typed as {@link T}.
+ *
+ * @example
+ * defaultsDeep(\{ a: 1, nested: \{ b: 2 \} \}, \{ nested: \{ b: 3, c: 4 \} \})
+ * =\> \{ a: 1, nested: \{ b: 3, c: 4 \} \}
+ */
+const defaultsDeep = (...layers) => {
+    const result = layers
+        .filter(Boolean)
+        .reduce((acc, layer) => mergeInto(acc, layer), {});
+    return result;
+};
+
+// src/GetDotenvOptions.ts
+const getDotenvOptionsFilename = 'getdotenv.config.json'; /**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset".
+ */
+/**
+ * Converts programmatic CLI options to `getDotenv` options. *
+ * @param cliOptions - CLI options. Defaults to `{}`.
+ *
+ * @returns `getDotenv` options.
+ */
+const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }) => {
+    /**
+     * Convert CLI-facing string options into {@link GetDotenvOptions}.
+     *
+     * - Splits {@link GetDotenvCliOptions.paths} using either a delimiter
+     *   or a regular expression pattern into a string array.   * - Parses {@link GetDotenvCliOptions.vars} as space-separated `KEY=VALUE`
+     *   pairs (configurable delimiters) into a {@link ProcessEnv}.
+     * - Drops CLI-only keys that have no programmatic equivalent.
+     *
+     * @remarks
+     * Follows exact-optional semantics by not emitting undefined-valued entries.
+     */
+    // Drop CLI-only keys (debug/scripts) without relying on Record casts.
+    // Create a shallow copy then delete optional CLI-only keys if present.
+    const restObj = { ...rest };
+    delete restObj.debug;
+    delete restObj.scripts;
+    const splitBy = (value, delim, pattern) => (value ? value.split(pattern ? RegExp(pattern) : (delim ?? ' ')) : []);
+    const kvPairs = (vars
+        ? splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
+            ? RegExp(varsAssignorPattern)
+            : (varsAssignor ?? '=')))
+        : []);
+    const parsedVars = Object.fromEntries(kvPairs);
+    // Preserve exactOptionalPropertyTypes: only include keys when defined.
+    return {
+        ...restObj,
+        ...(paths !== undefined
+            ? {
+                paths: splitBy(paths, pathsDelimiter, pathsDelimiterPattern),
+            }
+            : {}),
+        ...(vars !== undefined ? { vars: parsedVars } : {}),
+    };
+};
+const resolveGetDotenvOptions = async (customOptions) => {
+    /**
+     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
+     *
+     * 1. Base defaults derived from the CLI generator defaults
+     *    ({@link baseGetDotenvCliOptions}).
+     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
+     *    package root (if present).
+     * 3. The provided {@link customOptions}.
+     *
+     * The result preserves explicit empty values and drops only `undefined`.
+     *
+     * @returns Fully-resolved {@link GetDotenvOptions}.
+     *
+     * @example
+     * ```ts
+     * const options = await resolveGetDotenvOptions({ env: 'dev' });
+     * ```
+     */
+    const localPkgDir = await packageDirectory();
+    const localOptionsPath = localPkgDir
+        ? join(localPkgDir, getDotenvOptionsFilename)
+        : undefined;
+    const localOptions = (localOptionsPath && (await fs.exists(localOptionsPath))
+        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
+        : {});
+    // Merge order: base < local < custom (custom has highest precedence)
+    const mergedCli = defaultsDeep(baseGetDotenvCliOptions, localOptions);
+    const defaultsFromCli = getDotenvCliOptions2Options(mergedCli);
+    const result = defaultsDeep(defaultsFromCli, customOptions);
+    return {
+        ...result, // Keep explicit empty strings/zeros; drop only undefined
+        vars: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
+    };
+};
+
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * NOTE: These schemas are introduced without wiring to avoid behavior changes.
+ * Legacy paths continue to use existing types/logic. The new plugin host will
+ * use these schemas in strict mode; legacy paths will adopt them in warn mode
+ * later per the staged plan.
+ */
+// Minimal process env representation: string values or undefined to indicate "unset".
+const processEnvSchema = z.record(z.string(), z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+const getDotenvOptionsSchemaRaw = z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    excludePublic: z.boolean().optional(),
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    outputPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    privateToken: z.string().optional(),
+    vars: processEnvSchema.optional(),
+    // Host-only feature flag: guarded integration of config loader/overlay
+    useConfigLoader: z.boolean().optional(),
+});
+// RESOLVED: service-boundary contract (post-inheritance).
+// For Step A, keep identical to RAW (no behavior change). Later stages will// materialize required defaults and narrow shapes as resolution is wired.
+const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
+
+/**
+ * Zod schemas for configuration files discovered by the new loader. *
+ * Notes:
+ * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
+ * - RESOLVED: normalized shapes (paths always string[]).
+ * - For this step (JSON/YAML only), any defined `dynamic` will be rejected by the loader.
+ */
+// String-only env value map
+const stringMap = z.record(z.string(), z.string());
+const envStringMap = z.record(z.string(), stringMap);
+// Allow string[] or single string for "paths" in RAW; normalize later.
+const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
+const getDotenvConfigSchemaRaw = z.object({
+    dotenvToken: z.string().optional(),
+    privateToken: z.string().optional(),
+    paths: rawPathsSchema,
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    vars: stringMap.optional(), // public, global
+    envVars: envStringMap.optional(), // public, per-env
+    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    dynamic: z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: z.record(z.string(), z.unknown()).optional(),
+});
+// Normalize paths to string[]
+const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
+const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
+    ...raw,
+    paths: normalizePaths(raw.paths),
+}));
+
+// Discovery candidates (first match wins per scope/privacy).
+// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
+const PUBLIC_FILENAMES = [
+    'getdotenv.config.json',
+    'getdotenv.config.yaml',
+    'getdotenv.config.yml',
+    'getdotenv.config.js',
+    'getdotenv.config.mjs',
+    'getdotenv.config.cjs',
+    'getdotenv.config.ts',
+    'getdotenv.config.mts',
+    'getdotenv.config.cts',
+];
+const LOCAL_FILENAMES = [
+    'getdotenv.config.local.json',
+    'getdotenv.config.local.yaml',
+    'getdotenv.config.local.yml',
+    'getdotenv.config.local.js',
+    'getdotenv.config.local.mjs',
+    'getdotenv.config.local.cjs',
+    'getdotenv.config.local.ts',
+    'getdotenv.config.local.mts',
+    'getdotenv.config.local.cts',
+];
+const isYaml = (p) => ['.yaml', '.yml'].includes(extname(p).toLowerCase());
+const isJson = (p) => extname(p).toLowerCase() === '.json';
+const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
+// --- Internal JS/TS module loader helpers (default export) ---
+const importDefault$1 = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheName = (absPath, suffix) => {
+    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
+    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
+    return `${base}.${suffix}.mjs`;
+};
+const ensureDir$1 = async (dir) => {
+    await fs.ensureDir(dir);
+    return dir;
+};
+const loadJsTsDefault = async (absPath) => {
+    const fileUrl = pathToFileURL(absPath).toString();
+    const ext = extname(absPath).toLowerCase();
+    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
+        return importDefault$1(fileUrl);
+    }
+    // Try direct import first in case a TS loader is active.
+    try {
+        const val = await importDefault$1(fileUrl);
+        if (val)
+            return val;
+    }
+    catch {
+        /* fallthrough */
+    }
+    // esbuild bundle to a temp ESM file
+    try {
+        const esbuild = (await import('esbuild'));
+        const outDir = await ensureDir$1(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        return await importDefault$1(pathToFileURL(outfile).toString());
+    }
+    catch {
+        /* fallthrough to TS transpile */
+    }
+    // typescript.transpileModule simple transpile (single-file)
+    try {
+        const ts = (await import('typescript'));
+        const src = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(src, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        const outDir = await ensureDir$1(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
+        await fs.writeFile(outfile, out, 'utf-8');
+        return await importDefault$1(pathToFileURL(outfile).toString());
+    }
+    catch {
+        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
+    }
+};
+/**
+ * Discover JSON/YAML config files in the packaged root and project root.
+ * Order: packaged public → project public → project local. */
+const discoverConfigFiles = async (importMetaUrl) => {
+    const files = [];
+    // Packaged root via importMetaUrl (optional)
+    if (importMetaUrl) {
+        const fromUrl = fileURLToPath(importMetaUrl);
+        const packagedRoot = await packageDirectory({ cwd: fromUrl });
+        if (packagedRoot) {
+            for (const name of PUBLIC_FILENAMES) {
+                const p = join(packagedRoot, name);
+                if (await fs.pathExists(p)) {
+                    files.push({ path: p, privacy: 'public', scope: 'packaged' });
+                    break; // only one public file expected per scope
+                }
+            }
+            // By policy, packaged .local is not expected; skip even if present.
+        }
+    }
+    // Project root (from current working directory)
+    const projectRoot = await packageDirectory();
+    if (projectRoot) {
+        for (const name of PUBLIC_FILENAMES) {
+            const p = join(projectRoot, name);
+            if (await fs.pathExists(p)) {
+                files.push({ path: p, privacy: 'public', scope: 'project' });
+                break;
+            }
+        }
+        for (const name of LOCAL_FILENAMES) {
+            const p = join(projectRoot, name);
+            if (await fs.pathExists(p)) {
+                files.push({ path: p, privacy: 'local', scope: 'project' });
+                break;
+            }
+        }
+    }
+    return files;
+};
+/**
+ * Load a single config file (JSON/YAML). JS/TS is not supported in this step.
+ * Validates with Zod RAW schema, then normalizes to RESOLVED.
+ *
+ * For JSON/YAML: if a "dynamic" property is present, throws with guidance.
+ * For JS/TS: default export is loaded; "dynamic" is allowed.
+ */
+const loadConfigFile = async (filePath) => {
+    let raw = {};
+    try {
+        const abs = path.resolve(filePath);
+        if (isJsOrTs(abs)) {
+            // JS/TS support: load default export via robust pipeline.
+            const mod = await loadJsTsDefault(abs);
+            raw = mod ?? {};
+        }
+        else {
+            const txt = await fs.readFile(abs, 'utf-8');
+            raw = isJson(abs) ? JSON.parse(txt) : isYaml(abs) ? YAML.parse(txt) : {};
+        }
+    }
+    catch (err) {
+        throw new Error(`Failed to read/parse config: ${filePath}. ${String(err)}`);
+    }
+    // Validate RAW
+    const parsed = getDotenvConfigSchemaRaw.safeParse(raw);
+    if (!parsed.success) {
+        const msgs = parsed.error.issues
+            .map((i) => `${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Invalid config ${filePath}:\n${msgs}`);
+    }
+    // Disallow dynamic in JSON/YAML; allow in JS/TS
+    if (!isJsOrTs(filePath) && parsed.data.dynamic !== undefined) {
+        throw new Error(`Config ${filePath} specifies "dynamic"; JSON/YAML configs cannot include dynamic in this step. Use JS/TS config.`);
+    }
+    return getDotenvConfigSchemaResolved.parse(parsed.data);
+};
+/**
+ * Discover and load configs into resolved shapes, ordered by scope/privacy.
+ * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
+ */
+const resolveGetDotenvConfigSources = async (importMetaUrl) => {
+    const discovered = await discoverConfigFiles(importMetaUrl);
+    const result = {};
+    for (const f of discovered) {
+        const cfg = await loadConfigFile(f.path);
+        if (f.scope === 'packaged') {
+            // packaged public only
+            result.packaged = cfg;
+        }
+        else {
+            result.project ??= {};
+            if (f.privacy === 'public')
+                result.project.public = cfg;
+            else
+                result.project.local = cfg;
+        }
+    }
+    return result;
+};
 
 /**
  * Dotenv expansion utilities.
@@ -146,273 +566,558 @@ const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduc
  */
 const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
 
-const baseGetDotenvCliOptions = {
-    dotenvToken: '.env',
-    loadProcess: true,
-    logger: console,
-    paths: './',
-    pathsDelimiter: ' ',
-    privateToken: 'local',
-    scripts: {
-        'git-status': {
-            cmd: 'git branch --show-current && git status -s -u',
-            shell: true,
-        },
-    },
-    shell: true,
-    vars: '',
-    varsAssignor: '=',
-    varsDelimiter: ' ',
+const applyKv = (current, kv) => {
+    if (!kv || Object.keys(kv).length === 0)
+        return current;
+    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
+    return { ...current, ...expanded };
+};
+const applyConfigSlice = (current, cfg, env) => {
+    if (!cfg)
+        return current;
+    // kind axis: global then env (env overrides global)
+    const afterGlobal = applyKv(current, cfg.vars);
+    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
+    return applyKv(afterGlobal, envKv);
 };
-
 /**
- * Resolve a command string from the {@link Scripts} table.
- * A script may be expressed as a string or an object with a `cmd` property.
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
  *
- * @param scripts - Optional scripts table.
- * @param command - User-provided command name or string.
- * @returns Resolved command string (falls back to the provided command).
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
  */
-const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
-    ? scripts[command].cmd
-    : (scripts?.[command] ?? command);
+const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
+    let current = { ...base };
+    // Source: packaged (public -> local)
+    current = applyConfigSlice(current, configs.packaged, env);
+    // Packaged "local" is not expected by policy; if present, honor it.
+    // We do not have a separate object for packaged.local in sources, keep as-is.
+    // Source: project (public -> local)
+    current = applyConfigSlice(current, configs.project?.public, env);
+    current = applyConfigSlice(current, configs.project?.local, env);
+    // Programmatic explicit vars (top of static tier)
+    if (programmaticVars) {
+        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
+        current = applyKv(current, toApply);
+    }
+    return current;
+};
+
 /**
- * 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).
+ * Asynchronously read a dotenv file & parse it into an object.
  *
- * @param scripts - Optional scripts table.
- * @param command - User-provided command name or string.
- * @param shell - Global shell preference (string | boolean).
+ * @param path - Path to dotenv file.
+ * @returns The parsed dotenv object.
  */
-const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
-    ? (scripts[command].shell ?? false)
-    : (shell ?? false);
+const readDotenv = async (path) => {
+    try {
+        return (await fs.exists(path)) ? parse(await fs.readFile(path)) : {};
+    }
+    catch {
+        return {};
+    }
+};
 
-const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
-    let cwd = process.cwd();
-    if (pkgCwd) {
-        const pkgDir = await packageDirectory();
-        if (!pkgDir) {
-            logger.error('No package directory found.');
-            process.exit(0);
-        }
-        cwd = pkgDir;
+const importDefault = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheHash = (absPath, mtimeMs) => createHash('sha1')
+    .update(absPath)
+    .update(String(mtimeMs))
+    .digest('hex')
+    .slice(0, 12);
+/**
+ * Remove older compiled cache files for a given source base name, keeping
+ * at most `keep` most-recent files. Errors are ignored by design.
+ */
+const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
+    try {
+        const entries = await fs.readdir(cacheDir);
+        const mine = entries
+            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
+            .map((f) => path.join(cacheDir, f));
+        if (mine.length <= keep)
+            return;
+        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
+        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        const toDelete = stats.slice(keep).map((s) => s.p);
+        await Promise.all(toDelete.map(async (p) => {
+            try {
+                await fs.remove(p);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }));
     }
-    const absRootPath = path.posix.join(cwd.split(path.sep).join(path.posix.sep), rootPath.split(path.sep).join(path.posix.sep));
-    const paths = await globby(globs.split(/\s+/), {
-        cwd: absRootPath,
-        expandDirectories: false,
-        onlyDirectories: true,
-        absolute: true,
-    });
-    if (!paths.length) {
-        logger.error(`No paths found for globs '${globs}' at '${absRootPath}'.`);
-        process.exit(0);
+    catch {
+        // best-effort cleanup
     }
-    return { absRootPath, paths };
 };
-const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
-    if (!command) {
-        logger.error(`No command provided.`);
-        process.exit(0);
+/**
+ * Load a module default export from a JS/TS file with robust fallbacks:
+ * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
+ *   1) try direct import (if a TS loader is active),
+ *   2) esbuild bundle to a temp ESM file,
+ *   3) typescript.transpileModule fallback for simple modules.
+ *
+ * @param absPath - absolute path to source file
+ * @param cacheDirName - cache subfolder under .tsbuild
+ */
+const loadModuleDefault = async (absPath, cacheDirName) => {
+    const ext = path.extname(absPath).toLowerCase();
+    const fileUrl = url.pathToFileURL(absPath).toString();
+    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
+        return importDefault(fileUrl);
     }
-    const { absRootPath, paths } = await globPaths({
-        globs,
-        logger,
-        rootPath,
-        // exactOptionalPropertyTypes: only include when defined
-        ...(pkgCwd !== undefined ? { pkgCwd } : {}),
-    });
-    const headerTitle = list
-        ? 'Listing working directories...'
-        : 'Executing command batch...';
-    logger.info('');
-    const headerRootPath = `ROOT:  ${absRootPath}`;
-    const headerGlobs = `GLOBS: ${globs}`;
-    const headerCommand = `CMD:   ${command}`;
-    logger.info('*'.repeat(Math.max(headerTitle.length, headerRootPath.length, headerGlobs.length, headerCommand.length)));
-    logger.info(headerTitle);
-    logger.info('');
-    logger.info(headerRootPath);
-    logger.info(headerGlobs);
-    logger.info(headerCommand);
-    for (const path of paths) {
-        // Write path and command to console.
-        const pathLabel = `CWD:   ${path}`;
-        if (list) {
-            logger.info(pathLabel);
-            continue;
+    // Try direct import first (TS loader active)
+    try {
+        const dyn = await importDefault(fileUrl);
+        if (dyn)
+            return dyn;
+    }
+    catch {
+        /* fall through */
+    }
+    const stat = await fs.stat(absPath);
+    const hash = cacheHash(absPath, stat.mtimeMs);
+    const cacheDir = path.resolve('.tsbuild', cacheDirName);
+    await fs.ensureDir(cacheDir);
+    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
+    // Try esbuild
+    try {
+        const esbuild = (await import('esbuild'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile: cacheFile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        /* fall through to TS transpile */
+    }
+    // TypeScript transpile fallback
+    try {
+        const ts = (await import('typescript'));
+        const code = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(code, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        await fs.writeFile(cacheFile, out, 'utf-8');
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        // Caller decides final error wording; rethrow for upstream mapping.
+        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
+    }
+};
+
+/**
+ * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
+ *
+ * @param options - `GetDotenvOptions` object
+ * @returns The combined parsed dotenv object.
+ * * @example Load from the project root with default tokens
+ * ```ts
+ * const vars = await getDotenv();
+ * console.log(vars.MY_SETTING);
+ * ```
+ *
+ * @example Load from multiple paths and a specific environment
+ * ```ts
+ * const vars = await getDotenv({
+ *   env: 'dev',
+ *   dotenvToken: '.testenv',
+ *   privateToken: 'secret',
+ *   paths: ['./', './packages/app'],
+ * });
+ * ```
+ *
+ * @example Use dynamic variables
+ * ```ts
+ * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
+ * const vars = await getDotenv({ dynamicPath: '.env.js' });
+ * ```
+ *
+ * @remarks
+ * - When {@link GetDotenvOptions.loadProcess} is true, the resulting variables are merged
+ *   into `process.env` as a side effect.
+ * - When {@link GetDotenvOptions.outputPath} is provided, a consolidated dotenv file is written.
+ *   The path is resolved after expansion, so it may reference previously loaded vars.
+ *
+ * @throws Error when a dynamic module is present but cannot be imported.
+ * @throws Error when an output path was requested but could not be resolved.
+ */
+const getDotenv = async (options = {}) => {
+    // Apply defaults.
+    const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
+    // Read .env files.
+    const loaded = paths.length
+        ? await paths.reduce(async (e, p) => {
+            const publicGlobal = excludePublic || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, dotenvToken));
+            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
+            const privateGlobal = excludePrivate || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${privateToken}`));
+            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}.${privateToken}`));
+            const [eResolved, publicGlobalResolved, publicEnvResolved, privateGlobalResolved, privateEnvResolved,] = await Promise.all([
+                e,
+                publicGlobal,
+                publicEnv,
+                privateGlobal,
+                privateEnv,
+            ]);
+            return {
+                ...eResolved,
+                ...publicGlobalResolved,
+                ...publicEnvResolved,
+                ...privateGlobalResolved,
+                ...privateEnvResolved,
+            };
+        }, Promise.resolve({}))
+        : {};
+    const outputKey = nanoid();
+    const dotenv = dotenvExpandAll({
+        ...loaded,
+        ...vars,
+        ...(outputPath ? { [outputKey]: outputPath } : {}),
+    }, { progressive: true });
+    // Process dynamic variables. Programmatic option takes precedence over path.
+    if (!excludeDynamic) {
+        let dynamic = undefined;
+        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
+            dynamic = options.dynamic;
         }
-        logger.info('');
-        logger.info('*'.repeat(pathLabel.length));
-        logger.info(pathLabel);
-        logger.info(headerCommand);
-        // Execute command.
-        try {
-            await execaCommand(command, {
-                cwd: path,
-                env: {
-                    ...process.env,
-                    getDotenvCliOptions: getDotenvCliOptions
-                        ? JSON.stringify(getDotenvCliOptions)
-                        : undefined,
-                },
-                stdio: 'inherit',
-                shell, // already normalized to string | boolean | URL
-            });
+        else if (dynamicPath) {
+            const absDynamicPath = path.resolve(dynamicPath);
+            if (await fs.exists(absDynamicPath)) {
+                try {
+                    dynamic = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic');
+                }
+                catch {
+                    // Preserve legacy error text for compatibility with tests/docs.
+                    throw new Error(`Unable to load dynamic TypeScript file: ${absDynamicPath}. ` +
+                        `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
+                }
+            }
         }
-        catch (error) {
-            if (!ignoreErrors) {
-                throw error;
+        if (dynamic) {
+            try {
+                for (const key in dynamic)
+                    Object.assign(dotenv, {
+                        [key]: typeof dynamic[key] === 'function'
+                            ? dynamic[key](dotenv, env ?? defaultEnv)
+                            : dynamic[key],
+                    });
+            }
+            catch {
+                throw new Error(`Unable to evaluate dynamic variables.`);
             }
         }
     }
-    logger.info('');
+    // Write output file.
+    let resultDotenv = dotenv;
+    if (outputPath) {
+        const outputPathResolved = dotenv[outputKey];
+        if (!outputPathResolved)
+            throw new Error('Output path not found.');
+        const { [outputKey]: _omitted, ...dotenvForOutput } = dotenv;
+        await fs.writeFile(outputPathResolved, Object.keys(dotenvForOutput).reduce((contents, key) => {
+            const value = dotenvForOutput[key] ?? '';
+            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
+        }, ''), { encoding: 'utf-8' });
+        resultDotenv = dotenvForOutput;
+    }
+    // Log result.
+    if (log)
+        logger.log(resultDotenv);
+    // Load process.env.
+    if (loadProcess)
+        Object.assign(process.env, resultDotenv);
+    return resultDotenv;
 };
 
-const cmdCommand$1 = new Command()
-    .name('cmd')
-    .description('execute command, conflicts with --command option (default subcommand)')
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .action(async (_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 command = thisCommand.args.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),
+/**
+ * Compute the dotenv context for the host (uses the config loader/overlay path).
+ * - Resolves and validates options strictly (host-only).
+ * - Applies file cascade, overlays, dynamics, and optional effects.
+ * - Merges and validates per-plugin config slices (when provided).
+ *
+ * @param customOptions - Partial options from the current invocation.
+ * @param plugins - Installed plugins (for config validation).
+ * @param hostMetaUrl - import.meta.url of the host module (for packaged root discovery). */
+const computeContext = async (customOptions, plugins, hostMetaUrl) => {
+    const optionsResolved = await resolveGetDotenvOptions(customOptions);
+    const validated = getDotenvOptionsSchemaResolved.parse(optionsResolved);
+    // Always-on loader path
+    // 1) Base from files only (no dynamic, no programmatic vars)
+    const base = await getDotenv({
+        ...validated,
+        // Build a pure base without side effects or logging.
+        excludeDynamic: true,
+        vars: {},
+        log: false,
+        loadProcess: false,
+        outputPath: undefined,
     });
-});
-
-const batchCommand = 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);
+    // 2) Discover config sources and overlay
+    const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
+    const dotenvOverlaid = overlayEnv({
+        base,
+        env: validated.env ?? validated.defaultEnv,
+        configs: sources,
+        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
+    });
+    // Helper to apply a dynamic map progressively.
+    const applyDynamic = (target, dynamic, env) => {
+        if (!dynamic)
+            return;
+        for (const key of Object.keys(dynamic)) {
+            const value = typeof dynamic[key] === 'function'
+                ? dynamic[key](target, env)
+                : dynamic[key];
+            Object.assign(target, { [key]: value });
+        }
+    };
+    // 3) Apply dynamics in order
+    const dotenv = { ...dotenvOverlaid };
+    applyDynamic(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.packaged?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.project?.public?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.project?.local?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    // file dynamicPath (lowest)
+    if (validated.dynamicPath) {
+        const absDynamicPath = path.resolve(validated.dynamicPath);
+        try {
+            const dyn = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic-host');
+            applyDynamic(dotenv, dyn, validated.env ?? validated.defaultEnv);
+        }
+        catch {
+            throw new Error(`Unable to load dynamic from ${validated.dynamicPath}`);
+        }
+    }
+    // 4) Output/log/process merge
+    if (validated.outputPath) {
+        await fs.writeFile(validated.outputPath, Object.keys(dotenv).reduce((contents, key) => {
+            const value = dotenv[key] ?? '';
+            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
+        }, ''), { encoding: 'utf-8' });
+    }
+    const logger = validated.logger ?? console;
+    if (validated.log)
+        logger.log(dotenv);
+    if (validated.loadProcess)
+        Object.assign(process.env, dotenv);
+    // 5) Merge and validate per-plugin config (packaged < project.public < project.local)
+    const packagedPlugins = (sources.packaged &&
+        sources.packaged.plugins) ??
+        {};
+    const publicPlugins = (sources.project?.public &&
+        sources.project.public.plugins) ??
+        {};
+    const localPlugins = (sources.project?.local &&
+        sources.project.local.plugins) ??
+        {};
+    const mergedPluginConfigs = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
+    for (const p of plugins) {
+        if (!p.id || !p.configSchema)
+            continue;
+        const slice = mergedPluginConfigs[p.id];
+        if (slice === undefined)
+            continue;
+        const parsed = p.configSchema.safeParse(slice);
+        if (!parsed.success) {
+            const msgs = parsed.error.issues
+                .map((i) => `${i.path.join('.')}: ${i.message}`)
+                .join('\n');
+            throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
+        }
+        mergedPluginConfigs[p.id] = parsed.data;
     }
-    // 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),
+    return {
+        optionsResolved: validated,
+        dotenv: dotenv,
+        plugins: {},
+        pluginConfigs: mergedPluginConfigs,
+    };
+};
+
+const HOST_META_URL = import.meta.url;
+const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
+/**
+ * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
+ *
+ * Responsibilities:
+ * - Resolve options strictly and compute dotenv context (resolveAndLoad).
+ * - Expose a stable accessor for the current context (getCtx).
+ * - Provide a namespacing helper (ns).
+ * - Support composable plugins with parent → children install and afterResolve.
+ *
+ * NOTE: This host is additive and does not alter the legacy CLI.
+ */
+class GetDotenvCli extends Command {
+    /** Registered top-level plugins (composition happens via .use()) */
+    _plugins = [];
+    /** One-time installation guard */
+    _installed = false;
+    constructor(alias = 'getdotenv') {
+        super(alias);
+        // Ensure subcommands that use passThroughOptions can be attached safely.
+        // Commander requires parent commands to enable positional options when a
+        // child uses passThroughOptions.
+        this.enablePositionalOptions();
+        // Skeleton preSubcommand hook: produce a context if absent, without
+        // mutating process.env. The passOptions hook (when installed) will
+        // compute the final context using merged CLI options; keeping
+        // loadProcess=false here avoids leaking dotenv values into the parent
+        // process env before subcommands execute.
+        this.hook('preSubcommand', async () => {
+            if (this.getCtx())
+                return;
+            await this.resolveAndLoad({ loadProcess: false });
         });
-})
-    .addCommand(cmdCommand$1, { isDefault: true });
-
-const cmdCommand = new Command()
-    .name('cmd')
-    .description('Batch execute command according to the --shell option, conflicts with --command option (default subcommand)')
-    .configureHelp({ showGlobalOptions: true })
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .action(async (_options, thisCommand) => {
-    const args = thisCommand.args;
-    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',
-    });
-});
+    }
+    /**
+     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
+     */
+    async resolveAndLoad(customOptions = {}) {
+        // Resolve defaults, then validate strictly under the new host.
+        const optionsResolved = await resolveGetDotenvOptions(customOptions);
+        getDotenvOptionsSchemaResolved.parse(optionsResolved);
+        // Delegate the heavy lifting to the shared helper (guarded path supported).
+        const ctx = await computeContext(optionsResolved, this._plugins, HOST_META_URL);
+        // Persist context on the instance for later access.
+        this[CTX_SYMBOL] =
+            ctx;
+        // Ensure plugins are installed exactly once, then run afterResolve.
+        await this.install();
+        await this._runAfterResolve(ctx);
+        return ctx;
+    }
+    /**
+     * Retrieve the current invocation context (if any).
+     */
+    getCtx() {
+        return this[CTX_SYMBOL];
+    }
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name) {
+        return this.command(name);
+    }
+    /**
+     * Register a plugin for installation (parent level).
+     * Installation occurs on first resolveAndLoad() (or explicit install()).
+     */
+    use(plugin) {
+        this._plugins.push(plugin);
+        // Immediately run setup so subcommands exist before parsing.
+        const setupOne = (p) => {
+            p.setup(this);
+            for (const child of p.children)
+                setupOne(child);
+        };
+        setupOne(plugin);
+        return this;
+    }
+    /**
+     * Install all registered plugins in parent → children (pre-order).
+     * Runs only once per CLI instance.
+     */
+    async install() {
+        // Setup is performed immediately in use(); here we only guard for afterResolve.
+        this._installed = true;
+        // Satisfy require-await without altering behavior.
+        await Promise.resolve();
+    }
+    /**
+     * Run afterResolve hooks for all plugins (parent → children).
+     */
+    async _runAfterResolve(ctx) {
+        const run = async (p) => {
+            if (p.afterResolve)
+                await p.afterResolve(this, ctx);
+            for (const child of p.children)
+                await run(child);
+        };
+        for (const p of this._plugins)
+            await run(p);
+    }
+}
 
 /**
- * Create the root Commander command with all options and subcommands.
- * Pure builder: no side-effects; the caller attaches lifecycle hooks.
+ * Attach legacy root flags to a Commander program.
+ * Uses provided defaults to render help labels without coupling to generators.
  */
-const createRootCommand = (opts) => {
-    const { alias, debug, defaultEnv, description, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = opts;
-    const excludeAll = !!excludeDynamic &&
-        ((!!excludeEnv && !!excludeGlobal) ||
-            (!!excludePrivate && !!excludePublic));
-    const program = new Command()
-        .name(alias)
-        .description(description)
+const attachRootOptions = (program, defaults, opts) => {
+    const { defaultEnv, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
+    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
+    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
+    // Build initial chain.
+    let p = program
         .enablePositionalOptions()
         .passThroughOptions()
-        .option('-e, --env <string>', `target environment (dotenv-expanded)`, dotenvExpandFromProcessEnv, env)
-        .option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${[
+        .option('-e, --env <string>', `target environment (dotenv-expanded)`, dotenvExpandFromProcessEnv, env);
+    p = p.option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${[
         ['KEY1', 'VAL1'],
         ['KEY2', 'VAL2'],
     ]
-        .map((v) => v.join(varsAssignor ?? '='))
-        .join(varsDelimiter ?? ' ')}`, dotenvExpandFromProcessEnv)
-        .option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv)
+        .map((v) => v.join(va))
+        .join(vd)}`, dotenvExpandFromProcessEnv);
+    // Optional legacy root command flag (kept for generated CLI compatibility).
+    // Default is OFF; the generator opts in explicitly.
+    if (opts?.includeCommandOption === true) {
+        p = p.option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv);
+    }
+    p = p
         .option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath)
         .addOption(new Option('-s, --shell [string]', (() => {
-        const defaultLabel = shell
-            ? ` (default ${typeof shell === 'boolean' ? 'OS shell' : shell})`
-            : '';
+        let defaultLabel = '';
+        if (shell !== undefined) {
+            if (typeof shell === 'boolean') {
+                defaultLabel = ' (default OS shell)';
+            }
+            else if (typeof shell === 'string') {
+                // Safe string interpolation
+                defaultLabel = ` (default ${shell})`;
+            }
+        }
         return `command execution shell, no argument for default OS shell or provide shell string${defaultLabel}`;
     })()).conflicts('shellOff'))
         .addOption(new Option('-S, --shell-off', `command execution shell OFF${!shell ? ' (default)' : ''}`).conflicts('shell'))
         .addOption(new Option('-p, --load-process', `load variables to process.env ON${loadProcess ? ' (default)' : ''}`).conflicts('loadProcessOff'))
         .addOption(new Option('-P, --load-process-off', `load variables to process.env OFF${!loadProcess ? ' (default)' : ''}`).conflicts('loadProcess'))
-        .addOption(new Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeAll ? ' (default)' : ''}`).conflicts('excludeAllOff'))
-        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF${!excludeAll ? ' (default)' : ''}`).conflicts('excludeAll'))
+        .addOption(new Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeDynamic &&
+        ((excludeEnv && excludeGlobal) || (excludePrivate && excludePublic))
+        ? ' (default)'
+        : ''}`).conflicts('excludeAllOff'))
+        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'))
         .addOption(new Option('-z, --exclude-dynamic', `exclude dynamic dotenv variables from loading ON${excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamicOff'))
         .addOption(new Option('-Z, --exclude-dynamic-off', `exclude dynamic dotenv variables from loading OFF${!excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamic'))
         .addOption(new Option('-n, --exclude-env', `exclude environment-specific dotenv variables from loading${excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnvOff'))
@@ -425,8 +1130,7 @@ const createRootCommand = (opts) => {
         .addOption(new Option('-U, --exclude-public-off', `exclude public dotenv variables from loading OFF${!excludePublic ? ' (default)' : ''}`).conflicts('excludePublic'))
         .addOption(new Option('-l, --log', `console log loaded variables ON${log ? ' (default)' : ''}`).conflicts('logOff'))
         .addOption(new Option('-L, --log-off', `console log loaded variables OFF${!log ? ' (default)' : ''}`).conflicts('log'))
-        .addOption(new Option('-d, --debug', `debug mode ON${debug ? ' (default)' : ''}`).conflicts('debugOff'))
-        .addOption(new Option('-D, --debug-off', `debug mode OFF${!debug ? ' (default)' : ''}`).conflicts('debug'))
+        .option('--capture', 'capture child process stdio for commands (tests/CI)')
         .option('--default-env <string>', 'default target environment', dotenvExpandFromProcessEnv, defaultEnv)
         .option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file', dotenvExpandFromProcessEnv, dotenvToken)
         .option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)', dotenvExpandFromProcessEnv, dynamicPath)
@@ -438,579 +1142,1918 @@ const createRootCommand = (opts) => {
         .option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern', varsDelimiterPattern)
         .option('--vars-assignor <string>', 'vars assignment operator string', varsAssignor)
         .option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern', varsAssignorPattern)
+        // Hidden scripts pipe-through (stringified)
         .addOption(new Option('--scripts <string>')
         .default(JSON.stringify(scripts))
-        .hideHelp())
-        .addCommand(batchCommand)
-        .addCommand(cmdCommand, { isDefault: true });
-    return program;
+        .hideHelp());
+    // Diagnostics: opt-in tracing; optional variadic keys after the flag.
+    p = p.option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
+    return p;
 };
 
-/** @internal */
-const isPlainObject = (value) => value !== null &&
-    typeof value === 'object' &&
-    Object.getPrototypeOf(value) === Object.prototype;
-const mergeInto = (target, source) => {
-    for (const [key, sVal] of Object.entries(source)) {
-        if (sVal === undefined)
-            continue; // do not overwrite with undefined
-        const tVal = target[key];
-        if (isPlainObject(tVal) && isPlainObject(sVal)) {
-            target[key] = mergeInto({ ...tVal }, sVal);
-        }
-        else if (isPlainObject(sVal)) {
-            target[key] = mergeInto({}, sVal);
-        }
-        else {
-            target[key] = sVal;
-        }
-    }
-    return target;
-};
 /**
- * Perform a deep defaults-style merge across plain objects. *
- * - Only merges plain objects (prototype === Object.prototype).
- * - Arrays and non-objects are replaced, not merged.
- * - `undefined` values are ignored and do not overwrite prior values.
+ * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
+ * - If the user explicitly enabled the flag, return true.
+ * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
+ * - Otherwise, adopt the default (true → set; false/undefined → unset).
  *
- * @typeParam T - The resulting shape after merging all layers.
- * @param layers - Zero or more partial layers in ascending precedence order.
- * @returns The merged object typed as {@link T}.
+ * @param exclude - The "on" flag value as parsed by Commander.
+ * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
+ * @param defaultValue - The generator default to adopt when no explicit toggle is present.
+ * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
  *
  * @example
- * defaultsDeep(\{ a: 1, nested: \{ b: 2 \} \}, \{ nested: \{ b: 3, c: 4 \} \})
- * =\> \{ a: 1, nested: \{ b: 3, c: 4 \} \}
+ * ```ts
+ * resolveExclusion(undefined, undefined, true); // => true
+ * ```
  */
-const defaultsDeep = (...layers) => {
-    const result = layers
-        .filter(Boolean)
-        .reduce((acc, layer) => mergeInto(acc, layer), {});
-    return result;
-};
-
-// src/GetDotenvOptions.ts
-const getDotenvOptionsFilename = 'getdotenv.config.json';
+const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
 /**
- * Converts programmatic CLI options to `getDotenv` options.
+ * Resolve an optional flag with "--exclude-all" overrides.
+ * If excludeAll is set and the individual "...-off" is not, force true.
+ * If excludeAllOff is set and the individual flag is not explicitly set, unset.
+ * Otherwise, adopt the default (true → set; false/undefined → unset).
  *
- * @param cliOptions - CLI options. Defaults to `{}`.
+ * @param exclude - Individual include/exclude flag.
+ * @param excludeOff - Individual "...-off" flag.
+ * @param defaultValue - Default for the individual flag.
+ * @param excludeAll - Global "exclude-all" flag.
+ * @param excludeAllOff - Global "exclude-all-off" flag.
  *
- * @returns `getDotenv` options.
+ * @example
+ * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
  */
-const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }) => {
-    /**
-     * Convert CLI-facing string options into {@link GetDotenvOptions}.
-     *
-     * - Splits {@link GetDotenvCliOptions.paths} using either a delimiter
-     *   or a regular expression pattern into a string array.
-     * - Parses {@link GetDotenvCliOptions.vars} as space-separated `KEY=VALUE`
-     *   pairs (configurable delimiters) into a {@link ProcessEnv}.
-     * - Drops CLI-only keys that have no programmatic equivalent.
-     *
-     * @remarks
-     * Follows exact-optional semantics by not emitting undefined-valued entries.
-     */
-    // Drop CLI-only keys
-    const { debug, scripts, ...restFlags } = rest;
-    const splitBy = (value, delim, pattern) => (value ? value.split(pattern ? RegExp(pattern) : (delim ?? ' ')) : []);
-    const kvPairs = (vars
-        ? splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
-            ? RegExp(varsAssignorPattern)
-            : (varsAssignor ?? '=')))
-        : []);
-    const parsedVars = Object.fromEntries(kvPairs);
-    return {
-        ...restFlags,
-        paths: splitBy(paths, pathsDelimiter, pathsDelimiterPattern),
-        vars: parsedVars,
-    };
+const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
+// Order of precedence:
+// 1) Individual explicit "on" wins outright.
+// 2) Individual explicit "off" wins over any global.
+// 3) Global exclude-all forces true when not explicitly turned off.
+// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
+// 5) Fall back to the default (true => set; false/undefined => unset).
+(() => {
+    // Individual "on"
+    if (exclude === true)
+        return true;
+    // Individual "off"
+    if (excludeOff === true)
+        return undefined;
+    // Global "exclude-all" ON (unless explicitly turned off)
+    if (excludeAll === true)
+        return true;
+    // Global "exclude-all-off" (unless explicitly enabled)
+    if (excludeAllOff === true)
+        return undefined;
+    // Default
+    return defaultValue ? true : undefined;
+})();
+/**
+ * exactOptionalPropertyTypes-safe setter for optional boolean flags:
+ * delete when undefined; assign when defined — without requiring an index signature on T.
+ *
+ * @typeParam T - Target object type.
+ * @param obj - The object to write to.
+ * @param key - The optional boolean property key of {@link T}.
+ * @param value - The value to set or `undefined` to unset.
+ *
+ * @remarks
+ * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ */
+const setOptionalFlag = (obj, key, value) => {
+    const target = obj;
+    const k = key;
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    if (value === undefined)
+        delete target[k];
+    else
+        target[k] = value;
 };
-const resolveGetDotenvOptions = async (customOptions) => {
-    /**
-     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
-     *
-     * 1. Base defaults derived from the CLI generator defaults
-     *    ({@link baseGetDotenvCliOptions}).
-     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
-     *    package root (if present).
-     * 3. The provided {@link customOptions}.
-     *
-     * The result preserves explicit empty values and drops only `undefined`.
-     *
-     * @returns Fully-resolved {@link GetDotenvOptions}.
-     *
-     * @example
-     * ```ts
-     * const options = await resolveGetDotenvOptions({ env: 'dev' });
-     * ```
-     */
-    const localPkgDir = await packageDirectory();
-    const localOptionsPath = localPkgDir
-        ? join(localPkgDir, getDotenvOptionsFilename)
+
+/**
+ * Merge and normalize raw Commander options (current + parent + defaults)
+ * into a GetDotenvCliOptions-like object. Types are intentionally wide to
+ * avoid cross-layer coupling; callers may cast as needed.
+ */
+const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
+    const parent = typeof parentJson === 'string' && parentJson.length > 0
+        ? JSON.parse(parentJson)
         : undefined;
-    const localOptions = (localOptionsPath && (await fs.exists(localOptionsPath))
-        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
-        : {});
-    // Merge order: base < local < custom (custom has highest precedence)
-    const mergedCli = defaultsDeep(baseGetDotenvCliOptions, localOptions);
-    const defaultsFromCli = getDotenvCliOptions2Options(mergedCli);
-    const result = defaultsDeep(defaultsFromCli, customOptions);
+    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, scripts, shellOff, ...rest } = rawCliOptions;
+    const current = { ...rest };
+    if (typeof scripts === 'string') {
+        try {
+            current.scripts = JSON.parse(scripts);
+        }
+        catch {
+            // ignore parse errors; leave scripts undefined
+        }
+    }
+    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
+    const d = defaults;
+    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
+    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
+    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
+    // Normalize shell for predictability: explicit default shell per OS.
+    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
+    let resolvedShell = merged.shell;
+    if (shellOff)
+        resolvedShell = false;
+    else if (resolvedShell === true || resolvedShell === undefined) {
+        resolvedShell = defaultShell;
+    }
+    else if (typeof resolvedShell !== 'string' &&
+        typeof defaults.shell === 'string') {
+        resolvedShell = defaults.shell;
+    }
+    merged.shell = resolvedShell;
+    const cmd = typeof command === 'string' ? command : undefined;
+    return cmd !== undefined ? { merged, command: cmd } : { merged };
+};
+
+GetDotenvCli.prototype.attachRootOptions = function (defaults, opts) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    attachRootOptions(this, d, opts);
+    return this;
+};
+GetDotenvCli.prototype.passOptions = function (defaults) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    this.hook('preSubcommand', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        // Persist merged options for nested invocations (batch exec).
+        thisCommand.getDotenvCliOptions =
+            merged;
+        // Build service options and compute context (always-on config loader path).
+        const serviceOptions = getDotenvCliOptions2Options(merged);
+        await this.resolveAndLoad(serviceOptions);
+    });
+    // Also handle root-level flows (no subcommand) so option-aliases can run
+    // with the same merged options and context without duplicating logic.
+    this.hook('preAction', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        thisCommand.getDotenvCliOptions =
+            merged;
+        // Avoid duplicate heavy work if a context is already present.
+        if (!this.getCtx()) {
+            const serviceOptions = getDotenvCliOptions2Options(merged);
+            await this.resolveAndLoad(serviceOptions);
+        }
+    });
+    return this;
+};
+
+// 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$1 = (...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;
+};
+// Extract exitCode/stdout/stderr from execa result or error in a tolerant way.
+const pickResult = (r) => {
+    const exit = r.exitCode;
+    const stdoutVal = r.stdout;
+    const stderrVal = r.stderr;
     return {
-        ...result, // Keep explicit empty strings/zeros; drop only undefined
-        vars: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
+        exitCode: typeof exit === 'number' ? exit : Number.NaN,
+        stdout: typeof stdoutVal === 'string' ? stdoutVal : '',
+        stderr: typeof stderrVal === 'string' ? stderrVal : '',
     };
 };
+// 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;
+};
+/**
+ * Execute a command and capture stdout/stderr (buffered).
+ * - Preserves plain vs shell behavior and argv/string normalization.
+ * - Never re-emits stdout/stderr to parent; returns captured buffers.
+ * - Supports optional timeout (ms).
+ */
+const runCommandResult = async (command, shell, opts = {}) => {
+    const envSan = sanitizeEnv(opts.env);
+    {
+        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 { exitCode: 0, stdout: '', stderr: '' };
+        dbg$1('exec:capture (plain)', { file, args });
+        try {
+            const result = await execa(file, args, {
+                ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                ...(envSan !== undefined ? { env: envSan } : {}),
+                stdio: 'pipe',
+                ...(opts.timeoutMs !== undefined
+                    ? { timeout: opts.timeoutMs, killSignal: 'SIGKILL' }
+                    : {}),
+            });
+            const ok = pickResult(result);
+            dbg$1('exit:capture (plain)', { exitCode: ok.exitCode });
+            return ok;
+        }
+        catch (err) {
+            const out = pickResult(err);
+            dbg$1('exit:capture:error (plain)', { exitCode: out.exitCode });
+            return out;
+        }
+    }
+};
+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$1('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$1('exit (plain)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+    else {
+        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        dbg$1('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$1('exit (shell)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+};
 
 /**
- * Resolve `GetDotenvCliGenerateOptions` from `import.meta.url` and custom options.
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
  */
-const resolveGetDotenvCliGenerateOptions = async ({ importMetaUrl, ...customOptions }) => {
-    const baseOptions = {
-        ...baseGetDotenvCliOptions,
-        alias: 'getdotenv',
-        description: 'Base CLI.',
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
     };
-    const globalPkgDir = importMetaUrl
-        ? await packageDirectory({
-            cwd: fileURLToPath(importMetaUrl),
-        })
-        : undefined;
-    const globalOptionsPath = globalPkgDir
-        ? join(globalPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    const globalOptions = (globalOptionsPath && (await fs.exists(globalOptionsPath))
-        ? JSON.parse((await fs.readFile(globalOptionsPath)).toString())
-        : {});
-    const localPkgDir = await packageDirectory();
-    const localOptionsPath = localPkgDir
-        ? join(localPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    const localOptions = (localOptionsPath &&
-        localOptionsPath !== globalOptionsPath &&
-        (await fs.exists(localOptionsPath))
-        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
-        : {});
-    // Merge order: base < global < local < custom
-    const merged = defaultsDeep(baseOptions, globalOptions, localOptions, customOptions);
-    return merged;
+    return plugin;
 };
 
 /**
- * Asynchronously read a dotenv file & parse it into an object.
+ * 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 path - Path to dotenv file.
- * @returns The parsed dotenv object.
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @returns Resolved command string (falls back to the provided command).
  */
-const readDotenv = async (path) => {
+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);
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const trim = (s) => (typeof s === 'string' ? s.trim() : '');
+const unquote = (s) => s.length >= 2 &&
+    ((s.startsWith('"') && s.endsWith('"')) ||
+        (s.startsWith("'") && s.endsWith("'")))
+    ? s.slice(1, -1)
+    : s;
+const parseExportCredentialsJson = (txt) => {
     try {
-        return (await fs.exists(path)) ? parse(await fs.readFile(path)) : {};
+        const obj = JSON.parse(txt);
+        const src = obj.Credentials ?? obj;
+        const ak = src.AccessKeyId;
+        const sk = src.SecretAccessKey;
+        const tk = src.SessionToken;
+        if (ak && sk)
+            return {
+                accessKeyId: ak,
+                secretAccessKey: sk,
+                ...(tk ? { sessionToken: tk } : {}),
+            };
     }
     catch {
-        return {};
+        /* ignore */
     }
+    return undefined;
 };
-
-const importDefault = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
+const parseExportCredentialsEnv = (txt) => {
+    const lines = txt.split(/\r?\n/);
+    let id;
+    let secret;
+    let token;
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        // POSIX: export AWS_ACCESS_KEY_ID=..., export AWS_SECRET_ACCESS_KEY=..., export AWS_SESSION_TOKEN=...
+        let m = /^export\s+([A-Z0-9_]+)\s*=\s*(.+)$/.exec(line);
+        if (!m) {
+            // PowerShell: $Env:AWS_ACCESS_KEY_ID="...", etc.
+            m = /^\$Env:([A-Z0-9_]+)\s*=\s*(.+)$/.exec(line);
+        }
+        if (!m)
+            continue;
+        const k = m[1];
+        const valRaw = m[2];
+        if (typeof valRaw !== 'string')
+            continue;
+        let v = unquote(valRaw.trim());
+        // Drop trailing semicolons if present (some shells)
+        v = v.replace(/;$/, '');
+        if (k === 'AWS_ACCESS_KEY_ID')
+            id = v;
+        else if (k === 'AWS_SECRET_ACCESS_KEY')
+            secret = v;
+        else if (k === 'AWS_SESSION_TOKEN')
+            token = v;
+    }
+    if (id && secret)
+        return {
+            accessKeyId: id,
+            secretAccessKey: secret,
+            ...(token ? { sessionToken: token } : {}),
+        };
+    return undefined;
 };
-/**
- * @internal Compute a short hash from path + mtime for cache filenames.
- */
-const cacheHash = (absPath, mtimeMs) => createHash('sha1')
-    .update(absPath)
-    .update(String(mtimeMs))
-    .digest('hex')
-    .slice(0, 12);
-/**
- * @internal Load a dynamic module from path. Supports .js/.mjs/.ts/.tsx:
- * - .js/.mjs: direct import
- * - .ts/.tsx: try direct import (in case a TS loader is active), otherwise:
- *   - esbuild (if present): bundle to a temp ESM file and import it
- *   - fallback: typescript.transpileModule (single-file), then import temp file
- */
-const loadDynamicFromPath = async (absPath) => {
-    if (!(await fs.exists(absPath)))
+const getAwsConfigure = async (key, profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+    const r = await runCommandResult(['aws', 'configure', 'get', key, '--profile', profile], false, {
+        env: process.env,
+        timeoutMs,
+    });
+    // Guard for mocked undefined in tests; keep narrow lint scope.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!r || typeof r.exitCode !== 'number')
         return undefined;
-    const ext = path.extname(absPath).toLowerCase();
-    const fileUrl = url.pathToFileURL(absPath).toString();
-    if (ext !== '.ts' && ext !== '.tsx') {
-        return importDefault(fileUrl);
+    if (r.exitCode === 0) {
+        const v = trim(r.stdout);
+        return v.length > 0 ? v : undefined;
     }
-    // Try direct import (in case user started Node with a TS loader).
-    try {
-        const dyn = await importDefault(fileUrl);
-        if (dyn)
-            return dyn;
+    return undefined;
+};
+const exportCredentials = async (profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+    // Try JSON format first (AWS CLI v2)
+    const rJson = await runCommandResult([
+        'aws',
+        'configure',
+        'export-credentials',
+        '--profile',
+        profile,
+        '--format',
+        'json',
+    ], false, { env: process.env, timeoutMs });
+    if (rJson.exitCode === 0) {
+        const creds = parseExportCredentialsJson(rJson.stdout);
+        if (creds)
+            return creds;
     }
-    catch {
-        // ignore; fall through to compile
+    // Fallback: env lines
+    const rEnv = await runCommandResult(['aws', 'configure', 'export-credentials', '--profile', profile], false, { env: process.env, timeoutMs });
+    if (rEnv.exitCode === 0) {
+        const creds = parseExportCredentialsEnv(rEnv.stdout);
+        if (creds)
+            return creds;
     }
-    const stat = await fs.stat(absPath);
-    const hash = cacheHash(absPath, stat.mtimeMs);
-    const cacheDir = path.resolve('.tsbuild', 'getdotenv-dynamic');
-    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
-    // Try esbuild first
-    try {
-        const esbuild = (await import('esbuild'));
-        await fs.ensureDir(cacheDir);
-        await esbuild.build({
-            entryPoints: [absPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            target: 'node22',
-            outfile: cacheFile,
-            sourcemap: false,
-            logLevel: 'silent',
+    return undefined;
+};
+const resolveAwsContext = async ({ dotenv, cfg, }) => {
+    const profileKey = cfg.profileKey ?? 'AWS_LOCAL_PROFILE';
+    const profileFallbackKey = cfg.profileFallbackKey ?? 'AWS_PROFILE';
+    const regionKey = cfg.regionKey ?? 'AWS_REGION';
+    const profile = cfg.profile ??
+        dotenv[profileKey] ??
+        dotenv[profileFallbackKey] ??
+        undefined;
+    let region = cfg.region ?? dotenv[regionKey] ?? undefined;
+    // Short-circuit when strategy is disabled.
+    if (cfg.strategy === 'none') {
+        // If region is still missing and we have a profile, try best-effort region resolve.
+        if (!region && profile)
+            region = await getAwsConfigure('region', profile);
+        if (!region && cfg.defaultRegion)
+            region = cfg.defaultRegion;
+        const out = {};
+        if (profile !== undefined)
+            out.profile = profile;
+        if (region !== undefined)
+            out.region = region;
+        return out;
+    }
+    // Env-first credentials.
+    let credentials;
+    const envId = trim(process.env.AWS_ACCESS_KEY_ID);
+    const envSecret = trim(process.env.AWS_SECRET_ACCESS_KEY);
+    const envToken = trim(process.env.AWS_SESSION_TOKEN);
+    if (envId && envSecret) {
+        credentials = {
+            accessKeyId: envId,
+            secretAccessKey: envSecret,
+            ...(envToken ? { sessionToken: envToken } : {}),
+        };
+    }
+    else if (profile) {
+        // Try export-credentials
+        credentials = await exportCredentials(profile);
+        // On failure, detect SSO and optionally login then retry
+        if (!credentials) {
+            const ssoSession = await getAwsConfigure('sso_session', profile);
+            const looksSSO = typeof ssoSession === 'string' && ssoSession.length > 0;
+            if (looksSSO && cfg.loginOnDemand) {
+                // Best-effort login, then retry export once.
+                await runCommandResult(['aws', 'sso', 'login', '--profile', profile], false, {
+                    env: process.env,
+                    timeoutMs: DEFAULT_TIMEOUT_MS,
+                });
+                credentials = await exportCredentials(profile);
+            }
+        }
+        // Static fallback if still missing.
+        if (!credentials) {
+            const id = await getAwsConfigure('aws_access_key_id', profile);
+            const secret = await getAwsConfigure('aws_secret_access_key', profile);
+            const token = await getAwsConfigure('aws_session_token', profile);
+            if (id && secret) {
+                credentials = {
+                    accessKeyId: id,
+                    secretAccessKey: secret,
+                    ...(token ? { sessionToken: token } : {}),
+                };
+            }
+        }
+    }
+    // Final region resolution
+    if (!region && profile)
+        region = await getAwsConfigure('region', profile);
+    if (!region && cfg.defaultRegion)
+        region = cfg.defaultRegion;
+    const out = {};
+    if (profile !== undefined)
+        out.profile = profile;
+    if (region !== undefined)
+        out.region = region;
+    if (credentials)
+        out.credentials = credentials;
+    return out;
+};
+
+const AwsPluginConfigSchema = z.object({
+    profile: z.string().optional(),
+    region: z.string().optional(),
+    defaultRegion: z.string().optional(),
+    profileKey: z.string().default('AWS_LOCAL_PROFILE').optional(),
+    profileFallbackKey: z.string().default('AWS_PROFILE').optional(),
+    regionKey: z.string().default('AWS_REGION').optional(),
+    strategy: z.enum(['cli-export', 'none']).default('cli-export').optional(),
+    loginOnDemand: z.boolean().default(false).optional(),
+    setEnv: z.boolean().default(true).optional(),
+    addCtx: z.boolean().default(true).optional(),
+});
+
+const awsPlugin = () => definePlugin({
+    id: 'aws',
+    // Host validates this slice when the loader path is active.
+    configSchema: AwsPluginConfigSchema,
+    setup(cli) {
+        // Subcommand: aws
+        cli
+            .ns('aws')
+            .description('Establish an AWS session and optionally forward to the AWS CLI')
+            .configureHelp({ showGlobalOptions: true })
+            .enablePositionalOptions()
+            .passThroughOptions()
+            .allowUnknownOption(true)
+            // Boolean toggles
+            .option('--login-on-demand', 'attempt aws sso login on-demand')
+            .option('--no-login-on-demand', 'disable sso login on-demand')
+            .option('--set-env', 'write resolved values into process.env')
+            .option('--no-set-env', 'do not write resolved values into process.env')
+            .option('--add-ctx', 'mirror results under ctx.plugins.aws')
+            .option('--no-add-ctx', 'do not mirror results under ctx.plugins.aws')
+            // Strings / enums
+            .option('--profile <string>', 'AWS profile name')
+            .option('--region <string>', 'AWS region')
+            .option('--default-region <string>', 'fallback region')
+            .option('--strategy <string>', 'credential acquisition strategy: cli-export|none')
+            // Advanced key overrides
+            .option('--profile-key <string>', 'dotenv/config key for local profile')
+            .option('--profile-fallback-key <string>', 'fallback dotenv/config key for profile')
+            .option('--region-key <string>', 'dotenv/config key for region')
+            // Accept any extra operands so Commander does not error when tokens appear after "--".
+            .argument('[args...]')
+            .action(async (args, opts, thisCommand) => {
+            const self = thisCommand;
+            const parent = (self.parent ?? null);
+            // Access merged root CLI options (installed by passOptions())
+            const rootOpts = (parent?.getDotenvCliOptions ?? {});
+            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+                Boolean(rootOpts?.capture);
+            const underTests = process.env.GETDOTENV_TEST === '1' ||
+                typeof process.env.VITEST_WORKER_ID === 'string';
+            // Build overlay cfg from subcommand flags layered over discovered config.
+            const ctx = cli.getCtx();
+            const cfgBase = (ctx?.pluginConfigs?.['aws'] ??
+                {});
+            const overlay = {};
+            // Map boolean toggles (respect explicit --no-*)
+            if (Object.prototype.hasOwnProperty.call(opts, 'loginOnDemand'))
+                overlay.loginOnDemand = Boolean(opts.loginOnDemand);
+            if (Object.prototype.hasOwnProperty.call(opts, 'setEnv'))
+                overlay.setEnv = Boolean(opts.setEnv);
+            if (Object.prototype.hasOwnProperty.call(opts, 'addCtx'))
+                overlay.addCtx = Boolean(opts.addCtx);
+            // Strings/enums
+            if (typeof opts.profile === 'string')
+                overlay.profile = opts.profile;
+            if (typeof opts.region === 'string')
+                overlay.region = opts.region;
+            if (typeof opts.defaultRegion === 'string')
+                overlay.defaultRegion = opts.defaultRegion;
+            if (typeof opts.strategy === 'string')
+                overlay.strategy =
+                    opts.strategy;
+            // Advanced key overrides
+            if (typeof opts.profileKey === 'string')
+                overlay.profileKey = opts.profileKey;
+            if (typeof opts.profileFallbackKey === 'string')
+                overlay.profileFallbackKey = opts.profileFallbackKey;
+            if (typeof opts.regionKey === 'string')
+                overlay.regionKey = opts.regionKey;
+            const cfg = {
+                ...cfgBase,
+                ...overlay,
+            };
+            // Resolve current context with overrides
+            const out = await resolveAwsContext({
+                dotenv: ctx?.dotenv ?? {},
+                cfg,
+            });
+            // Apply env/ctx mirrors per toggles
+            if (cfg.setEnv !== false) {
+                if (out.region) {
+                    process.env.AWS_REGION = out.region;
+                    if (!process.env.AWS_DEFAULT_REGION)
+                        process.env.AWS_DEFAULT_REGION = out.region;
+                }
+                if (out.credentials) {
+                    process.env.AWS_ACCESS_KEY_ID = out.credentials.accessKeyId;
+                    process.env.AWS_SECRET_ACCESS_KEY =
+                        out.credentials.secretAccessKey;
+                    if (out.credentials.sessionToken !== undefined) {
+                        process.env.AWS_SESSION_TOKEN = out.credentials.sessionToken;
+                    }
+                }
+            }
+            if (cfg.addCtx !== false) {
+                if (ctx) {
+                    ctx.plugins ??= {};
+                    ctx.plugins['aws'] = {
+                        ...(out.profile ? { profile: out.profile } : {}),
+                        ...(out.region ? { region: out.region } : {}),
+                        ...(out.credentials ? { credentials: out.credentials } : {}),
+                    };
+                }
+            }
+            // Forward when positional args are present; otherwise session-only.
+            if (Array.isArray(args) && args.length > 0) {
+                const argv = ['aws', ...args];
+                const shellSetting = resolveShell(rootOpts?.scripts, 'aws', rootOpts?.shell);
+                const ctxDotenv = (ctx?.dotenv ?? {});
+                const exit = await runCommand(argv, shellSetting, {
+                    env: { ...process.env, ...ctxDotenv },
+                    stdio: capture ? 'pipe' : 'inherit',
+                });
+                // Deterministic termination (suppressed under tests)
+                if (!underTests) {
+                    process.exit(typeof exit === 'number' ? exit : 0);
+                }
+                return;
+            }
+            else {
+                // Session only: low-noise breadcrumb under debug
+                if (process.env.GETDOTENV_DEBUG) {
+                    const log = console;
+                    log.log('[aws] session established', {
+                        profile: out.profile,
+                        region: out.region,
+                        hasCreds: Boolean(out.credentials),
+                    });
+                }
+                if (!underTests)
+                    process.exit(0);
+                return;
+            }
+        });
+    },
+    async afterResolve(_cli, ctx) {
+        const log = console;
+        const cfgRaw = (ctx.pluginConfigs?.['aws'] ?? {});
+        const cfg = (cfgRaw || {});
+        const out = await resolveAwsContext({
+            dotenv: ctx.dotenv,
+            cfg,
         });
-        return await importDefault(url.pathToFileURL(cacheFile).toString());
+        const { profile, region, credentials } = out;
+        if (cfg.setEnv !== false) {
+            if (region) {
+                process.env.AWS_REGION = region;
+                if (!process.env.AWS_DEFAULT_REGION)
+                    process.env.AWS_DEFAULT_REGION = region;
+            }
+            if (credentials) {
+                process.env.AWS_ACCESS_KEY_ID = credentials.accessKeyId;
+                process.env.AWS_SECRET_ACCESS_KEY = credentials.secretAccessKey;
+                if (credentials.sessionToken !== undefined) {
+                    process.env.AWS_SESSION_TOKEN = credentials.sessionToken;
+                }
+            }
+        }
+        if (cfg.addCtx !== false) {
+            ctx.plugins ??= {};
+            ctx.plugins['aws'] = {
+                ...(profile ? { profile } : {}),
+                ...(region ? { region } : {}),
+                ...(credentials ? { credentials } : {}),
+            };
+        }
+        // Optional: low-noise breadcrumb for diagnostics
+        if (process.env.GETDOTENV_DEBUG) {
+            log.log('[aws] afterResolve', {
+                profile,
+                region,
+                hasCreds: Boolean(credentials),
+            });
+        }
+    },
+});
+
+const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
+    let cwd = process.cwd();
+    if (pkgCwd) {
+        const pkgDir = await packageDirectory();
+        if (!pkgDir) {
+            logger.error('No package directory found.');
+            process.exit(0);
+        }
+        cwd = pkgDir;
     }
-    catch {
-        // no esbuild; fall back to TS transpile for simple modules
+    const absRootPath = path.posix.join(cwd.split(path.sep).join(path.posix.sep), rootPath.split(path.sep).join(path.posix.sep));
+    const paths = await globby(globs.split(/\s+/), {
+        cwd: absRootPath,
+        expandDirectories: false,
+        onlyDirectories: true,
+        absolute: true,
+    });
+    if (!paths.length) {
+        logger.error(`No paths found for globs '${globs}' at '${absRootPath}'.`);
+        process.exit(0);
     }
-    try {
-        const ts = (await import('typescript'));
-        const code = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(code, {
-            compilerOptions: {
-                module: 'ESNext',
-                target: 'ES2022',
-                moduleResolution: 'NodeNext',
-            },
+    return { absRootPath, paths };
+};
+const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
+    const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+        Boolean(getDotenvCliOptions?.capture); // Require a command only when not listing. In list mode, a command is optional.
+    if (!command && !list) {
+        logger.error(`No command provided. Use --command or --list.`);
+        process.exit(0);
+    }
+    const { absRootPath, paths } = await globPaths({
+        globs,
+        logger,
+        rootPath,
+        // exactOptionalPropertyTypes: only include when defined
+        ...(pkgCwd !== undefined ? { pkgCwd } : {}),
+    });
+    const headerTitle = list
+        ? 'Listing working directories...'
+        : 'Executing command batch...';
+    logger.info('');
+    const headerRootPath = `ROOT:  ${absRootPath}`;
+    const headerGlobs = `GLOBS: ${globs}`;
+    // Prepare a safe label for the header (avoid undefined in template)
+    const commandLabel = Array.isArray(command)
+        ? command.join(' ')
+        : typeof command === 'string' && command.length > 0
+            ? command
+            : '';
+    const headerCommand = list ? `CMD:   (list only)` : `CMD:   ${commandLabel}`;
+    logger.info('*'.repeat(Math.max(headerTitle.length, headerRootPath.length, headerGlobs.length, headerCommand.length)));
+    logger.info(headerTitle);
+    logger.info('');
+    logger.info(headerRootPath);
+    logger.info(headerGlobs);
+    logger.info(headerCommand);
+    for (const path of paths) {
+        // Write path and command to console.
+        const pathLabel = `CWD:   ${path}`;
+        if (list) {
+            logger.info(pathLabel);
+            continue;
+        }
+        logger.info('');
+        logger.info('*'.repeat(pathLabel.length));
+        logger.info(pathLabel);
+        logger.info(headerCommand);
+        // Execute command.
+        try {
+            const hasCmd = (typeof command === 'string' && command.length > 0) ||
+                (Array.isArray(command) && command.length > 0);
+            if (hasCmd) {
+                await runCommand(command, shell, {
+                    cwd: path,
+                    env: {
+                        ...process.env,
+                        getDotenvCliOptions: getDotenvCliOptions
+                            ? JSON.stringify(getDotenvCliOptions)
+                            : undefined,
+                    },
+                    stdio: capture ? 'pipe' : 'inherit',
+                });
+            }
+            else {
+                // Should not occur due to the early guard; retain for type safety.
+                logger.error(`No command provided. Use --command or --list.`);
+                process.exit(0);
+            }
+        }
+        catch (error) {
+            if (!ignoreErrors) {
+                throw error;
+            }
+        }
+    }
+    logger.info('');
+};
+
+/**
+ * Build the default "cmd" subcommand action for the batch plugin.
+ * Mirrors the original inline implementation with identical behavior.
+ */
+const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _subOpts, _thisCommand) => {
+    const loggerLocal = opts.logger ?? console;
+    // Guard: when invoked without positional args (e.g., `batch --list`),
+    // defer entirely to the parent action handler.
+    const argsRaw = Array.isArray(commandParts)
+        ? commandParts
+        : [];
+    const localList = argsRaw.includes('-l') || argsRaw.includes('--list');
+    const args = localList
+        ? argsRaw.filter((t) => t !== '-l' && t !== '--list')
+        : argsRaw;
+    // Access merged per-plugin config from host context (if any).
+    const ctx = cli.getCtx();
+    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
+    const cfg = (cfgRaw || {});
+    // Resolve batch flags from the captured parent (batch) command.
+    const raw = batchCmd.opts();
+    const listFromParent = !!raw.list;
+    const ignoreErrors = !!raw.ignoreErrors;
+    const globs = typeof raw.globs === 'string' ? raw.globs : (cfg.globs ?? '*');
+    const pkgCwd = raw.pkgCwd !== undefined ? !!raw.pkgCwd : !!cfg.pkgCwd;
+    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : (cfg.rootPath ?? './');
+    // Resolve scripts/shell with precedence:
+    // plugin opts → plugin config → merged root CLI options
+    const mergedBag = ((batchCmd.parent ?? null)?.getDotenvCliOptions ?? {});
+    const scripts = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
+    const shell = opts.shell ?? cfg.shell ?? mergedBag.shell;
+    // If no positional args were given, bridge to --command/--list paths here.
+    if (args.length === 0) {
+        const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
+        if (typeof commandOpt === 'string') {
+            await execShellCommandBatch({
+                command: resolveCommand(scripts, commandOpt),
+                globs,
+                ignoreErrors,
+                list: false,
+                logger: loggerLocal,
+                ...(pkgCwd ? { pkgCwd } : {}),
+                rootPath,
+                shell: resolveShell(scripts, commandOpt, shell),
+            });
+            return;
+        }
+        if (raw.list || localList) {
+            await execShellCommandBatch({
+                globs,
+                ignoreErrors,
+                list: true,
+                logger: loggerLocal,
+                ...(pkgCwd ? { pkgCwd } : {}),
+                rootPath,
+                shell: (shell ?? false),
+            });
+            return;
+        }
+        {
+            const lr = loggerLocal;
+            const emit = lr.error ?? lr.log;
+            emit(`No command provided. Use --command or --list.`);
+        }
+        process.exit(0);
+    }
+    // If a local list flag was supplied with positional tokens (and no --command),
+    // treat tokens as additional globs and execute list mode.
+    if (localList && typeof raw.command !== 'string') {
+        const extraGlobs = args.map(String).join(' ').trim();
+        const mergedGlobs = [globs, extraGlobs].filter(Boolean).join(' ');
+        const shellBag = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
+        await execShellCommandBatch({
+            globs: mergedGlobs,
+            ignoreErrors,
+            list: true,
+            logger: loggerLocal,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: (shell ?? shellBag.shell ?? false),
         });
-        await fs.ensureDir(cacheDir);
-        await fs.writeFile(cacheFile, out.outputText, 'utf-8');
-        return await importDefault(url.pathToFileURL(cacheFile).toString());
+        return;
     }
-    catch {
-        throw new Error(`Unable to load dynamic TypeScript file: ${absPath}. ` +
-            `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
+    // If parent list flag is set and positional tokens are present (and no --command),
+    // treat tokens as additional globs for list-only mode.
+    if (listFromParent && args.length > 0 && typeof raw.command !== 'string') {
+        const extra = args.map(String).join(' ').trim();
+        const mergedGlobs = [globs, extra].filter(Boolean).join(' ');
+        const mergedBag2 = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
+        await execShellCommandBatch({
+            globs: mergedGlobs,
+            ignoreErrors,
+            list: true,
+            logger: loggerLocal,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: (shell ?? mergedBag2.shell ?? false),
+        });
+        return;
     }
+    // Join positional args as the command to execute.
+    const input = args.map(String).join(' ');
+    // Optional: round-trip parent merged options if present (shipped CLI).
+    const envBag = (batchCmd.parent ?? undefined)?.getDotenvCliOptions;
+    const mergedExec = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
+    const scriptsExec = scripts ?? mergedExec.scripts;
+    const shellExec = shell ?? mergedExec.shell;
+    const resolved = resolveCommand(scriptsExec, input);
+    const shellSetting = resolveShell(scriptsExec, input, shellExec);
+    // Preserve argv array only for shell-off Node -e snippets to avoid
+    // lossy re-tokenization (Windows/PowerShell quoting). For simple
+    // commands (e.g., "echo OK") keep string form to satisfy unit tests.
+    let commandArg = resolved;
+    if (shellSetting === false && resolved === input) {
+        const first = (args[0] ?? '').toLowerCase();
+        const hasEval = args.includes('-e') || args.includes('--eval');
+        if (first === 'node' && hasEval) {
+            commandArg = args.map(String);
+        }
+    }
+    await execShellCommandBatch({
+        command: commandArg,
+        ...(envBag ? { getDotenvCliOptions: envBag } : {}),
+        globs,
+        ignoreErrors,
+        list: false,
+        logger: loggerLocal,
+        ...(pkgCwd ? { pkgCwd } : {}),
+        rootPath,
+        shell: shellSetting,
+    });
 };
+
 /**
- * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
- *
- * @param options - `GetDotenvOptions` object
- * @returns The combined parsed dotenv object.
- * * @example Load from the project root with default tokens
- * ```ts
- * const vars = await getDotenv();
- * console.log(vars.MY_SETTING);
- * ```
- *
- * @example Load from multiple paths and a specific environment
- * ```ts
- * const vars = await getDotenv({
- *   env: 'dev',
- *   dotenvToken: '.testenv',
- *   privateToken: 'secret',
- *   paths: ['./', './packages/app'],
- * });
- * ```
- *
- * @example Use dynamic variables
- * ```ts
- * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
- * const vars = await getDotenv({ dynamicPath: '.env.js' });
- * ```
- *
- * @remarks
- * - When {@link GetDotenvOptions.loadProcess} is true, the resulting variables are merged
- *   into `process.env` as a side effect.
- * - When {@link GetDotenvOptions.outputPath} is provided, a consolidated dotenv file is written.
- *   The path is resolved after expansion, so it may reference previously loaded vars.
+ * Build the parent "batch" action handler (no explicit subcommand).
+ */
+const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
+    const logger = opts.logger ?? console;
+    // Ensure context exists (host preSubcommand on root creates if missing).
+    const ctx = cli.getCtx();
+    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
+    const cfg = (cfgRaw || {});
+    const raw = thisCommand.opts();
+    const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
+    const ignoreErrors = !!raw.ignoreErrors;
+    let globs = typeof raw.globs === 'string' ? raw.globs : (cfg.globs ?? '*');
+    const list = !!raw.list;
+    const pkgCwd = raw.pkgCwd !== undefined ? !!raw.pkgCwd : !!cfg.pkgCwd;
+    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : (cfg.rootPath ?? './');
+    // Treat parent positional tokens as the command when no explicit 'cmd' is used.
+    const argsParent = Array.isArray(commandParts) ? commandParts : [];
+    if (argsParent.length > 0 && !list) {
+        const input = argsParent.map(String).join(' ');
+        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        const scriptsAll = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
+        const shellAll = opts.shell ?? cfg.shell ?? mergedBag.shell;
+        const resolved = resolveCommand(scriptsAll, input);
+        const shellSetting = resolveShell(scriptsAll, input, shellAll);
+        // Parent path: pass a string; executor handles shell-specific details.
+        const commandArg = resolved;
+        await execShellCommandBatch({
+            command: commandArg,
+            globs,
+            ignoreErrors,
+            list: false,
+            logger,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: shellSetting,
+        });
+        return;
+    }
+    // List-only: merge extra positional tokens into globs when no --command is present.
+    if (list && argsParent.length > 0 && !commandOpt) {
+        const extra = argsParent.map(String).join(' ').trim();
+        if (extra.length > 0)
+            globs = [globs, extra].filter(Boolean).join(' ');
+        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        await execShellCommandBatch({
+            globs,
+            ignoreErrors,
+            list: true,
+            logger,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false),
+        });
+        return;
+    }
+    if (!commandOpt && !list) {
+        logger.error(`No command provided. Use --command or --list.`);
+        process.exit(0);
+    }
+    if (typeof commandOpt === 'string') {
+        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        const scriptsOpt = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
+        const shellOpt = opts.shell ?? cfg.shell ?? mergedBag.shell;
+        await execShellCommandBatch({
+            command: resolveCommand(scriptsOpt, commandOpt),
+            globs,
+            ignoreErrors,
+            list,
+            logger,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: resolveShell(scriptsOpt, commandOpt, shellOpt),
+        });
+        return;
+    }
+    // list only (explicit --list without --command)
+    const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+    const shellOnly = (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false);
+    await execShellCommandBatch({
+        globs,
+        ignoreErrors,
+        list: true,
+        logger,
+        ...(pkgCwd ? { pkgCwd } : {}),
+        rootPath,
+        shell: (shellOnly ?? false),
+    });
+};
+
+// Per-plugin config schema (optional fields; used as defaults).
+const ScriptSchema = z.union([
+    z.string(),
+    z.object({
+        cmd: z.string(),
+        shell: z.union([z.string(), z.boolean()]).optional(),
+    }),
+]);
+const BatchConfigSchema = z.object({
+    scripts: z.record(z.string(), ScriptSchema).optional(),
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    rootPath: z.string().optional(),
+    globs: z.string().optional(),
+    pkgCwd: z.boolean().optional(),
+});
+
+/**
+ * Batch plugin for the GetDotenv CLI host.
  *
- * @throws Error when a dynamic module is present but cannot be imported.
- * @throws Error when an output path was requested but could not be resolved.
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * - scripts/shell: used to resolve command and shell behavior per script or global default.
+ * - logger: defaults to console.
  */
-const getDotenv = async (options = {}) => {
-    // Apply defaults.
-    const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
-    // Read .env files.
-    const loaded = paths.length
-        ? await paths.reduce(async (e, p) => {
-            const publicGlobal = excludePublic || excludeGlobal
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, dotenvToken));
-            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
-            const privateGlobal = excludePrivate || excludeGlobal
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, `${dotenvToken}.${privateToken}`));
-            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}.${privateToken}`));
-            const [eResolved, publicGlobalResolved, publicEnvResolved, privateGlobalResolved, privateEnvResolved,] = await Promise.all([
-                e,
-                publicGlobal,
-                publicEnv,
-                privateGlobal,
-                privateEnv,
-            ]);
-            return {
-                ...eResolved,
-                ...publicGlobalResolved,
-                ...publicEnvResolved,
-                ...privateGlobalResolved,
-                ...privateEnvResolved,
+const batchPlugin = (opts = {}) => definePlugin({
+    id: 'batch',
+    // Host validates this when config-loader is enabled; plugins may also
+    // re-validate at action time as a safety belt.
+    configSchema: BatchConfigSchema,
+    setup(cli) {
+        const ns = cli.ns('batch');
+        const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
+        ns.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 resolution')
+            .option('-l, --list', 'list working directories without executing command')
+            .option('-e, --ignore-errors', 'ignore errors and continue with next path')
+            .argument('[command...]')
+            .addCommand(new Command()
+            .name('cmd')
+            .description('execute command, conflicts with --command option (default subcommand)')
+            .enablePositionalOptions()
+            .passThroughOptions()
+            .argument('[command...]')
+            .action(buildDefaultCmdAction(cli, batchCmd, opts)), { isDefault: true })
+            .action(buildParentAction(cli, opts));
+    },
+});
+
+const dbg = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:alias]', ...args);
+    }
+};
+const attachParentAlias = (cli, options, _cmd) => {
+    const aliasSpec = typeof options.optionAlias === 'string'
+        ? { flags: options.optionAlias, description: undefined, expand: true }
+        : options.optionAlias;
+    if (!aliasSpec)
+        return;
+    const deriveKey = (flags) => {
+        dbg('install alias option', flags);
+        const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
+        const name = long.replace(/^--/, '');
+        return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+    };
+    const aliasKey = deriveKey(aliasSpec.flags);
+    // Expose the option on the parent.
+    const desc = aliasSpec.description ??
+        'alias of cmd subcommand; provide command tokens (variadic)';
+    cli.option(aliasSpec.flags, desc);
+    // Shared alias executor for either preAction or preSubcommand hooks.
+    // Ensure we only execute once even if both hooks fire in a single parse.
+    let aliasHandled = false;
+    const maybeRunAlias = async (thisCommand) => {
+        dbg('alias:maybe:start');
+        const raw = thisCommand.rawArgs ?? [];
+        const childNames = thisCommand.commands.flatMap((c) => [
+            c.name(),
+            ...c.aliases(),
+        ]);
+        const hasSub = childNames.some((n) => raw.includes(n));
+        // Read alias value from parent opts.
+        const o = thisCommand.opts();
+        const val = o[aliasKey];
+        const provided = typeof val === 'string'
+            ? val.length > 0
+            : Array.isArray(val)
+                ? val.length > 0
+                : false;
+        if (!provided || hasSub) {
+            dbg('alias:maybe:skip', { provided, hasSub });
+            return; // not an alias-only invocation
+        }
+        if (aliasHandled) {
+            dbg('alias:maybe:already-handled');
+            return;
+        }
+        aliasHandled = true;
+        dbg('alias-only invocation detected');
+        // Merge CLI options and resolve dotenv context.
+        const { merged } = resolveCliOptions(o, baseRootOptionDefaults, process.env.getDotenvCliOptions);
+        const logger = merged.logger ?? console;
+        const serviceOptions = getDotenvCliOptions2Options(merged);
+        await cli.resolveAndLoad(serviceOptions);
+        // Normalize alias value.
+        const joined = typeof val === 'string'
+            ? val
+            : Array.isArray(val)
+                ? val.map(String).join(' ')
+                : '';
+        const input = aliasSpec.expand === false
+            ? joined
+            : (dotenvExpandFromProcessEnv(joined) ?? joined);
+        dbg('resolved input', { input });
+        const resolved = resolveCommand(merged.scripts, input);
+        const lg = logger;
+        if (merged.debug) {
+            (lg.debug ?? lg.log)('\n*** command ***\n', `'${resolved}'`);
+        }
+        const { logger: _omit, ...envBag } = merged;
+        // Test guard: when running under tests, prefer stdio: 'inherit' to avoid
+        // assertions depending on captured stdio; ignore GETDOTENV_STDIO/capture.
+        const underTests = process.env.GETDOTENV_TEST === '1' ||
+            typeof process.env.VITEST_WORKER_ID === 'string';
+        const forceExit = process.env.GETDOTENV_FORCE_EXIT === '1';
+        const capture = !underTests &&
+            (process.env.GETDOTENV_STDIO === 'pipe' ||
+                Boolean(merged.capture));
+        dbg('run:start', { capture, shell: merged.shell });
+        // Prefer explicit env injection: include resolved dotenv map to avoid leaking
+        // parent process.env secrets when exclusions are set.
+        const ctx = cli.getCtx();
+        const dotenv = (ctx?.dotenv ?? {});
+        // Diagnostics: --trace [keys...]
+        const traceOpt = merged.trace;
+        if (traceOpt) {
+            const parentKeys = Object.keys(process.env);
+            const dotenvKeys = Object.keys(dotenv);
+            const allKeys = Array.from(new Set([...parentKeys, ...dotenvKeys])).sort();
+            const keys = Array.isArray(traceOpt) ? traceOpt : allKeys;
+            const childEnvPreview = {
+                ...process.env,
+                ...dotenv,
             };
-        }, Promise.resolve({}))
-        : {};
-    const outputKey = nanoid();
-    const dotenv = dotenvExpandAll({
-        ...loaded,
-        ...vars,
-        ...(outputPath ? { [outputKey]: outputPath } : {}),
-    }, { progressive: true });
-    // Process dynamic variables. Programmatic option takes precedence over path.
-    if (!excludeDynamic) {
-        let dynamic = undefined;
-        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
-            dynamic = options.dynamic;
+            for (const k of keys) {
+                const parent = process.env[k];
+                const dot = dotenv[k];
+                const final = childEnvPreview[k];
+                const origin = dot !== undefined
+                    ? 'dotenv'
+                    : parent !== undefined
+                        ? 'parent'
+                        : 'unset';
+                process.stderr.write(`[trace] key=${k} origin=${origin} parent=${parent ?? ''} dotenv=${dot ?? ''} final=${final ?? ''}\n`);
+            }
         }
-        else if (dynamicPath) {
-            const absDynamicPath = path.resolve(dynamicPath);
-            dynamic = await loadDynamicFromPath(absDynamicPath);
+        let exitCode = Number.NaN;
+        try {
+            // Resolve shell and preserve argv for Node -e snippets under shell-off.
+            const shellSetting = resolveShell(merged.scripts, input, merged.shell);
+            let commandArg = resolved;
+            /**       * Special-case: when shell is OFF and no script alias remap occurred
+             * (resolved === input), treat a Node eval payload as an argv array to
+             * avoid lossy re-tokenization of the code string.
+             *
+             * Examples handled:
+             *   "node -e \"console.log(JSON.stringify(...))\""
+             *   "node --eval 'console.log(...)'"
+             *
+             * We peel exactly one pair of symmetric outer quotes from the code
+             * argument when present; inner quotes remain untouched.
+             */
+            if (shellSetting === false && resolved === input) {
+                // Helper: strip one symmetric outer quote layer
+                const stripOne = (s) => {
+                    if (s.length < 2)
+                        return s;
+                    const a = s.charAt(0);
+                    const b = s.charAt(s.length - 1);
+                    const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+                    return symmetric ? s.slice(1, -1) : s;
+                };
+                // Normalize whole input once for robust matching
+                const normalized = stripOne(input.trim());
+                // First try a lightweight regex on the normalized string
+                const m = /^\s*node\s+(--eval|-e)\s+([\s\S]+)$/i.exec(normalized);
+                if (m && typeof m[1] === 'string' && typeof m[2] === 'string') {
+                    const evalFlag = m[1];
+                    let codeArg = m[2].trim();
+                    codeArg = stripOne(codeArg);
+                    const flag = evalFlag.startsWith('--') ? '--eval' : '-e';
+                    commandArg = ['node', flag, codeArg];
+                }
+                else {
+                    // Fallback: tokenize and detect node -e/--eval form
+                    const parts = tokenize(input);
+                    if (parts.length >= 3) {
+                        // Narrow under noUncheckedIndexedAccess
+                        const p0 = parts[0];
+                        const p1 = parts[1];
+                        if (p0?.toLowerCase() === 'node' &&
+                            (p1 === '-e' || p1 === '--eval')) {
+                            commandArg = parts;
+                        }
+                    }
+                }
+            }
+            exitCode = await runCommand(commandArg, shellSetting, {
+                env: {
+                    ...process.env,
+                    ...dotenv,
+                    getDotenvCliOptions: JSON.stringify(envBag),
+                },
+                stdio: capture ? 'pipe' : 'inherit',
+            });
+            dbg('run:done', { exitCode });
         }
-        if (dynamic) {
+        catch (err) {
+            const code = typeof err.exitCode === 'number'
+                ? err.exitCode
+                : 1;
+            dbg('run:error', { exitCode: code, error: String(err) });
+            if (!underTests) {
+                dbg('process.exit (error path)', { exitCode: code });
+                process.exit(code);
+            }
+            else {
+                dbg('process.exit suppressed for tests (error path)', {
+                    exitCode: code,
+                });
+            }
+            return;
+        }
+        if (!Number.isNaN(exitCode)) {
+            dbg('process.exit', { exitCode });
+            process.exit(exitCode);
+        }
+        // Fallback: Some environments may not surface a numeric exitCode even on success.
+        // Always terminate alias-only invocations outside tests to avoid hanging the process,
+        // regardless of capture/GETDOTENV_STDIO. Under tests, suppress to keep the runner alive.
+        if (!underTests) {
+            dbg('process.exit (fallback: non-numeric exitCode)', { exitCode: 0 });
+            process.exit(0);
+        }
+        else {
+            dbg('process.exit (fallback suppressed for tests: non-numeric exitCode)', { exitCode: 0 });
+        }
+        // Optional last-resort guard: force an exit on the next tick when enabled.
+        // Intended for diagnosing environments where the process appears to linger
+        // despite reaching the success/error handlers above. Disabled under tests.
+        if (forceExit) {
             try {
-                for (const key in dynamic)
-                    Object.assign(dotenv, {
-                        [key]: typeof dynamic[key] === 'function'
-                            ? dynamic[key](dotenv, env ?? defaultEnv)
-                            : dynamic[key],
+                if (process.env.GETDOTENV_DEBUG_VERBOSE) {
+                    const getHandles = process._getActiveHandles;
+                    const handles = typeof getHandles === 'function' ? getHandles() : [];
+                    dbg('active handles before forced exit', {
+                        count: Array.isArray(handles) ? handles.length : undefined,
                     });
+                }
             }
             catch {
-                throw new Error(`Unable to evaluate dynamic variables.`);
+                // best-effort only
             }
+            const code = Number.isNaN(exitCode) ? 0 : exitCode;
+            dbg('process.exit (forced)', { exitCode: code });
+            setImmediate(() => process.exit(code));
         }
-    }
-    // Write output file.
-    let resultDotenv = dotenv;
-    if (outputPath) {
-        const outputPathResolved = dotenv[outputKey];
-        if (!outputPathResolved)
-            throw new Error('Output path not found.');
-        const { [outputKey]: _omitted, ...dotenvForOutput } = dotenv;
-        await fs.writeFile(outputPathResolved, Object.keys(dotenvForOutput).reduce((contents, key) => {
-            const value = dotenvForOutput[key] ?? '';
-            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
-        }, ''), { encoding: 'utf-8' });
-        resultDotenv = dotenvForOutput;
-    }
-    // Log result.
-    if (log)
-        logger.log(resultDotenv);
-    // Load process.env.
-    if (loadProcess)
-        Object.assign(process.env, resultDotenv);
-    return resultDotenv;
+    };
+    // Execute alias-only invocations whether the root handles the action  // itself (preAction) or Commander routes to a default subcommand (preSubcommand).
+    cli.hook('preAction', async (thisCommand, _actionCommand) => {
+        await maybeRunAlias(thisCommand);
+    });
+    cli.hook('preSubcommand', async (thisCommand) => {
+        await maybeRunAlias(thisCommand);
+    });
 };
 
-/**
- * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
- * - If the user explicitly enabled the flag, return true.
- * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
- * - Otherwise, adopt the default (true → set; false/undefined → unset).
- *
- * @param exclude - The "on" flag value as parsed by Commander.
- * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
- * @param defaultValue - The generator default to adopt when no explicit toggle is present.
- * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
+/**+ Cmd plugin: executes a command using the current getdotenv CLI context.
  *
- * @example
- * ```ts
- * resolveExclusion(undefined, undefined, true); // => true
- * ```
- */
-const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
+ * - Joins positional args into a single command string.
+ * - Resolves scripts and shell settings using shared helpers.
+ * - Forwards merged CLI options to subprocesses via
+ *   process.env.getDotenvCliOptions for nested CLI behavior. */
+const cmdPlugin = (options = {}) => definePlugin({
+    id: 'cmd',
+    setup(cli) {
+        const aliasSpec = typeof options.optionAlias === 'string'
+            ? { flags: options.optionAlias}
+            : options.optionAlias;
+        const deriveKey = (flags) => {
+            const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
+            const name = long.replace(/^--/, '');
+            return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+        };
+        const aliasKey = aliasSpec ? deriveKey(aliasSpec.flags) : undefined;
+        const cmd = 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, _opts, thisCommand) => {
+            // Commander passes positional tokens as the first action argument
+            const args = Array.isArray(commandParts) ? commandParts : [];
+            // No-op when invoked as the default command with no args.
+            if (args.length === 0)
+                return;
+            const parent = thisCommand.parent;
+            if (!parent)
+                throw new Error('parent command not found'); // Conflict detection: if an alias option is present on parent, do not
+            // also accept positional cmd args.
+            if (aliasKey) {
+                const pv = parent.opts();
+                const ov = pv[aliasKey];
+                if (ov !== undefined) {
+                    const merged = parent.getDotenvCliOptions ?? {};
+                    const logger = merged.logger ?? console;
+                    const lr = logger;
+                    const emit = lr.error ?? lr.log;
+                    emit(`--${aliasKey} option conflicts with cmd subcommand.`);
+                    process.exit(0);
+                }
+            }
+            // Merged CLI options are persisted by the shipped CLI preSubcommand hook.
+            const merged = parent.getDotenvCliOptions ?? {};
+            const logger = merged.logger ?? console;
+            // Join positional args into the command string.
+            const input = args.map(String).join(' ');
+            // Resolve command and shell using shared helpers.
+            const scripts = merged.scripts;
+            const shell = merged.shell;
+            const resolved = resolveCommand(scripts, input);
+            if (merged.debug) {
+                const lg = logger;
+                (lg.debug ?? lg.log)('\n*** command ***\n', `'${resolved}'`);
+            }
+            // Round-trip CLI options for nested getdotenv invocations.
+            // Omit logger (functions are not serializable).
+            const { logger: _omit, ...envBag } = merged;
+            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+                Boolean(merged.capture);
+            // Prefer explicit env injection: pass the resolved dotenv map to the child.
+            // This avoids leaking prior secrets from the parent process.env when
+            // exclusions (e.g., --exclude-private) are in effect.
+            const host = cli;
+            const ctx = host.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
+            const traceOpt = merged.trace;
+            if (traceOpt) {
+                // Determine keys to trace: all keys (parent ∪ dotenv) or selected.
+                const parentKeys = Object.keys(process.env);
+                const dotenvKeys = Object.keys(dotenv);
+                const allKeys = Array.from(new Set([...parentKeys, ...dotenvKeys])).sort();
+                const keys = Array.isArray(traceOpt) ? traceOpt : allKeys;
+                // Child env preview (as composed below; excluding getDotenvCliOptions)
+                const childEnvPreview = {
+                    ...process.env,
+                    ...dotenv,
+                };
+                for (const k of keys) {
+                    const parent = process.env[k];
+                    const dot = dotenv[k];
+                    const final = childEnvPreview[k];
+                    const origin = dot !== undefined
+                        ? 'dotenv'
+                        : parent !== undefined
+                            ? 'parent'
+                            : 'unset';
+                    // Emit concise diagnostic line to stderr.
+                    process.stderr.write(`[trace] key=${k} origin=${origin} parent=${parent ?? ''} dotenv=${dot ?? ''} final=${final ?? ''}\n`);
+                }
+            }
+            const shellSetting = resolveShell(scripts, input, shell);
+            /**
+             * Preserve original argv array when:
+             * - shell is OFF (plain execa), and
+             * - no script alias remap occurred (resolved === input).
+             *
+             * This avoids lossy re-tokenization of code snippets such as:
+             *   node -e "console.log(process.env.APP_SECRET ?? '')"
+             * where quotes may have been stripped by the parent shell and
+             * spaces inside the code must remain a single argument.
+             */
+            const commandArg = shellSetting === false && resolved === input
+                ? args.map(String)
+                : resolved;
+            await runCommand(commandArg, shellSetting, {
+                env: {
+                    ...process.env,
+                    ...dotenv,
+                    getDotenvCliOptions: JSON.stringify(envBag),
+                },
+                stdio: capture ? 'pipe' : 'inherit',
+            });
+        });
+        if (options.asDefault)
+            cli.addCommand(cmd, { isDefault: true });
+        else
+            cli.addCommand(cmd);
+        // Parent-attached option alias (optional).
+        if (aliasSpec)
+            attachParentAlias(cli, options);
+    },
+});
+
 /**
- * Resolve an optional flag with "--exclude-all" overrides.
- * If excludeAll is set and the individual "...-off" is not, force true.
- * If excludeAllOff is set and the individual flag is not explicitly set, unset.
- * Otherwise, adopt the default (true → set; false/undefined → unset).
+ * Demo plugin (educational).
  *
- * @param exclude - Individual include/exclude flag.
- * @param excludeOff - Individual "...-off" flag.
- * @param defaultValue - Default for the individual flag.
- * @param excludeAll - Global "exclude-all" flag.
- * @param excludeAllOff - Global "exclude-all-off" flag.
+ * 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.
  *
- * @example
- * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
- */
-const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => excludeAll && !excludeOff
-    ? true
-    : excludeAllOff && !exclude
-        ? undefined
-        : defaultValue
-            ? true
-            : undefined;
-/**
- * exactOptionalPropertyTypes-safe setter for optional boolean flags:
- * delete when undefined; assign when defined — without requiring an index signature on T.
+ * 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? \}.
  *
- * @typeParam T - Target object type.
- * @param obj - The object to write to.
- * @param key - The optional boolean property key of {@link T}.
- * @param value - The value to set or `undefined` to unset.
+ * 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).
  *
- * @remarks
- * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ * Usage (examples)
+ *   getdotenv demo ctx
+ *   getdotenv demo run --print APP_SETTING
+ *   getdotenv demo script echo OK
+ *   getdotenv --trace demo run --print ENV_SETTING
  */
-const setOptionalFlag = (obj, key, value) => {
-    const target = obj;
-    const k = key;
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-    if (value === undefined)
-        delete target[k];
-    else
-        target[k] = value;
-};
+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);
+        }
+    },
+});
 
+const ensureDir = async (p) => {
+    await fs.ensureDir(p);
+    return p;
+};
+const writeFile = async (dest, data) => {
+    await ensureDir(path.dirname(dest));
+    await fs.writeFile(dest, data, 'utf-8');
+};
+const copyTextFile = async (src, dest, substitutions) => {
+    const contents = await fs.readFile(src, 'utf-8');
+    const out = substitutions && Object.keys(substitutions).length > 0
+        ? Object.entries(substitutions).reduce((acc, [k, v]) => acc.split(k).join(v), contents)
+        : contents;
+    await writeFile(dest, out);
+};
 /**
- * Build the Commander preSubcommand hook using the provided context.
- *
- * Responsibilities:
- * - Merge parent CLI options with current invocation (parent \< current).
- * - Resolve tri-state flags, including `--exclude-all` overrides.
- * - Normalize the shell setting to a concrete value (string | boolean).
- * - Persist merged options on the command instance and pass to subcommands.
- * - Execute {@link getDotenv} and optional post-hook.
- * - Either forward to the default `cmd` subcommand or execute `--command`.
- *
- * @param context - See {@link PreSubHookContext}.
- * @returns An async hook suitable for Commander’s `preSubcommand`.
- *
- * @example `program.hook('preSubcommand', makePreSubcommandHook(ctx));`
- */ const makePreSubcommandHook = ({ logger, preHook, postHook, defaults }) => async (thisCommand) => {
-    // Get parent command GetDotenvCliOptions.
-    const parentGetDotenvCliOptions = process.env.getDotenvCliOptions
-        ? JSON.parse(process.env.getDotenvCliOptions)
-        : undefined;
-    // Get raw CLI options from commander.
-    const rawCliOptions = thisCommand.opts();
-    // Extract current GetDotenvCliOptions from raw CLI options.
-    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, scripts, shellOff, ...rawCliOptionsRest } = rawCliOptions;
-    const currentGetDotenvCliOptions = rawCliOptionsRest;
-    if (scripts)
-        currentGetDotenvCliOptions.scripts = JSON.parse(scripts);
-    // Merge current & parent GetDotenvCliOptions (parent < current).
-    const mergedGetDotenvCliOptions = defaultsDeep((parentGetDotenvCliOptions ?? {}), currentGetDotenvCliOptions);
-    // Resolve flags using defaults + current + exclude-all toggles.
-    setOptionalFlag(mergedGetDotenvCliOptions, 'debug', resolveExclusion(mergedGetDotenvCliOptions.debug, debugOff, defaults.debug));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludeDynamic', resolveExclusionAll(mergedGetDotenvCliOptions.excludeDynamic, excludeDynamicOff, defaults.excludeDynamic, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludeEnv', resolveExclusionAll(mergedGetDotenvCliOptions.excludeEnv, excludeEnvOff, defaults.excludeEnv, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludeGlobal', resolveExclusionAll(mergedGetDotenvCliOptions.excludeGlobal, excludeGlobalOff, defaults.excludeGlobal, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludePrivate', resolveExclusionAll(mergedGetDotenvCliOptions.excludePrivate, excludePrivateOff, defaults.excludePrivate, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludePublic', resolveExclusionAll(mergedGetDotenvCliOptions.excludePublic, excludePublicOff, defaults.excludePublic, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'log', resolveExclusion(mergedGetDotenvCliOptions.log, logOff, defaults.log));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'loadProcess', resolveExclusion(mergedGetDotenvCliOptions.loadProcess, loadProcessOff, defaults.loadProcess));
-    // Normalize shell for predictability: explicit default shell per OS.
-    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
-    let resolvedShell = mergedGetDotenvCliOptions.shell;
-    if (shellOff)
-        resolvedShell = false;
-    else if (resolvedShell === true || resolvedShell === undefined) {
-        resolvedShell = defaultShell;
+ * Ensure a set of lines exist (exact match) in a file. Creates the file
+ * when missing. Returns whether it was created or changed.
+ */
+const ensureLines = async (filePath, lines) => {
+    const exists = await fs.pathExists(filePath);
+    const current = exists ? await fs.readFile(filePath, 'utf-8') : '';
+    const curLines = current.split(/\r?\n/);
+    const have = new Set(curLines.filter((l) => l.length > 0));
+    let mutated = false;
+    for (const l of lines) {
+        if (!have.has(l)) {
+            curLines.push(l);
+            have.add(l);
+            mutated = true;
+        }
     }
-    else if (typeof resolvedShell !== 'string' &&
-        typeof defaults.shell === 'string') {
-        resolvedShell = defaults.shell;
+    // Normalize to LF and ensure trailing newline
+    const next = curLines.filter((l) => l.length > 0).join('\n') + '\n';
+    if (!exists) {
+        await writeFile(filePath, next);
+        return { created: true, changed: true };
     }
-    mergedGetDotenvCliOptions.shell = resolvedShell;
-    if (mergedGetDotenvCliOptions.debug && parentGetDotenvCliOptions) {
-        logger.debug('\n*** parent command GetDotenvCliOptions ***\n', parentGetDotenvCliOptions);
+    if (mutated) {
+        await fs.writeFile(filePath, next, 'utf-8');
+        return { created: false, changed: true };
     }
-    if (mergedGetDotenvCliOptions.debug)
-        logger.debug('\n*** current command raw options ***\n', rawCliOptions);
-    if (mergedGetDotenvCliOptions.debug)
-        logger.debug('\n*** merged GetDotenvCliOptions ***\n', {
-            mergedGetDotenvCliOptions,
+    return { created: false, changed: false };
+};
+
+// Templates root used by the scaffolder
+const TEMPLATES_ROOT = path.resolve('templates');
+
+const planConfigCopies = ({ format, withLocal, destRoot, }) => {
+    const copies = [];
+    if (format === 'json') {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'json', 'public', 'getdotenv.config.json'),
+            dest: path.join(destRoot, 'getdotenv.config.json'),
         });
-    // Execute pre-hook.
-    if (preHook) {
-        await preHook(mergedGetDotenvCliOptions);
-        if (mergedGetDotenvCliOptions.debug)
-            logger.debug('\n*** GetDotenvCliOptions after pre-hook ***\n', mergedGetDotenvCliOptions);
-    }
-    // Persist GetDotenvCliOptions in command for subcommand access.
-    thisCommand.getDotenvCliOptions = mergedGetDotenvCliOptions;
-    // Execute getdotenv.
-    const dotenv = await getDotenv(getDotenvCliOptions2Options(mergedGetDotenvCliOptions));
-    if (mergedGetDotenvCliOptions.debug)
-        logger.debug('\n*** getDotenv output ***\n', dotenv);
-    // Execute post-hook.
-    if (postHook)
-        await postHook(dotenv);
-    // Execute command.
-    const args = thisCommand.args ?? [];
-    const isCommand = typeof command === 'string' && command.length > 0;
-    if (isCommand && args.length > 0) {
-        const lr = logger;
-        (lr.error ?? lr.log)(`--command option conflicts with cmd subcommand.`);
-        process.exit(0);
+        if (withLocal) {
+            copies.push({
+                src: path.join(TEMPLATES_ROOT, 'config', 'json', 'local', 'getdotenv.config.local.json'),
+                dest: path.join(destRoot, 'getdotenv.config.local.json'),
+            });
+        }
     }
-    if (typeof command === 'string' && command.length > 0) {
-        const cmd = resolveCommand(mergedGetDotenvCliOptions.scripts, command);
-        if (mergedGetDotenvCliOptions.debug)
-            logger.debug('\n*** command ***\n', cmd);
-        const envSafe = {
-            ...mergedGetDotenvCliOptions,
-        };
-        delete envSafe.logger;
-        await execaCommand(cmd, {
-            env: {
-                ...process.env,
-                getDotenvCliOptions: JSON.stringify(envSafe),
-            },
-            shell: resolveShell(mergedGetDotenvCliOptions.scripts, command, mergedGetDotenvCliOptions.shell),
-            stdio: 'inherit',
+    else if (format === 'yaml') {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'public', 'getdotenv.config.yaml'),
+            dest: path.join(destRoot, 'getdotenv.config.yaml'),
+        });
+        if (withLocal) {
+            copies.push({
+                src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'local', 'getdotenv.config.local.yaml'),
+                dest: path.join(destRoot, 'getdotenv.config.local.yaml'),
+            });
+        }
+    }
+    else if (format === 'js') {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'js', 'getdotenv.config.js'),
+            dest: path.join(destRoot, 'getdotenv.config.js'),
+        });
+    }
+    else {
+        copies.push({
+            src: path.join(TEMPLATES_ROOT, 'config', 'ts', 'getdotenv.config.ts'),
+            dest: path.join(destRoot, 'getdotenv.config.ts'),
         });
     }
+    return copies;
+};
+const planCliCopies = ({ cliName, destRoot, }) => {
+    const subs = { __CLI_NAME__: cliName };
+    const base = path.join(destRoot, 'src', 'cli', cliName);
+    return [
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'index.ts'),
+            dest: path.join(base, 'index.ts'),
+            subs,
+        },
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'plugins', 'hello.ts'),
+            dest: path.join(base, 'plugins', 'hello.ts'),
+            subs,
+        },
+    ];
 };
 
 /**
- * Generate a Commander CLI Command for get-dotenv. * Orchestration only: delegates building and lifecycle hooks.
- */
-const generateGetDotenvCli = async (customOptions) => {
-    const options = await resolveGetDotenvCliGenerateOptions(customOptions);
-    const program = createRootCommand(options);
-    const defaults = {};
-    if (options.debug !== undefined)
-        defaults.debug = options.debug;
-    if (options.excludeDynamic !== undefined)
-        defaults.excludeDynamic = options.excludeDynamic;
-    if (options.excludeEnv !== undefined)
-        defaults.excludeEnv = options.excludeEnv;
-    if (options.excludeGlobal !== undefined)
-        defaults.excludeGlobal = options.excludeGlobal;
-    if (options.excludePrivate !== undefined)
-        defaults.excludePrivate = options.excludePrivate;
-    if (options.excludePublic !== undefined)
-        defaults.excludePublic = options.excludePublic;
-    if (options.loadProcess !== undefined)
-        defaults.loadProcess = options.loadProcess;
-    if (options.log !== undefined)
-        defaults.log = options.log;
-    if (options.scripts !== undefined)
-        defaults.scripts = options.scripts;
-    if (options.shell !== undefined)
-        defaults.shell = options.shell;
-    const ctx = {
-        logger: options.logger,
-        defaults,
-        ...(options.preHook ? { preHook: options.preHook } : {}),
-        ...(options.postHook ? { postHook: options.postHook } : {}),
-    };
-    program.hook('preSubcommand', makePreSubcommandHook(ctx));
-    return program;
+ * Determine whether the current environment should be treated as non-interactive.
+ * CI heuristics include: CI, GITHUB_ACTIONS, BUILDKITE, TEAMCITY_VERSION, TF_BUILD.
+ */
+const isNonInteractive = () => {
+    const ciLike = process.env.CI ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.BUILDKITE ||
+        process.env.TEAMCITY_VERSION ||
+        process.env.TF_BUILD;
+    return Boolean(ciLike) || !(stdin.isTTY && stdout.isTTY);
+};
+const promptDecision = async (filePath, logger, rl) => {
+    logger.log(`File exists: ${filePath}\nChoose: [o]verwrite, [e]xample, [s]kip, [O]verwrite All, [E]xample All, [S]kip All`);
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+        const a = (await rl.question('> ')).trim();
+        const valid = ['o', 'e', 's', 'O', 'E', 'S'];
+        if (valid.includes(a))
+            return a;
+        logger.log('Please enter one of: o e s O E S');
+    }
 };
 
-const program = await generateGetDotenvCli({
-    importMetaUrl: import.meta.url,
+/**
+ * Requirements: Init scaffolding plugin with collision flow and CI detection.
+ * Note: Large file scheduled for decomposition; tracked in stan.todo.md.
+ */
+const initPlugin = (opts = {}) => definePlugin({
+    id: 'init',
+    setup(cli) {
+        const logger = opts.logger ?? console;
+        const cmd = cli
+            .ns('init')
+            .description('Scaffold getdotenv config files and a host-based CLI skeleton.')
+            .argument('[dest]', 'destination path (default: ./)', '.')
+            .option('--config-format <format>', 'config format: json|yaml|js|ts', 'json')
+            .option('--with-local', 'include .local config variant')
+            .option('--dynamic', 'include dynamic examples (JS/TS configs)')
+            .option('--cli-name <string>', 'CLI name for skeleton and tokens')
+            .option('--force', 'overwrite all existing files')
+            .option('--yes', 'skip all collisions (no overwrite)')
+            .action(async (destArg) => {
+            // Read options directly from the captured command instance.
+            // Cast to a plain record to satisfy exact-optional and lint safety.
+            const o = cmd.opts() ?? {};
+            const destRel = typeof destArg === 'string' && destArg.length > 0 ? destArg : '.';
+            const cwd = process.cwd();
+            const destRoot = path.resolve(cwd, destRel);
+            const formatInput = o.configFormat;
+            const formatRaw = typeof formatInput === 'string'
+                ? formatInput.toLowerCase()
+                : 'json';
+            const format = (['json', 'yaml', 'js', 'ts'].includes(formatRaw)
+                ? formatRaw
+                : 'json');
+            const withLocal = !!o.withLocal;
+            // dynamic flag reserved for future template variants; present for UX compatibility
+            void o.dynamic;
+            // CLI name default: --cli-name | basename(dest) | 'mycli'
+            const cliName = (typeof o.cliName === 'string' && o.cliName.length > 0
+                ? o.cliName
+                : path.basename(destRoot) || 'mycli') || 'mycli';
+            // Precedence: --force > --yes > auto-detect(non-interactive => yes)
+            const force = !!o.force;
+            const yes = !!o.yes || (!force && isNonInteractive());
+            // Build copy plan
+            const cfgCopies = planConfigCopies({ format, withLocal, destRoot });
+            const cliCopies = planCliCopies({ cliName, destRoot });
+            const copies = [...cfgCopies, ...cliCopies];
+            // Interactive state
+            let globalDecision;
+            const rl = createInterface({ input: stdin, output: stdout });
+            try {
+                for (const item of copies) {
+                    const exists = await fs.pathExists(item.dest);
+                    if (!exists) {
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, item.dest, subs);
+                        logger.log(`Created ${path.relative(cwd, item.dest)}`);
+                        continue;
+                    }
+                    // Collision
+                    if (force) {
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, item.dest, subs);
+                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
+                        continue;
+                    }
+                    if (yes) {
+                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
+                        continue;
+                    }
+                    let decision = globalDecision;
+                    if (!decision) {
+                        const a = await promptDecision(item.dest, logger, rl);
+                        if (a === 'O') {
+                            globalDecision = 'overwrite';
+                            decision = 'overwrite';
+                        }
+                        else if (a === 'E') {
+                            globalDecision = 'example';
+                            decision = 'example';
+                        }
+                        else if (a === 'S') {
+                            globalDecision = 'skip';
+                            decision = 'skip';
+                        }
+                        else {
+                            decision =
+                                a === 'o' ? 'overwrite' : a === 'e' ? 'example' : 'skip';
+                        }
+                    }
+                    if (decision === 'overwrite') {
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, item.dest, subs);
+                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
+                    }
+                    else if (decision === 'example') {
+                        const destEx = `${item.dest}.example`;
+                        const subs = item.subs ?? {};
+                        await copyTextFile(item.src, destEx, subs);
+                        logger.log(`Wrote example ${path.relative(cwd, destEx)}`);
+                    }
+                    else {
+                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
+                    }
+                }
+                // Ensure .gitignore includes local config patterns.
+                const giPath = path.join(destRoot, '.gitignore');
+                const { created, changed } = await ensureLines(giPath, [
+                    'getdotenv.config.local.*',
+                    '*.local',
+                ]);
+                if (created) {
+                    logger.log(`Created ${path.relative(cwd, giPath)}`);
+                }
+                else if (changed) {
+                    logger.log(`Updated ${path.relative(cwd, giPath)}`);
+                }
+            }
+            finally {
+                rl.close();
+            }
+        });
+    },
 });
+
+// Shipped CLI rebased on plugin-first host.
+const program = new GetDotenvCli('getdotenv')
+    .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();