Skip to content

Commit 01cc707

Browse files
lbednerlbedner
authored
Merge pull request #5 from lbedner/typer
Add Typer CLI And Cookiecutter
2 parents 082a87f + 777f94a commit 01cc707

102 files changed

Lines changed: 9141 additions & 895 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -65,46 +65,6 @@ jobs:
6565
run: uv sync --all-extras
6666

6767
- name: Run tests
68-
run: uv run pytest -v
68+
run: uv run pytest -v -m "not slow"
6969

70-
docker-build:
71-
runs-on: ubuntu-latest
72-
steps:
73-
- uses: actions/checkout@v4
74-
75-
- name: Set up Docker Buildx
76-
uses: docker/setup-buildx-action@v3
77-
78-
- name: Build Docker image
79-
run: docker build -t aegis-stack:test .
80-
81-
- name: Test Docker container
82-
run: |
83-
# Start container in background
84-
docker run -d --name aegis-test -p 8000:8000 aegis-stack:test webserver
85-
86-
# Wait for container to be ready with retry logic
87-
echo "Waiting for container to be ready..."
88-
for i in {1..15}; do
89-
if curl -sf http://localhost:8000/health > /dev/null 2>&1; then
90-
echo "Container is ready!"
91-
break
92-
fi
93-
if [ $i -eq 15 ]; then
94-
echo "Container failed to start after 15 attempts"
95-
echo "Container logs:"
96-
docker logs aegis-test
97-
echo "Container status:"
98-
docker ps -a | grep aegis-test
99-
exit 1
100-
fi
101-
echo "Attempt $i/15 - waiting..."
102-
sleep 3
103-
done
104-
105-
# Test health endpoint one more time to be sure
106-
curl -f http://localhost:8000/health
107-
108-
# Clean up
109-
docker stop aegis-test
110-
docker rm aegis-test
70+

‎Makefile‎

Lines changed: 86 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,6 @@
1-
# Aegis Stack Makefile
2-
3-
# Run the application locally via Docker
4-
run-local: ## Run the application locally via Docker
5-
@docker compose --profile dev up webserver
6-
7-
# Run the application locally without Docker (for development)
8-
run-dev: ## Run the application locally without Docker
9-
@uv run python -m app.entrypoints.webserver
1+
# Aegis Stack CLI Development Makefile
2+
# This Makefile is for developing the Aegis Stack CLI tool itself.
3+
# Generated projects have their own Makefiles for application development.
104

115
# Run tests
126
test: ## Run tests
@@ -16,6 +10,15 @@ test: ## Run tests
1610
lint: ## Run linting with ruff
1711
@uv run ruff check .
1812

13+
# Auto-fix linting issues
14+
fix: ## Auto-fix linting and formatting issues
15+
@uv run ruff check . --fix
16+
@uv run ruff format .
17+
18+
# Format code only
19+
format: ## Format code with ruff
20+
@uv run ruff format .
21+
1922
# Run type checking
2023
typecheck: ## Run type checking with mypy
2124
@uv run mypy .
@@ -25,7 +28,7 @@ check: lint typecheck test ## Run all checks
2528

2629
# Install dependencies
2730
install: ## Install dependencies with uv
28-
@uv sync
31+
uv sync --all-extras
2932

3033
# Clean up cache files
3134
clean: ## Clean up cache files
@@ -40,31 +43,83 @@ docs-serve: ## Serve documentation locally with live reload on port 8001
4043
docs-build: ## Build the static documentation site
4144
@uv run mkdocs build
4245

43-
# Docker commands
44-
docker-build: ## Build the Docker image
45-
@docker build -t aegis-stack:latest .
46-
47-
docker-up: ## Start development services
48-
@docker compose --profile dev up -d
49-
50-
docker-down: ## Stop all services
51-
@docker compose down
52-
53-
docker-logs: ## Follow logs for all services
54-
@docker compose logs -f
55-
56-
docker-webserver: ## Run webserver in Docker
57-
@docker compose --profile dev up webserver
58-
59-
docker-test: ## Run tests in Docker
60-
@docker compose --profile test run --rm test_runner
46+
# CLI Development Commands
47+
cli-test: ## Test CLI commands locally
48+
@uv run python -m aegis --help
49+
@echo "✅ CLI command working"
6150

