# API Development Guidelines

Follow REST best practices when developing API endpoints.

## Principles

- Use semantic HTTP methods (GET, POST, PUT, DELETE)
- Return appropriate status codes
- Include error messages in response body

---
applyTo: "src/api/**/*.ts"  # REQUIRED
excludeAgent: "code-review"  # Optional
---

# TaskManager Development Guidelines

## Architecture

### Frontend
- React 18 with TypeScript
- Vite for build tooling
- Zustand for state management
- Tailwind CSS for styling

### Backend
- Node.js with Express
- PostgreSQL with Prisma ORM
- JWT for authentication

## Coding Conventions

- Use TypeScript strict mode
- Functional components with hooks
- Colocate tests with source files
- Use Zod for runtime validation

## Testing

- Use Vitest for unit tests
- Aim for 80% coverage on new code
- Mock external dependencies

## Examples

\`\`\`typescript
// Good: RESTful endpoint
app.get('/api/users', async (req, res) => {
  try {
    const users = await db.users.findAll();
    res.json({ users });
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch users' });
  }
});
\`\`\`

---
applyTo: "app/models/**/*.rb"
---

# Model Guidelines

These rules apply only to Ruby model files.

## Conventions

- Use ActiveRecord validations
- Define associations explicitly
- Add database indexes for foreign keys

---
applyTo: "**/*.ts,**/*.tsx"
---

# TypeScript Guidelines

These rules apply to all TypeScript files.

## Type Safety

- Always define explicit types for function parameters
- Avoid using `any` type
- Use `unknown` instead of `any` for truly unknown types

---
applyTo:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
---

# API Endpoint Guidelines

These rules apply only to API files.

## Requirements

- All endpoints must have error handling
- Use async/await for database calls
- Log all errors with structured logging
- Validate input with Zod schemas

## Example

\`\`\`typescript
import { z } from 'zod';

const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

app.post('/api/users', async (req, res) => {
  try {
    const data = createUserSchema.parse(req.body);
    const user = await db.users.create(data);
    res.status(201).json({ user });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(400).json({ error: error.errors });
    }
    logger.error('Failed to create user', { error });
    res.status(500).json({ error: 'Internal server error' });
  }
});
\`\`\`

# All TypeScript files
applyTo: "**/*.ts"

# React components
applyTo: "src/**/*.{tsx,jsx}"

# API routes
applyTo: "src/api/**/*.ts"

# Test files
applyTo: "**/*.test.ts"

# All files (any of these work)
applyTo: "**"
applyTo: "*"
applyTo: "**/*"

# Multiple patterns (array)
applyTo:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
  - "src/routes/**/*.ts"

---
applyTo: "**"
excludeAgent: "code-review"
---

# Coding Agent Only Instructions

These instructions are only used by the Copilot coding agent.

- Focus on implementation patterns
- Suggest modern syntax alternatives
- Optimize for readability in generated code

---
applyTo: "**/*.test.ts"
excludeAgent: "coding-agent"
---

# Code Review Only Instructions

These instructions are only used by Copilot code review.

- Verify test coverage is adequate
- Check for proper assertions
- Ensure tests are not flaky

---
applyTo: "**/*.test.ts"
---

# Testing Standards

All tests use Jest and React Testing Library.

## Component Tests

- Test user interactions, not implementation
- Use `screen.getByRole` over `getByTestId`
- Mock external dependencies
- Test accessibility (ARIA roles)

## Example

\`\`\`typescript
test('submits form when valid', async () => {
  render(<LoginForm />);

  await userEvent.type(screen.getByLabelText('Email'), 'test@example.com');
  await userEvent.type(screen.getByLabelText('Password'), 'password123');
  await userEvent.click(screen.getByRole('button', { name: 'Login' }));

  expect(mockLogin).toHaveBeenCalledWith({
    email: 'test@example.com',
    password: 'password123',
  });
});
\`\`\`

---
applyTo:
  - "src/db/**/*.ts"
  - "src/repositories/**/*.ts"
---

# Database Access Patterns

We use Prisma ORM with PostgreSQL.

## Query Guidelines

- Always use transactions for multi-step operations
- Use `select` to limit returned fields
- Include proper indexes
- Handle unique constraint violations

## Example

\`\`\`typescript
// Good: Transaction with error handling
async function transferFunds(fromId: string, toId: string, amount: number) {
  try {
    await prisma.$transaction(async (tx) => {
      await tx.account.update({
        where: { id: fromId },
        data: { balance: { decrement: amount } },
      });

      await tx.account.update({
        where: { id: toId },
        data: { balance: { increment: amount } },
      });
    });
  } catch (error) {
    if (error.code === 'P2025') {
      throw new Error('Account not found');
    }
    throw error;
  }
}
\`\`\`