create-simone-app 0.1.0

package/templates/api/base/TASK.md.template

@@ -0,0 +1,30 @@
+# Task: <title>
+
+## Goal
+
+<one sentence: what changes for the API consumer>
+
+## Context
+
+- Files: <src/modules/…, test/…, openapi.yaml>
+- Related rules: <docs/ai-rules/… §…>
+
+## Increments
+
+| # | What | Files | Verify | Commit |
+|---|---|---|---|---|
+| 1 | | | `bunx vitest run test/….test.ts` | `feat(scope): …` |
+| 2 | | | | |
+
+## Definition of done
+
+- [ ] `bun run verify` green on every commit
+- [ ] `openapi.yaml` updated
+- [ ] New routes covered: happy path, 422, 404
+- [ ] `git log --oneline` shows one commit per increment
+
+## Deviations from ai-rules
+
+| Rule § | Deviation | Why |
+|---|---|---|
+| | | |

package/templates/api/base/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+coverage
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store

package/templates/api/base/docs/agents/base.md

@@ -0,0 +1,54 @@
+# __NAME__
+
+Mock REST API (Bun + Express 5 + Zod) used as the backend for `simone-fe-template`
+and as the `api/base` pilot of the `create-simone-app` generator. Standalone: no auth,
+no database, no OIDC (not included on purpose).
+
+## Commands
+
+| Command                              | What                                                                                                 |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `bun run dev`                        | watch mode on :4000                                                                                  |
+| `bun run verify`                     | typecheck + lint + format + AGENTS check + tests (coverage ≥80%) — must be green before every commit |
+| `bun run test:watch`                 | Vitest watch                                                                                         |
+| `bun run seed:regen`                 | regenerate `src/data/*.json` (faker, seed 42, deterministic)                                         |
+| `bun run rules:sync` / `rules:check` | mirror ai-rules into `docs/ai-rules/` + `MANIFEST.json` / fail on drift                              |
+| `bun run agents:build`               | regenerate this file from `docs/agents/*.md` (never edit AGENTS.md by hand)                          |
+
+## Structure
+
+| Path                  | Role                                                                      |
+| --------------------- | ------------------------------------------------------------------------- |
+| `src/app.ts`          | `createApp()`: middleware + routers, no listen                            |
+| `src/server.ts`       | listen on `PORT` (4000)                                                   |
+| `src/lib/`            | `http-error.ts`, `pagination.ts` (`{ data, page, limit, total }`)         |
+| `src/middleware/`     | `validate.ts` (zod → 422), `errorHandler.ts` (`{ error, details? }`)      |
+| `src/modules/<name>/` | `*.schema.ts`, `*.repository.ts`, `*.router.ts` per module                |
+| `src/data/`           | `schemas.ts` (entity zod types), committed JSON fixtures, `repository.ts` |
+| `test/`               | one supertest file per module                                             |
+| `openapi.yaml`        | hand-written spec, served at `/docs.json`                                 |
+| `docs/ai-rules/`      | read-only mirror of company ai-rules (+ `MANIFEST.json`)                  |
+| `docs/agents/`        | fragments concatenated into `AGENTS.md`                                   |
+| `.agents/skills/`     | skills shared by Claude Code (`.claude/skills` symlink) and Codex         |
+
+## Workflow
+
+1. Copy `TASK.md.template` → `TASK.md`, split the work into small increments.
+2. Per increment: failing test → minimal code → `bun run verify` green → one Conventional Commit whose body explains _why_ (Italian body, English subject).
+3. New route = schema + repository + router + test + `openapi.yaml` entry, same commit.
+4. Never edit `docs/ai-rules/*`, `AGENTS.md`, `src/data/*.json` by hand (sync / build / regen instead).
+
+## Non-negotiables
+
+- Bun for everything (runtime, package manager, scripts). Vitest for tests (runs on Node → `src/` uses `node:*` only).
+- TypeScript strict + `noUncheckedIndexedAccess`. No `any`, `@ts-ignore`, `enum`, non-null `!`; use `unknown` + guards, `as const`.
+- ESLint 9 flat config with `no-duplicate-imports` + `consistent-type-imports` only; import order belongs to Prettier (`@trivago/prettier-plugin-sort-imports`).
+- Every list endpoint returns `{ data, page, limit, total }`; `limit` ≤ 100; `sort=-field` for descending, whitelisted fields.
+- Errors always `{ error, details? }` via `HttpError`; never leak internals on 500.
+- `data-testid` naming `feature-element-qualifier` (see `docs/ai-rules/testing-selectors.md`) applies to any HTML this API ever serves.
+
+## ai-rules
+
+| Topic                          | File                                 |
+| ------------------------------ | ------------------------------------ |
+| test selectors (`data-testid`) | `docs/ai-rules/testing-selectors.md` |

