@kindgi/dotenv-file 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kindgi Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @kindgi/dotenv-file
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Dotenv files the way applications read them, written the way people edit
+them. Zero runtime dependencies, no filesystem access — you read and write
+the files; this package parses, expands, layers and edits their text.
+
+Kindgi often lives inside an existing application and shares its `.env`
+files. When both read the same file they must see the same values, and when
+Kindgi writes a key it must not disturb anything else in the file. This
+package is where that guarantee lives.
+
+```ts
+import { readEnvLayers, setKey } from '@kindgi/dotenv-file';
+
+const env = readEnvLayers([
+  { source: '.env', contents: await readOrNull('.env') },
+  { source: '.env.local', contents: await readOrNull('.env.local') },
+]);
+env.values.DATABASE_URL; // merged + expanded
+env.origin.DATABASE_URL; // '.env.local' — which file supplied it
+
+const { contents } = setKey(existingText, 'ANTHROPIC_API_KEY', key);
+```
+
+## Reading — `parseEnvFile`
+
+Grammar is `dotenv`'s `parse()`, verified input-for-input against
+`dotenv@16.3.1` (the version Next.js 16 bundles) in
+`tests/conformance.test.ts` — a hand-picked corpus plus 3000 generated
+inputs.
+
+- `KEY=value` or `KEY: value`; optional leading whitespace and `export `.
+- Keys `[A-Za-z0-9_.-]+`.
+- Unquoted values stop at the first `#` and are trimmed.
+- `'…'`, `"…"`, `` `…` `` may span lines. Inside double quotes `\n` and `\r`
+  become newline / carriage return; nothing else is unescaped.
+- Duplicate keys: last wins.
+- Lines dotenv ignores come back as `malformed` so a rewrite never drops them.
+
+Results are structured lines (`EnvLine`) — comments, blanks, malformed
+lines and each entry's exact source text — so `serializeEnvFile(parseEnvFile(x))`
+reproduces `x` (with `\n` line endings).
+
+**One deliberate divergence:** dotenv's regex lets a key's separator, or an
+empty value's leading whitespace, cross a newline (`KEY=` followed by a line
+that starts with a quote joins the two). Here a key, its separator and the
+start of its value are always on one line.
+
+## Expanding — `expandEnv`
+
+`$NAME`, `${NAME}`, `${NAME:-default}`, `${NAME-default}`, `${NAME:+alt}`,
+`${NAME+alt}`, and `\$` for a literal `$`. Defaults nest.
+
+Host frameworks don't agree on expansion — Next.js 16 bundles
+`dotenv-expand` 10, Vite uses 12. Kindgi matches both wherever they agree
+(verified in `tests/conformance.test.ts`) and chooses as follows where they
+don't:
+
+| Case | Next.js (expand 10) | Vite (expand 12) | Kindgi |
+|---|---|---|---|
+| `${A}`, A defined above | A | A | A |
+| `A=$B`, B defined below | B | `""` | B |
+| `${A:-d}`, A set in the same file | `d` | A | A |
+| `${A-d}`, `${A:+x}`, `${A+x}` | not supported | supported | supported |
+| `$1` | `""` | `$1` | `$1` |
+| shell env vs. a file's own value | shell wins | shell wins | **file wins** |
+
+The last row is intentional: the files are the source, and
+`options.env` only fills names no file defines (so `${HOME}` works).
+Nothing reads `process.env` unless the caller passes it. Undefined
+references expand to `""`; cycles are cut; both are reported in
+`diagnostics`.
+
+## Layering — `readEnvLayers`
+
+Several files as one view. Layers are ordered **lowest precedence first**;
+a later layer's key wins. Raw values merge first and are expanded once over
+the merged view, so a reference in `.env` to a name defined in `.env.local`
+sees the `.env.local` value — the same result Next.js produces. Each key
+reports its `origin`; malformed lines, unresolved references and cycles
+come back as `diagnostics` with their source.
+
+## Writing — `setKey`, `unsetKey`, `renderEntry`
+
+`setKey` replaces the **last** occurrence of a key (the one readers see),
+keeping its `export ` prefix, or appends. `unsetKey` removes every
+occurrence. Every other line — comments, hand-written quoting, inline
+comments, malformed lines — is kept byte-for-byte.
+
+Values are rendered so they read back exactly, through dotenv and
+expansion:
+
+1. `[A-Za-z0-9_.,:/@+=%~-]+` → unquoted.
+2. Otherwise double quotes, if the value has no `"` and no literal `\n` /
+   `\r` sequence (real newlines are written as `\n`).
+3. Otherwise single quotes, if no `'` and no carriage return.
+4. Otherwise backticks, if no `` ` `` and no carriage return.
+5. Otherwise `EnvValueNotRepresentableError` — never a silently different
+   value.
+
+`$` is always written as `\$`, because expanders substitute `$NAME` even
+inside quotes and `\$` is the escape they all undo.
+
+Writes accept only POSIX env names (`ENV_KEY_REGEX`, `[A-Z_][A-Z0-9_]*`),
+so every key Kindgi writes can also be exported from a shell. Reads accept
+everything dotenv does (`DOTENV_KEY_REGEX`).

package/dist/expand.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `${VAR}` expansion over parsed dotenv values.
+ *
+ * Host frameworks expand with `dotenv-expand`, but not one version:
+ * Next.js 16 bundles v10's algorithm, Vite uses v12, and the two differ
+ * (v10 resolves references to keys defined later in the file, v12
+ * does not). This module implements one well-defined semantics that
+ * agrees with BOTH on everything they agree on — verified by
+ * `tests/conformance.test.ts` — and picks Next.js's (order-independent)
+ * answer where they differ.
+ *
+ * Syntax:
+ *   - `$NAME` (`[A-Za-z_][A-Za-z0-9_]*`) and `${NAME}`
+ *   - `${NAME:-default}` — default when NAME is unset or empty
+ *   - `${NAME-default}`  — default when NAME is unset
+ *   - `${NAME:+alt}`     — alt when NAME is set and non-empty, else empty
+ *   - `${NAME+alt}`      — alt when NAME is set, else empty
+ *   - `\$` — a literal `$` (the writer escapes every `$` this way)
+ *   Defaults / alts are themselves expanded. A `$` not followed by a
+ *   name or `{…}` is literal.
+ *
+ * Lookup: a name defined in the files resolves to its (expanded) file
+ * value, wherever in the files it is defined. Only a name defined in no
+ * file falls back to `options.env` (so `${HOME}` works). Unlike
+ * `dotenv-expand`, the caller's env never overrides a file's own value:
+ * the files are the source, the environment only fills gaps. Nothing
+ * reads `process.env` implicitly — callers pass what they mean.
+ *
+ * Undefined references expand to `''` and cycles (`A=$B`, `B=$A`) are
+ * cut at the repeated name; both are reported in `diagnostics`.
+ */
+export interface ExpandOptions {
+    /** Fallback for names no file defines. Never overrides a file value. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export interface ExpandDiagnostic {
+    readonly kind: 'unresolved' | 'cycle';
+    /** The key whose value contains the reference. */
+    readonly key: string;
+    /** The referenced name. */
+    readonly ref: string;
+}
+export interface ExpandResult {
+    readonly values: Record<string, string>;
+    readonly diagnostics: readonly ExpandDiagnostic[];
+}
+export declare function expandEnv(values: Readonly<Record<string, string>>, options?: ExpandOptions): ExpandResult;
+//# sourceMappingURL=expand.d.ts.map

package/dist/expand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../src/expand.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;IACtC,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAOD,wBAAgB,SAAS,CACvB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACxC,OAAO,GAAE,aAAkB,GAC1B,YAAY,CA2Dd"}

package/dist/expand.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+const NAME_START = /[A-Za-z_]/;
+const NAME_CHAR = /[A-Za-z0-9_]/;
+const OPERATORS = [':-', ':+', '-', '+'];
+export function expandEnv(values, options = {}) {
+    const env = options.env ?? {};
+    const resolved = new Map();
+    const stack = [];
+    const diagnostics = [];
+    const has = (name) => Object.prototype.hasOwnProperty.call(values, name);
+    function lookup(name, fromKey) {
+        if (has(name)) {
+            if (stack.includes(name)) {
+                diagnostics.push({ kind: 'cycle', key: fromKey, ref: name });
+                return undefined;
+            }
+            return resolve(name);
+        }
+        const fromEnv = env[name];
+        return typeof fromEnv === 'string' ? fromEnv : undefined;
+    }
+    function resolve(key) {
+        const cached = resolved.get(key);
+        if (cached !== undefined)
+            return cached;
+        stack.push(key);
+        const out = expandString(values[key] ?? '', key);
+        stack.pop();
+        resolved.set(key, out);
+        return out;
+    }
+    function evaluate(expression, key) {
+        const { name, op, operand } = splitExpression(expression);
+        const value = lookup(name, key);
+        if (op !== undefined)
+            return APPLY[op](value, () => expandString(operand, key));
+        if (value !== undefined)
+            return value;
+        if (!diagnostics.some((d) => d.key === key && d.ref === name)) {
+            diagnostics.push({ kind: 'unresolved', key, ref: name });
+        }
+        return '';
+    }
+    function expandString(input, key) {
+        let out = '';
+        let i = 0;
+        while (i < input.length) {
+            const token = readToken(input, i);
+            if (token === undefined) {
+                out += input[i];
+                i += 1;
+                continue;
+            }
+            out += token.kind === 'escape' ? '$' : evaluate(token.expression, key);
+            i = token.end;
+        }
+        return out;
+    }
+    const out = {};
+    for (const key of Object.keys(values))
+        out[key] = resolve(key);
+    return { values: out, diagnostics };
+}
+/** Operator semantics (bash): `:` also treats an empty value as unset. */
+const APPLY = {
+    ':-': (value, operand) => (value === undefined || value === '' ? operand() : value),
+    '-': (value, operand) => (value === undefined ? operand() : value),
+    ':+': (value, operand) => (value !== undefined && value !== '' ? operand() : ''),
+    '+': (value, operand) => (value !== undefined ? operand() : ''),
+};
+/** The escape or reference starting at `i`, if any. */
+function readToken(input, i) {
+    if (input[i] === '\\' && input[i + 1] === '$')
+        return { kind: 'escape', end: i + 2 };
+    if (input[i] !== '$')
+        return undefined;
+    const next = input[i + 1];
+    if (next === '{') {
+        const close = findBraceClose(input, i + 2);
+        return close === -1
+            ? undefined
+            : { kind: 'ref', expression: input.slice(i + 2, close), end: close + 1 };
+    }
+    if (next === undefined || !NAME_START.test(next))
+        return undefined;
+    let end = i + 2;
+    while (end < input.length && NAME_CHAR.test(input[end] ?? ''))
+        end += 1;
+    return { kind: 'ref', expression: input.slice(i + 1, end), end };
+}
+/**
+ * Index of the `}` closing a `${…}` whose body starts at `from`, or -1
+ * when it is not an expression (empty body, unterminated, or a bare `{`
+ * inside). A nested `${…}` — e.g. in a default — nests; `\$` is skipped.
+ */
+function findBraceClose(input, from) {
+    const tokens = /\\\$|\$\{|[{}]/g;
+    tokens.lastIndex = from;
+    let depth = 1;
+    for (let m = tokens.exec(input); m !== null; m = tokens.exec(input)) {
+        if (m[0] === '{')
+            return -1;
+        if (m[0] === '${')
+            depth += 1;
+        else if (m[0] === '}')
+            depth -= 1;
+        if (depth === 0)
+            return m.index === from ? -1 : m.index;
+    }
+    return -1;
+}
+function splitExpression(expression) {
+    for (let i = 1; i < expression.length; i += 1) {
+        for (const op of OPERATORS) {
+            if (expression.startsWith(op, i)) {
+                return { name: expression.slice(0, i), op, operand: expression.slice(i + op.length) };
+            }
+        }
+    }
+    return { name: expression, op: undefined, operand: '' };
+}
+//# sourceMappingURL=expand.js.map

package/dist/expand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.js","sourceRoot":"","sources":["../src/expand.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAoDjC,MAAM,UAAU,GAAG,WAAW,CAAC;AAC/B,MAAM,SAAS,GAAG,cAAc,CAAC;AACjC,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAGlD,MAAM,UAAU,SAAS,CACvB,MAAwC,EACxC,UAAyB,EAAE;IAE3B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE1F,SAAS,MAAM,CAAC,IAAY,EAAE,OAAe;QAC3C,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACd,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC7D,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3D,CAAC;IAED,SAAS,OAAO,CAAC,GAAW;QAC1B,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QACjD,KAAK,CAAC,GAAG,EAAE,CAAC;QACZ,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,SAAS,QAAQ,CAAC,UAAkB,EAAE,GAAW;QAC/C,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChC,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QAChF,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,CAAC;YAC9D,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,SAAS,YAAY,CAAC,KAAa,EAAE,GAAW;QAC9C,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;gBAChB,CAAC,IAAI,CAAC,CAAC;gBACP,SAAS;YACX,CAAC;YACD,GAAG,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;YACvE,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC;QAChB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC;AACtC,CAAC;AAED,0EAA0E;AAC1E,MAAM,KAAK,GAEP;IACF,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACnF,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CAChE,CAAC;AAMF,uDAAuD;AACvD,SAAS,SAAS,CAAC,KAAa,EAAE,CAAS;IACzC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IACrF,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3C,OAAO,KAAK,KAAK,CAAC,CAAC;YACjB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC;IAC7E,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACnE,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAAE,GAAG,IAAI,CAAC,CAAC;IACxE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAa,EAAE,IAAY;IACjD,MAAM,MAAM,GAAG,iBAAiB,CAAC;IACjC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACpE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,OAAO,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,KAAK,IAAI,CAAC,CAAC;aACzB,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,KAAK,IAAI,CAAC,CAAC;QAClC,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,SAAS,eAAe,CAAC,UAAkB;IAKzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC3B,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;gBACjC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;YACxF,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@kindgi/dotenv-file` — dotenv files the way applications read them,
+ * written the way people edit them.
+ *
+ *   - **Read** (`parse.ts`): `dotenv`'s grammar (verified against the
+ *     version Next.js bundles), returned as structured lines so edits
+ *     round-trip losslessly.
+ *   - **Expand** (`expand.ts`): `${VAR}` / `${VAR:-default}` / `\$`,
+ *     agreeing with `dotenv-expand` wherever its versions agree.
+ *   - **Layer** (`layers.ts`): several files (`.env` < `.env.local`) as
+ *     one view, with per-key origin.
+ *   - **Write** (`serialize.ts`): `setKey` / `unsetKey` touch one key and
+ *     keep every other byte; values are quoted so they read back
+ *     exactly.
+ *
+ * Zero runtime dependencies and no filesystem access — callers read and
+ * write the files. See `README.md`.
+ */
+export { type ExpandDiagnostic, type ExpandOptions, type ExpandResult, expandEnv, } from './expand.js';
+export { type EnvDiagnostic, type EnvLayer, type LayeredEnv, readEnv, readEnvLayers, } from './layers.js';
+export { DOTENV_KEY_REGEX, ENV_KEY_REGEX, type EnvLine, envLinesToRecord, parseEntryRaw, parseEnvFile, } from './parse.js';
+export { EnvValueNotRepresentableError, renderEntry, serializeEnvFile, setKey, unsetKey, } from './serialize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,OAAO,EACP,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,KAAK,OAAO,EACZ,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,6BAA6B,EAC7B,WAAW,EACX,gBAAgB,EAChB,MAAM,EACN,QAAQ,GACT,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * `@kindgi/dotenv-file` — dotenv files the way applications read them,
+ * written the way people edit them.
+ *
+ *   - **Read** (`parse.ts`): `dotenv`'s grammar (verified against the
+ *     version Next.js bundles), returned as structured lines so edits
+ *     round-trip losslessly.
+ *   - **Expand** (`expand.ts`): `${VAR}` / `${VAR:-default}` / `\$`,
+ *     agreeing with `dotenv-expand` wherever its versions agree.
+ *   - **Layer** (`layers.ts`): several files (`.env` < `.env.local`) as
+ *     one view, with per-key origin.
+ *   - **Write** (`serialize.ts`): `setKey` / `unsetKey` touch one key and
+ *     keep every other byte; values are quoted so they read back
+ *     exactly.
+ *
+ * Zero runtime dependencies and no filesystem access — callers read and
+ * write the files. See `README.md`.
+ */
+export { expandEnv, } from './expand.js';
+export { readEnv, readEnvLayers, } from './layers.js';
+export { DOTENV_KEY_REGEX, ENV_KEY_REGEX, envLinesToRecord, parseEntryRaw, parseEnvFile, } from './parse.js';
+export { EnvValueNotRepresentableError, renderEntry, serializeEnvFile, setKey, unsetKey, } from './serialize.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAIL,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,OAAO,EAIL,OAAO,EACP,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,aAAa,EAEb,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,6BAA6B,EAC7B,WAAW,EACX,gBAAgB,EAChB,MAAM,EACN,QAAQ,GACT,MAAM,gBAAgB,CAAC"}

