homehost 0.1.0__tar.gz

homehost-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug report
+about: Something isn't working
+labels: bug
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behavior:
+1. Run `homehost ...`
+2. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Actual behavior**
+What actually happened. Include the full error message / stack trace if there is one.
+
+**System info**
+Run `homehost doctor` and paste the output here.
+
+```
+# paste output here
+```
+
+**HomeHost version**
+Run `homehost --version` and paste here.
+
+```
+# paste output here
+```
+
+**Additional context**
+Add any other context about the problem here (e.g. project type, OS quirks, recent system changes).

homehost-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for HomeHost
+labels: enhancement
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Example: "I'm always frustrated when..."
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Who would benefit from this feature?**
+Describe the target audience (e.g. "developers hosting Flask apps", "non-technical users", etc.).
+
+**Additional context**
+Add any other context, mockups, or screenshots about the feature request here.

homehost-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,46 @@
+## Summary
+
+<!-- What does this PR do? Bullet-point the key changes. -->
+
+- 
+- 
+
+## Motivation
+
+<!-- Why is this change needed? Link related issues with "Fixes #123" or "Closes #123". -->
+
+## Type of change
+
+<!-- Check all that apply -->
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Refactor / code quality improvement
+- [ ] Documentation update
+- [ ] CI / tooling change
+
+## Test plan
+
+<!-- How did you verify this works? Check all completed items. -->
+
+- [ ] Added / updated unit tests in `tests/unit/`
+- [ ] All existing tests pass (`pytest tests/unit/ -v`)
+- [ ] Manually tested on macOS
+- [ ] Manually tested on Windows (if applicable)
+- [ ] Ran `homehost doctor` and confirmed no regressions
+- [ ] Linting passes (`ruff check homehost/`)
+- [ ] Type checks pass (`mypy homehost/ --ignore-missing-imports`)
+- [ ] Formatting is correct (`black --check homehost/ tests/`)
+
+## Screenshots / output
+
+<!-- For UI or CLI changes, paste terminal output or attach screenshots. -->
+
+## Checklist
+
+- [ ] My code follows the project's style guidelines
+- [ ] I have added docstrings to new public functions / classes
+- [ ] I have updated `CHANGELOG.md` if this is a user-facing change
+- [ ] Secrets and credentials are NOT hard-coded anywhere in my changes
+- [ ] I have read the [CONTRIBUTING](../CONTRIBUTING.md) guide (if it exists)

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

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "feature/**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [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 }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check homehost/
+
+      - name: Type check (mypy)
+        run: mypy homehost/ --ignore-missing-imports
+
+      - name: Format check (black)
+        run: black --check homehost/ tests/
+
+      - name: Run tests
+        run: pytest tests/unit/ -v --cov=homehost --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  lint-only:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - run: pip install ruff black mypy
+
+      - run: ruff check homehost/
+
+      - run: black --check homehost/ tests/

homehost-0.1.0/.gitignore

@@ -0,0 +1,100 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.pyo
+.venv/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.python-version
+
+# Testing
+.tox/
+.nox/
+.cache
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# HomeHost runtime data
+.homehost/
+caddy_data/
+cloudflared_config/
+
+# Caddy
+Caddyfile.local
+caddy.log
+
+# Secrets and environment
+.env
+.env.*
+*.key
+*.pem
+*.cert
+*.csr
+
+# Logs
+*.log
+logs/
+
+# Node.js (for template testing)
+node_modules/
+.npm
+.yarn/
+.pnp.*
+
+# Build artifacts
+dist/
+build/
+out/
+.next/
+.nuxt/
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+desktop.ini

