@karmaniverous/get-dotenv 6.2.4 → 6.4.0

package/dist/index.d.ts

@@ -2,6 +2,218 @@ import { z, ZodObject } from 'zod';
 export { z } from 'zod';
 import { OptionValues, Command, InferCommandArguments, Option, CommandUnknownOpts } from '@commander-js/extra-typings';
 
+/**
+ * Dotenv provenance model (descriptor-only).
+ *
+ * Requirements addressed:
+ * - Host ctx carries a dotenv provenance mapping describing per-key origin and override history.
+ * - Provenance is descriptor-only (no value payloads).
+ * - Provenance is an ordered stack per key in ascending precedence; the last entry is effective.
+ * - Explicit unsets are represented as `op: 'unset'` without requiring deletion of keys from the env map.
+ */
+/**
+ * Provenance kind for an entry in {@link DotenvProvenance}.
+ *
+ * @public
+ */
+type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
+/**
+ * Operation represented by a provenance entry.
+ *
+ * @public
+ */
+type DotenvProvenanceOp = 'set' | 'unset';
+/**
+ * Base shape for all provenance entries.
+ *
+ * @public
+ */
+interface DotenvProvenanceEntryBase {
+    /**
+     * The kind of provenance entry.
+     */
+    kind: DotenvProvenanceKind;
+    /**
+     * The operation applied at this layer.
+     */
+    op: DotenvProvenanceOp;
+}
+/**
+ * Provenance entry representing a value sourced from a dotenv file in the cascade.
+ *
+ * @public
+ */
+interface DotenvFileProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'file';
+    /** Global vs env-scoped file. */
+    scope: 'global' | 'env';
+    /** Public vs private file. */
+    privacy: 'public' | 'private';
+    /** Environment name (required when scope is `env`). */
+    env?: string;
+    /**
+     * The corresponding `paths[]` entry as provided by the caller/CLI.
+     * This is not an absolute path by policy.
+     */
+    path: string;
+    /**
+     * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
+     */
+    file: string;
+}
+/**
+ * Provenance entry representing a value sourced from config overlays (`vars` / `envVars`).
+ *
+ * @public
+ */
+interface DotenvConfigProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'config';
+    /** Global vs env-scoped config slice. */
+    scope: 'global' | 'env';
+    /** Public vs private on the privacy axis (`local` config maps to `private`). */
+    privacy: 'public' | 'private';
+    /** Environment name (required when scope is `env`). */
+    env?: string;
+    /** Packaged vs project config origin. */
+    configScope: 'packaged' | 'project';
+    /** Public vs local config file. */
+    configPrivacy: 'public' | 'local';
+}
+/**
+ * Provenance entry representing explicit variables overrides.
+ *
+ * Notes:
+ * - This kind represents values injected via `vars` (CLI/programmatic), not dotenv files.
+ *
+ * @public
+ */
+interface DotenvVarsProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'vars';
+}
+/**
+ * Source tier for dynamic variables.
+ *
+ * @public
+ */
+type DotenvDynamicSource = 'config' | 'programmatic' | 'dynamicPath';
+/**
+ * Provenance entry representing dynamic variables.
+ *
+ * @public
+ */
+interface DotenvDynamicProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'dynamic';
+    /** Dynamic source tier. */
+    dynamicSource: DotenvDynamicSource;
+    /**
+     * The `dynamicPath` value as provided by the caller/CLI when `dynamicSource` is `dynamicPath`.
+     * This is not resolved to an absolute path by provenance policy.
+     */
+    dynamicPath?: string;
+}
+/**
+ * Union of all supported provenance entry shapes.
+ *
+ * @public
+ */
+type DotenvProvenanceEntry = DotenvFileProvenanceEntry | DotenvConfigProvenanceEntry | DotenvVarsProvenanceEntry | DotenvDynamicProvenanceEntry;
+/**
+ * Per-key provenance history.
+ *
+ * Each key maps to an array of entries ordered in ascending precedence (lower to higher).
+ *
+ * @public
+ */
+type DotenvProvenance = Record<string, DotenvProvenanceEntry[]>;
+
+/**
+ * Resolved CLI options schema.
+ * For the current step this mirrors the RAW schema; later stages may further
+ * narrow types post-resolution in the host pipeline.
+ */
+/**
+ * CLI options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvCliOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
+declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: z.ZodOptional<z.ZodString>;
+    dotenvToken: z.ZodOptional<z.ZodString>;
+    dynamicPath: z.ZodOptional<z.ZodString>;
+    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    env: z.ZodOptional<z.ZodString>;
+    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
+    excludeEnv: z.ZodOptional<z.ZodBoolean>;
+    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
+    excludePrivate: z.ZodOptional<z.ZodBoolean>;
+    excludePublic: z.ZodOptional<z.ZodBoolean>;
+    loadProcess: z.ZodOptional<z.ZodBoolean>;
+    log: z.ZodOptional<z.ZodBoolean>;
+    logger: z.ZodDefault<z.ZodUnknown>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    privateToken: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+    capture: z.ZodOptional<z.ZodBoolean>;
+    trace: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    redact: z.ZodOptional<z.ZodBoolean>;
+    warnEntropy: z.ZodOptional<z.ZodBoolean>;
+    entropyThreshold: z.ZodOptional<z.ZodNumber>;
+    entropyMinLength: z.ZodOptional<z.ZodNumber>;
+    entropyWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    redactPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    paths: z.ZodOptional<z.ZodString>;
+    pathsDelimiter: z.ZodOptional<z.ZodString>;
+    pathsDelimiterPattern: z.ZodOptional<z.ZodString>;
+    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    shell: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    vars: z.ZodOptional<z.ZodString>;
+    varsAssignor: z.ZodOptional<z.ZodString>;
+    varsAssignorPattern: z.ZodOptional<z.ZodString>;
+    varsDelimiter: z.ZodOptional<z.ZodString>;
+    varsDelimiterPattern: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+/**
+ * Resolved programmatic options schema (post-inheritance).
+ * For now, this mirrors the RAW schema; future stages may materialize defaults
+ * and narrow shapes as resolution is wired into the host.
+ */
+/**
+ * Programmatic options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
+declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: z.ZodOptional<z.ZodString>;
+    dotenvToken: z.ZodOptional<z.ZodString>;
+    dynamicPath: z.ZodOptional<z.ZodString>;
+    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    env: z.ZodOptional<z.ZodString>;
+    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
+    excludeEnv: z.ZodOptional<z.ZodBoolean>;
+    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
+    excludePrivate: z.ZodOptional<z.ZodBoolean>;
+    excludePublic: z.ZodOptional<z.ZodBoolean>;
+    loadProcess: z.ZodOptional<z.ZodBoolean>;
+    log: z.ZodOptional<z.ZodBoolean>;
+    logger: z.ZodDefault<z.ZodUnknown>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    privateToken: z.ZodOptional<z.ZodString>;
+    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
+}, z.core.$strip>;
+
 /**
  * Minimal root options shape shared by CLI and generator layers.
  * Keep keys optional to respect exactOptionalPropertyTypes semantics.
@@ -121,6 +333,12 @@ interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions>
      * Final composed dotenv environment for this invocation.
      */
     dotenv: ProcessEnv;
