create-rigel 0.1.0

package/templates/express/scripts/openapi.export.ts

@@ -0,0 +1,77 @@
+/**
+ * OpenAPI exporter — the single machine-readable contract for the harness family.
+ *
+ * The whole harness shares one response envelope, one error-code enum, and one
+ * cursor format (see .claude/rules/api.md). This script turns the Zod schemas +
+ * route registrations into an OpenAPI 3.1 document that the Next.js frontend
+ * consumes via `openapi-fetch` — so the contract is generated, never hand-synced
+ * across backend and frontend.
+ *
+ * How it works:
+ *   - Routes/schemas register themselves into an OpenAPIRegistry exported from
+ *     `src/runtime/openapi.ts` (created by /infra-setup; products add paths there).
+ *   - This script imports that registry if it exists, generates the document, and
+ *     writes docs/generated/openapi.json + openapi.yaml.
+ *   - If the registry is absent (fresh template, pre-/infra-setup) it emits a
+ *     minimal-but-valid base document so the pipeline + CI drift-check still work.
+ *
+ * Run: `npm run openapi:export`  (CI runs it and fails if the committed doc drifts).
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { OpenApiGeneratorV31, OpenAPIRegistry } from '@asteasolutions/zod-to-openapi'
+import { stringify as yamlStringify } from 'yaml'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const repoRoot = resolve(here, '..')
+const OUT_DIR = resolve(repoRoot, 'docs/generated')
+
+/**
+ * Pull the product's populated registry from src/runtime/openapi.ts when present.
+ * Falls back to an empty registry so the template (no src/ yet) still produces a
+ * valid base document.
+ */
+async function loadRegistry(): Promise<OpenAPIRegistry> {
+  const candidates = [
+    resolve(repoRoot, 'dist/runtime/openapi.js'),
+    resolve(repoRoot, 'src/runtime/openapi.ts'),
+  ]
+  for (const file of candidates) {
+    if (!existsSync(file)) continue
+    const mod = (await import(pathToFileURL(file).href)) as { registry?: OpenAPIRegistry }
+    if (mod.registry) return mod.registry
+  }
+  return new OpenAPIRegistry()
+}
+
+async function main(): Promise<void> {
+  const registry = await loadRegistry()
+  const generator = new OpenApiGeneratorV31(registry.definitions)
+
+  const document = generator.generateDocument({
+    openapi: '3.1.0',
+    info: {
+      title: process.env.SERVICE_NAME ?? 'harness-service',
+      version: process.env.APP_VERSION ?? '0.0.1',
+      description:
+        'Generated contract. Canonical response envelope + error-code enum are identical across the harness family — see .claude/rules/api.md.',
+    },
+    servers: [{ url: '/api/v1' }],
+  })
+
+  mkdirSync(OUT_DIR, { recursive: true })
+  const json = `${JSON.stringify(document, null, 2)}\n`
+  writeFileSync(resolve(OUT_DIR, 'openapi.json'), json)
+  writeFileSync(resolve(OUT_DIR, 'openapi.yaml'), yamlStringify(document))
+
+  const pathCount = Object.keys(document.paths ?? {}).length
+  // eslint-disable-next-line no-console -- this is a build script, not app code
+  console.log(`openapi: wrote ${pathCount} path(s) to docs/generated/openapi.{json,yaml}`)
+}
+
+main().catch((err: unknown) => {
+  // eslint-disable-next-line no-console -- build script
+  console.error('openapi export failed:', err)
+  process.exit(1)
+})

