gaia-framework 1.57.0 → 1.57.2

package/_gaia/dev/knowledge/python/python-conventions.md

@@ -1,170 +0,0 @@
----
-name: Python Conventions and Standards
-stack: python
-version: "1.0"
-focus: [python]
----
-
-# Python Conventions and Standards
-
-## Principle
-
-Follow PEP 8 for style, use type hints throughout, manage dependencies with virtual environments and `pyproject.toml`, and structure projects with clear module boundaries. Use `ruff` for linting and formatting, `mypy` for type checking, and `pytest` for testing.
-
-## Rationale
-
-PEP 8 is the universal Python style standard; deviating from it creates friction for contributors and tooling. Type hints enable IDE autocompletion, catch bugs before runtime, and serve as documentation. `pyproject.toml` (PEP 621) consolidates project metadata, dependencies, and tool configuration in a single file, replacing the fragmented `setup.py` + `setup.cfg` + `requirements.txt` approach. Virtual environments isolate dependencies and prevent system-wide conflicts.
-
-## Pattern Examples
-
-### Pattern 1: Project Structure and pyproject.toml
-
-```
-my-project/
-  src/
-    my_project/
-      __init__.py
-      models/
-        __init__.py
-        user.py
-      services/
-        __init__.py
-        user_service.py
-      api/
-        __init__.py
-        routes.py
-      core/
-        __init__.py
-        config.py
-        exceptions.py
-  tests/
-    __init__.py
-    conftest.py
-    test_user_service.py
-  pyproject.toml
-```
-
-```toml
-# pyproject.toml
-[project]
-name = "my-project"
-version = "1.0.0"
-requires-python = ">=3.12"
-dependencies = [
-    "fastapi>=0.110",
-    "sqlalchemy>=2.0",
-    "pydantic>=2.0",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=8.0",
-    "pytest-asyncio>=0.23",
-    "ruff>=0.4",
-    "mypy>=1.10",
-]
-
-[tool.ruff]
-target-version = "py312"
-line-length = 88
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
-
-[tool.mypy]
-strict = true
-python_version = "3.12"
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-asyncio_mode = "auto"
-```
-
-### Pattern 2: Type Hints and Protocols
-
-```python
-from typing import Protocol, TypeVar, Generic
-from datetime import datetime
-
-
-# Protocol for structural typing (duck typing with type safety)
-class Repository(Protocol[T]):
-    async def get(self, id: int) -> T | None: ...
-    async def save(self, entity: T) -> T: ...
-    async def delete(self, id: int) -> bool: ...
-
-
-T = TypeVar("T")
-
-
-class BaseService(Generic[T]):
-    """Generic service with typed repository dependency."""
-
-    def __init__(self, repo: Repository[T]) -> None:
-        self._repo = repo
-
-    async def get_or_raise(self, id: int) -> T:
-        entity = await self._repo.get(id)
-        if entity is None:
-            raise EntityNotFoundError(f"Entity {id} not found")
-        return entity
-
-
-# Concrete implementation
-class UserService(BaseService[User]):
-    async def create(self, data: CreateUserRequest) -> User:
-        user = User(
-            email=data.email,
-            name=data.name,
-            created_at=datetime.now(),
-        )
-        return await self._repo.save(user)
-```
-
-### Pattern 3: Testing with pytest Fixtures
-
-```python
-import pytest
-from unittest.mock import AsyncMock
-
-
-@pytest.fixture
-def mock_user_repo() -> AsyncMock:
-    repo = AsyncMock(spec=UserRepository)
-    repo.get.return_value = User(id=1, email="test@example.com", name="Test")
-    return repo
-
-
-@pytest.fixture
-def user_service(mock_user_repo: AsyncMock) -> UserService:
-    return UserService(repo=mock_user_repo)
-
-
-async def test_get_user_returns_user(user_service: UserService) -> None:
-    user = await user_service.get_or_raise(1)
-    assert user.email == "test@example.com"
-
-
-async def test_get_user_raises_when_not_found(
-    user_service: UserService,
-    mock_user_repo: AsyncMock,
-) -> None:
-    mock_user_repo.get.return_value = None
-    with pytest.raises(EntityNotFoundError):
-        await user_service.get_or_raise(999)
-```
-
-## Anti-Patterns
-
-- **No type hints**: Omitting type annotations loses IDE support and prevents `mypy` from catching bugs. Add hints to all function signatures.
-- **`requirements.txt` without pinning**: `requests` instead of `requests==2.31.0` leads to unreproducible builds. Pin all dependencies.
-- **Global mutable state**: Module-level mutable variables (e.g., `db = None`) create testing nightmares. Use dependency injection.
-- **Wildcard imports**: `from module import *` pollutes the namespace and hides where symbols come from. Import explicitly.
-- **No virtual environment**: Installing packages globally causes version conflicts. Always use `venv`, `uv`, or `conda`.
-
-## Integration Points
-
-- **Django**: Django projects follow these conventions with Django-specific additions; see `django-patterns.md`.
-- **FastAPI**: FastAPI requires type hints for auto-documentation; see `fastapi-patterns.md`.
-- **Data Pipelines**: Pipeline scripts follow the same structure and testing patterns; see `data-pipelines.md`.
-- **CI/CD**: Run `ruff check`, `mypy`, and `pytest` in CI. Use `pre-commit` hooks locally.

