@sundaysf/cli-v3 0.0.1

package/templates/api/docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: __SF_PROJECT_SLUG__-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: __SF_DB_NAME__
+    ports:
+      - '5432:5432'
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres -d __SF_DB_NAME__']
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+volumes:
+  postgres-data:

package/templates/api/eslint.config.js

@@ -0,0 +1,27 @@
+const eslint = require('@eslint/js');
+const tseslint = require('typescript-eslint');
+const globals = require('globals');
+
+module.exports = tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: { ...globals.node, ...globals.jest },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+    },
+  },
+  {
+    // Plain CommonJS config files (this one, jest.*.js) legitimately use require().
+    files: ['**/*.js', '**/*.cjs'],
+    rules: { '@typescript-eslint/no-require-imports': 'off' },
+  },
+  {
+    ignores: ['dist/', 'node_modules/', 'coverage/'],
+  }
+);

package/templates/api/jest.config.js

@@ -0,0 +1,33 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  verbose: true,
+  // Tests live next to the code they cover, in __tests__/ folders.
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { tsconfig: 'tsconfig.spec.json' }],
+  },
+  // Loads .env, applies test defaults and refuses to run against a remote database.
+  setupFiles: ['<rootDir>/jest.setup.js'],
+  testTimeout: 30000,
+  // Route tests share one Postgres pool: run suites serially to keep them deterministic.
+  maxWorkers: 1,
+  collectCoverage: true,
+  collectCoverageFrom: ['src/**/*.ts'],
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '<rootDir>/src/server.ts',
+    '<rootDir>/src/migrations/',
+    '<rootDir>/src/seeds/',
+    '\\.d\\.ts$',
+    '\\.interfaces\\.ts$',
+    '/__tests__/',
+  ],
+  coverageReporters: ['text-summary', 'text'],
+  // Raise these as the project matures (the reference project runs at 100%).
+  coverageThreshold: {
+    global: { statements: 80, branches: 80, functions: 80, lines: 80 },
+  },
+};

package/templates/api/jest.setup.js

@@ -0,0 +1,25 @@
+// Runs before every test file (jest.config.js -> setupFiles).
+require('dotenv').config({ quiet: true });
+
+// Test-only defaults. Real values from .env win for the SQL_* group so route tests
+// can hit the local Postgres started with `docker compose up -d`.
+process.env.NODE_ENV = 'test';
+process.env.LOG_LEVEL = 'silent';
+process.env.RUN_MIGRATIONS = 'false';
+process.env.SQL_HOST = process.env.SQL_HOST || 'localhost';
+process.env.SQL_PORT = process.env.SQL_PORT || '5432';
+process.env.SQL_USER = process.env.SQL_USER || 'postgres';
+process.env.SQL_PASSWORD = process.env.SQL_PASSWORD || 'postgres';
+process.env.SQL_DB_NAME = process.env.SQL_DB_NAME || '__SF_DB_NAME__';
+
+// GUARD: route tests WRITE to the database. If .env points at a remote host (staging,
+// production...), abort before touching anything. Opt in explicitly when intended:
+//   ALLOW_REMOTE_DB_TESTS=1 npm test
+const sqlHost = process.env.SQL_HOST;
+const isLocalDb = sqlHost === 'localhost' || sqlHost === '127.0.0.1';
+if (!isLocalDb && process.env.ALLOW_REMOTE_DB_TESTS !== '1') {
+  throw new Error(
+    `SQL_HOST="${sqlHost}" is not local: tests write to the database. ` +
+      'Point SQL_* at localhost, or export ALLOW_REMOTE_DB_TESTS=1 if this is intentional.'
+  );
+}

package/templates/api/knexfile.ts

@@ -0,0 +1,5 @@
+// Used only by the knex CLI (npm run db:*). The app itself builds the same config through
+// src/db/knex.config.ts, so there is exactly one place where connection settings live.
+import { buildKnexConfig } from './src/db/knex.config';
+
+export default buildKnexConfig();

package/templates/api/src/app.ts

