@raiyyan/brisk 0.0.0-stage → 0.2.0

package/starters/minimal/src/features/notes/notes.schema.ts

@@ -0,0 +1,24 @@
+import { z } from "@raiyyan/brisk";
+import { isoDate, PageQuery } from "../../schemas.ts";
+
+export const CreateNoteBody = z.object({
+  name: z.string().trim().min(1).max(200),
+});
+
+// Keep .default() out of the create schema: .partial() keeps defaults, and a PATCH would reset omitted fields.
+export const UpdateNoteBody = CreateNoteBody.partial();
+
+export const NoteIdParams = z.object({ id: z.uuid() });
+
+export const ListNotesQuery = PageQuery;
+
+/** What clients see of a note: fields not listed here never leave the server. */
+export const NoteResponse = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: isoDate(),
+});
+
+export type CreateNoteBody = z.infer<typeof CreateNoteBody>;
+export type UpdateNoteBody = z.infer<typeof UpdateNoteBody>;
+export type ListNotesQuery = z.infer<typeof ListNotesQuery>;

package/starters/minimal/src/features/notes/notes.service.ts

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { inject, NotFoundError } from "@raiyyan/brisk";
+import { NotesRepository, type Note } from "./notes.repository.ts";
+import type { CreateNoteBody, ListNotesQuery, UpdateNoteBody } from "./notes.schema.ts";
+
+/** Business rules for notes. Throws errors the client understands; knows nothing about Express. */
+export class NotesService {
+  readonly #repository = inject(NotesRepository);
+
+  async list(query: ListNotesQuery) {
+    const { items, total } = await this.#repository.list(query);
+    return { items, total, page: query.page, limit: query.limit };
+  }
+
+  async get(id: string): Promise<Note> {
+    const row = await this.#repository.findById(id);
+    if (!row) throw new NotFoundError("Note not found", { details: { id } });
+    return row;
+  }
+
+  create(input: CreateNoteBody): Promise<Note> {
+    return this.#repository.insert({ id: randomUUID(), name: input.name, createdAt: new Date() });
+  }
+
+  async update(id: string, { name }: UpdateNoteBody): Promise<Note> {
+    const row = await this.get(id);
+    return this.#repository.update({ ...row, name: name ?? row.name });
+  }
+
+  async remove(id: string): Promise<void> {
+    if (!(await this.#repository.delete(id))) throw new NotFoundError("Note not found", { details: { id } });
+  }
+}

package/starters/minimal/src/main.ts

@@ -0,0 +1,4 @@
+import { app } from "./app.ts";
+import { env } from "./env.ts";
+
+await app.listen(env.PORT);

package/starters/minimal/src/schemas.ts

@@ -0,0 +1,26 @@
+import { z } from "@raiyyan/brisk";
+
+/**
+ * A response field for a timestamp: accepts a `Date` or an ISO string and always sends an ISO 8601 string,
+ * so clients type it as `string` and OpenAPI documents it as `date-time`.
+ */
+export const isoDate = () =>
+  z
+    .union([z.date(), z.string()])
+    .transform((value) => (value instanceof Date ? value : new Date(value)).toISOString())
+    .pipe(z.iso.datetime());
+
+/** Query fields for paged lists: `page` from 1, and `limit` up to 100. */
+export const PageQuery = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+/** A page of `item`s, with the total across all pages. */
+export const page = <Item extends z.ZodType>(item: Item) =>
+  z.object({
+    items: z.array(item),
+    page: z.number().int(),
+    limit: z.number().int(),
+    total: z.number().int(),
+  });

package/starters/minimal/templates/feature/src/features/index.ts.controllers.insert

@@ -0,0 +1 @@
+  {{camel}}: {{camel}}Controller,

package/starters/minimal/templates/feature/src/features/index.ts.imports.insert

@@ -0,0 +1 @@
+import { {{camel}}Controller } from "./{{kebab}}/{{kebab}}.controller.ts";

package/starters/minimal/templates/feature/src/features/{{kebab}}/{{kebab}}.controller.ts

@@ -0,0 +1,38 @@
+import { defineController, inject } from "@raiyyan/brisk";
+import { page } from "../../schemas.ts";
+import {
+  Create{{entity}}Body,
+  {{entity}}IdParams,
+  {{entity}}Response,
+  List{{pascal}}Query,
+  Update{{entity}}Body,
+} from "./{{kebab}}.schema.ts";
+import { {{pascal}}Service } from "./{{kebab}}.service.ts";
+
+export const {{camel}}Controller = defineController({ prefix: "/{{kebab}}" }, (route) => {
+  const {{camel}} = inject({{pascal}}Service);
+
+  return {
+    list: route.get("/", { query: List{{pascal}}Query, response: page({{entity}}Response) }, ({ query }) =>
+      {{camel}}.list(query),
+    ),
+
+    get: route.get("/:id", { params: {{entity}}IdParams, response: {{entity}}Response }, ({ params }) =>
+      {{camel}}.get(params.id),
+    ),
+
+    create: route.post("/", { body: Create{{entity}}Body, response: {{entity}}Response }, ({ body }) =>
+      {{camel}}.create(body),
+    ),
+
+    update: route.patch(
+      "/:id",
+      { params: {{entity}}IdParams, body: Update{{entity}}Body, response: {{entity}}Response },
+      ({ params, body }) => {{camel}}.update(params.id, body),
+    ),
+
+    remove: route.delete("/:id", { params: {{entity}}IdParams }, async ({ params }) => {
+      await {{camel}}.remove(params.id);
+    }),
+  };
+});

package/starters/minimal/templates/feature/src/features/{{kebab}}/{{kebab}}.repository.ts

@@ -0,0 +1,36 @@
+export interface {{entity}} {
+  id: string;
+  name: string;
+  createdAt: Date;
+}
+
+/**
+ * In-memory storage behind an async interface, the shape a database gives: swap the map for your database and
+ * the service does not change. Rows are lost on restart.
+ */
+export class {{pascal}}Repository {
+  readonly #rows = new Map<string, {{entity}}>();
+
+  async list({ page, limit }: { page: number; limit: number }): Promise<{ items: {{entity}}[]; total: number }> {
+    const rows = [...this.#rows.values()].toReversed();
+    return { items: rows.slice((page - 1) * limit, page * limit), total: rows.length };
+  }
+
+  async findById(id: string): Promise<{{entity}} | undefined> {
+    return this.#rows.get(id);
+  }
+
+  async insert(row: {{entity}}): Promise<{{entity}}> {
+    this.#rows.set(row.id, row);
+    return row;
+  }
+
+  async update(row: {{entity}}): Promise<{{entity}}> {
+    this.#rows.set(row.id, row);
+    return row;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    return this.#rows.delete(id);
+  }
+}

package/starters/minimal/templates/feature/src/features/{{kebab}}/{{kebab}}.schema.ts

@@ -0,0 +1,24 @@
+import { z } from "@raiyyan/brisk";
+import { isoDate, PageQuery } from "../../schemas.ts";
+
+export const Create{{entity}}Body = z.object({
+  name: z.string().trim().min(1).max(200),
+});
+
+// Keep .default() out of the create schema: .partial() keeps defaults, and a PATCH would reset omitted fields.
+export const Update{{entity}}Body = Create{{entity}}Body.partial();
+
+export const {{entity}}IdParams = z.object({ id: z.uuid() });
+
+export const List{{pascal}}Query = PageQuery;
+
+/** What clients see of a {{entityCamel}}: fields not listed here never leave the server. */
+export const {{entity}}Response = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: isoDate(),
+});
+
+export type Create{{entity}}Body = z.infer<typeof Create{{entity}}Body>;
+export type Update{{entity}}Body = z.infer<typeof Update{{entity}}Body>;
+export type List{{pascal}}Query = z.infer<typeof List{{pascal}}Query>;

package/starters/minimal/templates/feature/src/features/{{kebab}}/{{kebab}}.service.ts

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { inject, NotFoundError } from "@raiyyan/brisk";
+import { {{pascal}}Repository, type {{entity}} } from "./{{kebab}}.repository.ts";
+import type { Create{{entity}}Body, List{{pascal}}Query, Update{{entity}}Body } from "./{{kebab}}.schema.ts";
+
+/** Business rules for {{camel}}. Throws errors the client understands; knows nothing about Express. */
+export class {{pascal}}Service {
+  readonly #repository = inject({{pascal}}Repository);
+
+  async list(query: List{{pascal}}Query) {
+    const { items, total } = await this.#repository.list(query);
+    return { items, total, page: query.page, limit: query.limit };
+  }
+
+  async get(id: string): Promise<{{entity}}> {
+    const row = await this.#repository.findById(id);
+    if (!row) throw new NotFoundError("{{entity}} not found", { details: { id } });
+    return row;
+  }
+
+  create(input: Create{{entity}}Body): Promise<{{entity}}> {
+    return this.#repository.insert({ id: randomUUID(), name: input.name, createdAt: new Date() });
+  }
+
+  async update(id: string, { name }: Update{{entity}}Body): Promise<{{entity}}> {
+    const row = await this.get(id);
+    return this.#repository.update({ ...row, name: name ?? row.name });
+  }
+
+  async remove(id: string): Promise<void> {
+    if (!(await this.#repository.delete(id))) throw new NotFoundError("{{entity}} not found", { details: { id } });
+  }
+}

package/starters/minimal/templates/feature/test/{{kebab}}.service.test.ts

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { Container, NotFoundError } from "@raiyyan/brisk";
+import { afterAll, describe, expect, it } from "vitest";
+import { {{pascal}}Service } from "../src/features/{{kebab}}/{{kebab}}.service.ts";
+
+const container = new Container();
+const {{camel}} = container.get({{pascal}}Service);
+await container.init();
+afterAll(() => container.shutdown(() => {}));
+
+describe("{{pascal}}Service", () => {
+  it("creates a {{entityCamel}} and finds it again", async () => {
+    const created = await {{camel}}.create({ name: "unit" });
+    expect(await {{camel}}.get(created.id)).toEqual(created);
+  });
+
+  it("throws NotFoundError for an id that does not exist", async () => {
+    await expect({{camel}}.get(randomUUID())).rejects.toBeInstanceOf(NotFoundError);
+  });
+});

package/starters/minimal/templates/feature/test/{{kebab}}.test.ts

@@ -0,0 +1,35 @@
+import { randomUUID } from "node:crypto";
+import { createTestClient } from "@raiyyan/brisk/testing";
+import { afterAll, describe, expect, it } from "vitest";
+import { app } from "../src/app.ts";
+
+const api = await createTestClient(app);
+afterAll(() => api.close());
+
+describe("{{kebab}} API", () => {
+  it("creates, reads, lists, updates and deletes", async () => {
+    const created = await api.call.{{camel}}.create({ body: { name: "first" } });
+    const params = { id: created.id };
+    expect(created).toMatchObject({ name: "first" });
+
+    expect(await api.call.{{camel}}.get({ params })).toEqual(created);
+    expect((await api.call.{{camel}}.list({ query: { limit: 100 } })).items).toContainEqual(created);
+    expect(await api.call.{{camel}}.update({ params, body: { name: "second" } })).toMatchObject({
+      id: created.id,
+      name: "second",
+    });
+
+    await api.call.{{camel}}.remove({ params });
+    await expect(api.call.{{camel}}.get({ params })).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("rejects invalid input with the field that failed", async () => {
+    expect((await api.post("/api/{{kebab}}", { body: { name: "" } })).status).toBe(400);
+  });
+
+  it("answers 404 for an id that does not exist", async () => {
+    await expect(api.call.{{camel}}.get({ params: { id: randomUUID() } })).rejects.toMatchObject({
+      status: 404,
+    });
+  });
+});

package/starters/minimal/templates/middleware/src/middlewares/{{kebab}}.ts

@@ -0,0 +1,12 @@
+import { BadRequestError, defineMiddleware } from "@raiyyan/brisk";
+
+/**
+ * Reads the `x-{{kebab}}` header and adds `{{camel}}` to the ctx of every route that uses it. Replace the check
+ * with your own; return nothing for a check-only middleware. To validate path params or a query first,
+ * declare them: `defineMiddleware({ params: z.object({ ... }) }, ({ params }) => ...)`.
+ */
+export const {{camel}} = defineMiddleware(({ req }) => {
+  const value = req.get("x-{{kebab}}");
+  if (!value) throw new BadRequestError("Missing x-{{kebab}} header");
+  return { {{camel}}: value };
+});

package/starters/minimal/test/notes.service.test.ts

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { Container, NotFoundError } from "@raiyyan/brisk";
+import { afterAll, describe, expect, it } from "vitest";
+import { NotesService } from "../src/features/notes/notes.service.ts";
+
+const container = new Container();
+const notes = container.get(NotesService);
+await container.init();
+afterAll(() => container.shutdown(() => {}));
+
+describe("NotesService", () => {
+  it("creates a note and finds it again", async () => {
+    const created = await notes.create({ name: "unit" });
+    expect(await notes.get(created.id)).toEqual(created);
+  });
+
+  it("throws NotFoundError for an id that does not exist", async () => {
+    await expect(notes.get(randomUUID())).rejects.toBeInstanceOf(NotFoundError);
+  });
+});

package/starters/minimal/test/notes.test.ts

@@ -0,0 +1,35 @@
+import { randomUUID } from "node:crypto";
+import { createTestClient } from "@raiyyan/brisk/testing";
+import { afterAll, describe, expect, it } from "vitest";
+import { app } from "../src/app.ts";
+
+const api = await createTestClient(app);
+afterAll(() => api.close());
+
+describe("notes API", () => {
+  it("creates, reads, lists, updates and deletes", async () => {
+    const created = await api.call.notes.create({ body: { name: "first" } });
+    const params = { id: created.id };
+    expect(created).toMatchObject({ name: "first" });
+
+    expect(await api.call.notes.get({ params })).toEqual(created);
+    expect((await api.call.notes.list({ query: { limit: 100 } })).items).toContainEqual(created);
+    expect(await api.call.notes.update({ params, body: { name: "second" } })).toMatchObject({
+      id: created.id,
+      name: "second",
+    });
+
+    await api.call.notes.remove({ params });
+    await expect(api.call.notes.get({ params })).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("rejects invalid input with the field that failed", async () => {
+    expect((await api.post("/api/notes", { body: { name: "" } })).status).toBe(400);
+  });
+
+  it("answers 404 for an id that does not exist", async () => {
+    await expect(api.call.notes.get({ params: { id: randomUUID() } })).rejects.toMatchObject({
+      status: 404,
+    });
+  });
+});

package/starters/minimal/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test", "vitest.config.ts"]
+}

package/starters/minimal/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    // templates/ holds the files `brisk g` renders; they are not tests until rendered.
+    include: ["test/**/*.test.ts"],
+    env: { NODE_ENV: "test" },
+  },
+});

package/starters/sqlite-auth/.dockerignore

@@ -0,0 +1,8 @@
+**/node_modules
+.env
+coverage
+.git
+test
+templates
+*.db
+*.db-*

package/starters/sqlite-auth/.env.example

@@ -0,0 +1,9 @@
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=info
+DATABASE_PATH=data.db
+AUTH_SECRET=replace-with-32-or-more-random-characters
+WEB_ORIGIN=http://localhost:5173
+# Optional: the first admin, created at boot
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=change-me-to-a-long-password

package/starters/sqlite-auth/.oxfmtrc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 110,
+  "ignorePatterns": ["templates", "node_modules", "coverage"]
+}

package/starters/sqlite-auth/.oxlintrc.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "import", "unicorn", "oxc", "vitest"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn"
+  },
+  "rules": {
+    "typescript/no-floating-promises": "error",
+    "typescript/no-misused-promises": "error",
+    "import/no-cycle": "error"
+  },
+  "ignorePatterns": ["templates", "node_modules", "coverage"]
+}