package/templates/express/tests/architecture/isolation.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Cross-user isolation contract — mechanical enforcement of the invariant in
+ * ARCHITECTURE.md (Repo layer): a resource owned by user A must be invisible to
+ * user B (the API responds 404, never 403).
+ *
+ * For every repo that enforces ownership (a userId-scoped query), an isolation
+ * integration test MUST exist at `tests/integration/<resource>.isolation.test.ts`.
+ * This replaces the old "copy isolation.test.template.ts by hand" honor system:
+ * the suite fails CI if an owned resource ships without its isolation test.
+ *
+ * Fresh repos (no src/repo yet) pass; the check tightens as repos appear.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const REPO_DIR = 'src/repo'
+const INTEGRATION_DIR = 'tests/integration'
+
+// A repo enforces ownership if it scopes queries by the owning user — the harness
+// pattern is `findByIdAndUser` / `where: { ..., userId }`.
+const OWNERSHIP_RE = /findByIdAndUser|userId|user_id/
+
+/** Resource base names (e.g. "application") for repos that enforce ownership. */
+function ownedResources(): string[] {
+  if (!existsSync(REPO_DIR)) return []
+  const out: string[] = []
+  for (const file of readdirSync(REPO_DIR)) {
+    if (!file.endsWith('.repo.ts')) continue
+    const src = readFileSync(join(REPO_DIR, file), 'utf8')
+    if (OWNERSHIP_RE.test(src)) out.push(file.replace(/\.repo\.ts$/, ''))
+  }
+  return out
+}
+
+describe('architecture: cross-user isolation contract', () => {
+  const resources = ownedResources()
+
+  if (resources.length === 0) {
+    it('no owned resources yet — isolation contract not applicable', () => {
+      expect(resources).toEqual([])
+    })
+  } else {
+    it.each(resources)(
+      'owned resource "%s" must ship its tests/integration/<resource>.isolation.test.ts',
+      (resource) => {
+        const expected = join(INTEGRATION_DIR, `${resource}.isolation.test.ts`)
+        expect(existsSync(expected)).toBe(true)
+      }
+    )
+  }
+})

package/templates/express/tests/architecture/layers.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Architecture structural tests — enforce the layer import boundaries from
+ * ARCHITECTURE.md mechanically. These run in CI and in the gate-checker.
+ *
+ * Circular-import detection is handled separately by `npx madge --circular`
+ * (see .claude/agents/gate-checker.md). This file enforces the *direction* of
+ * allowed imports: a lower layer must never import from a higher one.
+ *
+ * Layers that do not exist yet (fresh repo, mid-build) are skipped, so this
+ * suite passes immediately after /infra-setup and tightens as layers appear.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SRC = 'src'
+
+/** Recursively collect every .ts file under a directory. */
+function tsFiles(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  const out: string[] = []
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) out.push(...tsFiles(full))
+    else if (entry.endsWith('.ts')) out.push(full)
+  }
+  return out
+}
+
+/** Extract the specifier from every `import ... from '...'` / `require('...')`. */
+function importSpecifiers(file: string): string[] {
+  const src = readFileSync(file, 'utf8')
+  const specs: string[] = []
+  const re = /(?:from\s+|require\(\s*)['"]([^'"]+)['"]/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(src)) !== null) { if (m[1] !== undefined) specs.push(m[1]) }
+  return specs
+}
+
+/** True if any file in `layerDir` imports something matching a forbidden layer. */
+function findViolations(layerDir: string, forbidden: string[]): string[] {
+  const violations: string[] = []
+  for (const file of tsFiles(join(SRC, layerDir))) {
+    for (const spec of importSpecifiers(file)) {
+      for (const bad of forbidden) {
+        if (spec.includes(`/${bad}/`) || spec.includes(`/${bad}`) || spec === bad) {
+          violations.push(`${file} imports forbidden layer "${bad}" via "${spec}"`)
+        }
+      }
+    }
+  }
+  return violations
+}
+
+describe('architecture: layer import boundaries', () => {
+  it('types imports nothing from other layers', () => {
+    const v = findViolations('types', ['config', 'models', 'repo', 'services', 'runtime', 'providers', 'utils'])
+    expect(v).toEqual([])
+  })
+
+  it('config imports only from types', () => {
+    const v = findViolations('config', ['models', 'repo', 'services', 'runtime', 'providers'])
+    expect(v).toEqual([])
+  })
+
+  it('repo does not import from service or runtime', () => {
+    const v = findViolations('repo', ['services', 'runtime'])
+    expect(v).toEqual([])
+  })
+
+  it('service does not import express, runtime, or providers', () => {
+    const v = findViolations('services', ['runtime', 'providers'])
+    const expressImports = tsFiles(join(SRC, 'services')).filter((f) =>
+      importSpecifiers(f).some((s) => s === 'express')
+    )
+    expect(v).toEqual([])
+    expect(expressImports).toEqual([])
+  })
+
+  it('utils has zero domain imports', () => {
+    const v = findViolations('utils', ['config', 'models', 'repo', 'services', 'runtime', 'providers'])
+    expect(v).toEqual([])
+  })
+})

package/templates/express/tests/integration/health.test.ts