package/dist/layers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Layered env files — several dotenv files read as one view, the way
+ * an application reads `.env` + `.env.local`.
+ *
+ * Layers are ordered LOWEST precedence first: a key in a later layer
+ * overrides the same key in an earlier one. Raw values are merged
+ * first, then expanded once over the merged view, so a reference in
+ * `.env` to a name defined in `.env.local` sees the `.env.local` value
+ * (matching how Next.js loads its files). Pure — the caller reads the
+ * files and passes their contents (`null` for a file that doesn't
+ * exist), so this module never touches the filesystem.
+ */
+import { type ExpandDiagnostic, type ExpandOptions } from './expand.js';
+export interface EnvLayer {
+    /** Where the contents came from (a path, usually). Reported back in `origin`. */
+    readonly source: string;
+    /** File contents, or `null` when the file does not exist. */
+    readonly contents: string | null;
+}
+export type EnvDiagnostic = (ExpandDiagnostic & {
+    readonly source: string;
+}) | {
+    readonly kind: 'malformed';
+    readonly source: string;
+    /** 1-based line number in `source`. */
+    readonly line: number;
+    /** The line's text. May hold a secret — show `source:line` to users, not this. */
+    readonly raw: string;
+    readonly reason: string;
+};
+export interface LayeredEnv {
+    /** Merged, expanded values. */
+    readonly values: Readonly<Record<string, string>>;
+    /** Merged values as written (before expansion). */
+    readonly raw: Readonly<Record<string, string>>;
+    /** For each key, the `source` of the layer that supplied it. */
+    readonly origin: Readonly<Record<string, string>>;
+    /** Sources that exist (non-`null` contents), in layer order. */
+    readonly present: readonly string[];
+    /** Malformed lines (ignored, as dotenv does), unresolved references, cycles. */
+    readonly diagnostics: readonly EnvDiagnostic[];
+}
+export declare function readEnvLayers(layers: readonly EnvLayer[], options?: ExpandOptions): LayeredEnv;
+/** One file's values, parsed and expanded. */
+export declare function readEnv(contents: string, options?: ExpandOptions): Record<string, string>;
+//# sourceMappingURL=layers.d.ts.map

package/dist/layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../src/layers.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAa,MAAM,aAAa,CAAC;AAGnF,MAAM,WAAW,QAAQ;IACvB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,MAAM,aAAa,GACrB,CAAC,gBAAgB,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAChD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;CAChD;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,OAAO,GAAE,aAAkB,GAC1B,UAAU,CAgCZ;AAED,8CAA8C;AAC9C,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7F"}