@sundaysf/cli-v3 0.0.1

package/templates/api/src/db/KnexConnection.ts

@@ -0,0 +1,59 @@
+import { knex, type Knex } from 'knex';
+import { types } from 'pg';
+import { logger } from '../common/logger';
+import { buildKnexConfig } from './knex.config';
+
+// Postgres DATE (OID 1082) stays a plain 'YYYY-MM-DD' string instead of a Date object
+// (which would drag a timezone into a date-only value).
+types.setTypeParser(1082, (value: string) => value);
+// NUMERIC (1700) and BIGINT (20) arrive as strings by default; the API works with numbers.
+// Precision beyond 2^53 is not a concern for money/decimal(15,2) columns and counts.
+types.setTypeParser(1700, (value: string) => parseFloat(value));
+types.setTypeParser(20, (value: string) => parseInt(value, 10));
+
+/**
+ * Process-wide knex singleton. `connect()` once at boot (server.ts) or in a test's
+ * beforeAll; DAOs resolve the connection lazily through `getConnection()`.
+ */
+class KnexManager {
+  private static instance: Knex | null = null;
+
+  static async connect(config?: Knex.Config, poolMax?: number): Promise<Knex> {
+    if (!KnexManager.instance) {
+      const instance = knex(config ?? buildKnexConfig(undefined, poolMax));
+      try {
+        await instance.raw('SELECT 1');
+        logger.info('Knex connection established');
+      } catch (error) {
+        await instance.destroy();
+        logger.error({ err: error }, 'Failed to establish Knex connection');
+        throw error;
+      }
+      KnexManager.instance = instance;
+    }
+    return KnexManager.instance;
+  }
+
+  static getConnection(): Knex {
+    if (!KnexManager.instance) {
+      throw new Error(
+        'Knex connection has not been established. Call KnexManager.connect() first.'
+      );
+    }
+    return KnexManager.instance;
+  }
+
+  static isConnected(): boolean {
+    return KnexManager.instance !== null;
+  }
+
+  static async disconnect(): Promise<void> {
+    if (KnexManager.instance) {
+      await KnexManager.instance.destroy();
+      KnexManager.instance = null;
+      logger.info('Knex connection closed');
+    }
+  }
+}
+
+export default KnexManager;

package/templates/api/src/db/__tests__/base-dao.test.ts

@@ -0,0 +1,73 @@
+import { randomUUID } from 'crypto';
+import { KnexManager, SundaysPackageVersionDAO } from '..';
+import type { ISundaysPackageVersion } from '..';
+
+// Exercises BaseDAO through the framework table (requires the local Postgres + migrations).
+describe('BaseDAO (via SundaysPackageVersionDAO)', () => {
+  const dao = new SundaysPackageVersionDAO();
+  const marker = `test-${randomUUID().slice(0, 8)}`;
+  let created: ISundaysPackageVersion;
+
+  beforeAll(async () => {
+    await KnexManager.connect();
+  });
+
+  afterAll(async () => {
+    await KnexManager.getConnection()('sundays_package_version')
+      .where('versionName', 'like', 'test-%')
+      .delete();
+    await KnexManager.disconnect();
+  });
+
+  it('creates with a generated uuid and timestamps', async () => {
+    created = await dao.create({ versionName: marker });
+    expect(created.id).toEqual(expect.any(Number));
+    expect(created.uuid).toMatch(/^[0-9a-f-]{36}$/);
+    expect(created.createdAt).toBeDefined();
+  });
+
+  it('reads by id and uuid', async () => {
+    expect((await dao.getById(created.id!))?.versionName).toBe(marker);
+    expect((await dao.getByUuid(created.uuid!))?.versionName).toBe(marker);
+    expect(await dao.getById(-1)).toBeNull();
+    expect(await dao.getByUuid(randomUUID())).toBeNull();
+    expect((await dao.getLatest())?.id).toBeGreaterThanOrEqual(created.id!);
+  });
+
+  it('updates and bumps updatedAt', async () => {
+    const updated = await dao.update(created.id!, {
+      versionName: `${marker}-2`,
+    });
+    expect(updated?.versionName).toBe(`${marker}-2`);
+    expect(await dao.update(-1, { versionName: 'x' })).toBeNull();
+  });
+
+  it('paginates with the standard envelope', async () => {
+    const page = await dao.getAll(1, 5);
+    expect(page.success).toBe(true);
+    expect(page.page).toBe(1);
+    expect(page.limit).toBe(5);
+    expect(page.count).toBe(page.data.length);
+    expect(page.totalCount).toBeGreaterThanOrEqual(1);
+    expect(page.totalPages).toBe(Math.ceil(page.totalCount / 5));
+    const clamped = await dao.getAll(0, 0);
+    expect(clamped.page).toBe(1);
+    expect(clamped.limit).toBe(1);
+  });
+
+  it('works inside a transaction', async () => {
+    const knex = KnexManager.getConnection();
+    await knex.transaction(async (trx) => {
+      const row = await dao.create({ versionName: `${marker}-trx` }, trx);
+      expect((await dao.getById(row.id!, trx))?.versionName).toBe(
+        `${marker}-trx`
+      );
+      expect(await dao.delete(row.id!, trx)).toBe(true);
+    });
+  });
+
+  it('deletes', async () => {
+    expect(await dao.delete(created.id!)).toBe(true);
+    expect(await dao.delete(created.id!)).toBe(false);
+  });
+});