@@ -0,0 +1,40 @@
+/**
+ * EXAMPLE integration test — the model for runtime/route tests.
+ *
+ * Activates once /infra-setup generates `src/runtime/app.ts` with the health
+ * routes. Demonstrates the supertest HTTP-contract pattern: hit the real
+ * Express app, assert status + the canonical response envelope.
+ *
+ * `/health`  — liveness: process is up (always 200, no dependencies)
+ * `/ready`   — readiness: DB ping + Redis ping (200 when both reachable)
+ */
+import request from 'supertest'
+import { app } from '../../src/runtime/app.js'
+
+describe('GET /health', () => {
+  it('returns 200 (liveness — no dependencies)', async () => {
+    const res = await request(app).get('/health')
+    expect(res.status).toBe(200)
+  })
+
+  it('returns the canonical success envelope', async () => {
+    const res = await request(app).get('/health')
+    expect(res.body.ok).toBe(true)
+    expect(res.body).toHaveProperty('data')
+    expect(res.body).toHaveProperty('meta.requestId')
+  })
+
+  it('propagates the X-Request-ID header', async () => {
+    const res = await request(app).get('/health').set('X-Request-ID', 'test-req-id')
+    expect(res.body.meta.requestId).toBe('test-req-id')
+  })
+})
+
+describe('GET /ready', () => {
+  it('returns 200 when dependencies are reachable', async () => {
+    const res = await request(app).get('/ready')
+    // 200 healthy, 503 when a dependency is down — both are valid contract responses
+    expect([200, 503]).toContain(res.status)
+    expect(res.body).toHaveProperty('ok')
+  })
+})

package/templates/express/tests/integration/isolation.test.template.ts

@@ -0,0 +1,88 @@
+/**
+ * TEMPLATE — Cross-User Isolation Test (the most important security test).
+ *
+ * This file is named `*.template.ts` so Jest does NOT run it (the matcher is
+ * `*.test.ts`). For every user-owned resource, COPY this to
+ * `tests/integration/<resource>.isolation.test.ts` (where <resource> matches the
+ * repo base name, e.g. `application.repo.ts` → `application.isolation.test.ts`),
+ * replace the placeholders, and make it pass.
+ *
+ * This is ENFORCED, not optional: `tests/architecture/isolation.test.ts` fails CI
+ * for any repo that scopes queries by userId but has no matching isolation test.
+ *
+ * The invariant (ARCHITECTURE.md, Repo layer):
+ *   A resource owned by user A must be invisible to user B. When B requests A's
+ *   resource, the API responds 404 — NEVER 403. A 403 confirms the resource
+ *   exists; a 404 reveals nothing.
+ *
+ * Replace:
+ *   - `/api/v1/applications`     → your resource route
+ *   - `createApplication(...)`   → your create helper / factory
+ *   - `validBody`                → a valid create payload
+ *   - `authTokenFor(userId)`     → your test auth-token helper
+ */
+import request from 'supertest'
+import { app } from '../../src/runtime/app.js'
+// import { authTokenFor, createUser, resetDb } from './setup.js'
+
+describe('cross-user isolation: applications', () => {
+  let userA: string
+  let userB: string
+  let tokenA: string
+  let tokenB: string
+  let resourceId: string
+
+  beforeAll(async () => {
+    // await resetDb()
+    // userA = (await createUser('a@example.com')).id
+    // userB = (await createUser('b@example.com')).id
+    // tokenA = authTokenFor(userA)
+    // tokenB = authTokenFor(userB)
+
+    // User A creates a resource
+    const created = await request(app)
+      .post('/api/v1/applications')
+      .set('Authorization', `Bearer ${tokenA}`)
+      .send(/* validBody */ {})
+    resourceId = created.body.data.id
+  })
+
+  it("user B cannot READ user A's resource (404, not 403)", async () => {
+    const res = await request(app)
+      .get(`/api/v1/applications/${resourceId}`)
+      .set('Authorization', `Bearer ${tokenB}`)
+    expect(res.status).toBe(404)
+    expect(res.body.ok).toBe(false)
+  })
+
+  it("user B cannot UPDATE user A's resource (404)", async () => {
+    const res = await request(app)
+      .patch(`/api/v1/applications/${resourceId}`)
+      .set('Authorization', `Bearer ${tokenB}`)
+      .send({ note: 'hijack attempt' })
+    expect(res.status).toBe(404)
+  })
+
+  it("user B cannot DELETE user A's resource (404)", async () => {
+    const res = await request(app)
+      .delete(`/api/v1/applications/${resourceId}`)
+      .set('Authorization', `Bearer ${tokenB}`)
+    expect(res.status).toBe(404)
+  })
+
+  it("user A's resource never appears in user B's list", async () => {
+    const res = await request(app)
+      .get('/api/v1/applications')
+      .set('Authorization', `Bearer ${tokenB}`)
+    const ids = (res.body.data.items as Array<{ id: string }>).map((r) => r.id)
+    expect(ids).not.toContain(resourceId)
+  })
+
+  it('user A (the owner) can still read their own resource (200)', async () => {
+    const res = await request(app)
+      .get(`/api/v1/applications/${resourceId}`)
+      .set('Authorization', `Bearer ${tokenA}`)
+    expect(res.status).toBe(200)
+    expect(res.body.data.id).toBe(resourceId)
+  })
+})

