packwise-skills 1.0.0 → 1.2.0

package/sub-skills/backend/python-server.md

@@ -1,164 +1,164 @@
-# Python Backend Build Sub-Skill
-
-Build Python backend services (FastAPI/Django/Flask/Litestar).
-
-**Current version**: Python 3.12+ / 3.13 (2025-2026)
-
-## When to Use
-
-- REST API / GraphQL API
-- Web application backend
-- AI/ML model serving
-- Data processing service
-- Research/academic projects
-- Admin panels / internal tools
-
-## Framework Quick Start
-
-### FastAPI (Recommended for new projects)
-
-```python
-from fastapi import FastAPI
-app = FastAPI()
-
-@app.get("/health")
-async def health():
-    return {"status": "ok"}
-
-@app.get("/api/users/{user_id}")
-async def get_user(user_id: int):
-    return {"user_id": user_id}
-```
-
-```bash
-uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
-```
-
-### Django (Full-featured, batteries-included)
-
-```bash
-django-admin startproject myproject
-cd myproject
-python manage.py migrate
-python manage.py collectstatic
-python manage.py runserver
-```
-
-### Flask (Lightweight, minimal)
-
-```python
-from flask import Flask
-app = Flask(__name__)
-
-@app.route("/health")
-def health():
-    return {"status": "ok"}
-```
-
-### Framework Comparison
-
-| Framework | Performance | Async | ORM | Admin | Best For |
-|-----------|------------|-------|-----|-------|---------|
-| FastAPI | Highest | Native | SQLAlchemy | Via admin | APIs, microservices, ML serving |
-| Django | Good | ASGI (since 4.1) | Built-in | Built-in | Full-stack web apps, CMS |
-| Flask | Moderate | Via extensions | SQLAlchemy | Via extensions | Simple APIs, microservices |
-| Litestar | High | Native | SQLAlchemy | Built-in | FastAPI alternative |
-
-## Build & Package
-
-```bash
-# FastAPI/Flask: run directly, no compilation needed
-# Django:
-python manage.py collectstatic       # Collect static files
-python manage.py migrate              # Database migration
-
-# Production WSGI/ASGI server
-# FastAPI/ASGI:
-pip install uvicorn[standard]
-uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
-
-# Django/Flask/WSGI:
-pip install gunicorn
-gunicorn -w 4 -b 0.0.0.0:8000 myapp.wsgi:application
-
-# Gunicorn + Uvicorn workers (async WSGI)
-gunicorn app:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
-```
-
-## Docker
-
-```dockerfile
-FROM python:3.13-slim AS builder
-WORKDIR /app
-COPY requirements.txt .
-RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
-
-FROM python:3.13-slim
-WORKDIR /app
-COPY --from=builder /install /usr/local
-COPY . .
-RUN groupadd -r appuser && useradd -r -g appuser appuser && \
-    chown -R appuser:appuser /app
-USER appuser
-EXPOSE 8000
-HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
-CMD ["gunicorn", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "app:app"]
-```
-
-## Dependency Management
-
-```bash
-# pip + requirements.txt (traditional)
-pip freeze > requirements.txt
-pip install -r requirements.txt
-
-# Poetry (recommended for new projects)
-poetry init
-poetry add fastapi uvicorn sqlalchemy
-poetry export -f requirements.txt --output requirements.txt
-
-# uv (fastest, Rust-based, pip-compatible)
-pip install uv
-uv pip install fastapi uvicorn
-uv pip compile requirements.in -o requirements.txt
-```
-
-## Gunicorn + Nginx
-
-```bash
-# Gunicorn (production WSGI server)
-gunicorn -w 4 -b 127.0.0.1:8000 myapp.wsgi:application
-
-# Nginx reverse proxy
-# upstream backend { server 127.0.0.1:8000; }
-# server {
-#     listen 80;
-#     server_name example.com;
-#     location / { proxy_pass http://backend; proxy_set_header Host $host; }
-# }
-```
-
-## Cloud Platforms
-
-| Platform | Method | Best For |
-|----------|--------|---------|
-| Railway | Git push | Quick deploy |
-| Render | Git push | Quick deploy |
-| Fly.io | Docker | Global deploy |
-| AWS Lambda | Mangum (ASGI adapter) | Serverless |
-| Vercel | Serverless Functions | FastAPI (limited) |
-| Aliyun FC | Serverless | China market |
-
-## Common Pitfalls
-
-| Issue | Fix |
-|-------|-----|
-| Dependency install failure | Pin exact versions; use `pip-compile` for locked deps |
-| Database migration | Run `alembic upgrade head` or `python manage.py migrate` in production |
-| Static files 404 | Nginx serves static files directly; Django: `collectstatic` |
-| Async not working | FastAPI: use `async def`; Django: enable ASGI; Flask: use Quart for async |
-| Python version mismatch | Specify `python:3.13-slim` in Dockerfile; match local and production |
-| `ModuleNotFoundError` | Ensure virtualenv activated; check `sys.path` |
-| WSGI vs ASGI confusion | FastAPI = ASGI (uvicorn); Django = WSGI (gunicorn) or ASGI (uvicorn) |
-| CORS error | FastAPI: `CORSMiddleware`; Django: `django-cors-headers`; Flask: `flask-cors` |
-| Memory leak in workers | Gunicorn: `--max-requests 1000` to restart workers periodically |
+# Python Backend Build Sub-Skill
+
+Build Python backend services (FastAPI/Django/Flask/Litestar).
+
+**Current version**: Python 3.12+ / 3.13 (2025-2026)
+
+## When to Use
+
+- REST API / GraphQL API
+- Web application backend
+- AI/ML model serving
+- Data processing service
+- Research/academic projects
+- Admin panels / internal tools
+
+## Framework Quick Start
+
+### FastAPI (Recommended for new projects)
+
+```python
+from fastapi import FastAPI
+app = FastAPI()
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+
+@app.get("/api/users/{user_id}")
+async def get_user(user_id: int):
+    return {"user_id": user_id}
+```
+
+```bash
+uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+### Django (Full-featured, batteries-included)
+
+```bash
+django-admin startproject myproject
+cd myproject
+python manage.py migrate
+python manage.py collectstatic
+python manage.py runserver
+```
+
+### Flask (Lightweight, minimal)
+
+```python
+from flask import Flask
+app = Flask(__name__)
+
+@app.route("/health")
+def health():
+    return {"status": "ok"}
+```
+
+### Framework Comparison
+
+| Framework | Performance | Async | ORM | Admin | Best For |
+|-----------|------------|-------|-----|-------|---------|
+| FastAPI | Highest | Native | SQLAlchemy | Via admin | APIs, microservices, ML serving |
+| Django | Good | ASGI (since 4.1) | Built-in | Built-in | Full-stack web apps, CMS |
+| Flask | Moderate | Via extensions | SQLAlchemy | Via extensions | Simple APIs, microservices |
+| Litestar | High | Native | SQLAlchemy | Built-in | FastAPI alternative |
+
+## Build & Package
+
+```bash
+# FastAPI/Flask: run directly, no compilation needed
+# Django:
+python manage.py collectstatic       # Collect static files
+python manage.py migrate              # Database migration
+
+# Production WSGI/ASGI server
+# FastAPI/ASGI:
+pip install uvicorn[standard]
+uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+
+# Django/Flask/WSGI:
+pip install gunicorn
+gunicorn -w 4 -b 0.0.0.0:8000 myapp.wsgi:application
+
+# Gunicorn + Uvicorn workers (async WSGI)
+gunicorn app:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
+```
+
+## Docker
+
+```dockerfile
+FROM python:3.13-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+FROM python:3.13-slim
+WORKDIR /app
+COPY --from=builder /install /usr/local
+COPY . .
+RUN groupadd -r appuser && useradd -r -g appuser appuser && \
+    chown -R appuser:appuser /app
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+CMD ["gunicorn", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "app:app"]
+```
+
+## Dependency Management
+
+```bash
+# pip + requirements.txt (traditional)
+pip freeze > requirements.txt
+pip install -r requirements.txt
+
+# Poetry (recommended for new projects)
+poetry init
+poetry add fastapi uvicorn sqlalchemy
+poetry export -f requirements.txt --output requirements.txt
+
+# uv (fastest, Rust-based, pip-compatible)
+pip install uv
+uv pip install fastapi uvicorn
+uv pip compile requirements.in -o requirements.txt
+```
+
+## Gunicorn + Nginx
+
+```bash
+# Gunicorn (production WSGI server)
+gunicorn -w 4 -b 127.0.0.1:8000 myapp.wsgi:application
+
+# Nginx reverse proxy
+# upstream backend { server 127.0.0.1:8000; }
+# server {
+#     listen 80;
+#     server_name example.com;
+#     location / { proxy_pass http://backend; proxy_set_header Host $host; }
+# }
+```
+
+## Cloud Platforms
+
+| Platform | Method | Best For |
+|----------|--------|---------|
+| Railway | Git push | Quick deploy |
+| Render | Git push | Quick deploy |
+| Fly.io | Docker | Global deploy |
+| AWS Lambda | Mangum (ASGI adapter) | Serverless |
+| Vercel | Serverless Functions | FastAPI (limited) |
+| Aliyun FC | Serverless | China market |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Dependency install failure | Pin exact versions; use `pip-compile` for locked deps |
+| Database migration | Run `alembic upgrade head` or `python manage.py migrate` in production |
+| Static files 404 | Nginx serves static files directly; Django: `collectstatic` |
+| Async not working | FastAPI: use `async def`; Django: enable ASGI; Flask: use Quart for async |
+| Python version mismatch | Specify `python:3.13-slim` in Dockerfile; match local and production |
+| `ModuleNotFoundError` | Ensure virtualenv activated; check `sys.path` |
+| WSGI vs ASGI confusion | FastAPI = ASGI (uvicorn); Django = WSGI (gunicorn) or ASGI (uvicorn) |
+| CORS error | FastAPI: `CORSMiddleware`; Django: `django-cors-headers`; Flask: `flask-cors` |
+| Memory leak in workers | Gunicorn: `--max-requests 1000` to restart workers periodically |

package/sub-skills/backend/rust-backend.md

@@ -1,118 +1,118 @@
-# Rust Backend Build Sub-Skill
-
-Build and package Rust backend services (Axum/Actix-Web/Rocket/Warp).
-
-**Current version**: Rust 1.82+ / Axum 0.7 / Actix-Web 4.x (2025-2026)
-
-## When to Use
-
-- High-performance API services
-- Microservices requiring low latency and minimal memory
-- WebSocket servers
-- System-level services (CLI backends, daemons)
-- Security-sensitive backends (memory safety guaranteed by compiler)
-
-## Build
-
-```bash
-# Standard build
-cargo build --release
-# Output: target/release/myapp
-
-# With version embedding
-cargo build --release
-# In build.rs:
-# println!("cargo:rustc-env=APP_VERSION={}", env!("CARGO_PKG_VERSION"));
-
-# Static binary (no system dependencies)
-RUSTFLAGS='-C target-feature=+crt-static' cargo build --release --target x86_64-unknown-linux-gnu
-
-# Cross-compile
-cargo install cross
-cross build --release --target x86_64-unknown-linux-gnu
-cross build --release --target aarch64-unknown-linux-gnu
-cross build --release --target x86_64-pc-windows-gnu
-cross build --release --target x86_64-apple-darwin
-```
-
-## Framework Quick Start
-
-### Axum (Recommended — Tokio team)
-
-```rust
-use axum::{routing::get, Router};
-use std::net::SocketAddr;
-
-#[tokio::main]
-async fn main() {
-    let app = Router::new()
-        .route("/", get(|| async { "Hello, World!" }))
-        .route("/health", get(|| async { "OK" }));
-
-    let addr = SocketAddr::from(([0, 0, 0, 0], 8080));
-    axum::serve(tokio::net::TcpListener::bind(addr).await.unwrap(), app)
-        .await
-        .unwrap();
-}
-```
-
-### Actix-Web (Highest raw performance)
-
-```rust
-use actix_web::{web, App, HttpServer, HttpResponse};
-
-#[actix_web::main]
-async fn main() -> std::io::Result<()> {
-    HttpServer::new(|| {
-        App::new()
-            .route("/", web::get().to(|| async { HttpResponse::Ok().body("Hello!") }))
-            .route("/health", web::get().to(|| async { HttpResponse::Ok().body("OK") }))
-    })
-    .bind("0.0.0.0:8080")?
-    .run()
-    .await
-}
-```
-
-## Docker
-
-```dockerfile
-FROM rust:1.82-slim AS builder
-WORKDIR /app
-COPY Cargo.toml Cargo.lock ./
-# Cache dependencies (create dummy src)
-RUN mkdir src && echo 'fn main(){}' > src/main.rs && cargo build --release && rm -rf src
-COPY src/ src/
-RUN touch src/main.rs && cargo build --release
-
-FROM debian:bookworm-slim
-RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
-    rm -rf /var/lib/apt/lists/* && \
-    groupadd -r appuser && useradd -r -g appuser appuser
-COPY --from=builder /app/target/release/myapp /myapp
-USER appuser
-EXPOSE 8080
-HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost:8080/health || exit 1
-CMD ["/myapp"]
-```
-
-## Selection Guide
-
-| Framework | Async Runtime | Performance | Ecosystem | Best For |
-|-----------|--------------|-------------|-----------|----------|
-| Axum | Tokio | High | Growing fast | New projects, middleware-heavy |
-| Actix-Web | Tokio | Highest | Mature | Maximum throughput |
-| Rocket | Tokio | High | Good | Rapid prototyping, ergonomic API |
-| Warp | Tokio | High | Smaller | Filter-based routing |
-| Poem | Tokio | High | Growing | OpenAPI integration |
-
-## Common Pitfalls
-
-| Issue | Fix |
-|-------|-----|
-| Binary too large | Use `strip = true` in Cargo.toml `[profile.release]`; use `upx --best` |
-| Slow compile | Use `sccache`; enable incremental compilation; reduce dependencies |
-| Cross-compile fails | Use `cross` tool; or Docker-based cross-compilation |
-| `openssl` build fails | Use `rustls` (pure Rust TLS) instead of native OpenSSL |
-| Missing system libs in Docker | Use `debian:bookworm-slim` (not `alpine`) for glibc compatibility |
-| Static linking issues | Use `x86_64-unknown-linux-musl` target for fully static binary |
+# Rust Backend Build Sub-Skill
+
+Build and package Rust backend services (Axum/Actix-Web/Rocket/Warp).
+
+**Current version**: Rust 1.82+ / Axum 0.7 / Actix-Web 4.x (2025-2026)
+
+## When to Use
+
+- High-performance API services
+- Microservices requiring low latency and minimal memory
+- WebSocket servers
+- System-level services (CLI backends, daemons)
+- Security-sensitive backends (memory safety guaranteed by compiler)
+
+## Build
+
+```bash
+# Standard build
+cargo build --release
+# Output: target/release/myapp
+
+# With version embedding
+cargo build --release
+# In build.rs:
+# println!("cargo:rustc-env=APP_VERSION={}", env!("CARGO_PKG_VERSION"));
+
+# Static binary (no system dependencies)
+RUSTFLAGS='-C target-feature=+crt-static' cargo build --release --target x86_64-unknown-linux-gnu
+
+# Cross-compile
+cargo install cross
+cross build --release --target x86_64-unknown-linux-gnu
+cross build --release --target aarch64-unknown-linux-gnu
+cross build --release --target x86_64-pc-windows-gnu
+cross build --release --target x86_64-apple-darwin
+```
+
+## Framework Quick Start
+
+### Axum (Recommended — Tokio team)
+
+```rust
+use axum::{routing::get, Router};
+use std::net::SocketAddr;
+
+#[tokio::main]
+async fn main() {
+    let app = Router::new()
+        .route("/", get(|| async { "Hello, World!" }))
+        .route("/health", get(|| async { "OK" }));
+
+    let addr = SocketAddr::from(([0, 0, 0, 0], 8080));
+    axum::serve(tokio::net::TcpListener::bind(addr).await.unwrap(), app)
+        .await
+        .unwrap();
+}
+```
+
+### Actix-Web (Highest raw performance)
+
+```rust
+use actix_web::{web, App, HttpServer, HttpResponse};
+
+#[actix_web::main]
+async fn main() -> std::io::Result<()> {
+    HttpServer::new(|| {
+        App::new()
+            .route("/", web::get().to(|| async { HttpResponse::Ok().body("Hello!") }))
+            .route("/health", web::get().to(|| async { HttpResponse::Ok().body("OK") }))
+    })
+    .bind("0.0.0.0:8080")?
+    .run()
+    .await
+}
+```
+
+## Docker
+
+```dockerfile
+FROM rust:1.82-slim AS builder
+WORKDIR /app
+COPY Cargo.toml Cargo.lock ./
+# Cache dependencies (create dummy src)
+RUN mkdir src && echo 'fn main(){}' > src/main.rs && cargo build --release && rm -rf src
+COPY src/ src/
+RUN touch src/main.rs && cargo build --release
+
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/* && \
+    groupadd -r appuser && useradd -r -g appuser appuser
+COPY --from=builder /app/target/release/myapp /myapp
+USER appuser
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost:8080/health || exit 1
+CMD ["/myapp"]
+```
+
+## Selection Guide
+
+| Framework | Async Runtime | Performance | Ecosystem | Best For |
+|-----------|--------------|-------------|-----------|----------|
+| Axum | Tokio | High | Growing fast | New projects, middleware-heavy |
+| Actix-Web | Tokio | Highest | Mature | Maximum throughput |
+| Rocket | Tokio | High | Good | Rapid prototyping, ergonomic API |
+| Warp | Tokio | High | Smaller | Filter-based routing |
+| Poem | Tokio | High | Growing | OpenAPI integration |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Binary too large | Use `strip = true` in Cargo.toml `[profile.release]`; use `upx --best` |
+| Slow compile | Use `sccache`; enable incremental compilation; reduce dependencies |
+| Cross-compile fails | Use `cross` tool; or Docker-based cross-compilation |
+| `openssl` build fails | Use `rustls` (pure Rust TLS) instead of native OpenSSL |
+| Missing system libs in Docker | Use `debian:bookworm-slim` (not `alpine`) for glibc compatibility |
+| Static linking issues | Use `x86_64-unknown-linux-musl` target for fully static binary |