# Contributing to CookieBridge

## Getting Started

1. Fork and clone the repository.
2. Install dependencies: `npm install`
3. Start the dev server: `npm run dev`
4. Run tests: `npm test`

## Development Setup

**Prerequisites:**
- Node.js 22+
- npm

**Relay server:**

```bash
npm install
npm run dev       # Starts with file watching on :8080
npm test          # Run test suite
npm run typecheck # Type checking only
```

**Admin panel (frontend):**

```bash
cd web
npm install
npm run dev       # Starts Vite dev server on :5173 (proxies API to backend)
```

The frontend dev server proxies `/api`, `/admin`, `/ws`, and `/health` to `http://localhost:8100`. Start the backend first with `npm run dev` (or adjust the proxy target in `web/vite.config.ts`).

**Full production build:**

```bash
npm run build:all   # Builds backend (tsc) + frontend (vite) → copies to public/
npm start           # Serves everything on :8080
```

**Extension:**

```bash
cd extension
npm install
node esbuild.config.mjs --browser=chrome
```

Load the unpacked extension from `extension/build/chrome/` in your browser.

## Making Changes

1. Create a branch from `main`.
2. Make focused, small commits. Each commit should do one thing.
3. Run `npm test` and `npm run typecheck` before pushing.
4. Open a pull request against `main`.

## Code Style

- TypeScript strict mode everywhere.
- No frameworks on the server — use Node.js built-ins where possible.
- Use libsodium for all cryptographic operations. No `crypto.subtle` or OpenSSL.
- Keep dependencies minimal.

## Testing

Tests use Vitest. Run with `npm test`.

- `tests/crypto.test.ts` — Encryption and signing primitives.
- `tests/pairing.test.ts` — Device pairing flow.
- `tests/conflict.test.ts` — LWW conflict resolution.
- `tests/integration.test.ts` — Full server integration tests.

Add tests for new features. Integration tests should start a real server instance.

## Commit Messages

Use clear, imperative commit messages:

```
feat: add cookie expiry sync support
fix: handle WebSocket reconnect on network change
docs: update self-hosting guide
```

## Reporting Issues

Open an issue with:
- What you expected to happen.
- What actually happened.
- Steps to reproduce.
- Browser and OS version (for extension issues).