package/starters/sqlite-auth/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+<!-- brisk:start -->
+
+## Building with brisk
+
+This app uses [brisk](https://www.npmjs.com/package/@raiyyan/brisk), a typed layer over Express 5 and Zod.
+Before writing or changing server code, read the full guide: `node_modules/@raiyyan/brisk/AGENTS.md`.
+
+Essentials:
+
+- The app is declared once in `src/app.ts` with `defineApp`; `app.listen(port)` runs it, `createTestClient(app, { providers })` tests it.
+- Routes are named: a controller's setup returns `{ list: route.get(...), create: route.post(...) }`. The names form the typed client (`api.users.create({ body })`).
+- Validate every input with a Zod schema on the route; set `response` to a DTO schema so internal fields never leak.
+- New code follows this project's own templates: `npx brisk g feature <name>` renders `templates/feature/`. Edit the templates when the project's conventions change.
+- Dependencies: `readonly #repo = inject(Repository)` in class fields. No decorators, no constructor wiring.
+- Errors: `throw new NotFoundError("…")` (or another error class) anywhere. Never try/catch to build responses; never call `next()`.
+- Shared request logic: `defineMiddleware` returning an object types `ctx`; declare `params` or `query` it reads to get them validated first. Express middleware such as multer goes in a route's `use` through `fromExpress()`.
+- App-wide middleware goes in `defineApp({ use })` (`fromExpress(cors())` included); handlers that are not brisk routes (static files, GraphQL, webhooks) go in `defineApp({ mount })`. Express settings go in `http.settings`.
+- Long-lived work (WebSockets, jobs, consumers, pools) is a provider class with `onInit`, `onReady`, `onDrain`, `onShutdown`; a feature lists its own in `defineController({ providers })`.
+- Test with `createTestClient` from `@raiyyan/brisk/testing`: `api.call.<controller>.<route>(input)` is typed; `api.post(path)` checks raw HTTP.
+
+<!-- brisk:end -->

package/starters/sqlite-auth/CLAUDE.md

@@ -0,0 +1,2 @@
+@AGENTS.md
+@node_modules/@raiyyan/brisk/AGENTS.md

package/starters/sqlite-auth/Dockerfile

@@ -0,0 +1,23 @@
+# Node runs the TypeScript sources directly: no build step.
+FROM node:26-slim
+WORKDIR /app
+ENV NODE_ENV=production
+
+# Production dependencies only, with whichever package manager the lockfile belongs to.
+COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* ./
+RUN if [ -f pnpm-lock.yaml ]; then corepack enable && pnpm install --prod --frozen-lockfile; \
+    elif [ -f yarn.lock ]; then corepack enable && yarn install --production --frozen-lockfile; \
+    else npm ci --omit=dev; fi
+
+COPY --chown=node:node tsconfig.json ./
+COPY --chown=node:node src ./src
+# The app runs as `node` and may write only to /app/data: mount a volume there (compose.yaml does).
+RUN mkdir -p /app/data && chown node:node /app/data
+USER node
+EXPOSE 3000
+
+# Docker uses this; Kubernetes and Podman's default OCI format ignore it and use their own probes on /health.
+HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
+  CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT ?? 3000) + '/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
+# SIGTERM from `docker stop` starts brisk's graceful shutdown.
+CMD ["node", "src/main.ts"]

