@1aboveio/skills 0.10.0

package/skills/backend/app-debug/references/common-errors.md

@@ -0,0 +1,128 @@
+# Common Runtime Errors — 1Above Stack
+
+Known error patterns for `a1-*` services on Cloud Run. Format: symptom → likely cause → fix.
+
+---
+
+## Database Errors
+
+### `FATAL: password authentication failed for user "..."`
+- **Cause:** Secret `database-url-a1-{env}` is pinned to an old version after DB password rotation, or a new secret version was added but the service wasn't redeployed.
+- **Fix:** Add new secret version with updated DB URL, then redeploy the service. Verify the revision picks up `latest` version.
+
+### `sqlalchemy.exc.OperationalError: could not connect to server: No such file or directory`
+- **Cause:** Cloud SQL Unix socket not mounted. `CLOUD_SQL_INSTANCE` env var is missing, wrong format, or Cloud SQL connection not added to the service.
+- **Fix:** Redeploy with `--add-cloudsql-instances cosmic-heaven-479306-v5:us-central1:ai-dev` and ensure `CLOUD_SQL_INSTANCE=cosmic-heaven-479306-v5:us-central1:ai-dev` is set.
+
+### `sqlalchemy.exc.OperationalError: could not connect to server: Connection refused`
+- **Cause:** TCP connection attempted instead of Unix socket, or Cloud SQL proxy not reachable. Often occurs when DB URL uses `localhost` or `127.0.0.1` instead of the socket path.
+- **Fix:** DB URL for Cloud SQL on Cloud Run must use the Unix socket format: `postgresql+asyncpg://user:pass@/dbname?host=/cloudsql/PROJECT:REGION:INSTANCE`
+
+### `tortoise.exceptions.ConfigurationError: DB URL not defined or wrong format`
+- **Cause:** Tortoise ORM initialized before the `DATABASE_URL` env var is resolved, or URL scheme is incompatible (`postgresql://` vs `postgres://` vs `asyncpg://`).
+- **Fix:** Ensure Tortoise uses `asyncpg` scheme (`postgresql+asyncpg://` or `asyncpg://`). Confirm `DATABASE_URL` is present in the revision env vars. Check `Tortoise.init()` is awaited inside the app lifespan, not at module import time.
+
+### `asyncpg.exceptions.TooManyConnectionsError`
+- **Cause:** Connection pool exhausted. Multiple cold starts creating new pools simultaneously, or pool size too large for Cloud SQL's max connection limit.
+- **Fix:** Set `maxsize` on the connection pool (e.g. `maxsize=5`). Consider Cloud SQL connection pooling via PgBouncer or reduce min-instances if connection churn is the issue.
+
+---
+
+## Secret Manager Errors
+
+### `google.api_core.exceptions.PermissionDenied: Secret Manager API ... caller does not have permission`
+- **Cause:** Cloud Run service account missing `roles/secretmanager.secretAccessor` on the project or specific secret.
+- **Fix:**
+  ```bash
+  gcloud projects add-iam-policy-binding cosmic-heaven-479306-v5 \
+    --member="serviceAccount:SA_EMAIL" \
+    --role="roles/secretmanager.secretAccessor"
+  ```
+
+### `google.api_core.exceptions.NotFound: Secret ... not found`
+- **Cause:** Secret name typo, wrong env suffix (`-dev` vs `-prod`), or secret was deleted.
+- **Fix:** List secrets to confirm correct name: `gcloud secrets list --project cosmic-heaven-479306-v5 --filter="name~a1"`. Check env var that specifies the secret name.
+
+### `Secret Manager API has not been used in project ... before`
+- **Cause:** Secret Manager API not enabled on the project (unlikely for existing project; more likely a wrong project ID).
+- **Fix:** Verify `--project cosmic-heaven-479306-v5` is correct. Enable if needed: `gcloud services enable secretmanager.googleapis.com --project cosmic-heaven-479306-v5`
+
+---
+
+## Container / Config Errors
+
+### `Container failed to start. Failed to start and then listen on the port defined by the PORT environment variable.`
+- **Cause (most common):** Application crash on startup — missing required env var, failed DB connection during init, or unhandled import error.
+- **Cause (port mismatch):** App binding to hardcoded port instead of reading `$PORT`.
+- **Fix:** Check startup logs immediately after this message. If port: ensure FastAPI runs on port `8000`, Next.js portal on `3000`, admin on `3001`. Confirm app reads `PORT` env var or matches Cloud Run's configured port.
+
+### `Revision failed, container listening on wrong port`
+- **Cause:** Cloud Run sends traffic to port 8000 (or configured port) but container is binding to a different port.
+- **Fix:** Update service port: `gcloud run services update SERVICE --port 8000 --region us-central1 --project cosmic-heaven-479306-v5`. Or fix the app to bind to `int(os.environ.get("PORT", 8000))`.
+
+### `Error: Cannot find module '...'` or `ModuleNotFoundError`
+- **Cause:** Dependency not installed in Docker image, or wrong base image used.
+- **Fix:** Rebuild and push a new image. Check `requirements.txt` / `pyproject.toml` / `package.json` includes the missing dep. This is a deploy-time issue — route to Cory or Suzzy + Watt.
+
+---
+
+## Resource / Performance Errors
+
+### `DEADLINE_EXCEEDED` on first request after idle
+- **Cause:** `min-instances=0` (default) causes cold start. Heavy initialization (DB connection pool, model loading, etc.) exceeds Cloud Run's request timeout.
+- **Fix (fast):** Set `min-instances=1` to keep one warm instance:
+  ```bash
+  gcloud run services update SERVICE-ENV \
+    --min-instances 1 \
+    --region us-central1 \
+    --project cosmic-heaven-479306-v5
+  ```
+- **Fix (proper):** Reduce startup work — lazy-load heavy resources, move initialization out of module scope.
+
+### Exit code `137` / `OOMKilled`
+- **Cause:** Container exceeded memory limit (default 256Mi on Cloud Run).
+- **Fix:** Increase memory: `gcloud run services update SERVICE-ENV --memory 1Gi --region us-central1 --project cosmic-heaven-479306-v5`. If memory keeps growing, investigate for memory leaks.
+
+### `Request timeout` / `upstream request timeout`
+- **Cause:** Request processing exceeds Cloud Run's request timeout (default 300s). Common in heavy data processing or slow DB queries.
+- **Fix:** Increase timeout: `gcloud run services update SERVICE-ENV --timeout 600 --region us-central1 --project cosmic-heaven-479306-v5`. Or break long work into async tasks.
+
+---
+
+## Next.js / Frontend Errors
+
+### `Error: Dynamic server usage: headers`
+- **Cause:** Using `headers()`, `cookies()`, or other dynamic APIs inside a component or route that Next.js attempted to statically render at build time.
+- **Fix:** Add `export const dynamic = 'force-dynamic'` at the top of the page/route file. Or move the dynamic call inside a Server Component that is not statically cached.
+
+### `Hydration failed because the initial UI does not match what was rendered on the server`
+- **Cause:** Server-rendered HTML differs from what React renders on the client. Common sources: `Date()`, `Math.random()`, `typeof window`, `localStorage` in render logic.
+- **Fix:** Wrap client-only code in `useEffect`. Use `suppressHydrationWarning` only as last resort. For timestamps: format server-side and pass as prop, or use a stable seed.
+
+### `Error: ECONNREFUSED 127.0.0.1:PORT` (Next.js Server Component or Server Action)
+- **Cause:** Server Component or Server Action making an HTTP call to an internal service using `localhost` or a hardcoded URL that isn't reachable from the Next.js container.
+- **Fix:** Use the Cloud Run service URL (not localhost). Set the backend URL via env var (e.g. `BACKEND_URL=https://a1-engine-dev-xxx-uc.a.run.app`). Confirm the env var is present in the revision.
+
+### `TypeError: Failed to fetch` / `fetch failed` in Server Action
+- **Cause:** Network call from Server Action failing. Could be DNS, wrong URL, or the target service is down.
+- **Fix:** Log the full URL being fetched. Check target service is running: `gcloud run services describe TARGET --region us-central1 --project cosmic-heaven-479306-v5`. Confirm VPC/egress config if services are VPC-internal.
+
+### `Error: cookies() was called outside a request scope`
+- **Cause:** `cookies()` called at module top level or in a static context.
+- **Fix:** Move the call inside the request handler function body, not at module scope.
+
+---
+
+## FastAPI Errors
+
+### HTTP 422 Unprocessable Entity
+- **Cause:** Request body or query params don't match the Pydantic schema. Often a client bug, but can also be a schema mismatch after an API change.
+- **Fix:** Check the response body for `detail` — it includes the exact field and validation error. Confirm client is sending the correct payload shape.
+
+### HTTP 500 with `RuntimeError: no running event loop`
+- **Cause:** Async code called from a sync context, or Tortoise ORM used before `Tortoise.init()` is awaited.
+- **Fix:** Ensure all DB operations happen inside `async def` functions. Confirm the lifespan handler initializes Tortoise before the app accepts requests.
+
+### `fastapi.exceptions.HTTPException: 401 / 403`
+- **Cause:** Auth middleware rejecting requests. JWT expired, wrong secret used to verify, or `auth-secret` mismatch between portal and engine.
+- **Fix:** Check `auth-secret` secret is the same version across both services. Verify token expiry and issuer config.

