create-simone-app 0.1.0

package/templates/api/base/test/orders.test.ts

@@ -0,0 +1,82 @@
+import request from 'supertest'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { createApp } from '../src/app'
+import {
+  ordersRepository,
+  productsRepository,
+  usersRepository,
+} from '../src/data/repository'
+
+const app = createApp()
+const pick = <T>(rows: readonly T[], i: number): T => {
+  const row = rows[i]
+  if (!row) throw new Error('empty fixture')
+  return row
+}
+
+describe('POST /api/orders', () => {
+  beforeEach(() => ordersRepository.reset())
+
+  it('creates an order with server-side prices and total → 201', async () => {
+    const user = pick(usersRepository.all(), 0)
+    const p1 = pick(productsRepository.all(), 0)
+    const p2 = pick(productsRepository.all(), 1)
+    const res = await request(app)
+      .post('/api/orders')
+      .send({
+        userId: user.id,
+        items: [
+          { productId: p1.id, qty: 2 },
+          { productId: p2.id, qty: 1 },
+        ],
+      })
+    expect(res.status).toBe(201)
+    expect(res.body).toMatchObject({
+      userId: user.id,
+      items: [
+        { productId: p1.id, qty: 2, unitPrice: p1.price },
+        { productId: p2.id, qty: 1, unitPrice: p2.price },
+      ],
+      total: Math.round((p1.price * 2 + p2.price) * 100) / 100,
+    })
+    expect(res.body.id).toMatch(/^[0-9a-f-]{36}$/)
+    expect(ordersRepository.all()).toHaveLength(11)
+  })
+
+  it('qty < 1 → 422', async () => {
+    const user = pick(usersRepository.all(), 0)
+    const p1 = pick(productsRepository.all(), 0)
+    const res = await request(app)
+      .post('/api/orders')
+      .send({ userId: user.id, items: [{ productId: p1.id, qty: 0 }] })
+    expect(res.status).toBe(422)
+    expect(res.body.details[0].path).toBe('items.0.qty')
+  })
+
+  it('empty items → 422', async () => {
+    const res = await request(app)
+      .post('/api/orders')
+      .send({ userId: 'x', items: [] })
+    expect(res.status).toBe(422)
+  })
+
+  it('unknown user → 404', async () => {
+    const p1 = pick(productsRepository.all(), 0)
+    const res = await request(app)
+      .post('/api/orders')
+      .send({ userId: 'ghost', items: [{ productId: p1.id, qty: 1 }] })
+    expect(res.status).toBe(404)
+    expect(res.body).toEqual({ error: 'User ghost not found' })
+  })
+
+  it('unknown product → 404, nothing persisted', async () => {
+    const user = pick(usersRepository.all(), 0)
+    const res = await request(app)
+      .post('/api/orders')
+      .send({ userId: user.id, items: [{ productId: 'ghost', qty: 1 }] })
+    expect(res.status).toBe(404)
+    expect(res.body).toEqual({ error: 'Product ghost not found' })
+    expect(ordersRepository.all()).toHaveLength(10)
+  })
+})

package/templates/api/base/test/products.test.ts

@@ -0,0 +1,54 @@
+import request from 'supertest'
+import { describe, expect, it } from 'vitest'
+
+import { createApp } from '../src/app'
+import { productsRepository } from '../src/data/repository'
+
+const app = createApp()
+
+describe('GET /api/products', () => {
+  it('returns the list contract with all 20 products', async () => {
+    const res = await request(app).get('/api/products')
+    expect(res.status).toBe(200)
+    expect(res.body).toMatchObject({ page: 1, limit: 20, total: 20 })
+  })
+
+  it('category filters', async () => {
+    const category = productsRepository.all()[0]?.category
+    if (!category) throw new Error('empty fixture')
+    const res = await request(app).get(`/api/products?category=${category}`)
+    expect(res.body.total).toBe(
+      productsRepository.all().filter((p) => p.category === category).length,
+    )
+    for (const p of res.body.data) expect(p.category).toBe(category)
+  })
+
+  it('unknown category → 422', async () => {
+    const res = await request(app).get('/api/products?category=weapons')
+    expect(res.status).toBe(422)
+    expect(res.body.details[0].path).toBe('category')
+  })
+
+  it('sort=-price sorts numerically descending', async () => {
+    const res = await request(app).get('/api/products?sort=-price')
+    const prices: number[] = res.body.data.map(
+      (p: { price: number }) => p.price,
+    )
+    expect(prices).toEqual([...prices].sort((a, b) => b - a))
+  })
+})
+
+describe('GET /api/products/:id', () => {
+  it('returns the product', async () => {
+    const target = productsRepository.all()[3]
+    if (!target) throw new Error('empty fixture')
+    const res = await request(app).get(`/api/products/${target.id}`)
+    expect(res.body).toEqual(target)
+  })
+
+  it('unknown id → 404', async () => {
+    const res = await request(app).get('/api/products/nope')
+    expect(res.status).toBe(404)
+    expect(res.body).toEqual({ error: 'Product nope not found' })
+  })
+})

