menv-npm 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Dallas Okoye (TheDanielDallas.com)
+
+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,67 @@
+# Menv NPM
+
+<!-- v0.1.0-alpha.11 -->
+
+Managed Environment Variables for Node.js projects.
+
+Menv is a lightweight CLI designed to bring consistency, safety, and automation to environment variable management. It ensures that your development, production, and example environment files stay in sync while proactively protecting against accidental secret leaks.
+
+## Features
+
+- **Automated .env.example Generation**: Create and maintain example files that mirror your actual environment configuration without exposing sensitive values.
+- **Environment Synchronization**: Detect and report inconsistencies between your local environment and documented templates.
+- **CI-Ready Validation**: Validate that all required variables exist before deployment, preventing runtime crashes.
+- **Real-time Watcher**: Automatically update your example files as you modify your local environment.
+- **Security Scanning**: Detect potential secret leaks (AWS, Stripe, GitHub, etc.) within your environment files.
+- **Auto-Protection**: Automatically ensures your environment files are added to .gitignore to prevent accidental commits.
+
+## Installation
+
+```bash
+npm install menv-npm --save-dev
+```
+
+## Quick Start
+
+Generate your initial .env.example:
+
+```bash
+npx menv generate
+```
+
+Check if your environment is in sync:
+
+```bash
+npx menv sync
+```
+
+Validate requirements for CI:
+
+```bash
+npx menv check
+```
+
+## Commands
+
+| Command    | Usage               | Description                                                    |
+| ---------- | ------------------- | -------------------------------------------------------------- |
+| `generate` | `menv-npm generate` | Creates or updates .env.example from .env                      |
+| `sync`     | `menv-npm sync`     | Compares .env and .env.example for inconsistencies             |
+| `check`    | `menv-npm check`    | Validates that all variables in the example file exist locally |
+| `watch`    | `menv-npm watch`    | Monitors .env for changes and updates the example file         |
+| `doctor`   | `menv-npm doctor`   | Scans all environment files for potential secret leaks         |
+
+## Community
+
+| Documentation                         | Description                                |
+| ------------------------------------- | ------------------------------------------ |
+| [Contributing](CONTRIBUTING.md)       | Learn how to get started with contributing |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Our standards for a healthy community      |
+| [Security](SECURITY.md)               | Procedures for reporting security issues   |
+| [License](LICENSE)                    | MIT Open Source License                    |
+
+---
+
+<div align="center">
+  Managed with care by <b>Daniel Dallas Okoye</b>
+</div>

package/dist/core/__tests__/envGenerator.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/envGenerator.spec.js

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import { generateExample } from "../envGenerator.js";
+describe("envGenerator", () => {
+    it("should generate empty values for keys", () => {
+        const lines = [
+            { key: "PORT", value: "3000", raw: "PORT=3000" },
+            { key: "DB", value: "url", raw: "DB=url" },
+        ];
+        const result = generateExample(lines);
+        expect(result).toBe("PORT=\nDB=");
+    });
+    it("should preserve comments and empty lines", () => {
+        const lines = [
+            { key: "", value: "", raw: "# Comment" },
+            { key: "", value: "", raw: "" },
+            { key: "PORT", value: "3000", raw: "PORT=3000" },
+        ];
+        const result = generateExample(lines);
+        expect(result).toBe("# Comment\n\nPORT=");
+    });
+});

package/dist/core/__tests__/envParser.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/envParser.spec.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { parseEnv } from "../envParser.js";
+describe("envParser", () => {
+    it("should parse simple key-value pairs", () => {
+        const content = "PORT=3000\nDATABASE_URL=postgres://localhost";
+        const result = parseEnv(content);
+        expect(result).toContainEqual(expect.objectContaining({ key: "PORT", value: "3000" }));
+        expect(result).toContainEqual(expect.objectContaining({
+            key: "DATABASE_URL",
+            value: "postgres://localhost",
+        }));
+    });
+    it("should handle comments and empty lines", () => {
+        const content = "# Comment\n\nPORT=3000";
+        const result = parseEnv(content);
+        expect(result.filter((l) => l.key)).toHaveLength(1);
+        expect(result[0].raw).toBe("# Comment");
+        expect(result[1].raw).toBe("");
+    });
+    it("should handle quoted values", () => {
+        const content = "SECRET=\"super secret\"\nKEY='single quoted'";
+        const result = parseEnv(content);
+        expect(result).toContainEqual(expect.objectContaining({ key: "SECRET", value: "super secret" }));
+        expect(result).toContainEqual(expect.objectContaining({ key: "KEY", value: "single quoted" }));
+    });
+});