package/templates/express/tests/load/smoke.js

@@ -0,0 +1,46 @@
+/**
+ * k6 SMOKE test — minimal load, run on every change / before a release.
+ * Goal: confirm the service is up and fast under light traffic.
+ *
+ *   k6 run tests/load/smoke.js
+ *   k6 run --env BASE_URL=https://staging.example.com --env AUTH_TOKEN=xyz tests/load/smoke.js
+ *
+ * Runs out of the box against /health (no auth, exists after /infra-setup).
+ * Copy the commented block to exercise a real authenticated endpoint per feature.
+ *
+ * Thresholds: P95 < 500ms, error rate < 1%.
+ */
+import http from 'k6/http'
+import { check, sleep } from 'k6'
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000'
+const AUTH_TOKEN = __ENV.AUTH_TOKEN || ''
+
+export const options = {
+  vus: 10,
+  duration: '30s',
+  thresholds: {
+    http_req_duration: ['p(95)<500'],
+    http_req_failed: ['rate<0.01'],
+  },
+}
+
+export default function () {
+  // --- Liveness: always available, no auth ---
+  const health = http.get(`${BASE_URL}/health`)
+  check(health, {
+    'health: status 200': (r) => r.status === 200,
+    'health: ok=true': (r) => r.json('ok') === true,
+    'health: < 500ms': (r) => r.timings.duration < 500,
+  })
+
+  // --- Authenticated feature path (copy & adapt per feature) ---
+  // const headers = { Authorization: `Bearer ${AUTH_TOKEN}`, 'Content-Type': 'application/json' }
+  // const list = http.get(`${BASE_URL}/api/v1/applications`, { headers })
+  // check(list, {
+  //   'list: status 200': (r) => r.status === 200,
+  //   'list: has data': (r) => r.json('data') !== undefined,
+  // })
+
+  sleep(1)
+}

package/templates/express/tests/load/soak.js

@@ -0,0 +1,45 @@
+/**
+ * k6 SOAK test — sustained moderate load over a long window. Catches memory
+ * leaks, connection-pool exhaustion, and slow degradation.
+ *
+ *   k6 run --env BASE_URL=https://staging.example.com tests/load/soak.js
+ *   k6 run --env DURATION=2h --env BASE_URL=... tests/load/soak.js
+ *
+ * Default duration is 30m (override with --env DURATION). Runs out of the box
+ * against /health. Copy the commented block for real endpoints.
+ *
+ * Thresholds: P95 < 800ms, error rate < 2% — must hold steady for the whole run.
+ */
+import http from 'k6/http'
+import { check, sleep } from 'k6'
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000'
+const AUTH_TOKEN = __ENV.AUTH_TOKEN || ''
+const DURATION = __ENV.DURATION || '30m'
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 20 }, // ramp to moderate load
+    { duration: DURATION, target: 20 }, // hold steady (the soak)
+    { duration: '2m', target: 0 }, // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<800'],
+    http_req_failed: ['rate<0.02'],
+  },
+}
+
+export default function () {
+  const health = http.get(`${BASE_URL}/health`)
+  check(health, {
+    'health: status 200': (r) => r.status === 200,
+    'health: ok=true': (r) => r.json('ok') === true,
+  })
+
+  // --- Authenticated feature path (copy & adapt per feature) ---
+  // const headers = { Authorization: `Bearer ${AUTH_TOKEN}`, 'Content-Type': 'application/json' }
+  // const list = http.get(`${BASE_URL}/api/v1/applications`, { headers })
+  // check(list, { 'list: status 200': (r) => r.status === 200 })
+
+  sleep(1)
+}