+    /**
+     * Dotenv provenance history for {@link GetDotenvCliCtx.dotenv}.
+     *
+     * Descriptor-only: does not include value payloads.
+     */
+    dotenvProvenance: DotenvProvenance;
     /**
      * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
      */
@@ -148,90 +366,6 @@ interface BrandOptions {
     helpHeader?: string;
 }
 
-/**
- * Resolved CLI options schema.
- * For the current step this mirrors the RAW schema; later stages may further
- * narrow types post-resolution in the host pipeline.
- */
-/**
- * CLI options schema (resolved).
- *
- * Today this mirrors {@link getDotenvCliOptionsSchemaRaw}, but is kept as a distinct export
- * so future resolution steps can narrow or materialize defaults without breaking the API.
- *
- * @public
- */
-declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
-    defaultEnv: z.ZodOptional<z.ZodString>;
-    dotenvToken: z.ZodOptional<z.ZodString>;
-    dynamicPath: z.ZodOptional<z.ZodString>;
-    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    env: z.ZodOptional<z.ZodString>;
-    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
-    excludeEnv: z.ZodOptional<z.ZodBoolean>;
-    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
-    excludePrivate: z.ZodOptional<z.ZodBoolean>;
-    excludePublic: z.ZodOptional<z.ZodBoolean>;
-    loadProcess: z.ZodOptional<z.ZodBoolean>;
-    log: z.ZodOptional<z.ZodBoolean>;
-    logger: z.ZodDefault<z.ZodUnknown>;
-    outputPath: z.ZodOptional<z.ZodString>;
-    privateToken: z.ZodOptional<z.ZodString>;
-    debug: z.ZodOptional<z.ZodBoolean>;
-    strict: z.ZodOptional<z.ZodBoolean>;
-    capture: z.ZodOptional<z.ZodBoolean>;
-    trace: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
-    redact: z.ZodOptional<z.ZodBoolean>;
-    warnEntropy: z.ZodOptional<z.ZodBoolean>;
-    entropyThreshold: z.ZodOptional<z.ZodNumber>;
-    entropyMinLength: z.ZodOptional<z.ZodNumber>;
-    entropyWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    redactPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    paths: z.ZodOptional<z.ZodString>;
-    pathsDelimiter: z.ZodOptional<z.ZodString>;
-    pathsDelimiterPattern: z.ZodOptional<z.ZodString>;
-    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    shell: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
-    vars: z.ZodOptional<z.ZodString>;
-    varsAssignor: z.ZodOptional<z.ZodString>;
-    varsAssignorPattern: z.ZodOptional<z.ZodString>;
-    varsDelimiter: z.ZodOptional<z.ZodString>;
-    varsDelimiterPattern: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-
-/**
- * Resolved programmatic options schema (post-inheritance).
- * For now, this mirrors the RAW schema; future stages may materialize defaults
- * and narrow shapes as resolution is wired into the host.
- */
-/**
- * Programmatic options schema (resolved).
- *
- * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
- * so future resolution steps can narrow or materialize defaults without breaking the API.
- *
- * @public
- */
-declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
-    defaultEnv: z.ZodOptional<z.ZodString>;
-    dotenvToken: z.ZodOptional<z.ZodString>;
-    dynamicPath: z.ZodOptional<z.ZodString>;
-    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    env: z.ZodOptional<z.ZodString>;
-    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
-    excludeEnv: z.ZodOptional<z.ZodBoolean>;
-    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
-    excludePrivate: z.ZodOptional<z.ZodBoolean>;
-    excludePublic: z.ZodOptional<z.ZodBoolean>;
-    loadProcess: z.ZodOptional<z.ZodBoolean>;
-    log: z.ZodOptional<z.ZodBoolean>;
-    logger: z.ZodDefault<z.ZodUnknown>;
-    outputPath: z.ZodOptional<z.ZodString>;
-    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    privateToken: z.ZodOptional<z.ZodString>;
-    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
-}, z.core.$strip>;
-
 /**
  * Canonical programmatic options and helpers for get-dotenv.
  *
@@ -1170,6 +1304,489 @@ declare function dotenvExpandAll<T extends Record<string, string | undefined> |
  */
 declare const dotenvExpandFromProcessEnv: (value: string | undefined) => string | undefined;
 
