@sundaysf/cli-v3 0.0.1

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@sundaysf/cli-v3",
+  "version": "0.0.1",
+  "description": "Sundays Framework v3 CLI - scaffolds an Express 5 + Knex + Postgres API and generates entity verticals",
+  "type": "module",
+  "bin": {
+    "sundaysf": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --exclude test/e2e",
+    "test:e2e": "SUNDAYS_E2E=1 vitest run test/e2e",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "sundays",
+    "scaffold",
+    "express",
+    "knex",
+    "cli"
+  ],
+  "author": "Pablo Dominguez",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "commander": "^15.0.0",
+    "execa": "^10.0.1",
+    "fs-extra": "^11.4.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^24.0.0",
+    "eslint": "^10.11.0",
+    "prettier": "^3.9.8",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.1"
+  }
+}

package/templates/api/.claude/agents/knex-table-implementer.md

@@ -0,0 +1,36 @@
+---
+name: knex-table-implementer
+description: Use this agent to add or change database tables in this Sundays Framework v3 project - migrations, interfaces, DAOs and the src/db barrel - following the project's Knex conventions. Examples - "add an order_item table", "add a nullable deletedAt column to product", "write a DAO method that lists products with their category".
+model: sonnet
+color: red
+---
+
+You are a database-layer specialist for a Sundays Framework v3 API (Knex 3 + PostgreSQL).
+Read `CLAUDE.md` first.
+
+## New table
+
+Run `sundaysf generate entity <name> <fields...>` (it writes the migration, interface, DAO, DTOs,
+controller, router, tests and barrel exports). Then refine the generated migration if needed.
+
+## Changing an existing table
+
+1. `npm run db:make-migration -- <verb>_<table>` creates `src/migrations/<timestamp>_<verb>_<table>.ts`.
+2. Implement `up` and `down` with the knex schema builder. Columns camelCase, tables snake_case,
+   foreign keys `.references('id').inTable('<table>').onDelete('CASCADE')` plus `.index()`.
+3. Update `src/db/interfaces/<x>/<x>.interfaces.ts` (`interface IX extends IEntity`).
+4. Add finders to `src/db/dao/<x>/<x>.dao.ts`. DAOs extend `BaseDAO<IX>`; use `this.q(trx)` for
+   the query builder and accept an optional `trx?: Knex.Transaction` on every method.
+   Relations: `leftJoin` + `this._knex.raw('to_jsonb(r.*) as related')`.
+5. If you create a new DAO or interface by hand, export them in `src/db/index.ts` above the
+   `// @sundays:daos` / `// @sundays:interfaces` markers.
+6. `npm run db:migrate`, then `npm run db:rollback && npm run db:migrate` to prove `down` works.
+7. Add or update tests under `src/db/dao/<x>/__tests__/` (real Postgres, clean up in `afterAll`).
+
+## Rules
+
+- Never edit an applied migration; write a new one.
+- Every table has `id` (increments), `uuid` (unique), `createdAt`, `updatedAt`
+  (`timestamp(...).notNullable().defaultTo(knex.fn.now())`).
+- Return `null` for not-found, never throw from a DAO for missing rows.
+- Keep `knexfile.ts` untouched: configuration lives in `src/db/knex.config.ts`.

package/templates/api/.claude/agents/sundays-backend-builder.md

@@ -0,0 +1,32 @@
+---
+name: sundays-backend-builder
+description: Use this agent to create or modify backend components (endpoints, controllers, routers, services, DTOs) in this Sundays Framework v3 project so they follow the project conventions exactly. Examples - "add a products API with CRUD", "add a POST /orders/:uuid/cancel endpoint", "this controller doesn't follow our standards, fix it".
+model: sonnet
+color: blue
+---
+
+You are a senior backend developer working on a Sundays Framework v3 API (Express 5 + TypeScript +
+Knex + PostgreSQL + Zod). Read `CLAUDE.md` first; it is the source of truth.
+
+## How you work
+
+1. **New entity?** Run `sundaysf generate entity <name> <fields...>` first, then adapt the output.
+   Never hand-write what the generator produces.
+2. **New endpoint on an existing entity?** Add the route in `src/routes/<x>/<x>.router.ts`
+   (`.bind()` the handler), the method in `src/controllers/<x>/<x>.controller.ts`, a DTO in
+   `src/dto/input/<x>/` when it takes a body, and DAO methods in `src/db/dao/<x>/<x>.dao.ts`.
+3. **Cross-cutting logic** (email, storage, external APIs) goes in `src/services/<x>/<x>.service.ts`.
+4. Write tests next to the code (`__tests__/`): unit test for the controller (mock `'../../../db'`),
+   route test with supertest when the endpoint touches the database.
+5. Finish with `npm run typecheck && npm run lint && npm test`.
+
+## Rules
+
+- Response envelope `{ success, data }` / `{ success, message, errors? }`; paginated lists return
+  `dao.getAll(page, limit)` directly.
+- Validation through Zod DTOs (`validateXCreate(req.body)`), never manual `if (!body.x)` checks.
+- Errors through `HttpError` helpers (`notFound`, `conflict`, `badRequest`, `unauthorized`), never
+  `res.status(500)` by hand; unexpected errors go to `next(err)`.
+- Public ids are `uuid`; resolve to numeric `id` before DAO writes.
+- Express 5 routing rules (no `*`, `{/:id}` for optional params).
+- No new dependencies without saying why.

