envcontract 0.1.0__tar.gz

envcontract-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q

envcontract-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# envcontract: never commit real env files
+.env
+.env.*
+!.env.schema
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+.venv/
+venv/

envcontract-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,15 @@
+- id: envcontract-guard
+  name: envcontract guard (block committing secret values)
+  description: Blocks a commit if staged files contain real values for secret keys.
+  entry: envcontract guard
+  language: python
+  pass_filenames: true
+  files: '(^|/)\.env($|\.)'
+
+- id: envcontract-check
+  name: envcontract check (validate .env against schema)
+  description: Validates the local .env against .env.schema.
+  entry: envcontract check
+  language: python
+  pass_filenames: false
+  always_run: true

envcontract-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to envcontract
+
+Thanks for your interest! envcontract aims to stay small, fast, and **100% local**.
+
+## Core principles (please don't break these)
+
+1. **Zero network.** envcontract must never make a network call. There's a test
+   (`tests/test_invariants.py`) that fails if any socket is opened.
+2. **Never print a secret value.** Output carries keys, line numbers, and
+   messages — never raw values for keys marked `secret`.
+3. **Small surface area.** We are not a secrets manager and not a generic
+   secret scanner. Keep the scope tight.
+
+## Dev setup
+
+```bash
+git clone https://github.com/hamzamansoorch/envcontract
+cd envcontract
+pip install -e ".[dev]"
+pytest -q
+ruff check .
+```
+
+## Adding a new variable type or rule
+
+1. Add the type to `VarType` in `schema.py`.
+2. Add validation in `validators.py` (`_check_type` / `_check_rules`).
+3. Add inference (if sensible) in `generate.py`.
+4. Add tests and update the schema reference in the README.
+
+## Pull requests
+
+Keep PRs focused. Include tests. Run `pytest` and `ruff check .` before pushing.

envcontract-0.1.0/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.

envcontract-0.1.0/NEXT_STEPS.md

