@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/error-ux-observability/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: "error-ux-observability"
+displayName: "Error UX & Observability"
+description: "Map backend failures to user-friendly messages, implement proper logging levels, and ensure observable error handling"
+keywords:
+  [
+    "error handling",
+    "error messages",
+    "logging",
+    "observability",
+    "user feedback",
+    "failure mapping",
+    "error ux",
+  ]
+---
+
+# Error UX & Observability
+
+## Overview
+
+This power helps you translate technical errors into user-friendly messages, implement proper logging for debugging, and ensure errors are observable in production.
+
+## When to Use
+
+- Implementing error handling in repositories/use cases
+- Mapping API errors to UI messages
+- Adding logging to track issues
+- Reviewing error handling code
+- Debugging production issues
+
+## Quick Reference
+
+### Failure to UI Message Mapping
+
+```dart
+// ✅ Map technical errors to user-friendly messages
+String getErrorMessage(Failure failure) {
+  return failure.when(
+    network: () => 'No internet connection. Please check your network.',
+    server: (code, message) {
+      if (code == 401) return 'Session expired. Please login again.';
+      if (code == 403) return 'You don\'t have permission for this action.';
+      if (code == 404) return 'Resource not found.';
+      if (code >= 500) return 'Server error. Please try again later.';
+      return message ?? 'Something went wrong.';
+    },
+    validation: (errors) => errors.values.first,
+    unauthorized: () => 'Please login to continue.',
+    notFound: () => 'Item not found.',
+    unknown: (error) => 'An unexpected error occurred.',
+  );
+}
+```
+
+### Logging Levels
+
+```dart
+// ✅ Use appropriate log levels
+logger.debug('Cache hit for attendance data'); // Development only
+logger.info('User logged in: userId=${user.id}'); // Important events
+logger.warning('API rate limit approaching'); // Potential issues
+logger.error('Failed to sync attendance', error: e, stackTrace: st); // Errors
+logger.fatal('Database corruption detected'); // Critical failures
+```
+
+### Error Context
+
+```dart
+// ✅ Include context in errors
+try {
+  await repository.submitLeave(leaveRequest);
+} catch (e, st) {
+  logger.error(
+    'Failed to submit leave request',
+    error: e,
+    stackTrace: st,
+    context: {
+      'userId': user.id,
+      'leaveType': leaveRequest.type,
+      'startDate': leaveRequest.startDate,
+    },
+  );
+  rethrow;
+}
+```
+
+## Error Handling Patterns
+
+### Repository Layer
+
+```dart
+@override
+Future<Result<Attendance>> submitAttendance(AttendanceRequest request) async {
+  try {
+    final response = await _remoteDataSource.submit(request);
+    return Result.success(response);
+  } on DioException catch (e) {
+    logger.error('Submit attendance failed', error: e);
+    return Result.failure(_mapDioError(e));
+  } catch (e, st) {
+    logger.error('Unexpected error', error: e, stackTrace: st);
+    return Result.failure(Failure.unknown(e.toString()));
+  }
+}
+```
+
+### Controller Layer
+
+```dart
+Future<void> submit() async {
+  final prev = state;
+  state = const AsyncLoading();
+  
+  final result = await ref.read(featureRepositoryProvider).submit(request);
+  
+  result.when(
+    success: (data) => ref.invalidateSelf(),
+    failure: (failure) {
+      logger.warning('Submit failed', context: {'failure': failure});
+      state = prev;
+      throw Exception(failure.message);
+    },
+  );
+}
+```
+
+### UI Layer
+
+```dart
+ref.listen(controllerProvider, (prev, next) {
+  next.whenOrNull(
+    error: (error, _) {
+      final message = error is Failure 
+        ? getErrorMessage(error)
+        : 'An unexpected error occurred';
+      OneSnackbar.error(context, message);
+    },
+  );
+});
+```
+
+## Logging Best Practices
+
+1. **Never log sensitive data** (passwords, tokens, PII)
+2. **Include context** (userId, action, timestamp)
+3. **Use structured logging** (key-value pairs)
+4. **Log at appropriate levels** (debug/info/warning/error/fatal)
+5. **Include stack traces for errors**
+
+## Steering Files
+
+- `failure_to_ui.md` - Complete failure-to-message mapping guide
+- `logging_levels.md` - When to use each log level
+
+## Templates
+
+- `failure_message_mapper` - Failure to UI message mapper template
+

