thierryc/glyphs3-to-glyphs4-skill

Migrar um plug-in do Glyphs 3 para o Glyphs 4

Crie uma cópia migrada e revisável de um plug-in Python. Trate a migração estática como preparação para um teste manual de inicialização no Glyphs 4, não como prova de compatibilidade em tempo de execução.

Diretrizes

• Preserve o plug-in ou repositório original.
• Nunca migre no local. Recuse um caminho de saída já existente.
• Nunca instale, execute, recarregue, reinicie o Glyphs ou altere uma pasta Plugins ativa, a menos que o usuário solicite explicitamente.
• Use as ferramentas docs_search e docs_get do Glyphs MCP como base de conhecimento principal para o desenvolvimento. Os namespaces das ferramentas variam conforme o cliente; resolva-os pelos nomes e descrições finais das ferramentas.
• Consulte orientações oficiais específicas antes de alterar APIs do GlyphsApp, métodos do ciclo de vida do plug-in, seletores, callbacks, metadados do bundle ou manipulação de formas.
• Não chame docs_enable_page_resources para trabalho normal. Recupere páginas sob demanda.
• Prefira o branch atual Glyphs4 de schriftgestalt/GlyphsSDK; não assuma que um template do Glyphs 3 ou um carregador em cache esteja atualizado.
• Mantenha alterações comportamentais separadas das alterações mecânicas de migração.

Fluxo de trabalho da base de conhecimento do Glyphs MCP

Leia references/glyphs-mcp-development-kb.md antes de revisar descobertas específicas de API.

1. Confirme que docs_search e docs_get estão disponíveis no servidor MCP do Glyphs.
2. Estabeleça uma linha de base de documentação antes de editar:
   • Pesquise plugins e obtenha o resultado do manual oficial de plug-ins.
   • Pesquise Info.plist e obtenha a visão geral do template de plug-in Python e o template plist.
   • Pesquise a classe base exata, como GeneralPlugin, ReporterPlugin, FilterWithoutDialog, PalettePlugin, SelectTool ou FileFormatPlugin; obtenha seu guia, template fonte e a seção relevante da API de plug-ins.
3. Pesquise cada classe, propriedade, callback ou seletor desconhecido separadamente. Prefira símbolos exatos curtos como GSLayer, shapes ou addCallback.
4. Obtenha resultados pelo doc_id ou path retornado. Se truncated for verdadeiro, continue a partir de nextOffset até que a seção relevante esteja completa.
5. Registre o título de cada página obtida, docId, sourceKind, sourceUrl e a decisão de migração que ela suporta. Inclua essa evidência no handoff.
6. Se as ferramentas não estiverem disponíveis, reporte que a revisão da documentação do Glyphs MCP está bloqueada. Uma auditoria estática pode continuar, mas não apresente alterações de API ou ciclo de vida não verificadas como prontas para migração.

Fluxo de trabalho

1. Identifique o plug-in ou repositório fonte, o alvo de compatibilidade pretendido (Apenas Glyphs 4 ou Glyphs 3 e 4) e um novo caminho de saída.

2. Conecte-se à base de conhecimento de desenvolvimento do Glyphs MCP e obtenha as páginas base para a família de plug-ins detectada.

3. Obtenha ou localize um checkout atual do branch oficial Glyphs4 do GlyphsSDK.

4. Audite antes de copiar:

   python3 scripts/migrate_plugin.py "/caminho/para/fonte" \
     --sdk "/caminho/para/GlyphsSDK"
   

5. Leia references/migration-review.md. Para cada descoberta específica de API, pesquise na documentação incluída do Glyphs por aquela classe, propriedade, callback, seletor ou tipo de plug-in e obtenha apenas as páginas relevantes.

6. Crie a cópia migrada e aplique correções conservadoras de importação de framework:

   python3 scripts/migrate_plugin.py "/caminho/para/fonte" \
     --output "/caminho/para/nova-copia-glyphs4" \
     --sdk "/caminho/para/GlyphsSDK" \
     --apply-safe-fixes
   

7. Use reescritas opcionais apenas após revisar seu impacto:

   • Adicione --rewrite-wildcard-imports para substituir declarações simples from GlyphsApp import * usando símbolos encontrados no stub .pyi do Glyphs 4.
   • Adicione --replace-loader para copiar o template do SDK Contents/MacOS/plugin para cada bundle.
   • Adicione --align-glyphs4-plist para remover chaves legadas de feed de atualização ausentes nos templates atuais do Glyphs 4. Confirme primeiro que o plug-in não depende de seu próprio feed de atualização.

8. Revise o relatório de migração gerado e o diff completo do fonte. Corrija manualmente descobertas relacionadas a ciclo de vida, API, dependências, UI ou formas mistas. Vincule cada alteração específica de API a uma página da base de conhecimento obtida.

9. Valide cada bundle:

   • Analise todos os arquivos Python com a versão do Python pretendida para o Glyphs.
   • Execute plutil -lint em cada Contents/Info.plist.
   • Confirme que NSPrincipalClass, PyMainFileNames e a classe Python principal estão consistentes.
   • Compare a estrutura do bundle com o template do SDK do Glyphs 4 atual correspondente.
   • Recompile arquivos .xib quando sua interface tiver mudado.

10. Entregue um plano de teste manual. Teste uma cópia descartável no Glyphs 4, exercite cada entrada de menu e callback, inspecione a saída do Macro Panel e do Console, e teste caminhos de desfazer, exportação, desenho e dependências relevantes para o plug-in.

Decisão de compatibilidade

• Para Apenas Glyphs 4, permita APIs e sintaxe Python suportadas pelo runtime do Glyphs 4 após confirmá-las nos stubs atuais.
• Para Glyphs 3 e 4, mantenha um caminho de código compartilhado quando prático, isole diferenças reais de API com verificações de capacidade e teste ambos os aplicativos. Não adicione sintaxe exclusiva do Glyphs 4 meramente para anotações.
• Se o plug-in reconstrói layer.paths, layer.components ou layer.shapes, inspecione se ele deve preservar a ordem de formas mistas ou tipos de forma mais recentes. Nunca presuma que uma reescrita apenas de paths é livre de perdas.

Entregas

Retorne a nova cópia, o relatório de migração, o alvo de compatibilidade, os resultados de validação estática e os testes manuais restantes para o Glyphs 4. Inclua uma tabela de evidências de documentação com o título de cada página, docId do Glyphs MCP, sourceUrl oficial e a decisão que ela suporta. Indique claramente que nenhuma instalação ou teste em tempo de execução ocorreu, a menos que realmente tenha ocorrido.

Recursos

• scripts/migrate_plugin.py: auditoria e auxiliar de cópia não destrutiva.
• references/migration-review.md: lista de verificação de revisão baseada em evidências e pontos de escalonamento.
• references/glyphs-mcp-development-kb.md: protocolo exato de consulta MCP, paginação, evidências e recuperação.
• .mcp.json: conexão do plug-in Claude Code com o servidor MCP do Glyphs local.
• mcp.json: conexão do plug-in Cursor com o servidor MCP do Glyphs local.
• .claude-plugin/plugin.json: metadados de comunidade/plug-in do Claude Code; carregue esta pasta com claude --plugin-dir.
• .cursor-plugin/plugin.json: metadados do plug-in Cursor que registra o SKILL.md raiz e mcp.json.
• agents/openai.yaml: metadados de exibição do Codex e dependência do Glyphs MCP.