package/dist/core/envGenerator.d.ts

@@ -0,0 +1,6 @@
+import { EnvLine } from "./envParser.js";
+/**
+ * Generates .env.example content from parsed EnvLines.
+ * Values are stripped, but comments and structure are preserved.
+ */
+export declare function generateExample(lines: EnvLine[]): string;

package/dist/core/envGenerator.js

@@ -0,0 +1,13 @@
+/**
+ * Generates .env.example content from parsed EnvLines.
+ * Values are stripped, but comments and structure are preserved.
+ */
+export function generateExample(lines) {
+    return lines
+        .map((line) => {
+        if (!line.key)
+            return line.raw;
+        return `${line.key}=`;
+    })
+        .join("\n");
+}

package/dist/core/envParser.d.ts

@@ -0,0 +1,11 @@
+export interface EnvLine {
+    key: string;
+    value: string;
+    comment?: string;
+    raw: string;
+}
+/**
+ * Parses raw .env content into structured data.
+ * Handles quoted values, escaped characters, and inline comments.
+ */
+export declare function parseEnv(content: string): EnvLine[];

package/dist/core/envParser.js

@@ -0,0 +1,31 @@
+/**
+ * Parses raw .env content into structured data.
+ * Handles quoted values, escaped characters, and inline comments.
+ */
+export function parseEnv(content) {
+    const lines = [];
+    const rawLines = content.split(/\r?\n/);
+    for (const raw of rawLines) {
+        const trimmed = raw.trim();
+        // Skip empty lines or pure comment lines
+        if (!trimmed || trimmed.startsWith("#")) {
+            lines.push({ key: "", value: "", raw });
+            continue;
+        }
+        const match = trimmed.match(/^([^=:#]+)[=:] ?(.*)/);
+        if (!match) {
+            lines.push({ key: "", value: "", raw });
+            continue;
+        }
+        let [_, key, value] = match;
+        key = key.trim();
+        value = value.trim();
+        // Remove surrounding quotes if present
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        lines.push({ key, value, raw });
+    }
+    return lines;
+}

package/dist/core/envValidator.d.ts

@@ -0,0 +1,9 @@
+import { EnvLine } from "./envParser.js";
+export interface SyncResult {
+    missingInExample: string[];
+    missingInEnv: string[];
+}
+/**
+ * Compares keys between .env and .env.example.
+ */
+export declare function compareEnvKeys(envLines: EnvLine[], exampleLines: EnvLine[]): SyncResult;

package/dist/core/envValidator.js

@@ -0,0 +1,11 @@
+/**
+ * Compares keys between .env and .env.example.
+ */
+export function compareEnvKeys(envLines, exampleLines) {
+    const envKeys = new Set(envLines.map((l) => l.key).filter(Boolean));
+    const exampleKeys = new Set(exampleLines.map((l) => l.key).filter(Boolean));
+    return {
+        missingInExample: Array.from(envKeys).filter((k) => !exampleKeys.has(k)),
+        missingInEnv: Array.from(exampleKeys).filter((k) => !envKeys.has(k)),
+    };
+}

package/dist/core/envWatcher.d.ts

@@ -0,0 +1,5 @@
+import chokidar from "chokidar";
+/**
+ * Watches for changes in .env and regenerates .env.example.
+ */
+export declare function startWatcher(): Promise<chokidar.FSWatcher>;

package/dist/core/envWatcher.js

@@ -0,0 +1,32 @@
+import chokidar from "chokidar";
+import fs from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+import { parseEnv } from "./envParser.js";
+import { generateExample } from "./envGenerator.js";
+/**
+ * Watches for changes in .env and regenerates .env.example.
+ */
+export async function startWatcher() {
+    const envPath = path.resolve(process.cwd(), ".env");
+    const examplePath = path.resolve(process.cwd(), ".env.example");
+    console.log(pc.dim(`Watching for changes in ${pc.cyan(".env")}...`));
+    const watcher = chokidar.watch(envPath, {
+        persistent: true,
+        ignoreInitial: true,
+    });
+    watcher.on("change", async () => {
+        try {
+            console.log(pc.blue("⚡ .env changed, regenerating .env.example..."));
+            const content = await fs.readFile(envPath, "utf8");
+            const parsed = parseEnv(content);
+            const generated = generateExample(parsed);
+            await fs.writeFile(examplePath, generated);
+            console.log(pc.green("✔ .env.example updated."));
+        }
+        catch (error) {
+            console.error(pc.red("✖ Failed to update .env.example in watch mode:"), error);
+        }
+    });
+    return watcher;
+}

package/dist/core/secretScanner.d.ts

@@ -0,0 +1,10 @@
+import { EnvLine } from "./envParser.js";
+export interface SecretIssue {
+    key: string;
+    type: string;
+    line: number;
+}
+/**
+ * Scans environment lines for potential secret leaks.
+ */
+export declare function scanSecrets(lines: EnvLine[]): SecretIssue[];

package/dist/core/secretScanner.js

@@ -0,0 +1,26 @@
+const PATTERNS = [
+    { name: "AWS Access Key", regex: /AKIA[0-9A-Z]{16}/ },
+    { name: "Stripe Secret Key", regex: /sk_live_[0-9a-zA-Z]{24}/ },
+    { name: "GitHub Token", regex: /ghp_[0-9a-zA-Z]{36}/ },
+    { name: "Private Key", regex: /-----BEGIN [A-Z ]+ PRIVATE KEY-----/ },
+];
+/**
+ * Scans environment lines for potential secret leaks.
+ */
+export function scanSecrets(lines) {
+    const issues = [];
+    lines.forEach((line, index) => {
+        if (!line.key)
+            return;
+        for (const pattern of PATTERNS) {
+            if (pattern.regex.test(line.value) || pattern.regex.test(line.raw)) {
+                issues.push({
+                    key: line.key,
+                    type: pattern.name,
+                    line: index + 1,
+                });
+            }
+        }
+    });
+    return issues;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { cac } from "cac";
+import pc from "picocolors";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parseEnv } from "./core/envParser.js";
+import { generateExample } from "./core/envGenerator.js";
+import { compareEnvKeys } from "./core/envValidator.js";
+import { startWatcher } from "./core/envWatcher.js";
+import { scanSecrets } from "./core/secretScanner.js";
+import { ensureGitignore } from "./utils/git.js";
+import { findTemplateFile } from "./utils/template.js";
+const cli = cac("menv");
+cli.command("generate", "Generate .env.example from .env").action(async () => {
+    try {
+        await ensureGitignore();
+        const envPath = path.resolve(process.cwd(), ".env");
+        const examplePath = path.resolve(process.cwd(), ".env.example");
+        if (!(await fs.stat(envPath).catch(() => false))) {
+            console.error(pc.red("✖ .env file not found in current directory."));
+            process.exit(1);
+        }
+        const content = await fs.readFile(envPath, "utf8");
+        const parsed = parseEnv(content);
+        const generated = generateExample(parsed);
+        await fs.writeFile(examplePath, generated);
+        console.log(pc.green("✔ .env.example generated successfully."));
+    }
+    catch (error) {
+        console.error(pc.red("✖ Failed to generate .env.example:"), error);
+        process.exit(1);
+    }
+});
+cli
+    .command("sync", "Check for inconsistencies between .env and .env.example")
+    .alias("synch")
+    .action(async () => {
+    try {
+        await ensureGitignore();
+        const envPath = path.resolve(process.cwd(), ".env");
+        const templatePath = await findTemplateFile();
+        if (!(await fs.stat(envPath).catch(() => false))) {
+            console.error(pc.red("✖ .env file not found."));
+            process.exit(1);
+        }
+        if (!templatePath) {
+            console.error(pc.red("✖ No environment template (.env.example or .env.sample) found."));
+            process.exit(1);
+        }
+        const templateName = path.basename(templatePath);
+        console.log(pc.dim(`\nComparing .env with ${templateName}...`));
+        const envContent = await fs.readFile(envPath, "utf8");
+        const templateContent = await fs.readFile(templatePath, "utf8");
+        const envParsed = parseEnv(envContent);
+        const templateParsed = parseEnv(templateContent);
+        const { missingInExample: missingInTemplate, missingInEnv } = compareEnvKeys(envParsed, templateParsed);
+        if (missingInTemplate.length === 0 && missingInEnv.length === 0) {
+            console.log(pc.green(`✔ ${templateName} is in sync with .env`));
+            return;
+        }
+        if (missingInTemplate.length > 0) {
+            console.log(pc.yellow(`\nMissing in ${templateName}:`));
+            missingInTemplate.forEach((k) => console.log(pc.dim(` - ${k}`)));
+        }
+        if (missingInEnv.length > 0) {
+            console.log(pc.yellow(`\nExtra in ${templateName} (not in .env):`));
+            missingInEnv.forEach((k) => console.log(pc.dim(` - ${k}`)));
+        }
+    }
+    catch (error) {
+        console.error(pc.red("✖ Failed to sync environment files:"), error);
+        process.exit(1);
+    }
+});
+cli
+    .command("check", "Validate that all required variables in .env.example exist in .env")
+    .action(async () => {
+    try {
+        await ensureGitignore();
+        const envPath = path.resolve(process.cwd(), ".env");
+        const templatePath = await findTemplateFile();
+        if (!templatePath) {
+            console.error(pc.red("✖ No environment template (.env.example or .env.sample) found."));
+            process.exit(1);
+        }
+        const templateName = path.basename(templatePath);
+        console.log(pc.dim(`\nValidating .env against ${templateName}...`));
+        const envContent = (await fs.stat(envPath).catch(() => false))
+            ? await fs.readFile(envPath, "utf8")
+            : "";
+        const templateContent = await fs.readFile(templatePath, "utf8");
+        const envParsed = parseEnv(envContent);
+        const exampleParsed = parseEnv(templateContent);
+        const envKeys = new Set(envParsed.map((l) => l.key).filter(Boolean));
+        const requiredKeys = exampleParsed.map((l) => l.key).filter(Boolean);
+        let hasMissing = false;
+        console.log(pc.bold("\nEnvironment Variable Check:"));
+        for (const key of requiredKeys) {
+            if (envKeys.has(key)) {
+                console.log(`${pc.green("✔")} ${key}`);
+            }
+            else {
+                console.log(`${pc.red("✖")} ${key} (missing)`);
+                hasMissing = true;
+            }
+        }
+        if (hasMissing) {
+            console.error(pc.red(`\n✖ Environment validation failed. Please check ${templateName}.`));
+            process.exit(1);
+        }
+        else {
+            console.log(pc.green("\n✔ Environment validation passed."));
+        }
+    }
+    catch (error) {
+        console.error(pc.red("✖ Validation error:"), error);
+        process.exit(1);
+    }
+});
+cli
+    .command("watch", "Watch for .env changes and automatically update .env.example")
+    .action(async () => {
+    try {
+        await ensureGitignore();
+        const envPath = path.resolve(process.cwd(), ".env");
+        if (!(await fs.stat(envPath).catch(() => false))) {
+            console.error(pc.red("✖ .env file not found."));
+            process.exit(1);
+        }
+        await startWatcher();
+    }
+    catch (error) {
+        console.error(pc.red("✖ Watcher error:"), error);
+        process.exit(1);
+    }
+});
+cli
+    .command("doctor", "Scan for potential secret leaks in environment files")
+    .action(async () => {
+    try {
+        await ensureGitignore();
+        const files = [
+            ".env",
+            ".env.example",
+            ".env.local",
+            ".env.development",
+            ".env.production",
+        ];
+        let totalIssues = 0;
+        for (const file of files) {
+            const filePath = path.resolve(process.cwd(), file);
+            if (!(await fs.stat(filePath).catch(() => false)))
+                continue;
+            const content = await fs.readFile(filePath, "utf8");
+            const parsed = parseEnv(content);
+            const issues = scanSecrets(parsed);
+            if (issues.length > 0) {
+                console.log(pc.yellow(`\n⚠ Potential secrets found in ${pc.bold(file)}:`));
+                issues.forEach((issue) => {
+                    console.log(`${pc.dim(`Line ${issue.line}:`)} ${pc.red(issue.key)} (${issue.type})`);
+                });
+                totalIssues += issues.length;
+            }
+        }
+        if (totalIssues === 0) {
+            console.log(pc.green("✔ No potential secrets detected."));
+        }
+        else {
+            console.log(pc.red(`\n✖ Total issues found: ${totalIssues}`));
+        }
+    }
+    catch (error) {
+        console.error(pc.red("✖ Doctor error:"), error);
+        process.exit(1);
+    }
+});
+cli.help();
+cli.version("0.1.0");
+cli.parse();

package/dist/utils/git.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Ensures that .env files are present in .gitignore.
+ * Creates .gitignore if it doesn't exist.
+ */
+export declare function ensureGitignore(): Promise<void>;

package/dist/utils/git.js

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+const ENV_PATTERNS = [
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.production",
+    ".env.test",
+    "node_modules",
+    "dist",
+    "!.env.example",
+    "!.env.sample",
+];
+const SECTION_HEADER = "# Menv: Environment file protection";
+/**
+ * Ensures that .env files are present in .gitignore.
+ * Creates .gitignore if it doesn't exist.
+ */
+export async function ensureGitignore() {
+    const gitignorePath = path.resolve(process.cwd(), ".gitignore");
+    try {
+        let content = "";
+        let exists = false;
+        try {
+            content = await fs.readFile(gitignorePath, "utf8");
+            exists = true;
+        }
+        catch {
+            // File doesn't exist, we'll create it
+        }
+        const lines = content.split("\n").map((l) => l.trim());
+        const missingPatterns = ENV_PATTERNS.filter((p) => !lines.includes(p));
+        if (missingPatterns.length === 0) {
+            return;
+        }
+        console.log(pc.dim("Updating .gitignore to protect environment files..."));
+        let newContent = content;
+        if (exists && content.length > 0 && !content.endsWith("\n")) {
+            newContent += "\n";
+        }
+        if (!content.includes(SECTION_HEADER)) {
+            newContent += `\n${SECTION_HEADER}\n`;
+        }
+        for (const pattern of missingPatterns) {
+            newContent += `${pattern}\n`;
+        }
+        await fs.writeFile(gitignorePath, newContent);
+    }
+    catch (error) {
+        // We don't want to crash the tool if .gitignore update fails,
+        // but we should warn the user.
+        console.warn(pc.yellow("⚠ Warning: Could not update .gitignore. Please ensure your .env files are ignored manually."));
+    }
+}

package/dist/utils/template.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Finds the environment template file in the current directory.
+ * Returns the path to .env.example or .env.sample if found.
+ */
+export declare function findTemplateFile(): Promise<string | null>;

package/dist/utils/template.js

@@ -0,0 +1,16 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const TEMPLATE_VARIANTS = [".env.example", ".env.sample"];
+/**
+ * Finds the environment template file in the current directory.
+ * Returns the path to .env.example or .env.sample if found.
+ */
+export async function findTemplateFile() {
+    for (const variant of TEMPLATE_VARIANTS) {
+        const filePath = path.resolve(process.cwd(), variant);
+        if (await fs.stat(filePath).catch(() => false)) {
+            return filePath;
+        }
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "menv-npm",
+  "version": "0.1.1",
+  "description": "Managed environment variables for Node.js",
+  "type": "module",
+  "bin": {
+    "menv": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src/**/*.ts",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "env",
+    "dotenv",
+    "configuration",
+    "validator",
+    "security"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "cac": "^6.7.14",
+    "picocolors": "^1.0.0",
+    "chokidar": "^3.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}