@@ -0,0 +1,48 @@
+import cors from 'cors';
+import express, { type Express } from 'express';
+import helmet from 'helmet';
+import { pinoHttp } from 'pino-http';
+import { env } from './common/config/env';
+import { logger } from './common/logger';
+import { errorMiddleware } from './middlewares/error/error.middleware';
+import { notFoundMiddleware } from './middlewares/not-found/not-found.middleware';
+import { requestIdMiddleware } from './middlewares/request-id/request-id.middleware';
+import { IndexRouter } from './routes';
+
+const app: Express = express();
+
+app.disable('x-powered-by');
+app.set('trust proxy', true);
+
+app.use(helmet());
+app.use(
+  cors({
+    origin:
+      env.CORS_ORIGINS === '*'
+        ? true
+        : env.CORS_ORIGINS.split(',').map((o) => o.trim()),
+  })
+);
+app.use(requestIdMiddleware);
+app.use(
+  pinoHttp({
+    logger,
+    genReqId: (req) => req.id,
+    autoLogging: { ignore: (req) => (req.url ?? '').startsWith('/api/health') },
+  })
+);
+
+// Webhooks that need the RAW body for signature verification (Stripe, etc.) must be
+// mounted here, BEFORE the JSON parser:
+//   app.post('/api/stripe/webhook', express.raw({ type: 'application/json' }), handler);
+
+app.use(express.urlencoded({ extended: true }));
+app.use(express.json());
+
+app.use('/api', new IndexRouter().router);
+
+// Order matters: 404 after every router, error handler last.
+app.use(notFoundMiddleware);
+app.use(errorMiddleware);
+
+export default app;

package/templates/api/src/common/__tests__/common.test.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { loadEnv } from '../config/env';
+import {
+  HttpError,
+  badRequest,
+  conflict,
+  forbidden,
+  isHttpError,
+  notFound,
+  unauthorized,
+} from '../errors/http.error';
+import {
+  DEFAULT_LIMIT,
+  DEFAULT_PAGE,
+  MAX_LIMIT,
+  getPagination,
+} from '../utils/pagination';
+import { parseDto } from '../validation/parse-dto';
+import { getServiceVersion } from '../utils/version.resolver';
+import { getServiceEnvironment } from '../utils/environment.resolver';
+
+/** The real env minus the keys under test, so extra required vars (e.g. JWT_SECRET) stay valid. */
+const envWithout = (...keys: string[]): NodeJS.ProcessEnv => {
+  const e: NodeJS.ProcessEnv = { ...process.env };
+  for (const k of keys) delete e[k];
+  return e;
+};
+
+describe('env', () => {
+  it('applies defaults and coerces types', () => {
+    const e = loadEnv({
+      ...envWithout('NODE_ENV', 'SQL_PORT', 'SQL_REJECT_UNAUTHORIZED'),
+      PORT: '4000',
+      RUN_MIGRATIONS: 'true',
+    });
+    expect(e.PORT).toBe(4000);
+    expect(e.RUN_MIGRATIONS).toBe(true);
+    expect(e.SQL_REJECT_UNAUTHORIZED).toBe(true);
+    expect(e.SQL_PORT).toBe(5432);
+    expect(e.NODE_ENV).toBe('development');
+  });
+
+  it('fails fast with a readable message', () => {
+    expect(() => loadEnv({ SQL_USER: 'u' })).toThrow(
+      /Invalid environment configuration/
+    );
+  });
+});
+
+describe('HttpError helpers', () => {
+  it.each([
+    [badRequest(), 400],
+    [unauthorized(), 401],
+    [forbidden(), 403],
+    [notFound(), 404],
+    [conflict(), 409],
+  ])('%s has status %i', (err, status) => {
+    expect(err).toBeInstanceOf(HttpError);
+    expect(err.statusCode).toBe(status);
+    expect(isHttpError(err)).toBe(true);
+  });
+
+  it('recognises non HttpErrors', () => {
+    expect(isHttpError(new Error('x'))).toBe(false);
+  });
+});
+
+describe('getPagination', () => {
+  it('falls back to defaults', () => {
+    expect(getPagination(undefined)).toEqual({
+      page: DEFAULT_PAGE,
+      limit: DEFAULT_LIMIT,
+    });
+    expect(getPagination({ page: 'x', limit: '-1' })).toEqual({
+      page: DEFAULT_PAGE,
+      limit: DEFAULT_LIMIT,
+    });
+  });
+  it('parses and caps values', () => {
+    expect(getPagination({ page: '3', limit: '25' })).toEqual({
+      page: 3,
+      limit: 25,
+    });
+    expect(getPagination({ limit: '9999' }).limit).toBe(MAX_LIMIT);
+  });
+});
+
+describe('parseDto', () => {
+  const schema = z.object({ name: z.string().min(1) }).strict();
+
+  it('returns typed data', () => {
+    expect(parseDto(schema, { name: 'ok' })).toEqual({ name: 'ok' });
+  });
+
+  it('throws HttpError(400) with field errors, also for undefined input', () => {
+    try {
+      parseDto(schema, undefined);
+      fail('should throw');
+    } catch (err) {
+      expect(isHttpError(err)).toBe(true);
+      const e = err as HttpError;
+      expect(e.statusCode).toBe(400);
+      expect(e.details).toHaveProperty('name');
+    }
+  });
+});
+
+describe('resolvers', () => {
+  it('reads the package version', () => {
+    expect(getServiceVersion()).toMatch(/^\d+\.\d+\.\d+/);
+    expect(getServiceVersion()).toBe(getServiceVersion());
+  });
+  it('capitalizes the environment', () => {
+    expect(getServiceEnvironment()).toBe('Test');
+  });
+});