package/starters/sqlite-auth/README.md

@@ -0,0 +1,93 @@
+# sqlite-auth
+
+An API built with [brisk](https://github.com/MohammadRaiyyan/brisk) on Express 5 and Zod, with a SQLite database and bearer-token accounts. Created with `npx brisk init --starter sqlite-auth`.
+
+What it brings:
+
+- SQLite through Node's built-in `node:sqlite` (no driver dependency), opened at startup with the migrations it has not applied yet, and closed on shutdown.
+- Accounts: passwords hashed with scrypt, HS256 bearer tokens signed with `AUTH_SECRET`, and `authenticate` / `requireRole` middlewares.
+- The first admin, created at startup from `ADMIN_EMAIL` and `ADMIN_PASSWORD` when that user does not exist.
+- CORS for `WEB_ORIGIN`, a per-minute rate limit, and static files from `public/` under `/static`.
+- A Dockerfile and `compose.yaml` that keep the database in a volume.
+
+## Run it
+
+```bash
+cp .env.example .env   # then set AUTH_SECRET to 32+ random characters: openssl rand -base64 48
+npm run dev
+```
+
+The API listens on port 3000 under `/api`. `GET /health` is the health check and `GET /openapi.json` the OpenAPI document.
+
+```bash
+curl -X POST localhost:3000/api/auth/login -H 'content-type: application/json' \
+  -d '{"email":"admin@example.com","password":"change-me-to-a-long-password"}'
+curl localhost:3000/api/users/me -H "authorization: Bearer <token>"
+```
+
+| Script                    | What it does                               |
+| ------------------------- | ------------------------------------------ |
+| `dev`                     | Runs the server and restarts it on changes |
+| `start`                   | Runs the server                            |
+| `test`                    | Runs the tests (vitest, in-memory SQLite)  |
+| `typecheck`               | Checks types (`tsc --noEmit`)              |
+| `lint`                    | oxlint                                     |
+| `format` / `format:check` | oxfmt                                      |
+| `brisk g <kind> <name>`   | Generates code from `templates/<kind>/`    |
+
+Node 24 or later runs the TypeScript sources directly; there is no build step.
+
+## Environment
+
+| Variable                        | Default                 | What it sets                                          |
+| ------------------------------- | ----------------------- | ----------------------------------------------------- |
+| `NODE_ENV`                      | `development`           | `development`, `test` or `production`                 |
+| `PORT`                          | `3000`                  | HTTP port                                             |
+| `LOG_LEVEL`                     | `info`                  | pino log level                                        |
+| `DATABASE_PATH`                 | `data.db`               | SQLite file                                           |
+| `AUTH_SECRET`                   | required                | HMAC key for tokens, 32 characters or more            |
+| `AUTH_TOKEN_TTL_SECONDS`        | `3600`                  | Token lifetime                                        |
+| `WEB_ORIGIN`                    | `http://localhost:5173` | Browser origin allowed by CORS                        |
+| `RATE_LIMIT_PER_MINUTE`         | `300`                   | Requests per client per minute                        |
+| `ADMIN_EMAIL`, `ADMIN_PASSWORD` | not set                 | The first admin, created at startup when both are set |
+
+The app refuses to start when a variable is invalid. Behind a proxy, set `http: { settings: { "trust proxy": 1 } }` in `src/app.ts` so the rate limit counts clients, not the proxy. The rate limit is kept in memory, per instance.
+
+## Layout
+
+| Path                 | What it holds                                                                       |
+| -------------------- | ----------------------------------------------------------------------------------- |
+| `src/env.ts`         | Environment variables, validated at startup                                         |
+| `src/app.ts`         | The app: controllers, CORS, rate limit, static files, error mappers                 |
+| `src/database/`      | The `Database` provider, migrations, the `Clock` token, the unique-violation mapper |
+| `src/auth/tokens.ts` | Signing and verifying tokens                                                        |
+| `src/middlewares/`   | `authenticate` and `requireRole`                                                    |
+| `src/features/`      | `auth` (login), `users`, and the example `notes`, registered in `index.ts`          |
+| `src/schemas.ts`     | Shared schema helpers: `isoDate()`, `PageQuery`, `page(item)`                       |
+| `templates/`         | What `brisk g` renders: `feature` and `middleware`. Yours to edit                   |
+| `test/`              | HTTP and service tests; `helpers.ts` signs in as the admin                          |
+
+## Add a feature
+
+```bash
+npx brisk g feature products
+```
+
+This writes `src/features/products/` (behind `authenticate`), its tests, registers the controller in `src/features/index.ts` and appends a `CREATE TABLE products` migration to `src/database/migrations.ts`. Keep the `@brisk:` marker lines in those files. Migrations run in order at startup; append new ones and never edit one that has shipped.
+
+`npx brisk g middleware tenant` writes `src/middlewares/tenant.ts`. To change what new code looks like, edit the files in `templates/`.
+
+The `notes` feature is an example generated from `templates/feature`. Before anything ships, you can delete `src/features/notes/`, `test/notes.test.ts`, `test/notes.service.test.ts`, its two lines in `src/features/index.ts` and its migration.
+
+## Docker
+
+```bash
+docker compose up --build
+```
+
+The image installs production dependencies with whichever lockfile is present (pnpm, yarn or npm), runs as the `node` user, and may write only to `/app/data`. `compose.yaml` mounts a volume there and sets `DATABASE_PATH=/app/data/app.db`, so the database survives new images. `docker stop` sends SIGTERM, which starts a graceful shutdown.
+
+## Learn more
+
+- [brisk documentation](https://github.com/MohammadRaiyyan/brisk#readme)
+- `AGENTS.md` and `CLAUDE.md` point coding agents at the brisk guide (`npx brisk agents` refreshes them).

package/starters/sqlite-auth/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+.env
+coverage
+*.db
+*.db-*

package/starters/sqlite-auth/compose.yaml

@@ -0,0 +1,14 @@
+services:
+  app:
+    build: .
+    env_file: .env
+    ports:
+      - "3000:3000"
+    stop_grace_period: 30s
+    environment:
+      DATABASE_PATH: /app/data/app.db
+    volumes:
+      - data:/app/data
+
+volumes:
+  data:

package/starters/sqlite-auth/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "starter-sqlite-auth",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch src/main.ts",
+    "start": "node src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "brisk": "brisk",
+    "lint": "oxlint --type-aware",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check"
+  },
+  "dependencies": {
+    "@raiyyan/brisk": "workspace:*",
+    "cors": "^2.8.6",
+    "express": "^5.3.0",
+    "express-rate-limit": "^8.7.4"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.6",
+    "oxfmt": "^0.78.0",
+    "oxlint": "^1.93.0",
+    "oxlint-tsgolint": "^7.0.2007",
+    "pino-pretty": "^13.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}