envcontract 0.1.0__py3-none-any.whl

envcontract/__init__.py

@@ -0,0 +1,3 @@
+"""envcontract — the contract for your .env. 100% local, your values never leave your machine."""
+
+__version__ = "0.1.0"

envcontract/cli.py

@@ -0,0 +1,138 @@
+"""Command-line entry point for envcontract."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from . import __version__
+from .drift import compute_drift
+from .generate import render_schema_yaml
+from .guard import scan_files
+from .parser import parse_file
+from .report import render_human, render_json
+from .schema import EnvSchema, SchemaError
+from .validators import validate
+
+_ENV_OPT = dict(default=".env", show_default=True, help="Path to the .env file.")
+_SCHEMA_OPT = dict(default=".env.schema", show_default=True, help="Path to the .env.schema file.")
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-V", "--version", prog_name="envcontract")
+def cli() -> None:
+    """envcontract - the contract for your .env.
+
+    Validate your .env against a committed schema, catch team drift, and
+    never commit a secret. 100% local: your values never leave your machine.
+    """
+
+
+def _load_schema_or_exit(schema_path: str, console: Console) -> EnvSchema:
+    try:
+        return EnvSchema.from_file(schema_path)
+    except SchemaError as exc:
+        console.print(f"[red]X[/red] {exc}")
+        sys.exit(2)
+
+
+@cli.command()
+@click.option("--env", "env_path", **_ENV_OPT)
+@click.option("--schema", "schema_path", **_SCHEMA_OPT)
+@click.option("--force", is_flag=True, help="Overwrite an existing schema file.")
+def init(env_path: str, schema_path: str, force: bool) -> None:
+    """Generate a .env.schema from an existing .env (values stripped)."""
+    console = Console()
+    if not Path(env_path).exists():
+        Console(stderr=True).print(f"[red]X[/red] env file not found: {env_path}")
+        sys.exit(2)
+    if Path(schema_path).exists() and not force:
+        Console(stderr=True).print(
+            f"[yellow]![/yellow] {schema_path} already exists. Use --force to overwrite."
+        )
+        sys.exit(2)
+
+    yaml_text = render_schema_yaml(parse_file(env_path))
+    Path(schema_path).write_text(yaml_text, encoding="utf-8")
+    n = yaml_text.count("\n    type:")
+    console.print(f"[green]+[/green] Wrote {schema_path} with {n} variable(s). No values were copied.")
+
+
+@cli.command()
+@click.option("--env", "env_path", **_ENV_OPT)
+@click.option("--schema", "schema_path", **_SCHEMA_OPT)
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON (for CI).")
+def check(env_path: str, schema_path: str, as_json: bool) -> None:
+    """Validate a .env against the schema (types, rules, required keys)."""
+    err_console = Console(stderr=True)
+    if not Path(env_path).exists():
+        err_console.print(f"[red]X[/red] env file not found: {env_path}")
+        sys.exit(2)
+    schema = _load_schema_or_exit(schema_path, err_console)
+
+    findings = validate(parse_file(env_path), schema)
+    if as_json:
+        click.echo(render_json(findings))
+    else:
+        render_human(findings, Console())
+    sys.exit(1 if any(f.severity.value == "error" for f in findings) else 0)
+
+
+@cli.command()
+@click.option("--env", "env_path", **_ENV_OPT)
+@click.option("--schema", "schema_path", **_SCHEMA_OPT)
+def diff(env_path: str, schema_path: str) -> None:
+    """Show what your local .env has vs. the schema (and vice versa)."""
+    console = Console()
+    err_console = Console(stderr=True)
+    if not Path(env_path).exists():
+        err_console.print(f"[red]X[/red] env file not found: {env_path}")
+        sys.exit(2)
+    schema = _load_schema_or_exit(schema_path, err_console)
+
+    d = compute_drift(parse_file(env_path), schema)
+    if not d.has_drift:
+        console.print(f"[green]+[/green] In sync: {len(d.in_sync)} variable(s) match the schema.")
+        sys.exit(0)
+
+    if d.missing_locally:
+        console.print("[red]Missing from your .env (declared in schema):[/red]")
+        for k in d.missing_locally:
+            console.print(f"  [red]-[/red] {k}")
+    if d.not_in_schema:
+        console.print("[yellow]In your .env but not in the schema:[/yellow]")
+        for k in d.not_in_schema:
+            console.print(f"  [yellow]+[/yellow] {k}")
+    sys.exit(1)
+
+
+@cli.command()
+@click.argument("files", nargs=-1)
+@click.option("--schema", "schema_path", **_SCHEMA_OPT)
+def guard(files: tuple[str, ...], schema_path: str) -> None:
+    """Pre-commit hook: block committing real values for secret keys."""
+    console = Console(stderr=True)
+    schema = None
+    if Path(schema_path).exists():
+        try:
+            schema = EnvSchema.from_file(schema_path)
+        except SchemaError:
+            schema = None
+
+    violations = scan_files(list(files), schema)
+    if not violations:
+        sys.exit(0)
+
+    console.print("[red]X envcontract: blocked commit - real secret values detected:[/red]")
+    for v in violations:
+        loc = f"{v.file}:{v.line_no}" if v.line_no else v.file
+        console.print(f"  [red]-[/red] {v.key}  ({loc})")
+    console.print("\nRemove these values (or move them to a git-ignored .env) before committing.")
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

envcontract/drift.py

@@ -0,0 +1,33 @@
+"""Compute drift between a local .env and the committed schema.
+
+Answers the "a teammate added a var and didn't tell anyone" problem.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .parser import ParsedEnv
+from .schema import EnvSchema
+
+
+@dataclass
+class Drift:
+    missing_locally: list[str]   # declared in schema, absent from local .env
+    not_in_schema: list[str]     # present locally, not declared in schema
+    in_sync: list[str]           # present in both
+
+    @property
+    def has_drift(self) -> bool:
+        return bool(self.missing_locally or self.not_in_schema)
+
+
+def compute_drift(parsed: ParsedEnv, schema: EnvSchema) -> Drift:
+    env_keys = list(parsed.as_dict().keys())
+    schema_keys = list(schema.variables.keys())
+    env_set, schema_set = set(env_keys), set(schema_keys)
+
+    missing_locally = [k for k in schema_keys if k not in env_set]
+    not_in_schema = [k for k in env_keys if k not in schema_set]
+    in_sync = [k for k in schema_keys if k in env_set]
+    return Drift(missing_locally, not_in_schema, in_sync)