package/templates/api/.env.example

@@ -0,0 +1,25 @@
+# ------------------------------------------------------------------------------
+# __SF_PROJECT_NAME__ - environment variables
+# Copy to .env (sundaysf new already did) and adjust. Never commit .env.
+# ------------------------------------------------------------------------------
+
+# Server
+PORT=__SF_PORT__
+NODE_ENV=development
+# pino level: fatal | error | warn | info | debug | trace | silent
+LOG_LEVEL=info
+# Comma separated list of allowed origins, or * for any
+CORS_ORIGINS=*
+
+# Database (matches docker-compose.yml)
+SQL_HOST=localhost
+SQL_PORT=5432
+SQL_USER=postgres
+SQL_PASSWORD=postgres
+SQL_DB_NAME=__SF_DB_NAME__
+# Set to false to accept self-signed certificates on remote hosts (SSL is off for localhost)
+SQL_REJECT_UNAUTHORIZED=true
+# Run pending migrations on boot (useful in containers). Default: false
+RUN_MIGRATIONS=false
+
+# @sundays:env

package/templates/api/.github/workflows/ci.yaml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    name: Typecheck, lint and test
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: __SF_DB_NAME__
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+    env:
+      NODE_ENV: test
+      SQL_HOST: localhost
+      SQL_PORT: 5432
+      SQL_USER: postgres
+      SQL_PASSWORD: postgres
+      SQL_DB_NAME: __SF_DB_NAME__
+      # @sundays:ci-env
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm run db:migrate
+      - run: npm test
+      - run: npm run build

package/templates/api/.github/workflows/deploy.yaml

@@ -0,0 +1,72 @@
+name: Deploy to AWS ECS
+
+# Manual deploy. Requires in the GitHub repo:
+#   secrets.AWS_ROLE_ARN   - IAM role assumed via OIDC (needs ECR push + ECS deploy)
+#   vars.AWS_REGION        - e.g. us-east-1
+# and, already created in AWS: an ECR repository, an ECS cluster/service and a task
+# definition, all named after the project (change the env block below if they differ).
+on:
+  workflow_dispatch:
+
+env:
+  AWS_REGION: ${{ vars.AWS_REGION || 'us-east-1' }}
+  ECR_REPOSITORY: __SF_PROJECT_SLUG__
+  ECS_CLUSTER: __SF_PROJECT_SLUG__
+  ECS_SERVICE: __SF_PROJECT_SLUG__
+  ECS_TASK_DEFINITION: __SF_PROJECT_SLUG__
+  CONTAINER_NAME: __SF_PROJECT_SLUG__
+
+jobs:
+  deploy:
+    name: Build, push and deploy
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Read package version
+        id: pkg
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Login to Amazon ECR
+        id: ecr
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Build, tag and push image
+        id: image
+        env:
+          REGISTRY: ${{ steps.ecr.outputs.registry }}
+          TAG: ${{ steps.pkg.outputs.version }}
+        run: |
+          docker build -t "$REGISTRY/$ECR_REPOSITORY:$TAG" .
+          docker tag "$REGISTRY/$ECR_REPOSITORY:$TAG" "$REGISTRY/$ECR_REPOSITORY:latest"
+          docker push "$REGISTRY/$ECR_REPOSITORY:$TAG"
+          docker push "$REGISTRY/$ECR_REPOSITORY:latest"
+          echo "image=$REGISTRY/$ECR_REPOSITORY:$TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Download current task definition
+        run: aws ecs describe-task-definition --task-definition "$ECS_TASK_DEFINITION" --query taskDefinition > task-definition.json
+
+      - name: Render new task definition
+        id: taskdef
+        uses: aws-actions/amazon-ecs-render-task-definition@v1
+        with:
+          task-definition: task-definition.json
+          container-name: ${{ env.CONTAINER_NAME }}
+          image: ${{ steps.image.outputs.image }}
+
+      - name: Deploy
+        uses: aws-actions/amazon-ecs-deploy-task-definition@v2
+        with:
+          task-definition: ${{ steps.taskdef.outputs.task-definition }}
+          service: ${{ env.ECS_SERVICE }}
+          cluster: ${{ env.ECS_CLUSTER }}
+          wait-for-service-stability: true

