dotenv-diff 1.5.0 → 1.6.2

package/README.md

@@ -31,7 +31,7 @@ dotenv-diff will automatically compare all matching .env* files in your project
 - `.env.production`
 - Any other .env.* file
 
-## Optional: Check values too 
+## Optional: Check values too
 
 ```bash
 dotenv-diff --check-values
@@ -39,6 +39,30 @@ dotenv-diff --check-values
 
 When using the `--check-values` option, the tool will also compare the actual values of the variables in `.env` and `.env.example`. It will report any mismatches found and it also compares values if .env.example defines a non-empty expected value.
 
+## Duplicate key warnings
+
+`dotenv-diff` warns when a `.env*` file contains the same key multiple times. The last occurrence wins. Suppress these warnings with `--allow-duplicates`.
+
+## Compare specific files
+
+Override the autoscan and compare exactly two files:
+
+```bash
+dotenv-diff --env .env.staging --example .env.example.staging
+```
+
+You can also fix only one side. For example, force a particular `.env` file and let the tool find the matching `.env.example`:
+
+```bash
+dotenv-diff --env .env.production
+```
+
+Or provide just an example file and let the tool locate the appropriate `.env`:
+
+```bash
+dotenv-diff --example .env.example.production
+```
+
 ## CI usage
 
 Run non-interactively in CI environments with:

package/dist/bin/dotenv-diff.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/dotenv-diff.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createProgram } from '../src/cli/program.js';
+import { run } from '../src/cli/run.js';
+const program = createProgram();
+run(program).catch((err) => {
+    console.error(err?.message ?? err);
+    process.exit(1);
+});

package/dist/cli.js

@@ -21,6 +21,8 @@ program
     .option('--check-values', 'Compare actual values if example has values')
     .option('--ci', 'Run non-interactively and never create files')
     .option('-y, --yes', 'Run non-interactively and answer Yes to prompts')
+    .option('--env <file>', 'Path to a specific .env file')
+    .option('--example <file>', 'Path to a specific .env.example file')
     .parse(process.argv);
 const options = program.opts();
 const checkValues = options.checkValues ?? false;
@@ -30,14 +32,108 @@ if (isCiMode && isYesMode) {
     console.log(chalk.yellow('⚠️  Both --ci and --yes provided; proceeding with --yes.'));
 }
 const cwd = process.cwd();
+const envFlag = options.env ? path.resolve(cwd, options.env) : null;
+const exampleFlag = options.example ? path.resolve(cwd, options.example) : null;
+const bothFlags = Boolean(envFlag && exampleFlag);
+let alreadyWarnedMissingEnv = false;
+if (bothFlags) {
+    const envExistsFlag = fs.existsSync(envFlag);
+    const exampleExistsFlag = fs.existsSync(exampleFlag);
+    if (!envExistsFlag || !exampleExistsFlag) {
+        if (!envExistsFlag) {
+            console.error(chalk.red(`❌ Error: --env file not found: ${path.basename(envFlag)}`));
+        }
+        if (!exampleExistsFlag) {
+            console.error(chalk.red(`❌ Error: --example file not found: ${path.basename(exampleFlag)}`));
+        }
+        process.exit(1);
+    }
+    console.log(chalk.bold(`🔍 Comparing ${path.basename(envFlag)} ↔ ${path.basename(exampleFlag)}...`));
+    const current = parseEnvFile(envFlag);
+    const example = parseEnvFile(exampleFlag);
+    const diff = diffEnv(current, example, checkValues);
+    const emptyKeys = Object.entries(current)
+        .filter(([, value]) => (value ?? '').trim() === '')
+        .map(([key]) => key);
+    let exitWithError = false;
+    if (diff.missing.length === 0 &&
+        diff.extra.length === 0 &&
+        emptyKeys.length === 0 &&
+        diff.valueMismatches.length === 0) {
+        console.log(chalk.green('  ✅ All keys match.'));
+        console.log();
+        process.exit(0);
+    }
+    if (diff.missing.length > 0) {
+        exitWithError = true;
+        console.log(chalk.red('  ❌ Missing keys:'));
+        diff.missing.forEach((key) => console.log(chalk.red(`      - ${key}`)));
+    }
+    if (diff.extra.length > 0) {
+        console.log(chalk.yellow('  ⚠️  Extra keys (not in example):'));
+        diff.extra.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+    }
+    if (emptyKeys.length > 0) {
+        console.log(chalk.yellow('  ⚠️  Empty values:'));
+        emptyKeys.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+    }
+    if (checkValues && diff.valueMismatches.length > 0) {
+        console.log(chalk.yellow('  ⚠️  Value mismatches:'));
+        diff.valueMismatches.forEach(({ key, expected, actual }) => {
+            console.log(chalk.yellow(`      - ${key}: expected '${expected}', but got '${actual}'`));
+        });
+    }
+    console.log();
+    process.exit(exitWithError ? 1 : 0);
+}
 const envFiles = fs
     .readdirSync(cwd)
     .filter((f) => f.startsWith('.env') && !f.startsWith('.env.example'))
     .sort((a, b) => (a === '.env' ? -1 : b === '.env' ? 1 : a.localeCompare(b)));
 // Brug første .env* fil som "main" hvis flere findes
 // (resten håndteres senere i et loop)
-const primaryEnv = envFiles.includes('.env') ? '.env' : envFiles[0] || '.env';
-const primaryExample = '.env.example';
+let primaryEnv = envFiles.includes('.env') ? '.env' : envFiles[0] || '.env';
+let primaryExample = '.env.example';
+// Override env-siden hvis --env er sat
+if (envFlag && !exampleFlag) {
+    const envNameFromFlag = path.basename(envFlag);
+    primaryEnv = envNameFromFlag;
+    const exists = fs.existsSync(envFlag);
+    if (exists) {
+        const set = new Set([envNameFromFlag, ...envFiles]);
+        envFiles.length = 0;
+        envFiles.push(...[...set]);
+    }
+    const suffix = envNameFromFlag === '.env' ? '' : envNameFromFlag.replace('.env', '');
+    const potentialExample = suffix ? `.env.example${suffix}` : '.env.example';
+    if (fs.existsSync(path.resolve(cwd, potentialExample))) {
+        primaryExample = potentialExample;
+    }
+}
+// Override example-siden hvis --example er sat
+if (exampleFlag && !envFlag) {
+    const exampleNameFromFlag = path.basename(exampleFlag);
+    primaryExample = exampleNameFromFlag;
+    if (exampleNameFromFlag.startsWith('.env.example')) {
+        const suffix = exampleNameFromFlag.slice('.env.example'.length); // '' eller '.staging'
+        const matchedEnv = suffix ? `.env${suffix}` : '.env';
+        if (fs.existsSync(path.resolve(cwd, matchedEnv))) {
+            primaryEnv = matchedEnv;
+            envFiles.length = 0;
+            envFiles.push(matchedEnv);
+        }
+        else {
+            // Ingen tidlig log her; Case 2 håndterer “file not found”-logikken
+            alreadyWarnedMissingEnv = true;
+        }
+    }
+    else {
+        // Ikke et .env.example* navn → betragt det som en arbitrær example-fil.
+        // Rør ikke env’ens valg; behold primaryEnv som tidligere (typisk '.env').
+        if (envFiles.length === 0)
+            envFiles.push(primaryEnv);
+    }
+}
 const envPath = path.resolve(cwd, primaryEnv);
 const examplePath = path.resolve(cwd, primaryExample);
 const envExists = fs.existsSync(envPath);
@@ -49,7 +145,9 @@ if (envFiles.length === 0 && !exampleExists) {
 }
 // Case 2: .env is missing but .env.example exists
 if (!envExists && exampleExists) {
-    console.log(chalk.yellow('📄 .env file not found.'));
+    if (!alreadyWarnedMissingEnv) {
+        console.log(chalk.yellow(`📄 ${path.basename(envPath)} file not found.`));
+    }
     let createEnv = false;
     if (isYesMode) {
         createEnv = true;
@@ -62,7 +160,7 @@ if (!envExists && exampleExists) {
         const response = await prompts({
             type: 'select',
             name: 'createEnv',
-            message: '❓ Do you want to create a new .env file from .env.example?',
+            message: `❓ Do you want to create a new ${path.basename(envPath)} file from ${path.basename(examplePath)}?`,
             choices: [
                 { title: 'Yes', value: true },
                 { title: 'No', value: false },
@@ -77,12 +175,12 @@ if (!envExists && exampleExists) {
     }
     const exampleContent = fs.readFileSync(examplePath, 'utf-8');
     fs.writeFileSync(envPath, exampleContent);
-    console.log(chalk.green('✅ .env file created successfully from .env.example.\n'));
-    warnIfEnvNotIgnored();
+    console.log(chalk.green(`✅ ${path.basename(envPath)} file created successfully from ${path.basename(examplePath)}.\n`));
+    warnIfEnvNotIgnored({ envFile: path.basename(envPath) });
 }
 // Case 3: .env exists, but .env.example is missing
 if (envExists && !exampleExists) {
-    console.log(chalk.yellow('📄 .env.example file not found.'));
+    console.log(chalk.yellow(`📄 ${path.basename(examplePath)} file not found.`));
     let createExample = false;
     if (isYesMode) {
         createExample = true;
@@ -95,7 +193,7 @@ if (envExists && !exampleExists) {
         const response = await prompts({
             type: 'select',
             name: 'createExample',
-            message: '❓ Do you want to create a new .env.example file from .env?',
+            message: `❓ Do you want to create a new ${path.basename(examplePath)} file from ${path.basename(envPath)}?`,
             choices: [
                 { title: 'Yes', value: true },
                 { title: 'No', value: false },
@@ -120,7 +218,7 @@ if (envExists && !exampleExists) {
     })
         .join('\n');
     fs.writeFileSync(examplePath, envContent);
-    console.log(chalk.green('✅ .env.example file created successfully from .env.\n'));
+    console.log(chalk.green(`✅ ${path.basename(examplePath)} file created successfully from ${path.basename(envPath)}.\n`));
 }
 // Case 4: Run comparison
 if (!fs.existsSync(envPath) || !fs.existsSync(examplePath)) {
@@ -130,12 +228,22 @@ if (!fs.existsSync(envPath) || !fs.existsSync(examplePath)) {
 // Case 5: Compare all found .env* files
 let exitWithError = false;
 for (const envName of envFiles.length > 0 ? envFiles : [primaryEnv]) {
+    // Skip self-compare når --example er sat (uden --env)
+    if (exampleFlag && !envFlag) {
+        const envAbs = path.resolve(cwd, envName);
+        if (envAbs === examplePath) {
+            // (valgfri) console.log(chalk.gray(`Skipping self-compare for ${envName}`));
+            continue;
+        }
+    }
     const suffix = envName === '.env' ? '' : envName.replace('.env', '');
     const exampleName = suffix ? `.env.example${suffix}` : primaryExample;
     const envPathCurrent = path.resolve(cwd, envName);
-    const examplePathCurrent = fs.existsSync(path.resolve(cwd, exampleName))
-        ? path.resolve(cwd, exampleName)
-        : examplePath;
+    const examplePathCurrent = (exampleFlag && !envFlag)
+        ? examplePath
+        : (fs.existsSync(path.resolve(cwd, exampleName))
+            ? path.resolve(cwd, exampleName)
+            : examplePath);
     if (!fs.existsSync(envPathCurrent) || !fs.existsSync(examplePathCurrent)) {
         console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${path.basename(examplePathCurrent)}...`));
         console.log(chalk.yellow('  ⚠️  Skipping: missing matching example file.'));

