@karmaniverous/get-dotenv 6.2.4 → 6.3.0

package/dist/index.mjs

@@ -1,27 +1,28 @@
-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-BSn6Be40.mjs';
+export { G as GetDotenvCli, b as baseRootOptionDefaults, e as defineDynamic, f as defineGetDotenvConfig, d as definePlugin, h as getDotenv, g as getDotenvCliOptions2Options, k as interpolateDeep, m as maybeWarnEntropy, r as readMergedOptions, i as redactDisplay, j as redactObject } from './chunks/readMergedOptions-DLBDzpXX.mjs';
+export { d as buildSpawnEnv, s as shouldCapture } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-DdqcXCV1.mjs';
+import fs from 'fs-extra';
 import 'crypto';
 import 'path';
 import 'url';
 export { z } from 'zod';
 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';
+export { t as traceChildEnv } from './chunks/index-BqZ3PB6c.mjs';
+export { d as dotenvExpand, b as dotenvExpandAll, c as dotenvExpandFromProcessEnv } from './chunks/overlayEnv-Bqh_kPGA.mjs';
+import path from 'node:path';
+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-_qtsVxda.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
 import '@commander-js/extra-typings';
-import './chunks/index-CeCufHlm.mjs';
+import './chunks/index-BNcKuiBy.mjs';
 import 'buffer';
 import 'os';
 import 'node:fs/promises';
@@ -36,5 +37,696 @@ 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');
+}
+
+/**
+ * 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),
+};
+const resolveEnvName = (env, defaultEnv) => typeof env === 'string' && env.length > 0
+    ? env
+    : typeof defaultEnv === 'string' && defaultEnv.length > 0
+        ? defaultEnv
+        : undefined;
+const buildTargetFilename = (opts) => {
+    const { dotenvToken, privateToken, scope, privacy, envName } = opts;
+    const parts = [dotenvToken];
+    if (scope === 'env') {
+        if (!envName) {
+            throw new Error(`Unable to resolve env-scoped dotenv filename: env is required.`);
+        }
+        parts.push(envName);
+    }
+    if (privacy === 'private')
+        parts.push(privateToken);
+    return parts.join('.');
+};
+const orderedPaths = (pathsIn, order) => {
+    const list = pathsIn.slice();
+    return order === 'forward' ? list : list.reverse();
+};
+const resolveTargetAcrossPaths = async (fsPort, opts) => {
+    const { filename, templateExtension, searchOrder } = opts;
+    const pathsOrdered = orderedPaths(opts.paths, searchOrder);
+    for (const dir of pathsOrdered) {
+        const targetPath = path.resolve(dir, filename);
+        if (await fsPort.pathExists(targetPath))
+            return { targetPath };
+        const templatePath = `${targetPath}.${templateExtension}`;
+        if (await fsPort.pathExists(templatePath))
+            return { targetPath, templatePath };
+    }
+    throw new Error(`Unable to locate dotenv target "${filename}" under provided paths, and no template was found.`);
+};
+/**
+ * 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 envName = resolveEnvName(options.env, options.defaultEnv);
+    const filename = buildTargetFilename({
+        dotenvToken,
+        privateToken,
+        scope: options.scope,
+        privacy: options.privacy,
+        ...(envName ? { envName } : {}),
+    });
+    const resolved = await resolveTargetAcrossPaths(fsPort, {
+        paths: options.paths,
+        filename,
+        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 };
+}
+
+export { applyDotenvEdits, editDotenvFile, editDotenvText, parseDotenvDocument, renderDotenvDocument };