KB-PLUGIN-018 — Convenção de wrapper directory para ZIPs de release

Contexto

ZIPs de release de plugin GLPI distribuídos via Mindplace devem ter um wrapper directory consistente no topo (uma pasta com o nome do plugin envolvendo todos os arquivos). Sem isso, o extrator do Mindplace podia mutilar paths em versões anteriores ao fix descrito em KB-PLUGIN-017.

Mesmo após o fix do detector, manter o wrapper continua sendo a forma "correta" e mais robusta: dá ao extrator um prefix bem-definido para remover, e remove ambiguidade na inspeção do ZIP.

Estrutura esperada

mcprotocol-1.0.3.zip
└── mcprotocol/            ← wrapper directory (nome = key do plugin = basename do diretório)
    ├── setup.php
    ├── hook.php
    ├── ajax/
    │   └── mcp.php
    ├── src/
    │   ├── Boot.php
    │   └── Server.php
    └── public/
        └── logo.png

Verificação rápida:

unzip -l <plugin>-<ver>.zip | head
# Primeiro entry DEVE ser "<plugin>/"
# Todos os demais entries DEVEM começar com "<plugin>/"

Fluxo oficial (automatizado)

Use o script bin/mindplace-release.sh documentado em KB-PLUGIN-013. Desde 2026-05-21, a Fase 3 do script gera ZIPs com wrapper directory automaticamente — rodando zip do diretório pai do plugin:

# Trecho relevante de bin/mindplace-release.sh (Fase 3)
PARENT_DIR="$(dirname "$PLUGIN_DIR")"
PLUGIN_BASENAME="$(basename "$PLUGIN_DIR")"
cd "$PARENT_DIR"
zip -r "$ZIP_PATH" "$PLUGIN_BASENAME" \
  --exclude "$PLUGIN_BASENAME/.git*" \
  --exclude "$PLUGIN_BASENAME/node_modules/*" \
  --exclude "$PLUGIN_BASENAME/vendor/*" \
  --exclude "*.DS_Store" \
  --exclude "*.zip" \
  -q

# Sanity check: aborta se wrapper não aparecer no topo
FIRST_ENTRY=$(unzip -Z1 "$ZIP_PATH" | head -1)
if [ "$FIRST_ENTRY" != "$PLUGIN_BASENAME/" ]; then
  err "ZIP gerado sem wrapper directory esperado..."
fi

O sanity check no fim falha rápido se algum dia o ZIP voltar a sair sem wrapper.

Geração manual (fallback)

Se precisar gerar localmente fora do script:

# A partir do diretório PAI da pasta do plugin
cd /home/glpi/glpi_dev/plugins/
zip -r mcprotocol-1.0.3.zip mcprotocol/ \
  -x "mcprotocol/.git*" \
  -x "*.zip" \
  -x "mcprotocol/node_modules/*" \
  -x "mcprotocol/vendor/*"

Não fazer cd plugin && zip -r ...zip . — esse padrão produz ZIP sem wrapper e era o bug histórico do script.

.gitignore padrão do plugin

Para que o ZIP não inclua arquivos sensíveis ou de teste, garantir .gitignore na raiz do plugin:

# Dependências
vendor/
node_modules/

# macOS
.DS_Store
**/.DS_Store

# IDE
.idea/
.vscode/

# Logs
*.log

# Build artifacts
*.zip

# Arquivos de teste (não publicar)
ajax/test*.php
ajax/mcp_test.php
front/test*.php

O script mindplace-release.sh excludes .git* por padrão; o .gitignore em si pode ser commitado e publicado sem problema.

Erros comuns

Sintoma	Causa	Fix
Após instalar via Mindplace, arquivos com nomes mutilados (`.php`, `p.php`, pastas `ic/`, `t/`)	ZIP gerado sem wrapper + Mindplace com detector buggy	Atualizar Mindplace ([KB-PLUGIN-017]) e regerar ZIP com wrapper
Após instalar, pasta `mcprotocol/mcprotocol/` aninhada	ZIP com wrapper mas extrator versão muito antiga, ou wrapper com nome diferente do `key`	Conferir que o basename do diretório bate com o `key` em plugins.json
Release não aparece no Mindplace	Release sem asset `.zip` no Forgejo	Verificar que a Fase 4 do script subiu o asset; tem rate limit ou erro?

Veja também

KB-PLUGIN-011 — Procedimento de release legado via GitHub (deprecated)
KB-PLUGIN-013 — Runbook completo de publicação no Mindplace via Forgejo
KB-PLUGIN-017 — Bug do detector de wrapper (motivação histórica)

4.5 KiB Raw Blame History