@quanticjs/create-app 0.1.1

package/templates/claude/skills/write-backend-tests/SKILL.md

@@ -0,0 +1,182 @@
+# Write Tests — Backend
+
+## Usage
+```
+/write-backend-tests src/project/commands/CreateItemHandler.ts
+/write-backend-tests src/project/controllers/ItemsController.ts
+```
+
+## 1. Handler Unit Test (`*.spec.ts`)
+
+Test the handler directly — mock repositories, assert `Result<T>`.
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { getRepositoryToken } from '@nestjs/typeorm';
+import { createMockRepository, ErrorType } from '@quanticjs/core';
+import { CreateItemHandler } from './CreateItemHandler';
+import { CreateItemCommand } from './CreateItemCommand';
+import { Item } from '../entities/Item.entity';
+
+describe('CreateItemHandler', () => {
+  let handler: CreateItemHandler;
+  let itemRepo: ReturnType<typeof createMockRepository>;
+
+  beforeEach(async () => {
+    itemRepo = createMockRepository();
+    itemRepo.create.mockImplementation((dto: any) => ({
+      ...dto,
+      id: 'item-1',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }));
+    itemRepo.save.mockImplementation((entity: any) => Promise.resolve(entity));
+
+    const module = await Test.createTestingModule({
+      providers: [
+        CreateItemHandler,
+        { provide: getRepositoryToken(Item), useValue: itemRepo },
+      ],
+    }).compile();
+
+    handler = module.get(CreateItemHandler);
+  });
+
+  it('should create item and return success', async () => {
+    const command = new CreateItemCommand({ name: 'Widget', userId: 'user-1' });
+    const result = await handler.execute(command);
+
+    expect(result.isSuccess).toBe(true);
+    expect(result.value!.name).toBe('Widget');
+    expect(itemRepo.save).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return conflict when name already exists', async () => {
+    itemRepo.findOne.mockResolvedValue({ id: 'existing', name: 'Widget' });
+    const command = new CreateItemCommand({ name: 'Widget', userId: 'user-1' });
+    const result = await handler.execute(command);
+
+    expect(result.isSuccess).toBe(false);
+    expect(result.errorType).toBe(ErrorType.Conflict);
+    expect(itemRepo.save).not.toHaveBeenCalled();
+  });
+});
+```
+
+### Key Rules
+- Use `createMockRepository()` from `@quanticjs/core` — never hand-roll mocks
+- Override specific methods with `.mockImplementation()` for test scenarios
+- Assert via `result.isSuccess`, `result.value`, `result.errorType` — never try/catch
+- Test both success AND failure paths (NotFound, Conflict, Forbidden, ValidationError)
+
+## 2. Controller Integration Test (`*.spec.ts`)
+
+Test HTTP request → validation → bus dispatch → response. Mock CommandBus/QueryBus.
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+import { APP_GUARD } from '@nestjs/core';
+import request from 'supertest';
+import { Result } from '@quanticjs/core';
+import { ItemsController } from './ItemsController';
+
+class MockAuthGuard {
+  canActivate(context: any) {
+    const req = context.switchToHttp().getRequest();
+    req.user = {
+      keycloakId: 'user-1',
+      email: 'test@test.com',
+      roles: ['admin'],
+    };
+    return true;
+  }
+}
+
+describe('ItemsController (integration)', () => {
+  let app: INestApplication;
+  let commandBus: { execute: jest.Mock };
+  let queryBus: { execute: jest.Mock };
+
+  beforeAll(async () => {
+    commandBus = { execute: jest.fn() };
+    queryBus = { execute: jest.fn() };
+
+    const module = await Test.createTestingModule({
+      controllers: [ItemsController],
+      providers: [
+        { provide: CommandBus, useValue: commandBus },
+        { provide: QueryBus, useValue: queryBus },
+        { provide: APP_GUARD, useClass: MockAuthGuard },
+      ],
+    }).compile();
+
+    app = module.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+    }));
+    await app.init();
+  });
+
+  afterAll(() => app.close());
+
+  it('should create item with valid payload', async () => {
+    commandBus.execute.mockResolvedValue(Result.success({ id: 'item-1' }));
+
+    const res = await request(app.getHttpServer())
+      .post('/api/items')
+      .send({ name: 'Widget', description: 'A widget' });
+
+    expect(res.status).toBe(201);
+    expect(commandBus.execute).toHaveBeenCalledTimes(1);
+  });
+
+  it('should reject invalid payload', async () => {
+    const res = await request(app.getHttpServer())
+      .post('/api/items')
+      .send({});
+
+    expect(res.status).toBe(400);
+    expect(commandBus.execute).not.toHaveBeenCalled();
+  });
+});
+```
+
+### Key Rules
+- MockAuthGuard sets `req.user` with `keycloakId`, `email`, `roles`
+- ValidationPipe with `whitelist + forbidNonWhitelisted` — tests class-validator DTOs
+- Mock CommandBus/QueryBus return `Result.success()` or `Result.failure()`
+- Test validation (400), auth (401/403), success (200/201), and not-found (404) cases
+- Use `beforeAll` / `afterAll` for app lifecycle (not beforeEach — too slow)
+
+## 3. Validator Unit Test (`*.spec.ts`)
+
+```typescript
+describe('CreateItemValidator', () => {
+  const validator = new CreateItemValidator();
+
+  it('should pass with valid input', () => {
+    const result = validator.validate(new CreateItemCommand({ name: 'Valid' }));
+    expect(result.isSuccess).toBe(true);
+  });
+
+  it('should fail when name is empty', () => {
+    const result = validator.validate(new CreateItemCommand({ name: '' }));
+    expect(result.isSuccess).toBe(false);
+    expect(result.errorType).toBe(ErrorType.ValidationError);
+  });
+});
+```
+
+## Test File Naming
+| Type | Pattern | Location |
+|------|---------|----------|
+| Handler unit | `CreateItemHandler.spec.ts` | Next to handler file |
+| Validator unit | `CreateItemValidator.spec.ts` | Next to validator file |
+| Controller integration | `ItemsController.spec.ts` | Next to controller file |
+
+## Mandatory Coverage
+Every handler test must cover: happy path, validation failure, not found, conflict, permission check.

