@karmaniverous/get-dotenv 6.2.4 → 6.4.0

package/dist/index.mjs

@@ -1,27 +1,31 @@
-export { c as createCli } from './chunks/createCli-BY6_cfZr.mjs';
-export { G as GetDotenvCli, e as baseRootOptionDefaults, a as defineDynamic, b as defineGetDotenvConfig, d as definePlugin, g as getDotenv, c as getDotenvCliOptions2Options, i as interpolateDeep, m as maybeWarnEntropy, r as readMergedOptions, f as redactDisplay, h as redactObject } from './chunks/readMergedOptions-Nt0TR7dX.mjs';
-export { b as buildSpawnEnv, s as shouldCapture } from './chunks/spawnEnv-CN8a7cNR.mjs';
-export { d as defineScripts, g as groupPlugins } from './chunks/types-DJ-BGABd.mjs';
-import 'fs-extra';
+export { c as createCli } from './chunks/createCli-BnRdfRRL.mjs';
+import { e as resolveGetDotenvOptions, w as writeDotenvFile } from './chunks/readMergedOptions-B7VdLROn.mjs';
+export { G as GetDotenvCli, b as baseRootOptionDefaults, f as defineDynamic, h as defineGetDotenvConfig, d as definePlugin, g as getDotenvCliOptions2Options, i as interpolateDeep, r as readMergedOptions } from './chunks/readMergedOptions-B7VdLROn.mjs';
+export { d as buildSpawnEnv, s as shouldCapture } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-CVDR-Sjk.mjs';
+import fs from 'fs-extra';
 import 'crypto';
-import 'path';
+import path$1 from 'path';
 import 'url';
 export { z } from 'zod';
+import { nanoid } from 'nanoid';
+import { r as redactObject, m as maybeWarnEntropy } from './chunks/index-r0Me7-sT.mjs';
+export { a as redactDisplay, t as traceChildEnv } from './chunks/index-r0Me7-sT.mjs';
+import { f as readDotenv, d as dotenvExpandAll, a as applyDynamicMap, c as loadAndApplyDynamic } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
+export { g as dotenvExpand, h as dotenvExpandFromProcessEnv } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
+import path from 'node:path';
 import 'dotenv';
-export { t as traceChildEnv } from './chunks/index-Bc3h0a95.mjs';
-export { d as dotenvExpand, a as dotenvExpandAll, b as dotenvExpandFromProcessEnv } from './chunks/overlayEnv-Bs2kVayG.mjs';
-import './chunks/loader-DnhPeGfq.mjs';
+import './chunks/loader-CePOf74i.mjs';
 import 'package-directory';
 import 'yaml';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
-import 'nanoid';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-TFRzhB2c.mjs';
+import './chunks/resolveCliOptions-pgUXHJtj.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
 import '@commander-js/extra-typings';
-import './chunks/index-CeCufHlm.mjs';
+import './chunks/index-70Dm0f1N.mjs';
 import 'buffer';
 import 'os';
 import 'node:fs/promises';
@@ -36,5 +40,850 @@ import 'globby';
 import './plugins-init.mjs';
 import 'node:process';
 import 'readline/promises';
-import 'node:path';
 import 'node:url';
