@totaland/create-starter-kit 2.0.2 → 2.0.3

package/templates/backend/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "cybermate-api",
+  "version": "1.0.0",
+  "description": "Fast TypeScript backend starter kit with Ultimate Express, Scalar API docs, and Drizzle ORM.",
+  "type": "module",
+  "main": "build/index.js",
+  "scripts": {
+    "start": "node build/index.js",
+    "dev": "vite-node --watch src/index.ts",
+    "typecheck": "npx tsc --noEmit",
+    "build": "swc src -d build --strip-leading-paths --copy-files",
+    "build:debug": "swc src -d build --strip-leading-paths --copy-files --source-maps",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "prebuild": "rm -rf build",
+    "knip": "knip",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  },
+  "files": [
+    "build"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "2.0.6",
+    "@swc-node/register": "^1.11.1",
+    "@swc/cli": "0.7.7",
+    "@swc/core": "^1.10.1",
+    "@types/bun": "1.2.14",
+    "@types/cors": "^2.8.19",
+    "@types/node": "24.0.7",
+    "@vitest/coverage-v8": "^4.0.13",
+    "@vitest/ui": "^4.0.13",
+    "knip": "^5.69.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.8.3",
+    "vite": "^5.4.21",
+    "vite-node": "^5.2.0",
+    "vitest": "^4.0.13"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.1.0",
+    "@scalar/express-api-reference": "^0.8.25",
+    "cors": "^2.8.5",
+    "dotenv": "17.0.0",
+    "drizzle-kit": "^0.31.7",
+    "drizzle-orm": "^0.44.7",
+    "lru-cache": "^11.2.2",
+    "postgres": "^3.4.7",
+    "ultimate-express": "^2.0.12",
+    "ultimate-ws": "^2.0.6",
+    "zod": "^4.1.12"
+  },
+  "trustedDependencies": [
+    "@swc/core"
+  ]
+}

package/templates/backend/playwright.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "@playwright/test";
+import { config as loadEnv } from "dotenv";
+
+// Load environment variables (e.g. PLAYWRIGHT_BASE_URL) before tests spin up.
+loadEnv();
+
+export default defineConfig({
+  testDir: "src/generated/tests",
+  reporter: [
+    ["line"],
+    ["html", { outputFolder: "playwright-report", open: "never" }],
+  ],
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:3000",
+  },
+});

package/templates/backend/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+onlyBuiltDependencies:
+  - '@swc/core'
+  - esbuild

package/templates/backend/src/features/health/controller.ts

@@ -0,0 +1,5 @@
+import type { Request, Response } from 'ultimate-express';
+
+export const getHealth = (req: Request, res: Response) => {
+    res.json({ status: 'ok', timestamp: new Date().toISOString() });
+};

package/templates/backend/src/features/health/health.test.ts

@@ -0,0 +1,23 @@
+import { vi } from 'vitest';
+import type { Request, Response } from 'ultimate-express';
+import { getHealth } from './controller.js';
+
+// Simple ISO-8601 with offset matcher (aligned with schema)
+const isoWithOffset =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+describe('GET /api/health', () => {
+    it('returns ok status and timestamp', () => {
+        const json = vi.fn();
+        const res = { json } as unknown as Response;
+        const req = {} as Request;
+
+        getHealth(req, res);
+
+        expect(json).toHaveBeenCalledTimes(1);
+        const payload = json.mock.calls[0][0] as { status: string; timestamp: string };
+
+        expect(payload).toMatchObject({ status: 'ok' });
+        expect(payload.timestamp).toMatch(isoWithOffset);
+    });
+});

package/templates/backend/src/features/health/index.ts

@@ -0,0 +1,7 @@
+import { Router } from 'ultimate-express';
+import { getHealth } from './controller.js';
+import './schemas.js';
+
+export const healthRouter = Router();
+
+healthRouter.get('/', getHealth);