package/_gaia/dev/knowledge/typescript/express-patterns.md

@@ -1,188 +0,0 @@
----
-name: Express.js Application Patterns
-stack: typescript
-version: "1.0"
-focus: [express]
----
-
-# Express.js Application Patterns
-
-## Principle
-
-Structure Express applications with a clear middleware chain: parsing, authentication, route-specific logic, and centralized error handling. Use typed request/response objects, validation middleware for input sanitization, and async error wrappers to prevent unhandled promise rejections. Organize routes into modular routers by domain.
-
-## Rationale
-
-Express processes requests through a middleware chain in the order middleware is registered. This linear flow makes it easy to reason about request processing but requires discipline to avoid middleware order bugs. TypeScript types on request/response objects catch shape mismatches at compile time. Centralized error handling via a four-argument middleware ensures consistent error responses and prevents leaked stack traces in production.
-
-## Pattern Examples
-
-### Pattern 1: Typed Middleware Chain
-
-```typescript
-import express, { Request, Response, NextFunction } from 'express';
-import cors from 'cors';
-import helmet from 'helmet';
-
-// Extend Express Request with typed properties
-interface AuthenticatedRequest extends Request {
-  user: { id: string; role: string };
-}
-
-// Auth middleware — adds typed user to request
-function authenticate(req: Request, res: Response, next: NextFunction): void {
-  const token = req.headers.authorization?.replace('Bearer ', '');
-  if (!token) {
-    res.status(401).json({ error: 'Authentication required' });
-    return;
-  }
-  try {
-    const payload = verifyToken(token);
-    (req as AuthenticatedRequest).user = payload;
-    next();
-  } catch {
-    res.status(401).json({ error: 'Invalid token' });
-  }
-}
-
-// Role guard middleware factory
-function requireRole(...roles: string[]) {
-  return (req: Request, res: Response, next: NextFunction): void => {
-    const user = (req as AuthenticatedRequest).user;
-    if (!roles.includes(user.role)) {
-      res.status(403).json({ error: 'Insufficient permissions' });
-      return;
-    }
-    next();
-  };
-}
-
-const app = express();
-app.use(helmet());
-app.use(cors());
-app.use(express.json({ limit: '10mb' }));
-app.use('/api', authenticate);  // All /api routes require auth
-```
-
-### Pattern 2: Modular Router with Validation
-
-```typescript
-import { Router } from 'express';
-import { z } from 'zod';
-
-const router = Router();
-
-// Validation middleware factory
-function validate(schema: z.ZodSchema) {
-  return (req: Request, res: Response, next: NextFunction): void => {
-    const result = schema.safeParse(req.body);
-    if (!result.success) {
-      res.status(422).json({
-        error: 'Validation failed',
-        details: result.error.flatten().fieldErrors,
-      });
-      return;
-    }
-    req.body = result.data;
-    next();
-  };
-}
-
-const CreateUserSchema = z.object({
-  name: z.string().min(1).max(100),
-  email: z.string().email(),
-});
-
-// Async handler wrapper — catches rejected promises
-function asyncHandler(
-  fn: (req: Request, res: Response, next: NextFunction) => Promise<void>
-) {
-  return (req: Request, res: Response, next: NextFunction) => {
-    fn(req, res, next).catch(next);
-  };
-}
-
-router.post(
-  '/',
-  validate(CreateUserSchema),
-  asyncHandler(async (req: Request, res: Response) => {
-    const user = await userService.create(req.body);
-    res.status(201).json(user);
-  })
-);
-
-router.get(
-  '/:id',
-  asyncHandler(async (req: Request, res: Response) => {
-    const user = await userService.findById(req.params.id);
-    if (!user) {
-      res.status(404).json({ error: 'User not found' });
-      return;
-    }
-    res.json(user);
-  })
-);
-
-export const userRouter = router;
-```
-
-### Pattern 3: Centralized Error Handling
-
-```typescript
-// Custom error classes
-class AppError extends Error {
-  constructor(
-    public statusCode: number,
-    message: string,
-    public isOperational = true
-  ) {
-    super(message);
-    Object.setPrototypeOf(this, AppError.prototype);
-  }
-}
-
-class NotFoundError extends AppError {
-  constructor(resource: string) {
-    super(404, `${resource} not found`);
-  }
-}
-
-// Error handling middleware — MUST have 4 parameters
-function errorHandler(
-  err: Error,
-  req: Request,
-  res: Response,
-  _next: NextFunction
-): void {
-  if (err instanceof AppError) {
-    res.status(err.statusCode).json({
-      error: err.message,
-      ...(process.env.NODE_ENV === 'development' && { stack: err.stack }),
-    });
-    return;
-  }
-
-  // Unexpected errors — log and return generic message
-  console.error('Unhandled error:', err);
-  res.status(500).json({ error: 'Internal server error' });
-}
-
-// Register AFTER all routes
-app.use('/api/users', userRouter);
-app.use('/api/orders', orderRouter);
-app.use(errorHandler);  // Must be last
-```
-
-## Anti-Patterns
-
-- **No async error handling**: Unhandled promise rejections in route handlers crash the process. Always use an async wrapper or express-async-errors.
-- **Error middleware not last**: Registering the error handler before routes means it never catches route errors.
-- **Business logic in route handlers**: Route handlers should validate, delegate to a service, and format the response. Keep them thin.
-- **No input validation**: Trusting `req.body` without validation opens injection and type-mismatch vulnerabilities.
-
-## Integration Points
-
-- **React/Next.js**: Express APIs are consumed by React client components; see `react-patterns.md` and `nextjs-patterns.md`.
-- **TypeScript**: Strict typing for middleware, requests, and responses; see `ts-conventions.md`.
-- **Testing**: Use `supertest` for HTTP-level integration tests against the Express app.
-- **Docker**: Express apps are containerized with multi-stage builds for production deployment.

