Initial upload with CI/CD workflow

README.md

@@ -1,3 +1,244 @@
-# dotenv-types
+# Dotenv Types
 
-A CLI tool that validates .env files against a schema and auto-generates TypeScript interfaces for type-safe environment variables.
+A CLI tool that validates .env files against a schema and auto-generates TypeScript interfaces for type-safe environment variables in TypeScript projects.
+
+## Features
+
+- **Schema Validation**: Validate .env files against a JSON schema definition
+- **TypeScript Type Generation**: Generate TypeScript interfaces from .env variables
+- **Strict Type Checking**: Required vs optional values with proper type annotations
+- **Nested Object Support**: Parse DB_* prefixed variables into nested objects
+- **Migration Helper**: Analyze existing .env files and generate initial schema
+
+## Installation
+
+```bash
+# Using npm
+npm install -g dotenv-types
+
+# Using yarn
+yarn global add dotenv-types
+
+# Using pnpm
+pnpm add -g dotenv-types
+```
+
+Or run directly with npx:
+
+```bash
+npx dotenv-types validate
+```
+
+## Usage
+
+### Validate Command
+
+Validate your .env file against a schema:
+
+```bash
+dotenv-types validate -e .env -s schema.json
+```
+
+Options:
+- `-e, --env <path>`: Path to .env file (default: `.env`)
+- `-s, --schema <path>`: Path to schema.json file
+
+### Generate Command
+
+Generate TypeScript interfaces from your .env file:
+
+```bash
+dotenv-types generate -e .env -o env.d.ts
+```
+
+Options:
+- `-e, --env <path>`: Path to .env file (default: `.env`)
+- `-s, --schema <path>`: Path to schema.json file
+- `-o, --output <path>`: Output file path (stdout if not specified)
+- `-n, --name <name>`: Interface name (default: `EnvVariables`)
+
+### Migrate Command
+
+Generate a schema.json from an existing .env file:
+
+```bash
+dotenv-types migrate -e .env -o schema.json
+```
+
+Options:
+- `-e, --env <path>`: Path to .env file (default: `.env`)
+- `-o, --output <path>`: Output file path (default: `schema.json`)
+
+## Configuration
+
+### Schema Definition
+
+Create a `schema.json` file to define your environment variable requirements:
+
+```json
+{
+  "variables": {
+    "PORT": {
+      "type": "port",
+      "required": true,
+      "desc": "Port number for the server"
+    },
+    "NODE_ENV": {
+      "type": "enum",
+      "required": true,
+      "choices": ["development", "production", "test"],
+      "desc": "Environment mode"
+    },
+    "DATABASE_URL": {
+      "type": "url",
+      "required": true,
+      "desc": "Database connection URL"
+    },
+    "DEBUG": {
+      "type": "boolean",
+      "required": false,
+      "default": false,
+      "desc": "Enable debug mode"
+    }
+  }
+}
+```
+
+### Supported Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `string` | Any string value | `"hello"` |
+| `number` | Decimal number | `3.14` |
+| `int` | Integer | `42` |
+| `boolean` | true/false | `true` |
+| `port` | Valid port number (1-65535) | `3000` |
+| `url` | Valid URL | `https://api.example.com` |
+| `email` | Valid email | `user@example.com` |
+| `enum` | One of specified values | `"development"` |
+| `json` | Valid JSON string | `{"key": "value"}` |
+| `host` | Valid hostname | `localhost` |
+
+## Examples
+
+### Basic Usage
+
+1. Create a `.env` file:
+
+```env
+PORT=3000
+NODE_ENV=development
+DATABASE_URL=postgres://localhost:5432/mydb
+DEBUG=true
+```
+
+2. Generate a schema:
+
+```bash
+dotenv-types migrate -e .env -o schema.json
+```
+
+3. Validate your .env:
+
+```bash
+dotenv-types validate -e .env -s schema.json
+```
+
+4. Generate TypeScript types:
+
+```bash
+dotenv-types generate -e .env -o env.d.ts
+```
+
+### Generated TypeScript Interface
+
+```typescript
+export interface EnvVariables {
+  /** Port number for the server */
+  PORT: number;
+
+  /** Environment mode */
+  NODE_ENV: 'development' | 'production' | 'test';
+
+  /** Database connection URL */
+  DATABASE_URL: string;
+
+  /** Enable debug mode */
+  DEBUG?: boolean;  // Default: false
+}
+```
+
+### Nested Objects
+
+Dotenv Types supports nested objects via underscore notation:
+
+```env
+APP_NAME=myapp
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=admin
+DB_PASSWORD=secret
+REDIS_HOST=localhost
+REDIS_PORT=6379
+```
+
+Generates:
+
+```typescript
+export interface EnvVariables {
+  APP_NAME: string;
+  Db?: {
+    HOST?: string;
+    PORT?: number;
+    USER?: string;
+    PASSWORD?: string;
+  };
+  Redis?: {
+    HOST?: string;
+    PORT?: number;
+  };
+}
+```
+
+## API Reference
+
+### JavaScript API
+
+```typescript
+import { parseEnvFile } from 'dotenv-types/core/parser';
+import { validateEnv, parseSchemaFromEnv } from 'dotenv-types/core/validator';
+import { generateTypeScriptInterface } from 'dotenv-types/utils/typeGenerator';
+
+// Parse .env file
+const parsed = parseEnvFile('.env');
+
+// Validate against schema
+const schema = parseSchemaFromEnv(parsed.flat);
+const result = validateEnv(parsed.flat, schema);
+
+// Generate TypeScript interface
+const code = generateTypeScriptInterface(schema, parsed);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run linting
+npm run lint
+
+# Run CLI locally
+npm run dev -- validate -e .env
+```
+
+## License
+
+MIT