envcontract/generate.py

@@ -0,0 +1,53 @@
+"""Generate a .env.schema from an existing .env.
+
+Infers a type per variable, flags likely secrets, and — critically — never
+writes any value into the schema. The schema is a contract, not a secret store.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .parser import ParsedEnv
+from .secrets import looks_like_secret_key
+
+_URL_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.\-]*://[^\s]+$")
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+_BOOL_VALUES = {"true", "false", "yes", "no", "on", "off"}
+
+
+def infer_type(value: str) -> str:
+    v = value.strip()
+    if v.lower() in _BOOL_VALUES:
+        return "bool"
+    if _URL_RE.match(v):
+        return "url"
+    if _EMAIL_RE.match(v):
+        return "email"
+    if re.fullmatch(r"[+-]?\d+", v):
+        return "int"
+    if re.fullmatch(r"[+-]?\d*\.\d+", v):
+        return "float"
+    return "string"
+
+
+def render_schema_yaml(parsed: ParsedEnv) -> str:
+    """Build a clean, deterministic .env.schema YAML (values stripped)."""
+    lines = [
+        "# Generated by `envcontract init`. Commit this file; it contains no secret values.",
+        "version: 1",
+        "variables:",
+    ]
+    seen: set[str] = set()
+    for entry in parsed.entries:
+        if entry.key in seen:
+            continue
+        seen.add(entry.key)
+        vtype = infer_type(entry.value)
+        secret = looks_like_secret_key(entry.key)
+        lines.append(f"  {entry.key}:")
+        lines.append(f"    type: {vtype}")
+        lines.append("    required: true")
+        if secret:
+            lines.append("    secret: true")
+    return "\n".join(lines) + "\n"

envcontract/guard.py

@@ -0,0 +1,54 @@
+"""Detect real secret values about to be committed.
+
+Narrow by design: we only flag keys the schema marks ``secret: true`` that
+carry a real (non-placeholder, non-empty) value. We never print the value.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .parser import parse_file
+from .schema import EnvSchema
+from .secrets import looks_like_secret_key
+
+# Common placeholders that are safe to commit.
+_PLACEHOLDERS = {
+    "", "changeme", "change_me", "your_value_here", "xxx", "todo",
+    "placeholder", "example", "secret", "<your-key>", "...",
+}
+
+
+@dataclass
+class Violation:
+    file: str
+    key: str
+    line_no: int | None
+
+
+def _is_real_secret_value(value: str) -> bool:
+    v = value.strip().lower()
+    if v in _PLACEHOLDERS:
+        return False
+    return len(value.strip()) >= 6
+
+
+def scan_files(files: list[str], schema: EnvSchema | None) -> list[Violation]:
+    """Return violations: secret-marked keys carrying a real value in staged files."""
+    secret_keys = {k for k, r in schema.variables.items() if r.secret} if schema else set()
+    violations: list[Violation] = []
+
+    for f in files:
+        path = Path(f)
+        if not path.exists() or not path.is_file():
+            continue
+        try:
+            parsed = parse_file(path)
+        except (UnicodeDecodeError, OSError):
+            continue
+        for entry in parsed.entries:
+            is_secret = entry.key in secret_keys or looks_like_secret_key(entry.key)
+            if is_secret and _is_real_secret_value(entry.value):
+                violations.append(Violation(file=f, key=entry.key, line_no=entry.line_no))
+    return violations