package/dist/src/cli/program.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createProgram(): Command;

package/dist/src/cli/program.js

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+export function createProgram() {
+    return new Command()
+        .name('dotenv-diff')
+        .description('Compare .env and .env.example files')
+        .option('--check-values', 'Compare actual values if example has values')
+        .option('--ci', 'Run non-interactively and never create files')
+        .option('-y, --yes', 'Run non-interactively and answer Yes to prompts')
+        .option('--env <file>', 'Path to a specific .env file')
+        .option('--example <file>', 'Path to a specific .env.example file')
+        .option('--allow-duplicates', 'Do not warn about duplicate keys in .env* files');
+}

package/dist/src/cli/run.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function run(program: Command): Promise<void>;

package/dist/src/cli/run.js

@@ -0,0 +1,62 @@
+import { normalizeOptions } from '../config/options.js';
+import { discoverEnvFiles } from '../services/envDiscovery.js';
+import { pairWithExample } from '../services/envPairing.js';
+import { ensureFilesOrPrompt } from '../commands/init.js';
+import { compareMany } from '../commands/compare.js';
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+export async function run(program) {
+    program.parse(process.argv);
+    const raw = program.opts();
+    const opts = normalizeOptions(raw);
+    // Special-case: both flags → direct comparison
+    if (opts.envFlag && opts.exampleFlag) {
+        const envExists = fs.existsSync(opts.envFlag);
+        const exExists = fs.existsSync(opts.exampleFlag);
+        if (!envExists || !exExists) {
+            if (!envExists) {
+                console.error(chalk.red(`❌ Error: --env file not found: ${path.basename(opts.envFlag)}`));
+            }
+            if (!exExists) {
+                console.error(chalk.red(`❌ Error: --example file not found: ${path.basename(opts.exampleFlag)}`));
+            }
+            process.exit(1);
+        }
+        const { exitWithError } = await compareMany([
+            {
+                envName: path.basename(opts.envFlag),
+                envPath: opts.envFlag,
+                examplePath: opts.exampleFlag,
+            },
+        ], {
+            checkValues: opts.checkValues,
+            cwd: opts.cwd,
+            allowDuplicates: opts.allowDuplicates,
+        });
+        process.exit(exitWithError ? 1 : 0);
+    }
+    const d = discoverEnvFiles({
+        cwd: opts.cwd,
+        envFlag: opts.envFlag,
+        exampleFlag: opts.exampleFlag,
+    });
+    const res = await ensureFilesOrPrompt({
+        cwd: d.cwd,
+        primaryEnv: d.primaryEnv,
+        primaryExample: d.primaryExample,
+        alreadyWarnedMissingEnv: d.alreadyWarnedMissingEnv,
+        isYesMode: opts.isYesMode,
+        isCiMode: opts.isCiMode,
+    });
+    if (res.shouldExit)
+        process.exit(res.exitCode);
+    // compare all pairs
+    const pairs = pairWithExample(d);
+    const { exitWithError } = await compareMany(pairs, {
+        checkValues: opts.checkValues,
+        cwd: opts.cwd,
+        allowDuplicates: opts.allowDuplicates,
+    });
+    process.exit(exitWithError ? 1 : 0);
+}