6251
# Show help
6352
help: ## Show this help message
6453
@echo "Available commands:"
65-
@grep -E '^[a-zA-Z_-]+:.*?## .*$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $1, $2}'
66-
67-
.PHONY: run-local run-dev test lint typecheck check install clean docs-serve docs-build docker-build docker-up docker-down docker-logs docker-webserver docker-test help
54+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
55+
56+
# ============================================================================
57+
# TEMPLATE TESTING TARGETS
58+
# For rapid iteration on cookiecutter template changes
59+
#
60+
# These targets help with the development workflow when modifying the
61+
# cookiecutter templates in aegis/templates/cookiecutter-aegis-project/
62+
#
63+
# Typical workflow:
64+
# 1. Make changes to template files
65+
# 2. Run 'make test-template-quick' for fast feedback
66+
# 3. Run 'make test-template' for full validation
67+
# 4. Run 'make clean-test-projects' to cleanup
68+
# ============================================================================
69+
70+
test-template-quick: ## Quick template test - generate basic project without validation
71+
@echo "🚀 Quick template test - generating basic project..."
72+
@chmod -R +w ../test-basic-stack 2>/dev/null || true
73+
@rm -rf ../test-basic-stack
74+
@env -u VIRTUAL_ENV uv run aegis init test-basic-stack --output-dir .. --no-interactive --force --yes
75+
@echo "📦 Setting up virtual environment and CLI..."
76+
@cd ../test-basic-stack && chmod -R +w .venv 2>/dev/null || true && rm -rf .venv && env -u VIRTUAL_ENV uv sync --extra dev --extra docs
77+
@cd ../test-basic-stack && env -u VIRTUAL_ENV uv pip install -e .
78+
@echo "✅ Basic test project generated in ../test-basic-stack/"
79+
@echo " CLI command 'test-basic-stack' is now available"
80+
@echo " Run 'cd ../test-basic-stack && make check' to validate"
81+
82+
test-template: ## Full template test - generate project and run validation
83+
@echo "🛡️ Full template test - generating and validating project..."
84+
@chmod -R +w ../test-basic-stack 2>/dev/null || true
85+
@rm -rf ../test-basic-stack
86+
@env -u VIRTUAL_ENV uv run aegis init test-basic-stack --output-dir .. --no-interactive --force --yes
87+
@echo "📦 Installing dependencies and CLI..."
88+
@cd ../test-basic-stack && chmod -R +w .venv 2>/dev/null || true && rm -rf .venv && env -u VIRTUAL_ENV uv sync --extra dev --extra docs
89+
@cd ../test-basic-stack && env -u VIRTUAL_ENV uv pip install -e .
90+
@echo "🔍 Running validation checks..."
91+
@cd ../test-basic-stack && env -u VIRTUAL_ENV make check
92+
@echo "🧪 Testing CLI script installation..."
93+
@cd ../test-basic-stack && env -u VIRTUAL_ENV uv run test-basic-stack --help >/dev/null && echo "✅ CLI script 'test-basic-stack --help' works" || echo "⚠️ CLI script test failed"
94+
@cd ../test-basic-stack && env -u VIRTUAL_ENV uv run test-basic-stack health quick >/dev/null 2>&1 && echo "✅ CLI script 'test-basic-stack health quick' works" || echo "ℹ️ Health command test skipped (requires running backend)"
95+
@echo "✅ Template test completed successfully!"
96+
@echo " Test project available in ../test-basic-stack/"
97+
@echo " CLI command 'test-basic-stack' is available"
98+
99+
test-template-with-components: ## Test template with scheduler component included
100+
@echo "🧩 Component template test - generating project with scheduler..."
101+
@chmod -R +w ../test-component-stack 2>/dev/null || true
102+
@rm -rf ../test-component-stack
103+
@env -u VIRTUAL_ENV uv run aegis init test-component-stack --components scheduler --output-dir .. --no-interactive --force --yes
104+
@echo "📦 Installing dependencies and CLI..."
105+
@cd ../test-component-stack && chmod -R +w .venv 2>/dev/null || true && rm -rf .venv && env -u VIRTUAL_ENV uv sync --extra dev --extra docs
106+
@cd ../test-component-stack && env -u VIRTUAL_ENV uv pip install -e .
107+
@echo "🔍 Running validation checks..."
108+
@cd ../test-component-stack && env -u VIRTUAL_ENV make check
109+
@echo "🧪 Testing CLI script installation..."
110+
@cd ../test-component-stack && env -u VIRTUAL_ENV uv run test-component-stack --help >/dev/null && echo "✅ CLI script 'test-component-stack --help' works" || echo "⚠️ CLI script test failed"
111+
@cd ../test-component-stack && env -u VIRTUAL_ENV uv run test-component-stack health quick >/dev/null 2>&1 && echo "✅ CLI script 'test-component-stack health quick' works" || echo "ℹ️ Health command test skipped (requires running backend)"
112+
@echo "✅ Component template test completed successfully!"
113+
@echo " Test project available in ../test-component-stack/"
114+
@echo " CLI command 'test-component-stack' is available"
115+
116+
clean-test-projects: ## Remove all generated test project directories
117+
@echo "🧹 Cleaning up test projects..."
118+
@chmod -R +w ../test-basic-stack ../test-component-stack 2>/dev/null || true
119+
@rm -rf ../test-basic-stack ../test-component-stack 2>/dev/null || true
120+
@echo "✅ Test projects cleaned up"
121+
122+
.PHONY: test lint fix format typecheck check install clean docs-serve docs-build cli-test test-template-quick test-template test-template-with-components clean-test-projects help
68123

69124
# Default target
70125
.DEFAULT_GOAL := help

‎README.md‎

