env-drift-check 0.1.4 → 0.1.6

package/README.md

@@ -1,75 +1,84 @@
-# env-drift-check: Automatic .env Sync & Validation
+# env-drift-check: Interactive .env Sync & Validation for Teams
 
 [![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)
 
-> **Stop copy-pasting `.env` files.** Onboard developers in seconds with interactive prompts, smart schema validation, and drift detection.
+> **Eliminate "It works on my machine" issues.** Synchronize `.env` files across your team with interactive prompts, smart schema validation, and real-time drift detection.
 
-**env-drift-check** is the ultimate CLI tool for managing environment variables in Node.js projects. It ensures your local `.env` file is always in sync with `.env.example`, preventing runtime errors caused by missing keys. Perfect for teams and CI/CD pipelines.
+**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.
 
 ![env-drift-check demo](https://github.com/shashi089/env-drift-check/raw/main/assets/env-drift-check.png)
 
-##  Why use this?
+## 🚀 Why Use env-drift-check?
 
-| Feature | Other Tools | **env-drift-check** |
+Manually managing environment variables is error-prone. **env-drift-check** automates the process:
+
+| Pain Point | Standard Approach | **env-drift-check** |
 | :--- | :--- | :--- |
-| **Missing Keys** | Crash & Exit  |  **Interactive Setup Wizard**  |
-| **Validation** | Basic Existence Check | **Rich Types** (Email, URL, Regex, Number)  |
-| **Onboarding** | Manual (Read docs → Copy → Paste) | **Automated** (Run command → Fill prompts)  |
-| **Drift Detection** | Static | **Real-time** comparison with `.env.example` |
+| **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 |
 
-##  Features
+### Key Features
 
-- **Interactive Mode**: Automatically detects missing keys and prompts you to fill them in via CLI.
-- **Smart Schema Validation**: Enforce types like `email`, `url`, `number`, `boolean`, `enum`, and custom `regex`.
-- **Drift Detection**: Instantly compare your local environment against the team's `.env.example`.
-- **CI/CD Ready**: Use strict mode to fail builds if environment variables are missing or invalid.
-- **Zero Config**: Works out of the box, or add `envwise.config.json` for advanced validation rules.
+- **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.
 
-## Installation
+## 📖 Documentation
 
-Install globally or as a dev dependency:
+- [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
 
 ```bash
-npm install -g env-drift-check
-# OR
+# Install as a dev dependency (Recommended)
 npm install --save-dev env-drift-check
+
+# OR install globally
+npm install -g env-drift-check
 ```
 
 ## Usage
 
-### 1. Basic Check
-Check if your `.env` is missing any keys defined in `.env.example`. This is great for a quick status check.
+### 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`).
 ```bash
 npx env-drift-check
+# Specify a custom reference file
+npx env-drift-check --base .env.production
 ```
 
-### 2. Interactive Setup (Recommended)
-The **interactive mode** is the star feature. If missing keys are found, it launches a wizard to help you fill them in without leaving your terminal.
-
+### 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
 ```
 
-![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)
-
-### 3. CI/CD Mode (Strict)
-Ensure no broken code hits production. Use strict mode in your build pipeline to fail if environment variables are missing.
-
+### 4. CI/CD & Strict Mode
+Fail your build or test suite if environment variables are out of sync.
 ```bash
 npx env-drift-check --strict
 ```
 
-## Configuration
+---
 
-Create a `envwise.config.json` file in your root directory to define validation rules and defaults. This acts as a schema for your environment variables.
+## 🛠 Advanced Configuration
+
+Define validation rules in `envwise.config.json` to ensure data integrity across environments.
 
 ```json
 {
@@ -92,31 +101,26 @@ Create a `envwise.config.json` file in your root directory to define validation
     "ENVIRONMENT": {
       "type": "enum",
       "values": ["development", "production", "test"]
-    },
-    "API_KEY": {
-      "type": "regex",
-      "regex": "^[A-Z0-9]{32}$",
-      "description": "32-character alphanumeric API key"
     }
   }
 }
 ```
 
-### Validation Types
+### Supported Validation Types
 
-| Type | Options | Description |
+| Type | Description | Example Rule |
 | :--- | :--- | :--- |
-| `string` | `min`, `max` | Validate string length. |
-| `number` | `min`, `max` | Validate numeric ranges. |
-| `boolean` | `mustBeFalseIn` | Ensure flags (like debug mode) are off in prod. |
-| `enum` | `values` (array) | Restrict to a set of allowed values. |
-| `email` | - | Validate standard email formats. |
-| `url` | - | Validate URL structure. |
-| `regex` | `regex` (string) | Custom pattern matching for keys, secrets, etc. |
+| `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_.*" }` |
 
 ## Contributing
 
-We welcome contributions! Please follow these steps:
+We welcome contributions! See the [issues](https://github.com/shashi089/env-drift-check/issues) for planned features or bug reports.
 
 1. Fork the repository.
 2. Create your feature branch (`git checkout -b feature/amazing-feature`).
@@ -124,6 +128,6 @@ We welcome contributions! Please follow these steps:
 4. Push to the branch (`git push origin feature/amazing-feature`).
 5. Open a Pull Request.
 
-##  License
+## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT © [Shashidhar Naik](https://github.com/shashi089)

package/dist/cli.js

@@ -6,70 +6,109 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const commander_1 = require("commander");
 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;
+const program = new commander_1.Command();
+program
+    .name("env-drift-check")
+    .description("Interactive .env synchronizer and validator")
+    .version("0.1.5");
+program
+    .command("check", { isDefault: true })
+    .description("Check for environment drift (default command)")
+    .argument("[file]", "Target .env file to check", ".env")
+    .option("-b, --base <reference>", "Reference .env file to check against (e.g., .env.example)")
+    .option("-i, --interactive", "Launch interactive setup wizard for missing keys")
+    .option("-s, --strict", "Fail with non-zero exit code if issues are found")
+    .option("-a, --all", "Check all .env* files in the current directory")
+    .action(async (file, options) => {
+    const config = (0, loadConfig_1.loadConfig)();
+    const basePath = path_1.default.resolve(options.base || config.baseEnv || ".env.example");
+    if (!fs_1.default.existsSync(basePath)) {
+        console.error(`Reference file missing: ${basePath}`);
+        process.exit(1);
     }
-    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);
+    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 && options.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;
     }
-    (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) {
+    if (options.all) {
         allFiles = fs_1.default.readdirSync(process.cwd())
             .filter(f => f.startsWith(".env") && f !== path_1.default.basename(basePath));
     }
     else {
-        allFiles = [positionalArgs[0] || ".env"];
+        allFiles = [file];
     }
     let overallSuccess = true;
-    for (const file of allFiles) {
-        const success = await runForFile(file);
+    for (const f of allFiles) {
+        const success = await runForFile(f);
         if (!success)
             overallSuccess = false;
     }
-    if (strict && !overallSuccess) {
+    if (options.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);
 });
+program
+    .command("init")
+    .description("Initialize a new project with default configuration")
+    .action(() => {
+    const configPath = path_1.default.join(process.cwd(), "envwise.config.json");
+    const exampleEnvPath = path_1.default.join(process.cwd(), ".env.example");
+    if (fs_1.default.existsSync(configPath)) {
+        console.log("ℹ️ envwise.config.json already exists.");
+    }
+    else {
+        const defaultConfig = {
+            baseEnv: ".env.example",
+            rules: {
+                PORT: {
+                    type: "number",
+                    min: 1024,
+                    max: 65535,
+                    description: "Application port"
+                }
+            }
+        };
+        fs_1.default.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+        console.log("✅ Created envwise.config.json");
+    }
+    if (fs_1.default.existsSync(exampleEnvPath)) {
+        console.log("ℹ️ .env.example already exists.");
+    }
+    else {
+        fs_1.default.writeFileSync(exampleEnvPath, "PORT=3000\n");
+        console.log("✅ Created .env.example");
+    }
+    console.log("\nSetup complete! Run 'npx env-drift-check -i' to sync your .env file.");
+});
+program.parse(process.argv);

package/dist/config/loadConfig.d.ts

@@ -1,2 +1,8 @@
 import { Config } from "../types";
+/**
+ * Loads the project configuration from 'envwise.config.json' if it exists.
+ * Falls back to default configuration if no file is found.
+ *
+ * @returns The consolidated configuration object
+ */
 export declare function loadConfig(): Config;

package/dist/config/loadConfig.js

@@ -10,6 +10,12 @@ const DEFAULT_CONFIG = {
     baseEnv: ".env.example",
     rules: {}
 };
+/**
+ * Loads the project configuration from 'envwise.config.json' if it exists.
+ * Falls back to default configuration if no file is found.
+ *
+ * @returns The consolidated configuration object
+ */
 function loadConfig() {
     const configPath = path_1.default.resolve("envwise.config.json");
     if (!fs_1.default.existsSync(configPath)) {

package/dist/engine/driftChecker.d.ts

@@ -1,2 +1,11 @@
 import { DriftResult, Config } from "../types";
+/**
+ * Compares a base environment (template) against a target environment (actual)
+ * and returns the differences including missing keys, extra keys, and value mismatches.
+ *
+ * @param base - The record representing the template environment (e.g., .env.example)
+ * @param target - The record representing the actual environment (e.g., .env)
+ * @param config - Configuration object containing validation rules
+ * @returns An object containing the results of the drift check
+ */
 export declare function checkDrift(base: Record<string, string>, target: Record<string, string>, config: Config): DriftResult;

package/dist/engine/driftChecker.js

@@ -2,6 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkDrift = checkDrift;
 const validator_1 = require("./validator");
+/**
+ * Compares a base environment (template) against a target environment (actual)
+ * and returns the differences including missing keys, extra keys, and value mismatches.
+ *
+ * @param base - The record representing the template environment (e.g., .env.example)
+ * @param target - The record representing the actual environment (e.g., .env)
+ * @param config - Configuration object containing validation rules
+ * @returns An object containing the results of the drift check
+ */
 function checkDrift(base, target, config) {
     const result = {
         missing: [],

package/dist/engine/envParser.d.ts

@@ -1 +1,9 @@
+/**
+ * Parses a .env file from the given file system path.
+ * It handles comments, empty lines, and quoted values.
+ *
+ * @param path - The absolute or relative path to the .env file
+ * @returns A record containing key-value pairs of the environment variables
+ * @throws {Error} If the file does not exist
+ */
 export declare function parseEnv(path: string): Record<string, string>;

package/dist/engine/envParser.js

@@ -5,6 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseEnv = parseEnv;
 const fs_1 = __importDefault(require("fs"));
+/**
+ * Parses a .env file from the given file system path.
+ * It handles comments, empty lines, and quoted values.
+ *
+ * @param path - The absolute or relative path to the .env file
+ * @returns A record containing key-value pairs of the environment variables
+ * @throws {Error} If the file does not exist
+ */
 function parseEnv(path) {
     if (!fs_1.default.existsSync(path)) {
         throw new Error(`Env file not found: ${path}`);

package/dist/engine/interactive.d.ts

@@ -1,2 +1,11 @@
 import { Config } from "../types";
+/**
+ * Launches an interactive CLI wizard to help users fill in missing environment variables.
+ * Uses the 'prompts' package to collect user input with validation.
+ *
+ * @param missingKeys - An array of environment variable keys that are missing
+ * @param baseEnv - The template environment mapping
+ * @param config - The tool configuration containing validation rules
+ * @returns A promise that resolves to a record of the newly filled key-value pairs
+ */
 export declare function interactiveSetup(missingKeys: string[], baseEnv: Record<string, string>, config: Config): Promise<Record<string, string>>;

package/dist/engine/interactive.js

@@ -6,6 +6,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.interactiveSetup = interactiveSetup;
 const prompts_1 = __importDefault(require("prompts"));
 const validator_1 = require("./validator");
+/**
+ * Launches an interactive CLI wizard to help users fill in missing environment variables.
+ * Uses the 'prompts' package to collect user input with validation.
+ *
+ * @param missingKeys - An array of environment variable keys that are missing
+ * @param baseEnv - The template environment mapping
+ * @param config - The tool configuration containing validation rules
+ * @returns A promise that resolves to a record of the newly filled key-value pairs
+ */
 async function interactiveSetup(missingKeys, baseEnv, config) {
     const newValues = {};
     console.log("\n🛠  Interactive Setup: Let's fill in the missing variables.\n");

package/dist/engine/validator.d.ts

@@ -1,2 +1,12 @@
 import { Rule } from "../types";
+/**
+ * Validates a single environment variable value against a set of rules.
+ * Supports string length, number ranges, boolean flags, enums, emails, URLs, and custom regex.
+ *
+ * @param key - The name of the environment variable
+ * @param value - The value to validate
+ * @param rule - The validation rule configuration for this key
+ * @param env - The current environment (e.g., NODE_ENV) for conditional rules
+ * @returns A string containing the error message if validation fails, otherwise null
+ */
 export declare function validateValue(key: string, value: string, rule: Rule, env: string): string | null;

package/dist/engine/validator.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateValue = validateValue;
+/**
+ * Validates a single environment variable value against a set of rules.
+ * Supports string length, number ranges, boolean flags, enums, emails, URLs, and custom regex.
+ *
+ * @param key - The name of the environment variable
+ * @param value - The value to validate
+ * @param rule - The validation rule configuration for this key
+ * @param env - The current environment (e.g., NODE_ENV) for conditional rules
+ * @returns A string containing the error message if validation fails, otherwise null
+ */
 function validateValue(key, value, rule, env) {
     if (!value && rule.required !== false) {
         return `${key} is required`;

package/dist/types.d.ts

@@ -1,29 +1,56 @@
+/**
+ * Represents a validation rule for an environment variable.
+ */
 export interface Rule {
+    /** The data type of the variable. Used for validation and CLI input prompts. */
     type: "string" | "number" | "boolean" | "enum" | "email" | "url" | "regex";
+    /** Allowed values if the type is 'enum'. */
     values?: string[];
+    /** Custom regular expression string if the type is 'regex'. */
     regex?: string;
+    /** Minimum length (for strings) or minimum value (for numbers). */
     min?: number;
+    /** Maximum length (for strings) or maximum value (for numbers). */
     max?: number;
+    /** A helpful description displayed during interactive CLI setup. */
     description?: string;
+    /** Environment(s) where this boolean must be false (useful for safety flags). */
     mustBeFalseIn?: string;
+    /** Whether the variable is mandatory. Defaults to true. */
     required?: boolean;
 }
+/**
+ * Global configuration for the env-drift-check tool.
+ */
 export interface Config {
+    /** The template environment file to compare against (e.g., .env.example). */
     baseEnv?: string;
+    /** A map of environment variable keys to their validation rules. */
     rules?: Record<string, Rule>;
 }
+/**
+ * Details of a mismatch between the base and target environment values.
+ */
 export interface ValueMismatch {
     key: string;
     expected: string;
     actual: string;
 }
+/**
+ * The consolidated result of an environment drift check.
+ */
 export interface DriftResult {
+    /** Keys present in the template but missing in the target. */
     missing: string[];
+    /** Keys present in the target but absent from the template. */
     extra: string[];
+    /** Validation errors based on the defined rules. */
     errors: {
         key: string;
         message: string;
     }[];
+    /** Non-critical warnings. */
     warnings: string[];
+    /** Values that differ between the template and target for the same key. */
     mismatches: ValueMismatch[];
 }

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "env-drift-check",
-  "version": "0.1.4",
-  "description": "Interactive environment variable checker and setup wizard. Sync .env files with validation (Email, URL, Regex) and prompts.",
+  "version": "0.1.6",
+  "description": "Interactive .env synchronizer and validator. Detect environment drift, sync missing variables, and enforce schema validation for seamless developer onboarding.",
   "keywords": [
     "env",
     "dotenv",
     "check-env",
     "dotenv-safe",
+    "env-drift-check",
     "environment-variables",
+    "env-validation",
     "config",
     "validation",
     "interactive",
     "setup",
     "onboarding",
     "drift",
-    "checker"
+    "checker",
+    "cli-tool",
+    "dx",
+    "env-sync",
+    "security",
+    "workflow"
   ],
   "author": "Shashidhar Naik",
   "license": "MIT",