thierryc/glyphs3-to-glyphs4-skill

Migrieren eines Glyphs 3 Plug-ins zu Glyphs 4

Erstellen Sie eine überprüfbare migrierte Kopie eines Python-Plug-ins. Behandeln Sie die statische Migration als Vorbereitung für einen manuellen Starttest in Glyphs 4, nicht als Nachweis der Laufzeitkompatibilität.

Leitplanken

• Bewahren Sie das ursprüngliche Plug-in oder Repository.
• Niemals an Ort und Stelle migrieren. Lehnen Sie einen vorhandenen Ausgabepfad ab.
• Niemals Glyphs installieren, ausführen, neu laden, neu starten oder einen Live-Plugins-Ordner ändern, es sei denn, der Benutzer fordert dies separat an.
• Verwenden Sie die Glyphs MCP-Tools docs_search und docs_get als primäre Wissensdatenbank für die Entwicklung. Tool-Namensräume variieren je nach Client; lösen Sie sie anhand ihrer endgültigen Toolnamen und Beschreibungen auf.
• Holen Sie fokussierte offizielle Anleitungen ein, bevor Sie GlyphsApp-APIs, Plug-in-Lebenszyklusmethoden, Selektoren, Callbacks, Bundle-Metadaten oder die Formverarbeitung ändern.
• Rufen Sie docs_enable_page_resources für die normale Arbeit nicht auf. Rufen Sie Seiten bei Bedarf ab.
• Bevorzugen Sie den aktuellen Glyphs4-Zweig von schriftgestalt/GlyphsSDK; gehen Sie nicht davon aus, dass eine Glyphs 3 Vorlage oder ein zwischengespeicherter Loader aktuell ist.
• Halten Sie Verhaltensänderungen getrennt von mechanischen Migrationsänderungen.

Glyphs MCP Wissensdatenbank-Workflow

Lesen Sie references/glyphs-mcp-development-kb.md, bevor Sie API-spezifische Ergebnisse prüfen.

1. Stellen Sie sicher, dass docs_search und docs_get vom Glyphs MCP-Server verfügbar sind.
2. Erstellen Sie eine Dokumentationsbasislinie vor der Bearbeitung:
   • Suchen Sie nach plugins und rufen Sie das offizielle Plug-in-Handbuch ab.
   • Suchen Sie nach Info.plist und rufen Sie die Übersicht zur Python-Plug-in-Vorlage und die Plist-Vorlage ab.
   • Suchen Sie nach der exakten Basisklasse, z. B. GeneralPlugin, ReporterPlugin, FilterWithoutDialog, PalettePlugin, SelectTool oder FileFormatPlugin; rufen Sie deren Anleitung, Quellvorlage und den entsprechenden Plug-in-API-Abschnitt ab.
3. Suchen Sie jede unbekannte Klasse, Eigenschaft, Callback oder jeden Selektor einzeln. Bevorzugen Sie kurze exakte Symbole wie GSLayer, shapes oder addCallback.
4. Rufen Sie Ergebnisse anhand der zurückgegebenen doc_id oder path ab. Wenn truncated wahr ist, fahren Sie mit nextOffset fort, bis der relevante Abschnitt vollständig ist.
5. Notieren Sie den Titel, die docId, den sourceKind, die sourceUrl jeder abgerufenen Seite und die Migrationsentscheidung, die sie unterstützt. Fügen Sie diese Nachweise in die Übergabe ein.
6. Wenn die Tools nicht verfügbar sind, melden Sie, dass die Glyphs MCP-Dokumentationsprüfung blockiert ist. Eine statische Prüfung kann fortgesetzt werden, aber stellen Sie keine ungeprüften API- oder Lebenszyklusänderungen als migrationsbereit dar.

Arbeitsablauf

1. Ermitteln Sie das Quell-Plug-in oder Repository, das gewünschte Kompatibilitätsziel (Nur Glyphs 4 oder Glyphs 3 und 4) und einen neuen Ausgabepfad.

2. Stellen Sie eine Verbindung zur Glyphs MCP Entwicklungswissensdatenbank her und rufen Sie die Basislinienseiten für die erkannte Plug-in-Familie ab.

3. Besorgen oder lokalisieren Sie einen aktuellen Checkout des offiziellen Glyphs4-Zweigs von GlyphsSDK.

4. Prüfen Sie vor dem Kopieren:

   python3 scripts/migrate_plugin.py "/pfad/zum/quellplugin" \
     --sdk "/pfad/zu/GlyphsSDK"
   

5. Lesen Sie references/migration-review.md. Suchen Sie für jeden API-spezifischen Befund in der gebündelten Glyphs-Dokumentation nach dieser Klasse, Eigenschaft, Callback, Selektor oder Plug-in-Typ und rufen Sie nur die relevanten Seiten ab.

