create-rigel 0.1.0

package/templates/express/.claude/rules/architecture.md

@@ -0,0 +1,78 @@
+---
+paths:
+  - "src/**/*.ts"
+---
+
+# Architecture Rules — Auto-injected on every src/ file edit
+
+## Import Order Enforcement
+
+Before writing any import, check which layer you are in:
+
+| Your file is in | You may import from |
+|---|---|
+| `src/types/` | Nothing |
+| `src/config/` | `src/types/` only |
+| `src/models/` | `src/types/`, `src/config/` |
+| `src/repo/` | `src/types/`, `src/config/`, `src/models/` |
+| `src/services/` | `src/types/`, `src/config/`, `src/repo/` |
+| `src/runtime/` | `src/types/`, `src/config/`, `src/repo/`, `src/services/` |
+| `src/utils/` | Nothing (zero domain imports) |
+| `src/providers/` | `src/types/`, `src/config/` only |
+
+**Any import that violates this table is a layer violation. Fix it before proceeding.**
+
+## The Checks You Must Pass
+
+### Types layer (`src/types/`)
+```typescript
+// ✅ Correct — pure interface, no imports
+export interface Application { id: string; stage: ApplicationStage }
+
+// ❌ Wrong — importing another layer
+import { env } from '../config/env'   // FORBIDDEN in types
+```
+
+### Config layer (`src/config/`)
+```typescript
+// ✅ Correct
+import { z } from 'zod'                    // third-party ok
+import type { Application } from '../types' // Types ok
+
+// ❌ Wrong
+import { userRepo } from '../repo/user.repo'  // FORBIDDEN
+```
+
+### Service layer (`src/services/`)
+```typescript
+// ✅ Correct — takes domain types, returns domain types
+export async function createApplication(userId: string, input: CreateApplicationInput): Promise<Application>
+
+// ❌ Wrong — HTTP types in service
+import { Request, Response } from 'express'   // FORBIDDEN
+import { HttpException } from '../runtime/...' // FORBIDDEN
+```
+
+### Runtime layer (`src/runtime/`)
+```typescript
+// ✅ Correct handler structure (THIS ORDER — every time)
+router.post('/applications', async (req, res, next) => {
+  try {
+    const auth = await requireAuth(req)                          // 1. Auth
+    const limited = await rateLimitMiddleware(req, 'USER_API')  // 2. Rate limit
+    if (limited) return res.status(429).json(limited)
+    const body = CreateApplicationSchema.parse(req.body)         // 3. Validate
+    const result = await applicationService.create(auth.userId, body) // 4. Service
+    return res.status(201).json(ok(result, req.requestId))       // 5. Respond
+  } catch (err) { next(err) }                                    // 6. Error handler
+})
+
+// ❌ Wrong — business logic in handler
+router.post('/applications', async (req, res) => {
+  if (req.body.stage === 'APPLIED') { ... }  // logic belongs in service
+})
+```
+
+## Structural Test
+`tests/architecture/layers.test.ts` imports madge and fails CI if any of these are violated.
+Run it: `npm run test:arch`

package/templates/express/.claude/rules/database.md

