@claude-agent/envcheck 1.4.0 → 1.5.1

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,8 +1,9 @@
 {
   "name": "@claude-agent/envcheck",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Validate .env files, compare with .env.example, find missing or empty variables",
   "main": "src/index.js",
+  "types": "types/index.d.ts",
   "bin": {
     "envcheck": "bin/cli.js"
   },
@@ -22,7 +23,10 @@
     "pre-commit",
     "git-hooks",
     "secrets",
-    "security"
+    "security",
+    "monorepo",
+    "turborepo",
+    "workspaces"
   ],
   "author": "Claude Agent <claude-agent@agentmail.to>",
   "license": "MIT",
@@ -40,6 +44,10 @@
   "files": [
     "src/",
     "bin/",
+    "types/",
     "pre-commit-hook.sh"
-  ]
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
 }

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
 };

package/types/index.d.ts

@@ -0,0 +1,431 @@
+/**
+ * Type definitions for @claude-agent/envcheck
+ * Static environment variable validation for Node.js
+ */
+
+// ============================================================================
+// Basic Types
+// ============================================================================
+
+/**
+ * Validation type names supported by envcheck
+ */
+export type ValidationType =
+  | 'url'
+  | 'port'
+  | 'boolean'
+  | 'bool'
+  | 'email'
+  | 'number'
+  | 'integer'
+  | 'int'
+  | 'string'
+  | 'str'
+  | 'json'
+  | 'uuid';
+
+/**
+ * Issue severity level
+ */
+export type IssueType = 'error' | 'warning';
+
+/**
+ * Issue found during validation
+ */
+export interface Issue {
+  type: IssueType;
+  message: string;
+  line?: number;
+}
+
+/**
+ * Result of type validation
+ */
+export interface TypeValidationResult {
+  valid: boolean;
+  message?: string;
+}
+
+/**
+ * Type validator function
+ */
+export type TypeValidator = (value: string) => TypeValidationResult;
+
+// ============================================================================
+// Parse Types
+// ============================================================================
+
+/**
+ * Result of parsing a .env file
+ */
+export interface ParseResult {
+  variables: Record<string, string>;
+  errors: Array<{
+    line: number;
+    message: string;
+    content: string;
+  }>;
+  warnings: Array<{
+    line: number;
+    message: string;
+    content: string;
+  }>;
+  lineInfo: Record<string, number>;
+  typeHints: Record<string, string>;
+}
+
+/**
+ * Result of reading an env file
+ */
+export interface EnvFileResult extends ParseResult {
+  exists: boolean;
+  path: string;
+}
+
+// ============================================================================
+// Compare Types
+// ============================================================================
+
+/**
+ * Item missing from env file
+ */
+export interface MissingItem {
+  key: string;
+  exampleValue: string;
+  line: number;
+}
+
+/**
+ * Extra item in env file
+ */
+export interface ExtraItem {
+  key: string;
+  value: string;
+  line: number;
+}
+
+/**
+ * Empty item in env file
+ */
+export interface EmptyItem {
+  key: string;
+  line: number;
+}
+
+/**
+ * Result of comparing two env files
+ */
+export interface CompareResult {
+  env: EnvFileResult;
+  example: EnvFileResult;
+  missing: MissingItem[];
+  extra: ExtraItem[];
+  empty: EmptyItem[];
+  different: Array<{
+    key: string;
+    envValue: string;
+    exampleValue: string;
+  }>;
+}
+
+// ============================================================================
+// Validate Types
+// ============================================================================
+
+/**
+ * Options for validate function
+ */
+export interface ValidateOptions {
+  /** List of required variable names */
+  required?: string[];
+  /** Warn on empty values */
+  noEmpty?: boolean;
+  /** Type specifications for variables */
+  types?: Record<string, ValidationType>;
+  /** Enable type validation from hints */
+  validateTypes?: boolean;
+  /** Enable secret detection */
+  detectSecrets?: boolean;
+}
+
+/**
+ * Result of validation
+ */
+export interface ValidateResult {
+  valid: boolean;
+  env: EnvFileResult;
+  issues: Issue[];
+}
+
+// ============================================================================
+// Check Types
+// ============================================================================
+
+/**
+ * Options for check function
+ */
+export interface CheckOptions {
+  /** Path to example file */
+  examplePath?: string;
+  /** List of required variable names */
+  required?: string[];
+  /** Warn on empty values */
+  noEmpty?: boolean;
+  /** Error on extra variables */
+  noExtra?: boolean;
+  /** Treat warnings as errors */
+  strict?: boolean;
+  /** Type specifications for variables */
+  types?: Record<string, ValidationType>;
+  /** Enable type validation */
+  validateTypes?: boolean;
+  /** Enable secret detection */
+  detectSecrets?: boolean;
+}
+
+/**
+ * Result of check function
+ */
+export interface CheckResult {
+  valid: boolean;
+  issues: Issue[];
+  summary: {
+    errors: number;
+    warnings: number;
+  };
+  env?: EnvFileResult;
+  comparison?: CompareResult;
+}
+
+// ============================================================================
+// Secret Detection Types
+// ============================================================================
+
+/**
+ * Secret pattern definition
+ */
+export interface SecretPattern {
+  regex: RegExp;
+  description: string;
+  keyPattern?: RegExp;
+}
+
+/**
+ * Result of secret detection
+ */
+export interface SecretDetectionResult {
+  detected: boolean;
+  description: string;
+  message: string;
+}
+
+// ============================================================================
+// Monorepo Types
+// ============================================================================
+
+/**
+ * Options for monorepo scanning
+ */
+export interface ScanMonorepoOptions {
+  /** Warn on empty values */
+  noEmpty?: boolean;
+  /** Error on extra variables */
+  noExtra?: boolean;
+  /** Treat warnings as errors */
+  strict?: boolean;
+  /** Check consistency across apps */
+  checkConsistency?: boolean;
+  /** Enable secret detection */
+  detectSecrets?: boolean;
+}
+
+/**
+ * Result for a single app in monorepo scan
+ */
+export interface MonorepoAppResult {
+  name: string;
+  path: string;
+  hasEnv: boolean;
+  hasExample: boolean;
+  valid: boolean;
+  issues: Issue[];
+  variables: string[];
+  skipped?: boolean;
+  reason?: string;
+}
+
+/**
+ * Consistency mismatch in monorepo
+ */
+export interface ConsistencyMismatch {
+  variable: string;
+  issue: string;
+  details: Array<{
+    app: string;
+    type: string | null;
+    value?: string;
+  }>;
+}
+
+/**
+ * Result of scanning a monorepo
+ */
+export interface MonorepoScanResult {
+  root: string;
+  valid: boolean;
+  apps: MonorepoAppResult[];
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    errors: number;
+    warnings: number;
+  };
+  consistency: {
+    sharedVars: Record<string, string[]>;
+    mismatches: ConsistencyMismatch[];
+  };
+}
+
+/**
+ * Options for formatting monorepo result
+ */
+export interface FormatMonorepoOptions {
+  /** Enable ANSI colors */
+  colors?: boolean;
+  /** Show detailed issues */
+  verbose?: boolean;
+}
+
+// ============================================================================
+// Exported Functions
+// ============================================================================
+
+/**
+ * Parse .env file content into an object
+ * @param content - Raw .env file content
+ * @returns Parsed result with variables and metadata
+ */
+export function parse(content: string): ParseResult;
+
+/**
+ * Parse a single value, handling quotes and escapes
+ * @param raw - Raw value string
+ * @returns Parsed value
+ */
+export function parseValue(raw: string): string;
+
+/**
+ * Read and parse a .env file
+ * @param filePath - Path to .env file
+ * @returns Parsed file result
+ */
+export function readEnvFile(filePath: string): EnvFileResult;
+
+/**
+ * Compare two env files
+ * @param envPath - Path to .env file
+ * @param examplePath - Path to .env.example file
+ * @returns Comparison result
+ */
+export function compare(envPath: string, examplePath: string): CompareResult;
+
+/**
+ * Validate an env file
+ * @param filePath - Path to .env file
+ * @param options - Validation options
+ * @returns Validation result
+ */
+export function validate(filePath: string, options?: ValidateOptions): ValidateResult;
+
+/**
+ * Validate a value against a type
+ * @param value - Value to validate
+ * @param type - Type name
+ * @returns Validation result
+ */
+export function validateType(value: string, type: ValidationType): TypeValidationResult;
+
+/**
+ * Check an env file against example and validate
+ * @param envPath - Path to .env file
+ * @param options - Check options
+ * @returns Check result
+ */
+export function check(envPath: string, options?: CheckOptions): CheckResult;
+
+/**
+ * Generate a .env file from .env.example
+ * @param examplePath - Path to .env.example
+ * @param defaults - Default values to fill in
+ * @returns Generated .env content
+ */
+export function generate(examplePath: string, defaults?: Record<string, string>): string;
+
+/**
+ * Get list of variable names from file
+ * @param filePath - Path to env file
+ * @returns Array of variable names
+ */
+export function list(filePath: string): string[];
+
+/**
+ * Get a specific variable value
+ * @param filePath - Path to env file
+ * @param key - Variable name
+ * @returns Value or undefined
+ */
+export function get(filePath: string, key: string): string | undefined;
+
+/**
+ * Detect potential secrets in environment variables
+ * @param key - Variable name
+ * @param value - Variable value
+ * @returns Detection result or null if no secret detected
+ */
+export function detectSecret(key: string, value: string): SecretDetectionResult | null;
+
+/**
+ * Check if a value looks like a placeholder
+ * @param value - Value to check
+ * @returns True if it looks like a placeholder
+ */
+export function isPlaceholder(value: string): boolean;
+
+/**
+ * Find directories that might contain apps/packages in a monorepo
+ * @param rootDir - Root directory to scan
+ * @returns Array of directory paths
+ */
+export function findMonorepoApps(rootDir: string): string[];
+
+/**
+ * Scan a monorepo for env file issues
+ * @param rootDir - Root directory of monorepo
+ * @param options - Scan options
+ * @returns Monorepo scan result
+ */
+export function scanMonorepo(rootDir: string, options?: ScanMonorepoOptions): MonorepoScanResult;
+
+/**
+ * Format monorepo result for CLI output
+ * @param result - Monorepo scan result
+ * @param options - Format options
+ * @returns Formatted string
+ */
+export function formatMonorepoResult(result: MonorepoScanResult, options?: FormatMonorepoOptions): string;
+
+// ============================================================================
+// Exported Constants
+// ============================================================================
+
+/**
+ * Map of type names to validator functions
+ */
+export const typeValidators: Record<ValidationType, TypeValidator>;
+
+/**
+ * Array of secret detection patterns
+ */
+export const secretPatterns: SecretPattern[];