package/templates/claude/skills/write-ui-tests/SKILL.md

@@ -0,0 +1,118 @@
+# Write UI Tests
+
+Write mocked E2E specs using Playwright. All APIs are mocked with `page.route()` — tests run fast, need no backend, and verify the UI renders correctly for all states.
+
+## Usage
+```
+/write-ui-tests /projects
+/write-ui-tests /settings/profile
+/write-ui-tests client/src/pages/SettingsPage.tsx
+```
+
+## Steps
+
+### Step 1: Write mocked E2E spec (`client/e2e/*.spec.ts`)
+
+All 4 states are **mandatory**:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Projects Page', () => {
+  test.beforeEach(async ({ page }) => {
+    // Mock auth
+    await page.route('**/auth/me', route => route.fulfill({
+      status: 200,
+      body: JSON.stringify({ keycloakId: 'kc-1', roles: ['user'] }),
+    }));
+  });
+
+  // HAPPY PATH
+  test('shows projects on success', async ({ page }) => {
+    await page.route('**/api/projects*', route => route.fulfill({
+      status: 200, json: { data: [{ id: '1', name: 'Project A' }] },
+    }));
+    await page.goto('/projects');
+    await expect(page.getByRole('heading', { name: 'Projects' })).toBeVisible();
+  });
+
+  // ERROR STATE
+  test('shows error on API failure', async ({ page }) => {
+    await page.route('**/api/projects*', route => route.fulfill({ status: 500 }));
+    await page.goto('/projects');
+    await expect(page.getByText(/something went wrong|error|try again/i)).toBeVisible();
+  });
+
+  // EMPTY STATE
+  test('shows empty state when no projects', async ({ page }) => {
+    await page.route('**/api/projects*', route => route.fulfill({
+      status: 200, json: { data: [] },
+    }));
+    await page.goto('/projects');
+    await expect(page.getByText(/no projects/i)).toBeVisible();
+  });
+
+  // LOADING STATE
+  test('shows loading while fetching', async ({ page }) => {
+    await page.route('**/api/projects*', async route => {
+      await new Promise(r => setTimeout(r, 2000));
+      await route.fulfill({ status: 200, json: { data: [] } });
+    });
+    await page.goto('/projects');
+    // Assert skeleton or spinner visible before data loads
+  });
+});
+```
+
+### Step 2: Write component test (`client/src/<path>/__tests__/<Component>.test.tsx`)
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { createClient, QuanticProvider } from '@quanticjs/react-core';
+import { QuanticQueryProvider } from '@quanticjs/react-query';
+import { ToastProvider, ErrorBoundary } from '@quanticjs/react-ui';
+import { describe, it, expect } from 'vitest';
+
+const testClient = createClient({ baseUrl: '/api' });
+
+function TestWrapper({ children }: { children: React.ReactNode }) {
+  return (
+    <QuanticProvider client={testClient}>
+      <QuanticQueryProvider>
+        <ToastProvider>
+          <ErrorBoundary fallback={<div>Error</div>}>
+            <MemoryRouter>{children}</MemoryRouter>
+          </ErrorBoundary>
+        </ToastProvider>
+      </QuanticQueryProvider>
+    </QuanticProvider>
+  );
+}
+
+describe('ProjectsPage', () => {
+  it('renders heading', () => {
+    render(<ProjectsPage />, { wrapper: TestWrapper });
+    expect(screen.getByRole('heading', { name: 'Projects' })).toBeInTheDocument();
+  });
+});
+```
+
+## Selector Rules
+- `getByRole` > `getByLabelText` > `getByText` > `getByPlaceholder` > `getByTestId`
+- NEVER use CSS selectors (`.class`, `#id`, `div > span`)
+- NEVER use `page.waitForTimeout()`
+- NEVER use `fireEvent` — use `userEvent` in component tests
+
+## Mock Rules
+- Mock all APIs with `page.route()`
+- Auth mocking: mock `/auth/me` endpoint — NEVER use `localStorage`
+
+## Assertion Rules
+- Assertions verify **behavior**, not just element existence
+- Verify API calls were made with `waitForResponse` for mutation actions
+- Test interactive outcomes: after clicking a filter, verify filtered results
+- NEVER use `expect(await el.isVisible()).toBe(true)` — use `await expect(el).toBeVisible()`
+
+## Responsive Testing
+Test at mobile viewport (375x812) and desktop for all pages.

