@claude-agent/envcheck 1.4.0 → 1.5.0

package/README.md

@@ -4,9 +4,9 @@
 [![npm downloads](https://img.shields.io/npm/dm/@claude-agent/envcheck.svg)](https://www.npmjs.com/package/@claude-agent/envcheck)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> Validate .env files, compare with .env.example, find missing or empty variables.
+> Validate .env files, compare with .env.example, find missing or empty variables. **Now with monorepo support!**
 
-Never deploy with missing environment variables again.
+Never deploy with missing environment variables again. Works across entire monorepos with a single command.
 
 **Built autonomously by [Claude](https://claude.ai)** - an AI assistant by Anthropic.
 
@@ -34,6 +34,9 @@ envcheck .env.production
 # Require specific variables
 envcheck -r "DATABASE_URL,API_KEY"
 
+# Scan entire monorepo
+envcheck monorepo
+
 # Compare two files
 envcheck compare .env .env.staging
 
@@ -101,6 +104,104 @@ envcheck list .env -j
 envcheck get .env DATABASE_URL
 ```
 
+### Monorepo Command
+
+Scan all apps and packages in a monorepo with a single command:
+
+```bash
+# Scan from current directory
+envcheck monorepo
+
+# Scan specific directory
+envcheck monorepo ./my-monorepo
+
+# With verbose output (shows all issues per app)
+envcheck monorepo --verbose
+
+# JSON output for CI/CD
+envcheck monorepo --json
+
+# Enable secret detection
+envcheck monorepo --secrets
+```
+
+## Monorepo Support
+
+envcheck can scan entire monorepos, validating environment variables across all apps and packages.
+
+### Supported Structures
+
+envcheck automatically detects these common monorepo patterns:
+
+```
+my-monorepo/
+├── apps/
+│   ├── web/          # ✓ Scanned
+│   │   ├── .env
+│   │   └── .env.example
+│   └── api/          # ✓ Scanned
+│       ├── .env
+│       └── .env.example
+├── packages/
+│   ├── shared/       # ○ Skipped (no .env.example)
+│   └── utils/        # ✓ Scanned
+│       ├── .env
+│       └── .env.example
+└── .env.example      # ✓ Root included if exists
+```
+
+Supported directories: `apps/`, `packages/`, `workspaces/`, `services/`, `libs/`
+
+### Example Output
+
+```
+$ envcheck monorepo
+
+Monorepo Environment Check
+Root: /path/to/monorepo
+
+✓ apps/web: passed
+✗ apps/api: 1 error(s)
+○ packages/shared: skipped (No .env.example found)
+✓ packages/utils: passed
+
+Summary: 4 apps scanned
+  ✓ 2 passed
+  ✗ 1 failed
+  ○ 1 skipped
+
+✗ 1 error(s), 0 warning(s)
+```
+
+### Consistency Checks
+
+envcheck can detect inconsistencies across apps:
+
+- **Shared variables** - Track which variables appear in multiple apps
+- **Type mismatches** - Detect when the same variable has different type hints in different apps
+
+```javascript
+const { scanMonorepo } = require('@claude-agent/envcheck');
+
+const result = scanMonorepo('.', { checkConsistency: true });
+
+console.log(result.consistency.sharedVars);
+// { API_URL: ['apps/web', 'apps/api'] }
+
+console.log(result.consistency.mismatches);
+// [{ variable: 'API_URL', issue: 'type_mismatch', details: [...] }]
+```
+
+### GitHub Action for Monorepos
+
+```yaml
+- name: Validate all environment files
+  uses: claude-agent-tools/envcheck@v1
+  with:
+    monorepo: 'true'
+    strict: 'true'
+```
+
 ## API Usage
 
 ```javascript
@@ -357,22 +458,24 @@ WITH_EQUALS=postgres://user:pass@host/db?opt=val
 - **Auto-detection** - Finds .env.example automatically
 - **CI-friendly** - Exit codes and JSON output
 - **Comprehensive** - Parse, validate, compare, generate
-- **Well-tested** - 72 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) |
-| **Secret detection** | ✅ | ❌ | ❌ |
-| 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.
+- **Monorepo support** - Scan all apps/packages in one command
+- **Well-tested** - 87 tests covering edge cases
+
+## vs. dotenv-safe / envalid / dotenv-mono
+
+| Feature | envcheck | dotenv-safe | envalid | dotenv-mono |
+|---------|----------|-------------|---------|-------------|
+| Validates presence | ✅ | ✅ | ✅ | ❌ |
+| Based on .env.example | ✅ | ✅ | ❌ (schema) | ❌ |
+| **Static validation** | ✅ | ❌ | ❌ | ❌ |
+| **CI/CD integration** | ✅ GitHub Action | ❌ | ❌ | ❌ |
+| **Pre-commit hook** | ✅ | ❌ | ❌ | ❌ |
+| Type validation | ✅ (static) | ❌ | ✅ (runtime) | ❌ |
+| **Secret detection** | ✅ | ❌ | ❌ | ❌ |
+| **Monorepo scan** | ✅ | ❌ | ❌ | ❌ |
+| Zero dependencies | ✅ | ❌ | ❌ | ❌ |
+
+**Key difference:** envcheck validates *before* deployment (shift-left), while dotenv-safe and envalid validate at runtime when your app starts. dotenv-mono helps load env vars in monorepos but doesn't validate them. envcheck is the only tool that validates across entire monorepos with a single command.
 
 ## License
 

package/bin/cli.js

@@ -1,21 +1,23 @@
 #!/usr/bin/env node
 'use strict';
 
-const { check, compare, validate, list, get, readEnvFile } = require('../src/index.js');
+const { check, compare, validate, list, get, readEnvFile, scanMonorepo, formatMonorepoResult } = require('../src/index.js');
 const path = require('path');
 const fs = require('fs');
 
-const VERSION = '1.0.0';
+const VERSION = '1.5.0';
 
 const HELP = `
 envcheck - Validate .env files
 
 USAGE
   envcheck [options] [file]
+  envcheck monorepo [directory]
   envcheck compare <env> <example>
 
 COMMANDS
   check (default)    Check .env file, optionally against .env.example
+  monorepo           Scan all apps/packages in a monorepo
   compare            Compare two env files
   list               List variables in a file
   get <key>          Get a specific variable value
@@ -26,6 +28,8 @@ OPTIONS
   --no-empty             Warn on empty values
   --no-extra             Error on variables not in example
   --strict               Treat warnings as errors
+  --secrets              Enable secret detection (warn about real secrets)
+  --verbose              Show detailed output (monorepo mode)
   -q, --quiet            Only output errors
   -j, --json             Output as JSON
   -v, --version          Show version
@@ -35,6 +39,9 @@ EXAMPLES
   envcheck                          Check .env against .env.example
   envcheck .env.production          Check specific file
   envcheck -r "API_KEY,DB_URL"      Require specific variables
+  envcheck monorepo                 Scan monorepo from current directory
+  envcheck monorepo ./my-monorepo   Scan specific directory
+  envcheck monorepo --verbose       Show all issues per app
   envcheck compare .env .env.prod   Compare two files
   envcheck list .env                List all variables
   envcheck get .env API_KEY         Get specific value
@@ -51,6 +58,8 @@ function parseArgs(args) {
     strict: false,
     quiet: false,
     json: false,
+    verbose: false,
+    detectSecrets: false,
     args: []
   };
 
@@ -78,11 +87,15 @@ function parseArgs(args) {
       result.noExtra = true;
     } else if (arg === '--strict') {
       result.strict = true;
+    } else if (arg === '--secrets') {
+      result.detectSecrets = true;
+    } else if (arg === '--verbose') {
+      result.verbose = true;
     } else if (arg === '-q' || arg === '--quiet') {
       result.quiet = true;
     } else if (arg === '-j' || arg === '--json') {
       result.json = true;
-    } else if (arg === 'compare' || arg === 'list' || arg === 'get') {
+    } else if (arg === 'compare' || arg === 'list' || arg === 'get' || arg === 'monorepo') {
       result.command = arg;
     } else if (!arg.startsWith('-')) {
       result.args.push(arg);
@@ -277,6 +290,32 @@ function runGet(opts) {
   return 0;
 }
 
+function runMonorepo(opts) {
+  const rootDir = opts.args[0] || '.';
+
+  const result = scanMonorepo(rootDir, {
+    noEmpty: opts.noEmpty,
+    noExtra: opts.noExtra,
+    strict: opts.strict,
+    detectSecrets: opts.detectSecrets,
+    checkConsistency: true
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.valid ? 0 : 1;
+  }
+
+  // Use formatted output
+  const output = formatMonorepoResult(result, {
+    colors: !opts.quiet,
+    verbose: opts.verbose
+  });
+  console.log(output);
+
+  return result.valid ? 0 : 1;
+}
+
 function main() {
   const args = process.argv.slice(2);
   const opts = parseArgs(args);
@@ -287,6 +326,9 @@ function main() {
     case 'check':
       exitCode = runCheck(opts);
       break;
+    case 'monorepo':
+      exitCode = runMonorepo(opts);
+      break;
     case 'compare':
       exitCode = runCompare(opts);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-agent/envcheck",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Validate .env files, compare with .env.example, find missing or empty variables",
   "main": "src/index.js",
   "bin": {
@@ -22,7 +22,10 @@
     "pre-commit",
     "git-hooks",
     "secrets",
-    "security"
+    "security",
+    "monorepo",
+    "turborepo",
+    "workspaces"
   ],
   "author": "Claude Agent <claude-agent@agentmail.to>",
   "license": "MIT",

package/src/index.js

@@ -683,6 +683,278 @@ function get(filePath, key) {
   return env.variables[key];
 }
 
+/**
+ * Find directories that might contain apps/packages in a monorepo
+ * @param {string} rootDir - Root directory to scan
+ * @returns {string[]} Array of directory paths
+ */
+function findMonorepoApps(rootDir) {
+  const apps = [];
+  const basePath = path.resolve(rootDir);
+
+  // Common monorepo patterns
+  const patterns = ['apps', 'packages', 'workspaces', 'services', 'libs'];
+
+  for (const pattern of patterns) {
+    const dir = path.join(basePath, pattern);
+    if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
+      // Get all subdirectories
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          apps.push(path.join(dir, entry.name));
+        }
+      }
+    }
+  }
+
+  // Also check root for .env.example (some monorepos have root-level env)
+  if (fs.existsSync(path.join(basePath, '.env.example')) ||
+      fs.existsSync(path.join(basePath, '.env'))) {
+    apps.unshift(basePath);
+  }
+
+  return apps;
+}
+
+/**
+ * Scan a monorepo for env file issues
+ * @param {string} rootDir - Root directory of monorepo
+ * @param {Object} options - Scan options
+ * @returns {Object} Monorepo scan result
+ */
+function scanMonorepo(rootDir, options = {}) {
+  const {
+    noEmpty = false,
+    noExtra = false,
+    strict = false,
+    checkConsistency = true,
+    detectSecrets = false
+  } = options;
+
+  const basePath = path.resolve(rootDir);
+  const apps = findMonorepoApps(basePath);
+
+  const result = {
+    root: basePath,
+    valid: true,
+    apps: [],
+    summary: {
+      total: apps.length,
+      passed: 0,
+      failed: 0,
+      skipped: 0,
+      errors: 0,
+      warnings: 0
+    },
+    consistency: {
+      sharedVars: {},  // Variables that appear in multiple apps
+      mismatches: []   // Variables with different types/values across apps
+    }
+  };
+
+  // Track all variables across apps for consistency checking
+  const allVars = {};  // { varName: [{ app, value, type }] }
+
+  for (const appDir of apps) {
+    const appName = path.relative(basePath, appDir) || '.';
+    const envPath = path.join(appDir, '.env');
+    const examplePath = path.join(appDir, '.env.example');
+
+    const appResult = {
+      name: appName,
+      path: appDir,
+      hasEnv: fs.existsSync(envPath),
+      hasExample: fs.existsSync(examplePath),
+      valid: true,
+      issues: [],
+      variables: []
+    };
+
+    // Skip if no example file (can't validate)
+    if (!appResult.hasExample) {
+      appResult.skipped = true;
+      appResult.reason = 'No .env.example found';
+      result.apps.push(appResult);
+      result.summary.skipped++;
+      continue;
+    }
+
+    // If no .env but has example, that's also a problem
+    if (!appResult.hasEnv) {
+      appResult.valid = false;
+      appResult.issues.push({
+        type: 'warning',
+        message: 'No .env file found (but .env.example exists)'
+      });
+    }
+
+    // Run check if both files exist
+    if (appResult.hasEnv) {
+      const checkResult = check(envPath, {
+        examplePath,
+        noEmpty,
+        noExtra,
+        strict,
+        validateTypes: true,
+        detectSecrets
+      });
+
+      appResult.valid = checkResult.valid;
+      appResult.issues = checkResult.issues;
+      appResult.variables = Object.keys(checkResult.env?.variables || {});
+
+      // Track variables for consistency check
+      if (checkConsistency && checkResult.env?.variables) {
+        const example = readEnvFile(examplePath);
+        for (const [varName, value] of Object.entries(checkResult.env.variables)) {
+          if (!allVars[varName]) {
+            allVars[varName] = [];
+          }
+          allVars[varName].push({
+            app: appName,
+            value,
+            type: example.typeHints?.[varName] || null
+          });
+        }
+      }
+    }
+
+    // Update summary
+    if (appResult.skipped) {
+      // Already counted above
+    } else if (appResult.valid) {
+      result.summary.passed++;
+    } else {
+      result.summary.failed++;
+      result.valid = false;
+    }
+
+    const errors = appResult.issues.filter(i => i.type === 'error').length;
+    const warnings = appResult.issues.filter(i => i.type === 'warning').length;
+    result.summary.errors += errors;
+    result.summary.warnings += warnings;
+
+    result.apps.push(appResult);
+  }
+
+  // Check consistency across apps
+  if (checkConsistency) {
+    for (const [varName, occurrences] of Object.entries(allVars)) {
+      if (occurrences.length > 1) {
+        result.consistency.sharedVars[varName] = occurrences.map(o => o.app);
+
+        // Check for type mismatches
+        const types = new Set(occurrences.map(o => o.type).filter(Boolean));
+        if (types.size > 1) {
+          result.consistency.mismatches.push({
+            variable: varName,
+            issue: 'type_mismatch',
+            details: occurrences.map(o => ({ app: o.app, type: o.type }))
+          });
+          result.valid = false;
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format monorepo result for CLI output
+ * @param {Object} result - Monorepo scan result
+ * @param {Object} options - Format options
+ * @returns {string} Formatted output
+ */
+function formatMonorepoResult(result, options = {}) {
+  const { colors = true, verbose = false } = options;
+
+  const c = colors ? {
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    dim: '\x1b[2m',
+    reset: '\x1b[0m',
+    bold: '\x1b[1m'
+  } : { green: '', red: '', yellow: '', dim: '', reset: '', bold: '' };
+
+  const lines = [];
+
+  lines.push(`${c.bold}Monorepo Environment Check${c.reset}`);
+  lines.push(`Root: ${result.root}`);
+  lines.push('');
+
+  for (const app of result.apps) {
+    const icon = app.skipped ? `${c.dim}○${c.reset}` :
+                 app.valid ? `${c.green}✓${c.reset}` :
+                 `${c.red}✗${c.reset}`;
+
+    let status = '';
+    if (app.skipped) {
+      status = `${c.dim}skipped (${app.reason})${c.reset}`;
+    } else {
+      const errors = app.issues.filter(i => i.type === 'error').length;
+      const warnings = app.issues.filter(i => i.type === 'warning').length;
+
+      if (errors === 0 && warnings === 0) {
+        status = `${c.green}passed${c.reset}`;
+      } else if (errors > 0) {
+        status = `${c.red}${errors} error(s)${c.reset}`;
+        if (warnings > 0) status += `, ${c.yellow}${warnings} warning(s)${c.reset}`;
+      } else {
+        status = `${c.yellow}${warnings} warning(s)${c.reset}`;
+      }
+    }
+
+    lines.push(`${icon} ${app.name}: ${status}`);
+
+    // Show details in verbose mode
+    if (verbose && !app.skipped && app.issues.length > 0) {
+      for (const issue of app.issues) {
+        const prefix = issue.type === 'error' ? `${c.red}  ✗${c.reset}` : `${c.yellow}  !${c.reset}`;
+        lines.push(`${prefix} ${issue.message}`);
+      }
+    }
+  }
+
+  lines.push('');
+
+  // Summary
+  lines.push(`${c.bold}Summary:${c.reset} ${result.summary.total} apps scanned`);
+  if (result.summary.passed > 0) {
+    lines.push(`  ${c.green}✓${c.reset} ${result.summary.passed} passed`);
+  }
+  if (result.summary.failed > 0) {
+    lines.push(`  ${c.red}✗${c.reset} ${result.summary.failed} failed`);
+  }
+  if (result.summary.skipped > 0) {
+    lines.push(`  ${c.dim}○${c.reset} ${result.summary.skipped} skipped`);
+  }
+
+  // Consistency issues
+  if (result.consistency.mismatches.length > 0) {
+    lines.push('');
+    lines.push(`${c.yellow}Consistency Issues:${c.reset}`);
+    for (const mismatch of result.consistency.mismatches) {
+      lines.push(`  ${c.yellow}!${c.reset} ${mismatch.variable}: ${mismatch.issue}`);
+      for (const detail of mismatch.details) {
+        lines.push(`    - ${detail.app}: type=${detail.type || 'unspecified'}`);
+      }
+    }
+  }
+
+  // Final status
+  lines.push('');
+  if (result.valid) {
+    lines.push(`${c.green}✓ All checks passed${c.reset}`);
+  } else {
+    lines.push(`${c.red}✗ ${result.summary.errors} error(s), ${result.summary.warnings} warning(s)${c.reset}`);
+  }
+
+  return lines.join('\n');
+}
+
 module.exports = {
   parse: parseEnv,
   parseValue,
@@ -697,5 +969,9 @@ module.exports = {
   check,
   generate,
   list,
-  get
+  get,
+  // Monorepo support
+  findMonorepoApps,
+  scanMonorepo,
+  formatMonorepoResult
 };