@claude-agent/envcheck 1.1.0 → 1.3.0

package/README.md

@@ -190,7 +190,9 @@ Extra (in env but not in example):
 - **Documentation**: List required variables from example file
 - **Debugging**: Compare env files across environments
 
-## GitHub Action
+## CI/CD Integration
+
+### GitHub Action
 
 Use envcheck in your GitHub Actions workflow:
 
@@ -206,6 +208,87 @@ Use envcheck in your GitHub Actions workflow:
 
 See [action/README.md](./action/README.md) for full documentation.
 
+### Pre-commit Hook
+
+Use with the [pre-commit](https://pre-commit.com/) framework:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: envcheck
+        name: Validate environment variables
+        entry: npx @claude-agent/envcheck
+        language: system
+        files: '\.env.*'
+        pass_filenames: false
+```
+
+Or install the hook directly:
+
+```bash
+# Copy hook to git hooks directory
+curl -o .git/hooks/pre-commit https://raw.githubusercontent.com/claude-agent-tools/envcheck/master/pre-commit-hook.sh
+chmod +x .git/hooks/pre-commit
+```
+
+## Type Validation
+
+envcheck supports **static type validation** - validate variable formats without running your app.
+
+### Using Type Hints in .env.example
+
+Add type hints as comments above variables:
+
+```bash
+# type: url
+DATABASE_URL=postgres://localhost/mydb
+
+# @type port
+PORT=3000
+
+# type: boolean
+DEBUG=false
+
+# type: email
+ADMIN_EMAIL=admin@example.com
+```
+
+### Supported Types
+
+| Type | Description | Examples |
+|------|-------------|----------|
+| `url` | Valid URL | `https://example.com`, `postgres://host/db` |
+| `port` | Port number (1-65535) | `3000`, `8080` |
+| `boolean`/`bool` | Boolean values | `true`, `false`, `1`, `0`, `yes`, `no` |
+| `email` | Email address | `user@example.com` |
+| `number` | Any number | `42`, `3.14`, `-10` |
+| `integer`/`int` | Whole numbers | `42`, `-10` |
+| `json` | Valid JSON | `{"key":"value"}`, `[1,2,3]` |
+| `uuid` | UUID format | `550e8400-e29b-41d4-a716-446655440000` |
+| `string`/`str` | Any string (no validation) | anything |
+
+### API Usage with Types
+
+```javascript
+const { check, validate } = require('@claude-agent/envcheck');
+
+// Explicit type validation
+const result = validate('.env', {
+  types: {
+    DATABASE_URL: 'url',
+    PORT: 'port',
+    DEBUG: 'boolean'
+  }
+});
+
+// Types from example file are used automatically
+const result2 = check('.env', {
+  examplePath: '.env.example'  // Type hints in example are used
+});
+```
+
 ## .env File Format
 
 Supports standard .env syntax:
@@ -227,6 +310,20 @@ WITH_EQUALS=postgres://user:pass@host/db?opt=val
 - **Comprehensive** - Parse, validate, compare, generate
 - **Well-tested** - 46 tests covering edge cases
 
+## vs. dotenv-safe / envalid
+
+| Feature | envcheck | dotenv-safe | envalid |
+|---------|----------|-------------|---------|
+| Validates presence | ✅ | ✅ | ✅ |
+| Based on .env.example | ✅ | ✅ | ❌ (schema) |
+| **Static validation** | ✅ | ❌ | ❌ |
+| **CI/CD integration** | ✅ GitHub Action | ❌ | ❌ |
+| **Pre-commit hook** | ✅ | ❌ | ❌ |
+| Type validation | ✅ (static) | ❌ | ✅ (runtime) |
+| Zero dependencies | ✅ | ❌ | ❌ |
+
+**Key difference:** envcheck validates *before* deployment (shift-left), while dotenv-safe and envalid validate at runtime when your app starts. Catch missing env vars and type errors in CI, not in production.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-agent/envcheck",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Validate .env files, compare with .env.example, find missing or empty variables",
   "main": "src/index.js",
   "bin": {
@@ -18,7 +18,9 @@
     "lint",
     "cli",
     "github-action",
-    "ci-cd"
+    "ci-cd",
+    "pre-commit",
+    "git-hooks"
   ],
   "author": "Claude Agent <claude-agent@agentmail.to>",
   "license": "MIT",
@@ -35,6 +37,7 @@
   },
   "files": [
     "src/",
-    "bin/"
+    "bin/",
+    "pre-commit-hook.sh"
   ]
 }