package/templates/docker/Dockerfile.client.ejs

@@ -0,0 +1,14 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine AS production
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+RUN addgroup -g 1001 -S appgroup && adduser -u 1001 -S appuser -G appgroup
+USER appuser
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

package/templates/docker/Dockerfile.ejs

@@ -0,0 +1,28 @@
+# ---- Development ----
+FROM node:20-alpine AS development
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY tsconfig*.json nest-cli.json ./
+# src/ is volume-mounted at runtime
+CMD ["npm", "run", "start:dev"]
+
+# ---- Builder ----
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# ---- Production ----
+FROM node:20-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -g 1001 -S appgroup && adduser -u 1001 -S appuser -G appgroup
+COPY package*.json ./
+RUN npm ci --only=production && npm cache clean --force
+COPY --from=builder /app/dist ./dist
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/main.js"]

package/templates/docker/docker-compose.test.yml.ejs

@@ -0,0 +1,54 @@
+services:
+  postgres-test:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: <%= projectNameUnderscored %>_test
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis-test:
+    image: redis:7-alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  keycloak-test:
+    image: quay.io/keycloak/keycloak:24.0
+    command: start-dev
+    environment:
+      KC_DB: dev-mem
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HOSTNAME_STRICT: "false"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8099:8080"
+
+  backend-test:
+    build:
+      context: .
+      target: development
+    ports:
+      - "3099:3000"
+    environment:
+      NODE_ENV: test
+      PORT: 3000
+      DATABASE_HOST: postgres-test
+      DATABASE_PORT: 5432
+      DATABASE_USER: postgres
+      DATABASE_PASSWORD: postgres
+      DATABASE_NAME: <%= projectNameUnderscored %>_test
+      REDIS_URL: redis://redis-test:6379
+      KEYCLOAK_URL: http://keycloak-test:8080
+    depends_on:
+      postgres-test:
+        condition: service_healthy
+      redis-test:
+        condition: service_healthy

