thierryc/glyphs3-to-glyphs4-skill

Migrar un plug-in de Glyphs 3 a Glyphs 4

Crea una copia migrada y revisable de un plug-in de Python. Trata la migración estática como preparación para una prueba de lanzamiento manual en Glyphs 4, no como prueba de compatibilidad en tiempo de ejecución.

Barreras de protección

• Conserva el plug-in o repositorio original.
• Nunca migres en el lugar. Rechaza una ruta de salida existente.
• Nunca instales, ejecutes, recargues, reinicies Glyphs ni cambies una carpeta Plugins activa a menos que el usuario lo solicite por separado.
• Utiliza las herramientas docs_search y docs_get de Glyphs MCP como base de conocimiento de desarrollo principal. Los espacios de nombres de las herramientas varían según el cliente; resuélvelos por sus nombres finales y descripciones.
• Obtén orientación oficial específica antes de cambiar APIs de GlyphsApp, métodos del ciclo de vida del plug-in, selectores, callbacks, metadatos del bundle o manejo de formas.
• No llames a docs_enable_page_resources para trabajo normal. Recupera páginas según sea necesario.
• Prefiere la rama actual Glyphs4 de schriftgestalt/GlyphsSDK; no asumas que una plantilla de Glyphs 3 o un cargador en caché estén actualizados.
• Mantén los cambios de comportamiento separados de los cambios mecánicos de migración.

Flujo de trabajo de la base de conocimiento de Glyphs MCP

Lee references/glyphs-mcp-development-kb.md antes de revisar hallazgos específicos de la API.

1. Confirma que docs_search y docs_get estén disponibles desde el servidor Glyphs MCP.
2. Establece una línea base de documentación antes de editar:
   • Busca plugins y obtén el resultado del manual oficial de plug-ins.
   • Busca Info.plist y obtén la visión general de la plantilla de plug-in Python y la plantilla plist.
   • Busca la clase base exacta, como GeneralPlugin, ReporterPlugin, FilterWithoutDialog, PalettePlugin, SelectTool o FileFormatPlugin; obtén su guía, plantilla de fuente y la sección de API del plug-in relevante.
3. Busca cada clase, propiedad, callback o selector desconocido por separado. Prefiere símbolos exactos cortos como GSLayer, shapes o addCallback.
4. Obtén resultados según el doc_id o path devuelto. Si truncated es verdadero, continúa desde nextOffset hasta que la sección relevante esté completa.
5. Registra el título, docId, sourceKind, sourceUrl de cada página obtenida y la decisión de migración que respalda. Incluye esta evidencia en la entrega.
6. Si las herramientas no están disponibles, informa que la revisión de la documentación de Glyphs MCP está bloqueada. Puede continuar una auditoría estática, pero no presentes cambios de API o ciclo de vida no verificados como listos para migración.

Flujo de trabajo

1. Resuelve el plugín o repositorio fuente, el objetivo de compatibilidad previsto (Glyphs 4 only o Glyphs 3 and 4) y una nueva ruta de salida.

2. Conéctate a la base de conocimiento de desarrollo de Glyphs MCP y obtén las páginas base para la familia de plug-ins detectada.

3. Obtén o localiza un checkout actual de la rama oficial Glyphs4 de GlyphsSDK.

4. Audita antes de copiar:

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --sdk "/path/to/GlyphsSDK"
   

5. Lee references/migration-review.md. Para cada hallazgo específico de la API, busca en la documentación incluida de Glyphs esa clase, propiedad, callback, selector o tipo de plug-in y obtén solo las páginas relevantes.

6. Crea la copia migrada y aplica correcciones conservadoras de importación del framework:

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --output "/path/to/new-glyphs4-copy" \
     --sdk "/path/to/GlyphsSDK" \
     --apply-safe-fixes
   

7. Usa reescrituras opcionales solo después de revisar su impacto:

   • Agrega --rewrite-wildcard-imports para reemplazar sentencias simples from GlyphsApp import * usando símbolos encontrados en el stub .pyi de Glyphs 4.
   • Agrega --replace-loader para copiar la plantilla Contents/MacOS/plugin del SDK en cada bundle.
   • Agrega --align-glyphs4-plist para eliminar claves heredadas de update-feed ausentes en las plantillas actuales de Glyphs 4. Confirma primero que el plug-in no depende de su propio update-feed.

8. Revisa el informe de migración generado y el diff completo de la fuente. Corrige manualmente hallazgos de ciclo de vida, API, dependencias, UI o formas mixtas. Vincula cada cambio específico de la API a una página obtenida de la KB.

9. Valida cada bundle:

   • Analiza todos los archivos Python con la versión de Python prevista de Glyphs.
   • Ejecuta plutil -lint en cada Contents/Info.plist.
   • Confirma que NSPrincipalClass, PyMainFileNames y la clase Python principal coincidan.
   • Compara la estructura del bundle con la plantilla actual del SDK de Glyphs 4 correspondiente.
   • Recompila los archivos .xib cuando su interfaz haya cambiado.

10. Entrega un plan de pruebas manuales. Prueba una copia desechable en Glyphs 4, ejercita cada entrada de menú y callback, inspecciona el Panel de macros y la salida de la Consola, y prueba las rutas de deshacer, exportación, dibujo y dependencias relevantes para el plug-in.

Decisión de compatibilidad

• Para Glyphs 4 only, permite APIs y sintaxis de Python compatibles con el tiempo de ejecución de Glyphs 4 después de confirmarlas en los stubs actuales.
• Para Glyphs 3 and 4, mantén una ruta de código compartida cuando sea práctico, protege las diferencias reales de la API con comprobaciones de capacidad y prueba ambas aplicaciones. No agregues sintaxis exclusiva de Glyphs 4 meramente para anotaciones.
• Si el plug-in reconstruye layer.paths, layer.components o layer.shapes, inspecciona si debe preservar el orden de formas mixtas o tipos de formas más nuevos. Nunca infieras que una reescritura solo de paths es sin pérdidas.

Entregables

Devuelve la nueva copia, el informe de migración, el objetivo de compatibilidad, los resultados de validación estática y las pruebas manuales restantes de Glyphs 4. Incluye una tabla de evidencia de documentación con el título de cada página, el docId de Glyphs MCP, la sourceUrl oficial y la decisión que respalda. Declara claramente que no se realizó ninguna instalación en vivo ni prueba de tiempo de ejecución a menos que realmente se haya hecho.

Recursos

• scripts/migrate_plugin.py: ayuda para auditoría y copia no destructiva.
• references/migration-review.md: lista de verificación de revisión basada en evidencia y puntos de escalamiento.
• references/glyphs-mcp-development-kb.md: protocolo exacto de búsqueda MCP, paginación, evidencia y recuperación.
• .mcp.json: conexión de plug-in de Claude Code al servidor local de Glyphs MCP.
• mcp.json: conexión de plug-in de Cursor al servidor local de Glyphs MCP.
• .claude-plugin/plugin.json: metadatos de comunidad/plug-in de Claude Code; carga esta carpeta con claude --plugin-dir.
• .cursor-plugin/plugin.json: metadatos de plug-in de Cursor que registran la raíz SKILL.md y mcp.json.
• agents/openai.yaml: metadatos de visualización de Codex y dependencia de Glyphs MCP.