package/templates/api/src/common/config/env.ts

@@ -0,0 +1,53 @@
+import dotenv from 'dotenv';
+import { z } from 'zod';
+
+dotenv.config({ quiet: true });
+
+const LOG_LEVELS = [
+  'fatal',
+  'error',
+  'warn',
+  'info',
+  'debug',
+  'trace',
+  'silent',
+] as const;
+
+/**
+ * Every environment variable the app reads, validated once at boot. Add new variables
+ * here (with a default when sensible) so a misconfigured deploy fails fast and loudly.
+ */
+export const EnvSchema = z.object({
+  NODE_ENV: z
+    .enum(['development', 'test', 'production'])
+    .default('development'),
+  PORT: z.coerce.number().int().positive().default(__SF_PORT__),
+  LOG_LEVEL: z.enum(LOG_LEVELS).default('info'),
+  CORS_ORIGINS: z.string().default('*'),
+
+  SQL_HOST: z.string().default('localhost'),
+  SQL_PORT: z.coerce.number().int().positive().default(5432),
+  SQL_USER: z.string().min(1),
+  SQL_PASSWORD: z.string(),
+  SQL_DB_NAME: z.string().min(1),
+  SQL_REJECT_UNAUTHORIZED: z.stringbool().default(true),
+  RUN_MIGRATIONS: z.stringbool().default(false),
+  // @sundays:env-schema
+});
+
+export type Env = z.infer<typeof EnvSchema>;
+
+export const loadEnv = (source: NodeJS.ProcessEnv = process.env): Env => {
+  const result = EnvSchema.safeParse(source);
+  if (!result.success) {
+    throw new Error(
+      `Invalid environment configuration:\n${z.prettifyError(result.error)}`
+    );
+  }
+  return result.data;
+};
+
+export const env: Env = loadEnv();
+
+export const isProduction = (): boolean => env.NODE_ENV === 'production';
+export const isTest = (): boolean => env.NODE_ENV === 'test';

package/templates/api/src/common/errors/http.error.ts

@@ -0,0 +1,30 @@
+/**
+ * Error with an HTTP status. Throw it (or `next()` it) from anywhere in the request
+ * pipeline and the error middleware renders `{ success: false, message, errors? }`.
+ */
+export class HttpError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    message: string,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = 'HttpError';
+  }
+}
+
+export const badRequest = (
+  message = 'Bad request',
+  details?: unknown
+): HttpError => new HttpError(400, message, details);
+export const unauthorized = (message = 'Unauthorized'): HttpError =>
+  new HttpError(401, message);
+export const forbidden = (message = 'Forbidden'): HttpError =>
+  new HttpError(403, message);
+export const notFound = (message = 'Not found'): HttpError =>
+  new HttpError(404, message);
+export const conflict = (message = 'Conflict'): HttpError =>
+  new HttpError(409, message);
+
+export const isHttpError = (err: unknown): err is HttpError =>
+  err instanceof HttpError;

package/templates/api/src/common/logger/index.ts

@@ -0,0 +1,25 @@
+import pino, { type Logger } from 'pino';
+import { env } from '../config/env';
+
+/**
+ * Application logger. JSON in production (ship it to your log collector), pretty-printed
+ * elsewhere. Use `logger.child({ module: 'x' })` for per-module context, and `req.log`
+ * inside request handlers (pino-http attaches it with the request id).
+ */
+export const logger: Logger = pino({
+  level: env.LOG_LEVEL,
+  ...(env.NODE_ENV === 'development'
+    ? {
+        transport: {
+          target: 'pino-pretty',
+          options: {
+            colorize: true,
+            translateTime: 'HH:MM:ss',
+            ignore: 'pid,hostname',
+          },
+        },
+      }
+    : {}),
+});
+
+export type { Logger };

