env-drift-check 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnvWise Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# env-drift-check
+
+[![npm version](https://img.shields.io/npm/v/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)
+
+> **Stop copy-pasting `.env` files.** Onboard developers in seconds with interactive prompts and smart validation.
+
+**env-drift-check** is a powerful CLI tool that ensures your environment variables are always in sync with your code. Unlike other tools that just fail when keys are missing, we help you **fix them interactively**.
+
+##  Why use this?
+
+| Feature | Other Tools | **env-drift-check** |
+| :--- | :--- | :--- |
+| **Missing Keys** |  Crash & Exit | 🛠 **Interactive Setup Wizard** |
+| **Validation** | Basic Existence Check | **Rich Types** (Email, URL, Regex) |
+| **Onboarding** | Manual (Read docs → Copy → Paste) | **Automated** (Run command → Fill prompts) |
+
+##  Features
+
+- **Interactive Mode**: Automatically prompts users to fill in missing variables.
+- **Smart Validation**: enforce types like `email`, `url`, `number`, `boolean`, and `regex`.
+- **Drift Detection**: Compares your `.env` against `.env.example`.
+- **Zero Config**: Works out of the box, or add `envwise.config.json` for superpowers.
+
+## Installation
+
+```bash
+npm install -g env-drift-check
+# OR
+npx env-drift-check
+```
+
+## 🛠 Usage
+
+### 1. Basic Check
+Check if your `.env` is missing any keys defined in `.env.example`:
+
+```bash
+npx env-drift-check
+```
+
+### 2. Interactive Setup (Recommended)
+Automatically prompt the user to fill in missing keys:
+
+```bash
+npx env-drift-check --interactive
+# OR
+npx env-drift-check -i
+```
+
+### 3. CI/CD Mode (Strict)
+Fail the build if drift is detected (great for pipelines):
+
+```bash
+npx env-drift-check --strict
+```
+
+## Configuration
+
+Create a `envwise.config.json` to define validation rules.
+
+```json
+{
+  "baseEnv": ".env.example",
+  "rules": {
+    "PORT": {
+      "type": "number",
+      "min": 3000,
+      "max": 9000
+    },
+    "DATABASE_URL": {
+      "type": "url",
+      "description": "Connection string for MongoDB"
+    },
+    "ADMIN_EMAIL": {
+      "type": "email",
+      "required": true
+    },
+    "FEATURE_FLAG": {
+      "type": "boolean",
+      "mustBeFalseIn": "production"
+    },
+    "API_KEY": {
+      "type": "regex",
+      "regex": "^[A-Z0-9]{32}$",
+      "description": "32-character alphanumeric key"
+    }
+  }
+}
+```
+
+### Validation Types
+
+| Type | Options | Description |
+| :--- | :--- | :--- |
+| `string` | `min`, `max` | String length validation |
+| `number` | `min`, `max` | Numeric range validation |
+| `boolean` | `mustBeFalseIn` | True/False check |
+| `enum` | `values` (array) | Must be one of the allowlist |
+| `email` | - | Valid email format |
+| `url` | - | Valid URL format |
+| `regex` | `regex` (string) | Custom pattern matching |
+
+## Contributing
+
+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
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const envParser_1 = require("./engine/envParser");
+const driftChecker_1 = require("./engine/driftChecker");
+const consoleReporter_1 = require("./reporter/consoleReporter");
+const interactive_1 = require("./engine/interactive");
+const loadConfig_1 = require("./config/loadConfig");
+const args = process.argv.slice(2);
+const strict = args.includes("--strict");
+const interactive = args.includes("--interactive") || args.includes("-i");
+const checkAll = args.includes("--all");
+const positionalArgs = args.filter(a => !a.startsWith("-"));
+const config = (0, loadConfig_1.loadConfig)();
+const basePath = path_1.default.resolve(config.baseEnv || ".env.example");
+if (!fs_1.default.existsSync(basePath)) {
+    console.error(`Reference file missing: ${basePath}`);
+    process.exit(1);
+}
+const baseEnv = (0, envParser_1.parseEnv)(basePath);
+async function runForFile(targetFile) {
+    const targetPath = path_1.default.resolve(targetFile);
+    if (!fs_1.default.existsSync(targetPath)) {
+        console.error(`File missing: ${targetFile}`);
+        return false;
+    }
+    console.log(`\n Checking ${path_1.default.basename(targetPath)} against ${path_1.default.basename(basePath)}...`);
+    const targetEnv = (0, envParser_1.parseEnv)(targetPath);
+    let result = (0, driftChecker_1.checkDrift)(baseEnv, targetEnv, config);
+    if (result.missing.length > 0 && interactive) {
+        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");
+        fs_1.default.writeFileSync(targetPath, newContent);
+        console.log(`\n ✅ Updated ${path_1.default.basename(targetPath)} with new values.`);
+        // Re-check drift
+        result = (0, driftChecker_1.checkDrift)(baseEnv, updatedEnv, config);
+    }
+    (0, consoleReporter_1.report)(result);
+    const hasIssues = result.missing.length || result.mismatches.length || result.errors.length;
+    return !hasIssues;
+}
+async function main() {
+    let allFiles = [];
+    if (checkAll) {
+        allFiles = fs_1.default.readdirSync(process.cwd())
+            .filter(f => f.startsWith(".env") && f !== path_1.default.basename(basePath));
+    }
+    else {
+        allFiles = [positionalArgs[0] || ".env"];
+    }
+    let overallSuccess = true;
+    for (const file of allFiles) {
+        const success = await runForFile(file);
+        if (!success)
+            overallSuccess = false;
+    }
+    if (strict && !overallSuccess) {
+        console.error("\n Strict mode failed for one or more files");
+        process.exit(1);
+    }
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/config/loadConfig.d.ts

@@ -0,0 +1,2 @@
+import { Config } from "../types";
+export declare function loadConfig(): Config;

package/dist/config/loadConfig.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DEFAULT_CONFIG = {
+    baseEnv: ".env.example",
+    rules: {}
+};
+function loadConfig() {
+    const configPath = path_1.default.resolve("envwise.config.json");
+    if (!fs_1.default.existsSync(configPath)) {
+        return DEFAULT_CONFIG;
+    }
+    const raw = fs_1.default.readFileSync(configPath, "utf-8");
+    const userConfig = JSON.parse(raw);
+    return {
+        ...DEFAULT_CONFIG,
+        ...userConfig
+    };
+}

package/dist/engine/driftChecker.d.ts

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

package/dist/engine/driftChecker.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDrift = checkDrift;
+const validator_1 = require("./validator");
+function checkDrift(base, target, config) {
+    const result = {
+        missing: [],
+        extra: [],
+        errors: [],
+        warnings: [],
+        mismatches: []
+    };
+    // Missing & extra keys
+    for (const key of Object.keys(base)) {
+        if (!(key in target))
+            result.missing.push(key);
+    }
+    for (const key of Object.keys(target)) {
+        if (!(key in base))
+            result.extra.push(key);
+    }
+    // Value mismatch detection
+    for (const key of Object.keys(base)) {
+        if (key in target && base[key] !== target[key]) {
+            result.mismatches.push({
+                key,
+                expected: base[key],
+                actual: target[key]
+            });
+        }
+    }
+    // Rule-based validation
+    const rules = config.rules || {};
+    for (const [key, rule] of Object.entries(rules)) {
+        if (target[key]) {
+            const err = (0, validator_1.validateValue)(key, target[key], rule, target["NODE_ENV"]);
+            if (err)
+                result.errors.push({ key, message: err });
+        }
+    }
+    return result;
+}

package/dist/engine/envParser.d.ts

@@ -0,0 +1 @@
+export declare function parseEnv(path: string): Record<string, string>;

package/dist/engine/envParser.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnv = parseEnv;
+const fs_1 = __importDefault(require("fs"));
+const dotenv_1 = __importDefault(require("dotenv"));
+function parseEnv(path) {
+    if (!fs_1.default.existsSync(path)) {
+        throw new Error(`Env file not found: ${path}`);
+    }
+    const content = fs_1.default.readFileSync(path);
+    return dotenv_1.default.parse(content);
+}

package/dist/engine/fixer.d.ts

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1,19 @@
+"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;
+}

package/dist/engine/interactive.d.ts

@@ -0,0 +1,2 @@
+import { Config } from "../types";
+export declare function interactiveSetup(missingKeys: string[], baseEnv: Record<string, string>, config: Config): Promise<Record<string, string>>;

package/dist/engine/interactive.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interactiveSetup = interactiveSetup;
+const prompts_1 = __importDefault(require("prompts"));
+const validator_1 = require("./validator");
+async function interactiveSetup(missingKeys, baseEnv, config) {
+    const newValues = {};
+    console.log("\n🛠  Interactive Setup: Let's fill in the missing variables.\n");
+    for (const key of missingKeys) {
+        const rule = config.rules?.[key] || { type: "string" };
+        const initial = baseEnv[key] || "";
+        // Determine prompt type
+        let promptType = "text";
+        if (rule.type === "boolean")
+            promptType = "confirm";
+        if (rule.type === "number")
+            promptType = "number";
+        if (key.includes("PASSWORD") || key.includes("SECRET"))
+            promptType = "password";
+        const response = await (0, prompts_1.default)({
+            type: promptType,
+            name: "value",
+            message: `${key}${rule.description ? ` (${rule.description})` : ""}:`,
+            initial: promptType === "confirm" ? initial === "true" : initial,
+            validate: (val) => {
+                const strVal = String(val);
+                const error = (0, validator_1.validateValue)(key, strVal, rule, "local"); // Assuming 'local' context for now
+                return error || true;
+            }
+        });
+        // Handle user cancellation (Ctrl+C)
+        if (response.value === undefined) {
+            console.log("\nSetup cancelled.");
+            process.exit(1);
+        }
+        newValues[key] = String(response.value);
+    }
+    return newValues;
+}

package/dist/engine/validator.d.ts

@@ -0,0 +1,2 @@
+import { Rule } from "../types";
+export declare function validateValue(key: string, value: string, rule: Rule, env: string): string | null;

package/dist/engine/validator.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateValue = validateValue;
+function validateValue(key, value, rule, env) {
+    if (!value && rule.required !== false) {
+        return `${key} is required`;
+    }
+    // Number validation
+    if (rule.type === "number") {
+        const num = Number(value);
+        if (isNaN(num))
+            return `${key} must be a number`;
+        if (rule.min !== undefined && num < rule.min)
+            return `${key} must be at least ${rule.min}`;
+        if (rule.max !== undefined && num > rule.max)
+            return `${key} must be at most ${rule.max}`;
+    }
+    // String length validation
+    if (rule.type === "string") {
+        if (rule.min !== undefined && value.length < rule.min)
+            return `${key} must be at least ${rule.min} chars`;
+        if (rule.max !== undefined && value.length > rule.max)
+            return `${key} must be at most ${rule.max} chars`;
+    }
+    // Enum validation
+    if (rule.type === "enum" && rule.values && !rule.values.includes(value)) {
+        return `${key} must be one of: ${rule.values.join(", ")}`;
+    }
+    // Boolean validation
+    if (rule.type === "boolean") {
+        if (value !== "true" && value !== "false")
+            return `${key} must be true or false`;
+        if (rule.mustBeFalseIn === env && value === "true") {
+            return `${key} must be false in ${env}`;
+        }
+    }
+    // Email validation
+    if (rule.type === "email") {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!emailRegex.test(value))
+            return `${key} must be a valid email`;
+    }
+    // URL validation
+    if (rule.type === "url") {
+        try {
+            new URL(value);
+        }
+        catch {
+            return `${key} must be a valid URL`;
+        }
+    }
+    // Regex validation
+    if (rule.type === "regex" && rule.regex) {
+        const regex = new RegExp(rule.regex);
+        if (!regex.test(value))
+            return `${key} does not match required pattern`;
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./engine/driftChecker";
+export * from "./engine/envParser";
+export * from "./engine/validator";
+export * from "./engine/interactive";
+export * from "./config/loadConfig";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./engine/driftChecker"), exports);
+__exportStar(require("./engine/envParser"), exports);
+__exportStar(require("./engine/validator"), exports);
+__exportStar(require("./engine/interactive"), exports);
+__exportStar(require("./config/loadConfig"), exports);
+__exportStar(require("./types"), exports);

package/dist/reporter/consoleReporter.d.ts

@@ -0,0 +1,2 @@
+import { DriftResult } from "../types";
+export declare function report(result: DriftResult): void;

package/dist/reporter/consoleReporter.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.report = report;
+function report(result) {
+    if (result.missing.length) {
+        console.log("\n Missing Variables:");
+        result.missing.forEach(v => console.log(" -", v));
+    }
+    if (result.extra.length) {
+        console.log("\n Extra Variables:");
+        result.extra.forEach(v => console.log(" -", v));
+    }
+    if (result.errors.length) {
+        console.log("\n Errors:");
+        result.errors.forEach(e => console.log(" -", `${e.key}: ${e.message}`));
+    }
+    if (result.mismatches.length) {
+        console.log("\n Value Mismatches:");
+        result.mismatches.forEach(m => {
+            console.log(` - ${m.key}: expected="${m.expected}" actual="${m.actual}"`);
+            console.log(`   -Run --fix to sync ${m.key}`);
+        });
+    }
+    if (!result.missing.length &&
+        !result.extra.length &&
+        !result.errors.length &&
+        !result.mismatches.length) {
+        console.log("No environment drift detected");
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+export interface Rule {
+    type: "string" | "number" | "boolean" | "enum" | "email" | "url" | "regex";
+    values?: string[];
+    regex?: string;
+    min?: number;
+    max?: number;
+    description?: string;
+    mustBeFalseIn?: string;
+    required?: boolean;
+}
+export interface Config {
+    baseEnv?: string;
+    rules?: Record<string, Rule>;
+}
+export interface ValueMismatch {
+    key: string;
+    expected: string;
+    actual: string;
+}
+export interface DriftResult {
+    missing: string[];
+    extra: string[];
+    errors: {
+        key: string;
+        message: string;
+    }[];
+    warnings: string[];
+    mismatches: ValueMismatch[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "env-drift-check",
+  "version": "0.1.0",
+  "description": "Interactive environment variable checker and setup wizard. Sync .env files with validation (Email, URL, Regex) and prompts.",
+  "keywords": [
+    "env",
+    "dotenv",
+    "check-env",
+    "dotenv-safe",
+    "environment-variables",
+    "config",
+    "validation",
+    "interactive",
+    "setup",
+    "onboarding",
+    "drift",
+    "checker"
+  ],
+  "author": "Shashidhar Naik",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/shashi089/env-drift-check/issues"
+  },
+  "homepage": "https://github.com/shashi089/env-drift-check#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "main": "dist/cli.js",
+  "bin": {
+    "env-drift-check": "dist/cli.js"
+  },
+  "types": "dist/cli.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "dotenv": "^16.4.0",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/prompts": "^2.4.9",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}