homehost-0.1.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to HomeHost are documented in this file.
+
+The format follows [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]
+
+## [0.1.0] - 2026-05-30
+
+### Added
+
+#### Core
+- Initial public release of HomeHost
+- `homehost serve <path>` — serve any project from a local directory
+- `homehost setup` — interactive first-time setup wizard that installs Caddy and cloudflared
+- `homehost doctor` — diagnostic tool that checks the full installation and environment
+- `homehost new <template> <name>` — scaffold new projects from built-in starter templates
+- `homehost list` — list all currently running HomeHost projects
+- `homehost stop <name>` / `homehost stop --all` — stop one or all running projects
+- `homehost logs <name>` — stream live logs for a running project
+- `homehost config` — open the global config file in your default editor
+- `homehost update` — self-update HomeHost and managed binaries
+- `homehost version` — print version and dependency information
+
+#### Project Auto-detection
+- Automatic project type detection from directory contents (no config required)
+- Support for Static HTML/CSS/JS sites
+- Support for React apps (Create React App and Vite)
+- Support for Next.js apps (Pages Router and App Router)
+- Support for Express / generic Node.js servers
+- Support for Flask apps
+- Support for FastAPI apps
+- Support for Django apps
+- Support for generic Python apps (`main.py` / `app.py`)
+- Manual override via `homehost.toml` in project root
+
+#### Web Server
+- Caddy-based web serving with automatic binary management
+- Static file serving with directory listings disabled by default
+- Reverse proxy mode for app servers
+- Automatic Caddy installation on first run (macOS and Windows)
+- Automatic Caddy restart on configuration changes
+
+#### Public Tunneling
+- Cloudflare Tunnel integration via `cloudflared` for public HTTPS access
+- Automatic `cloudflared` binary installation on first run
+- Random subdomain generation (`https://<adjective>-<animal>-<n>.trycloudflare.com`)
+- Toggle tunnel on/off at runtime from TUI or web dashboard
+- Public URL displayed prominently in TUI with QR code
+
+#### TUI Dashboard (Terminal UI)
+- Textual-based full-screen TUI with real-time updates
+- Live log streaming from Caddy, app server, and cloudflared
+- Color-coded request log with method, path, status, and latency
+- Project status bar (running / stopped / error)
+- Keyboard shortcuts: `t` to toggle tunnel, `r` to restart, `q` to quit, `l` to clear logs
+- QR code display for instant mobile access to the public URL
+- Multi-project tab view when multiple projects are running
+
+#### Web Dashboard
+- FastAPI-backed dashboard at `http://localhost:9111`
+- Request log with filtering by status code, method, and path
+- Live traffic graph (requests per minute)
+- Project configuration viewer and editor
+- One-click tunnel toggle
+- Process health status for Caddy, app server, and cloudflared
+- Log download as plain text
+
+#### File Watcher / Auto-reload
+- `watchdog`-based file watcher for all project types
+- Debounced restarts to avoid churn during rapid file saves
+- Configurable watch paths and ignore patterns per project
+- Visual indicator in TUI when a reload is triggered
+
+#### Security
+- Automatic security headers on all responses:
+  - `Content-Security-Policy` (default-src 'self')
+  - `Strict-Transport-Security` (max-age=31536000; includeSubDomains)
+  - `X-Frame-Options: DENY`
+  - `X-Content-Type-Options: nosniff`
+  - `Referrer-Policy: strict-origin-when-cross-origin`
+  - `Permissions-Policy` (camera=(), microphone=(), geolocation=())
+- Rate limiting at 300 requests per minute per IP (configurable)
+- Optional HTTP Basic Auth (`homehost serve . --auth`)
+- bcrypt password hashing for stored credentials
+- No direct IP exposure (traffic routed through Cloudflare Tunnel)
+
+#### Configuration
+- Global config at `~/.homehost/config.toml` (auto-created on first run)
+- Per-project config via `homehost.toml` in project directory
+- Environment variable support via `--env-file` flag (defaults to `.env`)
+- All defaults sensible out of the box — config is optional
+
+#### Multi-project Support
+- Run multiple projects simultaneously on different ports
+- Each project gets its own Caddy process and optional tunnel
+- Unified TUI with tab navigation between projects
+- Web dashboard shows all projects in a sidebar
+
+#### Starter Templates
+- `static` — HTML/CSS/JS starter with responsive layout and modern CSS reset
+- `flask` — Flask app with SQLite, Jinja2 templates, and `.env` support
+- `fastapi` — FastAPI app with Pydantic models, auto-docs, and async routes
+- `nextjs` — Next.js 14 App Router starter with TypeScript and Tailwind CSS
+- `react` — React 18 + Vite starter with TypeScript
+
+#### Platform Support
+- macOS 12 (Monterey) and later
+- Windows 10 and Windows 11
+- Python 3.10, 3.11, and 3.12
+
+#### Developer Experience
+- Structured logging via `structlog`
+- Log files written to `~/.homehost/logs/`
+- Descriptive error codes (HH-1xx through HH-5xx) for all failure modes
+- `homehost doctor` outputs a shareable diagnostic report
+
+---
+
+[Unreleased]: https://github.com/homehost-dev/homehost/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/homehost-dev/homehost/releases/tag/v0.1.0