docs(changelog): release v0.1.4

.claude/hooks/git-gate.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Claude Code PreToolUse hook (Bash matcher).
+# Denies git commit/push/merge/rebase when:
+#   - the command uses --no-verify (bypasses Husky hooks), or
+#   - `npx tsc --noEmit` fails, or
+#   - ESLint fails on the staged (commit), unpushed (push) or uncommitted (merge/rebase) .ts/.js
+#     files under src/; push with no upstream/origin/main base checks all of src/,
+#   - or the toolchain (node_modules/.bin/tsc, eslint) is missing: run `npm ci`.
+# Fails closed: unparseable input that looks like a git write, or a failing git diff, is
+# blocked or escalated to a full check instead of passing.
+# Emits a PreToolUse deny decision as JSON; otherwise exits 0 silently.
+
+set -o pipefail
+
+INPUT=$(cat)
+# Parse the tool input with jq, falling back to node (always present in this repo). If neither
+# can parse it, fail closed: an unparsed command must never be allowed through silently.
+if command -v jq >/dev/null 2>&1; then
+  CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) || CMD_PARSE_FAILED=1
+elif command -v node >/dev/null 2>&1; then
+  CMD=$(printf '%s' "$INPUT" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{process.stdout.write(String((JSON.parse(s).tool_input||{}).command||""))})' 2>/dev/null) || CMD_PARSE_FAILED=1
+else
+  CMD_PARSE_FAILED=1
+fi
+if [ -n "$CMD_PARSE_FAILED" ]; then
+  # Only block unparsed input that looks like a git write; other commands are not gated.
+  if printf '%s' "$INPUT" | grep -qE 'git[^a-z].*(commit|push|merge|rebase)'; then
+    printf '%s\n' "Git gate: could not parse the tool input (install jq or node). Git write blocked." >&2
+    exit 2
+  fi
+  exit 0
+fi
+
+GIT_WRITE='(^|[[:space:]&|;(])git([[:space:]]+-[^[:space:]]+)*[[:space:]]+(commit|push|merge|rebase)([[:space:]]|$)'
+if ! printf '%s' "$CMD" | grep -qE "$GIT_WRITE"; then
+  exit 0
+fi
+
+deny() {
+  local reason=$1
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg reason "$reason" \
+      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":$reason}}'
+  else
+    # Fallback: exit code 2 blocks the tool call and shows stderr to the model.
+    printf '%s\n' "$reason" >&2
+    exit 2
+  fi
+  exit 0
+}
+
+# Quoted strings (commit messages, echo text) are stripped before matching flags, so
+# `git commit -m "fix -n parsing --no-verify"` is not mistaken for a bypass.
+STRIPPED=$(printf '%s' "$CMD" | sed -E "s/\"([^\"\\\\]|\\\\.)*\"//g; s/'[^']*'//g")
+if ! printf '%s' "$STRIPPED" | grep -qE "$GIT_WRITE"; then
+  exit 0
+fi
+
+# --no-verify on any git write, or `-n` (alone or in a short-flag cluster) on `git commit` only.
+GIT_COMMIT='git([[:space:]]+-[^[:space:]]+)*[[:space:]]+commit'
+if printf '%s' "$STRIPPED" | grep -qE -- '(^|[[:space:]])--no-verify([[:space:]=]|$)' \
+  || printf '%s' "$STRIPPED" | grep -qE -- "${GIT_COMMIT}[^|;&]*[[:space:]]-[[:alpha:]]*n[[:alpha:]]*([[:space:]]|\$)"; then
+  deny "Git gate: --no-verify is not allowed. Fix the failing Husky hooks instead of bypassing them."
+fi
+
+ROOT=${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}
+[ -n "$ROOT" ] || exit 0
+cd "$ROOT" || exit 0
+
+# FULL=1 checks the whole project (tsc + eslint on src/) instead of the changed files only.
+FULL=0
+if printf '%s' "$STRIPPED" | grep -qE 'git([[:space:]]+-[^[:space:]]+)*[[:space:]]+push'; then
+  BASE=$(git rev-parse --abbrev-ref '@{u}' 2>/dev/null)
+  if [ -z "$BASE" ] && git rev-parse --verify --quiet origin/main >/dev/null; then
+    BASE=origin/main
+  fi
+  if [ -n "$BASE" ]; then
+    # A failing diff (e.g. no merge base) falls back to a full check instead of passing.
+    FILES=$(git diff --name-only --diff-filter=d "$BASE"...HEAD 2>/dev/null) || FULL=1
+  else
+    # No base ref to diff against: fail closed with a full check instead of passing.
+    FULL=1
+  fi
+elif printf '%s' "$STRIPPED" | grep -qE "${GIT_COMMIT}([[:space:]]|\$)"; then
+  FILES=$(git diff --cached --name-only --diff-filter=d 2>/dev/null) || FULL=1
+else
+  # merge/rebase: the incoming commits already passed their own gates; check that the local
+  # working tree (staged + unstaged src/ changes vs HEAD) is not broken before rewriting history.
+  FILES=$(git diff HEAD --name-only --diff-filter=d 2>/dev/null) || FULL=1
+fi
+
+if [ "$FULL" -eq 1 ]; then
+  CODE_FILES=src
+else
+  CODE_FILES=$(printf '%s\n' "$FILES" | grep -E '^src/.*\.(ts|js)$' || true)
+  [ -n "$CODE_FILES" ] || exit 0
+fi
+
+if [ ! -x node_modules/.bin/tsc ] || [ ! -x node_modules/.bin/eslint ]; then
+  deny "Git gate: BLOCKED because the local toolchain is missing (node_modules/.bin/tsc or eslint not found). Run \`npm ci\` in ${ROOT} and retry."
+fi
+
+FAILURES=""
+
+TSC=$(node_modules/.bin/tsc --noEmit 2>&1)
+if [ $? -ne 0 ]; then
+  FAILURES="${FAILURES}--- TypeScript (tsc --noEmit) ---
+${TSC}
+
+"
+fi
+
+LINT=$(printf '%s\n' "$CODE_FILES" | xargs node_modules/.bin/eslint 2>&1)
+if [ $? -ne 0 ]; then
+  FAILURES="${FAILURES}--- ESLint ---
+${LINT}
+
+"
+fi
+
+if [ -n "$FAILURES" ]; then
+  deny "Git gate: commit/push/merge/rebase BLOCKED by errors in changed files.
+
+Fix the errors below and retry.
+
+${FAILURES}"
+fi
+
+exit 0

