@gokul-kannur/env-guard 1.0.0

package/.pre-commit-hooks.yaml

@@ -0,0 +1,11 @@
+# Pre-commit hooks for env-guard
+# See https://pre-commit.com for more information
+
+- id: env-guard
+  name: env-guard
+  description: Validate .env files for common mistakes
+  entry: env-guard
+  language: node
+  files: '\.env$'
+  types: [text]
+  pass_filenames: true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GokulKannur
+
+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,135 @@
+# env-guard
+
+Catch stupid .env mistakes before deploy. No sync. No presets. Just validation.
+
+## Why?
+
+Because you've broken production due to:
+
+- Missing env variable
+- Typo in variable name
+- Empty value you forgot to fill
+- `DEBUG=true` in production
+
+This tool catches those. Nothing more.
+
+## Install
+
+```bash
+npm install -g env-guard
+```
+
+## Usage
+
+```bash
+# Check current directory
+env-guard
+
+# Check specific file
+env-guard .env.production
+```
+
+### Common Options
+
+```bash
+# Compare against a specific example file
+env-guard --example .env.template
+
+# Strict mode (treat all empty values as errors)
+env-guard --strict
+
+# CI mode (GitHub Actions annotations)
+env-guard --ci
+```
+
+> **Note**: If `.env.example` (or the specified example file) is missing, comparison checks are skipped.
+
+That's it. It will:
+
+1. Read `.env`
+2. Compare with `.env.example` (if exists)
+3. Print errors/warnings
+4. Exit with code 1 if errors found
+
+## What it checks
+
+| Check | Type | Description |
+|-------|------|-------------|
+| Missing vars | Error | Key in example but not in env |
+| Duplicates | Error | Same key defined twice |
+| Empty values | Warning* | Key has no value |
+| Unused vars | Warning | Key in env but not in example |
+| Unsafe defaults | Warning | `DEBUG=true`, `NODE_ENV=development`, etc. |
+
+*Empty values become errors in `--strict` mode or for sensitive keys (DATABASE_*, PASSWORD, etc.)
+
+## Example output
+
+```
+🔍 env-guard validation report
+
+Errors (2)
+  ❌ Missing variable: DATABASE_URL (defined in example)
+  ❌ Duplicate key: API_KEY (lines 5 and 12)
+
+Warnings (3)
+  ⚠️ Empty value: OPTIONAL_VAR
+  ⚠️ Unused variable: OLD_CONFIG (not in example)
+  ⚠️ Unsafe default: DEBUG=true (may not be suitable for production)
+
+─────────────────────────────
+Total: 2 error(s), 3 warning(s)
+
+env-guard: 2 errors, 3 warnings
+```
+
+## CI/CD Usage
+
+### GitHub Actions
+
+```yaml
+- name: Validate env
+  run: npx env-guard --ci --strict
+```
+
+The `--ci` flag outputs GitHub Actions annotations:
+```
+::error file=.env,line=5::Missing variable: DATABASE_URL
+::warning file=.env,line=12::Unsafe default: DEBUG=true
+```
+
+### Pre-commit Hook
+
+This uses the CLI via a local hook, not a custom pre-commit plugin.
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/YOUR_USERNAME/env-guard
+    rev: v1.0.0
+    hooks:
+      - id: env-guard
+```
+
+## What this tool does NOT do
+
+- ❌ Sync files
+- ❌ Generate example files
+- ❌ Manage secrets
+- ❌ Framework integrations
+- ❌ Custom rules
+- ❌ Type validation
+
+If you need those, use something else.
+
+
+
+## Security & Privacy
+
+- **Runs locally**: Your env vars never leave your machine.
+- **No telemetry**: We don't track you.
+- **No logging**: Values are never printed to stdout (except masked) or logged to files.
+- **No external calls**: No analytics, no updates checks, nothing.
+
+MIT

package/bin/env-guard

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parse_1 = require("./parse");
+const rules_1 = require("./rules");
+const report_1 = require("./report");
+const program = new commander_1.Command();
+program
+    .name('env-guard')
+    .description('Catch stupid .env mistakes before deploy.')
+    .version('1.0.0')
+    .argument('[envFile]', 'Path to .env file', '.env')
+    .option('--example <file>', 'Path to .env.example file', '.env.example')
+    .option('--strict', 'Treat all empty values as errors')
+    .option('--json', 'Output as JSON')
+    .option('--ci', 'Output GitHub Actions annotations format')
+    .option('--no-example', 'Skip example file comparison')
+    .action((envFile, options) => {
+    try {
+        const envPath = path.resolve(process.cwd(), envFile);
+        if (!fs.existsSync(envPath)) {
+            console.error(`❌ Error: ${envFile} not found`);
+            process.exit(1);
+        }
+        const envResult = (0, parse_1.parseEnvFile)(envFile);
+        if (envResult.errors.length > 0) {
+            for (const error of envResult.errors) {
+                console.error(`❌ ${error}`);
+            }
+            process.exit(1);
+        }
+        let exampleVars = null;
+        if (options.example !== false) {
+            const examplePath = path.resolve(process.cwd(), options.example);
+            if (fs.existsSync(examplePath)) {
+                const exampleResult = (0, parse_1.parseEnvFile)(options.example);
+                if (exampleResult.errors.length === 0) {
+                    exampleVars = exampleResult.vars;
+                }
+            }
+        }
+        const result = (0, rules_1.validateEnv)(envResult.vars, exampleVars, options.strict);
+        if (options.json) {
+            (0, report_1.printJson)(result);
+        }
+        else if (options.ci) {
+            (0, report_1.printCi)(result, envFile);
+        }
+        else {
+            (0, report_1.printReport)(result);
+        }
+        if (result.errors.length > 0) {
+            process.exit(1);
+        }
+        else {
+            process.exit(0);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`❌ Error: ${error.message}`);
+        }
+        else {
+            console.error('❌ An unexpected error occurred');
+        }
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/parse.d.ts

@@ -0,0 +1,11 @@
+export interface EnvVar {
+    key: string;
+    value: string;
+    line: number;
+}
+export interface ParseResult {
+    vars: EnvVar[];
+    errors: string[];
+}
+export declare function parseEnvFile(filePath: string): ParseResult;
+export declare function getKeys(vars: EnvVar[]): Set<string>;

package/dist/parse.js

@@ -0,0 +1,78 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvFile = parseEnvFile;
+exports.getKeys = getKeys;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function parseEnvFile(filePath) {
+    const result = {
+        vars: [],
+        errors: [],
+    };
+    const absolutePath = path.resolve(process.cwd(), filePath);
+    if (!fs.existsSync(absolutePath)) {
+        result.errors.push(`File not found: ${filePath}`);
+        return result;
+    }
+    const content = fs.readFileSync(absolutePath, 'utf-8');
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        const lineNumber = i + 1;
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!match) {
+            continue;
+        }
+        const [, key, value] = match;
+        let cleanValue = value;
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            cleanValue = value.slice(1, -1);
+        }
+        result.vars.push({
+            key,
+            value: cleanValue,
+            line: lineNumber,
+        });
+    }
+    return result;
+}
+function getKeys(vars) {
+    return new Set(vars.map(v => v.key));
+}

package/dist/report.d.ts

@@ -0,0 +1,8 @@
+import { ValidationResult } from './rules';
+export declare function printReport(result: ValidationResult): void;
+/**
+ * GitHub Actions annotation format
+ * https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+export declare function printCi(result: ValidationResult, envFile: string): void;
+export declare function printJson(result: ValidationResult): void;

package/dist/report.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printReport = printReport;
+exports.printCi = printCi;
+exports.printJson = printJson;
+const colors = {
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+};
+function formatIssue(issue, isError) {
+    const icon = isError ? '❌' : '⚠️';
+    const color = isError ? colors.red : colors.yellow;
+    const lineInfo = (issue.line && !issue.hasInlineLineInfo) ? ` ${colors.dim}(line ${issue.line})${colors.reset}` : '';
+    return `${icon} ${color}${issue.message}${colors.reset}${lineInfo}`;
+}
+function printReport(result) {
+    const { errors, warnings } = result;
+    const total = errors.length + warnings.length;
+    console.log('');
+    console.log(`${colors.bold}🔍 env-guard validation report${colors.reset}`);
+    console.log('');
+    if (errors.length > 0) {
+        console.log(`${colors.red}${colors.bold}Errors (${errors.length})${colors.reset}`);
+        for (const error of errors) {
+            console.log(`  ${formatIssue(error, true)}`);
+        }
+        console.log('');
+    }
+    if (warnings.length > 0) {
+        console.log(`${colors.yellow}${colors.bold}Warnings (${warnings.length})${colors.reset}`);
+        for (const warning of warnings) {
+            console.log(`  ${formatIssue(warning, false)}`);
+        }
+        console.log('');
+    }
+    // Summary
+    if (total === 0) {
+        console.log(`${colors.green}✅ No issues found${colors.reset}`);
+    }
+    else {
+        console.log(`${colors.dim}─────────────────────────────${colors.reset}`);
+        console.log(`Total: ${errors.length} error(s), ${warnings.length} warning(s)`);
+    }
+    // One-line summary for logs
+    console.log('');
+    console.log(`env-guard: ${errors.length} errors, ${warnings.length} warnings`);
+}
+/**
+ * GitHub Actions annotation format
+ * https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+function printCi(result, envFile) {
+    const { errors, warnings } = result;
+    // Output GitHub Actions annotations
+    for (const error of errors) {
+        const line = error.line ? `,line=${error.line}` : '';
+        console.log(`::error file=${envFile}${line}::${error.message}`);
+    }
+    for (const warning of warnings) {
+        const line = warning.line ? `,line=${warning.line}` : '';
+        console.log(`::warning file=${envFile}${line}::${warning.message}`);
+    }
+    // Summary line
+    if (errors.length === 0 && warnings.length === 0) {
+        console.log('env-guard: ✅ No issues found');
+    }
+    else {
+        console.log(`env-guard: ${errors.length} errors, ${warnings.length} warnings`);
+    }
+}
+function printJson(result) {
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/rules.d.ts

@@ -0,0 +1,15 @@
+import { EnvVar } from './parse';
+export interface ValidationResult {
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+export interface ValidationIssue {
+    type: string;
+    key: string;
+    message: string;
+    line?: number;
+    hasInlineLineInfo?: boolean;
+}
+export declare function isSensitiveKey(key: string): boolean;
+export declare function maskValue(key: string, value: string): string;
+export declare function validateEnv(envVars: EnvVar[], exampleVars: EnvVar[] | null, strict?: boolean): ValidationResult;

package/dist/rules.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSensitiveKey = isSensitiveKey;
+exports.maskValue = maskValue;
+exports.validateEnv = validateEnv;
+// Keys that should NEVER be empty in production
+const REQUIRED_PATTERNS = [
+    /^DATABASE/i,
+    /^DB_/i,
+    /^API_KEY/i,
+    /^SECRET/i,
+    /^PASSWORD/i,
+];
+// Keys that indicate unsafe defaults
+const UNSAFE_DEFAULTS = {
+    'DEBUG': ['true', '1', 'yes'],
+    'APP_DEBUG': ['true', '1', 'yes'],
+    'NODE_ENV': ['development', 'dev'],
+    'LOG_LEVEL': ['debug', 'trace'],
+};
+// Sensitive keys that should be masked in output
+const SENSITIVE_PATTERNS = [
+    /SECRET/i,
+    /PASSWORD/i,
+    /TOKEN/i,
+    /KEY/i,
+    /CREDENTIAL/i,
+    /AUTH/i,
+    /PRIVATE/i,
+];
+function isSensitiveKey(key) {
+    return SENSITIVE_PATTERNS.some(pattern => pattern.test(key));
+}
+function maskValue(key, value) {
+    if (isSensitiveKey(key)) {
+        if (value.length <= 4) {
+            return '****';
+        }
+        return value.substring(0, 2) + '****' + value.substring(value.length - 2);
+    }
+    return value;
+}
+function validateEnv(envVars, exampleVars, strict = false) {
+    const result = {
+        errors: [],
+        warnings: [],
+    };
+    const envKeys = new Set(envVars.map(v => v.key));
+    const exampleKeys = exampleVars ? new Set(exampleVars.map(v => v.key)) : null;
+    // Check for missing keys (in example but not in env)
+    if (exampleKeys) {
+        for (const exampleVar of exampleVars) {
+            if (!envKeys.has(exampleVar.key)) {
+                result.errors.push({
+                    type: 'missing',
+                    key: exampleVar.key,
+                    message: `Missing variable: ${exampleVar.key} (defined in example)`,
+                });
+            }
+        }
+    }
+    // Check for duplicates
+    const seen = new Map();
+    for (const envVar of envVars) {
+        if (seen.has(envVar.key)) {
+            result.errors.push({
+                type: 'duplicate',
+                key: envVar.key,
+                message: `Duplicate key: ${envVar.key} (lines ${seen.get(envVar.key)} and ${envVar.line})`,
+                line: envVar.line,
+                hasInlineLineInfo: true,
+            });
+        }
+        seen.set(envVar.key, envVar.line);
+    }
+    // Check for empty values
+    for (const envVar of envVars) {
+        if (envVar.value === '' || envVar.value.trim() === '') {
+            const isRequired = REQUIRED_PATTERNS.some(p => p.test(envVar.key));
+            if (isRequired || strict) {
+                result.errors.push({
+                    type: 'empty',
+                    key: envVar.key,
+                    message: `Empty value: ${envVar.key}`,
+                    line: envVar.line,
+                });
+            }
+            else {
+                result.warnings.push({
+                    type: 'empty',
+                    key: envVar.key,
+                    message: `Empty value: ${envVar.key}`,
+                    line: envVar.line,
+                });
+            }
+        }
+    }
+    // Check for unused keys (in env but not in example)
+    if (exampleKeys) {
+        for (const envVar of envVars) {
+            if (!exampleKeys.has(envVar.key)) {
+                result.warnings.push({
+                    type: 'unused',
+                    key: envVar.key,
+                    message: `Unused variable: ${envVar.key} (not in example)`,
+                    line: envVar.line,
+                });
+            }
+        }
+    }
+    // Check for unsafe defaults
+    for (const envVar of envVars) {
+        const unsafeValues = UNSAFE_DEFAULTS[envVar.key];
+        if (unsafeValues && unsafeValues.includes(envVar.value.toLowerCase())) {
+            result.warnings.push({
+                type: 'unsafe',
+                key: envVar.key,
+                message: `Unsafe default: ${envVar.key}=${envVar.value} (may not be suitable for production)`,
+                line: envVar.line,
+            });
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@gokul-kannur/env-guard",
+    "version": "1.0.0",
+    "description": "Catch stupid .env mistakes before deploy. No sync. No presets. Just validation.",
+    "main": "dist/index.js",
+    "bin": {
+        "env-guard": "./bin/env-guard"
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "ts-node src/index.ts",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "env",
+        "dotenv",
+        "validator",
+        "cli",
+        "developer-tools",
+        "ci"
+    ],
+    "author": "",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/GokulKannur/env-guard.git"
+    },
+    "bugs": {
+        "url": "https://github.com/GokulKannur/env-guard/issues"
+    },
+    "homepage": "https://github.com/GokulKannur/env-guard#readme",
+    "devDependencies": {
+        "@types/node": "^20.10.0",
+        "typescript": "^5.3.0",
+        "ts-node": "^10.9.0"
+    },
+    "dependencies": {
+        "commander": "^11.1.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseEnvFile } from './parse';
+import { validateEnv } from './rules';
+import { printReport, printJson, printCi } from './report';
+
+const program = new Command();
+
+program
+    .name('env-guard')
+    .description('Catch stupid .env mistakes before deploy.')
+    .version('1.0.0')
+    .argument('[envFile]', 'Path to .env file', '.env')
+    .option('--example <file>', 'Path to .env.example file', '.env.example')
+    .option('--strict', 'Treat all empty values as errors')
+    .option('--json', 'Output as JSON')
+    .option('--ci', 'Output GitHub Actions annotations format')
+    .option('--no-example', 'Skip example file comparison')
+    .action((envFile, options) => {
+        try {
+            const envPath = path.resolve(process.cwd(), envFile);
+
+            if (!fs.existsSync(envPath)) {
+                console.error(`❌ Error: ${envFile} not found`);
+                process.exit(1);
+            }
+
+            const envResult = parseEnvFile(envFile);
+            if (envResult.errors.length > 0) {
+                for (const error of envResult.errors) {
+                    console.error(`❌ ${error}`);
+                }
+                process.exit(1);
+            }
+
+            let exampleVars = null;
+            if (options.example !== false) {
+                const examplePath = path.resolve(process.cwd(), options.example);
+                if (fs.existsSync(examplePath)) {
+                    const exampleResult = parseEnvFile(options.example);
+                    if (exampleResult.errors.length === 0) {
+                        exampleVars = exampleResult.vars;
+                    }
+                }
+            }
+
+            const result = validateEnv(envResult.vars, exampleVars, options.strict);
+
+            if (options.json) {
+                printJson(result);
+            } else if (options.ci) {
+                printCi(result, envFile);
+            } else {
+                printReport(result);
+            }
+
+            if (result.errors.length > 0) {
+                process.exit(1);
+            } else {
+                process.exit(0);
+            }
+
+        } catch (error) {
+            if (error instanceof Error) {
+                console.error(`❌ Error: ${error.message}`);
+            } else {
+                console.error('❌ An unexpected error occurred');
+            }
+            process.exit(1);
+        }
+    });
+
+program.parse();

package/src/parse.ts

@@ -0,0 +1,65 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface EnvVar {
+    key: string;
+    value: string;
+    line: number;
+}
+
+export interface ParseResult {
+    vars: EnvVar[];
+    errors: string[];
+}
+
+export function parseEnvFile(filePath: string): ParseResult {
+    const result: ParseResult = {
+        vars: [],
+        errors: [],
+    };
+
+    const absolutePath = path.resolve(process.cwd(), filePath);
+
+    if (!fs.existsSync(absolutePath)) {
+        result.errors.push(`File not found: ${filePath}`);
+        return result;
+    }
+
+    const content = fs.readFileSync(absolutePath, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        const lineNumber = i + 1;
+
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+
+        if (!match) {
+            continue;
+        }
+
+        const [, key, value] = match;
+
+        let cleanValue = value;
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            cleanValue = value.slice(1, -1);
+        }
+
+        result.vars.push({
+            key,
+            value: cleanValue,
+            line: lineNumber,
+        });
+    }
+
+    return result;
+}
+
+export function getKeys(vars: EnvVar[]): Set<string> {
+    return new Set(vars.map(v => v.key));
+}

package/src/report.ts

@@ -0,0 +1,86 @@
+import { ValidationResult, ValidationIssue } from './rules';
+
+const colors = {
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+};
+
+function formatIssue(issue: ValidationIssue, isError: boolean): string {
+    const icon = isError ? '❌' : '⚠️';
+    const color = isError ? colors.red : colors.yellow;
+    const lineInfo = (issue.line && !issue.hasInlineLineInfo) ? ` ${colors.dim}(line ${issue.line})${colors.reset}` : '';
+
+    return `${icon} ${color}${issue.message}${colors.reset}${lineInfo}`;
+}
+
+export function printReport(result: ValidationResult): void {
+    const { errors, warnings } = result;
+    const total = errors.length + warnings.length;
+
+    console.log('');
+    console.log(`${colors.bold}🔍 env-guard validation report${colors.reset}`);
+    console.log('');
+
+    if (errors.length > 0) {
+        console.log(`${colors.red}${colors.bold}Errors (${errors.length})${colors.reset}`);
+        for (const error of errors) {
+            console.log(`  ${formatIssue(error, true)}`);
+        }
+        console.log('');
+    }
+
+    if (warnings.length > 0) {
+        console.log(`${colors.yellow}${colors.bold}Warnings (${warnings.length})${colors.reset}`);
+        for (const warning of warnings) {
+            console.log(`  ${formatIssue(warning, false)}`);
+        }
+        console.log('');
+    }
+
+    // Summary
+    if (total === 0) {
+        console.log(`${colors.green}✅ No issues found${colors.reset}`);
+    } else {
+        console.log(`${colors.dim}─────────────────────────────${colors.reset}`);
+        console.log(`Total: ${errors.length} error(s), ${warnings.length} warning(s)`);
+    }
+
+    // One-line summary for logs
+    console.log('');
+    console.log(`env-guard: ${errors.length} errors, ${warnings.length} warnings`);
+}
+
+/**
+ * GitHub Actions annotation format
+ * https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+export function printCi(result: ValidationResult, envFile: string): void {
+    const { errors, warnings } = result;
+
+    // Output GitHub Actions annotations
+    for (const error of errors) {
+        const line = error.line ? `,line=${error.line}` : '';
+        console.log(`::error file=${envFile}${line}::${error.message}`);
+    }
+
+    for (const warning of warnings) {
+        const line = warning.line ? `,line=${warning.line}` : '';
+        console.log(`::warning file=${envFile}${line}::${warning.message}`);
+    }
+
+    // Summary line
+    if (errors.length === 0 && warnings.length === 0) {
+        console.log('env-guard: ✅ No issues found');
+    } else {
+        console.log(`env-guard: ${errors.length} errors, ${warnings.length} warnings`);
+    }
+}
+
+export function printJson(result: ValidationResult): void {
+    console.log(JSON.stringify(result, null, 2));
+}

package/src/rules.ts

@@ -0,0 +1,150 @@
+import { EnvVar } from './parse';
+
+export interface ValidationResult {
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+
+export interface ValidationIssue {
+    type: string;
+    key: string;
+    message: string;
+    line?: number;
+    hasInlineLineInfo?: boolean;
+}
+
+// Keys that should NEVER be empty in production
+const REQUIRED_PATTERNS = [
+    /^DATABASE/i,
+    /^DB_/i,
+    /^API_KEY/i,
+    /^SECRET/i,
+    /^PASSWORD/i,
+];
+
+// Keys that indicate unsafe defaults
+const UNSAFE_DEFAULTS: Record<string, string[]> = {
+    'DEBUG': ['true', '1', 'yes'],
+    'APP_DEBUG': ['true', '1', 'yes'],
+    'NODE_ENV': ['development', 'dev'],
+    'LOG_LEVEL': ['debug', 'trace'],
+};
+
+// Sensitive keys that should be masked in output
+const SENSITIVE_PATTERNS = [
+    /SECRET/i,
+    /PASSWORD/i,
+    /TOKEN/i,
+    /KEY/i,
+    /CREDENTIAL/i,
+    /AUTH/i,
+    /PRIVATE/i,
+];
+
+export function isSensitiveKey(key: string): boolean {
+    return SENSITIVE_PATTERNS.some(pattern => pattern.test(key));
+}
+
+export function maskValue(key: string, value: string): string {
+    if (isSensitiveKey(key)) {
+        if (value.length <= 4) {
+            return '****';
+        }
+        return value.substring(0, 2) + '****' + value.substring(value.length - 2);
+    }
+    return value;
+}
+
+export function validateEnv(
+    envVars: EnvVar[],
+    exampleVars: EnvVar[] | null,
+    strict: boolean = false
+): ValidationResult {
+    const result: ValidationResult = {
+        errors: [],
+        warnings: [],
+    };
+
+    const envKeys = new Set(envVars.map(v => v.key));
+    const exampleKeys = exampleVars ? new Set(exampleVars.map(v => v.key)) : null;
+
+    // Check for missing keys (in example but not in env)
+    if (exampleKeys) {
+        for (const exampleVar of exampleVars!) {
+            if (!envKeys.has(exampleVar.key)) {
+                result.errors.push({
+                    type: 'missing',
+                    key: exampleVar.key,
+                    message: `Missing variable: ${exampleVar.key} (defined in example)`,
+                });
+            }
+        }
+    }
+
+    // Check for duplicates
+    const seen = new Map<string, number>();
+    for (const envVar of envVars) {
+        if (seen.has(envVar.key)) {
+            result.errors.push({
+                type: 'duplicate',
+                key: envVar.key,
+                message: `Duplicate key: ${envVar.key} (lines ${seen.get(envVar.key)} and ${envVar.line})`,
+                line: envVar.line,
+                hasInlineLineInfo: true,
+            });
+        }
+        seen.set(envVar.key, envVar.line);
+    }
+
+    // Check for empty values
+    for (const envVar of envVars) {
+        if (envVar.value === '' || envVar.value.trim() === '') {
+            const isRequired = REQUIRED_PATTERNS.some(p => p.test(envVar.key));
+
+            if (isRequired || strict) {
+                result.errors.push({
+                    type: 'empty',
+                    key: envVar.key,
+                    message: `Empty value: ${envVar.key}`,
+                    line: envVar.line,
+                });
+            } else {
+                result.warnings.push({
+                    type: 'empty',
+                    key: envVar.key,
+                    message: `Empty value: ${envVar.key}`,
+                    line: envVar.line,
+                });
+            }
+        }
+    }
+
+    // Check for unused keys (in env but not in example)
+    if (exampleKeys) {
+        for (const envVar of envVars) {
+            if (!exampleKeys.has(envVar.key)) {
+                result.warnings.push({
+                    type: 'unused',
+                    key: envVar.key,
+                    message: `Unused variable: ${envVar.key} (not in example)`,
+                    line: envVar.line,
+                });
+            }
+        }
+    }
+
+    // Check for unsafe defaults
+    for (const envVar of envVars) {
+        const unsafeValues = UNSAFE_DEFAULTS[envVar.key];
+        if (unsafeValues && unsafeValues.includes(envVar.value.toLowerCase())) {
+            result.warnings.push({
+                type: 'unsafe',
+                key: envVar.key,
+                message: `Unsafe default: ${envVar.key}=${envVar.value} (may not be suitable for production)`,
+                line: envVar.line,
+            });
+        }
+    }
+
+    return result;
+}

package/test/.env.example

@@ -0,0 +1,8 @@
+# Example .env file
+APP_NAME=
+APP_ENV=
+APP_DEBUG=
+DATABASE_URL=
+API_KEY=
+SECRET_TOKEN=
+MISSING_VAR=

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "commonjs",
+        "lib": [
+            "ES2022"
+        ],
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "declaration": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}