feat: implement M4 self-hosting, Docker & documentation
- Dockerfile with multi-stage build (Node 22 Alpine, sodium-native) - docker-compose.yml with health check for easy self-hosting - README with setup guide, API reference, and project overview - Architecture docs (data flow, component breakdown, protocol constants) - Security model docs (threat model, crypto primitives, self-hosting checklist) - GitHub Actions CI pipeline (test, typecheck, Docker smoke test, extension builds) - GitHub Actions release pipeline (GHCR push, extension zip artifacts) - CONTRIBUTING.md with dev setup and code style guidelines Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
76
CONTRIBUTING.md
Normal file
76
CONTRIBUTING.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
**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).
|
||||
Reference in New Issue
Block a user