package/templates/api/base/eslint.config.js

@@ -0,0 +1,21 @@
+import js from '@eslint/js'
+import { defineConfig, globalIgnores } from 'eslint/config'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig(
+  globalIgnores(['node_modules', 'dist', 'coverage', 'docs/ai-rules']),
+  js.configs.recommended,
+  tseslint.configs.strict,
+  tseslint.configs.stylistic,
+  {
+    // core-rules §10.2: only these two import rules; ordering is Prettier's job (§10.1)
+    rules: {
+      'no-duplicate-imports': 'error',
+      '@typescript-eslint/consistent-type-imports': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+    },
+  },
+)

package/templates/api/base/openapi.yaml

@@ -0,0 +1,233 @@
+openapi: 3.1.0
+info:
+  title: __NAME__
+  version: 0.1.0
+  description: Mock REST API (Bun + Express 5 + Zod). List endpoints share the `{ data, page, limit, total }` contract.
+servers:
+  - url: http://localhost:4000
+paths:
+  /api/health:
+    get:
+      summary: Liveness
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status, uptime]
+                properties:
+                  status: { type: string, const: ok }
+                  uptime: { type: number }
+  /api/users:
+    get:
+      summary: List users
+      parameters:
+        - $ref: '#/components/parameters/page'
+        - $ref: '#/components/parameters/limit'
+        - name: q
+          in: query
+          description: Case-insensitive match on name or email
+          schema: { type: string }
+        - name: sort
+          in: query
+          description: One of name, email, role, createdAt; prefix with - for descending
+          schema: { type: string, pattern: '^-?(name|email|role|createdAt)$' }
+      responses:
+        '200':
+          description: Page of users
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Page'
+                  - type: object
+                    properties:
+                      data:
+                        {
+                          type: array,
+                          items: { $ref: '#/components/schemas/User' },
+                        }
+        '422': { $ref: '#/components/responses/Validation' }
+  /api/users/{id}:
+    get:
+      summary: Get user
+      parameters: [{ $ref: '#/components/parameters/id' }]
+      responses:
+        '200':
+          description: User
+          content:
+            {
+              application/json:
+                { schema: { $ref: '#/components/schemas/User' } },
+            }
+        '404': { $ref: '#/components/responses/NotFound' }
+  /api/products:
+    get:
+      summary: List products
+      parameters:
+        - $ref: '#/components/parameters/page'
+        - $ref: '#/components/parameters/limit'
+        - name: category
+          in: query
+          schema: { $ref: '#/components/schemas/Category' }
+        - name: sort
+          in: query
+          schema: { type: string, pattern: '^-?(name|category|price|stock)$' }
+      responses:
+        '200':
+          description: Page of products
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Page'
+                  - type: object
+                    properties:
+                      data:
+                        {
+                          type: array,
+                          items: { $ref: '#/components/schemas/Product' },
+                        }
+        '422': { $ref: '#/components/responses/Validation' }
+  /api/products/{id}:
+    get:
+      summary: Get product
+      parameters: [{ $ref: '#/components/parameters/id' }]
+      responses:
+        '200':
+          description: Product
+          content:
+            {
+              application/json:
+                { schema: { $ref: '#/components/schemas/Product' } },
+            }
+        '404': { $ref: '#/components/responses/NotFound' }
+  /api/orders:
+    post:
+      summary: Create order (prices resolved server-side)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [userId, items]
+              properties:
+                userId: { type: string }
+                items:
+                  type: array
+                  minItems: 1
+                  items:
+                    type: object
+                    required: [productId, qty]
+                    properties:
+                      productId: { type: string }
+                      qty: { type: integer, minimum: 1 }
+      responses:
+        '201':
+          description: Created order
+          content:
+            {
+              application/json:
+                { schema: { $ref: '#/components/schemas/Order' } },
+            }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '422': { $ref: '#/components/responses/Validation' }
+  /api/stats:
+    get:
+      summary: Aggregates
+      responses:
+        '200':
+          description: Counts, revenue and top category by revenue
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [users, products, orders, revenue, topCategory]
+                properties:
+                  users: { type: integer }
+                  products: { type: integer }
+                  orders: { type: integer }
+                  revenue: { type: number }
+                  topCategory: { type: [string, 'null'] }
+components:
+  parameters:
+    id: { name: id, in: path, required: true, schema: { type: string } }
+    page:
+      {
+        name: page,
+        in: query,
+        schema: { type: integer, minimum: 1, default: 1 },
+      }
+    limit:
+      {
+        name: limit,
+        in: query,
+        schema: { type: integer, minimum: 1, maximum: 100, default: 20 },
+      }
+  responses:
+    NotFound:
+      description: Resource not found
+      content:
+        { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
+    Validation:
+      description: Invalid input
+      content:
+        { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
+  schemas:
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error: { type: string }
+        details:
+          type: array
+          items:
+            type: object
+            properties: { path: { type: string }, message: { type: string } }
+    Page:
+      type: object
+      required: [data, page, limit, total]
+      properties:
+        data: { type: array }
+        page: { type: integer }
+        limit: { type: integer }
+        total: { type: integer }
+    Category: { type: string, enum: [books, electronics, garden, toys, food] }
+    User:
+      type: object
+      required: [id, name, email, role, createdAt]
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        email: { type: string, format: email }
+        role: { type: string, enum: [admin, editor, viewer] }
+        createdAt: { type: string, format: date-time }
+    Product:
+      type: object
+      required: [id, name, category, price, stock]
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        category: { $ref: '#/components/schemas/Category' }
+        price: { type: number }
+        stock: { type: integer }
+    Order:
+      type: object
+      required: [id, userId, items, total, createdAt]
+      properties:
+        id: { type: string, format: uuid }
+        userId: { type: string, format: uuid }
+        items:
+          type: array
+          items:
+            type: object
+            required: [productId, qty, unitPrice]
+            properties:
+              productId: { type: string, format: uuid }
+              qty: { type: integer }
+              unitPrice: { type: number }
+        total: { type: number }
+        createdAt: { type: string, format: date-time }

package/templates/api/base/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/server.ts",
+    "build": "bun build src/server.ts --outdir dist --target bun",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "verify": "bun run typecheck && bun run lint && bun run format:check && bun run agents:check && bun run test",
+    "rules:sync": "bun scripts/rules-sync.ts",
+    "rules:check": "bun scripts/rules-check.ts",
+    "seed:regen": "bun scripts/seed-regen.ts",
+    "agents:build": "bun scripts/agents-build.ts",
+    "agents:check": "bun scripts/agents-build.ts --check"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@faker-js/faker": "^10.6.0",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/bun": "^1.4.2",
+    "@types/supertest": "^7.2.1",
+    "@vitest/coverage-v8": "^5.0.1",
+    "eslint": "^9",
+    "prettier": "^3.9.8",
+    "supertest": "^7.2.2",
+    "typescript": "^5",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.1"
+  }
+}