package/skills/backend/python-backend/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/backend/python-backend/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: python-backend
+description: Python backend conventions — architecture, design decisions, and implementation patterns. Read when designing or reviewing features involving FastAPI, Tortoise-ORM, Pydantic Settings, loguru, or uv dependency management.
+---
+
+# Python Backend Conventions
+
+**Stack:** Python 3.12 | FastAPI | Tortoise-ORM | Aerich | Pydantic v2 | loguru | uv | pytest
+
+## Critical Rule
+
+Use **uv** for all environment, dependency, and tool commands. No raw `pip`, `poetry`, `pipenv`, or manual `venv`.
+
+---
+
+## Tooling & Commands
+
+### Dependencies
+
+```bash
+# Runtime deps
+uv add fastapi tortoise-orm aerich pydantic pydantic-settings loguru
+
+# Dev deps
+uv add --dev pytest ruff mypy
+```
+
+### Running Commands
+
+```bash
+uv run uvicorn app.main:app --reload  # Start app
+uv run pytest                          # Run tests
+uv run ruff check .                    # Lint
+uv run mypy app                        # Type check
+uv run aerich migrate                  # Run migrations
+uv run aerich upgrade                  # Apply migrations
+```
+
+---
+
+## Architecture
+
+```
+app/
+├── api/          # API Layer - routes, endpoints
+├── services/     # Service Layer - business logic
+├── dal/          # Data Access Layer - Tortoise queries
+├── models/       # Tortoise ORM models
+├── schemas/      # Pydantic schemas
+└── core/         # Infrastructure
+    ├── config.py     # Pydantic Settings
+    ├── logging.py    # loguru configuration
+    ├── tortoise.py   # DB init/close
+    ├── errors.py     # Domain exceptions
+    └── security.py   # Auth utilities
+```
+
+### Export Rule
+
+All modules in `core`, `dal`, `services`, `schemas`, `api` must define `__all__`.
+All packages (`__init__.py`) re-export the public API using `__all__`.
+
+---
+
+## Config Management
+
+Location: `app/core/config.py`
+
+```python
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import AnyUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["Settings", "get_settings"]
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    ENV: Literal["local", "dev", "staging", "prod"] = "local"
+    DATABASE_URL: AnyUrl
+    LOG_LEVEL: str = "INFO"
+    APP_NAME: str = "Backend"
+    API_V1_PREFIX: str = "/api/v1"
+    JWT_SECRET_KEY: str
+    JWT_ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Global, cached settings accessor."""
+    return Settings()
+```
+
+**Rule:** Never create new `Settings()` manually; always use `get_settings()`.
+
+---
+
+## Logging
+
+Location: `app/core/logging.py`
+
+```python
+from __future__ import annotations
+
+import sys
+from loguru import logger
+
+from app.core.config import get_settings
+
+__all__ = ["logger", "configure_logging"]
+
+
+def configure_logging() -> None:
+    """Configure global loguru logger. Call once at app startup."""
+    settings = get_settings()
+
+    logger.remove()
+    logger.add(
+        sys.stderr,
+        level=settings.LOG_LEVEL,
+        enqueue=True,
+        backtrace=False,
+        diagnose=False,
+        serialize=settings.ENV in ("staging", "prod"),
+    )
+```
+
+**Rule:** Import `logger` from `app.core.logging` (not `loguru` directly).
+
+---
+
+## Tortoise-ORM & Aerich
+
+Location: `app/core/tortoise.py`
+
+```python
+from __future__ import annotations
+
+from tortoise import Tortoise
+
+from app.core.config import get_settings
+
+__all__ = ["TORTOISE_ORM", "init_db", "close_db"]
+
+settings = get_settings()
+
+TORTOISE_ORM = {
+    "connections": {
+        "default": str(settings.DATABASE_URL),
+    },
+    "apps": {
+        "models": {
+            "models": ["app.models.user", "app.models.order", "aerich.models"],
+            "default_connection": "default",
+        },
+    },
+}
+
+
+async def init_db() -> None:
+    await Tortoise.init(config=TORTOISE_ORM)
+
+
+async def close_db() -> None:
+    await Tortoise.close_connections()
+```
+
+---
+
+## Data Access Layer (DAL)
+
+Location: `app/dal/**`
+
+- Functional style, Tortoise only
+- No FastAPI, no Pydantic, no auth, no logging
+
+```python
+# app/dal/order_dal.py
+from __future__ import annotations
+
+from tortoise.transactions import in_transaction
+from app.models.order import Order, OrderItem
+
+__all__ = ["get_user_orders_with_items", "create_order_with_items"]
+
+
+async def get_user_orders_with_items(
+    user_id: int,
+    limit: int = 20,
+    offset: int = 0,
+) -> list[Order]:
+    return await (
+        Order
+        .filter(user_id=user_id)
+        .prefetch_related("items")
+        .order_by("-created_at")
+        .offset(offset)
+        .limit(limit)
+    )
+
+
+async def create_order_with_items(
+    user_id: int,
+    items: list[dict],
+) -> Order:
+    async with in_transaction() as conn:
+        order = await Order.using_db(conn).create(user_id=user_id)
+        for item in items:
+            await OrderItem.using_db(conn).create(order=order, **item)
+        return order
+```
+
+### Complexity Rule
+
+- **Simple / one-off** queries: Direct Tortoise in services
+- **Complex / reused / transactional**: DAL functions
+
+---
+
+## Service Layer
+
+Location: `app/services/**`
+
+- Center of business logic
+- Uses DAL for complex queries
+- Raises domain exceptions from `app/core/errors.py`
+- Uses `logger` for business-level events
+
+```python
+# app/services/order_service.py
+from __future__ import annotations
+
+from app.schemas.order import OrderCreate, OrderRead
+from app.models.order import Order
+from app.dal import get_user_orders_with_items, create_order_with_items
+from app.core.errors import OrderNotFoundError, PermissionDeniedError
+from app.core.logging import logger
+
+__all__ = ["list_my_orders", "get_order_detail", "create_order"]
+
+
+async def list_my_orders(
+    user_id: int,
+    limit: int = 20,
+    offset: int = 0,
+) -> list[OrderRead]:
+    orders = await get_user_orders_with_items(user_id, limit, offset)
+    logger.info("Listed orders", user_id=user_id, count=len(orders))
+    return [OrderRead.model_validate(o) for o in orders]
+```
+
+---
+
+## API Layer
+
+Location: `app/api/**`
+
+- Uses `APIRouter`, `Depends`, `HTTPException`, `status`
+- Converts domain exceptions to HTTP status codes
+
+```python
+# app/api/v1/orders.py
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from app.schemas.order import OrderCreate, OrderRead
+from app.services import list_my_orders, create_order, get_order_detail
+from app.core.errors import OrderNotFoundError, PermissionDeniedError
+from app.api.deps import get_current_user
+from app.core.logging import logger
+
+__all__ = ["router"]
+
+router = APIRouter(prefix="/orders", tags=["orders"])
+
+
+@router.get("/", response_model=list[OrderRead])
+async def list_orders(current_user=Depends(get_current_user)) -> list[OrderRead]:
+    return await list_my_orders(user_id=current_user.id)
+
+
+@router.get("/{order_id}", response_model=OrderRead)
+async def get_order(
+    order_id: int,
+    current_user=Depends(get_current_user),
+) -> OrderRead:
+    try:
+        return await get_order_detail(current_user.id, order_id)
+    except OrderNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except PermissionDeniedError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+```
+
+---
+
+## Do / Don't
+
+### Do
+
+- Use **uv** for env, deps, and all Python tooling
+- Use **Pydantic Settings** with `get_settings()` for config
+- Use **loguru** via `app.core.logging.logger`
+- Keep API -> Service -> DAL separation
+- Use DAL for complex/reused DB logic
+- Use `__all__` and package `__init__.py` for explicit exports
+- Use pytest for all tests
+
+### Don't
+
+- Don't use raw `pip`, `venv`, or `pytest` outside `uv run`
+- Don't import `loguru.logger` directly
+- Don't instantiate `Settings()` directly
+- Don't call Tortoise from API routes
+- Don't let DAL log or handle business logic
+- Don't raise `HTTPException` outside the API layer

package/skills/cicd-pipeline/cloud-build/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO