# EnvSchema

[![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema/actions)
[![PyPI version](https://img.shields.io/pypi/v/envschema.svg)](https://pypi.org/project/envschema/)
[![Python versions](https://img.shields.io/pypi/pyversions/envschema.svg)](https://pypi.org/project/envschema/)
[![License](https://img.shields.io/pypi/l/envschema.svg)](https://opensource.org/licenses/MIT)

A CLI tool that validates environment variables against a JSON/YAML schema file. Developers define expected env vars with types, defaults, required flags, and descriptions in a schema. The tool validates actual .env files or runtime environment against this schema, catching type mismatches, missing required vars, and providing helpful error messages.

## Features

- Schema validation with type checking (str, int, bool, list)
- Missing required variable detection
- `.env.example` generation from schema
- CI/CD integration for pre-deployment checks
- Support for JSON and YAML schema formats
- Pattern validation with regex support

## Installation

```bash
pip install envschema
```

Or install from source:

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema.git
cd envschema
pip install -e .
```

## Quick Start

1. Create a schema file (`.env.schema.json` or `.env.schema.yaml`):

```json
{
  "version": "1.0",
  "envVars": [
    {
      "name": "DATABASE_URL",
      "type": "str",
      "required": true,
      "description": "PostgreSQL connection string"
    },
    {
      "name": "DEBUG_MODE",
      "type": "bool",
      "required": false,
      "default": "false"
    }
  ]
}
```

2. Validate your `.env` file:

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

## CLI Commands

### validate

Validate environment variables against a schema:

```bash
envschema validate SCHEMA [--file PATH] [--env/--no-env] [--format text|json] [--ci] [--strict]
```

Options:
- `SCHEMA`: Path to the schema file (JSON or YAML)
- `--file`, `-f`: Path to .env file to validate
- `--env/--no-env`: Include os.environ in validation (default: true)
- `--format`, `-o`: Output format (text or json, default: text)
- `--ci`: CI mode (cleaner output)
- `--strict`: Fail on warnings

### generate

Generate `.env.example` from a schema:

```bash
envschema generate SCHEMA [--output PATH] [--no-comments]
```

Options:
- `SCHEMA`: Path to the schema file
- `--output`, `-o`: Output file path (default: .env.example)
- `--no-comments`: Don't include description comments

### check

Validate a schema file:

```bash
envschema check SCHEMA
```

## Schema Format

### JSON Schema

```json
{
  "version": "1.0",
  "envVars": [
    {
      "name": "VAR_NAME",
      "type": "str|int|bool|list",
      "required": true|false,
      "default": "default_value",
      "description": "Variable description",
      "pattern": "regex_pattern"
    }
  ]
}
```

### YAML Schema

```yaml
version: "1.0"
envVars:
  - name: VAR_NAME
    type: str
    required: true
    default: "value"
    description: Variable description
    pattern: "^[A-Z]+$"
```

## Supported Types

- `str`: String (always valid)
- `int`: Integer (validates numeric values)
- `bool`: Boolean (true, false, 1, 0, yes, no, on, off)
- `list`: Comma-separated list of values

## Examples

### Validate with environment variables

```bash
export DATABASE_URL="postgres://localhost/mydb"
export DEBUG_MODE="true"
envschema validate schema.json
```

### Validate with .env file

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

### CI/CD Integration

```bash
envschema validate schema.json --file .env --ci --format json
```

Exit codes:
- 0: Validation passed
- 1: Validation failed
- 2: Error (schema not found, invalid format)

### Generate .env.example

```bash
envschema generate schema.json
# Generates .env.example

envschema generate schema.json --output .env.dev
```

## API Reference

```python
from envschema import Schema, ValidationEngine, EnvLoader

# Load schema
schema = Schema.load("schema.json")

# Load environment
loader = EnvLoader(".env")
env_vars = loader.load()

# Validate
engine = ValidationEngine(schema)
result = engine.validate(env_vars)

if not result.is_valid:
    print(result.missing_required)
    print(result.type_errors)
```

## License

MIT License - see LICENSE file for details.