package/templates/api/base/scripts/agents-build.ts

@@ -0,0 +1,26 @@
+import { join } from 'node:path'
+
+/** Fragment order, written by create-simone-app for the chosen variants. */
+const FRAGMENTS: string[] = await Bun.file('docs/agents/fragments.json').json()
+const OUT = 'AGENTS.md'
+const HEADER =
+  '<!-- Generated by `bun run agents:build` from docs/agents/*.md. Edit the fragments, not this file. -->\n\n'
+
+const parts = await Promise.all(
+  FRAGMENTS.map((name) => Bun.file(join('docs/agents', `${name}.md`)).text()),
+)
+const built = HEADER + parts.map((p) => p.trim()).join('\n\n') + '\n'
+
+if (process.argv.includes('--check')) {
+  const current = (await Bun.file(OUT).exists())
+    ? await Bun.file(OUT).text()
+    : ''
+  if (current !== built) {
+    console.error(`${OUT} is stale: run \`bun run agents:build\``)
+    process.exit(1)
+  }
+  console.log(`${OUT} up to date (${built.split('\n').length} lines)`)
+} else {
+  await Bun.write(OUT, built)
+  console.log(`wrote ${OUT} (${built.split('\n').length} lines)`)
+}

package/templates/api/base/scripts/rules-check.ts

@@ -0,0 +1,48 @@
+import { join } from 'node:path'
+
+import {
+  MANIFEST,
+  type Manifest,
+  RULES_DIR,
+  rulesSource,
+  sha256,
+} from './rules.config'
+
+const manifestFile = Bun.file(MANIFEST)
+if (!(await manifestFile.exists())) {
+  console.error(`${MANIFEST} missing: run \`bun run rules:sync\``)
+  process.exit(1)
+}
+const manifest: Manifest = await manifestFile.json()
+const source = rulesSource()
+const upstreamAvailable = await Bun.file(join(source, 'README.md')).exists()
+let failed = false
+
+for (const entry of manifest.files) {
+  const local = join(RULES_DIR, entry.file)
+  if (!(await Bun.file(local).exists())) {
+    console.error(`missing ${local}`)
+    failed = true
+    continue
+  }
+  if ((await sha256(local)) !== entry.sha256) {
+    console.error(`${local} differs from MANIFEST (edited by hand?)`)
+    failed = true
+  }
+  if (upstreamAvailable) {
+    const upstream = join(source, entry.source)
+    if ((await sha256(upstream)) !== entry.sha256) {
+      console.error(
+        `${entry.source} changed upstream: run \`bun run rules:sync\``,
+      )
+      failed = true
+    }
+  }
+}
+
+if (!upstreamAvailable)
+  console.warn(`ai-rules not found at ${source}: checked local integrity only`)
+if (failed) process.exit(1)
+console.log(
+  `ai-rules ok (${manifest.files.length} files, synced ${manifest.syncedAt})`,
+)