@@ -0,0 +1,182 @@
+# envcontract — Launch Checklist & Next Steps
+
+Status: code complete (v0.1.0), 29 tests passing, wheel + sdist built.
+What's left is **verify locally → publish to GitHub → publish to PyPI → launch.**
+
+---
+
+## Step 1 — Verify it works on your machine (5 min)
+
+Open the VS Code integrated terminal in the project root (the folder with `pyproject.toml`).
+
+```bash
+# (recommended) create a clean virtual environment
+python -m venv .venv
+# Windows:
+.venv\Scripts\activate
+# macOS/Linux:
+# source .venv/bin/activate
+
+pip install -e ".[dev]"
+
+pytest -q              # expect: 29 passed
+ruff check .           # expect: All checks passed!
+envcontract --help         # should list init / check / diff / guard
+```
+
+If `pytest` shows 29 passed, the project transferred intact. ✅
+
+### Smoke-test the actual commands
+
+```bash
+mkdir demo && cd demo
+printf 'DATABASE_URL=postgres://localhost/db\nPORT=8080\nSTRIPE_KEY=sk_live_abc123\n' > .env
+
+envcontract init           # creates .env.schema (values stripped, STRIPE_KEY flagged secret)
+type .env.schema       # Windows (use `cat` on macOS/Linux)
+envcontract check          # should pass
+envcontract guard .env     # should BLOCK (real secret in .env)
+cd .. 
+```
+
+---
+
+## Step 2 — Fix the placeholders (2 min)
+
+Before publishing, replace these with your real details:
+
+- **`pyproject.toml`** → `Homepage` / `Issues` URLs currently use `github.com/hamza/envcontract`.
+- **`README.md`** → the pre-commit example uses `https://github.com/hamzamansoorch/envcontract`. 
+- **`LICENSE`** → confirm the copyright name/year.
+- **`CONTRIBUTING.md`** → the clone URL uses `<you>`.
+
+
+---
+
+## Step 3 — Confirm the name is still free (2 min)
+
+```bash
+pip index versions envcontract      # "not found" = available
+```
+
+Also check `https://pypi.org/project/envcontract/` and `https://github.com/hamzamansoorch/envcontract` in a browser.
+If taken, pick a fallback (`envguard`, `envschema`, `dotcheck`) and rename in `pyproject.toml` (`name =`) and the `[project.scripts]` entry.
+
+---
+
+## Step 4 — Put it on GitHub (5 min)
+
+```bash
+git init
+git add .
+git commit -m "envcontract v0.1.0 — validate .env, catch drift, guard secrets"
+git branch -M main
+# create an empty repo named 'envcontract' on github.com first, then:
+git remote add origin https://github.com/hamzamansoorch/envcontract.git
+git push -u origin main
+```
+
+Your `.gitignore` already excludes real `.env` files and build artifacts. Double-check no `.env` got committed: `git ls-files | findstr .env` (should only show `.env.schema.example`).
+
+After pushing, the GitHub Actions CI (`.github/workflows/ci.yml`) runs automatically on Linux/macOS/Windows across Python 3.10–3.12.
+
+---
+
+## Step 5 — Publish to PyPI (10 min)
+
+First test on **TestPyPI** so you don't waste the real name on a mistake.
+
+```bash
+pip install build twine
+python -m build                       # rebuilds dist/ (wheel + sdist)
+
+# 5a. Test upload
+twine upload --repository testpypi dist/*
+pip install --index-url https://test.pypi.org/simple/ envcontract   # try it in a fresh venv
+
+# 5b. Real upload (once happy)
+twine upload dist/*
+```
+
+You'll need a PyPI account + an API token (Account settings → API tokens). Use `__token__` as the username and the token as the password.
+
+---
+
+## Step 6 — Tag a release (2 min)
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Then on GitHub: Releases → Draft a new release → pick the tag → paste highlights from the README.
+This is also the `rev:` users reference in the pre-commit example.
+
+---
+
+## How END USERS will install & use it (this is your "it works" demo)
+
+Once it's on PyPI, anyone can do:
+
+```bash
+pipx install envcontract            # or: pip install envcontract
+
+cd their-project
+envcontract init                    # generate .env.schema from their .env
+git add .env.schema             # commit the contract (no secrets in it)
+
+envcontract check                   # validate their .env  → exit 1 if broken
+envcontract diff                    # see what their .env is missing vs the schema
+```
+
+**As a pre-commit hook** (their `.pre-commit-config.yaml`):
+
+```yaml
+repos:
+  - repo: https://github.com/<you>/envcontract
+    rev: v0.1.0
+    hooks:
+      - id: envcontract-guard       # blocks committing real secret values
+```
+
+**In CI** (their GitHub Actions):
+
+```yaml
+- run: pip install envcontract
+- run: envcontract check --json     # fails the build if .env is invalid
+```
+
+---
+
+## Step 7 — Launch & get stars
+
+- **Show HN**: title like "Show HN: envcontract – a local-only contract for your .env (validate, drift, secret guard)". Lead with the privacy promise.
+- **r/Python and r/devops**: short post, link the repo, ask for feedback.
+- **Add a demo GIF** to the top of the README (use asciinema + agg, or a screen recorder). A visual demo dramatically increases stars.
+- Pin good first issues so contributors have an entry point.
+
+---
+
+## What's left to BUILD (optional, post-launch)
+
+- Demo GIF/asciinema in README (high impact, do this before Show HN).
+- `.vscode/settings.json` for contributors (interpreter, pytest, ruff).
+- Multi-environment support (`.env.development`, `.env.production` against one schema).
+- VS Code extension for inline schema validation.
+- `envcontract sync` to interactively update a local `.env` to match schema additions.
+
+---
+
+## Quick status
+
+| Item | State |
+|------|-------|
+| 4 commands (init/check/diff/guard) | ✅ done |
+| 29 tests + lint | ✅ passing |
+| Privacy invariants (no-network, no secret printing) | ✅ enforced by tests |
+| README / CONTRIBUTING / LICENSE / CI / pre-commit | ✅ done |
+| Wheel + sdist built | ✅ in `dist/` |
+| Placeholders replaced | ⬜ you |
+| GitHub repo | ⬜ you |
+| PyPI publish | ⬜ you |
+| Demo GIF + launch posts | ⬜ optional |

envcontract-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,34 @@
+# 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/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "envcontract"
+version = "0.1.0"
+description = "The contract for your .env — validate it, catch team drift, and never commit a secret. 100% local."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Hamza Mansoor" }]
+keywords = ["dotenv", "env", "environment-variables", "validation", "secrets", "cli", "pre-commit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "pydantic>=2.0",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "ruff>=0.4", "mypy>=1.0"]
+
+[project.scripts]
+envcontract = "envcontract.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/hamzamansoorch/envcontract"
+Issues = "https://github.com/hamzamansoorch/envcontract/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/envcontract"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

envcontract-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"