package/templates/api/src/db/__tests__/index.barrel.test.ts

@@ -0,0 +1,10 @@
+import * as db from '..';
+
+describe('db barrel', () => {
+  it('exports the framework pieces', () => {
+    expect(db.KnexManager).toBeDefined();
+    expect(db.BaseDAO).toBeDefined();
+    expect(db.buildKnexConfig).toBeDefined();
+    expect(db.SundaysPackageVersionDAO).toBeDefined();
+  });
+});

package/templates/api/src/db/__tests__/knex-connection.test.ts

@@ -0,0 +1,90 @@
+import KnexManager from '../KnexConnection';
+import { buildKnexConfig, isLocalhost } from '../knex.config';
+import { loadEnv } from '../../common/config/env';
+
+// Requires the local Postgres from docker-compose.yml (npm run test:unit skips this suite).
+describe('KnexManager', () => {
+  afterAll(async () => {
+    await KnexManager.disconnect();
+  });
+
+  it('throws before connect()', async () => {
+    await KnexManager.disconnect();
+    expect(KnexManager.isConnected()).toBe(false);
+    expect(() => KnexManager.getConnection()).toThrow(/connect\(\) first/);
+  });
+
+  it('connects once and reuses the instance', async () => {
+    const a = await KnexManager.connect();
+    const b = await KnexManager.connect();
+    expect(a).toBe(b);
+    expect(KnexManager.isConnected()).toBe(true);
+    const { rows } = await KnexManager.getConnection().raw('SELECT 1 AS one');
+    expect(rows[0].one).toBe(1);
+  });
+
+  it('disconnects idempotently', async () => {
+    await KnexManager.disconnect();
+    await KnexManager.disconnect();
+    expect(KnexManager.isConnected()).toBe(false);
+  });
+
+  it('rejects and leaves no instance when the database is unreachable', async () => {
+    const bad = buildKnexConfig(
+      loadEnv({
+        ...process.env,
+        SQL_HOST: '127.0.0.1',
+        SQL_PORT: '1',
+        SQL_USER: 'x',
+        SQL_PASSWORD: 'x',
+        SQL_DB_NAME: 'x',
+      }),
+      1
+    );
+    const silent = {
+      warn: () => {},
+      error: () => {},
+      deprecate: () => {},
+      debug: () => {},
+    };
+    await expect(
+      KnexManager.connect({
+        ...bad,
+        acquireConnectionTimeout: 1000,
+        log: silent,
+      })
+    ).rejects.toBeDefined();
+    expect(KnexManager.isConnected()).toBe(false);
+  });
+});
+
+describe('buildKnexConfig', () => {
+  const base = {
+    ...process.env,
+    SQL_USER: 'u',
+    SQL_PASSWORD: 'p',
+    SQL_DB_NAME: 'db',
+  };
+
+  it('disables ssl for localhost', () => {
+    const cfg = buildKnexConfig(loadEnv({ ...base, SQL_HOST: 'localhost' }));
+    expect((cfg.connection as { ssl: unknown }).ssl).toBe(false);
+    expect(isLocalhost('::1')).toBe(true);
+  });
+
+  it('enables ssl with rejectUnauthorized for remote hosts', () => {
+    const cfg = buildKnexConfig(
+      loadEnv({
+        ...base,
+        SQL_HOST: 'db.example.com',
+        SQL_REJECT_UNAUTHORIZED: 'false',
+      }),
+      3
+    );
+    expect((cfg.connection as { ssl: unknown }).ssl).toEqual({
+      rejectUnauthorized: false,
+    });
+    expect(cfg.pool?.max).toBe(3);
+    expect(cfg.migrations?.loadExtensions).toEqual(['.ts']);
+  });
+});

