v0.9.7 - Python-Engine, Gitignore-Anker-Fix, Engine-Lebenszyklus & Sicherheitshärtung

Highlights

docmd v0.9.7 führt die Python-Engine ein, behebt eine kritische Gitignore-Regression aus v0.9.6, vereinheitlicht das Lebenszyklusmanagement von Engine-Prozessen und enthält Sicherheitsverbesserungen im CLI und Dev-Server.

  • Python-Engine (@docmd/engine-python): Ein brandneuer Engine-Adapter auf Basis von Python 3 (>= 3.8) zur Beschleunigung von Dateierkennung, Git-Verlauf-Parsing und Such-Indexierung über einen hochperformanten Stdio-Worker-Pool.
  • Einheitlicher Engine-Lebenszyklus (@docmd/api, @docmd/core): Standardisierte shutdown()- und destroy()-Methoden über alle Engines hinweg (js, rust, python) mit automatischem Idle-Worker-Management und sauberem Prozessende.
  • docmd-search 0.1.6 Integration: Such-Integration und Peer-Dependencies aktualisiert auf docmd-search >=0.1.6 mit nativer Python-Engine-Unterstützung.
  • Gitignore-Anker-Muster-Fix (#244): Verankerte Muster (z. B. /airo) werden jetzt relativ zum Projektstamm abgeglichen, nicht gegen den absoluten Dateisystempfad. Zuvor wurden alle Seiten still ausgeschlossen und Builds meldeten Generated 0 pages, wenn das Muster zufällig dem Namen eines übergeordneten Ordners entsprach.
  • MCP config.exclude-Erzwingung (#245): search_docs, list_docs und validate_docs respektieren jetzt config.exclude. Zuvor wurden ausgeschlossene Dateien (wie Entwürfe oder archivierte Seiten) KI-Agenten über MCP-Tools offengelegt.
  • Absicherung gegen Shell-Injection: execSync mit Shell-Interpolation wurde durch spawnSync mit expliziten Argument-Arrays im doctor-Befehl und bei der Such-Indexierung ersetzt.
  • Dev-Server XSS & Pfad-Traversal-Härtung: URL-Reflexionen in 404/500-Fehlerseiten werden jetzt HTML-escaped; Weiterleitungsziele werden strikt validiert.
  • Asset-Pfad-Kanonisierung: Die Asset-Auflösung des Live-Servers erzwingt jetzt eine sichere Pfadgrenze.

Python-Engine (@docmd/engine-python)

v0.9.7 erweitert die Multi-Engine-Architektur von docmd neben JavaScript und Rust um Python:

  • Auto-Erkennung & Zero-Config: Ist Python 3 im Systempfad vorhanden, aktiviert "engine": "python" in docmd.config.json automatisch die Python-Engine. Andernfalls greift docmd nahtlos auf die JS-Engine zurück.
  • Persistenter Worker-Pool: Verwendet einen optimierten Stdio-JSON-RPC-Worker mit Idle-Cleanup, wodurch der Subprozess-Startaufwand entfällt.
  • Plugin-Integration: Unterstützt direkt Git-Log-Extraktion, Suchindexierung und Batch-Dateiscans.

Engine-Lebenszyklus & Ressourcen-Bereinigung (@docmd/api, @docmd/core)

  • Standardisiertes Herunterfahren: shutdown()- und destroy()-Hooks im Engine-Interface über alle Engine-Pakete (@docmd/engine-js, @docmd/engine-rust, @docmd/engine-python).
  • Ressourcenfreigabe: Build- und Dev-Pipelines rufen bei Abschluss shutdownEngines() auf, um Pipes, Arbeitsspeicher und native Bindings sauber freizugeben.
  • Idle-Worker: Der Python-Worker beendet sich bei Inaktivität automatisch, um verwaiste Hintergrundprozesse zu verhindern.

Gitignore-Anker-Regression (@docmd/core)

Behobener Fehler (#244): Seit v0.9.6 die .gitignore-Unterstützung für die Seitenerkennung einführte, wurden verankerte Muster mit führendem / von diesem Schrägstrich befreit und gegen den vollständigen absoluten Pfad jeder Datei geprüft. /airo (gedacht zum Ignorieren einer Binärdatei im Repo-Stamm) würde so auch jede Datei unter /Users/jemand/github/airo/docs/ ausschließen.

Ursache: isExcludedPath entfernte das führende / und führte normalizedPath.includes('/airo/') gegen den vollständigen absoluten Pfad aus.

Fix: Verankerte Muster werden jetzt nur gegen den Pfad relativ zum obersten Quellverzeichnis geprüft. Nicht verankerte Muster (kein führendes /) behalten ihr bisheriges Matching-Verhalten bei.

Sicherheitshärtung (@docmd/core, @docmd/plugins-search, @docmd/live)

  • doctor-Befehl: execSync durch spawnSync(['npm', 'doctor']) mit shell: false ersetzt.
  • Such-Indexierungs-Subprocess: Analog abgesichert.
  • Dev-Server (docmd dev): req.url in 404- und 500-Fehlern wird jetzt HTML-escaped. Weiterleitungsziele werden gegen eine Whitelist geprüft.
  • Live-Server-Asset-Auflösung: Alle Asset-Pfade werden durch canonicalSafePath aufgelöst.

MCP config.exclude-Erzwingung (@docmd/core)

Behobener Fehler (#245): search_docs, list_docs und validate_docs im MCP-Server ignorierten config.exclude. Die interne Funktion findMarkdownFiles() übersprang lediglich node_modules und Punkt-Verzeichnisse – sie berücksichtigte die in v0.9.6 eingeführten Ausschlussmuster nicht. Dadurch konnten KI-Agenten Dokumentationen finden und lesen, die absichtlich von der veröffentlichten Website ausgeschlossen waren (z. B. archivierte Spezifikationen, interne Entwürfe).

Fix: search_docs und list_docs nutzen jetzt findFilesRecursive() (denselben Datei-Walker wie die Build-Pipeline), welcher config.exclude, .gitignore und alle Standard-Überspringungsregeln anwendet. validate_docs leitet config.exclude an den Datei-Walker der Link-Validierung weiter. Build-Ausgabe und MCP-Tool-Ergebnisse stimmen nun darin überein, was als veröffentlichte Dokumentation gilt.

Ausblick auf 0.9.8

  • Integritätsprüfung nach Pre-Flight-Batch-Installationen zur Erkennung halb-extrahierter Pakete.
  • Weitere Verbesserungen der Gitignore-Engine (Negationsmuster !, subdirektorie-spezifische .gitignore-Dateien).
Nächste Übersicht