6. Erstellen Sie die migrierte Kopie und wenden Sie konservative Framework-Import-Korrekturen an:

   python3 scripts/migrate_plugin.py "/pfad/zum/quellplugin" \
     --output "/pfad/zur/neuen-glyphs4-kopie" \
     --sdk "/pfad/zu/GlyphsSDK" \
     --apply-safe-fixes
   

7. Verwenden Sie optionale Umschreibungen nur, nachdem Sie deren Auswirkungen geprüft haben:

   • Fügen Sie --rewrite-wildcard-imports hinzu, um einfache from GlyphsApp import *-Anweisungen durch Symbole aus dem Glyphs 4 .pyi Stub zu ersetzen.
   • Fügen Sie --replace-loader hinzu, um die SDK-Vorlage Contents/MacOS/plugin in jedes Bundle zu kopieren.
   • Fügen Sie --align-glyphs4-plist hinzu, um alte Update-Feed-Schlüssel zu entfernen, die in den aktuellen Glyphs 4 Vorlagen fehlen. Bestätigen Sie zuerst, dass das Plug-in nicht von einem eigenen Update-Feed abhängt.

8. Überprüfen Sie den generierten Migrationsbericht und das vollständige Source-Diff. Beheben Sie Lebenszyklus-, API-, Abhängigkeits-, UI- oder Mixed-Shape-Befunde manuell. Verknüpfen Sie jede API-spezifische Änderung mit einer abgerufenen KB-Seite.

9. Validieren Sie jedes Bundle:

   • Parsen Sie alle Python-Dateien mit der vorgesehenen Glyphs Python-Version.
   • Führen Sie plutil -lint auf jeder Contents/Info.plist aus.
   • Bestätigen Sie, dass NSPrincipalClass, PyMainFileNames und die Haupt-Python-Klasse übereinstimmen.
   • Vergleichen Sie die Bundle-Struktur mit der passenden aktuellen Glyphs 4 SDK-Vorlage.
   • Kompilieren Sie .xib-Dateien neu, wenn sich deren Oberfläche geändert hat.

10. Übergeben Sie einen manuellen Testplan. Testen Sie eine Einwegkopie in Glyphs 4, führen Sie jeden Menüeintrag und Callback aus, prüfen Sie die Macro Panel- und Konsolenausgabe und testen Sie die für das Plug-in relevanten Pfade für Rückgängig, Export, Zeichnung und Abhängigkeiten.

Kompatibilitätsentscheidung

• Für Nur Glyphs 4 erlauben Sie APIs und Python-Syntax, die von der Glyphs 4 Laufzeit unterstützt werden, nachdem Sie diese in den aktuellen Stubs bestätigt haben.
• Für Glyphs 3 und 4 behalten Sie nach Möglichkeit einen gemeinsamen Codepfad bei, schirmen echte API-Unterschiede mit Fähigkeitsprüfungen ab und testen beide Apps. Fügen Sie keine nur für Glyphs 4 gültige Syntax lediglich für Annotationen hinzu.
• Wenn das Plug-in layer.paths, layer.components oder layer.shapes rekonstruiert, prüfen Sie, ob es die gemischte Reihenfolge der Shapes oder neuere Shape-Arten bewahren muss. Nehmen Sie niemals an, dass eine reine Pfad-Umschreibung verlustfrei ist.

Liefergegenstände

Geben Sie die neue Kopie, den Migrationsbericht, das Kompatibilitätsziel, die statischen Validierungsergebnisse und die verbleibenden manuellen Glyphs 4 Tests zurück. Fügen Sie eine Dokumentationsnachweistabelle mit dem Titel jeder Seite, der Glyphs MCP docId, der offiziellen sourceUrl und der getroffenen Entscheidung bei. Geben Sie klar an, dass keine Live-Installation oder kein Laufzeittest stattgefunden hat, es sei denn, dies ist tatsächlich geschehen.

Ressourcen

• scripts/migrate_plugin.py: Hilfsprogramm für Audit und zerstörungsfreies Kopieren.
• references/migration-review.md: Evidenzbasierte Prüfliste und Eskalationspunkte.
• references/glyphs-mcp-development-kb.md: Exaktes MCP-Nachschlageschema, Paging, Nachweise und Wiederherstellungsprotokoll.
• .mcp.json: Claude Code Plug-in-Verbindung zum lokalen Glyphs MCP-Server.
• mcp.json: Cursor Plug-in-Verbindung zum lokalen Glyphs MCP-Server.
• .claude-plugin/plugin.json: Claude Code Community/Plugin-Metadaten; laden Sie diesen Ordner mit claude --plugin-dir.
• .cursor-plugin/plugin.json: Cursor Plugin-Metadaten, die das Wurzelverzeichnis SKILL.md und mcp.json registrieren.
• agents/openai.yaml: Codex-Anzeigemetadaten und Glyphs MCP-Abhängigkeit.