package/dist/src/commands/compare.d.ts

@@ -0,0 +1,11 @@
+export declare function compareMany(pairs: Array<{
+    envName: string;
+    envPath: string;
+    examplePath: string;
+}>, opts: {
+    checkValues: boolean;
+    cwd: string;
+    allowDuplicates?: boolean;
+}): Promise<{
+    exitWithError: boolean;
+}>;

package/dist/src/commands/compare.js

@@ -0,0 +1,72 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { parseEnvFile } from '../lib/parseEnv.js';
+import { diffEnv } from '../lib/diffEnv.js';
+import { warnIfEnvNotIgnored } from '../services/git.js';
+import { findDuplicateKeys } from '../services/duplicates.js';
+export async function compareMany(pairs, opts) {
+    let exitWithError = false;
+    for (const { envName, envPath, examplePath } of pairs) {
+        if (!fs.existsSync(envPath) || !fs.existsSync(examplePath)) {
+            console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${path.basename(examplePath)}...`));
+            console.log(chalk.yellow('  ⚠️  Skipping: missing matching example file.'));
+            console.log();
+            continue;
+        }
+        console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${path.basename(examplePath)}...`));
+        warnIfEnvNotIgnored({
+            cwd: opts.cwd,
+            envFile: envName,
+            log: (msg) => console.log(msg.replace(/^/gm, '  ')),
+        });
+        if (!opts.allowDuplicates) {
+            const dupsEnv = findDuplicateKeys(envPath);
+            if (dupsEnv.length > 0) {
+                console.log(chalk.yellow(`  ⚠️  Duplicate keys in ${envName} (last occurrence wins):`));
+                dupsEnv.forEach(({ key, count }) => console.log(chalk.yellow(`      - ${key} (${count} occurrences)`)));
+            }
+            const exName = path.basename(examplePath);
+            const dupsEx = findDuplicateKeys(examplePath);
+            if (dupsEx.length > 0) {
+                console.log(chalk.yellow(`  ⚠️  Duplicate keys in ${exName} (last occurrence wins):`));
+                dupsEx.forEach(({ key, count }) => console.log(chalk.yellow(`      - ${key} (${count} occurrences)`)));
+            }
+        }
+        const current = parseEnvFile(envPath);
+        const example = parseEnvFile(examplePath);
+        const diff = diffEnv(current, example, opts.checkValues);
+        const emptyKeys = Object.entries(current)
+            .filter(([, v]) => (v ?? '').trim() === '')
+            .map(([k]) => k);
+        if (diff.missing.length === 0 &&
+            diff.extra.length === 0 &&
+            emptyKeys.length === 0 &&
+            diff.valueMismatches.length === 0) {
+            console.log(chalk.green('  ✅ All keys match.'));
+            console.log();
+            continue;
+        }
+        if (diff.missing.length > 0) {
+            exitWithError = true;
+            console.log(chalk.red('  ❌ Missing keys:'));
+            diff.missing.forEach((key) => console.log(chalk.red(`      - ${key}`)));
+        }
+        if (diff.extra.length > 0) {
+            console.log(chalk.yellow('  ⚠️  Extra keys (not in example):'));
+            diff.extra.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+        }
+        if (emptyKeys.length > 0) {
+            console.log(chalk.yellow('  ⚠️  Empty values:'));
+            emptyKeys.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+        }
+        if (opts.checkValues && diff.valueMismatches.length > 0) {
+            console.log(chalk.yellow('  ⚠️  Value mismatches:'));
+            diff.valueMismatches.forEach(({ key, expected, actual }) => {
+                console.log(chalk.yellow(`      - ${key}: expected '${expected}', but got '${actual}'`));
+            });
+        }
+        console.log();
+    }
+    return { exitWithError };
+}