package/templates/backend/src/features/health/schemas.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { registry } from '../../lib/openapi.js';
+
+const isoDateTimeWithOffset = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/, 'Invalid datetime');
+
+export const HealthResponseSchema = z
+    .object({
+        status: z.literal('ok'),
+        timestamp: isoDateTimeWithOffset,
+    })
+    .openapi('HealthResponse');
+
+registry.registerPath({
+    method: 'get',
+    path: '/api/health',
+    tags: ['Health'],
+    responses: {
+        200: {
+            description: 'Health check',
+            content: {
+                'application/json': {
+                    schema: HealthResponseSchema,
+                },
+            },
+        },
+    },
+});

package/templates/backend/src/features/orders/controller.ts

@@ -0,0 +1,18 @@
+import type { RequestHandler } from 'ultimate-express';
+import type { z } from 'zod';
+import type { ValidatedRequest } from '../../lib/validateRequest.js';
+import { CreateOrderSchema } from './schemas.js';
+
+type CreateOrderInput = z.infer<typeof CreateOrderSchema>;
+
+export const getOrders: RequestHandler = (_req, res) => {
+    res.json([
+        { id: 1, item: 'Laptop', price: 1200 },
+        { id: 2, item: 'Mouse', price: 25 },
+    ]);
+};
+
+export const createOrder: RequestHandler<any, any, CreateOrderInput> = (req, res) => {
+    const { item, price } = (req as ValidatedRequest<{ body: CreateOrderInput }>).validated.body;
+    res.status(201).json({ id: 3, item, price });
+};

package/templates/backend/src/features/orders/index.ts

@@ -0,0 +1,10 @@
+import { Router } from 'ultimate-express';
+import { validateRequest } from '../../lib/validateRequest.js';
+import { createOrder, getOrders } from './controller.js';
+import { CreateOrderSchema } from './schemas.js';
+
+// TODO: replace with real implementation
+export const ordersRouter = Router();
+
+ordersRouter.get('/', getOrders);
+ordersRouter.post('/', validateRequest({ body: CreateOrderSchema }), createOrder);

package/templates/backend/src/features/orders/schemas.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { registry } from '../../lib/openapi.js';
+
+export const OrderSchema = z
+    .object({
+        id: z.number().int().positive(),
+        item: z.string().min(1),
+        price: z.number().positive(),
+    })
+    .openapi('Order');
+
+export const CreateOrderSchema = z
+    .object({
+        item: z.string().min(1),
+        price: z.number().positive(),
+    })
+    .openapi('CreateOrder');
+
+registry.registerPath({
+    method: 'get',
+    path: '/api/orders',
+    tags: ['Orders'],
+    responses: {
+        200: {
+            description: 'List all orders',
+            content: {
+                'application/json': {
+                    schema: z.array(OrderSchema),
+                },
+            },
+        },
+    },
+});
+
+registry.registerPath({
+    method: 'post',
+    path: '/api/orders',
+    tags: ['Orders'],
+    request: {
+        body: {
+            required: true,
+            content: {
+                'application/json': {
+                    schema: CreateOrderSchema,
+                },
+            },
+        },
+    },
+    responses: {
+        201: {
+            description: 'Created order',
+            content: {
+                'application/json': {
+                    schema: OrderSchema,
+                },
+            },
+        },
+        400: {
+            description: 'Validation error',
+        },
+    },
+});

package/templates/backend/src/index.ts

@@ -0,0 +1,43 @@
+// example backend with ultimate-express
+import 'dotenv/config';
+import express from 'ultimate-express';
+import type { Request, Response } from 'ultimate-express';
+import cors from 'cors';
+import { ordersRouter } from './features/orders/index.js';
+import { healthRouter } from './features/health/index.js';
+import { apiReference } from '@scalar/express-api-reference';
+import { generateOpenApiDocument } from './lib/openapi.js';
+
+const app = express();
+
+app.use(cors());
+app.use(express.json());
+
+app.get('/', (req: Request, res: Response) => {
+  res.send('Hello, Ultimate Express!');
+});
+
+// Mount feature routes
+app.use('/api/orders', ordersRouter);
+app.use('/api/health', healthRouter);
+
+// API Documentation with Scalar
+app.use(
+  '/api/docs',
+  apiReference({
+    spec: {
+      url: '/openapi.json',
+    },
+  }),
+);
+
+// Example OpenAPI spec endpoint
+app.get('/openapi.json', (req: Request, res: Response) => {
+  res.json(generateOpenApiDocument());
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server is running on http://localhost:${PORT}`);
+  console.log(`API Documentation available at http://localhost:${PORT}/api/docs`);
+});

