diff --git a/README.md b/README.md index 33d7296..0b20ad7 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,100 @@ # Kosmos Storage Audit -Dieses Verzeichnis enthaelt einen ersten Modul-Prototypen fuer die Analyse von Medienreferenzen und riskanten Ablageorten in FoundryVTT. +`Kosmos Storage Audit` hilft Spielleitern dabei, fehlende, veraltete und moeglicherweise verwaiste Mediendateien in einer FoundryVTT-Installation zu finden. -## Foundry Manifest +Das Modul ist als Pruefwerkzeug gedacht. Es aendert keine Weltdaten und verschiebt oder loescht keine Dateien. -- Manifest-URL: - - `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/raw/branch/main/module.json` -- Download-URL: - - `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/archive/main.zip` +## Installation -## Ausrichtung +Manifest-URL: -- Das Zielprodukt ist ein online nutzbares Foundry-Modul. -- Die Kernlogik unter `scripts/core/` ist bewusst runtime-neutral gehalten. -- `scripts/adapters/foundry-runtime.js` bindet die Kernlogik an die laufende Foundry-Instanz. -- `tools/offline-analyze.mjs` ist nur ein Entwicklungs-Harness, um Parser und Matching lokal gegen eine gestoppte Instanz zu pruefen. +```text +https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/raw/branch/main/module.json +``` -## Erste Kernbausteine +Alternativ: -- `path-utils.js` - - Normalisierung auf `data:` und `public:` inklusive URL-Decoding und Unicode-Normalisierung -- `reference-extractor.js` - - rekursive String- und Attribut-Extraktion aus JSON/Objekten inklusive Wildcard-Erkennung -- `finding-engine.js` - - Klassifizierung von Broken References, Orphans und Fremdverweisen mit Wildcard-Matching -- `analyzer.js` - - Orchestrierung von Dateien, Quellen und Findings -- `audit-report-app.js` - - Foundry-UI mit Fortschrittsanzeige, gruppierter Arbeitsansicht, JSON-Export und lokalisierter Oberfläche +- Projektseite: `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit` +- ZIP-Download: `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/archive/main.zip` -## Wichtige Heuristik +## Was das Modul prueft -- Bei mehreren Welten versucht das Tool nicht, globale "echte Orphans" im gesamten `data`-Root zu behaupten. -- Orphans werden nur in klar eingrenzbaren Bereichen gemeldet: - - weltlokale Bereiche - - explizit riskante Paket-`storage`-Ordner - - nicht offensichtliche `public`-Bereiche -- Weltverweise auf Modul- oder Systemassets gelten nicht pauschal als Problem. -- Sie werden erst dann hochgezogen, wenn das Zielasset im owning Paket selbst nicht sichtbar referenziert ist. -- Wildcard-Pfade wie `Ork*_Token.webp` werden nicht als kaputt markiert, solange mindestens eine passende Datei im gescannten Root existiert. -- Dieselben Wildcard-Referenzen zaehlen auch als eingehende Referenz fuer passende Dateien und verhindern damit false-positive `orphan-file`-Treffer. -- URL-encodierte oder unterschiedlich normalisierte Umlaute sollen auf dieselbe kanonische Pfadform zusammengefuehrt werden. -- Die UI unterstuetzt konsistent Deutsch und Englisch ueber Foundry-Sprachdateien. +Der Report zeigt drei Arten von Problemen: -## Noch offen +- `Fehlt` + Dateien werden noch von Objekten in der Welt verwendet, sind aber im geprueften Bestand nicht vorhanden. +- `Veraltet` + Die Welt verweist auf Dateien in Modul- oder Systemordnern, die dort nicht mehr wie regulaerer Paketinhalt aussehen. +- `Verwaist` + Dateien liegen noch im Storage, fuer die im aktuell geprueften Datenbestand keine Verwendung mehr gefunden wurde. -- bessere Laufzeitabdeckung fuer Welteinstellungen und weitere Referenzquellen -- optional zusaetzliche Exportformate neben JSON -- Aktionen zum sicheren Verschieben oder Migrieren +## Wobei das hilft + +Typische Faelle sind: + +- kaputte Bilder, Videos oder Sounds +- Uploads eines Spielleiters in ungeeignete Modulordner +- Dateien aus alten Modulversionen, die noch in Weltdaten referenziert werden +- Altlasten, die sich ueber Jahre in `data` oder `public` ansammeln + +## Was der Report nicht macht + +- keine Dateien loeschen +- keine Referenzen automatisch reparieren +- keine Weltdaten migrieren +- keine Dateien verschieben oder kopieren + +Das Modul zeigt nur, was geprueft werden sollte. + +## Hinweise zur Auswertung + +`Fehlt` + +- Diese Treffer sollte man in der Regel zuerst anschauen. +- Meist wurde eine Datei geloescht, verschoben oder durch ein Update ersetzt. + +`Veraltet` + +- Diese Treffer deuten oft auf alte Moduldateien oder unguenstige Upload-Orte hin. +- In manchen Faellen kann eine neue Initialisierung oder ein erneuter Import des betroffenen Moduls helfen. + +`Verwaist` + +- Diese Treffer sind bewusst vorsichtiger zu lesen. +- Das Modul kann derzeit technisch nicht pruefen, ob eine Datei eventuell noch im Kontext einer anderen Welt verwendet wird. + +## Hinweise im Report + +Im Abschnitt `Hinweise` tauchen Faelle auf, die absichtlich nicht als Findings gezaehlt werden, zum Beispiel: + +- Verweise auf Dateien aus inaktiven Modulen +- Verweise auf Modulordner, die von Foundry derzeit nicht mehr als installierte Module erkannt werden + +Diese Hinweise sollen beim Einordnen helfen, ohne die eigentliche Ergebnisliste mit moeglichen False Positives aufzublaehen. + +## Filter fuer Verwaist + +Bei `Verwaist` kann man bestimmte Pfadgruppen direkt ausblenden, zum Beispiel: + +- `modules/*` +- `systems/*` +- `canvas/cards/docs/icons/nue/sounds/toolclips/ui` + +Das ist hilfreich, wenn man sich zuerst auf spielleiternahe Upload-Bereiche konzentrieren moechte. + +## Sicherheit + +Der aktuelle Stand des Moduls ist reine Analyse. + +Es werden: + +- Dateien gelesen +- Referenzen ausgewertet +- Findings angezeigt +- Reports exportiert + +Es werden keine Daten veraendert. + +## Sprache + +Die Oberflaeche unterstuetzt Deutsch und Englisch und richtet sich nach der eingestellten Foundry-Sprache.