Lines changed: 39 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,65 +4,62 @@
44
[![Documentation](https://github.com/lbedner/aegis-stack/workflows/Deploy%20Documentation/badge.svg)](https://github.com/lbedner/aegis-stack/actions/workflows/docs.yml)
55
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
66

7-
**A production-ready, async-first Python foundation for builders who refuse to wait.**
7+
**Build production-ready Python applications with your chosen components.**
88

9-
Aegis Stack provides a minimal, yet powerful, set of tools and patterns to help you build and deploy robust, scalable applications quickly. It's designed for developers who think in systems, not scripts, and who value speed, simplicity, and scalability.
9+
Aegis Stack is a CLI-driven framework for creating custom Python applications. Select exactly the components you need - no bloat, no unused dependencies.
1010

11-
---
11+
## 🚀 Quick Start
1212

13-
## Core Features
14-
15-
- **Full-Stack Python:** A unified development experience with [FastAPI](https://fastapi.tiangolo.com/) for the backend and [Flet](https://flet.dev/) for the frontend.
16-
- **Async-First Architecture:** Built from the ground up with `asyncio` to handle high-concurrency workloads efficiently.
17-
- **Composable Lifecycle Management:** A powerful, registry-based system for managing startup and shutdown events.
18-
- **Automatic Service Discovery:** A "drop-in" architecture where services are automatically discovered and integrated, no manual configuration required.
19-
- **Structured, Production-Ready Logging:** Out-of-the-box structured logging with `structlog`, providing human-readable logs for development and JSON logs for production.
20-
- **Modern Documentation:** A beautiful, maintainable documentation site powered by [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
13+
```bash
14+
# Install
15+
pip install aegis-stack
2116

22-
## Philosophy
17+
# Create a simple API
18+
aegis init my-api
2319

24-
Aegis Stack is built on three pillars:
20+
# Create with background processing
21+
aegis init task-processor --components scheduler
2522

26-
1. **Speed:** Get from idea to production as quickly as possible.
27-
2. **Simplicity:** Favor clear, Pythonic patterns over complex, magical frameworks.
28-
3. **Scalability:** Start with a simple monolith and evolve into a distributed system as your needs grow.
23+
# Start building
24+
cd my-project && uv sync && source .venv/bin/activate && make run-local
25+
```
2926

27+
## 🧩 Available Components
3028

31-
## Getting Started
29+
| Component | Purpose | Status |
30+
|-----------|---------|--------|
31+
| **Core** (FastAPI + Flet) | Web API + Frontend | ✅ **Included** |
32+
| **Scheduler** | Background tasks, cron jobs | ✅ **Available** |
33+
| **Database** | PostgreSQL + SQLAlchemy + Alembic | 🚧 **Coming Soon** |
34+
| **Cache** | Redis caching and sessions | 🚧 **Coming Soon** |
3235

33-
### Environment Setup
36+
## What You Get
3437

35-
1. **Copy the environment template:**
36-
```bash
37-
cp .env.example .env
38-
```
38+
- **FastAPI backend** with automatic API documentation
39+
- **Flet frontend** with system health dashboard
40+
- **CLI management** with health monitoring commands
41+
- **Production ready** with structured logging and containerization
42+
- **Async-first** architecture for high-concurrency workloads
3943

40-
2. **Customize your environment:**
41-
Edit `.env` to match your local setup. The defaults work for development.
44+
## 📱 System Health Dashboard
4245

43-
### Usage
46+
![System Health Dashboard](docs/images/dashboard.png)
4447

45-
This project uses a `Makefile` to provide convenient commands for common tasks.
48+
Real-time monitoring with component status, health percentages, and cross-platform deployment (web, desktop, mobile).
4649

47-
### Running the Application
50+
## 📚 Learn More
4851

49-
To run the local development server with live reloading:
50-
```bash
51-
make run-local
52-
```
53-
The application will be available at `http://127.0.0.1:8000`.
52+
- **[📖 CLI Reference](docs/cli-reference.md)** - Complete command reference
53+
- **[🏗️ Components](docs/components/index.md)** - Deep dive into available components
54+
- **[🧠 Philosophy](docs/philosophy.md)** - Architecture and design principles
5455

55-
### Documentation
56+
## Development Commands
5657

57-
To serve the documentation locally with live reloading:
5858
```bash
59-
make docs-serve
59+
make run-local # Start development server
60+
make test # Run test suite
61+
make check # Run all quality checks
62+
make docs-serve # Serve documentation
6063
```
61-
The documentation will be available at `http://localhost:8001/aegis-stack/`.
62-
63-
### Code Quality and Tests
6464

65-
To run all checks (linting, type checking, and tests) at once:
66-
```bash
67-
make check
68-
```
65+
Built on FastAPI, Flet, Typer, and other open-source tools.

‎aegis/__init__.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
"""
2+
Aegis Stack CLI - Component generation and project management tools.
3+
"""
4+
5+
__version__ = "0.1.0"

0 commit comments

Comments
 (0)