package/templates/backend/src/lib/openapi.ts

@@ -0,0 +1,25 @@
+import { OpenAPIRegistry, OpenApiGeneratorV3, extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+
+extendZodWithOpenApi(z);
+
+export const registry = new OpenAPIRegistry();
+
+export const generateOpenApiDocument = () => {
+    const generator = new OpenApiGeneratorV3(registry.definitions);
+
+    return generator.generateDocument({
+        openapi: '3.1.0',
+        info: {
+            title: 'Ultimate Express API',
+            version: '1.0.0',
+            description: 'API documentation generated from Zod schemas',
+        },
+        servers: [
+            {
+                url: `http://localhost:${process.env.PORT || 3000}`,
+                description: 'Development server',
+            },
+        ],
+    });
+};

package/templates/backend/src/lib/validateRequest.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { NextFunction, Request, Response } from 'ultimate-express';
+import { z } from 'zod';
+import { validateRequest } from './validateRequest.js';
+
+const createRes = () => {
+    const json = vi.fn();
+    const status = vi.fn().mockReturnValue({ json });
+    return { json, status } as unknown as Response;
+};
+
+describe('validateRequest', () => {
+    it('parses and assigns validated data, then calls next', () => {
+        const middleware = validateRequest({
+            body: z.object({
+                id: z.coerce.number().int(),
+                name: z.string().transform((v) => v.trim()),
+            }),
+            query: z.object({
+                page: z.coerce.number().default(1),
+            }),
+            params: z.object({
+                slug: z.string().min(1),
+            }),
+            headers: z.object({
+                'x-trace': z.string().uuid(),
+            }),
+        });
+
+        const req = {
+            body: { id: '42', name: ' Alice ' },
+            query: {},
+            params: { slug: 'hello' },
+            headers: { 'x-trace': '550e8400-e29b-41d4-a716-446655440000' },
+        } as unknown as Request;
+        const res = createRes();
+        const next = vi.fn() as unknown as NextFunction;
+
+        middleware(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        const validated = (req as any).validated;
+        expect(validated.body).toEqual({ id: 42, name: 'Alice' });
+        expect(validated.query).toEqual({ page: 1 });
+        expect(validated.params).toEqual({ slug: 'hello' });
+        expect(validated.headers).toEqual({ 'x-trace': '550e8400-e29b-41d4-a716-446655440000' });
+
+        expect(req.body).toEqual({ id: 42, name: 'Alice' });
+        expect(req.query).toEqual({ page: 1 });
+        expect(req.params).toEqual({ slug: 'hello' });
+        expect(req.headers).toEqual({ 'x-trace': '550e8400-e29b-41d4-a716-446655440000' });
+    });
+
+    it('returns 400 with flattened errors on validation failure', () => {
+        const middleware = validateRequest({
+            body: z.object({ id: z.number().int() }),
+        });
+
+        const req = { body: { id: 'not-a-number' } } as unknown as Request;
+        const res = createRes();
+        const next = vi.fn() as unknown as NextFunction;
+
+        middleware(req, res, next);
+
+        expect(next).not.toHaveBeenCalled();
+        expect(res.status).toHaveBeenCalledWith(400);
+        const payload = (res.json as any).mock.calls[0][0] as { errors: unknown };
+        expect(payload).toHaveProperty('message', 'Validation error');
+        expect(payload.errors).toBeDefined();
+    });
+
+    it('no-op when no schemas provided', () => {
+        const middleware = validateRequest({});
+        const req = {} as Request;
+        const res = createRes();
+        const next = vi.fn() as unknown as NextFunction;
+
+        middleware(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        expect((res as any).status).not.toHaveBeenCalled();
+        expect((res as any).json).not.toHaveBeenCalled();
+    });
+});

package/templates/backend/src/lib/validateRequest.ts

@@ -0,0 +1,72 @@
+import type { NextFunction, Request, Response } from 'ultimate-express';
+import { z, type ZodType } from 'zod';
+
+type RequestSchemas = {
+    body?: ZodType<unknown>;
+    query?: ZodType<unknown>;
+    params?: ZodType<unknown>;
+    headers?: ZodType<unknown>;
+};
+
+type ParsedRequest<S extends RequestSchemas> = {
+    [K in keyof S]: S[K] extends ZodType<unknown> ? z.infer<S[K]> : never;
+};
+
+export type ValidatedRequest<T> = Request & { validated: T };
+
+export const validateRequest =
+    <S extends RequestSchemas>(schemas: S) =>
+    (req: Request, res: Response, next: NextFunction) => {
+        const shape: Record<string, ZodType<unknown>> = {};
+        const input: Record<string, unknown> = {};
+
+        if (schemas.body) {
+            shape.body = schemas.body;
+            input.body = req.body;
+        }
+        if (schemas.query) {
+            shape.query = schemas.query;
+            input.query = req.query;
+        }
+        if (schemas.params) {
+            shape.params = schemas.params;
+            input.params = req.params;
+        }
+        if (schemas.headers) {
+            shape.headers = schemas.headers;
+            input.headers = req.headers;
+        }
+
+        if (Object.keys(shape).length === 0) {
+            next();
+            return;
+        }
+
+        const result = z.object(shape).safeParse(input);
+
+        if (!result.success) {
+            res.status(400).json({
+                message: 'Validation error',
+                errors: result.error.flatten((issue) => issue.message),
+            });
+            return;
+        }
+
+        const parsed = result.data as ParsedRequest<S>;
+
+        if (schemas.body) {
+            req.body = parsed.body as typeof req.body;
+        }
+        if (schemas.query) {
+            req.query = parsed.query as typeof req.query;
+        }
+        if (schemas.params) {
+            req.params = parsed.params as typeof req.params;
+        }
+        if (schemas.headers) {
+            req.headers = parsed.headers as typeof req.headers;
+        }
+
+        (req as ValidatedRequest<ParsedRequest<S>>).validated = parsed;
+        next();
+    };

package/templates/backend/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": false,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"exclude": ["node_modules", "build", "**/*.test.ts", "**/*.spec.ts"]
+}

package/templates/backend/tsconfig.json

@@ -0,0 +1,30 @@
+{
+	"compilerOptions": {
+		"outDir": "./build",
+		"rootDir": "./",
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"lib": ["ESNext", "DOM"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"allowJs": true,
+		"types": ["node", "vitest/globals"],
+
+		// Node module resolution
+		"moduleResolution": "node",
+		"noEmit": true,
+
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	},
+	"include": ["src/**/*", "scripts/**/*"],
+	"exclude": ["node_modules"],
+}

package/templates/backend/vitest.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.{test,spec}.{js,ts}', 'src/**/*.{test,spec}.{js,ts}'],
+    exclude: ['node_modules', 'build', 'src/generated/tests/**/*'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.{ts,js}'],
+      exclude: [
+        'node_modules/',
+        'build/',
+        'tests/',
+        '*.config.*',
+        'src/**/schemas.ts',
+        'src/lib/openapi.ts',
+        'src/index.ts',
+        'src/**/index.ts',
+        'src/features/orders/**/*',
+      ]
+    }
+  },
+  resolve: {
+    alias: {
+      '@': '/src',
+    }
+  }
+});