package/_gaia/dev/knowledge/typescript/nextjs-patterns.md

@@ -1,166 +0,0 @@
----
-name: Next.js Application Patterns
-stack: typescript
-version: "1.0"
-focus: [nextjs]
----
-
-# Next.js Application Patterns
-
-## Principle
-
-Use the App Router with React Server Components (RSC) as the default rendering strategy. Fetch data on the server to reduce client bundle size and improve initial load. Use client components (`'use client'`) only when interactivity (hooks, event handlers, browser APIs) is required. Leverage Next.js caching layers (request memoization, data cache, full route cache) deliberately.
-
-## Rationale
-
-Server Components eliminate the client-side JavaScript for data display, reducing bundle sizes by 30-50%. The App Router's nested layout system prevents re-rendering shared UI (navigation, sidebars) during navigation. Next.js provides multiple caching layers that must be understood to avoid stale data in production. Route handlers replace API routes with a more natural request/response model.
-
-## Pattern Examples
-
-### Pattern 1: Server Component with Data Fetching
-
-```typescript
-// app/users/page.tsx — Server Component (default, no 'use client')
-import { UserList } from './user-list';
-
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-async function getUsers(): Promise<User[]> {
-  const res = await fetch('https://api.example.com/users', {
-    next: { revalidate: 60 },  // ISR: revalidate every 60 seconds
-  });
-  if (!res.ok) throw new Error('Failed to fetch users');
-  return res.json();
-}
-
-export default async function UsersPage() {
-  const users = await getUsers();
-  return (
-    <main>
-      <h1>Users</h1>
-      {/* UserList can be a client component for interactivity */}
-      <UserList initialUsers={users} />
-    </main>
-  );
-}
-
-// app/users/loading.tsx — Automatic Suspense boundary
-export default function Loading() {
-  return <UserListSkeleton />;
-}
-
-// app/users/error.tsx — Error boundary
-'use client';
-export default function Error({ error, reset }: {
-  error: Error & { digest?: string };
-  reset: () => void;
-}) {
-  return (
-    <div>
-      <h2>Something went wrong</h2>
-      <button onClick={reset}>Try again</button>
-    </div>
-  );
-}
-```
-
-### Pattern 2: Nested Layouts
-
-```typescript
-// app/layout.tsx — Root layout (wraps all pages)
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <Navbar />
-        {children}
-      </body>
-    </html>
-  );
-}
-
-// app/dashboard/layout.tsx — Dashboard layout (persists across dashboard pages)
-import { Sidebar } from '@/components/sidebar';
-
-export default function DashboardLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <div className="flex">
-      <Sidebar />
-      <main className="flex-1 p-6">{children}</main>
-    </div>
-  );
-}
-
-// app/dashboard/analytics/page.tsx — inherits both layouts
-export default async function AnalyticsPage() {
-  const metrics = await getMetrics();
-  return <MetricsDashboard data={metrics} />;
-}
-```
-
-### Pattern 3: Route Handler with Validation
-
-```typescript
-// app/api/users/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { z } from 'zod';
-
-const CreateUserSchema = z.object({
-  name: z.string().min(1).max(100),
-  email: z.string().email(),
-  role: z.enum(['admin', 'member']).default('member'),
-});
-
-export async function POST(request: NextRequest) {
-  try {
-    const body = await request.json();
-    const validated = CreateUserSchema.parse(body);
-    const user = await db.user.create({ data: validated });
-    return NextResponse.json(user, { status: 201 });
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return NextResponse.json(
-        { errors: error.flatten().fieldErrors },
-        { status: 422 }
-      );
-    }
-    return NextResponse.json(
-      { error: 'Internal server error' },
-      { status: 500 }
-    );
-  }
-}
-
-export async function GET(request: NextRequest) {
-  const { searchParams } = new URL(request.url);
-  const page = parseInt(searchParams.get('page') ?? '1');
-  const limit = parseInt(searchParams.get('limit') ?? '20');
-  const users = await db.user.findMany({
-    skip: (page - 1) * limit,
-    take: limit,
-  });
-  return NextResponse.json(users);
-}
-```
-
-## Anti-Patterns
-
-- **`'use client'` on everything**: Treating the App Router like the Pages Router. Default to server components; opt into client only for interactivity.
-- **Fetching in client components**: Using `useEffect` to fetch data that could be fetched on the server wastes client bandwidth and reveals API details.
-- **Ignoring caching semantics**: Not setting `revalidate` or `cache` options on `fetch` leads to unexpected stale or always-fresh behavior.
-- **Passing functions as props from server to client**: Functions are not serializable across the RSC boundary. Use server actions or route handlers.
-
-## Integration Points
-
-- **React**: Client components use React hooks and patterns; see `react-patterns.md`.
-- **Express**: Next.js can sit behind an Express server for custom middleware; see `express-patterns.md`.
-- **TypeScript**: Strict typing for route handlers, page props, and metadata; see `ts-conventions.md`.
-- **Testing**: Use `@testing-library/react` with Next.js test utilities for component and integration tests.