+
+/**
+ * Dotenv editor types (format-preserving).
+ *
+ * Requirements addressed:
+ * - Provide a format-preserving dotenv edit surface (pure text pipeline + FS adapter).
+ * - Preserve comments/blank lines/unknown lines and separator spacing; support merge vs sync.
+ * - Deterministic target selection across getdotenv `paths` with optional template bootstrap.
+ *
+ * Notes:
+ * - The parser intentionally preserves unknown lines verbatim rather than rejecting them.
+ * - The editor focuses on `.env`-style KEY=VALUE lines; anything not recognized is preserved as raw text.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Narrow helper for internal use: detect own properties safely.
+ *
+ * @internal
+ */
+const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+
+/**
+ * Apply edits to a parsed dotenv document while preserving formatting.
+ *
+ * Requirements addressed:
+ * - Mode: merge vs sync.
+ * - Duplicate key strategy: all/first/last.
+ * - undefined behavior: skip (default).
+ * - null behavior: delete (default).
+ * - Quote preservation where safe; upgrade quoting when required (multiline, whitespace safety, inline comment safety).
+ *
+ * @packageDocumentation
+ */
+const coerceToString = (v) => {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number')
+        return String(v);
+    if (typeof v === 'boolean')
+        return v ? 'true' : 'false';
+    if (v === null || v === undefined)
+        return '';
+    return JSON.stringify(v);
+};
+const needsQuoted = (value, hasInlineSuffix) => {
+    if (value.includes('\n'))
+        return true;
+    if (value.includes('\r'))
+        return true;
+    // Preserve correctness: leading/trailing whitespace should be quoted.
+    if (/^\s|\s$/.test(value))
+        return true;
+    // Inline comment safety: if there is a suffix (comment) and the value contains '#', quote it.
+    if (hasInlineSuffix && value.includes('#'))
+        return true;
+    return false;
+};
+const escapeDoubleQuoted = (value) => 
+// Minimal escaping: escape only `"`. (Do not force-escape backslashes.)
+value.replace(/"/g, '\\"');
+const toFileEol = (valueLf, fileEol) => fileEol === '\n' ? valueLf : valueLf.replace(/\n/g, '\r\n');
+const renderValueToken = (args) => {
+    const { value, preferQuote, hasInlineSuffix, fileEol } = args;
+    const multiline = value.includes('\n');
+    if (multiline) {
+        // Multiline correctness: use double quotes.
+        return {
+            token: `"${toFileEol(escapeDoubleQuoted(value), fileEol)}"`,
+            quote: '"',
+        };
+    }
+    const mustQuote = needsQuoted(value, hasInlineSuffix);
+    if (!mustQuote && preferQuote === null)
+        return { token: value, quote: null };
+    // Try to preserve original quote style when safe.
+    if (preferQuote === "'" && !value.includes("'") && !mustQuote) {
+        return { token: `'${value}'`, quote: "'" };
+    }
+    if (preferQuote === "'" && !value.includes("'")) {
+        return { token: `'${value}'`, quote: "'" };
+    }
+    // Prefer double quotes as the general safe fallback.
+    return { token: `"${escapeDoubleQuoted(value)}"`, quote: '"' };
+};
+const pickIndexes = (idxs, strategy) => {
+    if (idxs.length === 0)
+        return [];
+    if (strategy === 'first') {
+        const first = idxs[0];
+        return first === undefined ? [] : [first];
+    }
+    if (strategy === 'last') {
+        const last = idxs[idxs.length - 1];
+        return last === undefined ? [] : [last];
+    }
+    return idxs.slice();
+};
+const segmentEndEol = (seg) => {
+    if ('eol' in seg)
+        return seg.eol;
+    // Raw segments store EOL inside raw; best-effort detect tail.
+    const raw = seg.raw;
+    if (raw.endsWith('\r\n'))
+        return '\r\n';
+    if (raw.endsWith('\n'))
+        return '\n';
+    return '';
+};
+const rebuildAssignmentRaw = (args) => {
+    const { seg, valueLf, fileEol } = args;
+    const { token, quote } = renderValueToken({
+        value: valueLf,
+        preferQuote: seg.quote,
+        hasInlineSuffix: seg.suffix.length > 0,
+        fileEol,
+    });
+    const line = `${seg.prefix}${seg.key}${seg.separator}${seg.valuePadding}${token}${seg.suffix}`;
+    const eol = segmentEndEol(seg);
+    const raw = eol ? line + eol : line;
+    return { ...seg, raw, value: valueLf, quote, eol };
+};
+const rebuildBareAsAssignment = (args) => {
+    const { seg, valueLf, fileEol, defaultSeparator } = args;
+    const { token, quote } = renderValueToken({
+        value: valueLf,
+        preferQuote: null,
+        hasInlineSuffix: seg.suffix.length > 0,
+        fileEol,
+    });
+    const separator = defaultSeparator;
+    const line = `${seg.prefix}${seg.key}${separator}${token}${seg.suffix}`;
+    const eol = segmentEndEol(seg);
+    const raw = eol ? line + eol : line;
+    return {
+        kind: 'assignment',
+        raw,
+        key: seg.key,
+        prefix: seg.prefix,
+        separator,
+        valuePadding: '',
+        quote,
+        value: valueLf,
+        suffix: seg.suffix,
+        eol,
+    };
+};
+const buildNewAssignmentAtEnd = (args) => {
+    const { key, valueLf, fileEol, defaultSeparator, endEol } = args;
+    const { token, quote } = renderValueToken({
+        value: valueLf,
+        preferQuote: null,
+        hasInlineSuffix: false,
+        fileEol,
+    });
+    const line = `${key}${defaultSeparator}${token}`;
+    const raw = endEol ? line + endEol : line;
+    return {
+        kind: 'assignment',
+        raw,
+        key,
+        prefix: '',
+        separator: defaultSeparator,
+        valuePadding: '',
+        quote,
+        value: valueLf,
+        suffix: '',
+        eol: endEol,
+    };
+};
+/**
+ * Apply a set of key/value updates to a parsed dotenv document.
+ *
+ * @param doc - Parsed dotenv document.
+ * @param updates - Key/value update map.
+ * @param opts - Editing options.
+ * @returns A new {@link DotenvDocument} with edits applied.
+ *
+ * @public
+ */
+function applyDotenvEdits(doc, updates, opts) {
+    const mode = opts?.mode ?? 'merge';
+    const duplicateKeys = opts?.duplicateKeys ?? 'all';
+    const defaultSeparator = opts?.defaultSeparator ?? '=';
+    const segs = doc.segments.slice();
+    // Index key-bearing segments.
+    const byKey = new Map();
+    for (let i = 0; i < segs.length; i++) {
+        const s = segs[i];
+        if (!s)
+            continue;
+        if (s.kind === 'assignment' || s.kind === 'bare') {
+            const list = byKey.get(s.key) ?? [];
+            list.push(i);
+            byKey.set(s.key, list);
+        }
+    }
+    const deleteIdx = new Set();
+    const replace = new Map();
+    // Sync deletions: remove any existing key lines not present in update map (own props).
+    if (mode === 'sync') {
+        for (const [key, idxs] of byKey.entries()) {
+            if (!hasOwn(updates, key)) {
+                for (const i of idxs)
+                    deleteIdx.add(i);
+            }
+        }
+    }
+    // Apply update-driven deletes and replacements.
+    for (const key of Object.keys(updates)) {
+        const v = updates[key];
+        const idxsAll = byKey.get(key) ?? [];
+        if (v === null) {
+            for (const i of pickIndexes(idxsAll, duplicateKeys))
+                deleteIdx.add(i);
+            continue;
+        }
+        if (v === undefined) {
+            // Note: in sync mode, this key counts as present (do not delete); replacements are skipped.
+            continue;
+        }
+        const valueLf = coerceToString(v);
+        for (const i of pickIndexes(idxsAll, duplicateKeys)) {
+            const seg = segs[i];
+            if (!seg)
+                continue;
+            if (seg.kind === 'assignment') {
+                replace.set(i, rebuildAssignmentRaw({ seg, valueLf, fileEol: doc.fileEol }));
+            }
+            else if (seg.kind === 'bare') {
+                replace.set(i, rebuildBareAsAssignment({
+                    seg,
+                    valueLf,
+                    fileEol: doc.fileEol,
+                    defaultSeparator,
+                }));
+            }
+        }
+    }
+    // Rebuild the segment list, applying deletions and replacements.
+    const out = [];
+    for (let i = 0; i < segs.length; i++) {
+        if (deleteIdx.has(i))
+            continue;
+        const repl = replace.get(i);
+        const original = segs[i];
+        if (repl)
+            out.push(repl);
+        else if (original)
+            out.push(original);
+    }
+    // Merge mode: append missing keys (only when provided with a concrete value).
+    if (mode === 'merge') {
+        const existingKeys = new Set();
+        for (const s of out) {
+            if (s.kind === 'assignment' || s.kind === 'bare')
+                existingKeys.add(s.key);
+        }
+        // Use the document EOL when inserting new lines; final newline presence is handled by render().
+        const endEol = doc.fileEol;
+        for (const key of Object.keys(updates)) {
+            if (existingKeys.has(key))
+                continue;
+            const v = updates[key];
+            if (v === undefined)
+                continue;
+            if (v === null)
+                continue;
+            const valueLf = coerceToString(v);
+            out.push(buildNewAssignmentAtEnd({
+                key,
+                valueLf,
+                fileEol: doc.fileEol,
+                defaultSeparator,
+                endEol,
+            }));
+        }
+    }
+    return { ...doc, segments: out };
+}
+
+/**
+ * Parse a dotenv file into a format-preserving document model.
+ *
+ * Requirements addressed:
+ * - Preserve comments, blank lines, ordering, and unknown lines verbatim.
+ * - Preserve separator spacing around `=`.
+ * - Support multiline quoted values (double/single quotes) by grouping physical lines.
+ *
+ * @packageDocumentation
+ */
+const detectFileEol = (txt) => txt.includes('\r\n') ? '\r\n' : '\n';
+const endsWithNewline$1 = (txt) => txt.endsWith('\n') || txt.endsWith('\r\n');
+const splitLinesWithEol = (txt) => {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < txt.length; i++) {
+        const ch = txt.charAt(i);
+        if (ch !== '\n')
+            continue;
+        const isCrlf = i > 0 && txt.charAt(i - 1) === '\r';
+        const line = txt.slice(start, isCrlf ? i - 1 : i);
+        out.push({ line, eol: isCrlf ? '\r\n' : '\n' });
+        start = i + 1;
+    }
+    if (start < txt.length) {
+        out.push({ line: txt.slice(start), eol: '' });
+    }
+    else if (txt.length === 0) {
+        out.push({ line: '', eol: '' });
+    }
+    return out;
+};
+const normalizeInnerNewlinesToLf = (v) => v.replace(/\r\n/g, '\n');
+const findFirstNonWhitespace = (s) => {
+    for (let i = 0; i < s.length; i++) {
+        if (!/\s/.test(s.charAt(i)))
+            return i;
+    }
+    return -1;
+};
+const splitInlineCommentUnquoted = (rhs) => {
+    // Match a `#` that is preceded by whitespace; keep all whitespace before `#` with the suffix.
+    for (let i = 0; i < rhs.length; i++) {
+        const ch = rhs.charAt(i);
+        if (ch !== '#')
+            continue;
+        if (i === 0)
+            return { value: '', suffix: rhs };
+        const prev = rhs.charAt(i - 1);
+        if (!/\s/.test(prev))
+            continue;
+        let j = i;
+        while (j > 0 && /\s/.test(rhs.charAt(j - 1)))
+            j--;
+        return { value: rhs.slice(0, j), suffix: rhs.slice(j) };
+    }
+    return { value: rhs, suffix: '' };
+};
+const tryParseQuotedValueAcrossLines = (lines, startIndex, startRhs, quote) => {
+    // Parse the quoted value beginning at the first quote in startRhs.
+    // Returns null if a closing quote is never found (to avoid corrupting segmentation).
+    let idx = startIndex;
+    let rhs = startRhs;
+    const firstQuoteIdx = rhs.indexOf(quote);
+    if (firstQuoteIdx < 0)
+        return null;
+    // Value text begins after the opening quote.
+    let cursor = firstQuoteIdx + 1;
+    let escaped = false;
+    let valueOut = '';
+    while (idx < lines.length) {
+        for (; cursor < rhs.length; cursor++) {
+            const ch = rhs.charAt(cursor);
+            if (escaped) {
+                valueOut += ch;
+                escaped = false;
+                continue;
+            }
+            if (ch === '\\') {
+                // Preserve backslashes; caller may choose to re-escape on render.
+                valueOut += ch;
+                escaped = true;
+                continue;
+            }
+            if (ch === quote) {
+                // Closing quote: suffix is the remainder of this physical line after the closing quote.
+                return {
+                    endIndex: idx,
+                    value: normalizeInnerNewlinesToLf(valueOut),
+                    suffix: rhs.slice(cursor + 1),
+                };
+            }
+            valueOut += ch;
+        }
+        // Move to next physical line; insert a newline into the value.
+        idx += 1;
+        if (idx >= lines.length)
+            break;
+        // If the file ended without a newline, we still treat the join as a newline inside the quoted value.
+        valueOut += '\n';
+        const next = lines[idx];
+        if (!next)
+            break;
+        rhs = next.line;
+        cursor = 0;
+        escaped = false;
+    }
+    return null;
+};
+const parseKeyPrefix = (line) => {
+    // Allow: indentation + optional "export " + KEY
+    // KEY must be a shell-ish identifier.
+    const m = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(.*)$/.exec(line);
+    if (!m)
+        return null;
+    const prefix = m[1] ?? '';
+    const key = m[2] ?? '';
+    const rest = m[3] ?? '';
+    if (!key)
+        return null;
+    return { prefix, key, rest };
+};
+/**
+ * Parse dotenv text into a document model that preserves formatting.
+ *
+ * @param text - Dotenv file contents as UTF-8 text.
+ * @returns A parsed {@link DotenvDocument}.
+ *
+ * @public
+ */
+function parseDotenvDocument(text) {
+    const fileEol = detectFileEol(text);
+    const trailingNewline = endsWithNewline$1(text);
+    const lines = splitLinesWithEol(text);
+    const segments = [];
+    for (let i = 0; i < lines.length; i++) {
+        const cur = lines[i];
+        if (!cur)
+            continue;
+        const line = cur.line;
+        const eol = cur.eol;
+        const parsed = parseKeyPrefix(line);
+        if (!parsed) {
+            const rawSeg = { kind: 'raw', raw: line + eol };
+            segments.push(rawSeg);
+            continue;
+        }
+        const { prefix, key, rest } = parsed;
+        const mAssign = /^(\s*=\s*)(.*)$/.exec(rest);
+        if (mAssign) {
+            const separator = mAssign[1] ?? '=';
+            const rhs = mAssign[2] ?? '';
+            // Preserve whitespace between separator and first token.
+            const nonWs = findFirstNonWhitespace(rhs);
+            const valuePadding = nonWs >= 0 ? rhs.slice(0, nonWs) : rhs;
+            const tokenStart = nonWs >= 0 ? rhs.charAt(nonWs) : '';
+            // Try quoted parsing first (single-line or multiline).
+            if (tokenStart === '"' || tokenStart === "'") {
+                const quote = tokenStart === '"' ? '"' : "'";
+                const parsedQuoted = tryParseQuotedValueAcrossLines(lines, i, rhs, quote);
+                if (parsedQuoted) {
+                    const endIndex = parsedQuoted.endIndex;
+                    const raw = lines
+                        .slice(i, endIndex + 1)
+                        .map((l) => l.line + l.eol)
+                        .join('');
+                    const endEol = lines[endIndex]?.eol ?? '';
+                    const seg = {
+                        kind: 'assignment',
+                        raw,
+                        key,
+                        prefix,
+                        separator,
+                        valuePadding,
+                        quote,
+                        value: parsedQuoted.value,
+                        suffix: parsedQuoted.suffix,
+                        eol: endEol,
+                    };
+                    segments.push(seg);
+                    i = endIndex;
+                    continue;
+                }
+                // If quote is unclosed, preserve the line verbatim as raw.
+                // This avoids accidentally “parsing” malformed lines and losing formatting.
+                const rawSeg = { kind: 'raw', raw: line + eol };
+                segments.push(rawSeg);
+                continue;
+            }
+            // Unquoted single-line value: split inline comments.
+            const { value, suffix } = splitInlineCommentUnquoted(rhs);
+            const seg = {
+                kind: 'assignment',
+                raw: line + eol,
+                key,
+                prefix,
+                separator,
+                valuePadding,
+                quote: null,
+                value,
+                suffix,
+                eol,
+            };
+            segments.push(seg);
+            continue;
+        }
+        // Bare-key placeholder (KEY or KEY # comment). Only accept whitespace/comment in rest.
+        const mBare = /^(\s*)(#.*)?$/.exec(rest);
+        if (mBare) {
+            const suffix = (mBare[1] ?? '') + (mBare[2] ?? '');
+            const seg = {
+                kind: 'bare',
+                raw: line + eol,
+                key,
+                prefix,
+                suffix,
+                eol,
+            };
+            segments.push(seg);
+            continue;
+        }
+        // Unknown/unsupported syntax for this line: preserve verbatim.
+        const rawSeg = { kind: 'raw', raw: line + eol };
+        segments.push(rawSeg);
+    }
+    return { fileEol, trailingNewline, segments };
+}
+
+/**
+ * Render a parsed dotenv document back to text.
+ *
+ * Requirements addressed:
+ * - Preserve existing EOLs by default; support forcing LF/CRLF.
+ * - Preserve trailing newline presence/absence.
+ *
+ * @packageDocumentation
+ */
+const normalizeEol = (txt, eol) => txt.replace(/\r?\n/g, eol);
+const stripOneFinalNewline = (txt) => {
+    if (txt.endsWith('\r\n'))
+        return txt.slice(0, -2);
+    if (txt.endsWith('\n'))
+        return txt.slice(0, -1);
+    return txt;
+};
+const endsWithNewline = (txt) => txt.endsWith('\n') || txt.endsWith('\r\n');
+/**
+ * Render a {@link DotenvDocument} to text.
+ *
+ * @param doc - Document to render.
+ * @param eolMode - EOL policy (`preserve` | `lf` | `crlf`).
+ * @returns Rendered dotenv text.
+ *
+ * @public
+ */
+function renderDotenvDocument(doc, eolMode = 'preserve') {
+    const joined = doc.segments.map((s) => s.raw).join('');
+    const targetEol = eolMode === 'crlf' ? '\r\n' : eolMode === 'lf' ? '\n' : doc.fileEol;
+    const normalized = eolMode === 'preserve' ? joined : normalizeEol(joined, targetEol);
+    // Preserve final newline presence/absence.
+    if (doc.trailingNewline) {
+        return endsWithNewline(normalized) ? normalized : normalized + targetEol;
+    }
+    return stripOneFinalNewline(normalized);
+}
+
+/**
+ * High-level convenience API for editing dotenv text in memory.
+ *
+ * Requirements addressed:
+ * - Pure/text layer: parse → apply edits → render (no FS).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Edit dotenv text with format preservation.
+ *
+ * @param text - Existing dotenv text.
+ * @param updates - Update map of keys to values.
+ * @param options - Edit options (merge vs sync, duplicates, null/undefined behavior, EOL policy).
+ * @returns Updated dotenv text.
+ *
+ * @public
+ */
+function editDotenvText(text, updates, options = {}) {
+    const doc = parseDotenvDocument(text);
+    const edited = applyDotenvEdits(doc, updates, {
+        ...(options.mode ? { mode: options.mode } : {}),
+        ...(options.duplicateKeys ? { duplicateKeys: options.duplicateKeys } : {}),
+        ...(options.undefinedBehavior
+            ? { undefinedBehavior: options.undefinedBehavior }
+            : {}),
+        ...(options.nullBehavior ? { nullBehavior: options.nullBehavior } : {}),
+        ...(typeof options.defaultSeparator === 'string'
+            ? { defaultSeparator: options.defaultSeparator }
+            : {}),
+    });
+    return renderDotenvDocument(edited, options.eol ?? 'preserve');
+}
+
+/**
+ * @packageDocumentation
+ * Deterministic dotenv target selection across a multi-path cascade.
+ *
+ * This module extracts the “which file should we edit?” logic from the FS-level editor
+ * so plugins/tools can reuse the same selection semantics as {@link editDotenvFile}.
+ *
+ * Notes:
+ * - Selection is based on `paths` only (directories), consistent with get-dotenv overlay precedence.
+ * - Default search order is reverse (last path wins).
+ * - Template discovery is supported via `<target>.<templateExtension>` and returns the template path
+ *   when the concrete target is missing.
+ */
+const resolveEnvName = (env, defaultEnv) => typeof env === 'string' && env.length > 0
+    ? env
+    : typeof defaultEnv === 'string' && defaultEnv.length > 0
+        ? defaultEnv
+        : undefined;
+/**
+ * Build the dotenv filename for a selector (scope × privacy) using the same naming
+ * convention as get-dotenv.
+ *
+ * @param opts - Filename selector options.
+ * @returns The filename token (for example, `.env.dev.local`).
+ * @throws Error when `scope` is `'env'` and neither `env` nor `defaultEnv` is provided.
+ *
+ * @public
+ */
+function buildDotenvTargetFilename(opts) {
+    const dotenvToken = opts.dotenvToken ?? '.env';
+    const privateToken = opts.privateToken ?? 'local';
+    const envName = resolveEnvName(opts.env, opts.defaultEnv);
+    const parts = [dotenvToken];
+    if (opts.scope === 'env') {
+        if (!envName) {
+            throw new Error(`Unable to resolve env-scoped dotenv filename: env is required.`);
+        }
+        parts.push(envName);
+    }
+    if (opts.privacy === 'private')
+        parts.push(privateToken);
+    return parts.join('.');
+}
+const orderedPaths = (pathsIn, order) => {
+    const list = pathsIn.slice();
+    return order === 'forward' ? list : list.reverse();
+};
+/**
+ * Resolve a deterministic dotenv target across `paths` based on scope/privacy selectors.
+ *
+ * Selection rules:
+ * - Iterates `paths` in the requested search order.
+ * - Returns the first existing target file.
+ * - Otherwise, returns the first sibling template file (`<target>.<templateExtension>`) when present.
+ * - Throws when neither a target nor a template exists anywhere under `paths`.
+ *
+ * @param opts - Resolver options (paths + selector + fs port).
+ * @returns The resolved target path and optional template path.
+ *
+ * @public
+ */
+async function resolveDotenvTarget(opts) {
+    const filename = buildDotenvTargetFilename(opts);
+    const templateExtension = opts.templateExtension ?? 'template';
+    const searchOrder = opts.searchOrder ?? 'reverse';
+    const pathsOrdered = orderedPaths(opts.paths, searchOrder);
+    for (const dir of pathsOrdered) {
+        const targetPath = path.resolve(dir, filename);
+        if (await opts.fs.pathExists(targetPath)) {
+            return { targetPath, filename };
+        }
+        const templatePath = `${targetPath}.${templateExtension}`;
+        if (await opts.fs.pathExists(templatePath)) {
+            return { targetPath, templatePath, filename };
+        }
+    }
+    throw new Error(`Unable to locate dotenv target "${filename}" under provided paths, and no template was found.`);
+}
+
+/**
+ * FS-level dotenv editor adapter (target resolution + template bootstrap).
+ *
+ * Requirements addressed:
+ * - Deterministic target selection across getdotenv `paths` only.
+ * - Scope axis (global|env) × privacy axis (public|private).
+ * - Template bootstrap: copy `<target>.<templateExtension>` to `<target>` when needed.
+ * - Edit in place while preserving formatting via the pure text editor.
+ *
+ * @packageDocumentation
+ */
+const defaultFs = {
+    pathExists: async (p) => fs.pathExists(p),
+    readFile: async (p) => fs.readFile(p, 'utf-8'),
+    writeFile: async (p, contents) => fs.writeFile(p, contents, 'utf-8'),
+    copyFile: async (src, dest) => fs.copyFile(src, dest),
+};
+/**
+ * Edit a dotenv file selected by scope/privacy across a list of search paths.
+ *
+ * @param updates - Update map of keys to values.
+ * @param options - Target selection options + edit options.
+ * @returns An {@link EditDotenvFileResult}.
+ *
+ * @public
+ */
+async function editDotenvFile(updates, options) {
+    const fsPort = options.fs ?? defaultFs;
+    const dotenvToken = options.dotenvToken ?? '.env';
+    const privateToken = options.privateToken ?? 'local';
+    const templateExtension = options.templateExtension ?? 'template';
+    const searchOrder = options.searchOrder ?? 'reverse';
+    const resolved = await resolveDotenvTarget({
+        fs: fsPort,
+        paths: options.paths,
+        dotenvToken,
+        privateToken,
+        ...(typeof options.env === 'string' && options.env.length > 0
+            ? { env: options.env }
+            : {}),
+        ...(typeof options.defaultEnv === 'string' && options.defaultEnv.length > 0
+            ? { defaultEnv: options.defaultEnv }
+            : {}),
+        scope: options.scope,
+        privacy: options.privacy,
+        templateExtension,
+        searchOrder,
+    });
+    let createdFromTemplate = false;
+    if (resolved.templatePath) {
+        // Template bootstrap: copy template as the destination sibling.
+        // Only copy if the target does not already exist.
+        if (!(await fsPort.pathExists(resolved.targetPath))) {
+            await fsPort.copyFile(resolved.templatePath, resolved.targetPath);
+            createdFromTemplate = true;
+        }
+    }
+    const before = await fsPort.readFile(resolved.targetPath);
+    const after = editDotenvText(before, updates, {
+        ...(options.mode ? { mode: options.mode } : {}),
+        ...(options.duplicateKeys ? { duplicateKeys: options.duplicateKeys } : {}),
+        ...(options.undefinedBehavior
+            ? { undefinedBehavior: options.undefinedBehavior }
+            : {}),
+        ...(options.nullBehavior ? { nullBehavior: options.nullBehavior } : {}),
+        ...(options.eol ? { eol: options.eol } : {}),
+        ...(typeof options.defaultSeparator === 'string'
+            ? { defaultSeparator: options.defaultSeparator }
+            : {}),
+    });
+    const changed = before !== after;
+    if (changed) {
+        await fsPort.writeFile(resolved.targetPath, after);
+    }
+    return { path: resolved.targetPath, createdFromTemplate, changed };
+}
+
+async function getDotenv(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$1.resolve(p, dotenvToken));
+            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path$1.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
+            const privateGlobal = excludePrivate || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path$1.resolve(p, `${dotenvToken}.${privateToken}`));
+            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path$1.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) {
+        // A2 precedence: programmatic dynamic < dynamicPath (dynamicPath wins when present)
+        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
+            try {
+                applyDynamicMap(dotenv, options.dynamic, env ?? defaultEnv);
+            }
+            catch {
+                throw new Error(`Unable to evaluate dynamic variables.`);
+            }
+        }
+        // dynamicPath is evaluated even when programmatic `dynamic` is present.
+        if (dynamicPath) {
+            const absDynamicPath = path$1.resolve(dynamicPath);
+            await loadAndApplyDynamic(dotenv, absDynamicPath, env ?? defaultEnv, 'getdotenv-dynamic');
+        }
+    }
+    // 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 writeDotenvFile(outputPathResolved, dotenvForOutput);
+        resultDotenv = dotenvForOutput;
+    }
+    // Log result.
+    if (log) {
+        const redactFlag = options.redact ?? false;
+        const redactPatterns = options.redactPatterns ?? undefined;
+        const redOpts = {};
+        if (redactFlag)
+            redOpts.redact = true;
+        if (redactFlag && Array.isArray(redactPatterns))
+            redOpts.redactPatterns = redactPatterns;
+        const bag = redactFlag
+            ? redactObject(resultDotenv, redOpts)
+            : { ...resultDotenv };
+        logger.log(bag);
+        // Entropy warnings: once-per-key-per-run (presentation only)
+        const warnEntropyVal = options.warnEntropy ?? true;
+        const entropyThresholdVal = options
+            .entropyThreshold;
+        const entropyMinLengthVal = options
+            .entropyMinLength;
+        const entropyWhitelistVal = options.entropyWhitelist;
+        const entOpts = {};
+        if (typeof warnEntropyVal === 'boolean')
+            entOpts.warnEntropy = warnEntropyVal;
+        if (typeof entropyThresholdVal === 'number')
+            entOpts.entropyThreshold = entropyThresholdVal;
+        if (typeof entropyMinLengthVal === 'number')
+            entOpts.entropyMinLength = entropyMinLengthVal;
+        if (Array.isArray(entropyWhitelistVal))
+            entOpts.entropyWhitelist = entropyWhitelistVal;
+        for (const [k, v] of Object.entries(resultDotenv)) {
+            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
+                logger.log(line);
+            });
+        }
+    }
+    // Load process.env.
+    if (loadProcess)
+        Object.assign(process.env, resultDotenv);
+    return resultDotenv;
+}
+
+export { applyDotenvEdits, dotenvExpandAll, editDotenvFile, editDotenvText, getDotenv, maybeWarnEntropy, parseDotenvDocument, redactObject, renderDotenvDocument };