chore: add pre-commit hooks, docker-compose, WS protocol doc, and sta…

[kulkan-IV]

Summary

This PR bundles four developer-experience
improvements shipped together as a single
branch.

Closes #138
Closes #139
Closes #133
Closes #132

---

Changes

#138 — WebSocket event protocol

reference (docs/websocket-protocol.md)
Added a standalone 450-line protocol
reference covering every event the /ws
feed can emit:

• Server → client: connected,
  snapshot, subscribed, intent_created,
  intent_accepted, intent_filled,
  intent_cancelled, intent_expired,
  replay_start, replay_end,
  replay_too_old
• Client → server: subscribe (chain
  filter), replay (gap recovery)
• Full payload shapes and field tables for
  every event
• Heartbeat / keepalive behaviour and
  sequence-number gap-detection explanation
• Complete Intent, TokenInfo, and
  StellarToken type reference
• Quick-start code example and link to
  scripts/solver-bot.ts
• Notes pending updates once issues Write a backup/restore runbook for the persistent intents store #61
  (topic subscriptions) and Add an audit trail for cancelled and expired intents #62 (event
  sequencing) land

#139 — Intent state machine diagram

(README.md)
Added a Mermaid stateDiagram-v2 diagram
and a transition-rules table to the README,
covering all six states (open,
accepted, filled, cancelled,
expired, slashed) and every valid
transition with its trigger and guard
conditions.

#133 — docker-compose.yml for local

development
Added a compose file that starts the full
local stack with a single command:

• postgres service — PostgreSQL 16
  Alpine, healthcheck, named volume,
  credentials matching .env.example
• backend service — builds from local
  Dockerfile, waits for postgres
  healthcheck, overrides DATABASE_URL to
  use the container hostname, optional .env
  file passthrough
• README Docker section expanded with
  full-stack, DB-only, and image-only usage
  instructions

#132 — Pre-commit hooks (husky +

lint-staged)

• Added husky@9.1.7 and
  lint-staged@17.2.0 as pinned dev
  dependencies
• "prepare": "husky" script so hooks
  install automatically after npm install
• .husky/pre-commit runs lint-staged
  (ESLint --fix on staged .ts files) then
  npm run typecheck (whole-project type
  check) — fast staged-only lint, full type
  safety on every commit
• Also fixed a pre-existing JSON syntax
  error in package.json (duplicate
  solver:demo key that was breaking npm install)

---

Testing

npm run lint
npm run typecheck
npm test
npm run test:e2e

All checks pass. No runtime behaviour was
changed — this PR is purely additive (docs,
config, dev tooling).

[drips-wave]

@kulkan-IV Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[james2177]

fix your conflicts