package/dist/src/commands/init.d.ts

@@ -0,0 +1,12 @@
+export declare function ensureFilesOrPrompt(args: {
+    cwd: string;
+    primaryEnv: string;
+    primaryExample: string;
+    alreadyWarnedMissingEnv: boolean;
+    isYesMode: boolean;
+    isCiMode: boolean;
+}): Promise<{
+    didCreate: boolean;
+    shouldExit: boolean;
+    exitCode: number;
+}>;

package/dist/src/commands/init.js

@@ -0,0 +1,66 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { confirmYesNo } from '../ui/prompts.js';
+import { warnIfEnvNotIgnored } from '../services/git.js';
+export async function ensureFilesOrPrompt(args) {
+    const { cwd, primaryEnv, primaryExample, alreadyWarnedMissingEnv, isYesMode, isCiMode, } = args;
+    const envPath = path.resolve(cwd, primaryEnv);
+    const examplePath = path.resolve(cwd, primaryExample);
+    const envExists = fs.existsSync(envPath);
+    const exampleExists = fs.existsSync(examplePath);
+    // Case 1: no .env and no .env.example
+    if (!envExists && !exampleExists) {
+        const hasAnyEnv = fs.readdirSync(cwd).some((f) => f.startsWith('.env'));
+        if (!hasAnyEnv) {
+            console.log(chalk.yellow('⚠️  No .env* or .env.example file found. Skipping comparison.'));
+            return { didCreate: false, shouldExit: true, exitCode: 0 };
+        }
+    }
+    // Case 2: missing .env but has .env.example
+    if (!envExists && exampleExists) {
+        if (!alreadyWarnedMissingEnv) {
+            console.log(chalk.yellow(`📄 ${path.basename(envPath)} file not found.`));
+        }
+        let createEnv = isYesMode
+            ? true
+            : isCiMode
+                ? false
+                : await confirmYesNo(`❓ Do you want to create a new ${path.basename(envPath)} file from ${path.basename(examplePath)}?`, { isCiMode, isYesMode });
+        if (!createEnv) {
+            console.log(chalk.gray('🚫 Skipping .env creation.'));
+            return { didCreate: false, shouldExit: true, exitCode: 0 };
+        }
+        const exampleContent = fs.readFileSync(examplePath, 'utf-8');
+        fs.writeFileSync(envPath, exampleContent);
+        console.log(chalk.green(`✅ ${path.basename(envPath)} file created successfully from ${path.basename(examplePath)}.\n`));
+        warnIfEnvNotIgnored({ envFile: path.basename(envPath) });
+    }
+    // Case 3: has .env but is missing .env.example
+    if (envExists && !exampleExists) {
+        console.log(chalk.yellow(`📄 ${path.basename(examplePath)} file not found.`));
+        let createExample = isYesMode
+            ? true
+            : isCiMode
+                ? false
+                : await confirmYesNo(`❓ Do you want to create a new ${path.basename(examplePath)} file from ${path.basename(envPath)}?`, { isCiMode, isYesMode });
+        if (!createExample) {
+            console.log(chalk.gray('🚫 Skipping .env.example creation.'));
+            return { didCreate: false, shouldExit: true, exitCode: 0 };
+        }
+        const envContent = fs
+            .readFileSync(envPath, 'utf-8')
+            .split('\n')
+            .map((line) => {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                return trimmed;
+            const [key] = trimmed.split('=');
+            return `${key}=`;
+        })
+            .join('\n');
+        fs.writeFileSync(examplePath, envContent);
+        console.log(chalk.green(`✅ ${path.basename(examplePath)} file created successfully from ${path.basename(envPath)}.\n`));
+    }
+    return { didCreate: true, shouldExit: false, exitCode: 0 };
+}