@@ -0,0 +1,104 @@
+---
+paths:
+  - "src/repo/**/*.ts"
+  - "src/models/**/*.ts"
+  - "db/migrations/**/*.js"
+---
+
+# Database Rules — Auto-injected on repo/model/migration edits
+
+## The 5 Checks Before Every Repo Method Ships
+
+### 1. Zod Parse on Every Result
+```typescript
+// ✅ REQUIRED
+const raw = await Application.findByPk(id)
+if (!raw) throw new NotFoundError(`Application ${id} not found`)
+return ApplicationSchema.parse(raw.toJSON())
+
+// ❌ FORBIDDEN — implicit trust of DB output
+return raw as Application
+```
+
+### 2. No N+1 — Eager Load Always
+```typescript
+// ✅ Single query
+const apps = await Application.findAll({
+  where: { userId },
+  include: [
+    { model: Note },
+    { model: Contact },
+    { model: Reminder },
+  ],
+})
+
+// ❌ N+1 — DB called inside loop
+const apps = await Application.findAll({ where: { userId } })
+for (const app of apps) {
+  app.notes = await Note.findAll({ where: { applicationId: app.id } }) // N queries
+}
+```
+
+### 3. Cursor Pagination on All List Methods
+```typescript
+// ✅ Cursor-based
+async function list(userId: string, cursor?: PageCursor, limit = 20) {
+  const where: WhereOptions = { userId }
+  if (cursor) {
+    where[Op.or] = [
+      { createdAt: { [Op.lt]: cursor.createdAt } },
+      { createdAt: cursor.createdAt, id: { [Op.lt]: cursor.id } },
+    ]
+  }
+  const rows = await Application.findAll({
+    where, order: [['createdAt', 'DESC'], ['id', 'DESC']], limit: limit + 1,
+  })
+  const hasMore = rows.length > limit
+  const items = hasMore ? rows.slice(0, limit) : rows
+  return {
+    items: items.map(r => ApplicationSchema.parse(r.toJSON())),
+    nextCursor: hasMore ? { id: items.at(-1)!.id, createdAt: items.at(-1)!.createdAt } : null,
+    hasMore,
+  }
+}
+
+// ❌ FORBIDDEN on tables > 10k rows
+Application.findAll({ offset: page * limit, limit })
+```
+
+### 4. Transactions for Multi-Table Writes
+```typescript
+// ✅ REQUIRED when writing > 1 table
+return sequelize.transaction(async (t) => {
+  await Application.update({ stage }, { where: { id }, transaction: t })
+  await Note.create({ applicationId: id, content, type: 'SYSTEM' }, { transaction: t })
+})
+
+// No external API calls inside a transaction
+```
+
+### 5. Soft Delete — paranoid: true
+```typescript
+// Model must have paranoid: true
+@Table({ tableName: 'applications', paranoid: true })
+export class Application extends Model { ... }
+
+// findAll automatically filters deleted — no manual where needed
+await Application.findAll({ where: { userId } })  // deleted_at IS NULL automatic
+
+// Explicit include-deleted (opt-in only)
+await Application.findAll({ where: { userId }, paranoid: false })
+```
+
+## Model Checklist (every new model)
+- [ ] `@Table({ paranoid: true })` — soft delete
+- [ ] `@Default(() => newId())` on id — UUIDv7
+- [ ] `indexes` array defined on `@Table`
+- [ ] FK columns have index
+- [ ] ORDER BY columns have index
+- [ ] Partial index for `WHERE deleted_at IS NULL` queries
+
+## Migration Checklist (every new migration)
+- [ ] New indexes use `CONCURRENTLY`
+- [ ] FK constraints defined with explicit `ON DELETE` behaviour
+- [ ] Both `up` and `down` implemented

package/templates/express/.claude/rules/jobs.md

@@ -0,0 +1,81 @@
+---
+paths:
+  - "src/runtime/workers/**/*.ts"
+---
+
+# Job Rules — Auto-injected on worker file edits
+
+## Worker Checklist (every worker file)
+
+### 1. Validate payload with Zod before touching it
+```typescript
+const worker = new Worker(QUEUES.REMINDER_EMAIL, async (job) => {
+  // ✅ REQUIRED — validate before processing
+  const payload = ReminderEmailJobSchema.parse(job.data)
+
+  // ❌ FORBIDDEN
+  const { reminderId } = job.data   // trusting unvalidated external data
+}, { connection: redis })
+```
+
+### 2. Structured logging — start, complete, failed
+```typescript
+const worker = new Worker(QUEUES.REMINDER_EMAIL, async (job) => {
+  const payload = ReminderEmailJobSchema.parse(job.data)
+  const start = Date.now()
+
+  logger.info({ event: 'job.start', jobId: job.id, queue: QUEUES.REMINDER_EMAIL })
+
+  try {
+    await reminderService.sendReminderEmail(payload)
+    logger.info({ event: 'job.complete', jobId: job.id, queue: QUEUES.REMINDER_EMAIL, durationMs: Date.now() - start })
+  } catch (err) {
+    logger.error({ event: 'job.failed', jobId: job.id, queue: QUEUES.REMINDER_EMAIL, err: (err as Error).message })
+    throw err  // re-throw so BullMQ handles retry
+  }
+}, { connection: redis, concurrency: 5 })
+```
+
+### 3. Retry config on queue definition
+```typescript
+// ✅ Define retry on the queue
+export const reminderQueue = new Queue(QUEUES.REMINDER_EMAIL, {
+  connection: redis,
+  defaultJobOptions: {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 5000 },
+    removeOnComplete: { count: 100 },
+    removeOnFail:     { count: 500 },
+  },
+})
+```
+
+### 4. Metrics
+```typescript
+worker.on('completed', (job) => {
+  metrics.increment('jobs.completed', { queue: QUEUES.REMINDER_EMAIL })
+})
+worker.on('failed', (job, err) => {
+  metrics.increment('jobs.failed', { queue: QUEUES.REMINDER_EMAIL })
+  logger.error({ event: 'job.failed', jobId: job?.id, err: err.message })
+})
+```
+
+### 5. Circuit breaker on external calls inside workers
+```typescript
+// Workers call external APIs (email, SMS, webhooks)
+// Always wrap with circuit breaker + retry
+const result = await withRetry(
+  () => emailBreaker.call(() => emailProvider.send(payload)),
+  { maxAttempts: 3, baseDelayMs: 1000, maxDelayMs: 10000, jitter: true }
+)
+```
+
+### 6. Graceful shutdown hook
+```typescript
+// Register in src/runtime/server.ts shutdown sequence
+async function shutdown() {
+  await reminderWorker.close()   // drain in-flight jobs
+  await reminderQueue.close()
+}
+```

