aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/clean-validation/Makefile

@@ -0,0 +1,211 @@
+# clean-validation - Aegis Stack Project
+# Developer-friendly commands for Docker workflow
+
+#=============================================================================
+# CORE DOCKER COMMANDS
+#=============================================================================
+
+build: ## Build all Docker images (safe, sequential)
+	@echo "🔨 Building Docker images..."
+	@docker compose build
+
+serve: ## Run all services (assumes images are built)
+	@echo "🚀 Starting services... (Press Ctrl+C to stop)"
+	@docker compose --profile dev up
+
+serve-bg: ## Run all services in background
+	@echo "🚀 Starting services in background..."
+	@docker compose --profile dev up -d
+
+stop: ## Gracefully stop all services
+	@echo "⏹️  Stopping services..."
+	@docker compose --profile dev down
+
+clean: ## Nuclear cleanup - remove containers, networks, and images
+	@echo "🧹 Nuclear cleanup - removing everything..."
+	@docker compose down --remove-orphans --volumes --rmi all 2>/dev/null || true
+	@docker system prune -f
+
+#=============================================================================
+# DEVELOPER WORKFLOW COMMANDS (the ones you'll actually use)
+#=============================================================================
+
+rebuild: build serve ## Build images and start services
+
+refresh: clean build serve ## Nuclear reset - clean everything and rebuild
+
+restart: stop serve ## Quick restart (no rebuild)
+
+#=============================================================================
+# DEBUGGING AND LOGS
+#=============================================================================
+
+logs: ## Follow logs from all services
+	@echo "📋 Following all service logs..."
+	@docker compose logs -f
+
+logs-web: ## Follow webserver logs only
+	@echo "📋 Following webserver logs..."
+	@docker compose logs -f webserver
+
+logs-worker: ## Follow worker logs only
+	@echo "📋 Following worker logs..."
+	@docker compose logs -f worker-system worker-load-test
+
+logs-redis: ## Follow Redis logs only
+	@echo "📋 Following Redis logs..."
+	@docker compose logs -f redis
+
+logs-scheduler: ## Follow scheduler logs only
+	@echo "📋 Following scheduler logs..."
+	@docker compose logs -f scheduler
+
+shell: ## Open shell in webserver container
+	@echo "🐚 Opening shell in webserver container..."
+	@docker compose exec webserver /bin/bash
+
+shell-worker: ## Open shell in worker container
+	@echo "🐚 Opening shell in worker container..."
+	@docker compose exec worker-system /bin/bash
+
+ps: ## Show running containers
+	@echo "📊 Docker containers status:"
+	@docker compose ps
+
+#=============================================================================
+# REDIS DEBUGGING
+#=============================================================================
+
+redis-cli: ## Connect to Redis CLI
+	@echo "🔧 Connecting to Redis CLI..."
+	@docker compose exec redis redis-cli
+
+redis-stats: ## Show Redis memory and stats
+	@echo "📊 Redis statistics:"
+	@docker compose exec redis redis-cli info memory
+
+redis-keys: ## Show all Redis keys
+	@echo "🔑 Redis keys:"
+	@docker compose exec redis redis-cli keys "*"
+
+redis-reset: ## Clear all Redis data
+	@echo "🔄 Clearing all Redis data..."
+	@docker compose exec redis redis-cli flushall
+
+#=============================================================================
+# HEALTH AND TESTING
+#=============================================================================
+
+health: ## Check system health status
+	@echo "🩺 Checking system health..."
+	@uv run clean-validation health status
+
+health-detailed: ## Detailed system health information
+	@echo "🩺 Detailed system health..."
+	@uv run clean-validation health status --detailed
+
+health-json: ## System health as JSON
+	@uv run clean-validation health status --json
+
+health-probe: ## Health probe (exits 1 if unhealthy)
+	@uv run clean-validation health probe
+
+test: ## Run tests locally
+	@echo "🧪 Running tests..."
+	@uv run pytest
+
+test-verbose: ## Run tests with verbose output
+	@echo "🧪 Running tests (verbose)..."
+	@uv run pytest -v
+
+#=============================================================================
+# CODE QUALITY (local development tools)
+#=============================================================================
+
+lint: ## Check code style with ruff
+	@echo "🔍 Running linting..."
+	@uv run ruff check .
+
+fix: ## Auto-fix linting and formatting issues
+	@echo "🔧 Auto-fixing code issues..."
+	@uv run ruff check . --fix
+	@uv run ruff format .
+
+format: ## Format code with ruff
+	@echo "💄 Formatting code..."
+	@uv run ruff format .
+
+typecheck: ## Run type checking with mypy
+	@echo "🔍 Running type checking..."
+	@uv run mypy app/ --no-error-summary
+
+check: lint typecheck test ## Run all code quality checks
+	@echo "✅ All checks completed successfully!"
+
+#=============================================================================
+# PROJECT MANAGEMENT
+#=============================================================================
+
+install: ## Install/sync dependencies with uv
+	@echo "📦 Installing dependencies..."
+	@uv sync --all-extras
+
+deps-update: ## Update dependencies
+	@echo "📦 Updating dependencies..."
+	@uv sync --upgrade
+
+clean-cache: ## Clean Python cache files
+	@echo "🧹 Cleaning Python cache files..."
+	@find . -type d -name "__pycache__" -exec rm -rf {} +
+	@find . -type f -name "*.pyc" -delete
+
+#=============================================================================
+# DOCUMENTATION
+#=============================================================================
+
+docs-serve: ## Serve documentation locally (http://localhost:8001)
+	@echo "📚 Serving documentation on http://localhost:8001"
+	@uv run mkdocs serve --dev-addr 0.0.0.0:8001
+
+docs-build: ## Build static documentation
+	@echo "📚 Building documentation..."
+	@uv run mkdocs build
+
+#=============================================================================
+# WORKER DEBUGGING (arq)
+#=============================================================================
+
+worker-test: ## Test workers in burst mode (process and exit)
+	@echo "🧪 Testing system worker in burst mode..."
+	@uv run python -m arq app.components.worker.queues.system.WorkerSettings --burst
+
+#=============================================================================
+# HELP AND INFO
+#=============================================================================
+
+status: ## Show current system status
+	@echo "📊 Current system status:"
+	@echo
+	@echo "🐳 Docker containers:"
+	@docker compose ps || echo "No containers running"
+	@echo
+	@echo "📦 Dependencies:"
+	@uv pip list | head -20 || echo "Dependencies not installed"
+
+help: ## Show this help message
+	@echo "clean-validation development commands:"
+	@echo
+	@echo "🚀 WORKFLOW COMMANDS (start here):"
+	@echo "  make refresh      - Nuclear reset (clean + build + serve)"
+	@echo "  make rebuild      - Build and serve"
+	@echo "  make restart      - Quick restart"
+	@echo
+	@echo "🔧 CORE COMMANDS:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "💡 TIP: Use 'make refresh' when everything is broken!"
+
+.PHONY: build serve stop clean rebuild refresh restart logs logs-web logs-worker logs-redis logs-scheduler shell shell-worker ps redis-cli redis-stats redis-keys redis-reset health health-detailed health-json health-probe test test-verbose lint fix format typecheck check install deps-update clean-cache docs-serve docs-build worker-test status help
+
+# Default target - show help
+.DEFAULT_GOAL := help

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/clean-validation/README.md.j2