package/templates/api/.prettierignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+coverage/
+package-lock.json
+pnpm-lock.yaml

package/templates/api/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "bracketSameLine": true,
+  "arrowParens": "always"
+}

package/templates/api/.sundaysrc

@@ -0,0 +1,8 @@
+{
+  "runtime": "node",
+  "install": "npm install",
+  "build": "npm run build",
+  "start": "npm start",
+  "port": __SF_PORT__,
+  "cli": "__SF_CLI_VERSION__"
+}

package/templates/api/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository (an API generated by Sundays
+Framework v__SF_CLI_VERSION__).
+
+## Commands
+
+```bash
+npm run start:dev        # dev server with reload (tsx watch, no type-check)
+npm run typecheck        # tsc --noEmit (sources + tests)
+npm test                 # jest with coverage; routes/ and db/ suites need Postgres (docker compose up -d)
+npm run test:unit        # jest without database suites
+npm run lint             # eslint
+npm run format           # prettier
+npm run db:migrate       # apply src/migrations
+npm run db:rollback      # undo last batch
+npm run db:make-migration -- <name>
+npm run db:seed
+sundaysf generate entity <name> <fields...>   # scaffold a full entity (see below)
+```
+
+Before finishing any task run `npm run typecheck && npm run lint && npm test`.
+
+## Architecture
+
+Express 5 + TypeScript (CommonJS, ES2022) + Knex 3 + PostgreSQL. Layers, top to bottom:
+
+1. `src/routes/<x>/<x>.router.ts` — class with `public router: Router`; auto-mounted at
+   `/api/<x>` by `src/routes/index.ts` (folder name = mount path, no manual registration).
+2. `src/controllers/<x>/<x>.controller.ts` — class; one `async method(req, res, next)` per
+   endpoint wrapped in `try { } catch (err) { next(err) }`; DAOs as `private _xDAO = new XDAO()`.
+3. `src/dto/input/<x>/<x>.{create,update}.dto.ts` — Zod schema + `validateXCreate(input)` which
+   throws `HttpError(400)` with field errors.
+4. `src/services/<x>/<x>.service.ts` — cross-cutting logic (email, storage, tokens...).
+5. `src/db/dao/<x>/<x>.dao.ts` — `class XDAO extends BaseDAO<IX> { protected readonly table = 'x' }`
+   plus custom finders; `src/db/interfaces/<x>/<x>.interfaces.ts` — `interface IX extends IEntity`.
+6. `src/db/index.ts` — barrel. Import DAOs/types from `'../../db'`. Keep the
+   `// @sundays:interfaces` and `// @sundays:daos` markers: generators append above them.
+
+Boot: `src/server.ts` validates env (`src/common/config/env.ts`), connects `KnexManager`,
+optionally runs migrations (`RUN_MIGRATIONS=true`), then imports `src/app.ts` and listens.
+SIGTERM/SIGINT close the server and the pool.
+
+## Conventions (do not deviate)
+
+- Response envelope: `{ success: true, data }` / `{ success: false, message, errors? }`.
+  Paginated lists return `IDataPaginator` from `dao.getAll(page, limit)` as-is (already has `success`).
+- Public identifier is `uuid`; numeric `id` never leaves the API. Routes use `/:uuid`.
+- Table names snake_case, columns camelCase, every table has `id`, `uuid`, `createdAt`, `updatedAt`.
+- Migrations live in `src/migrations/` (TypeScript), named `<timestamp>_<verb>_<table>.ts`.
+- Pagination params via `getPagination(req.query)` (`src/common/utils/pagination.ts`).
+- Errors: `throw notFound('X not found')`, `conflict(...)`, `badRequest(...)`, `unauthorized(...)`
+  from `src/common/errors/http.error.ts`. Never `res.status(500)` by hand.
+- Logging: `req.log` inside handlers, `logger` (`src/common/logger`) elsewhere. No `console.*`.
+- New env vars go in the Zod schema in `src/common/config/env.ts`, `.env.example` and README.
+- Express 5 routing: no `*` (use `/*splat`), optional params `{/:id}`, no regex strings,
+  `req.query` is read-only, `req.body` is `undefined` when no parser matched.
+- Tests co-located in `__tests__/`: controller unit tests mock `'../../../db'` and use a
+  `mockRes()` helper; route tests use supertest + real Postgres and clean up in `afterAll`.
+- Keep coverage above the threshold in `jest.config.js`.
+
+## Adding an entity
+
+Always start with the generator, then adapt:
+
+```bash
+sundaysf generate entity product name:string:unique price:decimal categoryId:category.id isActive:boolean=true
+npm run db:migrate
+```
+
+Field syntax `name:type[?][:unique][=default]`; types `string text integer decimal boolean date
+datetime json uuid <entity>.id`. It creates migration, interface, DAO, DTOs, controller, router,
+unit test and route test, and updates `src/db/index.ts`. Add custom endpoints to the generated
+router/controller; add custom queries to the DAO using `this.q(trx)`.
+
+Transactions: `KnexManager.getConnection().transaction(async (trx) => { await dao.create(x, trx); })`.
+Relations: prefer `leftJoin` + `this._knex.raw('to_jsonb(r.*) as related')` inside the DAO.
+
+## Features in this project
+
+<!-- @sundays:features -->