package/templates/express/.claude/rules/security.md

@@ -0,0 +1,92 @@
+---
+paths:
+  - "src/runtime/**/*.ts"
+  - "src/repo/**/*.ts"
+---
+
+# Security Rules — Auto-injected on runtime and repo file edits
+
+## Runtime: Handler Security Checklist
+
+Every protected handler MUST follow this exact order:
+
+```typescript
+// 1. Auth FIRST — before anything else
+const auth = await requireAuth(req)  // throws UnauthorizedError if invalid
+
+// 2. Rate limit
+const limited = await checkRateLimit(req, 'USER_API')
+if (limited) return res.status(429).json(limited)
+
+// 3. Input validation — Zod, always
+const body = CreateApplicationSchema.parse(req.body)
+// Never: const body = req.body as CreateApplicationInput
+
+// 4. Call service with typed domain inputs
+const result = await applicationService.create(auth.userId, body)
+
+// 5. Respond with envelope
+return res.status(201).json(ok(result, req.requestId))
+```
+
+## Repo: Data Boundary Validation
+
+```typescript
+// ✅ REQUIRED — every query result
+const raw = await Application.findByPk(id)
+if (!raw) throw new NotFoundError(`Application ${id} not found`)
+return ApplicationSchema.parse(raw.toJSON())
+
+// ❌ FORBIDDEN — TypeScript lie
+return raw as Application
+return raw.toJSON() as Application
+```
+
+## SQL Injection Prevention
+
+```typescript
+// ✅ Safe — Sequelize parameterises automatically
+await Application.findAll({ where: { userId, stage } })
+
+// ✅ Safe — named replacements for raw queries
+await sequelize.query(
+  'SELECT * FROM applications WHERE user_id = :userId',
+  { replacements: { userId }, type: QueryTypes.SELECT }
+)
+
+// ❌ BLOCKED by ESLint — string interpolation
+await sequelize.query(`SELECT * FROM applications WHERE user_id = '${userId}'`)
+```
+
+## Auth Middleware — Never Inline
+
+```typescript
+// ✅ Always use the provider
+import { requireAuth } from '../../providers/auth/middleware'
+
+// ❌ Never roll your own inline JWT verification
+const token = req.headers.authorization?.split(' ')[1]
+const payload = jwt.verify(token, process.env.JWT_SECRET) // multiple violations
+```
+
+## Error Responses — Never Expose Internals
+
+```typescript
+// ✅ Correct — sanitised
+return next(new NotFoundError('Application not found'))
+// → errorHandler maps to: { error: { code: 'NOT_FOUND', message: 'Application not found' } }
+
+// ❌ Wrong — exposes internals
+res.status(500).json({ error: err.message, stack: err.stack })
+```
+
+## Ownership Enforcement in Repo
+
+```typescript
+// ✅ ALWAYS — user can only access their own resources
+await Application.findOne({ where: { id, userId } })         // userId from auth context
+await Application.findByPk(id, { where: { userId } })
+
+// ❌ NEVER — no ownership check
+await Application.findByPk(id)  // any user can access any application
+```

package/templates/express/.claude/rules/testing.md

