gaia-framework 1.57.0 → 1.57.2

package/_gaia/dev/skills/git-workflow.md

@@ -1,157 +0,0 @@
----
-name: git-workflow
-version: '1.0'
-applicable_agents: [typescript-dev, angular-dev, flutter-dev, java-dev, python-dev, mobile-dev]
-test_scenarios:
-  - scenario: Feature branch creation and naming
-    expected: Branch name follows convention {type}/{ticket}-{description}
-  - scenario: Conventional commit message
-    expected: Message follows type(scope): description format
-  - scenario: PR creation with template
-    expected: PR body includes all required sections
----
-
-<!-- SECTION: branching -->
-## Branching Strategy
-
-### Trunk-Based Development
-- `main` is always deployable
-- Short-lived feature branches (max 2-3 days)
-- Use feature flags for incomplete features in production
-
-### Branch Naming Convention
-```
-{type}/{ticket-key}-{short-description}
-```
-Types: `feature/`, `fix/`, `hotfix/`, `refactor/`, `chore/`, `test/`
-
-Examples:
-```
-feature/PROJ-123-user-auth
-fix/PROJ-456-login-redirect
-hotfix/PROJ-789-payment-null
-refactor/PROJ-101-extract-service
-```
-
-### Branch Rules
-- Never commit directly to `main`
-- Delete branches after merge
-- Rebase feature branches on `main` before PR
-- One branch per story/ticket
-
-### Release Branches
-- Create `release/v{major}.{minor}.{patch}` for release candidates
-- Cherry-pick fixes to release branch if needed
-- Tag release commits: `v{major}.{minor}.{patch}`
-
-<!-- SECTION: commits -->
-## Conventional Commits
-
-### Format
-```
-type(scope): description
-
-[optional body]
-
-[optional footer(s)]
-```
-
-### Types
-| Type | Use When |
-|------|----------|
-| `feat` | New feature or capability |
-| `fix` | Bug fix |
-| `refactor` | Code restructuring, no behavior change |
-| `test` | Adding or updating tests |
-| `docs` | Documentation only |
-| `chore` | Build, tooling, dependencies |
-| `style` | Formatting, whitespace, semicolons |
-| `perf` | Performance improvement |
-| `ci` | CI/CD configuration |
-
-### Scope
-- Use the component or module name: `feat(auth): add JWT refresh`
-- Use the file or layer: `fix(api): handle null response`
-- Omit scope for broad changes: `chore: update dependencies`
-
-### Examples
-```
-feat(auth): add password reset flow
-fix(cart): prevent negative quantities
-refactor(user-service): extract validation logic
-test(payment): add integration tests for Stripe webhook
-docs(api): update endpoint documentation
-perf(search): add database index for full-text queries
-```
-
-### Breaking Changes
-- Add `!` after type/scope: `feat(api)!: change response format`
-- Add `BREAKING CHANGE:` footer with migration instructions
-
-<!-- SECTION: pull-requests -->
-## Pull Requests
-
-### PR Template
-```markdown
-## Summary
-Brief description of changes and motivation.
-
-## Changes
-- List of specific changes made
-
-## Testing
-- [ ] Unit tests added/updated
-- [ ] Integration tests pass
-- [ ] Manual testing completed
-
-## Checklist
-- [ ] Code follows project conventions
-- [ ] No console.log/print statements left
-- [ ] Documentation updated if needed
-- [ ] No secrets or credentials committed
-```
-
-### Review Checklist
-- Correctness: Does the code do what it claims?
-- Tests: Are changes covered by tests?
-- Security: Any new attack vectors introduced?
-- Performance: Any N+1 queries, unnecessary re-renders?
-- Readability: Can a new team member understand this?
-
-### Merge Strategies
-- **Squash merge** for feature branches (clean history)
-- **Merge commit** for release branches (preserve history)
-- **Rebase** for keeping branch up to date with main
-- Never force push to shared branches
-
-<!-- SECTION: conflict-resolution -->
-## Conflict Resolution
-
-### Merge vs Rebase
-- **Rebase** for local feature branches before PR
-- **Merge** when integrating shared branches
-- Never rebase public/shared branches
-
-### Conflict Markers
-```
-<<<<<<< HEAD (your changes)
-  current code
-=======
-  incoming code
->>>>>>> feature/branch-name
-```
-
-### Resolution Steps
-1. Identify all conflicts: `git diff --name-only --diff-filter=U`
-2. Open each file, understand both sides of the conflict
-3. Choose the correct resolution (not always "ours" or "theirs")
-4. Remove all conflict markers
-5. Run tests after resolution
-6. Stage resolved files: `git add {file}`
-7. Complete the merge/rebase: `git rebase --continue` or `git merge --continue`
-
-### Prevention
-- Rebase frequently on main (daily)
-- Communicate with team about shared file changes
-- Keep PRs small to reduce conflict surface
-- Use CODEOWNERS to assign clear file ownership

