docmd v0.8.1 führt eine steckbare Engine-Architektur, wesentliche Verbesserungen bei der Performance der Git-Indizierung und wichtige Fixes für das SPA-Routing ein.

✨ Highlights

Steckbare Engine-Architektur (Vorschau)

docmd unterstützt jetzt ein steckbares Engine-System. Das neue Paket @docmd/engine-rust bietet die Grundlage für beschleunigte I/O-Operationen und ist so konzipiert, dass es reibungslos mit vorhandenen Plugins zusammenarbeitet.

{
  "engine": "rust"
}

Die Engine ist optional – die standardmäßige JavaScript-Engine verarbeitet weiterhin alle Workloads. Die Rust-Engine bietet spürbare Vorteile bei großen Repositories (mehr als 1.000 Dateien), bei denen die Git-Indizierung und Batch-Dateioperationen die Build-Zeit dominieren.

Architektur-Highlights:

• Steckbares Design: Engines sind Pakete unter @docmd/engine-* und folgen demselben Muster wie Plugins.
• Integrierte vorkompilierte Binärdateien: Alle unterstützten Plattform-Binärdateien werden nun über ein einziges, zentralisiertes Paket @docmd/engine-rust-binaries bereitgestellt.
• Lazy Loading: Native Binärdateien werden erst geladen, wenn die Engine explizit ausgewählt wird.
• Plugin-kompatibel: Plugins können die Engine-API für beschleunigte I/O-Operationen nutzen.
• Automatischer Fallback: Wenn die native Binärdatei nicht verfügbar ist, übernimmt die JS-Engine transparent.

Verfügbare Engine-Pakete:

Git-Indizierung: Persistenter Festplatten-Cache

Das Git-Plugin speichert Indizierungsergebnisse nun über Builds hinweg auf der Festplatte. Zuvor wurden Git-Metadaten bei jedem Build von Grund auf neu indiziert – selbst wenn sich keine Dateien geändert hatten. Das neue Cache-System:

• Leitet die Cache-Speicherung sauber in das isolierte temporäre Verzeichnis Ihres Betriebssystems (os.tmpdir()) um, um eine Überfrachtung des Projektverzeichnisses zu verhindern.
• Sichert den Cache-Abruf über Verzeichnisumbenennungen oder -verschiebungen hinweg, indem ein zuverlässiger Hash generiert wird, der an die Git-Tracking-URL Ihres Repositories oder eindeutige OS-Inode-Identifikatoren gebunden ist.
• Unterstützt konfigurierbare Speicherpfade über den neuen Konfigurationsparameter tmp.
• Funktioniert mit beiden Engine-Pfaden (Rust und JS) und dem execFile-Fallback.
• Bietet ca. 45 % schnellere Warmstarts auf der offiziellen Dokumentations-Website (886 Seiten).

Konfigurierbares tmp-Verzeichnis

Standardmäßig leitet docmd den internen Zustand und Build-Caches in den isolierten temporären Ordner Ihres Systems um, um Ihr Projektverzeichnis sauber zu halten. Für Umgebungen, die ein persistentes Caching an bestimmten Orten erfordern (z. B. CI/CD-Pipelines mit Cache-Key-Anforderungen), können Sie den Pfad nun mit dem Schlüssel tmp konfigurieren:

{
  "src": ".",
  "out": "site",
  "tmp": ".docmd-cache"
}

Dadurch können Sie den .docmd/-Zustandsordner in jedem beliebigen Verzeichnis verankern, sodass er über Build-Sitzungen hinweg problemlos gecached und wiederhergestellt werden kann.

JSON-Konfigurationsstandard

Beginnend mit v0.8.0 ist docmd.config.json das empfohlene Konfigurationsformat. Alle Dokumentationen der v0.8 wurden auf JSON-Beispiele aktualisiert. Die Formate .js und .ts werden weiterhin als Fallbacks für dynamische Konfigurationslogiken vollständig unterstützt.

🐛 Fehlerbehebungen

Externe Links in der SPA-Navigation

Es wurde ein Problem behoben, bei dem externe Links in der navigation.json mit external: true fälschlicherweise als relative Pfade aufgelöst wurden, nachdem über den SPA-Router auf eine andere interne Seite navigiert wurde. Die Links behalten nun ihre absoluten URLs bei.

Kurzschreibweise für externe Navigationslinks

Das Präfix external:, das zuvor nur in Markdown-Inhalten verfügbar war, funktioniert nun auch in der navigation.json als praktische Kurzschreibweise:

[
  { "title": "GitHub", "path": "external:https://github.com/docmd-io/docmd" }
]

Dies entspricht:

[
  { "title": "GitHub", "path": "https://github.com/docmd-io/docmd", "external": true }
]

Git-Cache-Verzeichnis-Stabilität & -Verlagerung

Es wurde ein Fehler behoben, bei dem der Cache des Git-Plugins während Workspace-Builds in wechselnde Verzeichnisse geschrieben wurde. Der Cache wurde sauber aus dem Projektverzeichnis direkt in os.tmpdir() verlagert. Er verwendet nun einen persistenten Repository-Identifikator und unterstützt den benutzerdefinierten Parameter tmp.

Engine-Konfiguration wird beachtet

Das Git-Plugin beachtet nun den Konfigurationsschlüssel engine. Zuvor wurde unabhängig von der Konfiguration immer versucht, zuerst die Rust-Engine zu laden. Das Setzen von "engine": "js" erzwingt nun korrekt die JavaScript-Engine.

📝 Vollständiger Changelog

🚀 Engine & Architektur

• Steckbares Engine-System: Neues Engine-Interface in @docmd/api zur Build-Beschleunigung.
• JS-Engine-Paket: Standard-Engine ausgelagert in das Paket @docmd/engine-js.
• Rust-Engine-Ecosystem: Native Rust-Beschleunigung mit zentraler Binärverteilung über @docmd/engine-rust-binaries.
• Engine-Loader-API: loadEngine() und registerEngine() für die Registrierung benutzerdefinierter Engines.
• Engine-Konfigurationsschlüssel: Neuer Schlüssel engine in der docmd.config.json zur Auswahl der Build-Engine.
• Engine-Hervorhebung: Erhöhte Protokollierungshervorhebung für benutzerdefinierte Build-Engines in TUI-Layouts.

⚡ Performance

• Git-Festplatten-Cache: Ergebnisse werden für Warmstarts auf der Festplatte gespeichert.
• Persistente Identifikation: Dual-Mode-Cache-Identifikation über Git-Remote-URL-Hashing und OS-Inode-Fallback.
• Konfigurierbarer Speicher: Unterstützung für das Überschreiben des Cache-Ziels über den Parameter tmp.
• Konfigurations-Resolver: Automatische Erkennungsunterstützung für Standard-JSON-Konfigurationsdateien in Workspace-Subprojekten.
• Festplatten-Cache-Vorwärmung: Build-Pipeline liest den Festplatten-Cache vor Engine- oder Subprozessaufrufen.

🐛 Fehlerbehebungen

• SPA-Router: Externe Links in der Seitenleiste bleiben bei clientseitiger Navigation korrekt erhalten.
• Navigationskonfiguration: Das Präfix external: wird nun als Kurzschreibweise in der navigation.json unterstützt.
• Linkauflösung: URL-Auflösungsfehler für protokollrelative URLs behoben.
• Git-Plugin: Beachtet nun den Konfigurationsschlüssel engine statt standardmäßig immer Rust zu laden.
• Workspace-Cache: Zustandsordner in deterministische temporäre OS-Strukturen verlagert, um Verluste zu vermeiden.