package/templates/api/src/common/utils/environment.resolver.ts

@@ -0,0 +1,7 @@
+import { env } from '../config/env';
+
+/** Capitalized NODE_ENV, for the health endpoint. */
+export const getServiceEnvironment = (): string => {
+  const value = env.NODE_ENV;
+  return value.charAt(0).toUpperCase() + value.slice(1);
+};

package/templates/api/src/common/utils/pagination.ts

@@ -0,0 +1,25 @@
+export interface IPaginationParams {
+  page: number;
+  limit: number;
+}
+
+export const DEFAULT_PAGE = 1;
+export const DEFAULT_LIMIT = 10;
+export const MAX_LIMIT = 100;
+
+/**
+ * Reads `?page=&limit=` from a query object. Missing, non numeric or < 1 values fall back
+ * to the defaults; `limit` is capped at MAX_LIMIT.
+ */
+export const getPagination = (
+  query: Record<string, unknown> | undefined
+): IPaginationParams => {
+  const rawPage = parseInt(String(query?.page ?? ''), 10);
+  const rawLimit = parseInt(String(query?.limit ?? ''), 10);
+  const page = Number.isNaN(rawPage) || rawPage < 1 ? DEFAULT_PAGE : rawPage;
+  const limit =
+    Number.isNaN(rawLimit) || rawLimit < 1
+      ? DEFAULT_LIMIT
+      : Math.min(rawLimit, MAX_LIMIT);
+  return { page, limit };
+};

package/templates/api/src/common/utils/version.resolver.ts

@@ -0,0 +1,24 @@
+import path from 'path';
+import fs from 'fs';
+
+let cached: string | null = null;
+
+/** Version from package.json (works from src/ under tsx and from dist/ once built). */
+export const getServiceVersion = (): string => {
+  if (cached) return cached;
+  const candidates = [
+    path.resolve(__dirname, '../../../package.json'),
+    path.resolve(process.cwd(), 'package.json'),
+  ];
+  for (const file of candidates) {
+    if (fs.existsSync(file)) {
+      const pkg = JSON.parse(fs.readFileSync(file, 'utf8')) as {
+        version?: string;
+      };
+      cached = pkg.version ?? '0.0.0';
+      return cached;
+    }
+  }
+  cached = '0.0.0';
+  return cached;
+};

package/templates/api/src/common/validation/parse-dto.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { HttpError } from '../errors/http.error';
+
+/**
+ * Validates `input` against a zod schema and returns the typed, sanitized value.
+ * On failure throws HttpError(400) whose `details` is `{ field: [messages] }`, rendered by
+ * the error middleware as `{ success: false, message: 'Validation failed', errors: {...} }`.
+ * Accepts `undefined` (Express 5 leaves req.body undefined when no parser matched).
+ */
+export const parseDto = <T>(schema: z.ZodType<T>, input: unknown): T => {
+  const result = schema.safeParse(input ?? {});
+  if (!result.success) {
+    throw new HttpError(
+      400,
+      'Validation failed',
+      z.flattenError(result.error).fieldErrors
+    );
+  }
+  return result.data;
+};

package/templates/api/src/controllers/health/__tests__/health.controller.test.ts