package/dist/src/config/options.d.ts

@@ -0,0 +1,19 @@
+export type Options = {
+    checkValues: boolean;
+    isCiMode: boolean;
+    isYesMode: boolean;
+    allowDuplicates: boolean;
+    envFlag: string | null;
+    exampleFlag: string | null;
+    cwd: string;
+};
+type RawOptions = {
+    checkValues?: boolean;
+    ci?: boolean;
+    yes?: boolean;
+    allowDuplicates?: boolean;
+    env?: string;
+    example?: string;
+};
+export declare function normalizeOptions(raw: RawOptions): Options;
+export {};

package/dist/src/config/options.js

@@ -0,0 +1,23 @@
+import chalk from 'chalk';
+import path from 'path';
+export function normalizeOptions(raw) {
+    const checkValues = raw.checkValues ?? false;
+    const isCiMode = Boolean(raw.ci);
+    const isYesMode = Boolean(raw.yes);
+    const allowDuplicates = Boolean(raw.allowDuplicates);
+    if (isCiMode && isYesMode) {
+        console.log(chalk.yellow('⚠️  Both --ci and --yes provided; proceeding with --yes.'));
+    }
+    const cwd = process.cwd();
+    const envFlag = typeof raw.env === 'string' ? path.resolve(cwd, raw.env) : null;
+    const exampleFlag = typeof raw.example === 'string' ? path.resolve(cwd, raw.example) : null;
+    return {
+        checkValues,
+        isCiMode,
+        isYesMode,
+        allowDuplicates,
+        envFlag,
+        exampleFlag,
+        cwd,
+    };
+}