package/Ai Agent Workflow/skills/error-ux-observability/references/failure_to_ui.md

@@ -0,0 +1,12 @@
+# Failure -> UI mapping (OneUp HR)
+
+## Rules
+- Do not show raw exceptions to users.
+- Always provide an action when possible.
+
+## Mapping table (example)
+- network -> "You're offline. Please check your internet." (Retry)
+- auth -> "Session expired. Please sign in again." (Go to login)
+- validation -> show field errors (Fix inputs)
+- server -> "Something went wrong on our side." (Retry)
+- cache -> "Saved data is unavailable." (Retry/Refresh)

package/Ai Agent Workflow/skills/error-ux-observability/references/logging_levels.md

@@ -0,0 +1,8 @@
+# Logging levels
+
+- Debug builds: detailed logs allowed but still redact secrets
+- Release builds: only essential logs + correlation ids
+- Never log: tokens, passwords, OTPs, precise location unless required and approved
+
+Prefer structured logs:
+- method, path, status, duration, requestId

package/Ai Agent Workflow/skills/error-ux-observability/steering/failure_to_ui.md

@@ -0,0 +1,12 @@
+# Failure -> UI mapping (OneUp HR)
+
+## Rules
+- Do not show raw exceptions to users.
+- Always provide an action when possible.
+
+## Mapping table (example)
+- network -> "You're offline. Please check your internet." (Retry)
+- auth -> "Session expired. Please sign in again." (Go to login)
+- validation -> show field errors (Fix inputs)
+- server -> "Something went wrong on our side." (Retry)
+- cache -> "Saved data is unavailable." (Retry/Refresh)

package/Ai Agent Workflow/skills/error-ux-observability/steering/logging_levels.md

@@ -0,0 +1,8 @@
+# Logging levels
+
+- Debug builds: detailed logs allowed but still redact secrets
+- Release builds: only essential logs + correlation ids
+- Never log: tokens, passwords, OTPs, precise location unless required and approved
+
+Prefer structured logs:
+- method, path, status, duration, requestId

package/Ai Agent Workflow/skills/error-ux-observability/templates/failure_message_mapper.md

@@ -0,0 +1,16 @@
+```
+// templates/failure_message_mapper.tmpl
+//
+// Map Failure to safe user message.
+
+String userMessageFromFailure(Failure f) {
+  return f.when(
+    server: (m) => m ?? 'Something went wrong. Please try again.',
+    network: (m) => m ?? 'No internet connection. Please check and retry.',
+    cache: (m) => m ?? 'Saved data is unavailable. Please refresh.',
+    auth: (m) => m ?? 'Session expired. Please sign in again.',
+    validation: (m) => m ?? 'Please check your input and try again.',
+    unknown: (m) => m ?? 'Unexpected error. Please try again.',
+  );
+}
+```

