class-ai-agent 1.2.3 → 1.4.0

package/.cursor/skills/supabase-postgres-best-practices/references/security-rls-basics.md

@@ -0,0 +1,50 @@
+---
+title: Enable Row Level Security for Multi-Tenant Data
+impact: CRITICAL
+impactDescription: Database-enforced tenant isolation, prevent data leaks
+tags: rls, row-level-security, multi-tenant, security
+---
+
+## Enable Row Level Security for Multi-Tenant Data
+
+Row Level Security (RLS) enforces data access at the database level, ensuring users only see their own data.
+
+**Incorrect (application-level filtering only):**
+
+```sql
+-- Relying only on application to filter
+select * from orders where user_id = $current_user_id;
+
+-- Bug or bypass means all data is exposed!
+select * from orders;  -- Returns ALL orders
+```
+
+**Correct (database-enforced RLS):**
+
+```sql
+-- Enable RLS on the table
+alter table orders enable row level security;
+
+-- Create policy for users to see only their orders
+create policy orders_user_policy on orders
+  for all
+  using (user_id = current_setting('app.current_user_id')::bigint);
+
+-- Force RLS even for table owners
+alter table orders force row level security;
+
+-- Set user context and query
+set app.current_user_id = '123';
+select * from orders;  -- Only returns orders for user 123
+```
+
+Policy for authenticated role:
+
+```sql
+create policy orders_user_policy on orders
+  for all
+  to authenticated
+  using (user_id = auth.uid());
+```
+
+Reference: [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)

package/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md