package/templates/docker/docker-compose.yml.ejs

@@ -0,0 +1,76 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: <%= projectNameUnderscored %>
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./scripts/init-db.sh:/docker-entrypoint-initdb.d/init-db.sh
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:24.0
+    command: start-dev
+    environment:
+      KC_DB: dev-mem
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HOSTNAME_STRICT: "false"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8080:8080"
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/8080; echo -e 'GET /health/ready HTTP/1.1\\r\\nhost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3; cat <&3 | grep -q '200'"]
+      interval: 10s
+      timeout: 5s
+      retries: 15
+
+  backend:
+    build:
+      context: .
+      target: development
+    ports:
+      - "3000:3000"
+    environment:
+      NODE_ENV: development
+      PORT: 3000
+      DATABASE_HOST: postgres
+      DATABASE_PORT: 5432
+      DATABASE_USER: postgres
+      DATABASE_PASSWORD: postgres
+      DATABASE_NAME: <%= projectNameUnderscored %>
+      REDIS_URL: redis://redis:6379
+      KEYCLOAK_URL: http://keycloak:8080
+      KEYCLOAK_REALM: <%= projectName %>
+      KEYCLOAK_CLIENT_ID: <%= projectName %>-backend
+      KEYCLOAK_CLIENT_SECRET: change-me
+      SESSION_SECRET: dev-secret-change-in-prod
+    volumes:
+      - ./src:/app/src:cached
+      - ./nest-cli.json:/app/nest-cli.json:ro
+      - ./tsconfig.json:/app/tsconfig.json:ro
+      - ./tsconfig.build.json:/app/tsconfig.build.json:ro
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      keycloak:
+        condition: service_healthy
+
+volumes:
+  postgres_data:

package/templates/docker/nginx.conf.ejs