package/templates/api/base/test/repository.test.ts

@@ -0,0 +1,45 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  ordersRepository,
+  productsRepository,
+  usersRepository,
+} from '../src/data/repository'
+
+describe('repository', () => {
+  beforeEach(() => ordersRepository.reset())
+
+  it('loads the committed fixtures', () => {
+    expect(usersRepository.all()).toHaveLength(50)
+    expect(productsRepository.all()).toHaveLength(20)
+    expect(ordersRepository.all()).toHaveLength(10)
+  })
+
+  it('findById returns the row or undefined', () => {
+    const first = usersRepository.all()[0]
+    if (!first) throw new Error('empty fixture')
+    expect(usersRepository.findById(first.id)).toEqual(first)
+    expect(usersRepository.findById('missing')).toBeUndefined()
+  })
+
+  it('insert validates and reset reloads the fixture', () => {
+    const order = ordersRepository.all()[0]
+    if (!order) throw new Error('empty fixture')
+    ordersRepository.insert({
+      ...order,
+      id: 'b2c3d4e5-0000-4000-8000-000000000000',
+    })
+    expect(ordersRepository.all()).toHaveLength(11)
+    expect(() => ordersRepository.insert({ ...order, total: -1 })).toThrow()
+    ordersRepository.reset()
+    expect(ordersRepository.all()).toHaveLength(10)
+  })
+
+  it('orders reference existing users and products', () => {
+    for (const order of ordersRepository.all()) {
+      expect(usersRepository.findById(order.userId)).toBeDefined()
+      for (const item of order.items)
+        expect(productsRepository.findById(item.productId)).toBeDefined()
+    }
+  })
+})

package/templates/api/base/test/smoke.test.ts

@@ -0,0 +1,7 @@
+import { describe, expect, it } from 'vitest'
+
+describe('smoke', () => {
+  it('runs under vitest', () => {
+    expect(1 + 1).toBe(2)
+  })
+})

package/templates/api/base/test/stats.test.ts

@@ -0,0 +1,40 @@
+import request from 'supertest'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { createApp } from '../src/app'
+import {
+  ordersRepository,
+  productsRepository,
+  usersRepository,
+} from '../src/data/repository'
+
+const app = createApp()
+
+describe('GET /api/stats', () => {
+  beforeEach(() => ordersRepository.reset())
+
+  it('counts, revenue and top category from the fixtures', async () => {
+    const res = await request(app).get('/api/stats')
+    expect(res.status).toBe(200)
+    expect(res.body).toMatchObject({ users: 50, products: 20, orders: 10 })
+    const revenue =
+      Math.round(
+        ordersRepository.all().reduce((s, o) => s + o.total, 0) * 100,
+      ) / 100
+    expect(res.body.revenue).toBe(revenue)
+    expect(productsRepository.all().map((p) => p.category)).toContain(
+      res.body.topCategory,
+    )
+  })
+
+  it('reflects new orders', async () => {
+    const user = usersRepository.all()[0]
+    const product = productsRepository.all()[0]
+    if (!user || !product) throw new Error('empty fixture')
+    await request(app)
+      .post('/api/orders')
+      .send({ userId: user.id, items: [{ productId: product.id, qty: 1 }] })
+    const res = await request(app).get('/api/stats')
+    expect(res.body.orders).toBe(11)
+  })
+})

package/templates/api/base/test/users.test.ts