.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__plugin_engram_engram__mem_search",
+      "mcp__plugin_engram_engram__mem_get_observation",
+      "mcp__plugin_engram_engram__mem_save",
+      "mcp__plugin_engram_engram__mem_context",
+      "mcp__plugin_engram_engram__mem_session_summary"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/git-gate.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "F=$(jq -r '.tool_input.file_path // empty'); [ -z \"$F\" ] && exit 0; case \"$F\" in *.ts|*.js|*.json|*.md) (cd \"$CLAUDE_PROJECT_DIR\" && npx --no prettier --config .prettierrc.js --write --log-level=silent \"$F\" >/dev/null 2>&1) || true ;; esac; exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/purple-baileys/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: purple-baileys
+description: >
+  Landmarks and invariants of the Baileys channel in evolution-in-purple:
+  whatsapp.baileys.service.ts entry points, onWhatsApp guards, the on-WhatsApp cache,
+  createJid, @lid (LID) addressing rules, QR / pairing code flow and the Baileys version pin.
+  Read BEFORE touching message receive/send, JID handling or connection logic.
+  Trigger: change in whatsapp.baileys.service.ts, onWhatsappCache.ts, createJid.ts, @lid / remoteJidAlt handling, QR or pairing, Baileys upgrade.
+---
+
+# Skill: purple-baileys
+
+File: `src/api/integrations/channel/whatsapp/whatsapp.baileys.service.ts` (~5k lines).
+Baileys is pinned exactly: `"baileys": "7.0.0-rc.9"` (`package.json:80`). Never use a caret;
+an upgrade is its own task with manual QR + send/receive verification.
+
+## Landmarks (verify line numbers before citing; they drift)
+
+| Area | Location |
+|---|---|
+| QR / pairing in `connectionUpdate` | `:334`, pairing code `:375-380`, QR limit `:336` |
+| Auth state selection (Redis / Prisma / provider files) | `defineAuthState` `:556` |
+| Socket creation | `createClient` `:576` |
+| Public connect entry | `connectToWhatsapp` `:723` |
+| Inbound handler | `messageHandle['messages.upsert']` `:1082` |
+| LID → PN swap before emit | `:1478-1480` |
+| Contact upsert using `remoteJidAlt` | `:1512-1517` |
+| Event dispatch (`connection.update`, `messages.upsert`) | `:1902-1919` |
+| Outbound core | `sendMessageWithTyping` `:2289` |
+| onWhatsApp guards (throw 400 when `!exists`) | `:2297`, `sendPresence` `:2571`, `blockUser` `:4118` |
+| Number verification | `whatsappNumber` `:3507` (cache → Baileys `onWhatsApp` `:3566`) |
+
+Helpers: `src/utils/onWhatsappCache.ts` (`saveOnWhatsappCache` `:73`, `getOnWhatsappCache`
+`:182`, `normalizeJid` `:68`) and `src/utils/createJid.ts` (`createJid` `:35`).
+
+## @lid rules (hard)
+
+1. **LID → PN is NOT derivable.** A `<digits>@lid` carries no phone number. Never compute,
+   guess or strip the suffix to obtain one.
+2. **PN is only learned** from: `key.remoteJidAlt` / `participantAlt` on received messages,
+   group participant metadata, or history sync. Persist the mapping when observed
+   (contact upsert at `:1512-1517`, `saveOnWhatsappCache`).
+3. **Never strip `@lid` on outbound.** `createJid` returns `@lid` JIDs unchanged
+   (`createJid.ts:38-40`); `whatsappNumber` skips Baileys verification for `@lid` and treats an
+   uncached LID as existing (`:3562`, `:3586-3594`). Keep both behaviors.
+4. The inbound swap at `:1478-1480` rewrites `remoteJid` to `remoteJidAlt` only when the alt is
+   present. Consumers (orbit, stenfar) also read `remoteJidAlt`/`addressingMode` themselves —
+   changing this is a contract change (`purple-contract`).
+
+Detail, failure modes and examples: `references/lid.md`.
+
+## onWhatsApp guards
+
+`sendMessageWithTyping`, `sendPresence` and `blockUser` all call `whatsappNumber` and throw
+`BadRequestException(isWA)` when `!isWA.exists` and the JID is not a group/broadcast. The 400
+body (the `OnWhatsAppDto`) is what consumers see on "number not on WhatsApp". Do not bypass the
+guard; fix the cache or the JID instead.
+
+## QR / pairing
+
+- `connectToWhatsapp(number?)` — passing a number enables pairing-code mode
+  (`this.phoneNumber`, `:375-380`); otherwise only QR.
+- QR emits `qrcode.updated` with `{ pairingCode, code, base64 }` (`:392`, `:400`); the count is
+  capped by `QRCODE.LIMIT` (`:336`), after which the instance stops retrying.
+
+## Verification
+
+No automated tests. After changes: `npx tsc --noEmit`, `npm run build`, then a manual run
+with a test instance — QR scan, inbound 1:1 (PN and LID contact), inbound group, outbound text.