package/Ai Agent Workflow/skills/fastapi-expert/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: fastapi-expert
+description: Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke for async SQLAlchemy, JWT authentication, WebSockets, OpenAPI documentation.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: backend
+  triggers: FastAPI, Pydantic, async Python, Python API, REST API Python, SQLAlchemy async, JWT authentication, OpenAPI, Swagger Python
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, django-expert, test-master
+---
+
+# FastAPI Expert
+
+Senior FastAPI specialist with deep expertise in async Python, Pydantic V2, and production-grade API development.
+
+## Role Definition
+
+You are a senior Python engineer with 10+ years of API development experience. You specialize in FastAPI with Pydantic V2, async SQLAlchemy, and modern Python 3.11+ patterns. You build scalable, type-safe APIs with automatic documentation.
+
+## When to Use This Skill
+
+- Building REST APIs with FastAPI
+- Implementing Pydantic V2 validation schemas
+- Setting up async database operations
+- Implementing JWT authentication/authorization
+- Creating WebSocket endpoints
+- Optimizing API performance
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify endpoints, data models, auth needs
+2. **Design schemas** - Create Pydantic V2 models for validation
+3. **Implement** - Write async endpoints with proper dependency injection
+4. **Secure** - Add authentication, authorization, rate limiting
+5. **Test** - Write async tests with pytest and httpx
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
+| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
+| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
+| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
+| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
+| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+
+## Constraints
+
+### MUST DO
+- Use type hints everywhere (FastAPI requires them)
+- Use Pydantic V2 syntax (`field_validator`, `model_validator`, `model_config`)
+- Use `Annotated` pattern for dependency injection
+- Use async/await for all I/O operations
+- Use `X | None` instead of `Optional[X]`
+- Return proper HTTP status codes
+- Document endpoints (auto-generated OpenAPI)
+
+### MUST NOT DO
+- Use synchronous database operations
+- Skip Pydantic validation
+- Store passwords in plain text
+- Expose sensitive data in responses
+- Use Pydantic V1 syntax (`@validator`, `class Config`)
+- Mix sync and async code improperly
+- Hardcode configuration values
+
+## Output Templates
+
+When implementing FastAPI features, provide:
+1. Schema file (Pydantic models)
+2. Endpoint file (router with endpoints)
+3. CRUD operations if database involved
+4. Brief explanation of key decisions
+
+## Knowledge Reference
+
+FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger

package/Ai Agent Workflow/skills/fastapi-expert/references/async-sqlalchemy.md

@@ -0,0 +1,146 @@
+# Async SQLAlchemy
+
+## Engine & Session Setup
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    pool_pre_ping=True,
+)
+
+async_session = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+class Base(DeclarativeBase):
+    pass
+```
+
+## Model Definition
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy import String, ForeignKey, DateTime, func
+from datetime import datetime
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    username: Mapped[str] = mapped_column(String(50), unique=True)
+    hashed_password: Mapped[str] = mapped_column(String(255))
+    is_active: Mapped[bool] = mapped_column(default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+
+    # Relationships
+    posts: Mapped[list["Post"]] = relationship(back_populates="author", lazy="selectin")
+
+class Post(Base):
+    __tablename__ = "posts"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str] = mapped_column(String(200))
+    content: Mapped[str]
+    author_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+
+    author: Mapped["User"] = relationship(back_populates="posts")
+```
+
+## Database Dependency
+
+```python
+from typing import AsyncGenerator
+from fastapi import Depends
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+# Type alias for injection
+DB = Annotated[AsyncSession, Depends(get_db)]
+```
+
+## CRUD Operations
+
+```python
+from sqlalchemy import select, update, delete
+from sqlalchemy.orm import selectinload
+
+async def get_user(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(select(User).where(User.id == user_id))
+    return result.scalar_one_or_none()
+
+async def get_user_with_posts(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(
+        select(User)
+        .options(selectinload(User.posts))
+        .where(User.id == user_id)
+    )
+    return result.scalar_one_or_none()
+
+async def get_users(db: AsyncSession, skip: int = 0, limit: int = 100) -> list[User]:
+    result = await db.execute(select(User).offset(skip).limit(limit))
+    return list(result.scalars().all())
+
+async def create_user(db: AsyncSession, user_in: UserCreate) -> User:
+    user = User(**user_in.model_dump())
+    db.add(user)
+    await db.flush()
+    await db.refresh(user)
+    return user
+
+async def update_user(db: AsyncSession, user_id: int, user_in: UserUpdate) -> User:
+    await db.execute(
+        update(User)
+        .where(User.id == user_id)
+        .values(**user_in.model_dump(exclude_unset=True))
+    )
+    return await get_user(db, user_id)
+
+async def delete_user(db: AsyncSession, user_id: int) -> bool:
+    result = await db.execute(delete(User).where(User.id == user_id))
+    return result.rowcount > 0
+```
+
+## Lifespan Handler
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    # Shutdown
+    await engine.dispose()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## Quick Reference
+
+| Operation | Method |
+|-----------|--------|
+| Select one | `result.scalar_one_or_none()` |
+| Select many | `result.scalars().all()` |
+| Eager load | `.options(selectinload(...))` |
+| Create | `db.add(obj)` + `await db.flush()` |
+| Update | `update(Model).where(...).values(...)` |
+| Delete | `delete(Model).where(...)` |
+| Commit | `await db.commit()` |
+| Rollback | `await db.rollback()` |