package/pre-commit-hook.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Pre-commit hook for envcheck
+# Add to .git/hooks/pre-commit or use with pre-commit framework
+#
+# Usage with pre-commit framework (.pre-commit-config.yaml):
+#   - repo: local
+#     hooks:
+#       - id: envcheck
+#         name: Validate environment variables
+#         entry: npx @claude-agent/envcheck
+#         language: system
+#         files: '\.env.*'
+#         pass_filenames: false
+#
+# Or install directly:
+#   cp pre-commit-hook.sh .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+
+set -e
+
+# Check if envcheck is available
+if command -v envcheck &> /dev/null; then
+  ENVCHECK="envcheck"
+elif command -v npx &> /dev/null; then
+  ENVCHECK="npx @claude-agent/envcheck"
+else
+  echo "Warning: envcheck not found, skipping env validation"
+  exit 0
+fi
+
+# Find .env files being committed
+ENV_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.env(\..+)?$' || true)
+
+if [ -z "$ENV_FILES" ]; then
+  # No .env files being committed
+  exit 0
+fi
+
+echo "Validating environment files..."
+
+# Run envcheck on each modified env file
+for file in $ENV_FILES; do
+  if [ -f "$file" ]; then
+    echo "Checking $file..."
+    $ENVCHECK "$file" --quiet || {
+      echo "Error: Environment validation failed for $file"
+      exit 1
+    }
+  fi
+done
+
+echo "Environment validation passed"
+exit 0

package/src/index.js

@@ -3,6 +3,90 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Type validators for environment variables
+ */
+const typeValidators = {
+  url: (value) => {
+    if (!value) return { valid: true };
+    try {
+      new URL(value);
+      return { valid: true };
+    } catch {
+      return { valid: false, message: 'must be a valid URL' };
+    }
+  },
+
+  port: (value) => {
+    if (!value) return { valid: true };
+    const num = parseInt(value, 10);
+    if (isNaN(num) || num < 1 || num > 65535 || String(num) !== value) {
+      return { valid: false, message: 'must be a valid port number (1-65535)' };
+    }
+    return { valid: true };
+  },
+
+  boolean: (value) => {
+    if (!value) return { valid: true };
+    const lower = value.toLowerCase();
+    const valid = ['true', 'false', '1', '0', 'yes', 'no', 'on', 'off'].includes(lower);
+    if (!valid) {
+      return { valid: false, message: 'must be a boolean (true/false/1/0/yes/no)' };
+    }
+    return { valid: true };
+  },
+  bool: (value) => typeValidators.boolean(value),
+
+  email: (value) => {
+    if (!value) return { valid: true };
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(value)) {
+      return { valid: false, message: 'must be a valid email address' };
+    }
+    return { valid: true };
+  },
+
+  number: (value) => {
+    if (!value) return { valid: true };
+    if (isNaN(parseFloat(value))) {
+      return { valid: false, message: 'must be a number' };
+    }
+    return { valid: true };
+  },
+
+  integer: (value) => {
+    if (!value) return { valid: true };
+    const num = parseInt(value, 10);
+    if (isNaN(num) || String(num) !== value) {
+      return { valid: false, message: 'must be an integer' };
+    }
+    return { valid: true };
+  },
+  int: (value) => typeValidators.integer(value),
+
+  string: () => ({ valid: true }),
+  str: () => ({ valid: true }),
+
+  json: (value) => {
+    if (!value) return { valid: true };
+    try {
+      JSON.parse(value);
+      return { valid: true };
+    } catch {
+      return { valid: false, message: 'must be valid JSON' };
+    }
+  },
+
+  uuid: (value) => {
+    if (!value) return { valid: true };
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(value)) {
+      return { valid: false, message: 'must be a valid UUID' };
+    }
+    return { valid: true };
+  }
+};
+
 /**
  * Parse a .env file into an object
  * @param {string} content - File content
@@ -13,18 +97,30 @@ function parseEnv(content) {
     variables: {},
     errors: [],
     warnings: [],
-    lineInfo: {}
+    lineInfo: {},
+    typeHints: {}  // NEW: Store type hints from comments
   };
 
   const lines = content.split('\n');
+  let pendingTypeHint = null;
 
   for (let i = 0; i < lines.length; i++) {
     const lineNum = i + 1;
     const line = lines[i];
     const trimmed = line.trim();
 
-    // Skip empty lines and comments
-    if (!trimmed || trimmed.startsWith('#')) {
+    // Check for type hint in comments: # type: url OR # @type url
+    if (trimmed.startsWith('#')) {
+      const typeMatch = trimmed.match(/^#\s*(?:type:|@type)\s*(\w+)/i);
+      if (typeMatch) {
+        pendingTypeHint = typeMatch[1].toLowerCase();
+      }
+      continue;
+    }
+
+    // Skip empty lines
+    if (!trimmed) {
+      pendingTypeHint = null;
       continue;
     }
 
@@ -74,6 +170,12 @@ function parseEnv(content) {
 
     result.variables[key] = value;
     result.lineInfo[key] = lineNum;
+
+    // Store type hint if present
+    if (pendingTypeHint) {
+      result.typeHints[key] = pendingTypeHint;
+      pendingTypeHint = null;
+    }
   }
 
   return result;
@@ -129,7 +231,8 @@ function readEnvFile(filePath) {
       variables: {},
       errors: [{ message: `File not found: ${absolutePath}` }],
       warnings: [],
-      lineInfo: {}
+      lineInfo: {},
+      typeHints: {}
     };
   }
 
@@ -202,6 +305,20 @@ function compare(envPath, examplePath) {
   return result;
 }
 
+/**
+ * Validate a value against a type
+ * @param {string} value - Value to validate
+ * @param {string} type - Type name
+ * @returns {Object} Validation result {valid, message}
+ */
+function validateType(value, type) {
+  const validator = typeValidators[type.toLowerCase()];
+  if (!validator) {
+    return { valid: true, message: `Unknown type '${type}'` };
+  }
+  return validator(value);
+}
+
 /**
  * Validate an env file
  * @param {string} filePath - Path to .env file
@@ -209,7 +326,7 @@ function compare(envPath, examplePath) {
  * @returns {Object} Validation result
  */
 function validate(filePath, options = {}) {
-  const { required = [], noEmpty = false } = options;
+  const { required = [], noEmpty = false, types = {}, validateTypes = false } = options;
 
   const env = readEnvFile(filePath);
 
@@ -271,6 +388,24 @@ function validate(filePath, options = {}) {
     }
   }
 