envcontract/parser.py

@@ -0,0 +1,115 @@
+"""Parse .env files into ordered key/value entries with line numbers.
+
+Aims to be compatible with python-dotenv conventions: ``export`` prefixes,
+single/double quotes, inline comments on unquoted values, and blank/comment
+lines. We deliberately keep this small and predictable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class EnvEntry:
+    """A single ``KEY=value`` line from a .env file."""
+
+    key: str
+    value: str
+    line_no: int
+    quoted: bool = False
+
+
+@dataclass(frozen=True)
+class ParseError:
+    """A malformed line we could not interpret as a key/value pair."""
+
+    line_no: int
+    raw: str
+    message: str
+
+
+@dataclass
+class ParsedEnv:
+    entries: list[EnvEntry]
+    errors: list[ParseError]
+
+    def as_dict(self) -> dict[str, str]:
+        """Later entries win, matching how shells/dotenv resolve duplicates."""
+        return {e.key: e.value for e in self.entries}
+
+    @property
+    def duplicate_keys(self) -> list[str]:
+        seen: set[str] = set()
+        dupes: list[str] = []
+        for e in self.entries:
+            if e.key in seen and e.key not in dupes:
+                dupes.append(e.key)
+            seen.add(e.key)
+        return dupes
+
+
+def _strip_inline_comment(value: str) -> str:
+    """Remove an unquoted trailing ``# comment`` (must be preceded by space)."""
+    result = []
+    for i, ch in enumerate(value):
+        if ch == "#" and (i == 0 or value[i - 1].isspace()):
+            break
+        result.append(ch)
+    return "".join(result).strip()
+
+
+def _parse_value(raw: str) -> tuple[str, bool]:
+    """Return (value, quoted). Handles single/double quotes and inline comments."""
+    raw = raw.strip()
+    if not raw:
+        return "", False
+    if raw[0] in {'"', "'"}:
+        quote = raw[0]
+        end = raw.find(quote, 1)
+        if end != -1:
+            inner = raw[1:end]
+            if quote == '"':
+                inner = inner.replace("\\n", "\n").replace("\\t", "\t").replace('\\"', '"')
+            return inner, True
+        # Unterminated quote: treat the rest literally.
+        return raw[1:], True
+    return _strip_inline_comment(raw), False
+
+
+def parse_text(text: str) -> ParsedEnv:
+    entries: list[EnvEntry] = []
+    errors: list[ParseError] = []
+
+    for line_no, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+
+        if "=" not in line:
+            errors.append(ParseError(line_no, raw_line, "missing '=' (not a KEY=value line)"))
+            continue
+
+        key, _, value_part = line.partition("=")
+        key = key.strip()
+        if not key:
+            errors.append(ParseError(line_no, raw_line, "empty key before '='"))
+            continue
+        if not all(c.isalnum() or c == "_" for c in key):
+            errors.append(
+                ParseError(line_no, raw_line, f"invalid key name '{key}' (use A-Z, 0-9, _)")
+            )
+            continue
+
+        value, quoted = _parse_value(value_part)
+        entries.append(EnvEntry(key=key, value=value, line_no=line_no, quoted=quoted))
+
+    return ParsedEnv(entries=entries, errors=errors)
+
+
+def parse_file(path: str | Path) -> ParsedEnv:
+    return parse_text(Path(path).read_text(encoding="utf-8"))

envcontract/report.py