@@ -0,0 +1,84 @@
+import request from 'supertest'
+import { describe, expect, it } from 'vitest'
+
+import { createApp } from '../src/app'
+import { usersRepository } from '../src/data/repository'
+
+const app = createApp()
+
+describe('GET /api/users', () => {
+  it('defaults to page 1, limit 20 and returns the list contract', async () => {
+    const res = await request(app).get('/api/users')
+    expect(res.status).toBe(200)
+    expect(res.body).toMatchObject({ page: 1, limit: 20, total: 50 })
+    expect(res.body.data).toHaveLength(20)
+  })
+
+  it('paginates', async () => {
+    const res = await request(app).get('/api/users?page=3&limit=20')
+    expect(res.body.data).toHaveLength(10)
+    expect(res.body.page).toBe(3)
+  })
+
+  it('q filters by name or email, case-insensitive', async () => {
+    const target = usersRepository.all()[0]
+    if (!target) throw new Error('empty fixture')
+    const res = await request(app).get(
+      `/api/users?q=${encodeURIComponent(target.email.toUpperCase())}`,
+    )
+    expect(res.status).toBe(200)
+    expect(res.body.total).toBeGreaterThanOrEqual(1)
+    expect(res.body.data.map((u: { id: string }) => u.id)).toContain(target.id)
+  })
+
+  it('q with no match → empty data, total 0', async () => {
+    const res = await request(app).get('/api/users?q=zzzzzzzzzz')
+    expect(res.body).toMatchObject({ data: [], total: 0 })
+  })
+
+  it('sort=-name sorts descending', async () => {
+    const res = await request(app).get('/api/users?sort=-name&limit=100')
+    const names: string[] = res.body.data.map((u: { name: string }) => u.name)
+    expect(names).toEqual([...names].sort((a, b) => b.localeCompare(a)))
+  })
+
+  it('sort=createdAt sorts ascending', async () => {
+    const res = await request(app).get('/api/users?sort=createdAt&limit=100')
+    const dates: string[] = res.body.data.map(
+      (u: { createdAt: string }) => u.createdAt,
+    )
+    expect(dates).toEqual([...dates].sort())
+  })
+
+  it('limit > 100 → 422', async () => {
+    const res = await request(app).get('/api/users?limit=101')
+    expect(res.status).toBe(422)
+    expect(res.body.error).toBe('Invalid query')
+    expect(res.body.details[0].path).toBe('limit')
+  })
+
+  it('unknown sort field → 422', async () => {
+    const res = await request(app).get('/api/users?sort=password')
+    expect(res.status).toBe(422)
+  })
+})
+
+describe('GET /api/users/:id', () => {
+  it('returns the user', async () => {
+    const target = usersRepository.all()[5]
+    if (!target) throw new Error('empty fixture')
+    const res = await request(app).get(`/api/users/${target.id}`)
+    expect(res.status).toBe(200)
+    expect(res.body).toEqual(target)
+  })
+
+  it('unknown id → 404 typed', async () => {
+    const res = await request(app).get(
+      '/api/users/00000000-0000-4000-8000-000000000000',
+    )
+    expect(res.status).toBe(404)
+    expect(res.body).toEqual({
+      error: 'User 00000000-0000-4000-8000-000000000000 not found',
+    })
+  })
+})

package/templates/api/base/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "lib": ["ESNext"],
+    "types": ["bun"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src", "test", "scripts", "*.ts", "eslint.config.js"]
+}

package/templates/api/base/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+    env: { LOG_LEVEL: 'silent' },
+    // CI runners can stall the first supertest request; 5s is too tight for a cold process.
+    testTimeout: 15_000,
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+      exclude: ['src/server.ts'],
+      thresholds: { lines: 80, functions: 80, branches: 80, statements: 80 },
+    },
+  },
+})

package/templates/api/variants/features/no-github-ci/variant.json

@@ -0,0 +1 @@
+{ "remove": [".github"] }

package/templates/api/variants/framework/express/docs/agents/framework-express.md

