@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/add-crud-routes/SKILL.md

@@ -0,0 +1,221 @@
+# Skill: Add CRUD Routes
+
+Generate a complete set of CRUD API routes for a resource, following MARS conventions for authentication, validation, ownership, and error handling.
+
+## When to Use
+
+Use this skill when the user asks to create endpoints for listing, creating, reading, updating, or deleting a resource.
+
+## Prerequisites
+
+- A Prisma model exists for the resource (see `add-prisma-model` skill).
+- Server access functions exist in `src/features/<name>/server/`.
+- Zod validation schemas exist in `src/features/<name>/validation/schemas.ts`.
+
+## Generated Structure
+
+```
+src/app/api/protected/<resource>/
+├── route.ts              # GET (list) + POST (create)
+└── [id]/
+    └── route.ts          # GET (one) + PATCH (update) + DELETE
+```
+
+## Step 1: Collection Route (`route.ts`)
+
+```typescript
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { findAllForUser, createForUser } from '@/features/<resource>/server';
+import { resourceSchemas } from '@/features/<resource>/validation/schemas';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const items = await findAllForUser(request.session.userId);
+    return NextResponse.json(items);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<resource>' });
+  }
+});
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const body = resourceSchemas.create.parse(await request.json());
+    const item = await createForUser(request.session.userId, body);
+    return NextResponse.json(item, { status: 201 });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<resource>' });
+  }
+});
+```
+
+## Step 2: Item Route (`[id]/route.ts`)
+
+```typescript
+import { handleApiError, withOwnership, withAuth, type AuthenticatedRequest } from '@/lib/mars';
+import { findById, updateById, deleteById } from '@/features/<resource>/server';
+import { resourceSchemas } from '@/features/<resource>/validation/schemas';
+import { NextResponse } from 'next/server';
+
+async function getResourceOwner(
+  _request: AuthenticatedRequest,
+  context: { params: Promise<{ [key: string]: string }> },
+): Promise<string | null> {
+  const { id } = await context.params;
+  const item = await findById(id);
+  return item?.userId ?? null;
+}
+
+export const GET = withOwnership(getResourceOwner, async (request, context) => {
+  try {
+    const { id } = await context.params;
+    const item = await findById(id);
+    return NextResponse.json(item);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<resource>/[id]' });
+  }
+});
+
+export const PATCH = withOwnership(getResourceOwner, async (request, context) => {
+  try {
+    const { id } = await context.params;
+    const body = resourceSchemas.update.parse(await request.json());
+    const item = await updateById(id, body);
+    return NextResponse.json(item);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<resource>/[id]' });
+  }
+});
+
+export const DELETE = withOwnership(getResourceOwner, async (_request, context) => {
+  try {
+    const { id } = await context.params;
+    await deleteById(id);
+    return NextResponse.json({ message: 'Deleted' });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<resource>/[id]' });
+  }
+});
+```
+
+## Step 3: Server Access Functions
+
+```typescript
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import type { CreateInput, UpdateInput } from '../validation/schemas';
+
+export async function findAllForUser(userId: string) {
+  return prisma.<resource>.findMany({
+    where: { userId },
+    orderBy: { createdAt: 'desc' },
+  });
+}
+
+export async function findById(id: string) {
+  return prisma.<resource>.findUnique({ where: { id } });
+}
+
+export async function createForUser(userId: string, data: CreateInput) {
+  return prisma.<resource>.create({
+    data: { ...data, userId },
+  });
+}
+
+export async function updateById(id: string, data: UpdateInput) {
+  return prisma.<resource>.update({
+    where: { id },
+    data,
+  });
+}
+
+export async function deleteById(id: string) {
+  return prisma.<resource>.delete({ where: { id } });
+}
+```
+
+## Step 4: Validation Schemas
+
+```typescript
+import { z } from 'zod';
+
+export const resourceSchemas = {
+  create: z.object({
+    name: z.string().min(1, 'Name is required').max(100),
+    description: z.string().max(500).optional(),
+  }),
+  update: z.object({
+    name: z.string().min(1).max(100).optional(),
+    description: z.string().max(500).optional(),
+  }),
+};
+
+export type CreateInput = z.infer<typeof resourceSchemas.create>;
+export type UpdateInput = z.infer<typeof resourceSchemas.update>;
+```
+
+## Pagination (Optional)
+
+For resources that may grow large, add pagination to the list endpoint:
+
+```typescript
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const url = new URL(request.url);
+    const page = Math.max(1, Number(url.searchParams.get('page') || '1'));
+    const limit = Math.min(100, Math.max(1, Number(url.searchParams.get('limit') || '20')));
+    const skip = (page - 1) * limit;
+
+    const [items, total] = await Promise.all([
+      prisma.<resource>.findMany({
+        where: { userId: request.session.userId },
+        orderBy: { createdAt: 'desc' },
+        skip,
+        take: limit,
+      }),
+      prisma.<resource>.count({
+        where: { userId: request.session.userId },
+      }),
+    ]);
+
+    return NextResponse.json({
+      items,
+      pagination: { page, limit, total, totalPages: Math.ceil(total / limit) },
+    });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<resource>' });
+  }
+});
+```
+
+## Admin Variant
+
+For admin-only CRUD (e.g., managing all users' resources):
+
+```typescript
+export const GET = withRole(['admin'], async (request, context) => {
+  // No userId scoping -- admin sees all
+  const items = await prisma.<resource>.findMany({
+    orderBy: { createdAt: 'desc' },
+    include: { user: { select: { id: true, name: true, email: true } } },
+  });
+  return NextResponse.json(items);
+});
+```
+
+## Middleware Registration
+
+Add the new protected routes to `src/middleware.ts` CSRF protection if not already covered by the `/api/protected` prefix match.
+
+## Checklist
+
+- [ ] Collection route (GET list + POST create)
+- [ ] Item route (GET one + PATCH update + DELETE)
+- [ ] Ownership verification via `withOwnership`
+- [ ] All queries scoped by `userId`
+- [ ] Zod validation on create and update
+- [ ] `handleApiError` in every catch block
+- [ ] Server access functions with `'server-only'`
+- [ ] Pagination for potentially large collections
+- [ ] Tests for each endpoint

package/template/.cursor/skills/add-e2e-test/SKILL.md

@@ -0,0 +1,227 @@
+# Skill: Add an E2E Test
+
+Write a Playwright end-to-end test for a MARS feature or user flow.
+
+## When to Use
+
+Use this skill when the user asks to add E2E tests, integration tests, browser tests, or test a full user flow.
+
+## Architecture
+
+MARS uses Playwright for E2E tests. Tests live in `e2e/` at the project root and run against the full application.
+
+## Setup
+
+Config lives at `playwright.config.ts`. Key settings:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? 'github' : 'html',
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+  webServer: {
+    command: 'yarn dev',
+    port: 3000,
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## Template: Auth Flow Test
+
+```typescript
+// e2e/auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Authentication', () => {
+  test('user can sign in', async ({ page }) => {
+    await page.goto('/sign-in');
+
+    await expect(page.getByRole('heading', { name: /sign in/i })).toBeVisible();
+
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('password123');
+    await page.getByRole('button', { name: /sign in/i }).click();
+
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByRole('heading', { name: /dashboard/i })).toBeVisible();
+  });
+
+  test('shows error for invalid credentials', async ({ page }) => {
+    await page.goto('/sign-in');
+
+    await page.getByLabel('Email').fill('wrong@example.com');
+    await page.getByLabel('Password').fill('wrongpassword');
+    await page.getByRole('button', { name: /sign in/i }).click();
+
+    await expect(page.getByText(/invalid credentials/i)).toBeVisible();
+    await expect(page).toHaveURL('/sign-in');
+  });
+
+  test('redirects to sign-in when accessing protected route', async ({ page }) => {
+    await page.goto('/dashboard');
+    await expect(page).toHaveURL(/sign-in/);
+  });
+});
+```
+
+## Template: CRUD Flow Test
+
+```typescript
+// e2e/projects.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Projects', () => {
+  test.beforeEach(async ({ page }) => {
+    // Sign in before each test
+    await page.goto('/sign-in');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('password123');
+    await page.getByRole('button', { name: /sign in/i }).click();
+    await expect(page).toHaveURL('/dashboard');
+  });
+
+  test('can create a new project', async ({ page }) => {
+    await page.goto('/projects');
+    await page.getByRole('button', { name: /create/i }).click();
+
+    await page.getByLabel('Name').fill('My Test Project');
+    await page.getByLabel('Description').fill('A test project for E2E');
+    await page.getByRole('button', { name: /save/i }).click();
+
+    await expect(page.getByText('My Test Project')).toBeVisible();
+  });
+
+  test('can edit a project', async ({ page }) => {
+    await page.goto('/projects');
+    await page.getByText('My Test Project').click();
+    await page.getByRole('button', { name: /edit/i }).click();
+
+    await page.getByLabel('Name').clear();
+    await page.getByLabel('Name').fill('Updated Project');
+    await page.getByRole('button', { name: /save/i }).click();
+
+    await expect(page.getByText('Updated Project')).toBeVisible();
+  });
+
+  test('can delete a project', async ({ page }) => {
+    await page.goto('/projects');
+    await page.getByText('Updated Project').click();
+    await page.getByRole('button', { name: /delete/i }).click();
+    await page.getByRole('button', { name: /confirm/i }).click();
+
+    await expect(page.getByText('Updated Project')).not.toBeVisible();
+  });
+});
+```
+
+## Auth Helper (Reusable Login)
+
+For tests that need authentication, create a helper:
+
+```typescript
+// e2e/helpers/auth.ts
+import type { Page } from '@playwright/test';
+
+export async function signIn(page: Page, email = 'test@example.com', password = 'password123') {
+  await page.goto('/sign-in');
+  await page.getByLabel('Email').fill(email);
+  await page.getByLabel('Password').fill(password);
+  await page.getByRole('button', { name: /sign in/i }).click();
+}
+```
+
+Or use Playwright's `storageState` for persistent auth:
+
+```typescript
+// e2e/auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'e2e/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/sign-in');
+  await page.getByLabel('Email').fill('test@example.com');
+  await page.getByLabel('Password').fill('password123');
+  await page.getByRole('button', { name: /sign in/i }).click();
+  await expect(page).toHaveURL('/dashboard');
+  await page.context().storageState({ path: authFile });
+});
+```
+
+Then in `playwright.config.ts`:
+
+```typescript
+projects: [
+  { name: 'setup', testMatch: /.*\.setup\.ts/ },
+  {
+    name: 'chromium',
+    use: { ...devices['Desktop Chrome'], storageState: authFile },
+    dependencies: ['setup'],
+  },
+],
+```
+
+## Patterns
+
+### Testing Form Validation
+
+```typescript
+test('shows validation errors for empty form', async ({ page }) => {
+  await page.goto('/contact');
+  await page.getByRole('button', { name: /send/i }).click();
+
+  await expect(page.getByText(/name is required/i)).toBeVisible();
+  await expect(page.getByText(/invalid email/i)).toBeVisible();
+});
+```
+
+### Testing API Responses via Network
+
+```typescript
+test('handles server errors gracefully', async ({ page }) => {
+  await page.route('**/api/protected/projects', (route) =>
+    route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service unavailable' }) }),
+  );
+
+  await page.goto('/projects');
+  await expect(page.getByText(/try again/i)).toBeVisible();
+});
+```
+
+### Visual Regression
+
+```typescript
+test('dashboard looks correct', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    maxDiffPixelRatio: 0.01,
+  });
+});
+```
+
+## Running Tests
+
+```bash
+yarn test:e2e                  # Run all E2E tests
+yarn test:e2e:ui               # Open Playwright UI
+npx playwright test --headed   # Run with visible browser
+npx playwright show-report     # View HTML report
+```
+
+## Checklist
+
+- [ ] Test file in `e2e/` directory
+- [ ] Tests use `test.describe` for grouping
+- [ ] Auth helper or `storageState` for authenticated tests
+- [ ] Uses role-based selectors (`getByRole`, `getByLabel`, `getByText`) over CSS selectors
+- [ ] Tests both happy path and error paths
+- [ ] No hard-coded waits (`waitForTimeout`) -- use `expect` assertions
+- [ ] Test data cleaned up (or use test-specific seed data)