@@ -0,0 +1,58 @@
+"""Render validation findings as human-friendly terminal output or JSON.
+
+Invariant: this module never prints a secret value. Findings carry messages,
+not raw values, and any value echoed elsewhere is masked first.
+"""
+
+from __future__ import annotations
+
+import json
+
+from rich.console import Console
+from rich.table import Table
+
+from .validators import Finding, Severity
+
+_ICON = {Severity.ERROR: "[red]✗[/red]", Severity.WARNING: "[yellow]![/yellow]"}
+
+
+def render_human(findings: list[Finding], console: Console | None = None) -> None:
+    console = console or Console()
+    errors = [f for f in findings if f.severity is Severity.ERROR]
+    warnings = [f for f in findings if f.severity is Severity.WARNING]
+
+    if not findings:
+        console.print("[bold green]✓ All variables valid.[/bold green] Your .env matches the schema.")
+        return
+
+    table = Table(show_header=True, header_style="bold", expand=False)
+    table.add_column("")
+    table.add_column("Variable", style="cyan", no_wrap=True)
+    table.add_column("Line", justify="right", style="dim")
+    table.add_column("Issue")
+    for f in findings:
+        table.add_row(_ICON[f.severity], f.key, str(f.line_no or "-"), f.message)
+    console.print(table)
+
+    parts = []
+    if errors:
+        parts.append(f"[red]{len(errors)} error(s)[/red]")
+    if warnings:
+        parts.append(f"[yellow]{len(warnings)} warning(s)[/yellow]")
+    console.print("  ".join(parts))
+
+
+def build_json(findings: list[Finding]) -> dict:
+    return {
+        "ok": not any(f.severity is Severity.ERROR for f in findings),
+        "errors": sum(1 for f in findings if f.severity is Severity.ERROR),
+        "warnings": sum(1 for f in findings if f.severity is Severity.WARNING),
+        "findings": [
+            {"severity": f.severity.value, "key": f.key, "line": f.line_no, "message": f.message}
+            for f in findings
+        ],
+    }
+
+
+def render_json(findings: list[Finding]) -> str:
+    return json.dumps(build_json(findings), indent=2)

envcontract/schema.py

