create-appystack 0.1.0

package/template/server/src/index.ts

@@ -0,0 +1,118 @@
+import express from 'express';
+import { createServer } from 'node:http';
+import { join, dirname } from 'node:path'; // used for production static file serving below
+import { fileURLToPath } from 'node:url';
+import { Server } from 'socket.io';
+import helmet from 'helmet';
+import compression from 'compression';
+import cors from 'cors';
+import { env } from './config/env.js';
+import { logger } from './config/logger.js';
+import { requestLogger } from './middleware/requestLogger.js';
+import { errorHandler } from './middleware/errorHandler.js';
+import { apiLimiter } from './middleware/rateLimiter.js';
+import healthRouter from './routes/health.js';
+import infoRouter from './routes/info.js';
+import type { ServerToClientEvents, ClientToServerEvents } from '@appystack-template/shared';
+import { SOCKET_EVENTS } from '@appystack-template/shared';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const app = express();
+const httpServer = createServer(app);
+
+const io = new Server<ClientToServerEvents, ServerToClientEvents>(httpServer, {
+  cors: {
+    origin: env.CLIENT_URL,
+    methods: ['GET', 'POST'],
+  },
+});
+
+// Middleware
+app.use(helmet());
+app.use(compression());
+app.use(cors({ origin: env.CLIENT_URL }));
+app.use(express.json());
+app.use(requestLogger);
+
+// Rate limiting — apply before all routes
+app.use(apiLimiter);
+
+// Routes
+app.use(healthRouter);
+app.use(infoRouter);
+
+// Production static file serving — serve the built client app
+if (env.isProduction) {
+  const clientDist = join(__dirname, '../../client/dist');
+  app.use(express.static(clientDist));
+
+  // SPA fallback — serve index.html for all non-API routes
+  app.get('*splat', (_req, res) => {
+    res.sendFile(join(clientDist, 'index.html'));
+  });
+}
+
+// 404 catch-all — must be after all routes (only reached in non-production for unknown API routes)
+app.use((_req, res) => {
+  res.status(404).json({
+    status: 'error',
+    error: 'Not found',
+    timestamp: new Date().toISOString(),
+  });
+});
+
+// Global error handler — must be last middleware (4 params)
+app.use(errorHandler);
+
+// Socket.io
+io.on('connection', (socket) => {
+  // Auth pattern — uncomment and adapt for your app:
+  // const token = socket.handshake.auth.token as string | undefined;
+  // if (!token) { socket.disconnect(); return; }
+  // try {
+  //   const payload = verifyToken(token); // replace with your JWT verify function
+  //   socket.data.userId = payload.sub;
+  // } catch {
+  //   socket.disconnect();
+  //   return;
+  // }
+  logger.info({ socketId: socket.id }, 'Client connected');
+
+  socket.on(SOCKET_EVENTS.CLIENT_PING, () => {
+    logger.info({ socketId: socket.id }, 'Received client:ping');
+    socket.emit(SOCKET_EVENTS.SERVER_PONG, {
+      message: 'pong',
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  socket.on('disconnect', () => {
+    logger.info({ socketId: socket.id }, 'Client disconnected');
+  });
+});
+
+// Start server — skip in test environment to prevent EADDRINUSE when multiple
+// test files import this module. Tests use supertest with app directly.
+if (!env.isTest) {
+  httpServer.listen(env.PORT, () => {
+    logger.info(`Server running on http://localhost:${env.PORT}`);
+    logger.info(`Client URL: ${env.CLIENT_URL}`);
+  });
+}
+
+// Graceful shutdown
+const shutdown = () => {
+  logger.info('Shutting down gracefully...');
+  io.close();
+  httpServer.close(() => {
+    logger.info('Server closed');
+    process.exit(0);
+  });
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+export { app, httpServer };

package/template/server/src/middleware/errorHandler.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import request from 'supertest';
+import express, { type Request, type Response, type NextFunction } from 'express';
+import { AppError, errorHandler } from './errorHandler.js';
+
+function buildApp(thrower: (req: Request, res: Response, next: NextFunction) => void) {
+  const app = express();
+  app.get('/test', thrower);
+  app.use(errorHandler);
+  return app;
+}
+
+describe('AppError', () => {
+  it('stores statusCode and message', () => {
+    const err = new AppError(422, 'Unprocessable');
+    expect(err.statusCode).toBe(422);
+    expect(err.message).toBe('Unprocessable');
+  });
+
+  it('defaults isOperational to true', () => {
+    const err = new AppError(400, 'Bad input');
+    expect(err.isOperational).toBe(true);
+  });
+
+  it('allows isOperational to be set false', () => {
+    const err = new AppError(500, 'Crash', false);
+    expect(err.isOperational).toBe(false);
+  });
+
+  it('is an instance of Error', () => {
+    const err = new AppError(404, 'Not found');
+    expect(err).toBeInstanceOf(Error);
+  });
+});
+
+describe('errorHandler middleware', () => {
+  it('returns the AppError statusCode and message when isOperational is true', async () => {
+    const app = buildApp((_req, _res, next) => {
+      next(new AppError(404, 'Resource not found'));
+    });
+
+    const res = await request(app).get('/test');
+
+    expect(res.status).toBe(404);
+    expect(res.body.status).toBe('error');
+    expect(res.body.error).toBe('Resource not found');
+    expect(res.body.timestamp).toBeDefined();
+  });
+
+  it('returns 500 and generic message for non-operational AppError', async () => {
+    const app = buildApp((_req, _res, next) => {
+      next(new AppError(500, 'Internal detail', false));
+    });
+
+    const res = await request(app).get('/test');
+
+    expect(res.status).toBe(500);
+    expect(res.body.status).toBe('error');
+    expect(res.body.error).toBe('Internal server error');
+  });
+
+  it('returns 500 and generic message for unknown (non-AppError) errors', async () => {
+    const app = buildApp((_req, _res, next) => {
+      next(new Error('Unexpected crash'));
+    });
+
+    const res = await request(app).get('/test');
+
+    expect(res.status).toBe(500);
+    expect(res.body.status).toBe('error');
+    expect(res.body.error).toBe('Internal server error');
+  });
+
+  it('returns the correct status for a 403 AppError', async () => {
+    const app = buildApp((_req, _res, next) => {
+      next(new AppError(403, 'Forbidden'));
+    });
+
+    const res = await request(app).get('/test');
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toBe('Forbidden');
+  });
+});

package/template/server/src/middleware/errorHandler.ts

@@ -0,0 +1,27 @@
+import type { Request, Response, NextFunction } from 'express';
+import { logger } from '../config/logger.js';
+
+export class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+    public isOperational = true
+  ) {
+    super(message);
+    this.name = 'AppError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export function errorHandler(err: Error, _req: Request, res: Response, _next: NextFunction) {
+  const statusCode = err instanceof AppError ? err.statusCode : 500;
+  const isOperational = err instanceof AppError ? err.isOperational : false;
+
+  logger.error({ err, statusCode, isOperational }, err.message);
+
+  res.status(statusCode).json({
+    status: 'error',
+    error: isOperational ? err.message : 'Internal server error',
+    timestamp: new Date().toISOString(),
+  });
+}

package/template/server/src/middleware/rateLimiter.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import request from 'supertest';
+import express from 'express';
+import rateLimit from 'express-rate-limit';
+
+// Build a test-specific limiter with a very low limit so we can trigger 429 without
+// sending 100 real requests.
+function buildApp(limit: number) {
+  const testLimiter = rateLimit({
+    windowMs: 60 * 1000,
+    limit,
+    standardHeaders: 'draft-8',
+    legacyHeaders: false,
+  });
+
+  const app = express();
+  app.use(testLimiter);
+  app.get('/ping', (_req, res) => {
+    res.json({ ok: true });
+  });
+  return app;
+}
+
+describe('rateLimiter middleware', () => {
+  it('allows requests under the limit', async () => {
+    const app = buildApp(5);
+
+    const res = await request(app).get('/ping');
+
+    expect(res.status).toBe(200);
+    expect(res.body.ok).toBe(true);
+  });
+
+  it('returns 429 once the per-window limit is exceeded', async () => {
+    const app = buildApp(3);
+
+    // Send 3 allowed requests
+    for (let i = 0; i < 3; i++) {
+      const res = await request(app).get('/ping');
+      expect(res.status).toBe(200);
+    }
+
+    // The 4th request should be rate-limited
+    const limited = await request(app).get('/ping');
+    expect(limited.status).toBe(429);
+  });
+
+  it('includes RateLimit headers on successful responses', async () => {
+    const app = buildApp(10);
+
+    const res = await request(app).get('/ping');
+
+    // draft-8 headers use RateLimit-* format
+    expect(res.status).toBe(200);
+    // At least one rate-limit related header should be present
+    const headers = Object.keys(res.headers).join(' ').toLowerCase();
+    expect(headers).toMatch(/ratelimit/);
+  });
+
+  it('does not set legacy X-RateLimit headers', async () => {
+    const app = buildApp(10);
+
+    const res = await request(app).get('/ping');
+
+    expect(res.headers['x-ratelimit-limit']).toBeUndefined();
+    expect(res.headers['x-ratelimit-remaining']).toBeUndefined();
+  });
+});

package/template/server/src/middleware/rateLimiter.ts

@@ -0,0 +1,8 @@
+import rateLimit from 'express-rate-limit';
+
+export const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  limit: 100,
+  standardHeaders: 'draft-8',
+  legacyHeaders: false,
+});

package/template/server/src/middleware/requestLogger.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { requestLogger } from './requestLogger.js';
+import { logger } from '../config/logger.js';
+
+function buildApp() {
+  const app = express();
+  app.use(requestLogger);
+  app.get('/ok', (_req, res) => {
+    res.json({ ok: true });
+  });
+  app.get('/client-error', (_req, res) => {
+    res.status(404).json({ error: 'not found' });
+  });
+  app.get('/server-error', (_req, res) => {
+    res.status(500).json({ error: 'crash' });
+  });
+  app.get('/redirect', (_req, res) => {
+    res.status(301).redirect('/ok');
+  });
+  return app;
+}
+
+describe('requestLogger middleware', () => {
+  it('allows a successful request to pass through', async () => {
+    const res = await request(buildApp()).get('/ok');
+    expect(res.status).toBe(200);
+    expect(res.body.ok).toBe(true);
+  });
+
+  it('does not block 4xx responses', async () => {
+    const res = await request(buildApp()).get('/client-error');
+    expect(res.status).toBe(404);
+  });
+
+  it('does not block 5xx responses', async () => {
+    const res = await request(buildApp()).get('/server-error');
+    expect(res.status).toBe(500);
+  });
+
+  it('assigns a unique request id', async () => {
+    const app = buildApp();
+    const res1 = await request(app).get('/ok');
+    const res2 = await request(app).get('/ok');
+    // Both requests succeed; id is internal but pino-http attaches nothing to body
+    expect(res1.status).toBe(200);
+    expect(res2.status).toBe(200);
+  });
+});
+
+describe('requestLogger customLogLevel', () => {
+  // pino-http calls methods on a child logger created via logger.child({req}).
+  // We intercept logger.child to return a controlled mock so we can assert
+  // which log level method is actually invoked for each HTTP status code.
+
+  interface ChildMock {
+    info: ReturnType<typeof vi.fn>;
+    warn: ReturnType<typeof vi.fn>;
+    error: ReturnType<typeof vi.fn>;
+    child: ReturnType<typeof vi.fn>;
+  }
+
+  let childMock: ChildMock;
+
+  beforeEach(() => {
+    childMock = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      child: vi.fn(),
+    };
+    // child().child() may be called too — wire up nested child to same mock
+    childMock.child.mockReturnValue(childMock);
+    vi.spyOn(logger, 'child').mockReturnValue(
+      childMock as unknown as ReturnType<typeof logger.child>
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('logs at info level for 2xx responses', async () => {
+    await request(buildApp()).get('/ok');
+    expect(childMock.info).toHaveBeenCalled();
+    expect(childMock.warn).not.toHaveBeenCalled();
+    expect(childMock.error).not.toHaveBeenCalled();
+  });
+
+  it('logs at info level for 3xx responses', async () => {
+    await request(buildApp()).get('/redirect').redirects(0);
+    expect(childMock.info).toHaveBeenCalled();
+    expect(childMock.warn).not.toHaveBeenCalled();
+    expect(childMock.error).not.toHaveBeenCalled();
+  });
+
+  it('logs at warn level for 4xx responses', async () => {
+    await request(buildApp()).get('/client-error');
+    expect(childMock.warn).toHaveBeenCalled();
+    expect(childMock.info).not.toHaveBeenCalled();
+    expect(childMock.error).not.toHaveBeenCalled();
+  });
+
+  it('logs at error level for 5xx responses', async () => {
+    await request(buildApp()).get('/server-error');
+    expect(childMock.error).toHaveBeenCalled();
+    expect(childMock.info).not.toHaveBeenCalled();
+    expect(childMock.warn).not.toHaveBeenCalled();
+  });
+});

package/template/server/src/middleware/requestLogger.ts

@@ -0,0 +1,17 @@
+import pinoHttp from 'pino-http';
+import crypto from 'node:crypto';
+import { logger } from '../config/logger.js';
+
+export const requestLogger = pinoHttp({
+  logger,
+  genReqId: () => crypto.randomUUID(),
+  customLogLevel: (_req, res) => {
+    const status = res.statusCode;
+    if (status >= 500) return 'error';
+    if (status >= 400) return 'warn';
+    return 'info';
+  },
+  customSuccessMessage: (req, res) => {
+    return `${req.method} ${req.url} ${res.statusCode}`;
+  },
+});

package/template/server/src/middleware/validate.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect } from 'vitest';
+import request from 'supertest';
+import express, { type Request, type Response, type NextFunction } from 'express';
+import { z } from 'zod';
+import { validate } from './validate.js';
+
+// Attach a catch-all error handler so unhandled errors produce a JSON body for assertions
+function withErrorHandler(app: ReturnType<typeof express>) {
+  app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
+    res.status(500).json({ status: 'error', error: err.message });
+  });
+  return app;
+}
+
+const nameSchema = z.object({ name: z.string().min(1) });
+const paramsSchema = z.object({ id: z.string().uuid() });
+
+function buildBodyApp() {
+  const app = express();
+  app.use(express.json());
+  app.post('/items', validate({ body: nameSchema }), (req, res) => {
+    res.json({ received: req.body });
+  });
+  return withErrorHandler(app);
+}
+
+function buildParamsApp() {
+  const app = express();
+  app.get('/items/:id', validate({ params: paramsSchema }), (req, res) => {
+    res.json({ id: req.params.id });
+  });
+  return withErrorHandler(app);
+}
+
+// Query-only validation: Zod parses req.query without mutating it.
+// We verify invalid inputs are rejected with 400 (Zod error path).
+// We do not test valid-input body passthrough here because req.query
+// is a getter-only property in Express 5 / Node's IncomingMessage;
+// assigning the parsed value would throw TypeError.
+function buildQueryValidationApp() {
+  const querySchema = z.object({ page: z.string().regex(/^\d+$/, 'must be digits only') });
+  const app = express();
+  app.get('/items', validate({ query: querySchema }), (_req, res) => {
+    res.json({ ok: true });
+  });
+  return withErrorHandler(app);
+}
+
+describe('validate middleware — body', () => {
+  const app = buildBodyApp();
+
+  it('passes valid body to the route handler', async () => {
+    const res = await request(app)
+      .post('/items')
+      .send({ name: 'Widget' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(200);
+    expect(res.body.received.name).toBe('Widget');
+  });
+
+  it('returns 400 with Zod errors when body field fails validation', async () => {
+    const res = await request(app)
+      .post('/items')
+      .send({ name: '' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(typeof res.body.error).toBe('string');
+    expect(res.body.timestamp).toBeDefined();
+  });
+
+  it('returns 400 when required body field is missing', async () => {
+    const res = await request(app).post('/items').send({}).set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(typeof res.body.error).toBe('string');
+  });
+});
+
+describe('validate middleware — query', () => {
+  const app = buildQueryValidationApp();
+
+  it('returns 400 with Zod errors when query parameter fails validation', async () => {
+    const res = await request(app).get('/items?page=abc');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(typeof res.body.error).toBe('string');
+  });
+
+  it('returns 400 when required query parameter is missing', async () => {
+    const res = await request(app).get('/items');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+  });
+});
+
+describe('validate middleware — params', () => {
+  const app = buildParamsApp();
+
+  it('passes valid UUID param to the route handler', async () => {
+    const uuid = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
+    const res = await request(app).get(`/items/${uuid}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.id).toBe(uuid);
+  });
+
+  it('returns 400 with Zod errors for invalid UUID param', async () => {
+    const res = await request(app).get('/items/not-a-uuid');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(typeof res.body.error).toBe('string');
+  });
+});
+
+// Multi-schema validation: body + query validated together in a single middleware call
+const multiBodySchema = z.object({ name: z.string().min(1) });
+const multiQuerySchema = z.object({ page: z.string().regex(/^\d+$/, 'must be digits only') });
+
+function buildMultiSchemaApp() {
+  const app = express();
+  app.use(express.json());
+  app.post('/multi', validate({ body: multiBodySchema, query: multiQuerySchema }), (req, res) => {
+    res.json({ name: req.body.name, page: req.query['page'] });
+  });
+  return withErrorHandler(app);
+}
+
+describe('validate middleware — multi-schema (body + query)', () => {
+  const app = buildMultiSchemaApp();
+
+  it('passes when both body and query satisfy their schemas', async () => {
+    const res = await request(app)
+      .post('/multi?page=1')
+      .send({ name: 'Widget' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(200);
+    expect(res.body.name).toBe('Widget');
+    expect(res.body.page).toBe('1');
+  });
+
+  it('returns 400 when body fails validation but query is valid', async () => {
+    const res = await request(app)
+      .post('/multi?page=1')
+      .send({ name: '' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(typeof res.body.error).toBe('string');
+  });
+
+  it('returns 400 when query fails validation but body is valid', async () => {
+    const res = await request(app)
+      .post('/multi?page=abc')
+      .send({ name: 'Widget' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(typeof res.body.error).toBe('string');
+  });
+
+  it('returns 400 when both body and query fail validation', async () => {
+    const res = await request(app)
+      .post('/multi?page=abc')
+      .send({ name: '' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(typeof res.body.error).toBe('string');
+  });
+});
+
+// Non-Zod error propagation: schema throws a plain Error → next(err) rather than 400
+function buildThrowingApp() {
+  const throwingSchema = {
+    parse: () => {
+      throw new Error('unexpected schema failure');
+    },
+  } as unknown as z.ZodType;
+
+  const app = express();
+  app.use(express.json());
+  app.post('/throw', validate({ body: throwingSchema }), (_req, res) => {
+    res.json({ ok: true });
+  });
+  return withErrorHandler(app);
+}
+
+describe('validate middleware — non-Zod error propagation', () => {
+  const app = buildThrowingApp();
+
+  it('calls next(err) and reaches the error handler when schema throws a plain Error', async () => {
+    const res = await request(app)
+      .post('/throw')
+      .send({ any: 'data' })
+      .set('Content-Type', 'application/json');
+
+    // The catch-all error handler (added by withErrorHandler) returns 500 for non-Zod errors
+    expect(res.status).toBe(500);
+    expect(res.body.status).toBe('error');
+    expect(res.body.error).toBe('unexpected schema failure');
+  });
+});

package/template/server/src/middleware/validate.ts

@@ -0,0 +1,23 @@
+import { z, ZodError } from 'zod';
+import type { Request, Response, NextFunction } from 'express';
+
+export function validate(schema: { body?: z.ZodType; query?: z.ZodType; params?: z.ZodType }) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    try {
+      if (schema.body) req.body = schema.body.parse(req.body);
+      // Express 5: req.query is a getter — use Object.assign to mutate in place
+      if (schema.query) Object.assign(req.query, schema.query.parse(req.query));
+      if (schema.params) req.params = schema.params.parse(req.params);
+      next();
+    } catch (err) {
+      if (err instanceof ZodError) {
+        const message = err.errors.map((e) => e.message).join('; ');
+        res
+          .status(400)
+          .json({ status: 'error', error: message, timestamp: new Date().toISOString() });
+        return;
+      }
+      next(err);
+    }
+  };
+}

package/template/server/src/routes/health.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import request from 'supertest';
+import express from 'express';
+import healthRouter from './health.js';
+
+const app = express();
+app.use(healthRouter);
+
+describe('GET /health', () => {
+  it('returns ok status', async () => {
+    const res = await request(app).get('/health');
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('ok');
+    expect(res.body.timestamp).toBeDefined();
+    expect(res.body.data.status).toBe('ok');
+  });
+});