@@ -0,0 +1,52 @@
+import type { NextFunction, Request, Response } from 'express';
+import { HealthController } from '../health.controller';
+
+jest.mock('../../../common/utils/version.resolver', () => ({
+  getServiceVersion: jest.fn(() => '9.9.9'),
+}));
+jest.mock('../../../common/utils/environment.resolver', () => ({
+  getServiceEnvironment: jest.fn(() => 'Test'),
+}));
+
+/** Minimal chainable Response double, reused across controller unit tests. */
+export const mockRes = (): Response => {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+};
+
+describe('HealthController', () => {
+  it('responds with status, version and environment', async () => {
+    const controller = new HealthController();
+    const res = mockRes();
+    const next = jest.fn() as NextFunction;
+
+    await controller.getHealthStatus({} as Request, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        success: true,
+        health: 'Up!',
+        version: '9.9.9',
+        environment: 'Test',
+        database: 'disconnected',
+      })
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('forwards unexpected errors to next()', async () => {
+    const controller = new HealthController();
+    const res = mockRes();
+    (res.status as jest.Mock).mockImplementation(() => {
+      throw new Error('boom');
+    });
+    const next = jest.fn() as NextFunction;
+
+    await controller.getHealthStatus({} as Request, res, next);
+
+    expect(next).toHaveBeenCalledWith(expect.any(Error));
+  });
+});

package/templates/api/src/controllers/health/health.controller.ts

@@ -0,0 +1,26 @@
+import type { NextFunction, Request, Response } from 'express';
+import { getServiceEnvironment } from '../../common/utils/environment.resolver';
+import { getServiceVersion } from '../../common/utils/version.resolver';
+import KnexManager from '../../db/KnexConnection';
+
+export class HealthController {
+  /** GET /api/health */
+  public async getHealthStatus(
+    _req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> {
+    try {
+      res.status(200).json({
+        success: true,
+        health: 'Up!',
+        version: getServiceVersion(),
+        environment: getServiceEnvironment(),
+        database: KnexManager.isConnected() ? 'connected' : 'disconnected',
+        uptime: Math.round(process.uptime()),
+      });
+    } catch (err) {
+      next(err);
+    }
+  }
+}

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

@@ -0,0 +1,92 @@
+import { randomUUID } from 'crypto';
+import type { Knex } from 'knex';
+import KnexManager from './KnexConnection';
+import type { CreateInput, IBaseDAO, IDataPaginator, IEntity } from './d.types';
+
+/**
+ * Generic CRUD over one table. Subclasses only declare the table name and add their own
+ * finders:
+ *
+ *   export class ProductDAO extends BaseDAO<IProduct> {
+ *     protected readonly table = 'product';
+ *     getBySlug(slug: string) { return this.q().where({ slug }).first(); }
+ *   }
+ *
+ * Every method accepts an optional transaction so multi-table writes can share one:
+ *   await knex.transaction(async (trx) => { await dao.create(x, trx); ... });
+ */
+export abstract class BaseDAO<T extends IEntity> implements IBaseDAO<T> {
+  protected abstract readonly table: string;
+
+  /** Lazy: the DAO can be instantiated before KnexManager.connect() runs. */
+  protected get _knex(): Knex {
+    return KnexManager.getConnection();
+  }
+
+  /** Query builder on this table, bound to `trx` when given. */
+  protected q(trx?: Knex.Transaction): Knex.QueryBuilder {
+    return (trx ?? this._knex)(this.table);
+  }
+
+  async create(item: CreateInput<T>, trx?: Knex.Transaction): Promise<T> {
+    const [row] = await this.q(trx)
+      .insert({ ...item, uuid: randomUUID() })
+      .returning('*');
+    return row as T;
+  }
+
+  async getById(id: number, trx?: Knex.Transaction): Promise<T | null> {
+    const row = await this.q(trx).where({ id }).first();
+    return (row as T | undefined) ?? null;
+  }
+
+  async getByUuid(uuid: string, trx?: Knex.Transaction): Promise<T | null> {
+    const row = await this.q(trx).where({ uuid }).first();
+    return (row as T | undefined) ?? null;
+  }
+
+  async update(
+    id: number,
+    item: Partial<T>,
+    trx?: Knex.Transaction
+  ): Promise<T | null> {
+    const [row] = await this.q(trx)
+      .where({ id })
+      .update({ ...item, updatedAt: this._knex.fn.now() })
+      .returning('*');
+    return (row as T | undefined) ?? null;
+  }
+
+  async delete(id: number, trx?: Knex.Transaction): Promise<boolean> {
+    const deleted = await this.q(trx).where({ id }).delete();
+    return deleted > 0;
+  }
+
+  async getAll(
+    page: number,
+    limit: number,
+    trx?: Knex.Transaction
+  ): Promise<IDataPaginator<T>> {
+    const safePage = Math.max(page, 1);
+    const safeLimit = Math.max(limit, 1);
+    const offset = (safePage - 1) * safeLimit;
+
+    const [countRow] = await this.q(trx).count('* as count');
+    const totalCount = Number((countRow as { count: string | number }).count);
+    const data = (await this.q(trx)
+      .select('*')
+      .orderBy('id', 'desc')
+      .limit(safeLimit)
+      .offset(offset)) as T[];
+
+    return {
+      success: true,
+      data,
+      page: safePage,
+      limit: safeLimit,
+      count: data.length,
+      totalCount,
+      totalPages: Math.ceil(totalCount / safeLimit),
+    };
+  }
+}