create-appystack 0.1.0

package/template/scripts/customize.ts

@@ -0,0 +1,175 @@
+import { intro, outro, text, cancel, isCancel } from '@clack/prompts';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+function readFile(relPath: string): string {
+  return readFileSync(resolve(ROOT, relPath), 'utf-8');
+}
+
+function writeFile(relPath: string, content: string): void {
+  writeFileSync(resolve(ROOT, relPath), content, 'utf-8');
+}
+
+function replaceAll(content: string, from: string, to: string): string {
+  return content.split(from).join(to);
+}
+
+async function main(): Promise<void> {
+  intro('AppyStack Template Customization');
+
+  const projectName = await text({
+    message: 'Project name (e.g. my-app)',
+    placeholder: 'my-app',
+    validate(value) {
+      if (!value || value.trim().length === 0) return 'Project name is required';
+      if (!/^[a-z0-9-]+$/.test(value.trim()))
+        return 'Use lowercase letters, numbers, and hyphens only';
+    },
+  });
+  if (isCancel(projectName)) {
+    cancel('Customization cancelled.');
+    process.exit(0);
+  }
+
+  const packageScope = await text({
+    message: 'Package scope (e.g. @myorg)',
+    placeholder: '@myorg',
+    validate(value) {
+      if (!value || value.trim().length === 0) return 'Package scope is required';
+      if (!value.trim().startsWith('@')) return 'Scope must start with @';
+      if (!/^@[a-z0-9-]+$/.test(value.trim())) return 'Use @lowercase-letters-numbers-hyphens only';
+    },
+  });
+  if (isCancel(packageScope)) {
+    cancel('Customization cancelled.');
+    process.exit(0);
+  }
+
+  const serverPortInput = await text({
+    message: 'Server port',
+    placeholder: '5501',
+    initialValue: '5501',
+    validate(value) {
+      const port = Number(value);
+      if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return 'Enter a valid port number (1–65535)';
+    },
+  });
+  if (isCancel(serverPortInput)) {
+    cancel('Customization cancelled.');
+    process.exit(0);
+  }
+
+  const clientPortInput = await text({
+    message: 'Client port',
+    placeholder: '5500',
+    initialValue: '5500',
+    validate(value) {
+      const port = Number(value);
+      if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return 'Enter a valid port number (1–65535)';
+    },
+  });
+  if (isCancel(clientPortInput)) {
+    cancel('Customization cancelled.');
+    process.exit(0);
+  }
+
+  const description = await text({
+    message: 'Project description',
+    placeholder: 'My awesome app',
+    validate(value) {
+      if (!value || value.trim().length === 0) return 'Description is required';
+    },
+  });
+  if (isCancel(description)) {
+    cancel('Customization cancelled.');
+    process.exit(0);
+  }
+
+  const name = (projectName as string).trim();
+  const scope = (packageScope as string).trim();
+  const serverPort = (serverPortInput as string).trim();
+  const clientPort = (clientPortInput as string).trim();
+  const desc = (description as string).trim();
+
+  const oldScope = '@appystack-template';
+  const oldRootName = '@appydave/appystack-template';
+  const oldServerPort = '5501';
+  const oldClientPort = '5500';
+  const oldTitle = 'AppyStack Template';
+  const oldDescription = 'RVETS stack boilerplate (React, Vite, Express, TypeScript, Socket.io)';
+
+  // --- Root package.json ---
+  let rootPkg = readFile('package.json');
+  rootPkg = replaceAll(rootPkg, oldRootName, `${scope}/${name}`);
+  rootPkg = replaceAll(rootPkg, oldDescription, desc);
+  writeFile('package.json', rootPkg);
+
+  // --- shared/package.json ---
+  let sharedPkg = readFile('shared/package.json');
+  sharedPkg = replaceAll(sharedPkg, oldScope, scope);
+  writeFile('shared/package.json', sharedPkg);
+
+  // --- server/package.json ---
+  let serverPkg = readFile('server/package.json');
+  serverPkg = replaceAll(serverPkg, oldScope, scope);
+  writeFile('server/package.json', serverPkg);
+
+  // --- client/package.json ---
+  let clientPkg = readFile('client/package.json');
+  clientPkg = replaceAll(clientPkg, oldScope, scope);
+  writeFile('client/package.json', clientPkg);
+
+  // --- .env.example ---
+  let envExample = readFile('.env.example');
+  envExample = replaceAll(envExample, `PORT=${oldServerPort}`, `PORT=${serverPort}`);
+  envExample = replaceAll(
+    envExample,
+    `CLIENT_URL=http://localhost:${oldClientPort}`,
+    `CLIENT_URL=http://localhost:${clientPort}`
+  );
+  writeFile('.env.example', envExample);
+
+  // --- server/src/config/env.ts ---
+  let envTs = readFile('server/src/config/env.ts');
+  envTs = replaceAll(
+    envTs,
+    `PORT: z.coerce.number().default(${oldServerPort})`,
+    `PORT: z.coerce.number().default(${serverPort})`
+  );
+  envTs = replaceAll(
+    envTs,
+    `CLIENT_URL: z.string().default('http://localhost:${oldClientPort}')`,
+    `CLIENT_URL: z.string().default('http://localhost:${clientPort}')`
+  );
+  writeFile('server/src/config/env.ts', envTs);
+
+  // --- client/vite.config.ts ---
+  let viteConfig = readFile('client/vite.config.ts');
+  viteConfig = replaceAll(viteConfig, `port: ${oldClientPort}`, `port: ${clientPort}`);
+  viteConfig = replaceAll(
+    viteConfig,
+    `target: 'http://localhost:${oldServerPort}'`,
+    `target: 'http://localhost:${serverPort}'`
+  );
+  writeFile('client/vite.config.ts', viteConfig);
+
+  // --- client/index.html ---
+  let indexHtml = readFile('client/index.html');
+  indexHtml = replaceAll(indexHtml, `<title>${oldTitle}</title>`, `<title>${name}</title>`);
+  writeFile('client/index.html', indexHtml);
+
+  outro(
+    `Done! Project customized as "${scope}/${name}". Run "npm install" to update the workspace symlinks.`
+  );
+}
+
+main().catch((err: unknown) => {
+  console.error(err);
+  process.exit(1);
+});