package/_gaia/dev/knowledge/typescript/react-patterns.md

@@ -1,176 +0,0 @@
----
-name: React Component Patterns
-stack: typescript
-version: "1.0"
-focus: [react]
----
-
-# React Component Patterns
-
-## Principle
-
-Build UIs with functional components and hooks. Use `useState` for local state, `useEffect` for side effects with proper dependency arrays, `useCallback`/`useMemo` for referential stability and expensive computations, and Context for dependency injection of shared services. Compose complex components from simple, focused building blocks.
-
-## Rationale
-
-React's rendering model re-creates component output on every state change. Understanding when React re-renders and how to prevent unnecessary work is crucial for performance. Hooks provide a composable primitive that replaces class lifecycle methods with a more declarative API. Custom hooks extract and share stateful logic without render props or HOCs. Context avoids prop drilling but should not replace purpose-built state management for frequently changing data.
-
-## Pattern Examples
-
-### Pattern 1: Custom Hook for Data Fetching
-
-```typescript
-interface UseQueryResult<T> {
-  data: T | undefined;
-  error: Error | null;
-  isLoading: boolean;
-  refetch: () => void;
-}
-
-function useQuery<T>(url: string): UseQueryResult<T> {
-  const [data, setData] = useState<T>();
-  const [error, setError] = useState<Error | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
-
-  const fetchData = useCallback(async () => {
-    setIsLoading(true);
-    setError(null);
-    try {
-      const response = await fetch(url);
-      if (!response.ok) throw new Error(`HTTP ${response.status}`);
-      const json = await response.json();
-      setData(json);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setIsLoading(false);
-    }
-  }, [url]);
-
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  return { data, error, isLoading, refetch: fetchData };
-}
-
-// Usage
-function UserList() {
-  const { data: users, isLoading, error } = useQuery<User[]>('/api/users');
-  if (isLoading) return <Spinner />;
-  if (error) return <ErrorMessage error={error} />;
-  return <ul>{users?.map(u => <UserCard key={u.id} user={u} />)}</ul>;
-}
-```
-
-### Pattern 2: Compound Components with Context
-
-```typescript
-interface TabsContextValue {
-  activeTab: string;
-  setActiveTab: (id: string) => void;
-}
-
-const TabsContext = createContext<TabsContextValue | null>(null);
-
-function useTabs(): TabsContextValue {
-  const context = useContext(TabsContext);
-  if (!context) throw new Error('useTabs must be used within <Tabs>');
-  return context;
-}
-
-function Tabs({ defaultTab, children }: { defaultTab: string; children: ReactNode }) {
-  const [activeTab, setActiveTab] = useState(defaultTab);
-  return (
-    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
-      <div role="tablist">{children}</div>
-    </TabsContext.Provider>
-  );
-}
-
-function TabTrigger({ id, children }: { id: string; children: ReactNode }) {
-  const { activeTab, setActiveTab } = useTabs();
-  return (
-    <button
-      role="tab"
-      aria-selected={activeTab === id}
-      onClick={() => setActiveTab(id)}
-    >
-      {children}
-    </button>
-  );
-}
-
-function TabContent({ id, children }: { id: string; children: ReactNode }) {
-  const { activeTab } = useTabs();
-  if (activeTab !== id) return null;
-  return <div role="tabpanel">{children}</div>;
-}
-
-// Usage
-// <Tabs defaultTab="profile">
-//   <TabTrigger id="profile">Profile</TabTrigger>
-//   <TabTrigger id="settings">Settings</TabTrigger>
-//   <TabContent id="profile"><ProfileForm /></TabContent>
-//   <TabContent id="settings"><SettingsForm /></TabContent>
-// </Tabs>
-```
-
-### Pattern 3: Performance with useMemo and useCallback
-
-```typescript
-interface DataTableProps {
-  rows: DataRow[];
-  filter: string;
-  onRowClick: (row: DataRow) => void;
-}
-
-function DataTable({ rows, filter, onRowClick }: DataTableProps) {
-  // Expensive filtering — memoize so it only recomputes when inputs change
-  const filteredRows = useMemo(
-    () => rows.filter(r => r.name.toLowerCase().includes(filter.toLowerCase())),
-    [rows, filter]
-  );
-
-  // Stable callback reference for child components
-  const handleRowClick = useCallback(
-    (row: DataRow) => { onRowClick(row); },
-    [onRowClick]
-  );
-
-  return (
-    <table>
-      <tbody>
-        {filteredRows.map(row => (
-          <MemoizedRow key={row.id} row={row} onClick={handleRowClick} />
-        ))}
-      </tbody>
-    </table>
-  );
-}
-
-const MemoizedRow = memo(function Row({
-  row, onClick,
-}: { row: DataRow; onClick: (row: DataRow) => void }) {
-  return (
-    <tr onClick={() => onClick(row)}>
-      <td>{row.name}</td>
-      <td>{row.value}</td>
-    </tr>
-  );
-});
-```
-
-## Anti-Patterns
-
-- **useEffect as onChange handler**: Using `useEffect` to respond to state changes that should be handled in the event handler itself.
-- **Missing dependency array**: Omitting the dependency array in `useEffect` causes it to run on every render.
-- **Context for high-frequency updates**: Putting rapidly changing state (mouse position, animations) in Context re-renders all consumers.
-- **Premature memoization**: Wrapping everything in `useMemo`/`useCallback` adds complexity. Only memoize when profiling shows a bottleneck.
-
-## Integration Points
-
-- **Next.js**: React components are used in both server and client contexts; see `nextjs-patterns.md`.
-- **Express**: React apps consume Express APIs; see `express-patterns.md` for API design.
-- **TypeScript**: Strict typing enhances React component props; see `ts-conventions.md`.
-- **Testing**: Use React Testing Library for component tests; test custom hooks with `renderHook`.