package/_gaia/dev/skills/security-basics.md

@@ -1,230 +0,0 @@
----
-name: security-basics
-version: '1.0'
-applicable_agents: [typescript-dev, angular-dev, flutter-dev, java-dev, python-dev, mobile-dev]
-test_scenarios:
-  - scenario: Input validation implementation
-    expected: All user inputs are validated at the boundary with allowlists and type checks
-  - scenario: Secrets management setup
-    expected: Secrets are loaded from environment variables or vault, never hardcoded
-  - scenario: CORS configuration
-    expected: CORS allows only specific origins, methods, and headers for the application
----
-
-<!-- SECTION: owasp-top-10 -->
-## OWASP Top 10 Prevention
-
-### A01: Broken Access Control
-- Deny by default; require explicit grants for each resource
-- Enforce ownership checks: users can only access their own data
-- Disable directory listing on web servers
-- Log and alert on access control failures
-
-```typescript
-// Always check resource ownership
-async function getOrder(userId: string, orderId: string) {
-  const order = await orderRepo.findById(orderId);
-  if (!order) throw new NotFoundError('Order not found');
-  if (order.userId !== userId) throw new ForbiddenError('Access denied');
-  return order;
-}
-```
-
-### A02: Cryptographic Failures
-- Use TLS 1.2+ for all data in transit
-- Hash passwords with bcrypt (cost factor >= 12) or argon2
-- Never roll your own cryptography
-- Encrypt sensitive data at rest (PII, payment info)
-
-### A03: Injection
-- Use parameterized queries for all database operations
-- Never concatenate user input into queries, commands, or templates
-```typescript
-// BAD: SQL injection risk
-const query = `SELECT * FROM users WHERE id = '${userId}'`;
-
-// GOOD: Parameterized query
-const query = 'SELECT * FROM users WHERE id = $1';
-const result = await db.query(query, [userId]);
-```
-
-### A05: Security Misconfiguration
-- Remove default accounts and passwords
-- Disable stack traces and debug info in production
-- Keep dependencies updated; automate vulnerability scanning
-- Use security headers: `Strict-Transport-Security`, `X-Content-Type-Options`
-
-### A07: Identification and Authentication Failures
-- Enforce strong passwords (min 12 chars, check against breached lists)
-- Implement rate limiting on login endpoints
-- Use multi-factor authentication for admin accounts
-- Invalidate sessions on password change
-
-### A09: Security Logging and Monitoring
-- Log authentication events (success and failure)
-- Log authorization failures and input validation rejections
-- Never log sensitive data (passwords, tokens, PII)
-- Set up alerts for anomalous patterns (brute force, unusual access)
-
-<!-- SECTION: input-validation -->
-## Input Validation
-
-### Validate at Boundaries
-Apply validation at every entry point into the system:
-- HTTP request bodies, query params, path params, headers
-- Message queue payloads
-- File uploads
-- Third-party API responses
-
-### Validation Strategy
-```typescript
-// Use a schema validation library (e.g., Zod, Joi, class-validator)
-import { z } from 'zod';
-
-const CreateUserSchema = z.object({
-  email: z.string().email().max(255),
-  name: z.string().min(2).max(100).trim(),
-  age: z.number().int().min(13).max(150).optional(),
-});
-
-// Validate at the controller boundary
-function createUser(req: Request, res: Response) {
-  const result = CreateUserSchema.safeParse(req.body);
-  if (!result.success) {
-    return res.status(422).json({
-      type: 'validation-error',
-      errors: result.error.issues,
-    });
-  }
-  // result.data is typed and safe to use
-  return userService.create(result.data);
-}
-```
-
-### Validation Rules
-- **Allowlist over denylist**: Define what is accepted, not what is rejected
-- **Type coercion**: Parse strings to expected types explicitly
-- **Length limits**: Enforce max length on all string inputs
-- **Range checks**: Enforce min/max on numeric inputs
-- **Format validation**: Use regex or parsers for emails, URLs, dates
-- **Sanitization**: Strip HTML/script tags from text that will be rendered
-
-### File Upload Validation
-- Validate MIME type against an allowlist
-- Enforce maximum file size
-- Generate new filenames; never use user-provided names
-- Scan uploaded files for malware if possible
-- Store uploads outside the web root
-
-<!-- SECTION: secrets-management -->
-## Secrets Management
-
-### Environment-Based Secrets
-- Load secrets from environment variables, never from source code
-- Use `.env` files for local development only (git-ignored)
-- Use a secrets manager in production (AWS Secrets Manager, Vault, GCP Secret Manager)
-
-### .env File Pattern
-```bash
-# .env.example (committed -- shows structure, no real values)
-DATABASE_URL=postgres://user:password@localhost:5432/dbname
-JWT_SECRET=replace-with-a-real-secret
-STRIPE_API_KEY=sk_test_replace_me
-```
-
-```bash
-# .env (git-ignored -- contains real local values)
-DATABASE_URL=postgres://dev:devpass@localhost:5432/myapp_dev
-JWT_SECRET=local-dev-secret-not-for-production
-STRIPE_API_KEY=sk_test_abc123
-```
-
-### Configuration Loading
-```typescript
-// Validate required env vars at startup, fail fast if missing
-function loadConfig() {
-  const required = ['DATABASE_URL', 'JWT_SECRET'];
-  const missing = required.filter((key) => !process.env[key]);
-  if (missing.length > 0) {
-    throw new Error(`Missing required env vars: ${missing.join(', ')}`);
-  }
-  return {
-    databaseUrl: process.env.DATABASE_URL,
-    jwtSecret: process.env.JWT_SECRET,
-    port: parseInt(process.env.PORT || '3000', 10),
-  };
-}
-```
-
-### Secrets Hygiene
-- Rotate secrets on a regular schedule (at minimum annually)
-- Use separate secrets per environment (dev, staging, production)
-- Never log secrets, even at debug level
-- If a secret is leaked, rotate it immediately
-- Use short-lived tokens (JWTs, OAuth tokens) where possible
-- Use pre-commit hooks (`git-secrets`, `gitleaks`) to prevent accidental commits
-
-<!-- SECTION: cors-csrf -->
-## CORS and CSRF
-
-### CORS Configuration
-Cross-Origin Resource Sharing controls which domains can call your API.
-
-```typescript
-// Express CORS configuration
-import cors from 'cors';
-
-app.use(cors({
-  origin: ['https://app.example.com', 'https://admin.example.com'],
-  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
-  allowedHeaders: ['Content-Type', 'Authorization'],
-  credentials: true,
-  maxAge: 86400, // cache preflight for 24 hours
-}));
-```
-
-### CORS Rules
-- Never use `origin: '*'` with `credentials: true`
-- Allowlist specific origins; do not reflect the `Origin` header blindly
-- Restrict methods and headers to what the application actually uses
-- Use `maxAge` to reduce preflight requests
-
-### CSRF Protection
-Cross-Site Request Forgery tricks a user's browser into making unwanted requests.
-
-**Token-based CSRF prevention**:
-```typescript
-// Server: generate token and set as cookie
-import csrf from 'csurf';
-app.use(csrf({ cookie: true }));
-
-// Client: include token in request header
-fetch('/api/transfer', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'X-CSRF-Token': getCsrfToken(), // read from cookie or meta tag
-  },
-  body: JSON.stringify({ amount: 100, to: 'account-456' }),
-});
-```
-
-### CSRF Prevention Strategies
-| Strategy | How It Works |
-|----------|--------------|
-| Synchronizer token | Server generates token, client sends it back with each state-changing request |
-| Double-submit cookie | Token in cookie + token in header; server compares both |
-| SameSite cookies | Set `SameSite=Strict` or `Lax` on session cookies |
-| Custom request header | Require a custom header (e.g., `X-Requested-With`) that browsers block cross-origin |
-
-### Security Headers Checklist
-```
-Strict-Transport-Security: max-age=31536000; includeSubDomains
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
-Content-Security-Policy: default-src 'self'
-Referrer-Policy: strict-origin-when-cross-origin
-Permissions-Policy: camera=(), microphone=(), geolocation=()
-```
-- Apply these headers globally via middleware or reverse proxy
-- Test header configuration with securityheaders.com

