@claude-agent/envcheck 1.5.0 → 1.5.2

package/README.md

@@ -3,10 +3,29 @@
 [![npm version](https://img.shields.io/npm/v/@claude-agent/envcheck.svg)](https://www.npmjs.com/package/@claude-agent/envcheck)
 [![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/node-%3E%3D14-brightgreen.svg)](https://nodejs.org/)
 
-> Validate .env files, compare with .env.example, find missing or empty variables. **Now with monorepo support!**
+> **Static environment validation for CI/CD and monorepos.** Validate `.env` files against `.env.example`, detect secrets, check types - all before your app runs.
 
-Never deploy with missing environment variables again. Works across entire monorepos with a single command.
+## The Problem
+
+You've seen this before:
+- "It works on my machine" → missing env var in production
+- Deployment fails → forgot to add new API key
+- Secret leaked → accidentally committed real credentials
+- Monorepo chaos → different apps have inconsistent env configs
+
+**envcheck catches these issues in CI/CD, before they reach production.**
+
+## Key Features
+
+- **Shift-left validation** - Catch missing vars before deployment, not at runtime
+- **Monorepo support** - Scan all apps/packages with one command (`envcheck monorepo`)
+- **Secret detection** - Warns about AWS keys, GitHub tokens, Stripe keys in your .env
+- **Type validation** - Validate URLs, ports, emails, JSON without running your app
+- **GitHub Action** - Drop-in CI/CD integration
+- **Zero dependencies** - Fast install, minimal footprint
 
 **Built autonomously by [Claude](https://claude.ai)** - an AI assistant by Anthropic.
 
@@ -459,8 +478,14 @@ WITH_EQUALS=postgres://user:pass@host/db?opt=val
 - **CI-friendly** - Exit codes and JSON output
 - **Comprehensive** - Parse, validate, compare, generate
 - **Monorepo support** - Scan all apps/packages in one command
+- **TypeScript support** - Full type definitions included
 - **Well-tested** - 87 tests covering edge cases
 
+## Examples
+
+See the [examples directory](./examples) for complete demos:
+- [Monorepo Demo](./examples/monorepo-demo) - Demonstrates scanning a full monorepo structure
+
 ## vs. dotenv-safe / envalid / dotenv-mono
 
 | Feature | envcheck | dotenv-safe | envalid | dotenv-mono |

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@claude-agent/envcheck",
-  "version": "1.5.0",
-  "description": "Validate .env files, compare with .env.example, find missing or empty variables",
+  "version": "1.5.2",
+  "description": "Static .env validation for CI/CD and monorepos. Validate against .env.example, detect secrets, check types - before deployment.",
   "main": "src/index.js",
+  "types": "types/index.d.ts",
   "bin": {
     "envcheck": "bin/cli.js"
   },
@@ -15,17 +16,26 @@
     "environment",
     "variables",
     "validate",
+    "validation",
     "lint",
+    "linter",
     "cli",
     "github-action",
     "ci-cd",
+    "cicd",
     "pre-commit",
     "git-hooks",
     "secrets",
     "security",
     "monorepo",
     "turborepo",
-    "workspaces"
+    "nx",
+    "lerna",
+    "workspaces",
+    "static-analysis",
+    "type-validation",
+    "envfile",
+    "config"
   ],
   "author": "Claude Agent <claude-agent@agentmail.to>",
   "license": "MIT",
@@ -43,6 +53,10 @@
   "files": [
     "src/",
     "bin/",
+    "types/",
     "pre-commit-hook.sh"
-  ]
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
 }

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[];