@@ -0,0 +1,97 @@
+---
+paths:
+  - "tests/**/*.ts"
+  - "tests/**/*.test.ts"
+---
+
+# Testing Rules — Auto-injected on test file edits
+
+## Coverage Thresholds (enforced in CI — fail if below)
+
+| Layer | Threshold | What to test |
+|---|---|---|
+| `src/utils/` | **100%** | Every branch, every edge case |
+| `src/services/` | **90%** | Happy path + all error paths + state machine transitions |
+| `src/repo/` | **80%** | Query results, Zod parse, ownership, cursor pagination |
+| `src/runtime/routes/` | **75%** | Auth required, 422 validation, 404 not found |
+| `src/providers/` | **70%** | Core functionality |
+
+## Required Test Patterns
+
+### Service Tests — error paths are mandatory
+```typescript
+describe('applicationService.transitionStage', () => {
+  it('advances stage when transition is valid', async () => { ... })
+  it('throws StageTransitionError when transition is invalid', async () => {
+    await expect(applicationService.transitionStage(userId, appId, 'ACCEPTED'))
+      .rejects.toThrow(StageTransitionError)
+  })
+  it('throws TerminalStageError when application is already accepted', async () => { ... })
+  it('throws NotFoundError when application does not belong to user', async () => { ... })
+  it('creates system note in same transaction as stage update', async () => { ... })
+})
+```
+
+### Zod Schema Tests — malformed inputs
+```typescript
+describe('CreateApplicationSchema', () => {
+  it('rejects missing company', () => {
+    expect(() => CreateApplicationSchema.parse({ role: 'Engineer' })).toThrow()
+  })
+  it('rejects invalid stage value', () => {
+    expect(() => ApplicationSchema.parse({ ...valid, stage: 'PENDING' })).toThrow()
+  })
+})
+```
+
+### Route Tests — test the HTTP contract
+```typescript
+describe('POST /api/v1/applications', () => {
+  it('returns 401 without auth token', async () => {
+    const res = await request(app).post('/api/v1/applications').send(validBody)
+    expect(res.status).toBe(401)
+  })
+  it('returns 422 with invalid body', async () => {
+    const res = await request(app)
+      .post('/api/v1/applications')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ role: 'Engineer' })  // missing company
+    expect(res.status).toBe(422)
+  })
+  it('returns 201 with standard envelope', async () => {
+    const res = await request(app)
+      .post('/api/v1/applications')
+      .set('Authorization', `Bearer ${token}`)
+      .send(validBody)
+    expect(res.status).toBe(201)
+    expect(res.body).toHaveProperty('data')
+    expect(res.body).toHaveProperty('meta.requestId')
+  })
+})
+```
+
+### Architecture Tests — structural
+```typescript
+// tests/architecture/layers.test.ts
+// Uses madge to check import graph
+it('repo layer does not import from service or runtime', async () => {
+  const graph = await madge('src/repo/', { tsConfig: 'tsconfig.json' })
+  const deps = graph.obj()
+  const violations = Object.entries(deps)
+    .filter(([, imports]) => imports.some(i => i.includes('service') || i.includes('runtime')))
+  expect(violations).toHaveLength(0)
+})
+```
+
+### Cross-User Isolation Tests — mandatory for owned resources
+
+Every repo that scopes queries by `userId` (an owned resource) MUST ship
+`tests/integration/{resource}.isolation.test.ts` — copy `isolation.test.template.ts`.
+It proves user B gets **404 (not 403)** for user A's resource on read/update/delete/list.
+Enforced: `tests/architecture/isolation.test.ts` fails CI if the file is missing.
+
+## Test File Naming
+- Unit: `tests/unit/{layer}/{filename}.test.ts`
+- Integration: `tests/integration/{feature}.test.ts`
+- Isolation: `tests/integration/{resource}.isolation.test.ts` (required per owned resource)
+- Architecture: `tests/architecture/layers.test.ts`, `tests/architecture/isolation.test.ts`

package/templates/express/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "model": "claude-opus-4-8",
+  "permissions": {
+    "allow": [
+      "Bash(npm *)",
+      "Bash(npx *)",
+      "Bash(node *)",
+      "Bash(git *)",
+      "Bash(tsx *)",
+      "Bash(bash *)",
+      "Bash(sh *)",
+      "Bash(cat *)",
+      "Bash(ls *)",
+      "Bash(grep *)",
+      "Bash(find *)",
+      "Bash(wc *)",
+      "Bash(madge *)",
+      "Bash(k6 *)"
+    ],
+    "deny": []
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/post-write.sh"
+          }
+        ]
+      }
+    ]
+  }
+}