.claude/skills/purple-baileys/references/lid.md

@@ -0,0 +1,44 @@
+# purple-baileys — @lid detail
+
+## What a LID is
+
+WhatsApp privacy addressing: some 1:1 and group participants appear as `<digits>@lid`
+(`key.addressingMode === 'lid'`) instead of `<phone>@s.whatsapp.net`. The digits are an opaque
+identifier, not a phone number.
+
+## Where the phone number (PN) can come from
+
+| Source | Field | Code |
+|---|---|---|
+| Received message key | `key.remoteJidAlt` (1:1), `key.participantAlt` (groups) | `whatsapp.baileys.service.ts:159-160` (key type), `:1250-1251`, `:1478`, `:1516-1517` |
+| Group metadata | participant entries returned by Baileys group metadata | group fetch paths (shape depends on Baileys version — verify) |
+| History sync | message keys in `messaging-history.set` | `whatsapp.baileys.service.ts:927` |
+| On-WhatsApp cache | `jidOptions`, `lid` | `src/utils/onWhatsappCache.ts:73`, `:182` |
+
+If none of these has been observed, the PN is unknown. Reply to the LID JID.
+
+## Outbound
+
+- `createJid` keeps `@lid`, `@g.us`, `@s.whatsapp.net`, `@broadcast` untouched
+  (`src/utils/createJid.ts:38-44`); only bare numbers get normalized (BR/MX/AR rules at `:2`, `:17`).
+- `whatsappNumber` (`whatsapp.baileys.service.ts:3507`) resolves users from the cache first, then
+  calls `client.onWhatsApp` only for non-LID JIDs (`:3562-3566`). An uncached LID returns
+  `exists: true` with `lid: 'lid'` (`:3586-3594`).
+
+## Known failure modes
+
+- Stripping `@lid` and sending to `<digits>@s.whatsapp.net` → 400 "exists: false" from the guard
+  or delivery to the wrong account.
+- Treating `remoteJid` as the stable chat key: the swap at `:1478-1480` means the same chat can
+  arrive as PN or LID depending on whether `remoteJidAlt` was present.
+- Persisting a LID as a phone number in consumer CRMs. Consumers must read `remoteJidAlt`
+  (orbit: `orbit-backend/src/evolution-api-webhook/evolution-api-webhook.service.ts:227-231`;
+  stenfar: `canal-stenfar/src/services/whatsapp/phoneExtractor.js:35-44`).
+
+## Manual verification matrix
+
+1. 1:1 inbound from a PN contact → `remoteJid` is `@s.whatsapp.net`.
+2. 1:1 inbound from a LID contact with alt → `remoteJid` swapped to PN, `remoteJidAlt` kept.
+3. Group inbound with LID participant → `participant` LID, `participantAlt` PN when present.
+4. Outbound to a LID JID → delivered; no 400.
+5. Outbound to an unknown PN → `onWhatsApp` check, 400 when not registered.