package/templates/api/src/db/d.types.ts

@@ -0,0 +1,42 @@
+import type { Knex } from 'knex';
+
+/** Columns every table created by sundaysf has. */
+export interface IEntity {
+  id?: number;
+  uuid?: string;
+  createdAt?: Date | string;
+  updatedAt?: Date | string;
+}
+
+/** Payload accepted by `create`: everything but the server-generated columns. */
+export type CreateInput<T extends IEntity> = Omit<
+  T,
+  'id' | 'uuid' | 'createdAt' | 'updatedAt'
+>;
+
+export interface IDataPaginator<T> {
+  success: boolean;
+  data: T[];
+  page: number;
+  limit: number;
+  count: number;
+  totalCount: number;
+  totalPages: number;
+}
+
+export interface IBaseDAO<T extends IEntity> {
+  create(item: CreateInput<T>, trx?: Knex.Transaction): Promise<T>;
+  getById(id: number, trx?: Knex.Transaction): Promise<T | null>;
+  getByUuid(uuid: string, trx?: Knex.Transaction): Promise<T | null>;
+  update(
+    id: number,
+    item: Partial<T>,
+    trx?: Knex.Transaction
+  ): Promise<T | null>;
+  delete(id: number, trx?: Knex.Transaction): Promise<boolean>;
+  getAll(
+    page: number,
+    limit: number,
+    trx?: Knex.Transaction
+  ): Promise<IDataPaginator<T>>;
+}

package/templates/api/src/db/dao/sundays-package-version/sundays-package-version.dao.ts

@@ -0,0 +1,12 @@
+import { BaseDAO } from '../../BaseDAO';
+import type { ISundaysPackageVersion } from '../../interfaces/sundays-package-version/sundays-package-version.interfaces';
+
+/** Framework bookkeeping table: which Sundays version generated this project. */
+export class SundaysPackageVersionDAO extends BaseDAO<ISundaysPackageVersion> {
+  protected readonly table = 'sundays_package_version';
+
+  async getLatest(): Promise<ISundaysPackageVersion | null> {
+    const row = await this.q().orderBy('id', 'desc').first();
+    return (row as ISundaysPackageVersion | undefined) ?? null;
+  }
+}

package/templates/api/src/db/index.ts

@@ -0,0 +1,17 @@
+// Database barrel. Controllers and services import DAOs and entity types from here:
+//   import { ProductDAO, IProduct } from '../../db';
+// `sundaysf generate entity` appends to this file at the @sundays markers. Keep them.
+
+import KnexManager from './KnexConnection';
+export { KnexManager };
+export { BaseDAO } from './BaseDAO';
+export { buildKnexConfig } from './knex.config';
+export type { IBaseDAO, IDataPaginator, IEntity, CreateInput } from './d.types';
+
+// Interfaces
+export type { ISundaysPackageVersion } from './interfaces/sundays-package-version/sundays-package-version.interfaces';
+// @sundays:interfaces
+
+// DAOs
+export { SundaysPackageVersionDAO } from './dao/sundays-package-version/sundays-package-version.dao';
+// @sundays:daos