package/templates/express/tests/load/stress.js

@@ -0,0 +1,44 @@
+/**
+ * k6 STRESS test — find the breaking point. Run before a release / capacity planning.
+ * Ramps virtual users up to 100 and holds, then ramps down.
+ *
+ *   k6 run --env BASE_URL=https://staging.example.com --env AUTH_TOKEN=xyz tests/load/stress.js
+ *
+ * Runs out of the box against /health. Copy the commented block for real endpoints.
+ *
+ * Thresholds: P95 < 1000ms, P99 < 2000ms, error rate < 5%.
+ */
+import http from 'k6/http'
+import { check, sleep } from 'k6'
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000'
+const AUTH_TOKEN = __ENV.AUTH_TOKEN || ''
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 25 }, // warm up
+    { duration: '2m', target: 50 }, // ramp to moderate load
+    { duration: '2m', target: 100 }, // ramp to peak
+    { duration: '3m', target: 100 }, // hold at peak
+    { duration: '1m', target: 0 }, // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<1000', 'p(99)<2000'],
+    http_req_failed: ['rate<0.05'],
+  },
+}
+
+export default function () {
+  const health = http.get(`${BASE_URL}/health`)
+  check(health, {
+    'health: status 200': (r) => r.status === 200,
+    'health: < 1000ms': (r) => r.timings.duration < 1000,
+  })
+
+  // --- Authenticated feature path (copy & adapt per feature) ---
+  // const headers = { Authorization: `Bearer ${AUTH_TOKEN}`, 'Content-Type': 'application/json' }
+  // const list = http.get(`${BASE_URL}/api/v1/applications`, { headers })
+  // check(list, { 'list: status 200': (r) => r.status === 200 })
+
+  sleep(1)
+}

package/templates/express/tests/unit/utils/response.util.test.ts

@@ -0,0 +1,53 @@
+/**
+ * EXAMPLE unit test — the model for utils-layer tests (100% coverage required).
+ *
+ * Activates once /infra-setup generates `src/utils/response.util.ts`. It pins
+ * the canonical response envelope (see .claude/rules/api.md):
+ *   ok(data, requestId)        → { ok: true,  data, meta: { requestId, timestamp } }
+ *   err(code, message, reqId)  → { ok: false, error: { code, message }, meta: { requestId } }
+ *
+ * Utils tests must cover every branch and edge case — no exceptions.
+ */
+import { ok, err } from '../../../src/utils/response.util.js'
+
+describe('response.util — ok()', () => {
+  it('wraps data with ok: true and the request id', () => {
+    const res = ok({ id: 'abc' }, 'req-123')
+    expect(res.ok).toBe(true)
+    expect(res.data).toEqual({ id: 'abc' })
+    expect(res.meta.requestId).toBe('req-123')
+  })
+
+  it('includes an ISO timestamp in meta', () => {
+    const res = ok({ id: 'abc' }, 'req-123')
+    expect(typeof res.meta.timestamp).toBe('string')
+    expect(() => new Date(res.meta.timestamp).toISOString()).not.toThrow()
+  })
+
+  it('preserves array payloads without mutation', () => {
+    const items = [1, 2, 3]
+    const res = ok(items, 'req-123')
+    expect(res.data).toBe(items)
+  })
+
+  it('handles null data', () => {
+    const res = ok(null, 'req-123')
+    expect(res.ok).toBe(true)
+    expect(res.data).toBeNull()
+  })
+})
+
+describe('response.util — err()', () => {
+  it('wraps an error with ok: false and the canonical shape', () => {
+    const res = err('NOT_FOUND', 'Application not found', 'req-456')
+    expect(res.ok).toBe(false)
+    expect(res.error.code).toBe('NOT_FOUND')
+    expect(res.error.message).toBe('Application not found')
+    expect(res.meta.requestId).toBe('req-456')
+  })
+
+  it('never leaks a data field on errors', () => {
+    const res = err('INTERNAL_ERROR', 'boom', 'req-456')
+    expect(res).not.toHaveProperty('data')
+  })
+})

package/templates/express/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests", "scripts", "**/*.test.ts", "**/*.spec.ts"]
+}

package/templates/express/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*", "scripts/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}