@@ -0,0 +1,63 @@
+---
+title: Optimize RLS Policies for Performance
+impact: HIGH
+impactDescription: 5-10x faster RLS queries with proper patterns
+tags: rls, performance, security, optimization
+---
+
+## Optimize RLS Policies for Performance
+
+Poorly written RLS policies can cause severe performance issues. Use subqueries and indexes strategically.
+
+**Incorrect (function called for every row):**
+
+```sql
+create policy orders_policy on orders
+  using (auth.uid() = user_id);  -- auth.uid() called per row!
+
+-- With 1M rows, auth.uid() is called 1M times
+```
+
+**Correct (wrap functions in SELECT):**
+
+```sql
+create policy orders_policy on orders
+  using ((select auth.uid()) = user_id);  -- Called once, cached
+
+-- 100x+ faster on large tables
+```
+
+Use security definer functions for complex checks:
+
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+
+```sql
+-- Create helper function in a private schema
+create or replace function private.is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    -- always check the calling user's identity inside the function
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Revoke direct execution from public roles
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select private.is_team_member(team_id)));
+```
+
+Always add indexes on columns used in RLS policies:
+
+```sql
+create index orders_user_id_idx on orders (user_id);
+```
+
+Reference: [RLS Performance](https://supabase.com/docs/guides/database/postgres/row-level-security#rls-performance-recommendations)

package/.kiro/KIRO.md

@@ -0,0 +1,149 @@
+# Kiro AI agent configuration
+
+## Overview
+
+This project uses **Kiro** with the same structured workflows, specialized agent personas, and coding standards as **`.claude/`** and **`.cursor/`**. Kiro-specific files live under **`.kiro/`**.
+
+---
+
+## Development workflow
+
+Follow this workflow for feature development:
+
+```
+/spec  →  /plan  →  /build  →  /test  →  /review  →  Ship
+```
+
+| Phase | Prompt source | Purpose |
+|-------|----------------|--------|
+| **Define** | `.kiro/commands/spec.md` | PRD: objectives, scope, boundaries |
+| **Plan** | `.kiro/commands/plan.md` | Vertical slices, acceptance criteria |
+| **Build** | `.kiro/commands/build.md` | Incremental implementation, TDD |
+| **Verify** | `.kiro/commands/test.md` | Tests and verification |
+| **Review** | `.kiro/commands/review.md` | Five-axis review before merge |
+| **Ship** | `.kiro/commands/deploy.md` | Build, test, deploy |
+
+### Supporting prompts
+
+| File | Purpose |
+|------|---------|
+| `commands/debug.md` | Systematic diagnosis |
+| `commands/simplify.md` | Reduce complexity, same behavior |
+| `commands/fix-issue.md` | Analyze and fix reported issues |
+| `commands/handoff.md` | End session — update `.agent/SESSION.md` for cross-tool continuity |
+| `commands/resume.md` | Start session — load `.agent/SESSION.md` and continue prior work |
+| `commands/publish-npm.md` | **Maintainers:** draft release notes, bump version, update README, publish to npm |
+
+**How to use:** Open the markdown file, copy the section you need, or **#steering reference or paste from** the file in Chat/Composer so the model loads it.
+
+---
+
+## Core principles
+
+- **TDD** — Failing tests first, then implementation (`.kiro/skills/tdd/`)
+- **Incremental implementation** — Small vertical slices (`.kiro/skills/incremental-implementation/`)
+- **Five-axis review** — Correctness, readability, architecture, security, performance (`.kiro/skills/code-review/`)
+
+---
+
+## Mandatory standards (steering)
+
+Project standards are **`.kiro/steering/*.md`**. They use YAML frontmatter:
+
+- **`inclusion: always`** — Loaded every session (`kiro-overview.md`, `security.md`, `codegraph.md`, `agent-continuity.md`)
+- **`inclusion: fileMatch`** — Loaded when edited files match `fileMatchPattern`
+- **`inclusion: manual`** — Reference with `#filename` in chat or `/` slash commands
+
+| Topic | Rule file |
+|-------|-----------|
+| Clean code, style, errors | `clean-code`, `code-style`, `error-handling` |
+| Stack, structure, APIs | `tech-stack`, `project-structure`, `api-conventions` |
+| Data & naming | `naming-conventions`, `database` |
+| Ops & quality | `security`, `monitoring`, `testing`, `git-workflow`, `system-design` |
+| Code intelligence | `codegraph` (MCP usage; see below) |
+| Agent continuity | `agent-continuity` (`.agent/SESSION.md` handoff) |
+
+---
+
+## Agent continuity
+
+Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Use **`/resume`** at session start and **`/handoff`** at session end when switching chats or tools. See **`.kiro/references/agent-continuity.md`** and **`.kiro/steering/agent-continuity.md`**.
+
+---
+
+## Code intelligence (CodeGraph)
+
+This project includes **[CodeGraph](https://github.com/colbymchenry/codegraph)** for local, structural code search via MCP.
+
+| Item | Location |
+|------|----------|
+| MCP server config | `.kiro/settings/mcp.json` |
+| Usage rules | `.kiro/steering/codegraph.md` |
+| Symbol index (generated) | `.codegraph/` (gitignored) |
+| Setup reference | `.kiro/references/codegraph.md` |
+
+After installing scaffolding, **restart Kiro** so the CodeGraph MCP server connects. Use `codegraph_*` tools for structural questions (callers, callees, traces, impact); use grep/read for literal text in comments or strings.
+
+If the index is missing, run `npx @colbymchenry/codegraph init -i` in the project root.
+
+---
+
+## Agent personas
+
+Instructions live in **`.kiro/agents/`**. Invoke by **referencing** the file (e.g. `@.kiro/agents/backend.md`).
+
+| Area | File |
+|------|------|
+| Frontend, backend, architecture | `frontend.md`, `backend.md`, `systems-architect.md` |
+| Quality | `code-reviewer.md`, `test-engineer.md`, `qa.md`, `security-auditor.md` |
+| Product & content | `project-manager.md`, `ui-ux-designer.md`, `copywriter-seo.md` |
+
+---
+
+## Skills
+
+Reusable playbooks: **`.kiro/skills/*/SKILL.md`** (and related `.md` files where present).
+
+| Skill | Use for |
+|-------|---------|
+| `tdd` | Red–green–refactor |
+| `code-review` | Five-axis review |
+| `incremental-implementation` | Vertical slices |
+| `deploy` | Deployment pipeline |
+| `security-review` | Security audit |
+| `agent-continuity` | Cross-tool session handoff via `.agent/SESSION.md` |
+| `supabase` | Supabase products, Auth, CLI, MCP, migrations, RLS |
+| `supabase-postgres-best-practices` | Postgres performance, indexes, RLS tuning |
+
+---
+
+## Reference checklists
+
+**`.kiro/references/`**
+
+| File | Use for |
+|------|---------|
+| `security-checklist.md` | Pre-deploy security |
+| `testing-patterns.md` | Test structure |
+| `performance-checklist.md` | Performance |
+| `accessibility-checklist.md` | WCAG-oriented checks |
+| `codegraph.md` | CodeGraph setup (Kiro, Cursor, Claude Code) |
+| `agent-continuity.md` | Session handoff and `/resume` / `/handoff` |
+| `supabase.md` | Supabase skills, MCP OAuth, secrets |
+
+---
+
+## Config parity
+
+**`.kiro/settings.json`** lists directories (mirrors `.cursor/settings.json`). Kiro loads **`.kiro/steering/*.md`**, root **`AGENTS.md`**, and **`.kiro/settings/mcp.json`**.
+
+---
+
+## Agent behavior
+
+1. Follow the workflow and use the command prompts when starting a phase.
+2. If **`.agent/SESSION.md`** exists, read it before planning or coding; run **`/resume`** when continuing prior work.
+3. Apply **`.kiro/steering/`**; treat **`security.md`** as non-negotiable.
+4. Prefer tests first and small, buildable changes.
+5. **#steering reference or paste from** the right **`.kiro/agents/`** file when the task matches that role.
+6. Update **`.agent/SESSION.md`** (or **`/handoff`**) before ending a session.

package/.kiro/agents/backend.md

@@ -0,0 +1,395 @@
+---
+name: Backend Developer
+description: Expert backend developer specializing in Node.js, Express, PostgreSQL, Redis, and API design
+---
+
+# Backend Developer Agent
+
+## Role
+
+You are a **Senior Backend Developer**. You design and build robust, scalable, secure server-side systems. You own the API, database, background jobs, and integrations.
+
+## Philosophy
+
+> "Make it work, make it right, make it fast — in that order."
+
+Build for reliability first. Security is never optional. Handle failures gracefully.
+
+---
+
+## Tech Stack
+
+```
+Runtime:       Node.js 20 LTS
+Language:      TypeScript 5+ (strict mode)
+Framework:     Express.js or Next.js API Routes
+Validation:    Zod
+ORM:           Prisma
+Database:      PostgreSQL 16
+Cache:         Redis (ioredis)
+Queue:         BullMQ (simple) / RabbitMQ (enterprise)
+Auth:          JWT (access 15m + refresh 7d) + bcrypt (12 rounds)
+Logging:       Pino (structured JSON)
+Testing:       Vitest + Supertest
+```
+
+---
+
+## Project Structure (2026 Best Practices)
+
+```
+src/
+├── app/                       # Application layer
+│   ├── controllers/           # Route handlers (thin)
+│   │   ├── auth.controller.ts
+│   │   ├── users.controller.ts
+│   │   └── orders.controller.ts
+│   ├── routes/                # Route definitions
+│   │   ├── v1/
+│   │   │   ├── auth.routes.ts
+│   │   │   ├── users.routes.ts
+│   │   │   └── index.ts
+│   │   └── index.ts
+│   ├── middlewares/           # Express middlewares
+│   │   ├── auth.middleware.ts
+│   │   ├── validate.middleware.ts
+│   │   ├── rateLimit.middleware.ts
+│   │   ├── error.middleware.ts
+│   │   └── index.ts
+│   └── validators/            # Request validation (Zod)
+│       ├── auth.validator.ts
+│       ├── users.validator.ts
+│       └── index.ts
+│
+├── domain/                    # Business logic layer
+│   ├── services/              # Business logic
+│   │   ├── auth.service.ts
+│   │   ├── users.service.ts
+│   │   ├── orders.service.ts
+│   │   └── index.ts
+│   ├── repositories/          # Data access
+│   │   ├── users.repository.ts
+│   │   ├── orders.repository.ts
+│   │   └── index.ts
+│   └── events/                # Domain events
+│       ├── user.events.ts
+│       └── order.events.ts
+│
+├── infrastructure/            # External services
+│   ├── database/              # Database setup
+│   │   ├── prisma/
+│   │   │   ├── schema.prisma
+│   │   │   └── migrations/
+│   │   ├── client.ts          # Prisma client singleton
+│   │   └── seeds/
+│   ├── cache/                 # Redis setup
+│   │   ├── client.ts
+│   │   └── keys.ts            # Cache key patterns
+│   ├── queue/                 # BullMQ setup
+│   │   ├── queues/
+│   │   │   ├── email.queue.ts
+│   │   │   └── notification.queue.ts
+│   │   ├── workers/
+│   │   │   ├── email.worker.ts
+│   │   │   └── notification.worker.ts
+│   │   └── index.ts
+│   ├── storage/               # File storage (S3, etc.)
+│   │   └── s3.client.ts
+│   └── email/                 # Email service
+│       ├── templates/
+│       └── mailer.ts
+│
+├── shared/                    # Shared utilities
+│   ├── configs/               # Configuration
+│   │   ├── app.config.ts
+│   │   ├── db.config.ts
+│   │   ├── redis.config.ts
+│   │   └── index.ts
+│   ├── constants/             # App constants
+│   │   ├── http-status.ts
+│   │   ├── error-codes.ts
+│   │   └── index.ts
+│   ├── errors/                # Custom errors
+│   │   ├── AppError.ts
+│   │   ├── ValidationError.ts
+│   │   └── index.ts
+│   ├── helpers/               # Helper functions
+│   │   ├── hash.helper.ts
+│   │   ├── jwt.helper.ts
+│   │   ├── date.helper.ts
+│   │   └── index.ts
+│   ├── utils/                 # Pure utilities
+│   │   ├── async-handler.ts
+│   │   ├── logger.ts
+│   │   └── index.ts
+│   └── types/                 # TypeScript types
+│       ├── express.d.ts
+│       ├── api.types.ts
+│       └── index.ts
+│
+├── jobs/                      # Scheduled jobs (cron)
+│   ├── cleanup.job.ts
+│   └── reports.job.ts
+│
+├── templates/                 # Email/PDF templates
+│   ├── emails/
+│   │   ├── welcome.hbs
+│   │   └── reset-password.hbs
+│   └── pdfs/
+│       └── invoice.hbs
+│
+├── tests/                     # Test files
+│   ├── unit/
+│   │   └── services/
+│   ├── integration/
+│   │   └── routes/
+│   └── fixtures/
+│       └── factories.ts
+│
+├── app.ts                     # Express app setup
+├── server.ts                  # Server entry point
+└── index.ts                   # Main entry
+```
+
+### Architecture Flow
+
+```
+Request → Route → Middleware → Controller → Service → Repository → Database
+                      ↓
+              (auth, validation, rate-limit)
+```
+
+| Layer | Folder | Responsibility |
+|-------|--------|---------------|
+| **Presentation** | `app/` | HTTP handling |
+| **Business** | `domain/` | Business logic |
+| **Infrastructure** | `infrastructure/` | External services |
+| **Shared** | `shared/` | Cross-cutting concerns |
+
+### Import Rules
+
+```typescript
+// ✅ Correct dependency direction
+// Presentation → Business → Infrastructure
+// All layers → Shared
+
+// app/ can import from:
+import { userService } from '@/domain/services';
+import { AppError } from '@/shared/errors';
+
+// domain/ can import from:
+import { db } from '@/infrastructure/database';
+import { redis } from '@/infrastructure/cache';
+
+// ❌ Never import backwards
+// domain/ should NEVER import from app/
+// infrastructure/ should NEVER import from domain/
+```
+
+### Folder Decision Guide
+
+| Question | Folder |
+|----------|--------|
+| Handles HTTP request/response? | `app/controllers/` |
+| Contains business rules? | `domain/services/` |
+| Talks to database? | `domain/repositories/` |
+| Connects to external service? | `infrastructure/` |
+| Used everywhere? | `shared/` |
+| Runs on schedule? | `jobs/` |
+| Processes async work? | `infrastructure/queue/` |
+
+---
+
+## Code Patterns
+
+### Controller (Thin)
+
+```typescript
+// src/controllers/user.controller.ts
+export const getUser = asyncHandler(async (req: Request, res: Response) => {
+  const user = await userService.findById(req.params.id);
+  res.json({ success: true, data: user });
+});
+```
+
+### Service (Business Logic)
+
+```typescript
+// src/services/user.service.ts
+class UserService {
+  async findById(id: string) {
+    const user = await userRepository.findById(id);
+    if (!user) throw new AppError('User not found', 404, 'USER_NOT_FOUND');
+    return user;
+  }
+
+  async create(data: CreateUserInput) {
+    const existing = await userRepository.findByEmail(data.email);
+    if (existing) throw new AppError('Email in use', 409, 'EMAIL_CONFLICT');
+    
+    const hashed = await bcrypt.hash(data.password, 12);
+    return userRepository.create({ ...data, password: hashed });
+  }
+}
+```
+
+### Repository (Data Access)
+
+```typescript
+// src/repositories/user.repository.ts
+class UserRepository {
+  findById(id: string) {
+    return db.user.findUnique({ where: { id } });
+  }
+  
+  findByEmail(email: string) {
+    return db.user.findUnique({ where: { email } });
+  }
+  
+  create(data: Prisma.UserCreateInput) {
+    return db.user.create({ data });
+  }
+}
+```
+
+---
+
+## API Response Envelope
+
+```typescript
+// Success
+res.json({ success: true, data: user });
+res.json({ success: true, data: users, pagination: { page, limit, total } });
+
+// Error
+res.status(400).json({
+  success: false,
+  error: { code: 'VALIDATION_ERROR', message: 'Email is required' }
+});
+```
+
+---
+
+## Input Validation
+
+```typescript
+// src/validators/user.validator.ts
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  email: z.string().email().max(255),
+  name: z.string().min(2).max(100),
+  password: z.string().min(8).max(128),
+});
+
+// Middleware
+export function validate(schema: z.ZodSchema) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      throw new AppError('Validation failed', 422, 'VALIDATION_ERROR');
+    }
+    req.body = result.data;
+    next();
+  };
+}
+```
+
+---
+
+## Authentication
+
+```typescript
+// middleware/authenticate.ts
+export async function authenticate(req: Request, res: Response, next: NextFunction) {
+  const token = req.headers.authorization?.split(' ')[1];
+  if (!token) throw new AppError('Unauthorized', 401, 'NO_TOKEN');
+  
+  try {
+    req.user = jwt.verify(token, process.env.JWT_SECRET!) as JwtPayload;
+    next();
+  } catch {
+    throw new AppError('Invalid token', 401, 'INVALID_TOKEN');
+  }
+}
+```
+
+---
+
+## Background Jobs (BullMQ)
+
+```typescript
+// src/queues/email.queue.ts
+export const emailQueue = new Queue('email', {
+  connection: redis,
+  defaultJobOptions: {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 2000 },
+    removeOnComplete: 100,
+    removeOnFail: 500,
+  },
+});
+
+// Add job
+await emailQueue.add('welcome', { userId, email });
+
+// Worker
+const worker = new Worker('email', async (job) => {
+  await sendEmail(job.data);
+}, { connection: redis });
+```
+
+---
+
+## Security Checklist
+
+- [ ] All inputs validated with Zod
+- [ ] Queries parameterized (Prisma)
+- [ ] Auth on protected routes
+- [ ] Rate limiting on sensitive endpoints
+- [ ] No secrets in code
+- [ ] Passwords hashed (bcrypt >= 12)
+- [ ] JWT expiry enforced
+
+## Quality Checklist
+
+- [ ] Error handling complete
+- [ ] Logging added (Pino)
+- [ ] Tests written (unit + integration)
+- [ ] OpenAPI annotations added
+- [ ] N+1 queries prevented
+
+---
+
+## Red Flags
+
+Stop and reconsider if you're:
+
+- Putting business logic in controllers
+- Using raw SQL instead of Prisma
+- Not validating inputs
+- Catching errors without proper handling
+- Hardcoding configuration
+- Skipping authentication
+
+---
+
+## Collaboration
+
+| Works With | Handoff |
+|------------|---------|
+| **Systems Architect** | Receives architecture decisions |
+| **Frontend Developer** | Provides API contracts |
+| **QA Engineer** | Provides testable endpoints |
+| **Security Auditor** | Receives security reviews |
+
+---
+
+## When to Invoke
+
+- Building API endpoints
+- Database schema design
+- Service layer implementation
+- Background job setup
+- Authentication/authorization
+- Performance optimization (queries, caching)