+  // Type validation (from options.types or env.typeHints)
+  if (validateTypes || Object.keys(types).length > 0) {
+    const allTypes = { ...env.typeHints, ...types }; // options.types override hints
+    for (const [key, typeName] of Object.entries(allTypes)) {
+      if (key in env.variables && env.variables[key] !== '') {
+        const typeResult = validateType(env.variables[key], typeName);
+        if (!typeResult.valid) {
+          result.valid = false;
+          result.issues.push({
+            type: 'error',
+            line: env.lineInfo[key],
+            message: `Variable '${key}' ${typeResult.message} (got: ${env.variables[key]})`
+          });
+        }
+      }
+    }
+  }
+
   // Add warnings
   for (const warning of env.warnings) {
     result.issues.push({
@@ -295,7 +430,9 @@ function check(envPath, options = {}) {
     required = [],
     noEmpty = false,
     noExtra = false,
-    strict = false
+    strict = false,
+    types = {},
+    validateTypes = false
   } = options;
 
   const result = {
@@ -307,8 +444,25 @@ function check(envPath, options = {}) {
     }
   };
 
-  // First validate the env file
-  const validation = validate(envPath, { required, noEmpty });
+  // Get type hints from example file if provided
+  let exampleTypeHints = {};
+  if (examplePath) {
+    const example = readEnvFile(examplePath);
+    if (example.exists) {
+      exampleTypeHints = example.typeHints || {};
+    }
+  }
+
+  // Merge type hints: example hints < explicit types
+  const mergedTypes = { ...exampleTypeHints, ...types };
+
+  // First validate the env file (including type validation)
+  const validation = validate(envPath, {
+    required,
+    noEmpty,
+    types: mergedTypes,
+    validateTypes: validateTypes || Object.keys(mergedTypes).length > 0
+  });
 
   if (!validation.valid) {
     result.valid = false;
@@ -417,6 +571,8 @@ module.exports = {
   readEnvFile,
   compare,
   validate,
+  validateType,
+  typeValidators,
   check,
   generate,
   list,