package/Ai Agent Workflow/skills/fastapi-expert/references/authentication.md

@@ -0,0 +1,159 @@
+# Authentication
+
+## OAuth2 Password Flow
+
+```python
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from typing import Annotated
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/token")
+
+@router.post("/token")
+async def login(
+    db: DB,
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+) -> Token:
+    user = await authenticate_user(db, form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status.HTTP_401_UNAUTHORIZED,
+            "Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return Token(
+        access_token=create_access_token(sub=str(user.id)),
+        token_type="bearer",
+    )
+```
+
+## JWT Token Creation
+
+```python
+from datetime import datetime, timedelta, UTC
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def create_access_token(
+    sub: str,
+    expires_delta: timedelta | None = None,
+) -> str:
+    expire = datetime.now(UTC) + (expires_delta or timedelta(minutes=15))
+    return jwt.encode(
+        {"sub": sub, "exp": expire, "type": "access"},
+        settings.SECRET_KEY,
+        algorithm="HS256",
+    )
+
+def create_refresh_token(sub: str) -> str:
+    expire = datetime.now(UTC) + timedelta(days=7)
+    return jwt.encode(
+        {"sub": sub, "exp": expire, "type": "refresh"},
+        settings.SECRET_KEY,
+        algorithm="HS256",
+    )
+```
+
+## Get Current User
+
+```python
+async def get_current_user(
+    db: DB,
+    token: Annotated[str, Depends(oauth2_scheme)],
+) -> User:
+    credentials_exception = HTTPException(
+        status.HTTP_401_UNAUTHORIZED,
+        "Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
+        user_id = int(payload.get("sub"))
+        if payload.get("type") != "access":
+            raise credentials_exception
+    except (JWTError, ValueError, TypeError):
+        raise credentials_exception
+
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise credentials_exception
+    return user
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+```
+
+## Role-Based Access
+
+```python
+from enum import Enum
+
+class UserRole(str, Enum):
+    USER = "user"
+    ADMIN = "admin"
+    MODERATOR = "moderator"
+
+def require_roles(*roles: UserRole):
+    async def role_checker(current_user: CurrentUser) -> User:
+        if current_user.role not in roles:
+            raise HTTPException(
+                status.HTTP_403_FORBIDDEN,
+                f"Required roles: {[r.value for r in roles]}",
+            )
+        return current_user
+    return role_checker
+
+# Usage
+@router.delete("/{id}")
+async def delete_user(
+    user_id: int,
+    admin: Annotated[User, Depends(require_roles(UserRole.ADMIN))],
+) -> None:
+    ...
+```
+
+## Refresh Token
+
+```python
+@router.post("/refresh", response_model=Token)
+async def refresh_token(
+    db: DB,
+    refresh_token: str = Body(..., embed=True),
+) -> Token:
+    try:
+        payload = jwt.decode(refresh_token, settings.SECRET_KEY, algorithms=["HS256"])
+        if payload.get("type") != "refresh":
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid token type")
+        user_id = int(payload.get("sub"))
+    except (JWTError, ValueError):
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid refresh token")
+
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "User not found")
+
+    return Token(
+        access_token=create_access_token(sub=str(user.id)),
+        token_type="bearer",
+    )
+```
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| `OAuth2PasswordBearer` | Extract token from header |
+| `OAuth2PasswordRequestForm` | Login form data |
+| `jwt.encode()` | Create JWT |
+| `jwt.decode()` | Verify JWT |
+| `pwd_context.hash()` | Hash password |
+| `pwd_context.verify()` | Check password |
+| `Depends(get_current_user)` | Require auth |
+| `require_roles()` | Role-based access |