package/templates/frontend/.env.example

@@ -0,0 +1,7 @@
+# Environment variables for the frontend application
+
+# API Base URL
+VITE_API_URL=http://localhost:3000/api
+
+# Add other environment variables as needed
+# VITE_FEATURE_FLAG=true

package/templates/frontend/.github/agents/ /360/237/216/255 planner.agent.md"

@@ -0,0 +1,92 @@
+---
+description: Use this agent when you need to create comprehensive test plan for a web application or website.
+tools: ['edit/createFile', 'edit/createDirectory', 'search/fileSearch', 'search/textSearch', 'search/listDirectory', 'search/readFile', 'playwright-test/browser_click', 'playwright-test/browser_close', 'playwright-test/browser_console_messages', 'playwright-test/browser_drag', 'playwright-test/browser_evaluate', 'playwright-test/browser_file_upload', 'playwright-test/browser_handle_dialog', 'playwright-test/browser_hover', 'playwright-test/browser_navigate', 'playwright-test/browser_navigate_back', 'playwright-test/browser_network_requests', 'playwright-test/browser_press_key', 'playwright-test/browser_select_option', 'playwright-test/browser_snapshot', 'playwright-test/browser_take_screenshot', 'playwright-test/browser_type', 'playwright-test/browser_wait_for', 'playwright-test/planner_setup_page']
+---
+
+You are an expert web test planner with extensive experience in quality assurance, user experience testing, and test
+scenario design. Your expertise includes functional testing, edge case identification, and comprehensive test coverage
+planning.
+
+You will:
+
+1. **Navigate and Explore**
+   - Invoke the `planner_setup_page` tool once to set up page before using any other tools
+   - Explore the browser snapshot
+   - Do not take screenshots unless absolutely necessary
+   - Use browser_* tools to navigate and discover interface
+   - Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality
+
+2. **Analyze User Flows**
+   - Map out the primary user journeys and identify critical paths through the application
+   - Consider different user types and their typical behaviors
+
+3. **Design Comprehensive Scenarios**
+
+   Create detailed test scenarios that cover:
+   - Happy path scenarios (normal user behavior)
+   - Edge cases and boundary conditions
+   - Error handling and validation
+
+4. **Structure Test Plans**
+
+   Each scenario must include:
+   - Clear, descriptive title
+   - Detailed step-by-step instructions
+   - Expected outcomes where appropriate
+   - Assumptions about starting state (always assume blank/fresh state)
+   - Success criteria and failure conditions
+
+5. **Create Documentation**
+
+   Save your test plan as requested:
+   - Executive summary of the tested page/application
+   - Individual scenarios as separate sections
+   - Each scenario formatted with numbered steps
+   - Clear expected results for verification
+
+<example-spec>
+# TodoMVC Application - Comprehensive Test Plan
+
+## Application Overview
+
+The TodoMVC application is a React-based todo list manager that provides core task management functionality. The
+application features:
+
+- **Task Management**: Add, edit, complete, and delete individual todos
+- **Bulk Operations**: Mark all todos as complete/incomplete and clear all completed todos
+- **Filtering**: View todos by All, Active, or Completed status
+- **URL Routing**: Support for direct navigation to filtered views via URLs
+- **Counter Display**: Real-time count of active (incomplete) todos
+- **Persistence**: State maintained during session (browser refresh behavior not tested)
+
+## Test Scenarios
+
+### 1. Adding New Todos
+
+**Seed:** `tests/seed.spec.ts`
+
+#### 1.1 Add Valid Todo
+**Steps:**
+1. Click in the "What needs to be done?" input field
+2. Type "Buy groceries"
+3. Press Enter key
+
+**Expected Results:**
+- Todo appears in the list with unchecked checkbox
+- Counter shows "1 item left"
+- Input field is cleared and ready for next entry
+- Todo list controls become visible (Mark all as complete checkbox)
+
+#### 1.2
+...
+</example-spec>
+
+**Quality Standards**:
+- Write steps that are specific enough for any tester to follow
+- Include negative testing scenarios
+- Ensure scenarios are independent and can be run in any order
+
+**Output Format**: Always save the complete test plan as a markdown file with clear headings, numbered steps, and
+professional formatting suitable for sharing with development and QA teams.
+<example>Context: User wants to test a new e-commerce checkout flow. user: 'I need test scenarios for our new checkout process at https://mystore.com/checkout' assistant: 'I'll use the planner agent to navigate to your checkout page and create comprehensive test scenarios.' <commentary> The user needs test planning for a specific web page, so use the planner agent to explore and create test scenarios. </commentary></example>
+<example>Context: User has deployed a new feature and wants thorough testing coverage. user: 'Can you help me test our new user dashboard at https://app.example.com/dashboard?' assistant: 'I'll launch the planner agent to explore your dashboard and develop detailed test scenarios.' <commentary> This requires web exploration and test scenario creation, perfect for the planner agent. </commentary></example>