Metadata-Version: 2.4
Name: envschema-dsl
Version: 0.1.0
Summary: DSL for typed .env files — schema, validation, codegen
Keywords: env,dotenv,schema,validation,codegen,typescript,pydantic,zod
Author: nike4192
Author-email: nike4192 <nike4192@outlook.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: lark>=1.2
Requires-Dist: click>=8.0
Requires-Dist: pygls>=2.1.1
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/envschema/envschema
Project-URL: Repository, https://github.com/envschema/envschema
Provides-Extra: dev
Description-Content-Type: text/markdown

# envschema

DSL for typed `.env` files — schema, validation, codegen.

## Install

```bash
pip install envschema
# or
uv add envschema
```

## Quick Start

Create a `.env.schema` file:

```python
# Database
DB_HOST str @required
DB_PORT port = 5432
DB_PASSWORD str @secret @required
DB_NAME str = "myapp"

# App
NODE_ENV enum("development", "production", "test") = "development"
PORT int = 3000 : 0 < x < 65535
DEBUG bool = false
CORS_ORIGIN str[] = "http://localhost:3000"
API_KEY str @required : len(x) >= 32
```

Validate your `.env` file:

```bash
envschema validate .env.schema --env .env
```

```
  ✓ DB_HOST = db.example.com
  ✓ DB_PORT = 5432
  ✓ DB_PASSWORD = ***
  ✓ NODE_ENV = development
  ✓ PORT = 3000
  ✗ API_KEY — validation failed: len(x) >= 32 (x='short')
  ⚠ UNKNOWN_VAR — not defined in schema

Result: 5 OK, 1 errors, 1 warnings
```

Generate code:

```bash
envschema generate .env.schema -t ts          # TypeScript interface
envschema generate .env.schema -t zod         # Zod v4 schema
envschema generate .env.schema -t pydantic    # Pydantic BaseSettings
envschema generate .env.schema -t dataclasses # Python dataclass (no deps)
envschema generate .env.schema -t env-example # .env.example
```

## Features

### Types

```python
HOST str = "localhost"            # string
PORT int = 3000                   # integer
RATIO float = 0.5                 # float
DEBUG bool = false                # boolean
API_PORT port = 8080              # port (int 1-65535)
BASE_URL url                      # URL (any scheme://)
ADMIN_EMAIL email                 # email
DATA_DIR path = "/var/data"       # filesystem path
NODE_ENV enum("dev", "prod")      # enum
HOSTS str[]                       # array (comma-separated)
```

Type inference from defaults — `PORT = 3000` is inferred as `int`.

### Decorators

```python
DB_HOST str @required                      # must be set
DB_PASSWORD str @secret @required          # hidden in output
LOG_LEVEL str @description("Logging level") # description
```

### Inline Validation

Python expressions with `x` as the value:

```python
PORT int = 3000 : 0 < x < 65535
API_KEY str @required : len(x) >= 32
RATE_LIMIT int = 100 : 0 < x < 10000
```

### Block Syntax

For complex variables:

```python
DATABASE_URL {
    type = url
    description = "PostgreSQL connection string"
    @secret
    @required
    validate = "x.startswith('postgres://')"
}
```

### Type Aliases

```python
type LogLevel = enum("error", "warn", "info", "debug")
type ExtendedEnv = NodeEnv + enum("local")

LOG_LEVEL LogLevel = "warn"
```

### Presets

```python
#include <node.js>       # built-in preset (NODE_ENV, PORT, HOST)
#include <vite>          # VITE_* variables
#include "shared.schema" # local file

APP_NAME str = "myapp"
```

```bash
envschema presets list             # list available presets
envschema presets load directus    # download from registry
```

### Wildcard Expansion

```python
AUTH_PROVIDERS str[] = "google,github"

AUTH_{AUTH_PROVIDERS}_DRIVER str @required
AUTH_{AUTH_PROVIDERS}_CLIENT_ID str @secret @required
AUTH_{AUTH_PROVIDERS}_CLIENT_SECRET str @secret @required
```

Expands to `AUTH_GOOGLE_DRIVER`, `AUTH_GITHUB_DRIVER`, etc.
Default filter: `upper`. Custom: `{AUTH_PROVIDERS|lower}`.

## CLI

```bash
envschema parse <file>              # parse and display AST
envschema parse <file> --json       # output as JSON
envschema validate <schema> --env <env>  # validate .env against schema
envschema generate <schema> -t <target>  # generate code
envschema generators list           # list available targets
envschema presets list              # list presets
envschema presets load <name>       # download preset
envschema lsp                       # start LSP server (stdio)
```

## VS Code Extension

```bash
cd editors/vscode/envschema
npx @vscode/vsce package --allow-missing-repository
cursor --install-extension envschema-0.1.0.vsix
```

Provides syntax highlighting for `.env.schema` files.

## License

MIT