package/template/server/nodemon.json

@@ -0,0 +1,5 @@
+{
+  "watch": ["src"],
+  "ext": "ts,json",
+  "exec": "tsx src/index.ts"
+}

package/template/server/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@appystack-template/server",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Express + Socket.io server for AppyStack template",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "dev": "nodemon",
+    "build": "tsc && tsc-alias",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@appystack-template/shared": "*",
+    "compression": "^1.7.5",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.7",
+    "express": "^5.0.1",
+    "express-rate-limit": "^8.2.1",
+    "helmet": "^8.0.0",
+    "pino": "^9.6.0",
+    "pino-http": "^10.4.0",
+    "pino-pretty": "^13.0.0",
+    "socket.io": "^4.8.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/compression": "^1.7.5",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.5",
+    "@types/supertest": "^6.0.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "nodemon": "^3.1.9",
+    "socket.io-client": "^4.8.1",
+    "supertest": "^7.0.0",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.19.2",
+    "vitest": "^4.0.18"
+  }
+}

package/template/server/src/app.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import request from 'supertest';
+import type { AddressInfo } from 'node:net';
+import { io as ioc } from 'socket.io-client';
+import { SOCKET_EVENTS } from '@appystack-template/shared';
+import { app, httpServer } from './index.js';
+
+describe('Express app (via index.ts export)', () => {
+  it('GET /health returns 200', async () => {
+    const res = await request(app).get('/health');
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('ok');
+  });
+
+  it('GET /api/info returns 200', async () => {
+    const res = await request(app).get('/api/info');
+    expect(res.status).toBe(200);
+  });
+
+  it('GET /unknown-route returns 404', async () => {
+    const res = await request(app).get('/unknown-route-that-does-not-exist');
+    expect(res.status).toBe(404);
+    expect(res.body.status).toBe('error');
+    expect(res.body.error).toBe('Not found');
+  });
+});
+
+describe('Socket.io via httpServer export', () => {
+  let port: number;
+
+  beforeAll(async () => {
+    // In test mode index.ts skips auto-listen to prevent EADDRINUSE across
+    // parallel test files. Start the server on a random port here instead.
+    if (!httpServer.listening) {
+      await new Promise<void>((resolve) => httpServer.listen(0, resolve));
+    }
+    port = (httpServer.address() as AddressInfo).port;
+  });
+
+  afterAll(async () => {
+    if (httpServer.listening) {
+      await new Promise<void>((resolve, reject) =>
+        httpServer.close((err) => (err ? reject(err) : resolve()))
+      );
+    }
+  });
+
+  it('connects and receives server:pong after client:ping', () => {
+    return new Promise<void>((resolve, reject) => {
+      const url = `http://localhost:${port}`;
+
+      const client = ioc(url, { forceNew: true, transports: ['websocket'] });
+
+      client.on('connect_error', (err) => {
+        client.disconnect();
+        reject(err);
+      });
+
+      client.on('connect', () => {
+        client.on(SOCKET_EVENTS.SERVER_PONG, (data) => {
+          try {
+            expect(data.message).toBe('pong');
+            expect(typeof data.timestamp).toBe('string');
+            client.disconnect();
+            resolve();
+          } catch (err) {
+            client.disconnect();
+            reject(err);
+          }
+        });
+        client.emit(SOCKET_EVENTS.CLIENT_PING);
+      });
+    });
+  });
+
+  it('can connect and disconnect cleanly', () => {
+    return new Promise<void>((resolve, reject) => {
+      const url = `http://localhost:${port}`;
+
+      const client = ioc(url, { forceNew: true, transports: ['websocket'] });
+
+      client.on('connect_error', (err) => {
+        client.disconnect();
+        reject(err);
+      });
+
+      client.on('connect', () => {
+        expect(client.connected).toBe(true);
+        client.disconnect();
+      });
+
+      client.on('disconnect', (reason) => {
+        try {
+          expect(client.connected).toBe(false);
+          expect(reason).toBe('io client disconnect');
+          resolve();
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+  });
+});

package/template/server/src/config/env.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+describe('env config', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    // Clear the module cache so env.ts re-executes with new process.env
+    // We use dynamic import with cache-busting instead
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('applies default values when optional vars are absent', async () => {
+    process.env.NODE_ENV = 'test';
+    delete process.env.PORT;
+    delete process.env.CLIENT_URL;
+
+    const { env } = await import('./env.js?defaults=' + Date.now());
+
+    expect(env.PORT).toBe(5501);
+    expect(env.CLIENT_URL).toBe('http://localhost:5500');
+    expect(env.NODE_ENV).toBe('test');
+  });
+
+  it('reads PORT as a number when set', async () => {
+    process.env.NODE_ENV = 'test';
+    process.env.PORT = '9999';
+
+    const { env } = await import('./env.js?port=' + Date.now());
+
+    expect(env.PORT).toBe(9999);
+  });
+
+  it('exposes convenience boolean flags', async () => {
+    process.env.NODE_ENV = 'test';
+
+    const { env } = await import('./env.js?flags=' + Date.now());
+
+    expect(env.isTest).toBe(true);
+    expect(env.isDevelopment).toBe(false);
+    expect(env.isProduction).toBe(false);
+  });
+
+  it('sets isDevelopment true when NODE_ENV is development', async () => {
+    process.env.NODE_ENV = 'development';
+
+    const { env } = await import('./env.js?dev=' + Date.now());
+
+    expect(env.isDevelopment).toBe(true);
+    expect(env.isTest).toBe(false);
+    expect(env.isProduction).toBe(false);
+  });
+
+  it('sets isProduction true when NODE_ENV is production', async () => {
+    process.env.NODE_ENV = 'production';
+
+    const { env } = await import('./env.js?prod=' + Date.now());
+
+    expect(env.isProduction).toBe(true);
+    expect(env.isDevelopment).toBe(false);
+    expect(env.isTest).toBe(false);
+  });
+
+  it('exits with code 1 when NODE_ENV is an invalid value', async () => {
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+    process.env.NODE_ENV = 'staging';
+    vi.resetModules();
+    // env.ts calls process.exit(1) on failure but the mock does not stop execution,
+    // so spreading parsed.data (undefined) throws — catch that expected error.
+    try {
+      await import('./env.js?' + Date.now());
+    } catch {
+      // expected: module throws after mocked exit because parsed.data is undefined
+    }
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    exitSpy.mockRestore();
+  });
+
+  it('exits with code 1 when PORT is not a number', async () => {
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+    process.env.NODE_ENV = 'test';
+    process.env.PORT = 'not-a-number';
+    vi.resetModules();
+    // env.ts calls process.exit(1) on failure but the mock does not stop execution,
+    // so spreading parsed.data (undefined) throws — catch that expected error.
+    try {
+      await import('./env.js?' + Date.now());
+    } catch {
+      // expected: module throws after mocked exit because parsed.data is undefined
+    }
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    exitSpy.mockRestore();
+  });
+});

package/template/server/src/config/env.ts

@@ -0,0 +1,29 @@
+import dotenv from 'dotenv';
+import { z } from 'zod';
+
+dotenv.config();
+
+const envSchema = z.object({
+  // TODO: Update defaults for your project
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(5501),
+  CLIENT_URL: z.string().default('http://localhost:5500'),
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  console.error('Invalid environment variables:', parsed.error.flatten().fieldErrors);
+  process.exit(1);
+}
+
+/**
+ * Validated server environment configuration loaded from .env via Zod.
+ * Includes NODE_ENV, PORT, CLIENT_URL, and derived boolean flags (isDevelopment, isProduction, isTest).
+ */
+export const env = {
+  ...parsed.data,
+  isDevelopment: parsed.data.NODE_ENV === 'development',
+  isProduction: parsed.data.NODE_ENV === 'production',
+  isTest: parsed.data.NODE_ENV === 'test',
+};

package/template/server/src/config/logger.test.ts

@@ -0,0 +1,58 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+const mockPino = vi.fn(() => ({ info: vi.fn(), error: vi.fn(), debug: vi.fn() }));
+
+vi.mock('pino', () => ({
+  default: mockPino,
+}));
+
+describe('logger', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mockPino.mockClear();
+  });
+
+  it('uses level debug and pino-pretty transport in development', async () => {
+    vi.doMock('./env.js', () => ({
+      env: { isDevelopment: true },
+    }));
+
+    await import('./logger.js?' + Date.now());
+
+    expect(mockPino).toHaveBeenCalledOnce();
+    const callArg = (
+      mockPino.mock.calls[0] as unknown as [{ level: string; transport?: { target: string } }]
+    )[0];
+    expect(callArg.level).toBe('debug');
+    expect(callArg.transport).toBeDefined();
+    expect(callArg.transport?.target).toBe('pino-pretty');
+  });
+
+  it('uses level info and no transport in production', async () => {
+    vi.doMock('./env.js', () => ({
+      env: { isDevelopment: false },
+    }));
+
+    await import('./logger.js?' + Date.now());
+
+    expect(mockPino).toHaveBeenCalledOnce();
+    const callArg = (
+      mockPino.mock.calls[0] as unknown as [{ level: string; transport?: unknown }]
+    )[0];
+    expect(callArg.level).toBe('info');
+    expect(callArg.transport).toBeUndefined();
+  });
+
+  it('exports a valid pino logger instance with info, error, and debug methods', async () => {
+    vi.doMock('./env.js', () => ({
+      env: { isDevelopment: false },
+    }));
+
+    const { logger } = await import('./logger.js?' + Date.now());
+
+    expect(logger).toBeDefined();
+    expect(typeof logger.info).toBe('function');
+    expect(typeof logger.error).toBe('function');
+    expect(typeof logger.debug).toBe('function');
+  });
+});

package/template/server/src/config/logger.ts

@@ -0,0 +1,17 @@
+import pino from 'pino';
+import { env } from './env.js';
+
+/** Pino logger instance. Uses pino-pretty in development; JSON output in production/test. */
+export const logger = pino({
+  level: env.isDevelopment ? 'debug' : 'info',
+  ...(env.isDevelopment && {
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true,
+        translateTime: 'HH:MM:ss',
+        ignore: 'pid,hostname',
+      },
+    },
+  }),
+});