package/templates/api/src/db/interfaces/sundays-package-version/sundays-package-version.interfaces.ts

@@ -0,0 +1,5 @@
+import type { IEntity } from '../../d.types';
+
+export interface ISundaysPackageVersion extends IEntity {
+  versionName: string;
+}

package/templates/api/src/db/knex.config.ts

@@ -0,0 +1,46 @@
+import path from 'path';
+import type { Knex } from 'knex';
+import { env, type Env } from '../common/config/env';
+
+export const isLocalhost = (host: string): boolean =>
+  host === 'localhost' || host === '127.0.0.1' || host === '::1';
+
+/**
+ * Single source of truth for the knex configuration: used by KnexManager (runtime) and
+ * by knexfile.ts (knex CLI). Migrations and seeds live in src/ and are compiled with the
+ * app, so their extension follows the extension this file is running with
+ * ('.ts' under tsx / ts-jest, '.js' from dist/).
+ */
+export const buildKnexConfig = (e: Env = env, poolMax = 15): Knex.Config => {
+  const ext = path.extname(__filename) || '.js';
+  return {
+    client: 'pg',
+    connection: {
+      host: e.SQL_HOST,
+      port: e.SQL_PORT,
+      user: e.SQL_USER,
+      password: e.SQL_PASSWORD,
+      database: e.SQL_DB_NAME,
+      ssl: isLocalhost(e.SQL_HOST)
+        ? false
+        : { rejectUnauthorized: e.SQL_REJECT_UNAUTHORIZED },
+    },
+    pool: {
+      min: 1,
+      max: poolMax,
+      idleTimeoutMillis: 20000,
+      acquireTimeoutMillis: 30000,
+    },
+    migrations: {
+      tableName: 'knex_migrations',
+      directory: path.join(__dirname, '..', 'migrations'),
+      extension: 'ts',
+      loadExtensions: [ext],
+    },
+    seeds: {
+      directory: path.join(__dirname, '..', 'seeds'),
+      extension: 'ts',
+      loadExtensions: [ext],
+    },
+  };
+};

package/templates/api/src/middlewares/error/__tests__/error.middleware.test.ts

@@ -0,0 +1,117 @@
+import type { NextFunction, Request, Response } from 'express';
+import * as envConfig from '../../../common/config/env';
+import { HttpError } from '../../../common/errors/http.error';
+import { errorMiddleware } from '../error.middleware';
+
+const mockRes = (): Response => {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+};
+const req = {} as Request;
+const next = jest.fn() as NextFunction;
+
+describe('errorMiddleware', () => {
+  it('renders HttpError with its status and details', () => {
+    const res = mockRes();
+    errorMiddleware(
+      new HttpError(400, 'Validation failed', { name: ['Required'] }),
+      req,
+      res,
+      next
+    );
+    expect(res.status).toHaveBeenCalledWith(400);
+    expect(res.json).toHaveBeenCalledWith({
+      success: false,
+      message: 'Validation failed',
+      errors: { name: ['Required'] },
+    });
+  });
+
+  it('honours statusCode / status on plain errors', () => {
+    const res = mockRes();
+    errorMiddleware(
+      Object.assign(new Error('nope'), { status: 418 }),
+      req,
+      res,
+      next
+    );
+    expect(res.status).toHaveBeenCalledWith(418);
+    expect(res.json).toHaveBeenCalledWith({ success: false, message: 'nope' });
+  });
+
+  it('defaults to 500 and keeps the message outside production', () => {
+    const res = mockRes();
+    errorMiddleware(new Error('db exploded'), req, res, next);
+    expect(res.status).toHaveBeenCalledWith(500);
+    expect(res.json).toHaveBeenCalledWith({
+      success: false,
+      message: 'db exploded',
+    });
+  });
+
+  it('hides 500 messages in production', () => {
+    const spy = jest.spyOn(envConfig, 'isProduction').mockReturnValue(true);
+    const res = mockRes();
+    errorMiddleware(new Error('db exploded'), req, res, next);
+    expect(res.status).toHaveBeenCalledWith(500);
+    expect(res.json).toHaveBeenCalledWith({
+      success: false,
+      message: 'Internal server error',
+    });
+    spy.mockRestore();
+  });
+
+  it.each([
+    ['23505', 409, 'A record with the same unique value already exists'],
+    ['23503', 409, 'Referenced record does not exist or is still referenced'],
+    ['23502', 400, 'A required column is missing'],
+    ['22P02', 400, 'Invalid value for a column'],
+  ])('maps Postgres error %s to %i', (code, status, message) => {
+    const res = mockRes();
+    const pgError = Object.assign(new Error('insert into ... violates'), {
+      code,
+      constraint: 'product_name_unique',
+    });
+    errorMiddleware(pgError, req, res, next);
+    expect(res.status).toHaveBeenCalledWith(status);
+    expect(res.json).toHaveBeenCalledWith({
+      success: false,
+      message,
+      errors: { constraint: 'product_name_unique' },
+    });
+  });
+
+  it('ignores unknown Postgres codes and missing constraint names', () => {
+    const res = mockRes();
+    errorMiddleware(
+      Object.assign(new Error('weird'), { code: '58000' }),
+      req,
+      res,
+      next
+    );
+    expect(res.status).toHaveBeenCalledWith(500);
+    const res2 = mockRes();
+    errorMiddleware(
+      Object.assign(new Error('dup'), { code: '23505' }),
+      req,
+      res2,
+      next
+    );
+    expect(res2.json).toHaveBeenCalledWith({
+      success: false,
+      message: 'A record with the same unique value already exists',
+    });
+  });
+
+  it('survives a non-Error value', () => {
+    const res = mockRes();
+    errorMiddleware(undefined, req, res, next);
+    expect(res.status).toHaveBeenCalledWith(500);
+    expect(res.json).toHaveBeenCalledWith({
+      success: false,
+      message: 'Internal server error',
+    });
+  });
+});