+/**
+ * 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
+ */
+/**
+ * EOL policy for rendering a dotenv document.
+ *
+ * - `preserve`: preserve existing EOLs when possible; inserted line breaks use the detected file EOL.
+ * - `lf`: normalize all line breaks to `\n`.
+ * - `crlf`: normalize all line breaks to `\r\n`.
+ *
+ * @public
+ */
+type DotenvEolMode = 'preserve' | 'lf' | 'crlf';
+/**
+ * Editing mode for dotenv updates.
+ *
+ * - `merge` (default): update/add only the provided keys; do not delete unrelated keys.
+ * - `sync`: delete assignment/bare-key lines for keys not present in the update map.
+ *
+ * @public
+ */
+type DotenvEditMode = 'merge' | 'sync';
+/**
+ * Strategy for handling duplicate key occurrences.
+ *
+ * - `all` (default): update/delete all occurrences.
+ * - `first`: update/delete only the first occurrence.
+ * - `last`: update/delete only the last occurrence.
+ *
+ * @public
+ */
+type DotenvDuplicateKeyStrategy = 'all' | 'first' | 'last';
+/**
+ * Behavior when an update map contains a key with value `undefined`.
+ *
+ * - `skip` (default): do not modify existing occurrences; do not add a new key.
+ *
+ * @public
+ */
+type DotenvUndefinedBehavior = 'skip';
+/**
+ * Behavior when an update map contains a key with value `null`.
+ *
+ * - `delete` (default): delete matching assignment/bare-key lines (subject to duplicate strategy).
+ *
+ * @public
+ */
+type DotenvNullBehavior = 'delete';
+/**
+ * Update-map value types supported by the editor.
+ *
+ * Notes:
+ * - Objects/arrays are stringified with `JSON.stringify` before writing.
+ * - `null` deletes (by default).
+ * - `undefined` skips (by default).
+ *
+ * @public
+ */
+type DotenvUpdateValue = string | number | boolean | null | undefined | Record<string, unknown> | Array<unknown>;
+/**
+ * Update map keyed by dotenv variable name.
+ *
+ * @public
+ */
+type DotenvUpdateMap = Record<string, DotenvUpdateValue>;
+/**
+ * Options for editing a dotenv document in memory.
+ *
+ * @public
+ */
+interface DotenvEditOptions {
+    /**
+     * Editing mode (`merge` vs `sync`).
+     *
+     * @defaultValue `'merge'`
+     */
+    mode?: DotenvEditMode;
+    /**
+     * Duplicate key handling strategy.
+     *
+     * @defaultValue `'all'`
+     */
+    duplicateKeys?: DotenvDuplicateKeyStrategy;
+    /**
+     * `undefined` behavior.
+     *
+     * @defaultValue `'skip'`
+     */
+    undefinedBehavior?: DotenvUndefinedBehavior;
+    /**
+     * `null` behavior.
+     *
+     * @defaultValue `'delete'`
+     */
+    nullBehavior?: DotenvNullBehavior;
+    /**
+     * EOL normalization policy.
+     *
+     * @defaultValue `'preserve'`
+     */
+    eol?: DotenvEolMode;
+    /**
+     * Separator to use when converting a bare-key placeholder into an assignment.
+     *
+     * @defaultValue `'='`
+     */
+    defaultSeparator?: string;
+}
+/**
+ * A raw, unrecognized segment of a dotenv file. Preserved verbatim.
+ *
+ * @public
+ */
+interface DotenvRawSegment {
+    /**
+     * Segment kind.
+     */
+    kind: 'raw';
+    /**
+     * Raw text (including any EOL tokens) preserved verbatim.
+     */
+    raw: string;
+}
+/**
+ * Common fields for key-bearing segments (assignment or bare-key placeholder).
+ *
+ * @public
+ */
+interface DotenvKeySegmentBase {
+    /**
+     * Raw text for the segment, including EOL tokens.
+     */
+    raw: string;
+    /**
+     * The parsed key name (e.g., `APP_SETTING`).
+     */
+    key: string;
+    /**
+     * Prefix before the key (indentation and optional `export` token).
+     * Preserved verbatim.
+     */
+    prefix: string;
+    /**
+     * Trailing EOL token for the last physical line of this segment.
+     * For segments that end at EOF without a trailing newline, this is `''`.
+     */
+    eol: '' | '\n' | '\r\n';
+}
+/**
+ * A KEY=VALUE assignment segment.
+ *
+ * Supports single-line and multi-line quoted values (double/single quotes).
+ *
+ * @public
+ */
+interface DotenvAssignmentSegment extends DotenvKeySegmentBase {
+    /**
+     * Segment kind.
+     */
+    kind: 'assignment';
+    /**
+     * Separator including surrounding whitespace (e.g., `" = "` or `"="`).
+     */
+    separator: string;
+    /**
+     * Whitespace between separator and the start of the value token (preserved).
+     */
+    valuePadding: string;
+    /**
+     * Quote style when the value was quoted in the source.
+     */
+    quote: '"' | "'" | null;
+    /**
+     * Value content (without surrounding quotes).
+     *
+     * Note: multiline values use `\n` internally regardless of file EOL.
+     */
+    value: string;
+    /**
+     * Suffix after the value token on the closing line (typically inline comment + spaces).
+     * Preserved verbatim.
+     */
+    suffix: string;
+}
+/**
+ * A bare-key placeholder segment (e.g., `KEY` or `KEY # comment`).
+ *
+ * @public
+ */
+interface DotenvBareKeySegment extends DotenvKeySegmentBase {
+    /**
+     * Segment kind.
+     */
+    kind: 'bare';
+    /**
+     * Trailing text after the key (spaces and/or inline comment).
+     * Preserved verbatim.
+     */
+    suffix: string;
+}
+/**
+ * A parsed dotenv segment.
+ *
+ * @public
+ */
+type DotenvSegment = DotenvRawSegment | DotenvAssignmentSegment | DotenvBareKeySegment;
+/**
+ * A parsed dotenv document suitable for format-preserving edits.
+ *
+ * @public
+ */
+interface DotenvDocument {
+    /**
+     * Detected file EOL (used for inserted line breaks when preserving).
+     */
+    fileEol: '\n' | '\r\n';
+    /**
+     * Whether the original file ended with a trailing newline.
+     */
+    trailingNewline: boolean;
+    /**
+     * Ordered segments comprising the file.
+     */
+    segments: DotenvSegment[];
+}
+/**
+ * Minimal filesystem port used by the FS-level editor adapter.
+ *
+ * @public
+ */
+interface DotenvFs {
+    /**
+     * Return true when a path exists.
+     *
+     * @param p - Path to check.
+     */
+    pathExists(p: string): Promise<boolean>;
+    /**
+     * Read a UTF-8 text file.
+     *
+     * @param p - Path to read.
+     */
+    readFile(p: string): Promise<string>;
+    /**
+     * Write a UTF-8 text file.
+     *
+     * @param p - Path to write.
+     * @param contents - File contents.
+     */
+    writeFile(p: string, contents: string): Promise<void>;
+    /**
+     * Copy a file.
+     *
+     * @param src - Source path.
+     * @param dest - Destination path.
+     */
+    copyFile(src: string, dest: string): Promise<void>;
+}
+/**
+ * Dotenv target scope selector for FS-level editing.
+ *
+ * @public
+ */
+type DotenvTargetScope = 'global' | 'env';
+/**
+ * Dotenv target privacy selector for FS-level editing.
+ *
+ * @public
+ */
+type DotenvTargetPrivacy = 'public' | 'private';
+/**
+ * Path search order for selecting the first target match under `paths`.
+ *
+ * @public
+ */
+type DotenvPathSearchOrder = 'reverse' | 'forward';
+/**
+ * Options for resolving and editing a dotenv file in a multi-path cascade.
+ *
+ * @public
+ */
+interface EditDotenvFileOptions extends DotenvEditOptions {
+    /**
+     * Search paths (directories) to locate the target dotenv file.
+     */
+    paths: string[];
+    /**
+     * Base dotenv filename token.
+     *
+     * @defaultValue `'.env'`
+     */
+    dotenvToken?: string;
+    /**
+     * Private token used for private dotenv files.
+     *
+     * @defaultValue `'local'`
+     */
+    privateToken?: string;
+    /**
+     * Selected environment name (used when `scope` is `env`).
+     */
+    env?: string;
+    /**
+     * Default environment name used when `env` is not provided.
+     */
+    defaultEnv?: string;
+    /**
+     * Scope axis (global vs env-specific).
+     */
+    scope: DotenvTargetScope;
+    /**
+     * Privacy axis (public vs private).
+     */
+    privacy: DotenvTargetPrivacy;
+    /**
+     * Path search order.
+     *
+     * @defaultValue `'reverse'`
+     */
+    searchOrder?: DotenvPathSearchOrder;
+    /**
+     * Template extension used for bootstrap.
+     *
+     * When a target does not exist anywhere under `paths`, but a template exists
+     * (e.g. `.env.local.template`), the template will be copied to the target
+     * path and then edited in place.
+     *
+     * @defaultValue `'template'`
+     */
+    templateExtension?: string;
+    /**
+     * Optional filesystem port override (defaults to a Node FS adapter).
+     */
+    fs?: DotenvFs;
+}
+/**
+ * Result of a successful FS-level dotenv edit.
+ *
+ * @public
+ */
+interface EditDotenvFileResult {
+    /**
+     * Absolute path to the edited dotenv file.
+     */
+    path: string;
+    /**
+     * Whether the file was created from a template during this operation.
+     */
+    createdFromTemplate: boolean;
+    /**
+     * Whether the resulting file content differed from the prior content.
+     */
+    changed: boolean;
+}
+
+/**
+ * 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
+ */
+
+/**
+ * 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
+ */
+declare function applyDotenvEdits(doc: DotenvDocument, updates: DotenvUpdateMap, opts?: {
+    mode?: DotenvEditMode;
+    duplicateKeys?: DotenvDuplicateKeyStrategy;
+    undefinedBehavior?: DotenvUndefinedBehavior;
+    nullBehavior?: DotenvNullBehavior;
+    defaultSeparator?: string;
+}): DotenvDocument;
+
+/**
+ * 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
+ */
+
+/**
+ * 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
+ */
+declare function editDotenvFile(updates: DotenvUpdateMap, options: EditDotenvFileOptions): Promise<EditDotenvFileResult>;
+
+/**
+ * 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
+ */
+declare function editDotenvText(text: string, updates: DotenvUpdateMap, options?: DotenvEditOptions): string;
+
+/**
+ * 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
+ */
+
+/**
+ * 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
+ */
+declare function parseDotenvDocument(text: string): DotenvDocument;
+
+/**
+ * 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
+ */
+
+/**
+ * Render a {@link DotenvDocument} to text.
+ *
+ * @param doc - Document to render.
+ * @param eolMode - EOL policy (`preserve` | `lf` | `crlf`).
+ * @returns Rendered dotenv text.
+ *
+ * @public
+ */
+declare function renderDotenvDocument(doc: DotenvDocument, eolMode?: DotenvEolMode): string;
+
 /**
  * Deep interpolation utility for string leaves.
  * - Expands string values using dotenv-style expansion against the provided envRef.
@@ -1192,5 +1809,5 @@ declare const dotenvExpandFromProcessEnv: (value: string | undefined) => string
  */
 declare const interpolateDeep: <T>(value: T, envRef: ProcessEnv) => T;
 