package/dist/src/core/duplicates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Scan a .env-like file for duplicate keys.
+ * - Ignores empty lines and comments (#...)
+ * - Splits on first '='
+ * - Trims the key
+ * - Returns keys that appear more than once, with counts
+ */
+export declare function findDuplicateKeys(filePath: string): Array<{
+    key: string;
+    count: number;
+}>;

package/dist/src/core/duplicates.js

@@ -0,0 +1,33 @@
+import fs from 'fs';
+/**
+ * Scan a .env-like file for duplicate keys.
+ * - Ignores empty lines and comments (#...)
+ * - Splits on first '='
+ * - Trims the key
+ * - Returns keys that appear more than once, with counts
+ */
+export function findDuplicateKeys(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const lines = raw.split('\n');
+    const counts = new Map();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            continue; // no '=' or empty key
+        const key = trimmed.slice(0, eq).trim();
+        if (!key)
+            continue;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const duplicates = [];
+    for (const [key, count] of counts) {
+        if (count > 1)
+            duplicates.push({ key, count });
+    }
+    return duplicates;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { parseEnvFile } from './lib/parseEnv.js';
+export { diffEnv, DiffResult } from './lib/diffEnv.js';

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { parseEnvFile } from './lib/parseEnv.js';
+export { diffEnv } from './lib/diffEnv.js';

package/dist/src/lib/diffEnv.d.ts

@@ -0,0 +1,18 @@
+export type DiffResult = {
+    missing: string[];
+    extra: string[];
+    valueMismatches: {
+        key: string;
+        expected: string;
+        actual: string;
+    }[];
+};
+/**
+ * Compares two .env files and returns their differences.
+ *
+ * @param current - An object representing the current `.env` file (key-value pairs).
+ * @param example - An object representing the `.env.example` file (key-value pairs).
+ * @param checkValues - If true, compare values when the example has a non-empty value.
+ * @returns A `DiffResult` object containing missing, extra, and mismatched keys.
+ */
+export declare function diffEnv(current: Record<string, string>, example: Record<string, string>, checkValues?: boolean): DiffResult;

package/dist/src/lib/diffEnv.js

@@ -0,0 +1,29 @@
+/**
+ * Compares two .env files and returns their differences.
+ *
+ * @param current - An object representing the current `.env` file (key-value pairs).
+ * @param example - An object representing the `.env.example` file (key-value pairs).
+ * @param checkValues - If true, compare values when the example has a non-empty value.
+ * @returns A `DiffResult` object containing missing, extra, and mismatched keys.
+ */
+export function diffEnv(current, example, checkValues = false) {
+    const currentKeys = Object.keys(current);
+    const exampleKeys = Object.keys(example);
+    const missing = exampleKeys.filter((key) => !currentKeys.includes(key));
+    const extra = currentKeys.filter((key) => !exampleKeys.includes(key));
+    let valueMismatches = [];
+    if (checkValues) {
+        valueMismatches = exampleKeys
+            .filter((key) => {
+            return (currentKeys.includes(key) &&
+                example[key].trim() !== '' &&
+                current[key] !== example[key]);
+        })
+            .map((key) => ({
+            key,
+            expected: example[key],
+            actual: current[key],
+        }));
+    }
+    return { missing, extra, valueMismatches };
+}

package/dist/src/lib/parseEnv.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parses a `.env` file and returns an object with key-value pairs.
+ *
+ * @param path - The file path to the `.env` file.
+ * @returns A record object representing parsed environment variables.
+ *
+ * Lines that are empty or start with `#` (comments) are ignored.
+ * Multi-line or quoted values are not supported.
+ */
+export declare function parseEnvFile(path: string): Record<string, string>;

package/dist/src/lib/parseEnv.js

@@ -0,0 +1,25 @@
+import fs from 'fs';
+/**
+ * Parses a `.env` file and returns an object with key-value pairs.
+ *
+ * @param path - The file path to the `.env` file.
+ * @returns A record object representing parsed environment variables.
+ *
+ * Lines that are empty or start with `#` (comments) are ignored.
+ * Multi-line or quoted values are not supported.
+ */
+export function parseEnvFile(path) {
+    const content = fs.readFileSync(path, 'utf-8');
+    const lines = content.split('\n');
+    const result = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const [key, ...rest] = trimmed.split('=');
+        if (!key)
+            continue;
+        result[key.trim()] = rest.join('=').trim();
+    }
+    return result;
+}

package/dist/src/services/duplicates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Scan a .env-like file for duplicate keys.
+ * - Ignores empty lines and comments (#...)
+ * - Splits on first '='
+ * - Trims the key
+ * - Returns keys that appear more than once, with counts
+ */
+export declare function findDuplicateKeys(filePath: string): Array<{
+    key: string;
+    count: number;
+}>;

package/dist/src/services/duplicates.js

@@ -0,0 +1,33 @@
+import fs from 'fs';
+/**
+ * Scan a .env-like file for duplicate keys.
+ * - Ignores empty lines and comments (#...)
+ * - Splits on first '='
+ * - Trims the key
+ * - Returns keys that appear more than once, with counts
+ */
+export function findDuplicateKeys(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const lines = raw.split('\n');
+    const counts = new Map();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            continue; // no '=' or empty key
+        const key = trimmed.slice(0, eq).trim();
+        if (!key)
+            continue;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const duplicates = [];
+    for (const [key, count] of counts) {
+        if (count > 1)
+            duplicates.push({ key, count });
+    }
+    return duplicates;
+}

package/dist/src/services/envDiscovery.d.ts

@@ -0,0 +1,14 @@
+export type Discovery = {
+    cwd: string;
+    envFiles: string[];
+    primaryEnv: string;
+    primaryExample: string;
+    envFlag: string | null;
+    exampleFlag: string | null;
+    alreadyWarnedMissingEnv: boolean;
+};
+export declare function discoverEnvFiles({ cwd, envFlag, exampleFlag, }: {
+    cwd: string;
+    envFlag: string | null;
+    exampleFlag: string | null;
+}): Discovery;

package/dist/src/services/envDiscovery.js

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import path from 'path';
+export function discoverEnvFiles({ cwd, envFlag, exampleFlag, }) {
+    // Find all .env* files in the current directory except .env.example*
+    const envFiles = fs
+        .readdirSync(cwd)
+        .filter((f) => f.startsWith('.env') && !f.startsWith('.env.example'))
+        .sort((a, b) => a === '.env' ? -1 : b === '.env' ? 1 : a.localeCompare(b));
+    let primaryEnv = envFiles.includes('.env') ? '.env' : envFiles[0] || '.env';
+    let primaryExample = '.env.example';
+    let alreadyWarnedMissingEnv = false;
+    // --env (without --example): force primaryEnv and try to find a matching example name via suffix
+    if (envFlag && !exampleFlag) {
+        const envNameFromFlag = path.basename(envFlag);
+        primaryEnv = envNameFromFlag;
+        // If the specified --env actually exists, make sure it's in the list (first) without duplicates
+        if (fs.existsSync(envFlag)) {
+            const set = new Set([envNameFromFlag, ...envFiles]);
+            envFiles.length = 0;
+            envFiles.push(...Array.from(set));
+        }
+        // try to find a matching example name based on the suffix
+        const suffix = envNameFromFlag === '.env' ? '' : envNameFromFlag.replace('.env', '');
+        const potentialExample = suffix ? `.env.example${suffix}` : '.env.example';
+        if (fs.existsSync(path.resolve(cwd, potentialExample))) {
+            primaryExample = potentialExample;
+        }
+    }
+    // --example (without --env): force primaryExample and try to find a matching env name via suffix
+    if (exampleFlag && !envFlag) {
+        const exampleNameFromFlag = path.basename(exampleFlag);
+        primaryExample = exampleNameFromFlag;
+        if (exampleNameFromFlag.startsWith('.env.example')) {
+            const suffix = exampleNameFromFlag.slice('.env.example'.length);
+            const matchedEnv = suffix ? `.env${suffix}` : '.env';
+            if (fs.existsSync(path.resolve(cwd, matchedEnv))) {
+                primaryEnv = matchedEnv;
+                envFiles.length = 0;
+                envFiles.push(matchedEnv);
+            }
+            else {
+                alreadyWarnedMissingEnv = true;
+            }
+        }
+        else {
+            //  If the example file is not a standard .env.example, we just use it as is
+            if (envFiles.length === 0)
+                envFiles.push(primaryEnv);
+        }
+    }
+    return {
+        cwd,
+        envFiles,
+        primaryEnv,
+        primaryExample,
+        envFlag,
+        exampleFlag,
+        alreadyWarnedMissingEnv,
+    };
+}

package/dist/src/services/envPairing.d.ts

@@ -0,0 +1,6 @@
+import type { Discovery } from './envDiscovery.js';
+export declare function pairWithExample(d: Discovery): Array<{
+    envName: string;
+    envPath: string;
+    examplePath: string;
+}>;

package/dist/src/services/envPairing.js

@@ -0,0 +1,27 @@
+import fs from 'fs';
+import path from 'path';
+export function pairWithExample(d) {
+    const pairs = [];
+    const list = d.envFiles.length > 0 ? d.envFiles : [d.primaryEnv];
+    for (const envName of list) {
+        if (d.exampleFlag && !d.envFlag) {
+            const envAbs = path.resolve(d.cwd, envName);
+            if (envAbs === path.resolve(d.cwd, d.primaryExample))
+                continue;
+        }
+        const suffix = envName === '.env' ? '' : envName.replace('.env', '');
+        const exampleName = suffix ? `.env.example${suffix}` : d.primaryExample;
+        const envPathCurrent = path.resolve(d.cwd, envName);
+        const examplePathCurrent = d.exampleFlag && !d.envFlag
+            ? path.resolve(d.cwd, d.primaryExample)
+            : fs.existsSync(path.resolve(d.cwd, exampleName))
+                ? path.resolve(d.cwd, exampleName)
+                : path.resolve(d.cwd, d.primaryExample);
+        pairs.push({
+            envName,
+            envPath: envPathCurrent,
+            examplePath: examplePathCurrent,
+        });
+    }
+    return pairs;
+}

package/dist/src/services/git.d.ts

@@ -0,0 +1,23 @@
+export type GitignoreCheckOptions = {
+    /** Project root directory (default: process.cwd()) */
+    cwd?: string;
+    /** Name of the env file (default: ".env") */
+    envFile?: string;
+    /** Custom logger (default: console.log) */
+    log?: (msg: string) => void;
+};
+/** Are we in a git repo? (checks for .git directory in cwd) */
+export declare function isGitRepo(cwd?: string): boolean;
+/**
+ * Returns:
+ *  - true  → .env-matching patterns are found in .gitignore
+ *  - false → .env-matching patterns are NOT found (or a negation exists)
+ *  - null  → no .gitignore exists
+ */
+export declare function isEnvIgnoredByGit(options?: GitignoreCheckOptions): boolean | null;
+/**
+ * Logs a friendly warning if .env is not ignored by Git.
+ * - Does not hard fail: non-blocking DX.
+ * - Skips if not in a git repo or if .env does not exist.
+ */
+export declare function warnIfEnvNotIgnored(options?: GitignoreCheckOptions): void;

package/dist/src/services/git.js

@@ -0,0 +1,73 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+/** Are we in a git repo? (checks for .git directory in cwd) */
+export function isGitRepo(cwd = process.cwd()) {
+    return fs.existsSync(path.resolve(cwd, '.git'));
+}
+/**
+ * Returns:
+ *  - true  → .env-matching patterns are found in .gitignore
+ *  - false → .env-matching patterns are NOT found (or a negation exists)
+ *  - null  → no .gitignore exists
+ */
+export function isEnvIgnoredByGit(options = {}) {
+    const { cwd = process.cwd(), envFile = '.env' } = options;
+    const gitignorePath = path.resolve(cwd, '.gitignore');
+    if (!fs.existsSync(gitignorePath))
+        return null;
+    const raw = fs.readFileSync(gitignorePath, 'utf8');
+    const lines = raw
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('#'));
+    // If there is a negation (!pattern) that matches our candidates, we consider it as "not ignored"
+    if (lines.some((l) => l.startsWith('!') && matchesCandidate(l.slice(1), envFile))) {
+        return false;
+    }
+    const candidates = getCandidatePatterns(envFile);
+    return lines.some((line) => candidates.has(line));
+}
+/** Our simple candidate patterns that typically cover env files in the root and subfolders */
+function getCandidatePatterns(envFile = '.env') {
+    const base = envFile; // ".env"
+    const star = `${base}*`; // ".env*"
+    const dotStar = `${base}.*`; // ".env.*"
+    return new Set([
+        base,
+        `/${base}`,
+        `**/${base}`,
+        star,
+        `/${star}`,
+        `**/${star}`,
+        dotStar,
+        `/${dotStar}`,
+        `**/${dotStar}`,
+    ]);
+}
+// Matches only against our own candidate patterns (intentionally simple)
+function matchesCandidate(pattern, envFile) {
+    return getCandidatePatterns(envFile).has(pattern);
+}
+/**
+ * Logs a friendly warning if .env is not ignored by Git.
+ * - Does not hard fail: non-blocking DX.
+ * - Skips if not in a git repo or if .env does not exist.
+ */
+export function warnIfEnvNotIgnored(options = {}) {
+    const { cwd = process.cwd(), envFile = '.env', log = console.log } = options;
+    const envPath = path.resolve(cwd, envFile);
+    if (!fs.existsSync(envPath))
+        return; // No .env file → nothing to warn about
+    if (!isGitRepo(cwd))
+        return; // Not a git repo → skip
+    const gitignorePath = path.resolve(cwd, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        log(chalk.yellow(`⚠️  No .gitignore found – your ${envFile} may be committed.\n   Add:\n   ${envFile}\n   ${envFile}.*\n`));
+        return;
+    }
+    const ignored = isEnvIgnoredByGit({ cwd, envFile });
+    if (ignored === false || ignored === null) {
+        log(chalk.yellow(`⚠️  ${envFile} is not ignored by Git (.gitignore).\n   Consider adding:\n   ${envFile}\n   ${envFile}.*\n`));
+    }
+}

package/dist/src/ui/prompts.d.ts

@@ -0,0 +1,4 @@
+export declare function confirmYesNo(message: string, { isCiMode, isYesMode }: {
+    isCiMode: boolean;
+    isYesMode: boolean;
+}): Promise<boolean>;

package/dist/src/ui/prompts.js

@@ -0,0 +1,18 @@
+import prompts from 'prompts';
+export async function confirmYesNo(message, { isCiMode, isYesMode }) {
+    if (isYesMode)
+        return true;
+    if (isCiMode)
+        return false;
+    const res = await prompts({
+        type: 'select',
+        name: 'ok',
+        message,
+        choices: [
+            { title: 'Yes', value: true },
+            { title: 'No', value: false },
+        ],
+        initial: 0,
+    });
+    return Boolean(res.ok);
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dotenv-diff",
-  "version": "1.5.0",
+  "version": "1.6.2",
   "type": "module",
   "description": "A small CLI and library to find differences between .env and .env.example files.",
   "bin": {
-    "dotenv-diff": "dist/cli.js"
+    "dotenv-diff": "dist/bin/dotenv-diff.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
     "test": "vitest",
     "lint": "eslint ./src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\" \"src/*.ts\"",
-    "start": "node dist/cli.js"
+    "start": "node dist/bin/dotenv-diff.js"
   },
   "author": "Chrilleweb",
   "license": "MIT",