package/templates/api/src/middlewares/error/error.middleware.ts

@@ -0,0 +1,70 @@
+import type { NextFunction, Request, Response } from 'express';
+import { isProduction } from '../../common/config/env';
+import { logger } from '../../common/logger';
+import { isHttpError } from '../../common/errors/http.error';
+
+interface ErrorLike {
+  statusCode?: number;
+  status?: number;
+  message?: string;
+  type?: string;
+  /** Postgres SQLSTATE (set by pg on database errors). */
+  code?: string;
+  constraint?: string;
+  detail?: string;
+}
+
+/** Postgres constraint violations mapped to client errors instead of a raw 500. */
+const PG_ERRORS: Record<string, { statusCode: number; message: string }> = {
+  '23505': {
+    statusCode: 409,
+    message: 'A record with the same unique value already exists',
+  },
+  '23503': {
+    statusCode: 409,
+    message: 'Referenced record does not exist or is still referenced',
+  },
+  '23502': { statusCode: 400, message: 'A required column is missing' },
+  '22P02': { statusCode: 400, message: 'Invalid value for a column' },
+};
+
+/**
+ * Last middleware in the chain. Renders every error as `{ success: false, message }`
+ * (plus `errors` for validation failures). 500s hide their message in production.
+ */
+export const errorMiddleware = (
+  err: unknown,
+  req: Request,
+  res: Response,
+  _next: NextFunction
+): void => {
+  const e = (err ?? {}) as ErrorLike;
+  const pg = typeof e.code === 'string' ? PG_ERRORS[e.code] : undefined;
+  const statusCode = isHttpError(err)
+    ? err.statusCode
+    : (pg?.statusCode ?? e.statusCode ?? e.status ?? 500);
+  const details = isHttpError(err)
+    ? err.details
+    : pg && e.constraint
+      ? { constraint: e.constraint }
+      : undefined;
+  const log = req.log ?? logger;
+
+  if (statusCode >= 500) {
+    log.error({ err }, 'Unhandled error');
+  } else {
+    log.warn({ err: { message: e.message, statusCode } }, 'Request failed');
+  }
+
+  const message = pg
+    ? pg.message
+    : statusCode >= 500 && isProduction()
+      ? 'Internal server error'
+      : (e.message ?? 'Internal server error');
+
+  res.status(statusCode).json({
+    success: false,
+    message,
+    ...(details !== undefined ? { errors: details } : {}),
+  });
+};