@@ -0,0 +1,9 @@
+## Backend conventions (Express 5)
+
+- `src/app.ts` exports `createApp()` (no listen); `src/server.ts` listens on `PORT` (default 4000). Tests mount `createApp()` on supertest.
+- One folder per module in `src/modules/<name>/` with `<name>.schema.ts` (zod), `<name>.repository.ts`, `<name>.router.ts`.
+- Errors: throw `HttpError(status, message, details?)` from `src/lib/http-error.ts`; `errorHandler` renders `{ error, details? }`. Unknown errors → 500 without leaking the message.
+- Input: wrap handlers in `validate({ query, body, params }, handler)` from `src/middleware/validate.ts`; invalid input → 422 `{ error: 'Invalid query', details: [{ path, message }] }`.
+- Status codes: 200 read, 201 create, 404 missing resource, 422 validation, 500 unexpected. Nothing else without a reason in the commit body.
+- `src/` uses only `node:*` APIs (Vitest runs on Node); `Bun.*` is allowed in `scripts/` only.
+- `openapi.yaml` is hand-written and served parsed at `GET /docs.json`; update it in the same commit as the route.

package/templates/api/variants/framework/express/src/app.ts

@@ -0,0 +1,37 @@
+import cors from 'cors'
+import express, { type Express } from 'express'
+import helmet from 'helmet'
+import { pinoHttp } from 'pino-http'
+
+import { HttpError } from './lib/http-error'
+import { errorHandler } from './middleware/errorHandler'
+import { docsRouter } from './modules/docs/docs.router'
+import { healthRouter } from './modules/health/health.router'
+import { ordersRouter } from './modules/orders/orders.router'
+import { productsRouter } from './modules/products/products.router'
+import { statsRouter } from './modules/stats/stats.router'
+import { usersRouter } from './modules/users/users.router'
+
+/** Builds the app without listening: tests mount it on supertest, server.ts on a port. */
+export const createApp = (): Express => {
+  const app = express()
+
+  app.use(helmet())
+  app.use(cors())
+  app.use(express.json())
+  app.use(pinoHttp({ level: process.env.LOG_LEVEL ?? 'info' }))
+
+  app.use('/api/health', healthRouter)
+  app.use('/api/users', usersRouter)
+  app.use('/api/products', productsRouter)
+  app.use('/api/orders', ordersRouter)
+  app.use('/api/stats', statsRouter)
+  app.use('/docs.json', docsRouter)
+
+  app.use((req, _res, next) => {
+    next(new HttpError(404, `Route ${req.method} ${req.path} not found`))
+  })
+  app.use(errorHandler)
+
+  return app
+}

package/templates/api/variants/framework/express/src/middleware/errorHandler.ts

@@ -0,0 +1,13 @@
+import type { ErrorRequestHandler } from 'express'
+
+import { HttpError } from '../lib/http-error'
+
+/** Last middleware: stable error shape `{ error, details? }`. Unknown errors → 500. */
+export const errorHandler: ErrorRequestHandler = (err, req, res, _next) => {
+  if (err instanceof HttpError) {
+    res.status(err.status).json({ error: err.message, details: err.details })
+    return
+  }
+  req.log?.error(err)
+  res.status(500).json({ error: 'Internal Server Error' })
+}

package/templates/api/variants/framework/express/src/middleware/validate.ts

@@ -0,0 +1,59 @@
+import type { Request, RequestHandler, Response } from 'express'
+import type { ZodType } from 'zod'
+
+import { HttpError } from '../lib/http-error'
+
+interface Schemas<Q, B, P> {
+  query?: ZodType<Q>
+  body?: ZodType<B>
+  params?: ZodType<P>
+}
+
+export interface Validated<Q, B, P> {
+  query: Q
+  body: B
+  params: P
+}
+
+type Handler<Q, B, P> = (
+  input: Validated<Q, B, P>,
+  req: Request,
+  res: Response,
+) => Promise<void> | void
+
+const parse = <T>(
+  schema: ZodType<T> | undefined,
+  raw: unknown,
+  where: string,
+): T => {
+  if (!schema) return raw as T
+  const result = schema.safeParse(raw)
+  if (result.success) return result.data
+  throw new HttpError(
+    422,
+    `Invalid ${where}`,
+    result.error.issues.map((i) => ({
+      path: i.path.join('.'),
+      message: i.message,
+    })),
+  )
+}
+
+/**
+ * Validates query/body/params with zod and hands the typed result to the handler.
+ * Invalid input → 422 `{ error: 'Invalid query', details: [{ path, message }] }`.
+ * Express 5 makes `req.query` read-only, so the parsed values travel via `input`.
+ */
+export const validate =
+  <Q = unknown, B = unknown, P = unknown>(
+    schemas: Schemas<Q, B, P>,
+    handler: Handler<Q, B, P>,
+  ): RequestHandler =>
+  async (req, res) => {
+    const input: Validated<Q, B, P> = {
+      query: parse(schemas.query, req.query, 'query'),
+      body: parse(schemas.body, req.body, 'body'),
+      params: parse(schemas.params, req.params, 'params'),
+    }
+    await handler(input, req, res)
+  }

