infraestrutura: actualiza mapa de portas do gateway e regras de operação

Corrige a próxima porta livre (a 3188 documentada estava ocupada e causou um deploy falhado), regista o router youtube e o ssh-unified, e acrescenta três regras: backups do nginx nunca em sites-enabled/, cruzar sempre ss -tlnH com as portas roteadas, e contar ~40s de arranque nos MCPs Python/FastMCP.
fix: bump plugin.json de marketing/gestao/project-manager/wordpress
2026-07-30 22:58:47 +01:00 · 2026-07-30 22:58:46 +01:00
6 changed files with 49 additions and 8 deletions
@@ -9,3 +9,30 @@ layer: wiki
 # claude-plugins

 Marketplace de plugins Claude Code da Descomplicar
+
+## Versões — bumpar sempre nos DOIS sítios
+
+A versão de cada plugin vive em dois ficheiros e **não há automação a sincronizá-los**:
+
+| Ficheiro | Papel | Quem o lê |
+|---|---|---|
+| `<plugin>/.claude-plugin/plugin.json` | **fonte de verdade** | `/plugin update` — é esta que decide se há versão nova |
+| `.claude-plugin/marketplace.json` | agregado derivado | `/plugin marketplace update` — catálogo |
+
+Bumpar só o agregado **não tem efeito nenhum**: o catálogo mostra a versão nova, o
+`/plugin update` responde `already at the latest version` e o cache continua na antiga.
+Aconteceu a 30-07-2026 com marketing/gestao/project-manager/wordpress.
+
+Verificar coerência antes de commitar:
+
+```bash
+for p in */; do p=${p%/}; f="$p/.claude-plugin/plugin.json"; [ -f "$f" ] || continue
+  a=$(jq -r .version "$f")
+  b=$(jq -r ".plugins[]|select(.name==\"$p\").version" .claude-plugin/marketplace.json)
+  [ "$a" = "$b" ] || echo "DIVERGE $p: plugin.json=$a marketplace.json=$b"
+done
+```
+
+Depois de publicar: `/plugin marketplace update descomplicar-plugins` (catálogo) **e**
+`/plugin update <nome>@descomplicar-plugins` (reinstala no cache). O primeiro sozinho
+não actualiza o que corre.
@@ -1,7 +1,7 @@
 {
  "name": "gestao",
  "description": "Project management, time tracking, daily checkups, worklogs, reflections, knowledge management, archiving and compliance auditing. Backed by NotebookLM notebooks.",
-  "version": "1.6.2",
+  "version": "1.7.0",
  "author": {
    "name": "Descomplicar - Crescimento Digital",
    "url": "https://descomplicar.pt"
@@ -35,7 +35,6 @@ Gestao e health check dos MCPs no servidor gateway (VM 103, gateway.descomplicar
 | 2 | mcp-wikijs | 3152 | /v1/wikijs/mcp | P3 |
 | 5 | mcp-moloni | 3158 | /v1/moloni/mcp | P2 |
 | 6 | mcp-youtube-research | 3157 | /v1/youtube-research/mcp | P3 |
-| 7 | mcp-youtube | 3187 | /v1/youtube/mcp | P3 |

 ### systemd (24 services)

@@ -64,9 +63,15 @@ Gestao e health check dos MCPs no servidor gateway (VM 103, gateway.descomplicar
 | presenton-mcp | 3182 | /v1/presenton/mcp | supergateway | P3 |
 | cwp-mcp | 3183 | /v1/cwp/mcp | supergateway | P3 |
 | design-engine-mcp | 3184 | /v1/design-engine/mcp | supergateway | P3 |
+| mcp-youtube-router | 3198 | /v1/youtube/mcp | Python/Starlette | P3 |
+| mcp-youtube | 3187 | (nenhuma — upstream interno) | Python/FastMCP | P3 |
+| mcp-youtube-desc | 3199 | (nenhuma — upstream interno) | Python/FastMCP | P3 |
+| ssh-unified | 3192 | /v1/ssh-unified/mcp | Python/FastMCP | P3 |

 **Prioridades:** P1=critico (bloqueia trabalho) | P2=importante (degrada workflow) | P3=util
-**Proxima porta livre:** 3188
+**Proxima porta livre:** 3185 (depois: 3186, 3201). **Verificar sempre** — este mapa
+ficou desactualizado e a "3188" que aqui constava estava ocupada, causando um deploy falhado (30-07-2026):
+`ss -tlnH` cruzado com `grep -oE "127.0.0.1:3[0-9]{3}" /etc/nginx/sites-enabled/mcp-gateway`.

 ---

@@ -203,6 +208,13 @@ IP autorizado: `188.251.199.30`. Actualizar em `/etc/nginx/sites-enabled/` se mu
 - **Sempre** reportar estado mesmo que tudo OK
 - **Sempre** testar endpoint apos restart
 - **Sempre** actualizar mapa de portas ao adicionar/remover MCPs
+- **Nunca** guardar backups do nginx dentro de `sites-enabled/` — o include e por
+  wildcard, o backup passa a ser carregado e `nginx -t` falha com `duplicate log_format`,
+  quebrando *todo* o gateway. Backups vao para `/root/`.
+- **Nunca** confiar no "proxima porta livre" deste ficheiro sem cruzar `ss -tlnH` com as
+  portas roteadas no nginx.
+- **Contar** ~40s de arranque nos MCPs Python/FastMCP no gateway (import lento, I/O de
+  disco). Um probe imediato apos `systemctl start` da falso negativo — aguardar o bind.

 ---

@@ -215,7 +227,9 @@ IP autorizado: `188.251.199.30`. Actualizar em `/etc/nginx/sites-enabled/` se mu
 Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

 ```jsonl
-{"date":"","issue":"","fix":"","source":"user|auto"}
+{"date":"2026-07-30","issue":"Backup do nginx criado em sites-enabled/ -> duplicate log_format mcp_audit -> nginx -t falhou para todo o gateway","fix":"Backups para /root/. Verificar com nginx -t apos remover.","source":"auto"}
+{"date":"2026-07-30","issue":"Skill anunciava 3188 como proxima porta livre; estava ocupada -> deploy abortou","fix":"Cruzar ss -tlnH com grep 127.0.0.1:3XXX no nginx antes de escolher porta","source":"auto"}
+{"date":"2026-07-30","issue":"Probe tools/list imediatamente apos systemctl start deu falso negativo (FastMCP demora ~40s a bindar)","fix":"Poll da porta com timeout antes do probe HTTP","source":"auto"}
 ```

 *Adicionar nova linha após cada erro corrigido.*
@@ -1,7 +1,7 @@
 {
  "name": "marketing",
  "description": "Digital marketing strategy, SEO, content marketing, social media, ads, copywriting, video and YouTube. Backed by NotebookLM notebooks.",
-  "version": "1.0.0",
+  "version": "2.0.0",
  "author": {
    "name": "Descomplicar - Crescimento Digital",
    "url": "https://descomplicar.pt"
@@ -1,7 +1,7 @@
 {
  "name": "project-manager",
  "description": "Spec-driven project management with flexible sprints, scope validation, and NotebookLM-powered discovery. Prevents wasted work by forcing alignment before coding. 7 skills, 2 agents, 1 hook.",
-  "version": "1.1.0",
+  "version": "1.2.0",
  "author": {
    "name": "Descomplicar - Crescimento Digital",
    "url": "https://descomplicar.pt"
@@ -1,7 +1,7 @@
 {
  "name": "wordpress",
  "description": "WordPress development, maintenance and optimization - plugins, themes, WooCommerce, Elementor, Crocoblock. Backed by NotebookLM notebooks.",
-  "version": "1.0.0",
+  "version": "1.1.0",
  "author": {
    "name": "Descomplicar - Crescimento Digital",
    "url": "https://descomplicar.pt"