-export { GetDotenvCli, baseRootOptionDefaults, buildSpawnEnv, createCli, defineDynamic, defineGetDotenvConfig, definePlugin, defineScripts, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, getDotenv, getDotenvCliOptions2Options, groupPlugins, interpolateDeep, maybeWarnEntropy, readMergedOptions, redactDisplay, redactObject, shouldCapture, traceChildEnv };
-export type { CreateCliOptions, DynamicFn, DynamicMap, EntropyOptions, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GetDotenvConfig, GetDotenvDynamic, GetDotenvOptions, InferGetDotenvVarsFromConfig, InferPluginConfig, PluginWithInstanceHelpers, ProcessEnv, RedactOptions, ScriptsTable, TraceChildEnvOptions };
+export { GetDotenvCli, applyDotenvEdits, baseRootOptionDefaults, buildSpawnEnv, createCli, defineDynamic, defineGetDotenvConfig, definePlugin, defineScripts, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, editDotenvFile, editDotenvText, getDotenv, getDotenvCliOptions2Options, groupPlugins, interpolateDeep, maybeWarnEntropy, parseDotenvDocument, readMergedOptions, redactDisplay, redactObject, renderDotenvDocument, shouldCapture, traceChildEnv };
+export type { CreateCliOptions, DotenvAssignmentSegment, DotenvBareKeySegment, DotenvDocument, DotenvDuplicateKeyStrategy, DotenvEditMode, DotenvEditOptions, DotenvEolMode, DotenvFs, DotenvPathSearchOrder, DotenvSegment, DotenvTargetPrivacy, DotenvTargetScope, DotenvUpdateMap, DotenvUpdateValue, DynamicFn, DynamicMap, EditDotenvFileOptions, EditDotenvFileResult, EntropyOptions, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GetDotenvConfig, GetDotenvDynamic, GetDotenvOptions, InferGetDotenvVarsFromConfig, InferPluginConfig, PluginWithInstanceHelpers, ProcessEnv, RedactOptions, ScriptsTable, TraceChildEnvOptions };