@sundaysf/cli-v3 0.0.1

package/templates/api/src/middlewares/request-id/__tests__/request-id.middleware.test.ts

@@ -0,0 +1,31 @@
+import type { NextFunction, Request, Response } from 'express';
+import { requestIdMiddleware } from '../request-id.middleware';
+
+const build = (incoming?: string) => {
+  const req = { header: jest.fn(() => incoming) } as unknown as Request;
+  const res = { setHeader: jest.fn() } as unknown as Response;
+  const next = jest.fn() as NextFunction;
+  return { req, res, next };
+};
+
+describe('requestIdMiddleware', () => {
+  it('generates a uuid when no header is present', () => {
+    const { req, res, next } = build();
+    requestIdMiddleware(req, res, next);
+    expect(req.id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(res.setHeader).toHaveBeenCalledWith('x-request-id', req.id);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('reuses a sane incoming header', () => {
+    const { req, res, next } = build('trace-42');
+    requestIdMiddleware(req, res, next);
+    expect(req.id).toBe('trace-42');
+  });
+
+  it('ignores an oversized incoming header', () => {
+    const { req, res, next } = build('x'.repeat(200));
+    requestIdMiddleware(req, res, next);
+    expect(req.id).not.toBe('x'.repeat(200));
+  });
+});

package/templates/api/src/middlewares/request-id/request-id.middleware.ts

@@ -0,0 +1,20 @@
+import { randomUUID } from 'crypto';
+import type { NextFunction, Request, Response } from 'express';
+
+export const REQUEST_ID_HEADER = 'x-request-id';
+
+/**
+ * Gives every request an id (honouring an incoming X-Request-Id from a proxy) and echoes
+ * it back so clients and logs can be correlated. pino-http picks it up via genReqId.
+ */
+export const requestIdMiddleware = (
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void => {
+  const incoming = req.header(REQUEST_ID_HEADER);
+  const id = incoming && incoming.length <= 128 ? incoming : randomUUID();
+  req.id = id;
+  res.setHeader(REQUEST_ID_HEADER, id);
+  next();
+};

package/templates/api/src/migrations/20240101000000_create_sundays_package_version.ts

@@ -0,0 +1,15 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('sundays_package_version', (table) => {
+    table.increments('id').primary();
+    table.uuid('uuid').notNullable().unique();
+    table.string('versionName').notNullable();
+    table.timestamp('createdAt').notNullable().defaultTo(knex.fn.now());
+    table.timestamp('updatedAt').notNullable().defaultTo(knex.fn.now());
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('sundays_package_version');
+}

package/templates/api/src/routes/__tests__/index-router.test.ts

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+import express from 'express';
+import request from 'supertest';
+import { IndexRouter } from '..';
+
+const write = (file: string, content: string): void => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+};
+
+describe('IndexRouter auto-discovery', () => {
+  let dir: string;
+
+  // Fixtures live inside the project so ts-jest can resolve 'express'. The folder name
+  // starts with "_" so a real IndexRouter scan of src/routes ignores it (and __tests__).
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(__dirname, '_fixtures-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('mounts <folder>/<folder>.router at /<folder> and ignores _ and . folders', async () => {
+    write(
+      path.join(dir, 'ping', 'ping.router.ts'),
+      `import { Router, type Request, type Response } from 'express';
+       export class PingRouter {
+         public router = Router();
+         constructor() {
+           this.router.get('/', (_req: Request, res: Response) => { res.json({ ok: true }); });
+         }
+       }`
+    );
+    write(path.join(dir, '__tests__', '__tests__.router.ts'), 'export {};');
+    write(path.join(dir, '.hidden', '.hidden.router.ts'), 'export {};');
+    write(path.join(dir, 'empty', 'README.md'), '# no router here');
+
+    const app = express().use('/api', new IndexRouter(dir).router);
+    const ok = await request(app).get('/api/ping');
+    expect(ok.status).toBe(200);
+    expect(ok.body).toEqual({ ok: true });
+
+    expect((await request(app).get('/api/__tests__')).status).toBe(404);
+    expect((await request(app).get('/api/empty')).status).toBe(404);
+  });
+
+  it('skips modules that export no class', () => {
+    write(path.join(dir, 'noop', 'noop.router.ts'), 'export const value = 42;');
+    expect(() => new IndexRouter(dir)).not.toThrow();
+  });
+
+  it('rethrows when a router module fails to load', () => {
+    write(
+      path.join(dir, 'broken', 'broken.router.ts'),
+      'throw new Error("bad module");\nexport {};'
+    );
+    expect(() => new IndexRouter(dir)).toThrow('bad module');
+  });
+});

package/templates/api/src/routes/health/__tests__/health.routes.test.ts

@@ -0,0 +1,22 @@
+import request from 'supertest';
+import app from '../../../app';
+
+// No database needed: health does not query Postgres.
+describe('GET /api/health', () => {
+  it('returns the standard envelope with a request id header', async () => {
+    const res = await request(app).get('/api/health');
+
+    expect(res.status).toBe(200);
+    expect(res.body.success).toBe(true);
+    expect(res.body.health).toBe('Up!');
+    expect(typeof res.body.version).toBe('string');
+    expect(res.headers['x-request-id']).toBeDefined();
+  });
+
+  it('echoes an incoming X-Request-Id', async () => {
+    const res = await request(app)
+      .get('/api/health')
+      .set('X-Request-Id', 'abc-123');
+    expect(res.headers['x-request-id']).toBe('abc-123');
+  });
+});

package/templates/api/src/routes/health/health.router.ts

@@ -0,0 +1,18 @@
+import { Router } from 'express';
+import { HealthController } from '../../controllers/health/health.controller';
+
+export class HealthRouter {
+  public router: Router = Router();
+  private readonly _healthController = new HealthController();
+
+  constructor() {
+    this.initRoutes();
+  }
+
+  private initRoutes(): void {
+    this.router.get(
+      '/',
+      this._healthController.getHealthStatus.bind(this._healthController)
+    );
+  }
+}

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

@@ -0,0 +1,77 @@
+import fs from 'fs';
+import path from 'path';
+import { Router } from 'express';
+import { logger } from '../common/logger';
+
+/**
+ * Router auto-discovery. Every direct subfolder of src/routes/ that contains a
+ * `<folder>/<folder>.router.ts` is mounted at `/api/<folder>`:
+ *
+ *   src/routes/products/products.router.ts  ->  /api/products
+ *
+ * The file must export a class whose instances expose a `router: Router` property
+ * (default export or first exported class). Folders starting with "_" or "." are ignored.
+ */
+export class IndexRouter {
+  public readonly router: Router = Router();
+
+  constructor(private readonly routesDir: string = __dirname) {
+    this.loadRoutes();
+  }
+
+  /** '.ts' under tsx / ts-jest, '.js' from dist/. */
+  private get extension(): string {
+    return path.extname(__filename) || '.js';
+  }
+
+  private loadRoutes(): void {
+    const folders = fs
+      .readdirSync(this.routesDir, { withFileTypes: true })
+      .filter(
+        (d) =>
+          d.isDirectory() && !d.name.startsWith('_') && !d.name.startsWith('.')
+      )
+      .map((d) => d.name)
+      .sort();
+    const mounted: string[] = [];
+
+    for (const folder of folders) {
+      const file = path.join(
+        this.routesDir,
+        folder,
+        `${folder}.router${this.extension}`
+      );
+      if (!fs.existsSync(file)) {
+        logger.warn(
+          `[routes] no ${folder}.router${this.extension} found in routes/${folder}, skipped`
+        );
+        continue;
+      }
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require(file) as Record<string, unknown>;
+        const RouterClass = (mod.default ??
+          Object.values(mod).find((e) => typeof e === 'function')) as
+          (new () => { router: Router }) | undefined;
+        if (!RouterClass) {
+          logger.warn(
+            `[routes] ${path.basename(file)} exports no router class, skipped`
+          );
+          continue;
+        }
+        this.router.use(`/${folder}`, new RouterClass().router);
+        logger.info(
+          `[routes] mounted /api/${folder} -> ${path.basename(file)}`
+        );
+        mounted.push(`/api/${folder}`);
+      } catch (err) {
+        logger.error({ err }, `[routes] failed to load ${file}`);
+        throw err;
+      }
+    }
+    logger.info(
+      { routes: mounted },
+      `[routes] ${mounted.length} router(s) mounted`
+    );
+  }
+}

package/templates/api/src/seeds/001_sundays_package_version.ts

@@ -0,0 +1,14 @@
+import { randomUUID } from 'crypto';
+import type { Knex } from 'knex';
+
+export async function seed(knex: Knex): Promise<void> {
+  const existing = await knex('sundays_package_version')
+    .where({ versionName: '__SF_CLI_VERSION__' })
+    .first();
+  if (!existing) {
+    await knex('sundays_package_version').insert({
+      uuid: randomUUID(),
+      versionName: '__SF_CLI_VERSION__',
+    });
+  }
+}

package/templates/api/src/server.ts

@@ -0,0 +1,56 @@
+import { env } from './common/config/env';
+import { logger } from './common/logger';
+import KnexManager from './db/KnexConnection';
+
+const SHUTDOWN_TIMEOUT_MS = 10_000;
+
+const main = async (): Promise<void> => {
+  await KnexManager.connect();
+
+  if (env.RUN_MIGRATIONS) {
+    const [batch, applied] = await KnexManager.getConnection().migrate.latest();
+    if (applied.length) {
+      logger.info(
+        { batch, applied },
+        `[migrations] batch ${batch}: ${applied.length} applied`
+      );
+    } else {
+      logger.info('[migrations] up to date');
+    }
+  }
+
+  // app.ts is imported after the connection exists so nothing at module scope can hit
+  // the database before it is ready.
+  const { default: app } = await import('./app');
+  const server = app.listen(env.PORT, () => {
+    logger.info(
+      { port: env.PORT, env: env.NODE_ENV },
+      `API listening on http://localhost:${env.PORT}`
+    );
+  });
+
+  const shutdown = (signal: NodeJS.Signals): void => {
+    logger.info({ signal }, 'Shutting down');
+    server.close(async () => {
+      try {
+        await KnexManager.disconnect();
+        process.exit(0);
+      } catch (err) {
+        logger.error({ err }, 'Error during shutdown');
+        process.exit(1);
+      }
+    });
+    setTimeout(() => {
+      logger.warn('Forcing exit after shutdown timeout');
+      process.exit(1);
+    }, SHUTDOWN_TIMEOUT_MS).unref();
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+};
+
+main().catch((err: unknown) => {
+  logger.fatal({ err }, 'Failed to start');
+  process.exit(1);
+});

package/templates/api/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**", "**/*.test.ts"]
+}

package/templates/api/tsconfig.spec.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node", "jest"],
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["src/**/*", "knexfile.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/api-auth/overlay.json

@@ -0,0 +1,95 @@
+{
+  "packageJson": {
+    "dependencies": {
+      "bcryptjs": "^3.0.3",
+      "jsonwebtoken": "^9.0.3"
+    },
+    "devDependencies": {
+      "@types/jsonwebtoken": "^9.0.10"
+    }
+  },
+  "inject": [
+    {
+      "file": "src/db/index.ts",
+      "marker": "// @sundays:interfaces",
+      "lines": [
+        "export type { IUser, IPublicUser } from './interfaces/user/user.interfaces';",
+        "export type { IAuth } from './interfaces/auth/auth.interfaces';"
+      ]
+    },
+    {
+      "file": "src/db/index.ts",
+      "marker": "// @sundays:daos",
+      "lines": [
+        "export { UserDAO } from './dao/user/user.dao';",
+        "export { AuthDAO } from './dao/auth/auth.dao';"
+      ]
+    },
+    {
+      "file": "src/common/config/env.ts",
+      "marker": "// @sundays:env-schema",
+      "lines": [
+        "  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),",
+        "  JWT_EXPIRES_IN: z.string().default('7d'),"
+      ]
+    },
+    {
+      "file": ".env.example",
+      "marker": "# @sundays:env",
+      "lines": [
+        "# Auth (JWT). sundaysf new wrote a random secret to .env; keep it out of git.",
+        "JWT_SECRET=__SF_JWT_SECRET__",
+        "JWT_EXPIRES_IN=7d",
+        ""
+      ]
+    },
+    {
+      "file": ".github/workflows/ci.yaml",
+      "marker": "# @sundays:ci-env",
+      "lines": [
+        "      JWT_SECRET: ci-only-secret-not-used-anywhere-else-0123456789"
+      ]
+    },
+    {
+      "file": "README.md",
+      "marker": "<!-- @sundays:readme-env -->",
+      "lines": [
+        "| `JWT_SECRET` | (generated) | Secret used to sign access tokens. At least 32 characters. |",
+        "| `JWT_EXPIRES_IN` | `7d` | Access token lifetime (`60`, `1h`, `7d`...). |"
+      ]
+    },
+    {
+      "file": "README.md",
+      "marker": "<!-- @sundays:readme-endpoints -->",
+      "lines": [
+        "### Auth",
+        "",
+        "| Method | Path | Auth | Body |",
+        "|---|---|---|---|",
+        "| POST | `/api/auth/register` | no | `{ email, password, firstName, lastName }` |",
+        "| POST | `/api/auth/login` | no | `{ email, password }` |",
+        "| GET | `/api/auth/me` | Bearer | - |",
+        "",
+        "Register and login answer `{ success: true, data: { token, user } }`. Send the token as",
+        "`Authorization: Bearer <token>`; `authMiddleware` puts the payload in `req.auth`.",
+        "Protect any route by adding the middleware before the handler:",
+        "",
+        "```ts",
+        "this.router.get('/', authMiddleware, this._controller.getAll.bind(this._controller));",
+        "```",
+        ""
+      ]
+    },
+    {
+      "file": "CLAUDE.md",
+      "marker": "<!-- @sundays:features -->",
+      "lines": [
+        "- **Auth**: `POST /api/auth/register|login`, `GET /api/auth/me`. JWT signed by `JwtService`",
+        "  (`src/services/jwt`), passwords hashed by `PasswordService` (bcryptjs). Protect routes with",
+        "  `authMiddleware` from `src/middlewares/auth/auth.middleware.ts`, which sets `req.auth`",
+        "  (`{ sub: user uuid, userId, email }`). Tables: `user` (profile) and `auth` (credentials, 1:1).",
+        ""
+      ]
+    }
+  ]
+}

package/templates/api-auth/src/controllers/auth/__tests__/auth.controller.test.ts

@@ -0,0 +1,194 @@
+import type { NextFunction, Request, Response } from 'express';
+import { HttpError } from '../../../common/errors/http.error';
+
+const mockUserDao = {
+  getByEmail: jest.fn(),
+  getByUuid: jest.fn(),
+  create: jest.fn(),
+};
+const mockAuthDao = {
+  getByUserId: jest.fn(),
+  create: jest.fn(),
+  touchLastLogin: jest.fn(),
+};
+const mockTrx = jest.fn(async (fn: (trx: unknown) => Promise<unknown>) =>
+  fn('trx')
+);
+
+jest.mock('../../../db', () => ({
+  UserDAO: Object.assign(
+    jest.fn(() => mockUserDao),
+    { toPublic: (u: Record<string, unknown>) => ({ ...u, id: undefined }) }
+  ),
+  AuthDAO: jest.fn(() => mockAuthDao),
+  KnexManager: { getConnection: () => ({ transaction: mockTrx }) },
+}));
+
+import { AuthController } from '../auth.controller';
+import { JwtService } from '../../../services/jwt/jwt.service';
+
+const mockRes = (): Response => {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+};
+const user = {
+  id: 1,
+  uuid: 'uuid-1',
+  email: 'a@b.co',
+  firstName: 'A',
+  lastName: 'B',
+  isActive: true,
+};
+const body = {
+  email: 'A@b.co',
+  password: 'secret123',
+  firstName: 'A',
+  lastName: 'B',
+};
+
+describe('AuthController', () => {
+  const controller = new AuthController();
+  let next: jest.MockedFunction<NextFunction>;
+  beforeEach(() => {
+    jest.clearAllMocks();
+    next = jest.fn();
+  });
+  const errorOf = () => next.mock.calls[0][0] as unknown as HttpError;
+
+  describe('register', () => {
+    it('creates user + auth in a transaction and returns a token', async () => {
+      mockUserDao.getByEmail.mockResolvedValue(null);
+      mockUserDao.create.mockResolvedValue(user);
+      mockAuthDao.create.mockResolvedValue({ id: 9 });
+      const res = mockRes();
+
+      await controller.register({ body } as Request, res, next);
+
+      expect(mockUserDao.getByEmail).toHaveBeenCalledWith('a@b.co');
+      expect(mockUserDao.create).toHaveBeenCalledWith(
+        { email: 'a@b.co', firstName: 'A', lastName: 'B' },
+        'trx'
+      );
+      expect(mockAuthDao.create).toHaveBeenCalledWith(
+        { userId: 1, password: expect.stringMatching(/^\$2/) },
+        'trx'
+      );
+      expect(res.status).toHaveBeenCalledWith(201);
+      const payload = (res.json as jest.Mock).mock.calls[0][0];
+      expect(payload.success).toBe(true);
+      expect(new JwtService().verify(payload.data.token)).toEqual({
+        sub: 'uuid-1',
+        userId: 1,
+        email: 'a@b.co',
+      });
+      expect(payload.data.user.id).toBeUndefined();
+    });
+
+    it('rejects invalid input with 400', async () => {
+      await controller.register(
+        { body: { email: 'nope' } } as Request,
+        mockRes(),
+        next
+      );
+      expect(errorOf().statusCode).toBe(400);
+    });
+
+    it('rejects a duplicate email with 409', async () => {
+      mockUserDao.getByEmail.mockResolvedValue(user);
+      await controller.register({ body } as Request, mockRes(), next);
+      expect(errorOf().statusCode).toBe(409);
+    });
+  });
+
+  describe('login', () => {
+    const hash = '$2a$04$Z9mcz8kqW0K2q4YwJ8zvIe6z0qYqQm4L2dHfM9Yd3n9J6b0Z0m6Wu'; // placeholder, compare is mocked below
+
+    it('returns a token for valid credentials', async () => {
+      mockUserDao.getByEmail.mockResolvedValue(user);
+      mockAuthDao.getByUserId.mockResolvedValue({
+        id: 9,
+        userId: 1,
+        password: hash,
+      });
+      const spy = jest
+        .spyOn(controller['_passwordService'], 'compare')
+        .mockResolvedValue(true);
+      const res = mockRes();
+
+      await controller.login(
+        { body: { email: 'a@b.co', password: 'secret123' } } as Request,
+        res,
+        next
+      );
+
+      expect(spy).toHaveBeenCalledWith('secret123', hash);
+      expect(mockAuthDao.touchLastLogin).toHaveBeenCalledWith(9);
+      expect(res.status).toHaveBeenCalledWith(200);
+      expect((res.json as jest.Mock).mock.calls[0][0].data.token).toEqual(
+        expect.any(String)
+      );
+    });
+
+    it.each([
+      ['unknown email', null, null, false],
+      ['wrong password', user, { id: 9, userId: 1, password: hash }, false],
+    ])('answers 401 for %s', async (_label, foundUser, foundAuth, cmp) => {
+      mockUserDao.getByEmail.mockResolvedValue(foundUser);
+      mockAuthDao.getByUserId.mockResolvedValue(foundAuth);
+      jest
+        .spyOn(controller['_passwordService'], 'compare')
+        .mockResolvedValue(cmp);
+      await controller.login(
+        { body: { email: 'a@b.co', password: 'x' } } as Request,
+        mockRes(),
+        next
+      );
+      expect(errorOf().statusCode).toBe(401);
+      expect(errorOf().message).toBe('Invalid credentials');
+    });
+
+    it('answers 401 for a disabled account', async () => {
+      mockUserDao.getByEmail.mockResolvedValue({ ...user, isActive: false });
+      mockAuthDao.getByUserId.mockResolvedValue({
+        id: 9,
+        userId: 1,
+        password: hash,
+      });
+      jest
+        .spyOn(controller['_passwordService'], 'compare')
+        .mockResolvedValue(true);
+      await controller.login(
+        { body: { email: 'a@b.co', password: 'x' } } as Request,
+        mockRes(),
+        next
+      );
+      expect(errorOf().message).toBe('Account is disabled');
+    });
+  });
+
+  describe('me', () => {
+    it('returns the public user', async () => {
+      mockUserDao.getByUuid.mockResolvedValue(user);
+      const res = mockRes();
+      await controller.me(
+        { auth: { sub: 'uuid-1', userId: 1, email: 'a@b.co' } } as Request,
+        res,
+        next
+      );
+      expect(mockUserDao.getByUuid).toHaveBeenCalledWith('uuid-1');
+      expect(res.status).toHaveBeenCalledWith(200);
+    });
+
+    it('answers 404 when the user vanished', async () => {
+      mockUserDao.getByUuid.mockResolvedValue(null);
+      await controller.me(
+        { auth: { sub: 'gone', userId: 1, email: 'a@b.co' } } as Request,
+        mockRes(),
+        next
+      );
+      expect(errorOf().statusCode).toBe(404);
+    });
+  });
+});