@@ -0,0 +1,172 @@
+# clean-validation 🛡️
+
+A production-ready async Python application built with Aegis Stack
+
+## Components
+
+This Aegis Stack project includes the following components:
+
+- **✅ Backend**: FastAPI-based async web server
+- **✅ Frontend**: Flet-based Python UI framework
+- **✅ Scheduler**: APScheduler-based async task scheduling
+- **✅ Database**: SQLite database with SQLModel ORM
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Installation
+
+1. **Install dependencies:**
+   ```bash
+   uv sync                    # Core dependencies only
+   # Or for development: uv sync --all-extras  (includes testing, linting, docs)
+   ```
+
+2. **Activate virtual environment:**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+3. **Set up environment:**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Set up database:**
+   ```bash
+   # Create data directory for SQLite database
+   mkdir -p data
+
+   # Database will be created automatically on first run
+   # Default location: data/app.db
+   ```
+
+5. **Run the application:**
+   ```bash
+   make server
+   ```
+
+The application will be available at `http://127.0.0.1:8000`.
+
+## Development
+
+### Running Tests
+```bash
+make test
+```
+
+### Code Quality
+```bash
+make check  # Run linting, type checking, and tests
+```
+
+### CLI Commands
+
+Your project gets its own CLI command **automatically installed** when first used - no setup required! 🎉
+
+```bash
+# Health monitoring (auto-installs CLI if needed)
+make health                     # Basic health check
+make health-detailed            # Detailed component status
+make health-json               # JSON output for scripts
+make health-quick              # Quick healthy/unhealthy check
+
+# Direct CLI usage (after first make command)
+clean-validation health check              # Basic health check
+clean-validation health check --detailed   # Detailed component status
+clean-validation health check --json       # JSON output for scripts
+clean-validation health quick              # Quick healthy/unhealthy check
+
+# Explore all commands
+clean-validation --help                    # See all available commands
+clean-validation health --help             # See health subcommand options
+```
+
+**Environment Issues?** If CLI commands don't work:
+```bash
+# Ensure you're in the project's virtual environment
+unset VIRTUAL_ENV               # Clear Docker contamination
+source .venv/bin/activate       # Activate local venv
+make health                     # This will auto-install CLI
+# Or manually: make install-cli
+```
+
+### Documentation
+```bash
+make docs-serve  # Serve docs at http://localhost:8001/clean-validation/
+```
+
+## Docker
+
+### Development
+```bash
+docker compose --profile dev up
+```
+
+### Production
+```bash
+docker compose --profile prod up
+```
+
+## Configuration
+
+### Database Settings
+
+The database component uses SQLite with the following default configuration:
+
+```bash
+# Environment variables (add to .env file)
+DATABASE_URL=sqlite:///data/app.db          # Database file location
+DATABASE_ENGINE_ECHO=false                  # Enable SQL query logging
+```
+
+### Database Usage
+
+```python
+from app.core.db import db_session
+from sqlmodel import SQLModel, Field, select
+
+# Define a model
+class User(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    email: str
+
+# Use the database
+with db_session() as session:
+    user = User(name="John Doe", email="john@example.com")
+    session.add(user)
+    # Auto-committed by context manager
+```
+
+## Project Structure
+
+```
+clean-validation/
+├── app/                    # Application code
+│   ├── components/         # Component implementations
+│   │   ├── backend/       # FastAPI backend
+│   │   └── frontend/      # Flet frontend
+│   │   └── scheduler/     # APScheduler background tasks
+│   ├── cli/               # CLI commands and health monitoring
+│   ├── core/              # Core utilities
+│   │   ├── config.py      # Environment-dependent configuration
+│   │   ├── constants.py   # Immutable constants (12-Factor App)
+│   │   ├── db.py          # Database connection and session management
+│   │   └── log.py         # Structured logging
+│   ├── entrypoints/       # Execution entry points
+│   ├── integrations/      # App composition layer
+├── tests/                 # Test suite
+├── docs/                  # Documentation
+├── docker-compose.yml     # Docker services
+└── pyproject.toml        # Project configuration
+```
+
+---
+
+Generated with [Aegis Stack](https://github.com/lbedner/aegis-stack) 🛡️

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/clean-validation/docker-compose.yml.j2

@@ -0,0 +1,78 @@
+
+x-app: &app
+  image: ${AEGIS_STACK_TAG:-aegis-stack:latest}
+  build:
+    context: .
+    args:
+      - AEGIS_STACK_VERSION=${AEGIS_STACK_VERSION:-dev}
+      - PORT=${PORT:-8000}
+  env_file:
+    - ${AEGIS_STACK_ENV_FILE:-.env}
+  volumes:
+    - .:/code
+    # Exclude .venv to prevent host/container virtual environment conflicts
+    - /code/.venv
+  environment:
+    # Docker container marker for entrypoint script
+    - DOCKER_CONTAINER=1
+    - PORT=${PORT:-8000}
+  labels:
+    logging: "aegis-stack"
+
+services:
+  # DEVELOPMENT PROFILE
+
+  webserver:
+    <<: *app
+    command:
+      - webserver
+    ports:
+      - "${PORT:-8000}:${PORT:-8000}"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:${PORT:-8000}/health/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '0.5'
+        reservations:
+          memory: 256M
+          cpus: '0.25'
+    profiles:
+      - dev
+  # Scheduler service (runs scheduler tasks independently)
+  scheduler:
+    <<: *app
+    command:
+      - scheduler
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: '0.25'
+        reservations:
+          memory: 128M
+          cpus: '0.1'
+    profiles:
+      - dev
+      - prod
+
+  # TEST PROFILE
+
+  test_runner:
+    <<: *app
+    command:
+      - test
+    env_file:
+      - ${AEGIS_STACK_ENV_FILE:-.env}
+    profiles:
+      - test
+
+volumes:
+  aegis-data:

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/clean-validation/mkdocs.yml.j2

@@ -0,0 +1,62 @@
+# mkdocs.yml
+site_name: clean-validation
+site_description: A production-ready async Python application built with Aegis Stack
+site_author: Your Name
+site_url: https://your-username.github.io/clean-validation/
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for light vs dark mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.top
+    - search.highlight
+    - search.suggest
+    - content.code.copy
+
+# Navigation structure
+nav:
+  - Home: index.md
+  - Development: development.md
+  - API Reference: api.md
+  - Health Monitoring: health.md
+  - Components:
+    - Scheduler: components/scheduler.md
+
+# Plugins
+plugins:
+  - gen-files:
+      scripts:
+        - scripts/gen_docs.py
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_root_heading: true
+            show_source: true
+
+# Markdown extensions
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+# Additional configuration for Mermaid dark mode support
+extra_javascript:
+  - https://unpkg.com/mermaid@10.6.0/dist/mermaid.min.js
+  - javascripts/mermaid-config.js
+
+extra_css:
+  - stylesheets/mermaid.css

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/clean-validation/pyproject.toml.j2

@@ -0,0 +1,120 @@
+[project]
+name = "clean-validation"
+version = "0.1.0"
+description = "A production-ready async Python application built with Aegis Stack"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+
+dependencies = [
+    "fastapi==0.116.1",
+    "flet[all]==0.28.3",
+    "uvicorn==0.35.0",
+    "structlog==25.4.0",
+    "pydantic-settings==2.10.1",
+    "typer==0.16.0",
+    # Pin click to avoid yanked versions (typer dependency)
+    "click==8.2.1",
+    # Rich CLI formatting
+    "rich==14.1.0",
+    # HTTP client for CLI API calls
+    "httpx==0.28.1",
+    # System monitoring
+    "psutil==7.0.0",
+    "apscheduler==3.10.4",
+    "sqlmodel>=0.0.14",
+    "sqlalchemy>=2.0.0",
+    "aiosqlite>=0.19.0",
+    "greenlet>=1.1.0",
+]
+
+[project.scripts]
+clean-validation = "app.cli.main:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.4.1",
+    "pytest-asyncio==1.1.0",
+    "ruff==0.12.7",
+    "mypy==1.17.1",
+    "types-psutil==7.0.0.20250801",
+    "pre-commit==4.2.0",
+    "pip-audit==2.9.0",
+]
+docs = [
+    "mkdocs==1.6.1",
+    "mkdocs-material==9.6.16",
+    "mkdocstrings[python]==0.30.0",
+    "mkdocs-gen-files==0.5.0",
+    "pymdown-extensions==10.16.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]  # Added UP for pyupgrade (modern Python syntax)
+ignore = []
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ruff.lint.isort]
+force-single-line = false
+force-sort-within-sections = true
+known-first-party = ["app"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = "flet.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "apscheduler.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "sqlmodel.*"
+ignore_missing_imports = true
+
+# Ignore imports for future components that may not exist yet
+[[tool.mypy.overrides]]
+module = "app.components.database.main"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "app.components.cache.main"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "app.components.worker.*"
+ignore_missing_imports = true
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+]