.claude/skills/purple-contract/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: purple-contract
+description: >
+  The external contract of evolution-in-purple as consumed by orbit, canal-whatsapp and
+  stenfar: webhook payload envelope, event naming (MESSAGES_UPSERT vs messages-upsert with
+  webhookByEvents), and the REST routes each consumer calls. Read BEFORE changing any route,
+  DTO, response shape, webhook event or payload field.
+  Trigger: change to a REST route, request/response shape, webhook event name or payload, message key fields (remoteJid, remoteJidAlt), or instance/webhook config.
+---
+
+# Skill: purple-contract
+
+This engine replaces Evolution API 2.3.7 for three consumers. **The contract is "behaves
+exactly like Evolution 2.3.7"** unless a versioned breaking change says otherwise.
+Consumer matrix (endpoint/event × consumer, with source paths): `references/consumer-matrix.md`.
+
+## Webhook envelope
+
+Built in `src/api/integrations/event/webhook/webhook.controller.ts:93-103`:
+
+```ts
+{ ...extra, event, instance, data, destination, date_time, sender, server_url, apikey }
+```
+
+- `event` is the dotted lowercase name (`messages.upsert`, `connection.update`, ...).
+- Enabled-events list is stored uppercase with underscores (`MESSAGES_UPSERT`), derived at
+  `webhook.controller.ts:88`.
+- With `webhookByEvents: true` the URL becomes `${url}/${event-kebab}` — e.g.
+  `/messages-upsert` (`webhook.controller.ts:89`, `:109-110`). orbit depends on this
+  (routes `whatsapp/messages-upsert`, `qrcode-updated`, `connection-update`).
+- canal-whatsapp and stenfar use a single URL (`byEvents: false`) and switch on `event`.
+
+## Message key fields consumers read
+
+`data.key.remoteJid`, `remoteJidAlt`, `participant`, `participantAlt`, `addressingMode`,
+`fromMe`, `id`. The LID → PN swap (`whatsapp.baileys.service.ts:1478-1480`) is part of the
+contract (see `purple-baileys`).
+
+## REST surface consumers use
+
+Union of all consumers (details per consumer in the matrix):
+`/instance/{create,fetchInstances,connect,connectionState,logout}`,
+`/message/{sendText,sendMedia,sendWhatsAppAudio,sendReaction}`,
+`/chat/{markMessageAsRead,sendPresence,getBase64FromMediaMessage,findMessages,findContacts}`,
+`/group/findGroupInfos`, `/webhook/{set,find}`. Auth: `apikey` header.
+canal also calls `/group/findGroupByJid`, which does **not** exist here (see matrix §Open questions).
+
+## Rules
+
+1. **Non-breaking by default.** Additive fields are allowed; renaming, removing, retyping a
+   field, changing a status code, an event name or a URL suffix is breaking.
+2. **Breaking change ⇒ all of:** (a) new fork MAJOR/MINOR per `purple-release`, (b) a
+   `CHANGELOG.md` entry under the `evolution-in-purple` section with a migration note,
+   (c) a consumer check: grep each consumer listed in the matrix for the affected
+   route/event/field and record positives/negatives in the task doc.
+3. Update `references/consumer-matrix.md` in the same change whenever a consumer starts or
+   stops using a route/event.
+4. Consumers are read-only from this repo. Never edit orbit, canal-whatsapp or stenfar from
+   here; open a task in the consumer instead.
+
+## Consumer check (procedure)
+
+```bash
+rg -n '<route-or-event-or-field>' \
+  ../../orbit/orbit-backend/src \
+  ../../canal-whatsapp/canal-whatsapp-backend/src \
+  ../../stenfar/canal-stenfar/src
+```
+
+Paths are relative to a checkout under `~/Programacion/evolution/<worktree>`; adjust if the
+layout differs. canal-whatsapp calls REST through `@alien-2-0-llc/sdk-evolution-api`, so also
+grep that SDK's method names (`sendText`, `setWebhook`, ...).