env-drift-check 0.1.6 → 0.1.9

package/README.md

@@ -1,106 +1,172 @@
-# env-drift-check: Interactive .env Sync & Validation for Teams
+# env-drift-check
 
-[![npm version](https://img.shields.io/npm/v/env-drift-check.svg)](https://www.npmjs.com/package/env-drift-check)
-[![npm downloads](https://img.shields.io/npm/dm/env-drift-check.svg)](https://www.npmjs.com/package/env-drift-check)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<div align="center">
 
-> **Eliminate "It works on my machine" issues.** Synchronize `.env` files across your team with interactive prompts, smart schema validation, and real-time drift detection.
+**A combined environment drift detector + schema validator for multi-environment setups.**
 
-**env-drift-check** is a powerful CLI utility designed to manage environment variables in Node.js applications. It ensures your local `.env` remains in perfect sync with `.env.example`, preventing runtime crashes and streamlining developer onboarding.
+[![npm version](https://img.shields.io/npm/v/env-drift-check.svg?style=flat-square)](https://npmjs.org/package/env-drift-check)
+[![npm downloads](https://img.shields.io/npm/dm/env-drift-check.svg?style=flat-square)](https://npm-stat.com/charts.html?package=env-drift-check)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![CI Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)](#)
 
-![env-drift-check demo](https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check.png)
+*Say goodbye to "It works on my machine" and hello to bulletproof environment variables.*
 
-## 🚀 Why Use env-drift-check?
+[Installation](#installation) • [Features](#features) • [Quick Start](#quick-start) • [Configuration](#configuration) • [Usage](#usage) • [Roadmap](#roadmap)
 
-Manually managing environment variables is error-prone. **env-drift-check** automates the process:
+</div>
 
-| Pain Point | Standard Approach | **env-drift-check** |
-| :--- | :--- | :--- |
-| **Missing Keys** | Application crashes at runtime | **Interactive Setup Wizard** fills them |
-| **Type Safety** | String-only values, no validation | **Rich Validation** (Email, URL, Regex) |
-| **Team Onboarding** | "Copy this file from Slack/Docs" | `npx env-drift-check init` & sync |
-| **Configuration Drift** | Desync between dev/stage/prod | **Real-time Detection** against template |
+<div align="center">
+  <img src="https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check.png" alt="env-drift-check demo" />
+</div>
 
-### Key Features
+---
+
+## 💡 The Problem It Solves
+
+Managing `.env` files across a team of developers or multiple deployment environments (development, staging, production) is notoriously error-prone. 
+
+- **Missing variables** lead to unexpected runtime crashes.
+- **Incorrect data types** (e.g., passing a string `"false"` instead of a proper boolean) cause silent logical bugs.
+- **Onboarding new developers** often involves insecurely sharing `.env` files over Slack, or fighting with an outdated `.env.example`.
+
+**env-drift-check** bridges this gap. It provides real-time drift detection to ensure your local environments match the blueprint, an interactive CLI to fix missing variables instantly, and a robust schema validator to enforce types and formats.
+
+---
+
+## 🏗 Architecture & Flow
+
+```mermaid
+graph TD
+    A[Developers / CI] -->|Run env-drift-check| B(Engine)
+    
+    subgraph Validation Process
+    B -->|1. Parse| C{.env.example}
+    B -->|2. Parse| D[Target .env]
+    B -->|3. Load Rules| E[envwise.config.json]
+    
+    C --> F{Drift Detector}
+    D --> F
+    
+    F -->|Detect Mismatches| G{Compare Keys & Values}
+    E -->|Schema Validation| G
+    end
 
-- **Interactive Mode**: Automatically detects missing keys and prompts you to fill them in directly via the CLI.
-- **Smart Schema Validation**: Enforce strict types including `email`, `url`, `number`, `boolean`, `enum`, and custom `regex`.
-- **Zero Config Setup**: Works out of the box. Add an optional `envwise.config.json` for advanced rules.
-- **CI/CD Ready**: Use `--strict` mode in your build pipeline to prevent deployments with missing variables.
+    G -->|Interactive Mode| H[Prompt UI: Auto-fix]
+    H -->|Update| D
+    
+    G -->|Strict Mode| I[CI/CD Exit Code 1]
+    G -->|Report| J[Terminal Output]
+```
+
+---
+
+## 🚀 Features
+
+- 🔍 **Environment Drift Detection**: Compares your local `.env` against the base `.env.example` to find missing or extra keys.
+- 🛡️ **Extensive Schema Validation**: Enforce `string`, `number`, `boolean`, `enum`, `email`, `url`, and custom `regex` validations via `envwise.config.json`.
+- 🪄 **Interactive Auto-fix**: A beautiful CLI wizard that prompts you for missing variables and writes them back to your `.env` file automatically.
+- � **Formatting Preservation**: Inherently preserves your original inline comments, empty lines, bespoke spacing, and absolute key ordering when writing updates to your target `.env` file.
+- �🔄 **Multi-Environment Support**: Validate all `.env*` files in your project with the `--all` flag.
+- 🚦 **CI/CD Ready**: Use `--strict` mode to fail the build if variables are missing or invalid, ensuring safe deployments.
 
-## 📖 Documentation
+### How Does It Compare?
+
+| Feature | `dotenv-safe` | `envalid` | **`env-drift-check`** |
+| :--- | :---: | :---: | :---: |
+| **Missing Keys Detection** | ✅ | ✅ | ✅ |
+| **CLI Interactive Mode** | ❌ | ❌ | ✅ |
+| **Schema Validation (Config)** | ❌ | ✅ (Code) | ✅ (JSON) |
+| **Cross-Env File Check** | ❌ | ❌ | ✅ |
+| **No Code Integration Needed**| ❌ | ❌ | ✅ |
+
+*(env-drift-check works purely as a CLI tooling step, meaning you don't need to change your application's actual code to validate environment variables!)*
+
+---
 
-- [CLI Usage](./docs/CLI-Usage.md) - Detailed flags and command examples.
-- [Configuration](./docs/Configuration.md) - Advanced types and `envwise.config.json` schema.
-- [Programmatic API](./docs/API-Reference.md) - Integrating the validation engine into your code.
+## 📦 Installation
 
-## Installation
+Install `env-drift-check` as a development dependency:
 
 ```bash
-# Install as a dev dependency (Recommended)
 npm install --save-dev env-drift-check
-
-# OR install globally
-npm install -g env-drift-check
 ```
 
-## Usage
+Or run it directly using `npx` without installing:
 
-### 1. Initialize (New Setup)
-Bootstrap your project by creating a configuration and an example environment file.
 ```bash
 npx env-drift-check init
 ```
 
-### 2. Basic Check
-Compare your `.env` against the reference (default: `.env.example`).
+---
+
+## ⚡ Quick Start
+
+### 1. Initialize the Project
+
+Bootstrap your repository with a default configuration and `.env.example`:
+
 ```bash
-npx env-drift-check
-# Specify a custom reference file
-npx env-drift-check --base .env.production
+npx env-drift-check init
 ```
+*Output:*
+```text
+✅ Created envwise.config.json
+✅ Created .env.example
 
-### 3. Interactive Sync (The "Magic" Feature)
-If missing variables are found, launch the interactive wizard to fill them in without leaving your IDE.
-```bash
-npx env-drift-check --interactive
-# OR
-npx env-drift-check -i
+Setup complete! Run 'npx env-drift-check -i' to sync your .env file.
 ```
 
-### 4. CI/CD & Strict Mode
-Fail your build or test suite if environment variables are out of sync.
+### 2. Run an Interactive Check
+
+If you just cloned a repo, check for missing environment variables and fill them in right from the terminal:
+
 ```bash
-npx env-drift-check --strict
+npx env-drift-check -i
 ```
 
+![Interactive update](https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check-i-update.png)
+
+Once completed, your `.env` file is automatically updated!
+
+![Interactive success](https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check-i-final.png)
+
 ---
 
-## 🛠 Advanced Configuration
+## ⚙️ Configuration (`envwise.config.json`)
 
-Define validation rules in `envwise.config.json` to ensure data integrity across environments.
+To unlock the full power of the schema validator, define rules in an `envwise.config.json` file at the root of your project.
+
+### Sample Configuration
 
 ```json
 {
   "baseEnv": ".env.example",
   "rules": {
-    "PORT": {
-      "type": "number",
-      "min": 3000,
-      "max": 9000,
-      "description": "Port the server should listen on"
+    "PORT": { 
+      "type": "number", 
+      "min": 1024, 
+      "max": 65535,
+      "description": "The port the HTTP server binds to"
+    },
+    "NODE_ENV": { 
+      "type": "enum", 
+      "values": ["development", "production", "test", "staging"] 
     },
-    "DATABASE_URL": {
+    "DEBUG_MODE": { 
+      "type": "boolean", 
+      "mustBeFalseIn": "production" 
+    },
+    "DATABASE_URL": { 
       "type": "url",
-      "description": "Connection string for MongoDB/PostgreSQL"
+      "required": true
     },
     "ADMIN_EMAIL": {
-      "type": "email",
-      "required": true
+      "type": "email"
     },
-    "ENVIRONMENT": {
-      "type": "enum",
-      "values": ["development", "production", "test"]
+    "API_KEY": {
+      "type": "regex",
+      "regex": "^sk_(test|live)_[0-9a-zA-Z]{24}$",
+      "description": "Stripe API Key format"
     }
   }
 }
@@ -108,26 +174,104 @@ Define validation rules in `envwise.config.json` to ensure data integrity across
 
 ### Supported Validation Types
 
-| Type | Description | Example Rule |
-| :--- | :--- | :--- |
-| `string` | Length validation | `{ "min": 5, "max": 20 }` |
-| `number` | Range validation | `{ "min": 1, "max": 100 }` |
-| `boolean` | Flag checks | `{ "mustBeFalseIn": ["production"] }` |
-| `enum` | Restricted values | `{ "values": ["v1", "v2"] }` |
-| `email` | Standard email format | `type: "email"` |
-| `url` | Valid URL/URI structure | `type: "url"` |
-| `regex` | Custom pattern matching | `{ "regex": "^sk_live_.*" }` |
+| Type | Options | Description |
+|---|---|---|
+| `string` | `min`, `max` | Enforce string length bounds. |
+| `number` | `min`, `max` | Enforce numeric value limits. |
+| `boolean` | `mustBeFalseIn` | Ensure value is "true" or "false". Can conditionally reject "true" in specific environments (e.g. production safety). |
+| `enum` | `values: []` | Restrict the variable to a specific set of allowed strings. |
+| `email` | - | Validates against a standard email regex. |
+| `url` | - | Validates standard URI formats. |
+| `regex` | `regex` | Custom regular expression validation. |
+
+*(All variables are `required: true` by default unless explicitly specified as `required: false` in their rule).*
+
+---
+
+## 💻 CLI Usage Examples
+
+### Drift Detection Example
+Check the default `.env` file against the default `.env.example`:
+
+```bash
+npx env-drift-check
+```
+*Output Detail:*
+```text
+🚨 1 Mismatched Keys
+PORT: Expected 3000, got 8080
+
+❌ 2 Validation Errors
+DATABASE_URL: DATABASE_URL must be a valid URL
+NODE_ENV: NODE_ENV must be one of: development, production
+```
+
+### Multi-Environment Verification
+Check all `.env.development`, `.env.test`, `.env.production` files in parallel:
+
+```bash
+npx env-drift-check --all
+```
 
-## Contributing
+### CI/CD Pipeline Integration (Strict Mode)
+Run the check in your GitHub Actions, GitLab CI, or pre-commit hook. Using `--strict` ensures the process exits with `code 1` on any error.
 
-We welcome contributions! See the [issues](https://github.com/shashi089/env-drift-check/issues) for planned features or bug reports.
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  validate-env:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      # Assuming you have a .env.test you want to validate
+      - run: npx env-drift-check .env.test --strict
+```
+
+---
+
+## 🌟 Best Practices
+
+1. **Never commit `.env` or `.env.*` files!** Ensure they are in your `.gitignore`.
+2. **Always commit `.env.example`** and `envwise.config.json` as the source of truth for your team.
+3. **Use the Interactive Mode** (`-i`) locally during development and onboarding.
+4. **Use Strict Mode** (`--strict`) in your CI/CD pipeline to catch missing production variables early.
+5. **Add it to your `postinstall` or `prepare` script** in `package.json` to auto-prompt new developers:
+   ```json
+   "scripts": {
+     "prepare": "env-drift-check -i"
+   }
+   ```
+
+---
+
+## 🗺 Roadmap
+
+- [x] Boolean conditional checks (`mustBeFalseIn`)
+- [x] Interactive CLI prompts
+- [x] Multi-file parsing (`--all`)
+- [ ] **JSON Output Mode**: Provide `--format json` for reporting to integrate with other tooling pipelines.
+- [ ] **Secret Scanning**: Add basic entropy checks to prevent weak local passwords from entering production variables.
+- [ ] **Variable Deprecation**: Support marking keys as deprecated to gracefully remove them across teams.
+
+---
+
+## 🤝 Contributing
+
+Contributions are always welcome! 
+
+1. Fork the project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+---
 
-1. Fork the repository.
-2. Create your feature branch (`git checkout -b feature/amazing-feature`).
-3. Commit your changes (`git commit -m 'Add some amazing feature'`).
-4. Push to the branch (`git push origin feature/amazing-feature`).
-5. Open a Pull Request.
+## 📄 License
 
-## License
+Distributed under the MIT License. See `LICENSE` for more information.
 
-MIT © [Shashidhar Naik](https://github.com/shashi089)
+> Built with ❤️ for better Developer Experience by [Shashidhar Naik](https://github.com/shashi089)

package/dist/cli.js

@@ -16,7 +16,7 @@ const program = new commander_1.Command();
 program
     .name("env-drift-check")
     .description("Interactive .env synchronizer and validator")
-    .version("0.1.5");
+    .version("0.1.7");
 program
     .command("check", { isDefault: true })
     .description("Check for environment drift (default command)")
@@ -46,10 +46,57 @@ program
             const newValues = await (0, interactive_1.interactiveSetup)(result.missing, baseEnv, config);
             // Merge new values into targetEnv
             const updatedEnv = { ...targetEnv, ...newValues };
-            // Write back to file
-            const newContent = Object.entries(updatedEnv)
-                .map(([k, v]) => `${k}=${v}`)
-                .join("\n");
+            // Write back to file preserving formatting
+            const rawContent = fs_1.default.readFileSync(targetPath, "utf-8");
+            const lines = rawContent.split(/\r?\n/);
+            const eol = rawContent.includes("\r\n") ? "\r\n" : "\n";
+            const updatedLines = [];
+            const keysToUpdate = { ...newValues };
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith("#")) {
+                    updatedLines.push(line);
+                    continue;
+                }
+                const firstEq = line.indexOf("=");
+                if (firstEq !== -1) {
+                    const key = line.slice(0, firstEq).trim();
+                    if (key in keysToUpdate) {
+                        const prefix = line.slice(0, firstEq + 1);
+                        const rawValue = line.slice(firstEq + 1);
+                        let suffix = "";
+                        let inQuote = false;
+                        let quoteChar = "";
+                        for (let i = 0; i < rawValue.length; i++) {
+                            const c = rawValue[i];
+                            if ((c === '"' || c === "'") && !inQuote) {
+                                inQuote = true;
+                                quoteChar = c;
+                            }
+                            else if (c === quoteChar && inQuote) {
+                                inQuote = false;
+                            }
+                            else if (c === '#' && !inQuote) {
+                                // Keep spacing before the comment if possible
+                                const spaceMatch = rawValue.slice(0, i).match(/\s+$/);
+                                const spaces = spaceMatch ? spaceMatch[0] : " ";
+                                suffix = spaces + rawValue.slice(i);
+                                break;
+                            }
+                        }
+                        updatedLines.push(`${prefix}${keysToUpdate[key]}${suffix}`);
+                        delete keysToUpdate[key];
+                        continue;
+                    }
+                }
+                updatedLines.push(line);
+            }
+            if (Object.keys(keysToUpdate).length > 0) {
+                for (const [k, v] of Object.entries(keysToUpdate)) {
+                    updatedLines.push(`${k}=${v}`);
+                }
+            }
+            const newContent = updatedLines.join(eol);
             fs_1.default.writeFileSync(targetPath, newContent);
             console.log(`\n ✅ Updated ${path_1.default.basename(targetPath)} with new values.`);
             // Re-check drift

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "env-drift-check",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "Interactive .env synchronizer and validator. Detect environment drift, sync missing variables, and enforce schema validation for seamless developer onboarding.",
   "keywords": [
     "env",

package/dist/engine/fixer.d.ts

@@ -1,2 +0,0 @@
-import { DriftResult } from "../types";
-export declare function applyFixes(base: Record<string, string>, target: Record<string, string>, result: DriftResult): Record<string, string>;

package/dist/engine/fixer.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyFixes = applyFixes;
-function applyFixes(base, target, result) {
-    const fixedEnv = { ...target };
-    // Add missing keys
-    for (const key of result.missing) {
-        if (base[key]) {
-            fixedEnv[key] = base[key];
-        }
-    }
-    // Fix mismatched values (base → target)
-    for (const mismatch of result.mismatches) {
-        if (mismatch.expected) {
-            fixedEnv[mismatch.key] = mismatch.expected;
-        }
-    }
-    return fixedEnv;
-}