package/templates/api/variants/framework/express/src/modules/docs/docs.router.ts

@@ -0,0 +1,15 @@
+import { Router } from 'express'
+import { readFileSync } from 'node:fs'
+import { parse } from 'yaml'
+
+// openapi.yaml is hand-written; parsed once at startup with `yaml` (no native YAML import).
+// node:fs, not Bun.file: Vitest runs src/ on Node, Bun APIs stay in scripts/.
+const spec: unknown = parse(
+  readFileSync(new URL('../../../openapi.yaml', import.meta.url), 'utf8'),
+)
+
+export const docsRouter = Router()
+
+docsRouter.get('/', (_req, res) => {
+  res.json(spec)
+})

package/templates/api/variants/framework/express/src/modules/health/health.router.ts

@@ -0,0 +1,7 @@
+import { Router } from 'express'
+
+export const healthRouter = Router()
+
+healthRouter.get('/', (_req, res) => {
+  res.json({ status: 'ok', uptime: process.uptime() })
+})

package/templates/api/variants/framework/express/src/modules/orders/orders.router.ts

@@ -0,0 +1,14 @@
+import { Router } from 'express'
+
+import { validate } from '../../middleware/validate'
+import { createOrder } from './orders.repository'
+import { CreateOrderBodySchema } from './orders.schema'
+
+export const ordersRouter = Router()
+
+ordersRouter.post(
+  '/',
+  validate({ body: CreateOrderBodySchema }, ({ body }, _req, res) => {
+    res.status(201).json(createOrder(body))
+  }),
+)

package/templates/api/variants/framework/express/src/modules/products/products.router.ts

@@ -0,0 +1,24 @@
+import { Router } from 'express'
+
+import { notFound } from '../../lib/http-error'
+import { validate } from '../../middleware/validate'
+import { findProduct, searchProducts } from './products.repository'
+import { ProductIdParamsSchema, ProductsQuerySchema } from './products.schema'
+
+export const productsRouter = Router()
+
+productsRouter.get(
+  '/',
+  validate({ query: ProductsQuerySchema }, ({ query }, _req, res) => {
+    res.json(searchProducts(query))
+  }),
+)
+
+productsRouter.get(
+  '/:id',
+  validate({ params: ProductIdParamsSchema }, ({ params }, _req, res) => {
+    const product = findProduct(params.id)
+    if (!product) throw notFound('Product', params.id)
+    res.json(product)
+  }),
+)

package/templates/api/variants/framework/express/src/modules/stats/stats.router.ts

@@ -0,0 +1,9 @@
+import { Router } from 'express'
+
+import { computeStats } from './stats.repository'
+
+export const statsRouter = Router()
+
+statsRouter.get('/', (_req, res) => {
+  res.json(computeStats())
+})

package/templates/api/variants/framework/express/src/modules/users/users.router.ts

@@ -0,0 +1,24 @@
+import { Router } from 'express'
+
+import { notFound } from '../../lib/http-error'
+import { validate } from '../../middleware/validate'
+import { findUser, searchUsers } from './users.repository'
+import { UserIdParamsSchema, UsersQuerySchema } from './users.schema'
+
+export const usersRouter = Router()
+
+usersRouter.get(
+  '/',
+  validate({ query: UsersQuerySchema }, ({ query }, _req, res) => {
+    res.json(searchUsers(query))
+  }),
+)
+
+usersRouter.get(
+  '/:id',
+  validate({ params: UserIdParamsSchema }, ({ params }, _req, res) => {
+    const user = findUser(params.id)
+    if (!user) throw notFound('User', params.id)
+    res.json(user)
+  }),
+)

package/templates/api/variants/framework/express/src/server.ts

@@ -0,0 +1,8 @@
+import { createApp } from './app'
+import { APP_NAME } from './lib/appName'
+
+const port = Number(process.env.PORT ?? 4000)
+
+createApp().listen(port, () => {
+  console.log(`${APP_NAME} listening on http://localhost:${port}`)
+})