django-dev-helpers 0.1.0__tar.gz

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

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        django-version: ["4.2", "5.0", "5.1", "5.2", "6.0"]
+        exclude:
+          - python-version: "3.11"
+            django-version: "6.0"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -e ".[dev]"
+          uv pip install --system "Django==${{ matrix.django-version }}"
+
+      - name: Ruff check
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Tests
+        run: pytest -xvs
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Mypy
+        run: mypy src/django_dev_helpers

django_dev_helpers-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.env
+.env.*
+!.env.example
+!.env.sample
+.venv/
+venv/
+*.whl
+
+# Secrets / credentials (never commit these)
+*.pem
+*.key
+*.p12
+*.pfx
+*.keystore
+*.jks
+id_rsa
+id_dsa
+id_ecdsa
+id_ed25519
+credentials.json
+credentials.yml
+credentials.yaml
+service-account*.json
+
+# Project-specific dev-helper dotfiles
+.dev_helpers_token
+.dev_helpers_port
+.dev_helpers_pg_*
+.dev_helpers_redis_*
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+.DS_Store

django_dev_helpers-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: detect-private-key
+      - id: check-merge-conflict
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.21.2
+    hooks:
+      - id: pyupgrade
+        args: ["--py311-plus"]
+
+  - repo: https://github.com/adamchainz/django-upgrade
+    rev: 1.30.0
+    hooks:
+      - id: django-upgrade
+        args: ["--target-version", "4.2"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format

django_dev_helpers-0.1.0/.uv-cache/.gitignore

@@ -0,0 +1 @@
+*

django_dev_helpers-0.1.0/.uv-cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

django_dev_helpers-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

django_dev_helpers-0.1.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `lookup.source = "sidecar"` and inclusion of the run-site `.run-site-config`
+  TOML file in the `auto` lookup chain. Order is now: callable → env →
+  sidecar → settings.
+- `lookup.callable = "module:attr"` — full primary endpoint resolver,
+  pluggable per project.
+- `DEV_HELPERS_AUTOLOGIN_USERNAME` env var picked up as the autologin user
+  when `autologin.user_lookup_value` is not set explicitly.
+- Config validation in `conf.py` — unknown keys, invalid `gitignore.mode`,
+  invalid `lookup.source`, malformed `extra_cookies`, etc. raise
+  `ImproperlyConfigured` at app load.
+- `dev_helpers_doctor` now reports `.run-site-config` parse status and
+  warns when legacy `.run_site_*` files are present in the project root.
+- `docs/` directory with quickstart, configuration, autologin, dotfiles,
+  agent-help, standalone-usage, with-django-run-site, security guides.
+- Tests for the sidecar reader, config validation, view HTTP-method
+  restriction, AppConfig.ready orchestration, and a real-subprocess test
+  for token autoreload behavior.
+
+### Changed
+- Autologin view now restricted to `GET` (`@require_http_methods(["GET"])`).
+- Agent help prompt `shlex.quote`-s the DB user/password/name so passwords
+  containing quotes/spaces survive the shell snippet.
+- SIGTERM cleanup chains to the previously-installed handler instead of
+  replacing it; cleanup is idempotent across atexit + SIGTERM paths.
+- Browser auto-open and agent-help auto-print fire at most once per dev
+  session — re-runs of `AppConfig.ready()` (via Django's autoreloader)
+  are gated by `DEV_HELPERS_BROWSER_OPENED` / `DEV_HELPERS_HELP_PRINTED`
+  sentinel env vars.
+- Dotfile atomic writes now set explicit modes (token = `0o600`, others =
+  `0o644`) — the temp-file mode no longer leaks 0o600 to non-secret files.
+- Browser self-probe catches a narrow set of expected exceptions and no
+  longer logs every failed attempt with a traceback.
+- Browser open is skipped on Linux without `DISPLAY`/`WAYLAND_DISPLAY`.
+- `gitignore` mode warning now goes through `logger.warning` instead of
+  `print(stderr)`.
+
+### Fixed
+- `pyproject.toml` `pythonpath` now includes the repo root so `pytest`
+  works without a manual `PYTHONPATH=.`.
+- `pyproject.toml` `[dev]` extras now include `ruff` and `mypy` so CI
+  steps using them pass after `uv pip install -e ".[dev]"`.
+- `pyproject.toml` adds `[project.urls]` for OSS hygiene.
+- `__init__.py` exposes `__version__`.
+
+## [0.1.0] - 2026-05-07
+
+### Added
+- Autologin endpoint with token-based authentication
+- Dotfile management (token, port, PG, Redis)
+- Agent help / prompt template
+- Gitignore self-check
+- Browser auto-open with self-probe
+- Production safety kill switch
+- `dev_helpers_doctor` management command
+- `dev_helpers_print_help` management command
+- `dev_helpers_check_gitignore` management command

django_dev_helpers-0.1.0/CLAUDE.md

@@ -0,0 +1,31 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This is a Python package using a `src/` layout. Runtime code lives in `src/django_dev_helpers/`, including Django views, URL helpers, safety checks, configuration, dotfile support, browser opening, and management commands under `management/commands/`. Tests live in `tests/` and use the local Django settings module in `tests/settings.py`. Documentation is in `docs/`, with the frozen design spec in `docs/design/`. CI is defined in `.github/workflows/ci.yml`; packaging metadata and tool configuration are in `pyproject.toml`.
+
+## Build, Test, and Development Commands
+
+- `uv sync --extra dev`: install the package and development tools into the local environment.
+- `uv run pytest`: run the full pytest suite with `pytest-django`.
+- `uv run pytest tests/test_autologin_view.py`: run a focused test file.
+- `uv run ruff check .`: lint imports, pyupgrade rules, bugbear checks, and project style rules.
+- `uv run ruff format .`: format Python files.
+- `uv run mypy src/django_dev_helpers`: run type checks with Django stubs.
+- `uv build`: build the distributable package with Hatchling.
+
+## Coding Style & Naming Conventions
+
+Target Python 3.11 and keep code compatible with Django 4.2 through 5.2. Use 4-space indentation, typed public helpers where practical, and clear snake_case names for modules, functions, fixtures, and settings keys. Management commands should follow Django naming conventions, such as `dev_helpers_doctor.py`. Ruff is the source of truth for formatting and linting; line length is 120 characters.
+
+## Testing Guidelines
+
+Tests use `pytest`, `pytest-django`, and Django’s test database. Name tests `test_*.py` and test functions `test_<behavior>`. Prefer focused tests near the behavior being changed, and update fixtures in `tests/conftest.py` only when the setup is broadly useful. Run `uv run pytest` before submitting changes; run `uv run mypy src/django_dev_helpers` when public APIs, settings, or Django integration points change.
+
+## Commit & Pull Request Guidelines
+
+Recent commits use short, direct, capitalized subjects without prefixes, for example `Point CI badge and project URLs at iplweb org`. Keep the first line concise and describe the observable change. Pull requests should include a short summary, test results, linked issues when relevant, and docs updates for user-facing behavior. Include screenshots only for rendered documentation or browser-visible behavior.
+
+## Security & Configuration Tips
+
+This package provides development-only conveniences, including an autologin endpoint and generated dotfiles. Do not weaken the `DEBUG=False` safeguards, token checks, localhost restrictions, or failure behavior without updating `docs/security.md` and adding regression tests. Never commit generated `.dev_helpers_*` files or local secrets.

django_dev_helpers-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 django-dev-helpers contributors
+
+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.

django_dev_helpers-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: django-dev-helpers
+Version: 0.1.0
+Summary: Dev-time conveniences for Django projects: autologin endpoint, dotfiles for LLM agents, gitignore self-check
+Project-URL: Homepage, https://github.com/iplweb/django-dev-helpers
+Project-URL: Repository, https://github.com/iplweb/django-dev-helpers
+Project-URL: Issues, https://github.com/iplweb/django-dev-helpers/issues
+Project-URL: Changelog, https://github.com/iplweb/django-dev-helpers/blob/main/CHANGELOG.md
+Author: django-dev-helpers contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: django-stubs; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-django>=4; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# django-dev-helpers
+
+[![CI](https://github.com/iplweb/django-dev-helpers/actions/workflows/ci.yml/badge.svg)](https://github.com/iplweb/django-dev-helpers/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![Django](https://img.shields.io/badge/django-4.2%20%7C%205.0%20%7C%205.1%20%7C%205.2%20%7C%206.0-green)](https://www.djangoproject.com/)
+
+Dev-time conveniences for Django projects: autologin endpoint, dotfiles for LLM coding agents, agent help prompt, and gitignore self-check.
+
+## Features
+
+- **Autologin endpoint** — one URL logs in a user via token, no interactive login needed
+- **Dotfiles** — `.dev_helpers_token`, `.dev_helpers_port`, `.dev_helpers_pg_*`, `.dev_helpers_redis_*` written to project root for easy `cat` by LLM agents
+- **Agent help prompt** — copy-pasteable curl/psql/redis-cli commands printed at startup
+- **Gitignore self-check** — warns if dotfiles are not in `.gitignore`
+- **Browser auto-open** — opens autologin URL in browser after server starts
+- **Production-safe** — default-off, requires explicit `enabled=True`, raises on `DEBUG=False`
+
+## Installation
+
+```bash
+pip install django-dev-helpers
+# or
+uv add django-dev-helpers --group dev
+```
+
+## Quick Start
+
+1. Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_dev_helpers",
+]
+```
+
+2. Enable in settings:
+
+```python
+DJANGO_DEV_HELPERS = {"enabled": True}
+```
+
+Or via environment variable:
+```bash
+DJANGO_DEV_HELPERS_ENABLED=1 python manage.py runserver
+```
+
+3. Add URL patterns in your `urls.py`:
+
+```python
+from django_dev_helpers.urls import autologin_urlpatterns
+
+urlpatterns = [
+    *autologin_urlpatterns(),
+    # ... your other URLs
+]
+```
+
+That's it. On startup, the package will:
+- Generate an autologin token
+- Write dotfiles to your project root
+- Check `.gitignore`
+- Print agent help after first request
+- Open browser with autologin URL
+
+## Usage
+
+### Autologin
+
+```bash
+T=$(cat .dev_helpers_token)
+curl -L "http://localhost:8000/__autologin__/?token=$T"
+```
+
+### Management Commands
+
+```bash
+python manage.py dev_helpers_doctor          # Full diagnostic
+python manage.py dev_helpers_print_help      # Print agent prompt
+python manage.py dev_helpers_check_gitignore # Check .gitignore entries
+```
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Configuration reference](docs/configuration.md)
+- [Autologin endpoint](docs/autologin.md)
+- [Dotfiles + lookup chain](docs/dotfiles.md)
+- [Agent help / prompt](docs/agent-help.md)
+- [Standalone usage](docs/standalone-usage.md)
+- [Using with django-run-site](docs/with-django-run-site.md)
+- [Security](docs/security.md)
+- [Original design spec (frozen)](docs/design/spec-v0.1.md) — for design rationale
+
+## Configuration
+
+All configuration via `settings.DJANGO_DEV_HELPERS` dict. See [configuration docs](docs/configuration.md) for full reference.
+
+```python
+DJANGO_DEV_HELPERS = {
+    "enabled": True,
+    "autologin": {
+        "user_lookup_field": "username",
+        "user_lookup_value": "admin",
+        "url_path": "__autologin__/",
+        "redirect_to": "/",
+    },
+    "dotfiles": {
+        "enabled": True,
+    },
+    "agent_help": {
+        "auto_print": True,
+    },
+    "browser_open": {
+        "enabled": True,
+    },
+    "gitignore": {
+        "mode": "warn",  # warn | auto-add | error | off
+    },
+}
+```
+
+## Security
+
+This package exposes an autologin backdoor for development. It is **always off by default**:
+
+- `enabled` must be explicitly set to `True` (via settings or env var)
+- Raises `ImproperlyConfigured` if `DEBUG=False` and serving HTTP
+- Autologin view verifies token via `hmac.compare_digest` (timing-safe)
+- Only accepts requests from localhost/127.0.0.1 by default
+- Returns 404 (not 403/401) on any failure — endpoint appears non-existent
+
+**Never install this package in production.** Add it only to dev dependencies.
+
+## Requirements
+
+- Python >= 3.11
+- Django >= 4.2
+
+## Supported versions
+
+Combinations exercised on every push by the CI matrix
+(`.github/workflows/ci.yml`):
+
+|             | Python 3.11 | Python 3.12 | Python 3.13 |
+|-------------|:-----------:|:-----------:|:-----------:|
+| Django 4.2  |      ✓      |      ✓      |      ✓      |
+| Django 5.0  |      ✓      |      ✓      |      ✓      |
+| Django 5.1  |      ✓      |      ✓      |      ✓      |
+| Django 5.2  |      ✓      |      ✓      |      ✓      |
+| Django 6.0  |      —      |      ✓      |      ✓      |
+
+Django 6.0 requires Python ≥ 3.12, so the `(3.11, 6.0)` cell is excluded
+from CI.
+
+## License
+
+MIT

django_dev_helpers-0.1.0/README.md

@@ -0,0 +1,159 @@
+# django-dev-helpers
+
+[![CI](https://github.com/iplweb/django-dev-helpers/actions/workflows/ci.yml/badge.svg)](https://github.com/iplweb/django-dev-helpers/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![Django](https://img.shields.io/badge/django-4.2%20%7C%205.0%20%7C%205.1%20%7C%205.2%20%7C%206.0-green)](https://www.djangoproject.com/)
+
+Dev-time conveniences for Django projects: autologin endpoint, dotfiles for LLM coding agents, agent help prompt, and gitignore self-check.
+
+## Features
+
+- **Autologin endpoint** — one URL logs in a user via token, no interactive login needed
+- **Dotfiles** — `.dev_helpers_token`, `.dev_helpers_port`, `.dev_helpers_pg_*`, `.dev_helpers_redis_*` written to project root for easy `cat` by LLM agents
+- **Agent help prompt** — copy-pasteable curl/psql/redis-cli commands printed at startup
+- **Gitignore self-check** — warns if dotfiles are not in `.gitignore`
+- **Browser auto-open** — opens autologin URL in browser after server starts
+- **Production-safe** — default-off, requires explicit `enabled=True`, raises on `DEBUG=False`
+
+## Installation
+
+```bash
+pip install django-dev-helpers
+# or
+uv add django-dev-helpers --group dev
+```
+
+## Quick Start
+
+1. Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_dev_helpers",
+]
+```
+
+2. Enable in settings:
+
+```python
+DJANGO_DEV_HELPERS = {"enabled": True}
+```
+
+Or via environment variable:
+```bash
+DJANGO_DEV_HELPERS_ENABLED=1 python manage.py runserver
+```
+
+3. Add URL patterns in your `urls.py`:
+
+```python
+from django_dev_helpers.urls import autologin_urlpatterns
+
+urlpatterns = [
+    *autologin_urlpatterns(),
+    # ... your other URLs
+]
+```
+
+That's it. On startup, the package will:
+- Generate an autologin token
+- Write dotfiles to your project root
+- Check `.gitignore`
+- Print agent help after first request
+- Open browser with autologin URL
+
+## Usage
+
+### Autologin
+
+```bash
+T=$(cat .dev_helpers_token)
+curl -L "http://localhost:8000/__autologin__/?token=$T"
+```
+
+### Management Commands
+
+```bash
+python manage.py dev_helpers_doctor          # Full diagnostic
+python manage.py dev_helpers_print_help      # Print agent prompt
+python manage.py dev_helpers_check_gitignore # Check .gitignore entries
+```
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Configuration reference](docs/configuration.md)
+- [Autologin endpoint](docs/autologin.md)
+- [Dotfiles + lookup chain](docs/dotfiles.md)
+- [Agent help / prompt](docs/agent-help.md)
+- [Standalone usage](docs/standalone-usage.md)
+- [Using with django-run-site](docs/with-django-run-site.md)
+- [Security](docs/security.md)
+- [Original design spec (frozen)](docs/design/spec-v0.1.md) — for design rationale
+
+## Configuration
+
+All configuration via `settings.DJANGO_DEV_HELPERS` dict. See [configuration docs](docs/configuration.md) for full reference.
+
+```python
+DJANGO_DEV_HELPERS = {
+    "enabled": True,
+    "autologin": {
+        "user_lookup_field": "username",
+        "user_lookup_value": "admin",
+        "url_path": "__autologin__/",
+        "redirect_to": "/",
+    },
+    "dotfiles": {
+        "enabled": True,
+    },
+    "agent_help": {
+        "auto_print": True,
+    },
+    "browser_open": {
+        "enabled": True,
+    },
+    "gitignore": {
+        "mode": "warn",  # warn | auto-add | error | off
+    },
+}
+```
+
+## Security
+
+This package exposes an autologin backdoor for development. It is **always off by default**:
+
+- `enabled` must be explicitly set to `True` (via settings or env var)
+- Raises `ImproperlyConfigured` if `DEBUG=False` and serving HTTP
+- Autologin view verifies token via `hmac.compare_digest` (timing-safe)
+- Only accepts requests from localhost/127.0.0.1 by default
+- Returns 404 (not 403/401) on any failure — endpoint appears non-existent
+
+**Never install this package in production.** Add it only to dev dependencies.
+
+## Requirements
+
+- Python >= 3.11
+- Django >= 4.2
+
+## Supported versions
+
+Combinations exercised on every push by the CI matrix
+(`.github/workflows/ci.yml`):
+
+|             | Python 3.11 | Python 3.12 | Python 3.13 |
+|-------------|:-----------:|:-----------:|:-----------:|
+| Django 4.2  |      ✓      |      ✓      |      ✓      |
+| Django 5.0  |      ✓      |      ✓      |      ✓      |
+| Django 5.1  |      ✓      |      ✓      |      ✓      |
+| Django 5.2  |      ✓      |      ✓      |      ✓      |
+| Django 6.0  |      —      |      ✓      |      ✓      |
+
+Django 6.0 requires Python ≥ 3.12, so the `(3.11, 6.0)` cell is excluded
+from CI.
+
+## License
+
+MIT