---
id: KB-PLUGIN-018
title: "Convenção de wrapper directory na geração de ZIP de release de plugin (script mindplace-release.sh)"
domain: plugin-dev
tags:
  - mindplace
  - forgejo
  - release
  - zip
  - wrapper
  - mindplace-release-sh
status: active
severity: high
created_at: 2026-05-21
updated_at: 2026-05-21
applies_to:
  - Qualquer plugin publicado via bin/mindplace-release.sh
  - Plugins distribuídos pelo catálogo Mindplace
related:
  - KB-PLUGIN-013
  - KB-PLUGIN-017
---

# 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](KB-PLUGIN-017-mindplace-zip-wrapper-detector-bug.md).

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:

```bash
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](KB-PLUGIN-013-mindplace-plugin-publication-runbook.md). Desde 2026-05-21, a Fase 3 do script gera ZIPs com wrapper directory automaticamente — rodando `zip` do **diretório pai** do plugin:

```bash
# 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:

```bash
# A partir do diretório PAI da pasta do plugin
cd docker/glpi/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:

```gitignore
# 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](KB-PLUGIN-011-mindplace-release-zip-procedure.md) — Procedimento de release **legado** via GitHub (deprecated)
- [KB-PLUGIN-013](KB-PLUGIN-013-mindplace-plugin-publication-runbook.md) — Runbook completo de publicação no Mindplace via Forgejo
- [KB-PLUGIN-017](KB-PLUGIN-017-mindplace-zip-wrapper-detector-bug.md) — Bug do detector de wrapper (motivação histórica)