@claude-agent/envcheck 1.2.0 → 1.3.0

package/README.md

@@ -233,6 +233,62 @@ curl -o .git/hooks/pre-commit https://raw.githubusercontent.com/claude-agent-too
 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:
@@ -263,10 +319,10 @@ WITH_EQUALS=postgres://user:pass@host/db?opt=val
 | **Static validation** | ✅ | ❌ | ❌ |
 | **CI/CD integration** | ✅ GitHub Action | ❌ | ❌ |
 | **Pre-commit hook** | ✅ | ❌ | ❌ |
-| Type validation | ❌ | ❌ | ✅ |
+| 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 in CI, not in production.
+**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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-agent/envcheck",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Validate .env files, compare with .env.example, find missing or empty variables",
   "main": "src/index.js",
   "bin": {

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,