@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/python-development-python-scaffold.md

@@ -0,0 +1,331 @@
+---
+name: python-development-python-scaffold
+description: "You are a Python project architecture expert specializing in scaffolding production-ready Python applications. Generate complete project structures with modern tooling (uv, FastAPI, Django), type hint"
+---
+
+# Python Project Scaffolding
+
+You are a Python project architecture expert specializing in scaffolding production-ready Python applications. Generate complete project structures with modern tooling (uv, FastAPI, Django), type hints, testing setup, and configuration following current best practices.
+
+## Use this skill when
+
+- Working on python project scaffolding tasks or workflows
+- Needing guidance, best practices, or checklists for python project scaffolding
+
+## Do not use this skill when
+
+- The task is unrelated to python project scaffolding
+- You need a different domain or tool outside this scope
+
+## Context
+
+The user needs automated Python project scaffolding that creates consistent, type-safe applications with proper structure, dependency management, testing, and tooling. Focus on modern Python patterns and scalable architecture.
+
+## Requirements
+
+$ARGUMENTS
+
+## Instructions
+
+### 1. Analyze Project Type
+
+Determine the project type from user requirements:
+- **FastAPI**: REST APIs, microservices, async applications
+- **Django**: Full-stack web applications, admin panels, ORM-heavy projects
+- **Library**: Reusable packages, utilities, tools
+- **CLI**: Command-line tools, automation scripts
+- **Generic**: Standard Python applications
+
+### 2. Initialize Project with uv
+
+```bash
+# Create new project with uv
+uv init <project-name>
+cd <project-name>
+
+# Initialize git repository
+git init
+echo ".venv/" >> .gitignore
+echo "*.pyc" >> .gitignore
+echo "__pycache__/" >> .gitignore
+echo ".pytest_cache/" >> .gitignore
+echo ".ruff_cache/" >> .gitignore
+
+# Create virtual environment
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+```
+
+### 3. Generate FastAPI Project Structure
+
+```
+fastapi-project/
+├── pyproject.toml
+├── README.md
+├── .gitignore
+├── .env.example
+├── src/
+│   └── project_name/
+│       ├── __init__.py
+│       ├── main.py
+│       ├── config.py
+│       ├── api/
+│       │   ├── __init__.py
+│       │   ├── deps.py
+│       │   ├── v1/
+│       │   │   ├── __init__.py
+│       │   │   ├── endpoints/
+│       │   │   │   ├── __init__.py
+│       │   │   │   ├── users.py
+│       │   │   │   └── health.py
+│       │   │   └── router.py
+│       ├── core/
+│       │   ├── __init__.py
+│       │   ├── security.py
+│       │   └── database.py
+│       ├── models/
+│       │   ├── __init__.py
+│       │   └── user.py
+│       ├── schemas/
+│       │   ├── __init__.py
+│       │   └── user.py
+│       └── services/
+│           ├── __init__.py
+│           └── user_service.py
+└── tests/
+    ├── __init__.py
+    ├── conftest.py
+    └── api/
+        ├── __init__.py
+        └── test_users.py
+```
+
+**pyproject.toml**:
+```toml
+[project]
+name = "project-name"
+version = "0.1.0"
+description = "FastAPI project description"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.27.0",
+    "pydantic>=2.6.0",
+    "pydantic-settings>=2.1.0",
+    "sqlalchemy>=2.0.0",
+    "alembic>=1.13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.26.0",
+    "ruff>=0.2.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+```
+
+**src/project_name/main.py**:
+```python
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .api.v1.router import api_router
+from .config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,
+    openapi_url=f"{settings.API_V1_PREFIX}/openapi.json",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(api_router, prefix=settings.API_V1_PREFIX)
+
+@app.get("/health")
+async def health_check() -> dict[str, str]:
+    return {"status": "healthy"}
+```
+
+### 4. Generate Django Project Structure
+
+```bash
+# Install Django with uv
+uv add django django-environ django-debug-toolbar
+
+# Create Django project
+django-admin startproject config .
+python manage.py startapp core
+```
+
+**pyproject.toml for Django**:
+```toml
+[project]
+name = "django-project"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "django>=5.0.0",
+    "django-environ>=0.11.0",
+    "psycopg[binary]>=3.1.0",
+    "gunicorn>=21.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "django-debug-toolbar>=4.3.0",
+    "pytest-django>=4.8.0",
+    "ruff>=0.2.0",
+]
+```
+
+### 5. Generate Python Library Structure
+
+```
+library-name/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── src/
+│   └── library_name/
+│       ├── __init__.py
+│       ├── py.typed
+│       └── core.py
+└── tests/
+    ├── __init__.py
+    └── test_core.py
+```
+
+**pyproject.toml for Library**:
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "library-name"
+version = "0.1.0"
+description = "Library description"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Your Name", email = "email@example.com"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "ruff>=0.2.0", "mypy>=1.8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/library_name"]
+```
+
+### 6. Generate CLI Tool Structure
+
+```python
+# pyproject.toml
+[project.scripts]
+cli-name = "project_name.cli:main"
+
+[project]
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.7.0",
+]
+```
+
+**src/project_name/cli.py**:
+```python
+import typer
+from rich.console import Console
+
+app = typer.Typer()
+console = Console()
+
+@app.command()
+def hello(name: str = typer.Option(..., "--name", "-n", help="Your name")):
+    """Greet someone"""
+    console.print(f"[bold green]Hello {name}![/bold green]")
+
+def main():
+    app()
+```
+
+### 7. Configure Development Tools
+
+**.env.example**:
+```env
+# Application
+PROJECT_NAME="Project Name"
+VERSION="0.1.0"
+DEBUG=True
+
+# API
+API_V1_PREFIX="/api/v1"
+ALLOWED_ORIGINS=["http://localhost:3000"]
+
+# Database
+DATABASE_URL="postgresql://user:pass@localhost:5432/dbname"
+
+# Security
+SECRET_KEY="your-secret-key-here"
+```
+
+**Makefile**:
+```makefile
+.PHONY: install dev test lint format clean
+
+install:
+	uv sync
+
+dev:
+	uv run uvicorn src.project_name.main:app --reload
+
+test:
+	uv run pytest -v
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run ruff format .
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -rf .pytest_cache .ruff_cache
+```
+
+## Output Format
+
+1. **Project Structure**: Complete directory tree with all necessary files
+2. **Configuration**: pyproject.toml with dependencies and tool settings
+3. **Entry Point**: Main application file (main.py, cli.py, etc.)
+4. **Tests**: Test structure with pytest configuration
+5. **Documentation**: README with setup and usage instructions
+6. **Development Tools**: Makefile, .env.example, .gitignore
+
+Focus on creating production-ready Python projects with modern tooling, type safety, and comprehensive testing setup.

package/merged-commands/python-development.md

@@ -0,0 +1,139 @@
+---
+name: python-development
+description: Modern Python development with Python 3.12+, Django, FastAPI, async patterns, and production best practices. Use for Python projects, APIs, data processing, or automation scripts.
+source: wshobson/agents
+license: MIT
+---
+
+# Python Development
+
+## Project Setup
+
+### Modern Python Project Structure
+```
+my-project/
+├── src/
+│   └── my_project/
+│       ├── __init__.py
+│       ├── main.py
+│       └── utils.py
+├── tests/
+│   ├── __init__.py
+│   └── test_main.py
+├── pyproject.toml
+├── README.md
+└── .gitignore
+```
+
+### pyproject.toml
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.100.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+
+[tool.ruff]
+line-length = 88
+select = ["E", "F", "I", "N", "W"]
+
+[tool.mypy]
+strict = true
+```
+
+## Type Hints
+
+```python
+from typing import TypeVar, Generic
+from collections.abc import Sequence
+
+T = TypeVar('T')
+
+def process_items(items: Sequence[str]) -> list[str]:
+    return [item.upper() for item in items]
+
+class Repository(Generic[T]):
+    def get(self, id: int) -> T | None: ...
+    def save(self, item: T) -> T: ...
+```
+
+## Async Patterns
+
+```python
+import asyncio
+from collections.abc import AsyncIterator
+
+async def fetch_all(urls: list[str]) -> list[dict]:
+    async with aiohttp.ClientSession() as session:
+        tasks = [fetch_one(session, url) for url in urls]
+        return await asyncio.gather(*tasks)
+
+async def stream_data() -> AsyncIterator[bytes]:
+    async with aiofiles.open('large_file.txt', 'rb') as f:
+        async for chunk in f:
+            yield chunk
+```
+
+## FastAPI Patterns
+
+```python
+from fastapi import FastAPI, Depends, HTTPException
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class UserCreate(BaseModel):
+    email: str
+    name: str
+
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    name: str
+
+@app.post("/users", response_model=UserResponse)
+async def create_user(
+    user: UserCreate,
+    db: Database = Depends(get_db)
+) -> UserResponse:
+    result = await db.users.create(user.model_dump())
+    return UserResponse(**result)
+```
+
+## Testing
+
+```python
+import pytest
+from unittest.mock import AsyncMock, patch
+
+@pytest.fixture
+def mock_db():
+    db = AsyncMock()
+    db.users.get.return_value = {"id": 1, "name": "Test"}
+    return db
+
+@pytest.mark.asyncio
+async def test_get_user(mock_db):
+    result = await get_user(1, db=mock_db)
+    assert result["name"] == "Test"
+    mock_db.users.get.assert_called_once_with(1)
+```
+
+## Best Practices
+
+- Use `ruff` for linting and formatting
+- Use `mypy` with strict mode
+- Prefer `pathlib.Path` over `os.path`
+- Use dataclasses or Pydantic for data structures
+- Use `asyncio` for I/O-bound operations
+- Use `contextlib.asynccontextmanager` for async resources

package/merged-commands/python-packaging.md

@@ -0,0 +1,36 @@
+---
+name: python-packaging
+description: Create distributable Python packages with proper project structure, setup.py/pyproject.toml, and publishing to PyPI. Use when packaging Python libraries, creating CLI tools, or distributing Python code.
+---
+
+# Python Packaging
+
+Comprehensive guide to creating, structuring, and distributing Python packages using modern packaging tools, pyproject.toml, and publishing to PyPI.
+
+## Use this skill when
+
+- Creating Python libraries for distribution
+- Building command-line tools with entry points
+- Publishing packages to PyPI or private repositories
+- Setting up Python project structure
+- Creating installable packages with dependencies
+- Building wheels and source distributions
+- Versioning and releasing Python packages
+- Creating namespace packages
+- Implementing package metadata and classifiers
+
+## Do not use this skill when
+
+- The task is unrelated to python packaging
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.