feat: compartir el protocolo binario entre cliente y servidor

.dockerignore

@@ -0,0 +1,7 @@
+.git
+**/node_modules
+**/dist
+**/.next
+**/coverage
+**/.env*
+screenshots

.github/workflows/ci.yml

@@ -9,6 +9,42 @@ on:
       - main
 
 jobs:
+  protocol:
+    name: Shared protocol (typecheck, test, build)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: packages/protocol/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: packages/protocol
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        working-directory: packages/protocol
+        run: pnpm typecheck
+
+      - name: Test every client packet round trip
+        working-directory: packages/protocol
+        run: pnpm test
+
+      - name: Build
+        working-directory: packages/protocol
+        run: pnpm build
+
   api:
     name: API (typecheck, test, build)
     runs-on: ubuntu-latest
@@ -95,6 +131,7 @@ jobs:
   server:
     name: Server (typecheck, test, lint, build)
     runs-on: ubuntu-latest
+    needs: protocol
 
     steps:
       - name: Checkout
@@ -135,6 +172,7 @@ jobs:
   frontend:
     name: Frontend (typecheck, lint, build)
     runs-on: ubuntu-latest
+    needs: protocol
 
     steps:
       - name: Checkout
@@ -190,13 +228,13 @@ jobs:
       - name: Build Server image
         uses: docker/build-push-action@v6
         with:
-          context: ./server
+          context: .
           file: ./server/Dockerfile
           push: false
 
       - name: Build Frontend image
         uses: docker/build-push-action@v6
         with:
-          context: ./frontend
+          context: .
           file: ./frontend/Dockerfile
           push: false

README.md

@@ -172,8 +172,12 @@ Abrir `http://localhost:3000`.
 | API REST, autenticación y datos del juego | `api/` | 3001 |
 | Server del juego, WebSocket con protocolo binario | `server/` | 7666 |
 | Frontend, Next.js + PixiJS | `frontend/` | 3000 |
+| Contrato binario compartido | `packages/protocol/` | — |
 | PostgreSQL | `database/aoweb.sql` | 5432 |
 