@@ -0,0 +1,75 @@
+"""Load and validate the .env.schema contract itself.
+
+The schema is YAML. It describes variables and their rules — never values.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Optional
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+VarType = Literal["string", "int", "float", "bool", "url", "email", "enum"]
+
+
+class SchemaError(Exception):
+    """Raised when a .env.schema file is missing or malformed."""
+
+
+class VariableRule(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: VarType = "string"
+    required: bool = True
+    secret: bool = False
+    default: Optional[str] = None
+    pattern: Optional[str] = None
+    min: Optional[float] = None
+    max: Optional[float] = None
+    values: Optional[list[str]] = None
+    description: Optional[str] = None
+
+    @model_validator(mode="after")
+    def _check_enum(self) -> "VariableRule":
+        if self.type == "enum" and not self.values:
+            raise ValueError("enum type requires a non-empty 'values' list")
+        return self
+
+
+class EnvSchema(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    version: int = 1
+    variables: dict[str, VariableRule] = Field(default_factory=dict)
+
+    @classmethod
+    def from_text(cls, text: str) -> "EnvSchema":
+        try:
+            data = yaml.safe_load(text) or {}
+        except yaml.YAMLError as exc:
+            raise SchemaError(f"invalid YAML in schema: {exc}") from exc
+        if not isinstance(data, dict):
+            raise SchemaError("schema root must be a mapping with a 'variables' key")
+        try:
+            return cls.model_validate(data)
+        except ValidationError as exc:
+            raise SchemaError(_format_validation_error(exc)) from exc
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "EnvSchema":
+        p = Path(path)
+        if not p.exists():
+            raise SchemaError(
+                f"schema file not found: {p}. Run `envcontract init` to create one from your .env."
+            )
+        return cls.from_text(p.read_text(encoding="utf-8"))
+
+
+def _format_validation_error(exc: ValidationError) -> str:
+    lines = ["schema is invalid:"]
+    for err in exc.errors():
+        loc = ".".join(str(p) for p in err["loc"])
+        lines.append(f"  - {loc}: {err['msg']}")
+    return "\n".join(lines)

envcontract/secrets.py

@@ -0,0 +1,29 @@
+"""Heuristics for identifying secret-ish keys and safely masking values.
+
+Used by `init` (auto-flag secrets), `guard` (detect committed secrets), and
+`report` (never print a secret value).
+"""
+
+from __future__ import annotations
+
+import re
+
+_SECRET_KEY_PATTERN = re.compile(
+    r"(SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|API[_-]?KEY|ACCESS[_-]?KEY|"
+    r"CREDENTIAL|AUTH|CERT|SIGNING|_KEY$|^KEY$)",
+    re.IGNORECASE,
+)
+
+
+def looks_like_secret_key(key: str) -> bool:
+    """True if a variable name suggests it holds a secret."""
+    return bool(_SECRET_KEY_PATTERN.search(key))
+
+
+def mask(value: str) -> str:
+    """Mask a secret value so it never appears in full in any output."""
+    if value == "":
+        return "(empty)"
+    if len(value) <= 4:
+        return "****"
+    return f"{value[:2]}{'*' * 6}{value[-2:]}"

envcontract/validators.py

@@ -0,0 +1,128 @@
+"""Validate a parsed .env against an EnvSchema and produce findings."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+from .parser import ParsedEnv
+from .schema import EnvSchema, VariableRule
+
+_URL_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.\-]*://[^\s]+$")
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+_BOOL_VALUES = {"true", "false", "1", "0", "yes", "no", "on", "off"}
+
+
+class Severity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+def _fmt(n: float) -> str:
+    """Render 65535.0 as '65535' but keep 3.5 as '3.5'."""
+    return str(int(n)) if float(n).is_integer() else str(n)
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: Severity
+    key: str
+    message: str
+    line_no: int | None = None
+
+
+def _check_type(value: str, rule: VariableRule) -> str | None:
+    """Return an error message if the value doesn't match the declared type."""
+    t = rule.type
+    if t == "int":
+        try:
+            int(value)
+        except ValueError:
+            return f"expected an integer, got '{value}'"
+    elif t == "float":
+        try:
+            float(value)
+        except ValueError:
+            return f"expected a number, got '{value}'"
+    elif t == "bool":
+        if value.lower() not in _BOOL_VALUES:
+            return f"expected a boolean (true/false), got '{value}'"
+    elif t == "url":
+        if not _URL_RE.match(value):
+            return f"expected a URL (scheme://...), got '{value}'"
+    elif t == "email":
+        if not _EMAIL_RE.match(value):
+            return f"expected an email address, got '{value}'"
+    elif t == "enum":
+        if rule.values and value not in rule.values:
+            return f"must be one of {rule.values}, got '{value}'"
+    return None
+
+
+def _check_rules(value: str, rule: VariableRule) -> list[str]:
+    msgs: list[str] = []
+    if rule.pattern is not None and not re.search(rule.pattern, value):
+        msgs.append(f"does not match required pattern /{rule.pattern}/")
+    if rule.min is not None or rule.max is not None:
+        if rule.type in {"int", "float"}:
+            try:
+                num = float(value)
+                if rule.min is not None and num < rule.min:
+                    msgs.append(f"must be >= {_fmt(rule.min)}")
+                if rule.max is not None and num > rule.max:
+                    msgs.append(f"must be <= {_fmt(rule.max)}")
+            except ValueError:
+                pass  # type error already reported
+        else:
+            length = len(value)
+            if rule.min is not None and length < rule.min:
+                msgs.append(f"length must be >= {_fmt(rule.min)}")
+            if rule.max is not None and length > rule.max:
+                msgs.append(f"length must be <= {_fmt(rule.max)}")
+    return msgs
+
+
+def validate(parsed: ParsedEnv, schema: EnvSchema) -> list[Finding]:
+    findings: list[Finding] = []
+    env = parsed.as_dict()
+    line_of = {e.key: e.line_no for e in parsed.entries}
+
+    for err in parsed.errors:
+        findings.append(Finding(Severity.WARNING, "(parse)", err.message, err.line_no))
+    for dup in parsed.duplicate_keys:
+        findings.append(
+            Finding(Severity.WARNING, dup, "defined more than once (last value wins)", line_of.get(dup))
+        )
+
+    for key, rule in schema.variables.items():
+        present = key in env
+        if not present:
+            if rule.required and rule.default is None:
+                findings.append(Finding(Severity.ERROR, key, "required but missing"))
+            continue
+
+        value = env[key]
+        if value == "" and rule.required:
+            findings.append(Finding(Severity.ERROR, key, "required but empty", line_of.get(key)))
+            continue
+
+        type_err = _check_type(value, rule)
+        if type_err:
+            findings.append(Finding(Severity.ERROR, key, type_err, line_of.get(key)))
+            continue
+
+        for msg in _check_rules(value, rule):
+            findings.append(Finding(Severity.ERROR, key, msg, line_of.get(key)))
+
+    for key in env:
+        if key not in schema.variables:
+            findings.append(
+                Finding(Severity.WARNING, key, "present in .env but not declared in schema", line_of.get(key))
+            )
+
+    return findings
+
+
+def has_errors(findings: list[Finding]) -> bool:
+    return any(f.severity is Severity.ERROR for f in findings)

