Bump del SDK y regeneración del package-lock en Linux

Precaución

Regla: cada vez que se sube la versión de @ticketplushq/tables-sdk en un consumidor (tables-web, tables-app, bites-kiosk), el package-lock.json se regenera en Linux vía Docker — nunca en macOS — para garantizar que CI (npm ci) no falle por un lock divergente.

Cuándo aplica

Tras bumpear @ticketplushq/tables-sdk en el package.json de cualquiera de los 3 consumidores del SDK:

Repo	Convención de rango
tables-web	versión exacta (ej. "1.5.1")
tables-app	caret (ej. "^1.5.1")
bites-kiosk	caret (ej. "^1.5.1")

Por qué en Linux y no en macOS

1. CI corre npm ci, que aborta si package-lock.json no concuerda exactamente con package.json. El lock es el artefacto que CI consume; debe generarse en el mismo SO/arquitectura que CI (Linux).
2. Un npm install en macOS puede resolver dependencias opcionales / binarios por-plataforma distintos y/o hashes de integridad distintos → produce un lock que CI (Linux) rechaza, rompiendo el build aunque “localmente funcione”.
3. El SDK se publica a GitHub Packages (registry privado). El token de gh auth token NO tiene scope read:packages; el token válido vive en ~/.npmrc y hay que montarlo en el container para que npm pueda resolver el paquete.

Pasos

1. Bumpear la dep en package.json respetando la convención de rango del repo (web exacto, app/kiosk caret).

2. Regenerar solo el lock, en Linux, con auth a GH Packages:

   cd repos/<tables-web|tables-app|bites-kiosk>
   
   docker run --rm \
     -v "$PWD":/app -w /app \
     -v "$HOME/.npmrc":/root/.npmrc:ro \
     node:20.18.3 \
     sh -lc 'npm install --package-lock-only --ignore-scripts --no-audit --no-fund'

• node:20.18.3 — versión de .nvmrc de los repos (alinear con la imagen de CI si cambia).
• --package-lock-only — actualiza únicamente package-lock.json, sin escribir node_modules (rápido, sin contaminar el working-tree).
• -v "$HOME/.npmrc":/root/.npmrc:ro — auth de GH Packages (read-only).

Verificación

# El SDK debe quedar en la versión nueva y resuelto desde GH Packages:
grep -A2 '"node_modules/@ticketplushq/tables-sdk"' package-lock.json | grep -E "version|resolved"
# version: "1.5.1"
# resolved: "https://npm.pkg.github.com/download/@ticketplushq/tables-sdk/1.5.1/..."

git diff --stat package.json package-lock.json   # el diff del lock debe ser MINIMO

El diff esperado del lock es solo la entrada de @ticketplushq/tables-sdk (version + resolved + integrity). Si aparecen muchas otras líneas, revisar que la imagen de Node y el ~/.npmrc sean los correctos.

Commit

package.json y package-lock.json van juntos en el mismo commit. Ejemplo:

chore(deps): bump @ticketplushq/tables-sdk a 1.5.1

Lock regenerado con npm install en Docker Linux (node:20.18.3) — GH Packages.

Relación con el release del SDK

Este runbook es el paso downstream (en los consumidores). El upstream — publicar la versión nueva del SDK — se hace en tables-sdk con bump + tag v* sobre master (dispara release.yml → GH Packages). Recién cuando esa versión está publicada, los consumidores pueden resolverla con el comando de arriba.

Troubleshooting

• npm error code E401 / Unable to authenticate: falta el ~/.npmrc con el token de GH Packages, o el token expiró. No sirve gh auth token (sin read:packages).
• 404 Not Found para la versión nueva: el SDK todavía no se publicó a GH Packages (esperar a que termine release.yml del tag v<version>).
• El lock cambia muchísimo: se corrió en macOS o con una imagen de Node distinta a la de CI. Descartar y rehacer con node:20.18.3.