+La guía para validar cambios del protocolo está en
+[`docs/protocol-testing.md`](docs/protocol-testing.md).
+
 ## Contribuir
 
 Las issues abiertas están en [github.com/Bitcoindefi/OpenAO/issues](https://github.com/Bitcoindefi/OpenAO/issues).

docs/protocol-testing.md

@@ -0,0 +1,75 @@
+# Cómo probar el protocolo binario compartido
+
+## 1. Probar el contrato aislado
+
+Desde la raíz del repositorio:
+
+```bash
+cd packages/protocol
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+La suite tiene un fixture y un snapshot de bytes para cada opcode
+cliente→servidor. Comprueba tres cosas distintas:
+
+- que todos los opcodes sean únicos;
+- que no pueda existir un opcode sin prueba;
+- que `decode(encode(payload))` recupere el mismo payload y conserve el formato
+  de bytes conocido, incluyendo strings UTF-8.
+
+## 2. Comprobar ambos consumidores
+
+```bash
+cd server
+pnpm install --frozen-lockfile
+pnpm exec tsc --noEmit
+pnpm exec eslint "src/**/*.ts"
+pnpm build
+```
+
+```bash
+cd frontend
+pnpm install --frozen-lockfile
+pnpm exec tsc --noEmit
+pnpm lint
+NEXT_PUBLIC_AOWEB_TEST_MODE=true pnpm build
+```
+
+En PowerShell, la última línea se ejecuta así:
+
+```powershell
+$env:NEXT_PUBLIC_AOWEB_TEST_MODE = "true"
+pnpm build
+```
+
+## 3. Demostrar que el contrato protege ambos lados
+
+Como prueba local temporal, renombrar `position` a `positionV2` únicamente en
+`packages/protocol/src/opcodes.ts` y ejecutar los dos typechecks del paso 2.
+Frontend y servidor deben fallar al compilar porque ambos consumen esa clave.
+Revertir el cambio después de comprobarlo.
+
+Si se cambia solamente el valor numérico de un opcode, `pnpm test` debe fallar
+contra el snapshot de bytes. Esto evita publicar accidentalmente un cambio de
+wire incompatible.
+
+## 4. Prueba manual dentro del juego
+
+Levantar API, server y frontend como indica el README. Entrar con un personaje y
+recorrer esta lista mientras se observa la consola del server y la del navegador:
+
+1. Conectar el personaje y caminar en las cuatro direcciones.
+2. Escribir en el chat y confirmar que tildes y emoji llegan completos.
+3. Usar, equipar, reordenar, tirar, recoger, comprar y vender un objeto.
+4. Lanzar ataque cuerpo a cuerpo, a distancia y un hechizo.
+5. Abrir banco, cambiar de pestaña, mover un objeto, depositar y retirar oro.
+6. Abrir mercado, refrescar y cerrar; abrir retos y refrescar.
+7. Abrir crafting y crear un objeto válido.
+8. Salir y volver a entrar.
+
+El resultado esperado es el mismo comportamiento previo, sin mensajes de
+`Unknown client packet opcode`, `Cannot read ... bytes` ni `trailing bytes`.
+Esos errores indican inmediatamente qué paquete no coincide con el contrato.

frontend/Dockerfile

@@ -6,14 +6,16 @@
 RUN corepack enable
 
 FROM base AS deps
-WORKDIR /app
+WORKDIR /app/frontend
 
-COPY package.json pnpm-lock.yaml ./
-COPY pnpm-workspace.yaml ./
+COPY packages/protocol/package.json /app/packages/protocol/package.json
+COPY packages/protocol/src /app/packages/protocol/src
+COPY packages/protocol/tsconfig.json /app/packages/protocol/tsconfig.json
+COPY frontend/package.json frontend/pnpm-lock.yaml frontend/pnpm-workspace.yaml ./
 RUN pnpm install --frozen-lockfile
 
 FROM deps AS build
-WORKDIR /app
+WORKDIR /app/frontend
 
 ARG API_BASE_URL=http://localhost:3001
 ARG NEXT_PUBLIC_API_BASE_URL=http://localhost:3001
@@ -27,9 +29,9 @@
 ARG DO_SPACES_ENDPOINT
 ARG DO_SPACES_REGION=nyc3
 ARG DO_SPACES_BUCKET
 ARG DO_SPACES_ACCESS_KEY_ID
 ARG DO_SPACES_SECRET_ACCESS_KEY
 ARG GAME_DATA_ADMIN_PROXY_TOKEN
 
 ENV API_BASE_URL=$API_BASE_URL
 ENV NEXT_PUBLIC_API_BASE_URL=$NEXT_PUBLIC_API_BASE_URL
@@ -38,24 +40,28 @@
 ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
 ENV SITE_URL=$SITE_URL
 ENV NEXT_BUILD_ID=$NEXT_BUILD_ID
 ENV GAME_DATA_ADMIN_PROXY_TOKEN=$GAME_DATA_ADMIN_PROXY_TOKEN
 
-COPY . .
+COPY packages/protocol /app/packages/protocol
+COPY frontend .
 RUN pnpm build
 
 FROM base AS runtime
-WORKDIR /app
+WORKDIR /app/frontend
 
 ENV NODE_ENV=production
 ENV PORT=3000
 
-COPY package.json pnpm-lock.yaml ./
-COPY pnpm-workspace.yaml ./
+COPY packages/protocol/package.json /app/packages/protocol/package.json
+COPY packages/protocol/src /app/packages/protocol/src
+COPY packages/protocol/tsconfig.json /app/packages/protocol/tsconfig.json
+COPY frontend/package.json frontend/pnpm-lock.yaml frontend/pnpm-workspace.yaml ./
 RUN pnpm install --prod --frozen-lockfile
 
-COPY --from=build /app/.next ./.next
-COPY --from=build /app/public ./public
-COPY --from=build /app/next.config.ts ./next.config.ts
+COPY --from=build /app/packages/protocol/dist /app/packages/protocol/dist
+COPY --from=build /app/frontend/.next ./.next
+COPY --from=build /app/frontend/public ./public
+COPY --from=build /app/frontend/next.config.ts ./next.config.ts
 
 EXPOSE 3000