package/templates/api/Dockerfile

@@ -0,0 +1,17 @@
+# ---- build stage ------------------------------------------------------------
+FROM node:24-alpine AS builder
+WORKDIR /var/api
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# ---- runtime stage ----------------------------------------------------------
+FROM node:24-alpine
+ENV NODE_ENV=production
+WORKDIR /var/api
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY --from=builder /var/api/dist ./dist
+EXPOSE __SF_PORT__
+CMD ["node", "dist/server.js"]

package/templates/api/README.md

@@ -0,0 +1,164 @@
+# **SF_PROJECT_NAME**
+
+REST API built with [Sundays Framework](https://github.com/sundaysf) v__SF_CLI_VERSION__:
+Express 5 · TypeScript · Knex · PostgreSQL · Zod · pino · Jest.
+
+## Quick start
+
+```bash
+npm install                 # once
+docker compose up -d        # local PostgreSQL 16 on port 5432
+npm run db:migrate          # apply migrations
+npm run start:dev           # http://localhost:__SF_PORT__/api/health (reloads on change)
+```
+
+`sundaysf new` already created `.env` from `.env.example`. Add a new entity with:
+
+```bash
+sundaysf generate entity product name:string:unique price:decimal isActive:boolean=true
+npm run db:migrate
+```
+
+## Scripts
+
+| Script                                | What it does                                                                                      |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `npm run start:dev`                   | Dev server with reload (`tsx watch`). Does not type-check: run `typecheck` or rely on the editor. |
+| `npm run build`                       | Compile `src/` to `dist/` with `tsc`.                                                             |
+| `npm start`                           | Run the compiled server (`node dist/server.js`).                                                  |
+| `npm run typecheck`                   | `tsc --noEmit` over sources and tests.                                                            |
+| `npm test`                            | Jest with coverage. Route and DB suites need the local Postgres.                                  |
+| `npm run test:unit`                   | Jest without the `routes/` and `db/` suites (no database needed).                                 |
+| `npm run test:watch`                  | Jest in watch mode.                                                                               |
+| `npm run lint` / `npm run format`     | ESLint / Prettier.                                                                                |
+| `npm run db:migrate`                  | Apply pending migrations from `src/migrations/`.                                                  |
+| `npm run db:rollback`                 | Roll back the last migration batch.                                                               |
+| `npm run db:status`                   | List applied and pending migrations.                                                              |
+| `npm run db:seed`                     | Run seeds from `src/seeds/`.                                                                      |
+| `npm run db:make-migration -- <name>` | Create `src/migrations/<timestamp>_<name>.ts`.                                                    |
+| `npm run db:make-seed -- <name>`      | Create `src/seeds/<name>.ts`.                                                                     |
+
+## Environment variables
+
+Validated at boot by `src/common/config/env.ts` (Zod). A missing or malformed value stops the
+process with a readable error. Add new variables to that schema, to `.env.example`, and here.
+
+| Variable                  | Default       | Description                                                               |
+| ------------------------- | ------------- | ------------------------------------------------------------------------- |
+| `PORT`                    | `__SF_PORT__` | HTTP port.                                                                |
+| `NODE_ENV`                | `development` | `development`, `test` or `production`. Pretty logs only in development.   |
+| `LOG_LEVEL`               | `info`        | pino level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`, `silent`. |
+| `CORS_ORIGINS`            | `*`           | Comma separated allowed origins, or `*`.                                  |
+| `SQL_HOST`                | `localhost`   | PostgreSQL host. SSL is disabled for localhost.                           |
+| `SQL_PORT`                | `5432`        | PostgreSQL port.                                                          |
+| `SQL_USER`                | -             | PostgreSQL user.                                                          |
+| `SQL_PASSWORD`            | -             | PostgreSQL password.                                                      |
+| `SQL_DB_NAME`             | -             | Database name.                                                            |
+| `SQL_REJECT_UNAUTHORIZED` | `true`        | Set `false` to accept self-signed certificates on remote hosts.           |
+| `RUN_MIGRATIONS`          | `false`       | Run pending migrations on boot (handy for containers).                    |
+
+<!-- @sundays:readme-env -->
+
+## Project layout
+
+```
+src/
+  server.ts                 boot: env -> db -> (migrations) -> app.listen, graceful shutdown
+  app.ts                    express: helmet, cors, request id, pino-http, parsers, /api, 404, errors
+  routes/
+    index.ts                auto-discovery: routes/<x>/<x>.router.ts is mounted at /api/<x>
+    <entity>/<entity>.router.ts
+  controllers/<entity>/<entity>.controller.ts
+  dto/input/<entity>/<entity>.{create,update}.dto.ts   Zod schemas + validate helpers
+  services/<name>/<name>.service.ts                    cross-cutting logic (email, s3, jwt...)
+  middlewares/<name>/<name>.middleware.ts
+  jobs/<name>.job.ts        cron jobs (export run() and schedule(); register schedule() in server.ts)
+  db/
+    index.ts                barrel with @sundays markers (generators append here)
+    BaseDAO.ts              generic CRUD + pagination + optional transaction
+    KnexConnection.ts       KnexManager singleton (connect / getConnection / disconnect)
+    knex.config.ts          the one knex config (also used by knexfile.ts for the CLI)
+    dao/<entity>/<entity>.dao.ts
+    interfaces/<entity>/<entity>.interfaces.ts
+  migrations/               knex migrations (TypeScript, compiled with the app)
+  seeds/
+  common/
+    config/env.ts           validated environment
+    logger/                 pino
+    errors/http.error.ts    HttpError + badRequest()/notFound()/... helpers
+    validation/parse-dto.ts parseDto(schema, input)
+    utils/                  pagination, version/environment resolvers
+```
+
+Every file has its tests next to it in a `__tests__/` folder.
+
+## Conventions
+
+- **Response envelope**: `{ success: true, data }` on success, `{ success: false, message, errors? }`
+  on failure. Paginated lists return `IDataPaginator`:
+  `{ success, data, page, limit, count, totalCount, totalPages }`.
+- **Ids**: tables have a numeric `id` (internal) and a `uuid` (public). Routes take `/:uuid`;
+  controllers resolve the row and use `id` for DAO writes.
+- **Columns** are camelCase (`createdAt`, `categoryId`); **tables** are snake_case (`product_category`).
+- **Controllers** are classes with `private _xDAO = new XDAO()` members and
+  `async method(req, res, next)` handlers wrapped in `try { } catch (err) { next(err) }`.
+- **Routers** are classes exposing `public router: Router` and bind handlers with `.bind()`.
+- **Validation**: `const input = validateProductCreate(req.body)` throws `HttpError(400)` with
+  per-field errors; the error middleware renders it.
+- **Errors**: throw `notFound('Product not found')`, `conflict(...)`, etc. from
+  `src/common/errors/http.error.ts`, or `next(err)` for anything else.
+- **Express 5**: no `*` wildcards (`/*splat`), optional params are `{/:id}`, `req.query` is read-only.
+
+## Adding an entity
+
+```bash
+sundaysf generate entity product \
+  name:string:unique price:decimal categoryId:category.id isActive:boolean=true description:text?
+```
+
+This writes the migration, interface, DAO, create/update DTOs, controller, router and tests, and
+registers the DAO in `src/db/index.ts`. Then:
+
+```bash
+npm run db:migrate
+npm run start:dev
+curl -X POST localhost:__SF_PORT__/api/product -H 'content-type: application/json' \
+  -d '{"name":"Widget","price":9.5,"categoryId":1}'
+npm test
+```
+
+Field syntax: `name:type[?][:unique][=default]` with types `string`, `text`, `integer`,
+`decimal`, `boolean`, `date`, `datetime`, `json`, `uuid` or `<entity>.id` (foreign key).
+
+## Endpoints
+
+### Health
+
+| Method | Path          | Response                                                      |
+| ------ | ------------- | ------------------------------------------------------------- |
+| GET    | `/api/health` | `{ success, health, version, environment, database, uptime }` |
+
+<!-- @sundays:readme-endpoints -->
+
+## Testing
+
+- `npm test` runs everything with coverage (threshold in `jest.config.js`). Route and DB suites
+  connect to the `SQL_*` database from `.env` and clean up what they create.
+- `npm run test:unit` skips them so you can test without Postgres.
+- `jest.setup.js` refuses to run against a non-local `SQL_HOST` unless `ALLOW_REMOTE_DB_TESTS=1`.
+- Controller unit tests mock the `src/db` barrel with `jest.mock('../../../db', ...)`; route tests
+  use `supertest` against `app` with a real database.
+
+## Deploy
+
+- `Dockerfile`: two-stage build on `node:24-alpine`, `EXPOSE __SF_PORT__`, runs `node dist/server.js`.
+  Set `RUN_MIGRATIONS=true` in the container to migrate on boot.
+- `.github/workflows/ci.yaml`: on every PR and push to `main` runs typecheck, lint, migrations,
+  tests and build against a Postgres service.
+- `.github/workflows/deploy.yaml`: manual deploy to AWS ECS (build → ECR → new task definition →
+  service update). Configure `secrets.AWS_ROLE_ARN` (OIDC) and `vars.AWS_REGION` in GitHub, and
+  adjust the resource names at the top of the file if they differ from `__SF_PROJECT_SLUG__`.
+
+## Claude Code
+
+`CLAUDE.md` and `.claude/agents/` describe the conventions above for AI-assisted development.

package/templates/api/_dockerignore

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

package/templates/api/_gitignore

@@ -0,0 +1,23 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Environment (only .env.example is versioned)
+.env
+.env.*
+!.env.example
+
+# Tests
+coverage/
+src/routes/__tests__/_fixtures-*/
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Logs
+*.log

package/templates/api/_package.json

@@ -0,0 +1,58 @@
+{
+  "name": "__SF_PROJECT_SLUG__",
+  "version": "0.1.0",
+  "description": "__SF_PROJECT_NAME__ API - generated with Sundays Framework v__SF_CLI_VERSION__",
+  "private": true,
+  "main": "dist/server.js",
+  "scripts": {
+    "start:dev": "tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "typecheck": "tsc --noEmit -p tsconfig.spec.json",
+    "test": "jest",
+    "test:unit": "jest --testPathIgnorePatterns '/routes/' '/db/'",
+    "test:watch": "jest --watch",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "db:migrate": "tsx node_modules/knex/bin/cli.js migrate:latest",
+    "db:rollback": "tsx node_modules/knex/bin/cli.js migrate:rollback",
+    "db:status": "tsx node_modules/knex/bin/cli.js migrate:status",
+    "db:seed": "tsx node_modules/knex/bin/cli.js seed:run",
+    "db:make-migration": "tsx node_modules/knex/bin/cli.js migrate:make -x ts",
+    "db:make-seed": "tsx node_modules/knex/bin/cli.js seed:make -x ts"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^18.0.1",
+    "express": "^5.2.1",
+    "helmet": "^8.3.0",
+    "knex": "^3.3.0",
+    "pg": "^8.23.0",
+    "pino": "^10.3.1",
+    "pino-http": "^11.0.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.0",
+    "@types/supertest": "^7.0.0",
+    "eslint": "^10.11.0",
+    "globals": "^16.0.0",
+    "jest": "^30.5.2",
+    "pino-pretty": "^13.1.3",
+    "prettier": "^3.9.8",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.12",
+    "tsx": "^4.23.15",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.70.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT"
+}