package/template/server/src/helpers/response.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { apiSuccess, apiFailure } from './response.js';
+
+function buildApp() {
+  const app = express();
+  app.get('/success', (_req, res) => {
+    apiSuccess(res, { name: 'test' });
+  });
+  app.get('/success-201', (_req, res) => {
+    apiSuccess(res, { created: true }, 201);
+  });
+  app.get('/failure', (_req, res) => {
+    apiFailure(res, 'Something went wrong');
+  });
+  app.get('/failure-404', (_req, res) => {
+    apiFailure(res, 'Not found', 404);
+  });
+  return app;
+}
+
+describe('apiSuccess', () => {
+  it('returns 200 with status ok and data', async () => {
+    const res = await request(buildApp()).get('/success');
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('ok');
+    expect(res.body.data).toEqual({ name: 'test' });
+    expect(res.body.timestamp).toBeDefined();
+  });
+
+  it('returns the provided status code', async () => {
+    const res = await request(buildApp()).get('/success-201');
+    expect(res.status).toBe(201);
+    expect(res.body.data).toEqual({ created: true });
+  });
+});
+
+describe('apiFailure', () => {
+  it('returns 400 with status error and message', async () => {
+    const res = await request(buildApp()).get('/failure');
+    expect(res.status).toBe(400);
+    expect(res.body.status).toBe('error');
+    expect(res.body.error).toBe('Something went wrong');
+    expect(res.body.timestamp).toBeDefined();
+  });
+
+  it('returns the provided status code', async () => {
+    const res = await request(buildApp()).get('/failure-404');
+    expect(res.status).toBe(404);
+    expect(res.body.error).toBe('Not found');
+  });
+});

package/template/server/src/helpers/response.ts

@@ -0,0 +1,17 @@
+import type { Response } from 'express';
+
+export function apiSuccess<T>(res: Response, data: T, statusCode = 200): void {
+  res.status(statusCode).json({
+    status: 'ok',
+    data,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+export function apiFailure(res: Response, error: string, statusCode = 400): void {
+  res.status(statusCode).json({
+    status: 'error',
+    error,
+    timestamp: new Date().toISOString(),
+  });
+}