package/templates/api/src/middlewares/not-found/__tests__/not-found.middleware.test.ts

@@ -0,0 +1,54 @@
+import type { Request, Response } from 'express';
+import request from 'supertest';
+import app from '../../../app';
+import { notFoundMiddleware } from '../not-found.middleware';
+
+describe('notFoundMiddleware', () => {
+  it('returns the JSON envelope for API clients', async () => {
+    const res = await request(app)
+      .get('/api/nope')
+      .set('Accept', 'application/json');
+    expect(res.status).toBe(404);
+    expect(res.body).toEqual({
+      success: false,
+      message: 'Route GET /api/nope does not exist',
+    });
+  });
+
+  it('returns JSON when no Accept header is sent', async () => {
+    const res = await request(app).delete('/whatever');
+    expect(res.status).toBe(404);
+    expect(res.body.success).toBe(false);
+  });
+
+  it('returns an HTML page for browsers', async () => {
+    const res = await request(app).get('/nope').set('Accept', 'text/html');
+    expect(res.status).toBe(404);
+    expect(res.headers['content-type']).toMatch(/text\/html/);
+    expect(res.text).toContain('404');
+    expect(res.text).toContain('GET /nope');
+  });
+
+  it('escapes the requested path in the HTML page', () => {
+    const req = {
+      method: 'GET',
+      originalUrl: '/<script>alert("x")</script>',
+      accepts: jest.fn((types?: string | string[]) =>
+        Array.isArray(types) ? 'html' : 'text/html'
+      ),
+    } as unknown as Request;
+    const res = {
+      status: jest.fn().mockReturnThis(),
+      type: jest.fn().mockReturnThis(),
+      send: jest.fn().mockReturnThis(),
+      json: jest.fn().mockReturnThis(),
+    } as unknown as Response;
+
+    notFoundMiddleware(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(404);
+    const html = (res.send as jest.Mock).mock.calls[0][0] as string;
+    expect(html).toContain('&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt;');
+    expect(html).not.toContain('<script>alert');
+  });
+});

package/templates/api/src/middlewares/not-found/not-found.middleware.ts

@@ -0,0 +1,51 @@
+import type { Request, Response } from 'express';
+
+const PROJECT_NAME = '__SF_PROJECT_NAME__';
+
+const escapeHtml = (value: string): string =>
+  value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+
+/**
+ * 404 catch-all, mounted after every router and before the error middleware.
+ * Browsers (Accept: text/html) get a small HTML page; API clients get the standard
+ * `{ success: false, message }` envelope.
+ */
+export const notFoundMiddleware = (req: Request, res: Response): void => {
+  const method = escapeHtml(req.method);
+  const url = escapeHtml(req.originalUrl);
+
+  if (!req.accepts('html') || req.accepts(['json', 'html']) === 'json') {
+    res.status(404).json({
+      success: false,
+      message: `Route ${req.method} ${req.originalUrl} does not exist`,
+    });
+    return;
+  }
+
+  res.status(404).type('html').send(`<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>404 · ${escapeHtml(PROJECT_NAME)}</title>
+  </head>
+  <body style="margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#0f172a;color:#e2e8f0;font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;">
+    <main style="max-width:560px;padding:32px;">
+      <p style="margin:0;font-size:72px;font-weight:800;line-height:1;color:#38bdf8;">404</p>
+      <h1 style="margin:16px 0 8px;font-size:22px;">Nothing here</h1>
+      <p style="margin:0 0 16px;color:#94a3b8;line-height:1.6;">
+        <code style="background:#1e293b;padding:2px 8px;border-radius:6px;">${method} ${url}</code>
+        is not a route of the ${escapeHtml(PROJECT_NAME)} API.
+      </p>
+      <p style="margin:0;font-size:13px;color:#64748b;">
+        API clients receive <code>{ success: false, message }</code> with <code>Accept: application/json</code>.
+      </p>
+    </main>
+  </body>
+</html>`);
+};