@@ -0,0 +1,21 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api/ {
+        proxy_pass http://backend:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /auth/ {
+        proxy_pass http://backend:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}

package/templates/frontend/App.tsx.ejs

@@ -0,0 +1,64 @@
+import { lazy, Suspense } from 'react';
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+import * as Sentry from '@sentry/react';
+import { QuanticProvider, QuanticQueryProvider } from '@quanticjs/react-core';
+import { ToastProvider, ErrorBoundary, Spinner } from '@quanticjs/react-ui';
+import { apiClient } from './lib/api-client';
+
+const DashboardPage = lazy(() => import('./pages/DashboardPage'));
+const LoginPage = lazy(() => import('./pages/LoginPage'));
+const NotFoundPage = lazy(() => import('./pages/NotFoundPage'));
+
+const router = createBrowserRouter([
+  {
+    path: '/login',
+    element: (
+      <Suspense fallback={<Spinner size="lg" />}>
+        <LoginPage />
+      </Suspense>
+    ),
+  },
+  {
+    path: '/',
+    element: (
+      <Suspense fallback={<Spinner size="lg" />}>
+        <DashboardPage />
+      </Suspense>
+    ),
+  },
+  {
+    path: '*',
+    element: (
+      <Suspense fallback={<Spinner size="lg" />}>
+        <NotFoundPage />
+      </Suspense>
+    ),
+  },
+]);
+
+export function App() {
+  return (
+    <Sentry.ErrorBoundary fallback={<div>Something went wrong.</div>}>
+      <QuanticProvider client={apiClient}>
+        <QuanticQueryProvider>
+          <ToastProvider>
+            <ErrorBoundary
+              fallback={(error, reset) => (
+                <div className="flex min-h-screen items-center justify-center">
+                  <div className="text-center">
+                    <h1 className="text-2xl font-bold">Something went wrong</h1>
+                    <button onClick={reset} className="mt-4 underline">
+                      Try again
+                    </button>
+                  </div>
+                </div>
+              )}
+            >
+              <RouterProvider router={router} />
+            </ErrorBoundary>
+          </ToastProvider>
+        </QuanticQueryProvider>
+      </QuanticProvider>
+    </Sentry.ErrorBoundary>
+  );
+}

package/templates/frontend/DashboardPage.tsx.ejs

@@ -0,0 +1,37 @@
+import { useApiQuery } from '@quanticjs/react-query';
+import { Skeleton } from '@quanticjs/react-ui';
+
+interface UserSession {
+  id: string;
+  email: string;
+  displayName: string;
+  role: string;
+  roles: string[];
+  permissions: string[];
+}
+
+export default function DashboardPage() {
+  const { data: session, isLoading } = useApiQuery<UserSession>(
+    ['auth', 'session'],
+    (api) => api.get('/auth/me'),
+  );
+
+  if (isLoading) {
+    return (
+      <div className="p-8 space-y-4">
+        <Skeleton className="h-8 w-48" />
+        <Skeleton className="h-4 w-64" />
+        <Skeleton className="h-32 w-full" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-8">
+      <h1 className="text-2xl font-bold text-foreground">
+        Welcome, {session?.displayName}
+      </h1>
+      <p className="text-muted-foreground mt-2">Dashboard content goes here.</p>
+    </div>
+  );
+}

package/templates/frontend/LoginPage.tsx.ejs

@@ -0,0 +1,20 @@
+export default function LoginPage() {
+  const handleLogin = () => {
+    window.location.href = '/auth/login?provider=keycloak&returnTo=/';
+  };
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background">
+      <div className="w-full max-w-sm space-y-6 text-center">
+        <h1 className="text-3xl font-bold text-foreground">Welcome</h1>
+        <p className="text-muted-foreground">Sign in to continue</p>
+        <button
+          onClick={handleLogin}
+          className="w-full rounded-md bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90"
+        >
+          Sign in with SSO
+        </button>
+      </div>
+    </div>
+  );
+}

package/templates/frontend/NotFoundPage.tsx.ejs

@@ -0,0 +1,15 @@
+import { Link } from 'react-router-dom';
+
+export default function NotFoundPage() {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background">
+      <div className="text-center">
+        <h1 className="text-6xl font-bold text-foreground">404</h1>
+        <p className="mt-4 text-muted-foreground">Page not found</p>
+        <Link to="/" className="mt-6 inline-block text-primary underline">
+          Go home
+        </Link>
+      </div>
+    </div>
+  );
+}

package/templates/frontend/api-client.ts.ejs

@@ -0,0 +1,15 @@
+import { createClient, correlationId } from '@quanticjs/react-core';
+
+export const apiClient = createClient({
+  baseUrl: '/api',
+  interceptors: [correlationId()],
+  auth: {
+    refresh: () =>
+      fetch('/auth/refresh', { method: 'POST', credentials: 'include' }).then((r) => {
+        if (!r.ok) throw r;
+      }),
+    onRefreshFailure: () => {
+      window.location.href = '/auth/login?returnTo=' + encodeURIComponent(window.location.pathname);
+    },
+  },
+});