package/_gaia/dev/skills/testing-patterns.md

@@ -1,232 +0,0 @@
----
-name: testing-patterns
-version: '1.0'
-applicable_agents: [typescript-dev, angular-dev, flutter-dev, java-dev, python-dev, mobile-dev]
-test_scenarios:
-  - scenario: Unit test structure
-    expected: Test follows Arrange-Act-Assert pattern with descriptive naming
-  - scenario: Integration test isolation
-    expected: Test uses dedicated database/container and cleans up after execution
-  - scenario: Test double selection
-    expected: Appropriate double type chosen (mock for behavior, stub for state, fake for complex deps)
----
-
-<!-- SECTION: tdd-cycle -->
-## TDD Cycle
-
-### Red-Green-Refactor
-1. **Red**: Write a failing test that defines the desired behavior
-2. **Green**: Write the minimum code to make the test pass
-3. **Refactor**: Improve the code while keeping all tests green
-
-### TDD Rules
-- Never write production code without a failing test
-- Write only enough test to fail (compilation failures count)
-- Write only enough production code to pass the failing test
-- Refactor only when all tests are green
-
-### Test Pyramid
-```
-        /  E2E  \          Few, slow, expensive
-       /----------\
-      / Integration \      Moderate count
-     /----------------\
-    /    Unit Tests     \  Many, fast, cheap
-```
-
-- **Unit tests** (70%): Test individual functions and classes in isolation
-- **Integration tests** (20%): Test component interactions and external boundaries
-- **E2E tests** (10%): Test critical user journeys through the full stack
-
-### When to Use TDD
-- New features with clear acceptance criteria
-- Bug fixes (write test that reproduces bug first)
-- Complex business logic with edge cases
-- API contracts (test expected inputs/outputs)
-
-### When TDD May Not Fit
-- Exploratory prototyping (write tests after design stabilizes)
-- Pure UI layout work (use visual regression tests instead)
-- Generated code (test the generator, not every output)
-
-<!-- SECTION: unit-testing -->
-## Unit Testing
-
-### Arrange-Act-Assert (AAA)
-```typescript
-describe('OrderService', () => {
-  it('should apply 10% discount for orders over $100', () => {
-    // Arrange
-    const order = new Order([
-      new LineItem('Widget', 60.00),
-      new LineItem('Gadget', 50.00),
-    ]);
-    const service = new OrderService();
-
-    // Act
-    const total = service.calculateTotal(order);
-
-    // Assert
-    expect(total).toBe(99.00); // 110 - 10% = 99
-  });
-});
-```
-
-### Naming Conventions
-Use descriptive names that document behavior:
-```
-should_[expected behavior]_when_[condition]
-```
-Examples:
-- `should_reject_order_when_cart_is_empty`
-- `should_apply_discount_when_total_exceeds_threshold`
-- `should_send_notification_when_payment_succeeds`
-
-### Test Organization
-- One test file per source file: `user.service.ts` -> `user.service.spec.ts`
-- Group related tests with `describe` blocks
-- Keep each test focused on a single behavior
-- Avoid logic in tests (no if/else, loops, or try/catch)
-
-### Edge Cases to Cover
-- Empty inputs (null, undefined, empty string, empty array)
-- Boundary values (min, max, zero, negative)
-- Error conditions (invalid input, network failure, timeout)
-- Concurrent access (if applicable)
-
-### Test Independence
-- Tests must not depend on execution order
-- Each test sets up its own state and tears it down
-- No shared mutable state between tests
-- Use `beforeEach` for common setup, not `beforeAll` with mutations
-
-<!-- SECTION: integration-testing -->
-## Integration Testing
-
-### What to Integration Test
-- Database queries and transactions
-- HTTP API endpoints (request/response cycle)
-- Message queue producers and consumers
-- External service integrations (with contract tests)
-- Authentication and authorization flows
-
-### Database Integration Tests
-```typescript
-describe('UserRepository', () => {
-  let db: TestDatabase;
-
-  beforeAll(async () => {
-    db = await TestDatabase.create(); // isolated test DB
-  });
-
-  afterAll(async () => {
-    await db.destroy();
-  });
-
-  beforeEach(async () => {
-    await db.truncateAll(); // clean state per test
-  });
-
-  it('should find user by email', async () => {
-    await db.seed('users', { email: 'test@example.com', name: 'Test' });
-    const repo = new UserRepository(db.connection);
-
-    const user = await repo.findByEmail('test@example.com');
-
-    expect(user).toBeDefined();
-    expect(user.name).toBe('Test');
-  });
-});
-```
-
-### API Integration Tests
-```typescript
-describe('POST /api/users', () => {
-  it('should create a user and return 201', async () => {
-    const response = await request(app)
-      .post('/api/users')
-      .send({ email: 'new@example.com', name: 'New User' })
-      .expect(201);
-
-    expect(response.body.data.email).toBe('new@example.com');
-  });
-
-  it('should return 422 for invalid email', async () => {
-    const response = await request(app)
-      .post('/api/users')
-      .send({ email: 'not-an-email', name: 'Bad User' })
-      .expect(422);
-
-    expect(response.body.errors[0].field).toBe('email');
-  });
-});
-```
-
-### Isolation Strategies
-- Use test containers (Testcontainers) for databases, Redis, etc.
-- Truncate tables between tests, not between suites
-- Use separate database schemas or databases per test suite
-- Never run integration tests against shared environments
-
-<!-- SECTION: test-doubles -->
-## Test Doubles
-
-### Types of Test Doubles
-| Type | Purpose | Verifies |
-|------|---------|----------|
-| **Stub** | Returns pre-configured responses | State (return values) |
-| **Mock** | Records and verifies interactions | Behavior (method calls) |
-| **Spy** | Wraps real object, records calls | Both state and behavior |
-| **Fake** | Simplified working implementation | State via simplified logic |
-| **Dummy** | Fills a parameter, never actually used | Nothing |
-
-### When to Use Each
-- **Stub**: Replace a dependency to control inputs to the system under test
-- **Mock**: Verify the system under test calls a dependency correctly
-- **Spy**: Keep real behavior but verify interactions happened
-- **Fake**: Replace complex infrastructure (in-memory DB, fake HTTP server)
-- **Dummy**: Satisfy a function signature for a parameter you do not care about
-
-### Stub Example
-```typescript
-const priceService = {
-  getPrice: jest.fn().mockReturnValue(25.00),
-};
-const calculator = new OrderCalculator(priceService);
-const total = calculator.calculate(['item-1', 'item-2']);
-expect(total).toBe(50.00);
-```
-
-### Mock Example
-```typescript
-const emailService = { send: jest.fn() };
-const registration = new RegistrationService(emailService);
-
-await registration.register({ email: 'user@example.com' });
-
-expect(emailService.send).toHaveBeenCalledWith(
-  expect.objectContaining({ to: 'user@example.com', template: 'welcome' })
-);
-```
-
-### Fake Example
-```typescript
-class FakeUserRepository implements UserRepository {
-  private users: Map<string, User> = new Map();
-
-  async save(user: User): Promise<void> {
-    this.users.set(user.id, user);
-  }
-
-  async findById(id: string): Promise<User | null> {
-    return this.users.get(id) ?? null;
-  }
-}
-```
-
-### Test Double Guidelines
-- Prefer stubs over mocks -- test behavior outcomes, not implementation
-- Do not mock what you do not own (wrap third-party libs in adapters)
-- If you need more than 3 mocks in a test, the class has too many dependencies
-- Fakes are the best choice for repositories and external services
-- Reset all mocks/stubs in `beforeEach` to prevent test pollution