141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
---
|
|
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)
|