envcontract-0.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: envcontract
+Version: 0.1.0
+Summary: The contract for your .env — validate it, catch team drift, and never commit a secret. 100% local.
+Project-URL: Homepage, https://github.com/hamzamansoorch/envcontract
+Project-URL: Issues, https://github.com/hamzamansoorch/envcontract/issues
+Author: Hamza Mansoor
+License: MIT
+License-File: LICENSE
+Keywords: cli,dotenv,env,environment-variables,pre-commit,secrets,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# envcontract
+
+**The contract for your `.env`.** Validate it, catch team drift, and never commit a secret — **100% local, your values never leave your machine.**
+
+> Status: early development (v0.1.0). Built in the open.
+
+## Why
+
+Teammates add an env var and forget to tell anyone. Secrets get committed by accident. `.env.example` drifts out of sync and was never a real schema. `envcontract` fixes this with one committed contract — `.env.schema` — that lists your variables and their rules, but **never their secret values**.
+
+## Install
+
+```bash
+pipx install envcontract   # recommended (isolated)
+# or
+pip install envcontract
+```
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `envcontract init`  | Generate a `.env.schema` from your existing `.env` (values stripped). |
+| `envcontract check` | Validate your `.env` against the schema: missing keys, wrong types, failed rules. |
+| `envcontract diff`  | Show what your local `.env` has vs. the schema (catches team drift). |
+| `envcontract guard` | Pre-commit hook that blocks committing real values for secret keys. |
+
+## Privacy promise
+
+`envcontract` makes **zero network calls** and has **no telemetry**. It reads files on your machine and prints to your terminal. Nothing else. This is enforced by a test that fails if any network socket is opened.
+
+## License
+
+MIT

envcontract-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+envcontract/__init__.py,sha256=2MeIU-GYBymlHiyof_VKUItQgY-jy6yT6Qlg8thGejM,123
+envcontract/cli.py,sha256=4RPiFhMQr74CioZhHqNlDRWfESJCdIR_UVglG_0gJVU,5073
+envcontract/drift.py,sha256=32X6w51JY0rvezzII5A2setNNtzHICN9L-0RmTLKgus,1077
+envcontract/generate.py,sha256=3hS3TIc6bY-mi9z-S4jFZcJHn6_6i7ojRqyXuVvT6-w,1602
+envcontract/guard.py,sha256=2JoHyEzSwEqsAJSThes0x3yOYYu4EWSa_2Fy-VfuNl0,1679
+envcontract/parser.py,sha256=kTIb__990hucdzj2UkDpE2p9Khd6lYt3obtXzehopEk,3423
+envcontract/report.py,sha256=9pWHUttdM2M71EyMwE2rW1_G6dPW3JR-JYVVW3qVq8I,2010
+envcontract/schema.py,sha256=5GVDlza5Vbgbh5aCYC26axgOgTf_5p7cLUCSrdu_PEs,2385
+envcontract/secrets.py,sha256=NAs-qt0sTfdRiqYRmP3uGV3IRUdnUvP1vwS6nyhoLvs,819
+envcontract/validators.py,sha256=Qt__lBI_tSJqKQ-BXlASjlexwnzTcCoP2LK3AXQNk6M,4383
+envcontract-0.1.0.dist-info/METADATA,sha256=MmIAn8eIwkPTxWQGQBArasyfB2dmEcJZapobY8XENwQ,2401
+envcontract-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+envcontract-0.1.0.dist-info/entry_points.txt,sha256=CojvqWYMvr5RuPUGSqurOLcy44Gsi0XsEpGFVHWpBcE,52
+envcontract-0.1.0.dist-info/licenses/LICENSE,sha256=ughdgoKvVQbEroJad69qEZ2CPPHg4LD20Z7jL4YUA9A,1070
+envcontract-0.1.0.dist-info/RECORD,,

envcontract-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

envcontract-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+envcontract = envcontract.cli:cli

envcontract-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamza Mansoor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.