@claude-code-mastery/starter-kit 1.0.0

package/.claude/commands/create-api.md

@@ -0,0 +1,385 @@
+---
+description: Scaffold a new API endpoint — route, handler, types, tests — wired into the server
+scope: project
+argument-hint: <resource-name> [--no-db]
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion
+---
+
+# Create API Endpoint
+
+Scaffold a production-ready API endpoint for: **$ARGUMENTS**
+
+## Step 0 — Auto-Branch (if on main)
+
+Before creating any files, check the current branch:
+
+```bash
+git branch --show-current
+```
+
+**Default behavior** (`auto_branch = true` in `claude-mastery-project.conf`):
+- If on `main` or `master`: automatically create a feature branch and switch to it:
+  ```bash
+  git checkout -b feat/api-<resource-name>
+  ```
+  Report: "Created branch `feat/api-<resource>` — main stays untouched."
+- If already on a feature branch: proceed
+- If not a git repo: skip this check
+
+**To disable:** Set `auto_branch = false` in `claude-mastery-project.conf`. When disabled, warn and ask the user before proceeding on main.
+
+## Step 1 — Gather Context
+
+Before scaffolding, read the current project:
+
+1. **Read `src/server.ts`** (or `src/server.js`, `src/index.ts`) — understand the server setup
+2. **Scan `src/routes/`** — check for existing route patterns to follow
+3. **Scan `src/handlers/`** — check for existing handler patterns
+4. **Scan `src/types/`** — check for existing type patterns
+5. **Read `.env.example`** — check for database config
+
+If `--no-db` is in the arguments, skip database integration. Otherwise, use StrictDB if it's installed, or the native MongoDB driver if not (always through the adapter, never Mongoose).
+
+## Step 2 — Create Files
+
+Generate these files for the resource:
+
+### File 1: `src/types/<resource>.ts` — Types first (they're the spec)
+
+```typescript
+/** Database document shape */
+export interface <Resource>Doc {
+  _id: string;
+  // Add fields based on the resource
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** API request body for creating a resource */
+export interface Create<Resource>Body {
+  // Fields the client sends (NO _id, NO timestamps)
+}
+
+/** API request body for updating a resource */
+export interface Update<Resource>Body {
+  // Partial fields the client can update
+}
+
+/** API response shape (what the client receives) */
+export interface <Resource>Response {
+  id: string;
+  // Mapped from the doc — NEVER expose _id directly
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### File 2: `src/handlers/<resource>.ts` — Business logic
+
+```typescript
+import type { StrictDB } from 'strictdb';
+import type { <Resource>Doc, Create<Resource>Body, Update<Resource>Body, <Resource>Response } from '../types/<resource>.js';
+
+// ---------------------------------------------------------------------------
+// Schema + indexes — registered at startup via db.ensureIndexes()
+// ---------------------------------------------------------------------------
+
+// Called once at app startup with the shared StrictDB instance
+export function register<Resource>Schema(db: StrictDB) {
+  db.registerCollection({
+    name: '<resources>',
+    indexes: [{ collection: '<resources>', fields: { createdAt: -1 } }],
+  });
+}
+// Add more indexes based on query patterns
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const COLLECTION = '<resources>';
+
+/** Map a database document to API response (never expose internals) */
+function toResponse(doc: <Resource>Doc): <Resource>Response {
+  return {
+    id: String(doc._id),
+    // Map other fields
+    createdAt: doc.createdAt.toISOString(),
+    updatedAt: doc.updatedAt.toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CRUD operations — all receive the shared StrictDB instance
+// ---------------------------------------------------------------------------
+
+export async function create<Resource>(db: StrictDB, body: Create<Resource>Body): Promise<<Resource>Response> {
+  const now = new Date();
+  const doc: Omit<<Resource>Doc, '_id'> = {
+    ...body,
+    createdAt: now,
+    updatedAt: now,
+  };
+  await db.insertOne(COLLECTION, doc);
+  const created = await db.queryOne<<Resource>Doc>(COLLECTION, { createdAt: now });
+  if (!created) throw new Error('Failed to create resource');
+  return toResponse(created);
+}
+
+export async function get<Resource>ById(db: StrictDB, id: string): Promise<<Resource>Response | null> {
+  const doc = await db.queryOne<<Resource>Doc>(COLLECTION, { _id: id });
+  return doc ? toResponse(doc) : null;
+}
+
+export async function list<Resource>s(db: StrictDB, options: {
+  page?: number;
+  limit?: number;
+  sort?: Record<string, 1 | -1>;
+} = {}): Promise<{ data: <Resource>Response[]; total: number; page: number; limit: number }> {
+  const page = Math.max(1, options.page ?? 1);
+  const limit = Math.min(100, Math.max(1, options.limit ?? 20));
+  const sort = options.sort ?? { createdAt: -1 };
+
+  const [docs, total] = await Promise.all([
+    db.queryMany<<Resource>Doc>(COLLECTION, [
+      { $sort: sort },
+      { $skip: (page - 1) * limit },
+      { $limit: limit },
+    ]),
+    db.count(COLLECTION),
+  ]);
+
+  return { data: docs.map(toResponse), total, page, limit };
+}
+
+export async function update<Resource>(
+  db: StrictDB,
+  id: string,
+  body: Update<Resource>Body
+): Promise<<Resource>Response | null> {
+  const filter = { _id: id };
+  await db.updateOne(COLLECTION, filter, {
+    $set: { ...body, updatedAt: new Date() },
+  });
+  const updated = await db.queryOne<<Resource>Doc>(COLLECTION, filter);
+  return updated ? toResponse(updated) : null;
+}
+
+export async function delete<Resource>(db: StrictDB, id: string): Promise<boolean> {
+  await db.deleteOne(COLLECTION, { _id: id });
+  return true;
+}
+```
+
+### File 3: `src/routes/v1/<resource>.ts` — Routes (thin, no logic)
+
+```typescript
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import {
+  create<Resource>,
+  get<Resource>ById,
+  list<Resource>s,
+  update<Resource>,
+  delete<Resource>,
+} from '../../handlers/<resource>.js';
+
+const router = Router();
+
+// POST /api/v1/<resources>
+router.post('/', async (req: Request, res: Response) => {
+  try {
+    const result = await create<Resource>(req.body);
+    res.status(201).json(result);
+  } catch (err) {
+    console.error('Create <resource> failed:', err);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// GET /api/v1/<resources>
+router.get('/', async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const limit = parseInt(req.query.limit as string) || 20;
+    const result = await list<Resource>s({ page, limit });
+    res.json(result);
+  } catch (err) {
+    console.error('List <resources> failed:', err);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// GET /api/v1/<resources>/:id
+router.get('/:id', async (req: Request, res: Response) => {
+  try {
+    const result = await get<Resource>ById(req.params.id);
+    if (!result) {
+      res.status(404).json({ error: '<Resource> not found' });
+      return;
+    }
+    res.json(result);
+  } catch (err) {
+    console.error('Get <resource> failed:', err);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// PATCH /api/v1/<resources>/:id
+router.patch('/:id', async (req: Request, res: Response) => {
+  try {
+    const result = await update<Resource>(req.params.id, req.body);
+    if (!result) {
+      res.status(404).json({ error: '<Resource> not found' });
+      return;
+    }
+    res.json(result);
+  } catch (err) {
+    console.error('Update <resource> failed:', err);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// DELETE /api/v1/<resources>/:id
+router.delete('/:id', async (req: Request, res: Response) => {
+  try {
+    const found = await delete<Resource>(req.params.id);
+    if (!found) {
+      res.status(404).json({ error: '<Resource> not found' });
+      return;
+    }
+    res.status(204).send();
+  } catch (err) {
+    console.error('Delete <resource> failed:', err);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+export default router;
+```
+
+### File 4: Wire into server — Add to `src/server.ts`
+
+Add the import and route registration to the existing server:
+
+```typescript
+// Add this import
+import <resource>Routes from './routes/v1/<resource>.js';
+
+// Add this route registration (with /api/v1/ prefix)
+app.use('/api/v1/<resources>', <resource>Routes);
+```
+
+### File 5: `tests/unit/<resource>.test.ts` — Unit tests
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// Test the handler functions directly, mock the db layer
+
+describe('<Resource> Handlers', () => {
+  describe('create<Resource>', () => {
+    it('should create a new <resource> and return response', async () => {
+      // Arrange — mock db calls
+      // Act — call create<Resource>
+      // Assert — verify response shape, timestamps set
+    });
+  });
+
+  describe('get<Resource>ById', () => {
+    it('should return <resource> when found', async () => {
+      // Test happy path
+    });
+
+    it('should return null for invalid ObjectId', async () => {
+      // Test invalid id returns null
+    });
+
+    it('should return null when not found', async () => {
+      // Test missing doc returns null
+    });
+  });
+
+  describe('list<Resource>s', () => {
+    it('should return paginated results', async () => {
+      // Test pagination defaults
+    });
+
+    it('should cap limit at 100', async () => {
+      // Test max limit enforcement
+    });
+  });
+
+  describe('update<Resource>', () => {
+    it('should update and return updated doc', async () => {
+      // Test updatedAt is refreshed
+    });
+  });
+
+  describe('delete<Resource>', () => {
+    it('should return true when deleted', async () => {
+      // Test happy path
+    });
+
+    it('should return false for invalid ObjectId', async () => {
+      // Test invalid id
+    });
+  });
+});
+```
+
+## Step 3 — Best Practices Enforced
+
+Every generated endpoint MUST follow these rules:
+
+### Security
+- All user input passes through StrictDB's built-in sanitization and guardrails
+- NEVER trust `req.body` types at runtime — validate or use Zod schemas
+- NEVER expose `_id` directly — always map to `id: string`
+- NEVER expose internal error details to the client
+- ALWAYS return generic "Internal server error" for unexpected errors
+
+### Performance
+- Pagination on ALL list endpoints (default 20, max 100)
+- Indexes registered for all query patterns (`registerCollection()`)
+- Uses shared StrictDB instance (NEVER creates new connections)
+- `$limit` enforced before `$lookup` in any join queries
+
+### Architecture
+- Routes are THIN — no business logic, just parse and delegate
+- Handlers contain ALL business logic
+- Types defined FIRST — they're the contract
+- One handler file per resource domain
+- One route file per resource
+
+### Node.js Best Practices
+- Async error handling with try/catch on every route
+- Proper HTTP status codes (201 created, 204 no content, 404 not found)
+- JSON responses on all endpoints (including errors)
+- No callback-style code — async/await only
+- Receives the shared StrictDB instance (never creates its own)
+
+## Step 4 — Verification Checklist
+
+After generating, verify:
+
+- [ ] Types file created at `src/types/<resource>.ts`
+- [ ] Handler file created at `src/handlers/<resource>.ts`
+- [ ] Route file created at `src/routes/v1/<resource>.ts`
+- [ ] Routes wired into `src/server.ts` with `/api/v1/` prefix
+- [ ] Test file created at `tests/unit/<resource>.test.ts`
+- [ ] All CRUD operations: create, read (single + list), update, delete
+- [ ] Pagination on list endpoint (default 20, max 100)
+- [ ] Indexes registered with `registerCollection()`
+- [ ] No `any` types
+- [ ] No file exceeds 300 lines
+- [ ] _id never exposed — mapped to id string
+- [ ] All errors caught and logged
+- [ ] Data access through the adapter — StrictDB if installed, otherwise the native driver; never Mongoose, never a raw driver in handlers
+
+## RuleCatch Report
+
+After all files are created and verified, check RuleCatch:
+
+- If the RuleCatch MCP server is available: query for violations in the new API files
+- Report any violations found (type issues, missing assertions, security, etc.)
+- If no MCP: remind the user — "Check your RuleCatch dashboard for any violations in the new endpoint files"

package/.claude/commands/create-e2e.md

@@ -0,0 +1,230 @@
+---
+description: Create a Playwright E2E test with explicit success criteria
+scope: project
+argument-hint: <feature-or-page-name>
+allowed-tools: Read, Write, Grep, Glob, Bash, AskUserQuestion
+---
+
+# Create E2E Test
+
+Create a Playwright E2E test for: **$ARGUMENTS**
+
+## ABSOLUTE RULES — Read Before Writing a Single Line
+
+### 1. Every test MUST have explicit success criteria
+
+"Page loads" is NOT a test. Every `test()` block MUST assert:
+- **URL** — verify the page navigated to the correct URL
+- **Visible elements** — verify key elements are present and visible
+- **Correct data** — verify the right content is displayed
+- **Error states** — verify error messages show when expected
+
+```typescript
+// CORRECT — explicit success criteria
+test('dashboard shows user data after login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[name="email"]', 'test@example.com');
+  await page.fill('[name="password"]', 'password123');
+  await page.click('button[type="submit"]');
+
+  // ✅ Verify URL changed
+  await expect(page).toHaveURL('/dashboard');
+  // ✅ Verify key element visible
+  await expect(page.locator('h1')).toContainText('Welcome');
+  // ✅ Verify correct data displayed
+  await expect(page.locator('[data-testid="user-email"]')).toContainText('test@example.com');
+  // ✅ Verify sidebar loaded
+  await expect(page.locator('nav.sidebar')).toBeVisible();
+});
+
+// WRONG — this passes even when completely broken
+test('dashboard loads', async ({ page }) => {
+  await page.goto('/dashboard');
+  // no assertions!
+});
+```
+
+### 2. A test is FINISHED when it has ALL of these
+
+A test is NOT done until it has:
+- [ ] At least one `await expect(page).toHaveURL()` assertion
+- [ ] At least one `await expect(locator).toBeVisible()` assertion
+- [ ] At least one content/data verification (`toContainText`, `toHaveValue`, etc.)
+- [ ] Error case coverage (what happens when it fails?)
+- [ ] No `// TODO` or placeholder assertions
+
+If you cannot check ALL of these, the test is incomplete. Say so and explain what's missing.
+
+### 3. Test structure — ALWAYS follow this pattern
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('[Feature Name]', () => {
+  test.describe('happy path', () => {
+    test('should [specific behavior] when [specific condition]', async ({ page }) => {
+      // ARRANGE — navigate, set up state
+      // ACT — perform the user action
+      // ASSERT — verify SPECIFIC outcomes (URL, elements, data)
+    });
+  });
+
+  test.describe('error handling', () => {
+    test('should show error when [invalid input]', async ({ page }) => {
+      // Test the failure mode
+    });
+  });
+
+  test.describe('edge cases', () => {
+    test('should handle [empty state / max values / etc]', async ({ page }) => {
+      // Test boundaries
+    });
+  });
+});
+```
+
+### 4. Port configuration — ALWAYS use test ports
+
+E2E tests run on TEST ports, never dev ports:
+
+| Service   | Test Port | Base URL                   |
+|-----------|-----------|----------------------------|
+| Website   | 4000      | http://localhost:4000      |
+| API       | 4010      | http://localhost:4010      |
+| Dashboard | 4020      | http://localhost:4020      |
+
+The `baseURL` is already set in `playwright.config.ts`. Use relative paths:
+
+```typescript
+// CORRECT — uses baseURL from config
+await page.goto('/dashboard');
+
+// WRONG — hardcoded URL
+await page.goto('http://localhost:3000/dashboard');
+```
+
+### 5. What to test for each page type
+
+**For a page/route:**
+- URL is correct after navigation
+- Page title / heading is present
+- Key UI elements are visible (nav, sidebar, footer, etc.)
+- Dynamic data is loaded and displayed
+- Links navigate to correct destinations
+- Responsive behavior (if applicable)
+
+**For a form:**
+- Empty form shows proper validation messages
+- Valid submission succeeds (verify success state)
+- Invalid input shows specific error messages
+- Submit button disabled during processing
+- Form clears or redirects after success
+
+**For an API endpoint:**
+- Correct response status code
+- Response body matches expected shape
+- Error responses have proper status codes and messages
+- Authentication/authorization is enforced
+
+**For authentication:**
+- Login with valid credentials succeeds
+- Login with invalid credentials shows error
+- Protected pages redirect to login
+- Logout clears session
+- Token expiry is handled
+
+### 6. Naming convention
+
+File: `tests/e2e/[feature-name].spec.ts`
+
+Examples:
+- `tests/e2e/auth-login.spec.ts`
+- `tests/e2e/dashboard-overview.spec.ts`
+- `tests/e2e/api-users.spec.ts`
+- `tests/e2e/settings-profile.spec.ts`
+
+## Step 0 — Auto-Branch (if on main)
+
+Before creating any files, check the current branch:
+
+```bash
+git branch --show-current
+```
+
+**Default behavior** (`auto_branch = true` in `claude-mastery-project.conf`):
+- If on `main` or `master`: automatically create a feature branch and switch to it:
+  ```bash
+  git checkout -b test/<feature-name>
+  ```
+  Report: "Created branch `test/<feature>` — main stays untouched."
+- If already on a feature branch: proceed
+- If not a git repo: skip this check
+
+**To disable:** Set `auto_branch = false` in `claude-mastery-project.conf`. When disabled, warn and ask the user before proceeding on main.
+
+## Step 1 — Gather Information
+
+Before writing the test:
+
+1. **Read the source code** for the feature/page being tested
+2. **Identify all assertions** — what URLs, elements, and data should be verified?
+3. **Identify error states** — what can go wrong? What should the user see?
+4. **Check for test data** — does the test need seeded data? Mock API responses?
+
+## Step 2 — Ask What to Verify (if not obvious)
+
+If the feature has multiple possible success criteria, ask the user:
+
+Use AskUserQuestion to clarify:
+- "What specific elements should be visible on this page?"
+- "What data should be displayed after this action?"
+- "What error message should appear for invalid input?"
+
+## Step 3 — Write the Test
+
+Create the test file at `tests/e2e/[feature-name].spec.ts` following ALL rules above.
+
+Every test file MUST include:
+1. At least one happy-path test
+2. At least one error-case test
+3. Explicit assertions in every `test()` block
+
+## Step 4 — Verification Checklist
+
+After writing, verify:
+
+- [ ] File is at `tests/e2e/[name].spec.ts`
+- [ ] Every `test()` has at least 3 assertions (URL, element, data)
+- [ ] Error cases are covered
+- [ ] No hardcoded ports (uses baseURL from config)
+- [ ] No `// TODO` placeholders
+- [ ] Test names describe behavior: "should [verb] when [condition]"
+- [ ] No `any` types
+- [ ] No `.only` left in the code
+
+## Running Tests
+
+```bash
+# Run all E2E tests (spawns servers automatically on test ports)
+pnpm test:e2e
+
+# Run a specific test file
+pnpm test:e2e tests/e2e/auth-login.spec.ts
+
+# Run with UI mode (debug)
+pnpm test:e2e:ui
+
+# Run headed (see the browser)
+pnpm test:e2e:headed
+
+# View the last test report
+pnpm test:e2e:report
+```
+
+## RuleCatch Report
+
+After the test file is created and verified, check RuleCatch:
+
+- If the RuleCatch MCP server is available: query for violations in the new test file
+- Report any violations found (missing assertions, TypeScript issues, etc.)
+- If no MCP: suggest checking the RuleCatch dashboard