package/templates/api/base/scripts/rules-sync.ts

@@ -0,0 +1,35 @@
+import { mkdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+
+import {
+  MANIFEST,
+  type Manifest,
+  RULES,
+  RULES_DIR,
+  rulesSource,
+  sha256,
+} from './rules.config'
+
+const source = rulesSource()
+if (!(await Bun.file(join(source, 'README.md')).exists())) {
+  console.error(`ai-rules not found at ${source} (set AI_RULES_PATH)`)
+  process.exit(1)
+}
+
+await mkdir(RULES_DIR, { recursive: true })
+const manifest: Manifest = { syncedAt: new Date().toISOString(), files: [] }
+
+for (const rule of RULES) {
+  const from = join(source, rule)
+  const to = join(RULES_DIR, basename(rule))
+  await Bun.write(to, Bun.file(from))
+  manifest.files.push({
+    file: basename(rule),
+    source: rule,
+    sha256: await sha256(to),
+  })
+  console.log(`synced ${rule}`)
+}
+
+await Bun.write(MANIFEST, JSON.stringify(manifest, null, 2) + '\n')
+console.log(`wrote ${MANIFEST}`)

package/templates/api/base/scripts/rules.config.ts

@@ -0,0 +1,28 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** ai-rules files (relative to the ai-rules repo root) mirrored into docs/ai-rules. */
+export const RULES = ['frontend/testing-selectors.md'] as const
+
+export const RULES_DIR = 'docs/ai-rules'
+export const MANIFEST = join(RULES_DIR, 'MANIFEST.json')
+
+export const rulesSource = (): string =>
+  process.env.AI_RULES_PATH ?? join(homedir(), 'Progetti', 'ai-rules')
+
+export interface ManifestEntry {
+  file: string
+  source: string
+  sha256: string
+}
+
+export interface Manifest {
+  syncedAt: string
+  files: ManifestEntry[]
+}
+
+export const sha256 = async (path: string): Promise<string> => {
+  const hasher = new Bun.CryptoHasher('sha256')
+  hasher.update(await Bun.file(path).arrayBuffer())
+  return hasher.digest('hex')
+}

package/templates/api/base/scripts/seed-regen.ts

@@ -0,0 +1,64 @@
+import { faker } from '@faker-js/faker'
+
+import {
+  type Order,
+  PRODUCT_CATEGORIES,
+  type Product,
+  USER_ROLES,
+  type User,
+} from '../src/data/schemas'
+
+// Fixed seed + fixed ref date → identical fixtures on every run (fixtures are committed).
+faker.seed(42)
+faker.setDefaultRefDate('2026-01-01T00:00:00.000Z')
+
+const money = (n: number): number => Math.round(n * 100) / 100
+const pastDate = (): string =>
+  faker.date
+    .between({
+      from: '2024-01-01T00:00:00.000Z',
+      to: '2025-12-31T23:59:59.000Z',
+    })
+    .toISOString()
+
+const users: User[] = Array.from({ length: 50 }, () => {
+  const firstName = faker.person.firstName()
+  const lastName = faker.person.lastName()
+  return {
+    id: faker.string.uuid(),
+    name: `${firstName} ${lastName}`,
+    email: faker.internet.email({ firstName, lastName }).toLowerCase(),
+    role: faker.helpers.arrayElement(USER_ROLES),
+    createdAt: pastDate(),
+  }
+})
+
+const products: Product[] = Array.from({ length: 20 }, () => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  category: faker.helpers.arrayElement(PRODUCT_CATEGORIES),
+  price: money(Number(faker.commerce.price({ min: 5, max: 500 }))),
+  stock: faker.number.int({ min: 0, max: 200 }),
+}))
+
+const orders: Order[] = Array.from({ length: 10 }, () => {
+  const items = faker.helpers
+    .arrayElements(products, { min: 1, max: 4 })
+    .map((p) => ({
+      productId: p.id,
+      qty: faker.number.int({ min: 1, max: 5 }),
+      unitPrice: p.price,
+    }))
+  return {
+    id: faker.string.uuid(),
+    userId: faker.helpers.arrayElement(users).id,
+    items,
+    total: money(items.reduce((sum, i) => sum + i.qty * i.unitPrice, 0)),
+    createdAt: pastDate(),
+  }
+})
+
+for (const [name, rows] of Object.entries({ users, products, orders })) {
+  await Bun.write(`src/data/${name}.json`, JSON.stringify(rows, null, 2) + '\n')
+  console.log(`wrote src/data/${name}.json (${rows.length})`)
+}