@dennisrepa/elevate 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +227 -214
  2. package/dist/cli.js +3148 -1277
  3. package/dist/cli.js.map +1 -1
  4. package/docs/de.md +438 -305
  5. package/docs/en.md +442 -309
  6. package/package.json +88 -73
  7. package/docs/plans/transactional-updates.md +0 -142
package/docs/de.md CHANGED
@@ -1,305 +1,438 @@
1
- # 🪶 Elevate — Deutsche Dokumentation
2
-
3
- > **Interaktives Terminal-Dashboard (TUI) zur sicheren, selektiven und transparenten Aktualisierung von Abhängigkeiten in Polyglot-Monorepos.**
4
- > *Entwickelt und gepflegt von **Dennis Répa**.*
5
-
6
- ---
7
-
8
- ## 🌟 Übersicht
9
-
10
- **Elevate** ist ein interaktives Terminal-Dashboard (TUI) zur sicheren, selektiven und transparenten Aktualisierung von Abhängigkeiten in **Polyglot-Monorepos** (Node/npm & Java/Maven) sowie Einzelprojekten.
11
-
12
- * **Feder-Symbolik (`🪶`) & Orange-Brand (`#FF8800`):** Leicht, modern und übersichtlich im Terminal.
13
- * **Polyglot-Fähig:** Unterstützt gleichzeitig Frontend-Projekte (`package.json` mit npm Workspaces) und Backend-Projekte (`pom.xml` mit Maven).
14
- * **Release Channels:** Filtert Vorabversionen (Beta, RC, Alpha, Milestone, Snapshot) standardmäßig heraus und schlägt ausschließlich produktionsreife Releases vor.
15
- * **Animiertes Begleiter-Hühnchen („Pip“ 🐣):** Begleitet den Entwickler dezent im Terminal und reagiert auf Aktionen.
16
- * **Bilinguales i18n:** Jederzeit umschaltbar zwischen Deutsch und Englisch via Taste **`[L]`**.
17
-
18
- ---
19
-
20
- ## ✨ Features & Highlights
21
-
22
- 1. **🌐 Polyglot Monorepo Support (npm & Maven):**
23
- * **Node / npm:** Erkennt Root- und Workspace-Pakete, berechnet SemVer-Diffs, aktualisiert `package.json` und führt `npm install` aus.
24
- * **Java / Maven:** Durchsucht das Projekt nach allen `pom.xml`-Dateien (Spring-Boot-Services, Libraries etc.), fragt Maven Central ab und prüft Quellcode mit `mvn test-compile`.
25
- * **Live-Wechsel:** Ein Tastendruck auf **`[E]`** schaltet im laufenden Betrieb zwischen Frontend- und Backend-Modulen um.
26
-
27
- 2. **🔍 Version gezielt heraussuchen (`[V]`):**
28
- * Man muss nicht zwingend auf die `latest` Version aktualisieren: Taste **`[V]`** öffnet ein interaktives Such-Modal für das aktuell ausgewählte Paket.
29
- * Lädt alle jemals veröffentlichten Versionen aus der npm- oder Maven-Registry.
30
- * Ermöglicht Echtzeit-Filterung während des Tippens (z. B. `3.2` oder `25`), Pfeiltasten-Navigation und Übernahme mit `Enter`.
31
- * Manuell ausgewählte Versionen werden im Dashboard mit einem `[MANUELL]`-Badge hervorgehoben.
32
-
33
- 3. **🚦 Release Channels (`stable` vs. `all`):**
34
- * **`channel: "stable"` (Standard):** Verhindert das unabsichtliche Installieren instabiler Vorabversionen (`-alpha`, `-beta`, `-rc`, `-m1`, `-snapshot`).
35
- * **`channel: "all"`:** Zeigt alle Versionen an und hebt Vorabversionen mit farbigen Warn-Badges (`[BETA]`, `[RC]`, `[ALPHA]`) in Magenta hervor.
36
-
37
- 4. **🛡️ Monorepo-Schutz für interne Pakete:**
38
- * Schützt interne Pakete (z. B. `@my-org/*`, `com.mycompany.*`) davor, versehentlich durch fremde Bibliotheken aus öffentlichen Registries überschrieben zu werden.
39
-
40
- 5. **🐣 Das animierte Hühnchen („Pip“):**
41
- * Sitzt unten rechts im Dashboard.
42
- * Reagiert auf den Status:
43
- * *Idle:* Blinzelt sanft oder schlürft im Java-Modus Kaffee (`*kaffee schlürf* ☕`).
44
- * *Scan:* Sucht neugierig mit Lupe (`( ˘ө˘ )🔍`).
45
- * *Build:* Arbeitet emsig (`(ง •ө• )ง`).
46
- * *Erfolg:* Feiert das Update mit Konfetti (`\( ᵔөᵔ )/ 🎉`).
47
-
48
- 6. **🚀 Englischer Initial-Splash-Screen:**
49
- * Ein stylischer Startbildschirm mit animiertem Ladebalken (~3,2 Sekunden).
50
- * Kann jederzeit mit der `[Leertaste]` oder `[Enter]` sofort übersprungen werden.
51
-
52
- ---
53
-
54
- ## 🏗️ Domain-Driven Clean Architecture
55
-
56
- Elevate ist strikt nach den Prinzipien des **Domain-Driven Design (DDD)** und der **Hexagonalen Architektur (Ports & Adapters)** aufgebaut. UI und Hooks hängen niemals direkt von Paketmanagern ab:
57
-
58
- ```text
59
- src/
60
- ├── domain/ # 🧠 DOMAIN CORE (Reine Fachlogik, zero I/O)
61
- │ ├── models.ts # Entities & Value Objects (ProjectModule, UpdateCandidate, etc.)
62
- │ ├── ports.ts # Domain Ports (ModuleDiscoveryPort, RegistryPort, etc.)
63
- │ ├── ecosystem-strategy.ts # Strategy Pattern: Plattform-agnostisches Interface
64
- │ └── ecosystem-factory.ts # Factory Pattern: Liefert npm- oder Maven-Strategie
65
- │
66
- ├── adapters/ # 🔌 ADAPTERS (Konkrete Implementierungen)
67
- │ ├── npm/ # 📦 Node / npm Adapter
68
- │ │ ├── npm-discovery.ts # Liest workspaces aus Root-package.json
69
- │ │ ├── npm-registry.ts # npm-Registry-Abfragen & Dist-Tags
70
- │ │ ├── npm-scanner.ts # Parst dependencies & SemVer-Diffs
71
- │ │ ├── npm-updater.ts # Aktualisiert package.json & npm install
72
- │ │ ├── npm-verifier.ts # Konsistenzchecks & Build-Tests
73
- │ │ └── npm-strategy.ts # NpmEcosystemStrategy
74
- │ │
75
- │ └── maven/ # ☕ Java / Maven Adapter
76
- │ ├── maven-discovery.ts # Findet alle pom.xml im Projektbaum
77
- │ ├── maven-registry.ts # Maven Central Metadata & Release-Filter
78
- │ ├── maven-scanner.ts # Parst dependencies, Deduplizierung & Properties
79
- │ ├── maven-updater.ts # Aktualisiert pom.xml & mvn dependency:resolve
80
- │ ├── maven-verifier.ts # mvn test-compile Quellcode-Verifikation
81
- │ └── maven-strategy.ts # MavenEcosystemStrategy
82
- │
83
- ├── hooks/ # 🎣 APPLICATION HOOKS (Verwenden ausschließlich Ports)
84
- │ ├── use-workspaces.ts # Modulverwaltung über ModuleDiscoveryPort
85
- │ ├── use-packages.ts # Scan & Filterung über DependencyReaderPort
86
- │ └── use-updater.ts # Update & Verifikation über Updater-/Verifier-Ports
87
- │
88
- ├── components/ # 🎨 PRESENTATIONAL UI (Reine Darstellung mit Ink)
89
- │ ├── header.tsx # Ökosystem [E], Channel [stable], Sprache [L], Autor
90
- │ ├── workspace-bar.tsx # Aktives Modul mit statischem Schutzhinweis
91
- │ ├── mascot.tsx # 🐣 Animiertes Begleiter-Hühnchen ("Pip")
92
- │ ├── status-bar.tsx # Wackelfreie Statusleiste mit Zählern & Pip
93
- │ ├── tab-bar.tsx # Ökosystem-spezifische Tabs
94
- │ ├── package-list.tsx # Scrollbare Liste im Orange-Design
95
- │ ├── package-row.tsx # Zeile mit Badges ([Patch], [Minor], [MAJOR], [BETA])
96
- │ ├── controls-bar.tsx # Tastaturkürzel
97
- │ ├── workspace-modal.tsx # Modalauswahl für Module
98
- │ ├── version-modal.tsx # 🔍 Modale Version-Suche & Picker
99
- │ ├── splash-screen.tsx # Initialer Start-Screen
100
- │ ├── updating-view.tsx # Fortschrittsanzeige während des Updates
101
- │ └── summary-view.tsx # Ergebnisbericht nach Abschluss
102
- │
103
- ├── cli/ # 💻 HEADLESS CLI SUBCOMMANDS (für CI/CD & Shell-Agents)
104
- │ ├── parser.ts # Befehlszeilen-Parser (node:util.parseArgs)
105
- │ ├── command-modules.ts # `elevate modules`
106
- │ ├── command-scan.ts # `elevate scan`
107
- │ ├── command-versions.ts # `elevate versions`
108
- │ └── command-update.ts # `elevate update`
109
- │
110
- ├── mcp/ # 🤖 MODEL CONTEXT PROTOCOL (MCP Server)
111
- │ └── mcp-server.ts # Standardisierter stdio MCP-Server mit 5 Tools
112
- │
113
- ├── i18n/ # 🌍 Sprachverwaltung (de.ts / en.ts)
114
- ├── config.ts # ⚙️ Konfigurations-Loader
115
- ├── theme.ts # 🎨 Farb-Tokens & Icons
116
- ├── app.tsx # 📱 App-Shell (Container)
117
- └── index.tsx # 🏁 Universeller Einstiegspunkt (TUI / CLI / MCP)
118
- ```
119
-
120
- ---
121
-
122
- ## 🤖 Agentic & CI/CD Nutzung (Headless CLI & MCP)
123
-
124
- Elevate kann von KI-Agenten (Claude Code, Antigravity, Cursor, Copilot) sowie automatisierten CI/CD-Pipelines nahtlos angesteuert werden.
125
-
126
- ### 1. Headless CLI-Befehle (`--json`)
127
-
128
- ```bash
129
- # Module im Monorepo auflisten
130
- node tools/updater/elevate/index.mjs modules --json
131
-
132
- # Abhängigkeiten aller Module scannen (Exit-Code 1 wenn Updates verfügbar)
133
- node tools/updater/elevate/index.mjs scan --channel=stable --all-modules --json
134
-
135
- # Vollständige Versionshistorie eines Pakets abfragen
136
- node tools/updater/elevate/index.mjs versions chalk --json
137
-
138
- # Updates mit Guardrails simulieren (--dry-run)
139
- node tools/updater/elevate/index.mjs update --module=apps/e2e-cockpit --packages=chalk@5.6.2 --dry-run --json
140
-
141
- # Major-Updates gezielt anwenden (--allow-major erforderlich)
142
- node tools/updater/elevate/index.mjs update --module=apps/e2e-cockpit --packages=pinia@4.0.3 --allow-major --json
143
- ```
144
-
145
- ### 2. Model Context Protocol (MCP) Server
146
-
147
- Elevate bietet einen vollwertigen, stdio-basierten MCP-Server:
148
- ```bash
149
- node tools/updater/elevate/index.mjs mcp
150
- ```
151
-
152
- In der MCP-Konfiguration hinterlegen (z. B. `claude_desktop_config.json` oder Antigravity MCP):
153
- ```json
154
- {
155
- "mcpServers": {
156
- "elevate": {
157
- "command": "npx",
158
- "args": ["-y", "@dennisrepa/elevate", "mcp"]
159
- }
160
- }
161
- }
162
- ```
163
-
164
- #### Verfügbare MCP-Tools für LLMs:
165
- | Tool | Funktion |
166
- | :--- | :--- |
167
- | `elevate_discover_modules` | Erkennt alle Monorepo-Module und Workspaces für npm oder Maven |
168
- | `elevate_scan` | Scannt ein Modul (oder alle Module) nach verfügbaren Updates |
169
- | `elevate_get_versions` | Ruft die Versionshistorie direkt aus der Registry ab |
170
- | `elevate_apply_updates` | Wendet Updates mit Guardrails und Verifikations-Builds an |
171
- | `elevate_verify` | Führt modulspezifische Build- und Test-Checks aus |
172
-
173
- ---
174
-
175
- ## ⌨️ Tastatur-Steuerung (Interaktive TUI)
176
-
177
- | Taste | Aktion |
178
- | :--- | :--- |
179
- | **`E`** | **Ökosystem umschalten (📦 Node/npm ⇄ ☕ Java/Maven)** |
180
- | **`W`** | Modul- / Workspace-Auswahl öffnen |
181
- | **`V`** | **Version heraussuchen (Interaktiver Such- & Filterdialog)** |
182
- | **`L`** | Sprache umschalten (Deutsch ⇄ English) |
183
- | **`↑` / `↓`** *(oder `k`/`j`)* | In der Liste navigieren |
184
- | **`Space`** | Markierung des fokussierten Eintrags umschalten |
185
- | **`A`** | Alle sichtbaren Einträge im aktuellen Tab umschalten |
186
- | **`Tab`** *(oder `1`, `2`, `3`)* | Zwischen Tabs wechseln |
187
- | **`U`** | Update für alle ausgewählten Einträge starten |
188
- | **`R`** | Aktuelles Modul neu scannen |
189
- | **`Q`** | Elevate beenden |
190
-
191
- ---
192
-
193
- ## ⚙️ Konfiguration (`elevate.config.json`)
194
-
195
- Im Wurzelverzeichnis deines Repositories kann optional eine `elevate.config.json` angelegt werden:
196
-
197
- ```json
198
- {
199
- "author": "Dennis Répa",
200
- "channel": "stable",
201
- "locale": "de",
202
- "excludeScopes": ["@my-org", "com.mycompany"],
203
- "postUpdateScript": "npm test",
204
- "postUpdateLabel": "Test-Suite ausführen"
205
- }
206
- ```
207
-
208
- * **`author`:** Optionaler Name, der oben rechts im Header erscheint.
209
- * **`channel`:** `"stable"` (Standard, schließt Betas/RCs aus) oder `"all"` (zeigt auch Vorabversionen).
210
- * **`locale`:** `"de"` (Deutsch), `"en"` (Englisch) oder `"auto"` (automatische Erkennung).
211
- * **`excludeScopes`:** Liste interner Paket-Präfixe, die vor externen Registry-Abfragen geschützt werden.
212
- * **`postUpdateScript`:** Optionaler Konsistenz- oder Testbefehl nach einem npm-Update.
213
-
214
- ---
215
-
216
- ## 📦 Installation & Bereitstellung
217
-
218
- Elevate bietet maximale Flexibilität für jede Entwickler-Umgebung:
219
-
220
- ### 1. ⚡ Sofortstart ohne Installation via `npx` (Empfohlen)
221
- Startet Elevate sofort, ohne Klonen oder npm-Installationen:
222
- ```bash
223
- npx @dennisrepa/elevate
224
- ```
225
- > **Für autonome KI-Agenten (Claude Code, Cursor, Antigravity):**
226
- > Direkt in der MCP-Konfiguration hinterlegen:
227
- > ```json
228
- > {
229
- > "mcpServers": {
230
- > "elevate": {
231
- > "command": "npx",
232
- > "args": ["-y", "@dennisrepa/elevate", "mcp"]
233
- > }
234
- > }
235
- > }
236
- > ```
237
-
238
- ---
239
-
240
- ### 2. 🪟 Standalone Executable (Komplett ohne Node.js)
241
- Für reine Java-Entwickler, Systemadministratoren oder CI-Server ohne Node-Installation:
242
- 1. `elevate.exe` (Windows) oder `elevate-linux` aus den **[GitHub Releases](https://github.com/dennisrepa/elevate/releases)** herunterladen.
243
- 2. Direkt im Terminal oder per Doppelklick starten:
244
- ```powershell
245
- .\elevate.exe
246
- ```
247
-
248
- ---
249
-
250
- ### 3. 🌍 Globale System-Installation
251
- Installiert den Befehl `elevate` dauerhaft in jedem Terminal:
252
- ```bash
253
- npm install -g @dennisrepa/elevate
254
- ```
255
- Danach überall einfach aufrufen:
256
- ```bash
257
- elevate
258
- ```
259
-
260
- ---
261
-
262
- ### 4. 🏢 Monorepo- & Projekt-Integration
263
- Als devDependency im eigenen Monorepo hinterlegen:
264
- ```bash
265
- npm install -D @dennisrepa/elevate
266
- ```
267
- Skript in die Root-`package.json` einfügen:
268
- ```json
269
- {
270
- "scripts": {
271
- "elevate": "elevate"
272
- }
273
- }
274
- ```
275
- Jedes Teammitglied kann das Dashboard nun starten mit:
276
- ```bash
277
- npm run elevate
278
- ```
279
-
280
- ---
281
-
282
- ### 5. 🛠️ Lokale Entwicklung & Mitwirken (In diesem Repo)
283
- ```bash
284
- cd tools/updater/elevate
285
- npm run build
286
- npm link
287
- ```
288
- Direkt aus dem Root-Verzeichnis ausführen:
289
- ```powershell
290
- .\elevate.exe
291
- # oder
292
- node tools/updater/elevate/dist/cli.js
293
- ```
294
-
295
- ---
296
-
297
- ## ☕ Projekt unterstützen (Ko-fi & Sponsoring)
298
-
299
- Elevate ist Open-Source und wird mit Leidenschaft entwickelt. Wenn dir das Tool gefällt und es dir oder deinem Team Zeit spart, kannst du die Weiterentwicklung gerne unterstützen:
300
-
301
- [![Dennis Répa auf Ko-fi unterstützen](https://img.shields.io/badge/Ko--fi-Support%20Dennis%20R%C3%A9pa-F16061?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/dennisrepa)
302
-
303
- * ☕ **[Dennis Répa auf Ko-fi einen Kaffee spendieren](https://ko-fi.com/dennisrepa)**
304
- * 💻 Oder im Terminal: `npm fund @dennisrepa/elevate`
305
-
1
+ # 🪶 Elevate — Deutsche Dokumentation
2
+
3
+ > **Interaktives Terminal-Dashboard (TUI) zur sicheren, selektiven und transparenten Aktualisierung von Abhängigkeiten in Polyglot-Monorepos.**
4
+ > *Entwickelt und gepflegt von **Dennis Répa**.*
5
+
6
+ ---
7
+
8
+ ## 🌟 Übersicht
9
+
10
+ **Elevate** ist ein interaktives Terminal-Dashboard (TUI) zur sicheren, selektiven und transparenten Aktualisierung von Abhängigkeiten in **Polyglot-Monorepos** (Node/npm & Java/Maven) sowie Einzelprojekten.
11
+
12
+ * **Feder-Symbolik (`🪶`) & Orange-Brand (`#FF8800`):** Leicht, modern und übersichtlich im Terminal.
13
+ * **Polyglot-Fähig:** Unterstützt gleichzeitig Frontend-Projekte (`package.json` mit npm Workspaces) und Backend-Projekte (`pom.xml` mit Maven).
14
+ * **Release Channels:** Filtert Vorabversionen (Beta, RC, Alpha, Milestone, Snapshot) standardmäßig heraus und schlägt ausschließlich produktionsreife Releases vor.
15
+ * **Animiertes Begleiter-Hühnchen („Pip“ 🐣):** Begleitet den Entwickler dezent im Terminal und reagiert auf Aktionen.
16
+ * **Bilinguales i18n:** Jederzeit umschaltbar zwischen Deutsch und Englisch via Taste **`[L]`**.
17
+
18
+ ---
19
+
20
+ ## ✨ Features & Highlights
21
+
22
+ 1. **🌐 Polyglot Monorepo Support (npm, pnpm & Maven):**
23
+ * **Node / npm:** Löst Workspaces genau wie npm auf (inklusive Glob-Mustern wie `packages/**`), berechnet SemVer-Diffs, aktualisiert `package.json`, führt `npm install` aus und prüft das Lockfile.
24
+ * **Node / pnpm** (9 – 12): Dasselbe für pnpm-Repositories — Workspaces aus `pnpm-workspace.yaml`, das `workspace:`-Protokoll, `catalog:`-Einträge, `pnpm install` und eine Lockfile-Prüfung. Repositories mit Yarn oder Bun werden abgelehnt.
25
+ * **Java / Maven:** Findet jede `pom.xml` (auch die Root-POM), lässt Maven die Effective POM berechnen, sucht neuere Versionen über die Repositories des Builds (Mirrors, Nexus/Artifactory, Zugangsdaten aus der `settings.xml`) und prüft die betroffenen Module mit `mvn test-compile`.
26
+ * **Live-Wechsel:** Ein Tastendruck auf **`[E]`** schaltet im laufenden Betrieb zwischen Frontend- und Backend-Modulen um.
27
+
28
+ 2. **🔍 Version gezielt heraussuchen (`[V]`):**
29
+ * Man muss nicht zwingend auf die `latest` Version aktualisieren: Taste **`[V]`** öffnet ein interaktives Such-Modal für das aktuell ausgewählte Paket.
30
+ * Lädt alle jemals veröffentlichten Versionen aus der npm- oder Maven-Registry.
31
+ * Ermöglicht Echtzeit-Filterung während des Tippens (z. B. `3.2` oder `25`), Pfeiltasten-Navigation und Übernahme mit `Enter`.
32
+ * Manuell ausgewählte Versionen werden im Dashboard mit einem `[MANUELL]`-Badge hervorgehoben.
33
+
34
+ 3. **🚦 Release Channels (`stable` vs. `all`):**
35
+ * **`channel: "stable"` (Standard):** Verhindert das unabsichtliche Installieren instabiler Vorabversionen (`-alpha`, `-beta`, `-rc`, `-m1`, `-snapshot`).
36
+ * **`channel: "all"`:** Zeigt alle Versionen an und hebt Vorabversionen mit farbigen Warn-Badges (`[BETA]`, `[RC]`, `[ALPHA]`) in Magenta hervor.
37
+
38
+ 4. **🏢 Interne Abhängigkeiten (Workspace-Module & private Registries):**
39
+ * Workspace-Module, die voneinander abhängen, werden an ihre lokale Version angeglichen (`[Angleichen]`).
40
+ * Interne Pakete (`internalScopes`, z. B. `@my-org/*`, `com.mycompany.*`) werden nur in privaten Registries abgefragt, nie in einer öffentlichen.
41
+ * Details im Abschnitt [Interne Abhängigkeiten & Sicherheit](#-interne-abhängigkeiten--sicherheit).
42
+
43
+ 5. **🐣 Das animierte Hühnchen („Pip“):**
44
+ * Sitzt unten rechts im Dashboard.
45
+ * Reagiert auf den Status:
46
+ * *Idle:* Blinzelt sanft oder schlürft im Java-Modus Kaffee (`*kaffee schlürf* ☕`).
47
+ * *Scan:* Sucht neugierig mit Lupe (`( ˘ө˘ )🔍`).
48
+ * *Build:* Arbeitet emsig (`(ง •ө• )ง`).
49
+ * *Erfolg:* Feiert das Update mit Konfetti (`\( ᵔөᵔ )/ 🎉`).
50
+
51
+ 6. **🚀 Englischer Initial-Splash-Screen:**
52
+ * Ein stylischer Startbildschirm mit animiertem Ladebalken (~3,2 Sekunden).
53
+ * Kann jederzeit mit der `[Leertaste]` oder `[Enter]` sofort übersprungen werden.
54
+
55
+ ---
56
+
57
+ ## 🏢 Interne Abhängigkeiten & Sicherheit
58
+
59
+ Jede Abhängigkeit erhält eine **Herkunft**, bevor eine Registry kontaktiert wird:
60
+
61
+ | Herkunft | Erkannt an | Versionsquelle | Aktion |
62
+ | :--- | :--- | :--- | :--- |
63
+ | `workspace` | Ein Modul dieses Repositorys | Die **lokale** Version des Moduls | `align` (angleichen) |
64
+ | `private` | `internalScopes` oder eine explizite Zuordnung `@scope:registry` in der `.npmrc` | Die dafür konfigurierte private Registry | `update` |
65
+ | `public` | Alles andere | Die konfigurierte Registry | `update` |
66
+
67
+ Die URL der Registry allein entscheidet bewusst **nicht** über die Herkunft: In den meisten Unternehmen läuft jede Anfrage — auch für öffentliche Pakete — über einen Artifactory- oder Nexus-Proxy.
68
+
69
+ ### Workspace-Module angleichen
70
+
71
+ * **npm:** Schließt der Versionsbereich einer Abhängigkeit die lokale Version eines Workspace-Pakets nicht ein, verlinkt npm das Workspace **nicht**, sondern installiert ein gleichnamiges Paket aus der Registry. Elevate bietet an, den Bereich anzugleichen (z. B. `^1.0.0` ➔ `^2.0.0`). Nach `npm install` prüft es die `package-lock.json`: Jede angeglichene Abhängigkeit muss `"link": true` sein, sonst wird das Update zurückgenommen. Bereiche, die npm immer verlinkt (`*`, `file:`, `workspace:`), bleiben unberührt.
72
+ * **pnpm:** pnpm verlinkt ein Workspace-Paket nur, wenn die Abhängigkeit mit dem `workspace:`-Protokoll geschrieben ist; ein einfacher Bereich wie `^1.0.0` wird aus der Registry aufgelöst — auch wenn die lokale Version ihn erfüllt. Elevate gleicht deshalb `workspace:^1.2.0` ➔ `workspace:^2.0.0` an (Protokoll und Präfix bleiben; `workspace:*`, `workspace:^`, `workspace:~` und `workspace:../lib` brauchen nichts) und führt einen einfachen Bereich auf ein Modul als *nicht verlinkt* (`not-linked`) auf, ohne den Namen je in einer Registry nachzuschlagen oder den Bereich umzuschreiben. Nach `pnpm install` liest es den Abschnitt `importers` der `pnpm-lock.yaml` (`lockfileVersion` 9.x): Jede angeglichene Abhängigkeit muss eine `version` mit `link:` haben, sonst wird das Update zurückgenommen.
73
+ * **Maven:** Hängt ein Modul mit abweichender Version von einem Modul *desselben Reactors* ab (z. B. `1.0.0`, während das Modul auf `1.1.0-SNAPSHOT` steht), bietet Elevate das Angleichen an. Verweise über `${project.version}` brauchen kein Angleichen.
74
+ * Der Release Channel gilt beim Angleichen nicht: Ziel ist die lokale Version — auch `-SNAPSHOT` —, weil die Module eines Repositorys zusammen gebaut und getestet werden.
75
+
76
+ ### Private Registries & Dependency Confusion
77
+
78
+ * Interne Pakete werden nie in einer öffentlichen Registry abgefragt. Löst die Registry eines internen npm-Pakets zu `registry.npmjs.org` auf, wird es mit Begründung als *nicht angeboten* aufgeführt, statt abgefragt zu werden — genau diese Anfrage nach einem internen Namen nutzt ein Dependency-Confusion-Angriff aus.
79
+ * npm-Abfragen verwenden die npm-Konfiguration (`npm config`), Maven-Abfragen Maven selbst — Mirrors, private Repositories und Zugangsdaten gelten ohne eigene Elevate-Konfiguration, und Elevate fasst nie Zugangsdaten an.
80
+
81
+ ### Wohin Maven-Versionen geschrieben werden
82
+
83
+ Die Effective POM sagt, welche Version gilt, nicht wo sie steht. Elevate sucht die deklarierende Stelle — `<version>` einer Abhängigkeit, ein Eintrag im `<dependencyManagement>`, eine Property (auch in einer Parent-POM) oder ein externer `<parent>` — und ändert genau diesen Text; Formatierung und Kommentare bleiben erhalten. Vor dem Schreiben wird der Wert mit der effektiven Version abgeglichen. Weichen sie ab (aktive Profile, Properties von der Kommandozeile) oder stammt die Version aus einem externen Parent/BOM, wird die Abhängigkeit mit Begründung als *nicht angeboten* aufgeführt. Artefakte, die sich eine Versions-Property teilen, werden gekennzeichnet; widersprüchliche Zielversionen für eine gemeinsame Property werden abgelehnt.
84
+
85
+ ### Rücknahme
86
+
87
+ Jedes Update läuft als ein Ablauf: **Snapshot ➔ Schreiben & Installieren ➔ Integritätsprüfung ➔ Verifikation**. Schlägt Installation, Integritätsprüfung oder Verifikation fehl, werden alle berührten Dateien (Manifeste, Lockfile, Parent-POMs) wiederhergestellt und `node_modules` neu installiert. `--keep-on-failure` (CLI) bzw. `keepOnFailure` (MCP) behält die Änderungen einer fehlgeschlagenen *Verifikation* zur Untersuchung. Die Verifikation läuft außerdem einmal *vor* dem Update: Schlägt sie schon dort fehl, wird ein Fehlschlag danach als bereits vorhanden gemeldet und das Update behalten statt zurückgenommen. Ein abstürzender Verifier zählt als fehlgeschlagene Verifikation.
88
+
89
+ ### Verifikation
90
+
91
+ * **npm:** `npm ls` im Repository-Root (fehlende, ungültige oder unerfüllte Abhängigkeiten in allen Workspaces), sofern kein `postUpdateScript` gesetzt ist.
92
+ * **Maven:** `mvn test-compile -pl <geänderte Module> -amd` im Reactor — die geänderten Module *und alle Module, die von ihnen abhängen*. Eine Änderung an der Aggregator-POM baut den ganzen Reactor.
93
+
94
+ ### Voraussetzungen für Maven
95
+
96
+ Elevate verwendet den Maven Wrapper des Projekts (`mvnw` / `mvnw.cmd`), sonst `mvn` aus dem `PATH`. Fehlt beides, bricht der Maven-Scan mit einer klaren Meldung ab, statt zu raten. Die Plugin-Versionen sind für reproduzierbare Ergebnisse festgelegt (`maven-help-plugin` 3.5.2, `versions-maven-plugin` 2.22.0) und lassen sich je Repository mit `mavenPlugins` in der `elevate.config.json` ersetzen (siehe [Maven-Plugin-Versionen](#maven-plugin-versionen)). Scans schreiben temporäre Dateien nur nach `target/.elevate-*` und entfernen sie danach.
97
+
98
+ ### Repository-Root
99
+
100
+ Elevate verhält sich gleich, egal wo im Repository es gestartet wird. Der Root wird so bestimmt:
101
+
102
+ 1. Das nächste Verzeichnis (vom Startverzeichnis aufwärts) mit einer `elevate.config.json` ist der Root.
103
+ 2. Sonst schlägt npm das nächste Verzeichnis vor, dessen `package.json` `workspaces` deklariert, und Maven das obere Ende der zusammenhängenden POM-Kette (ein `<parent>`, der über `<relativePath>` gefunden wird, und jeder Aggregator, der das Projekt in `<modules>` aufführt). Der äußerste Vorschlag gewinnt.
104
+ 3. Ohne jede Markierung ist das Startverzeichnis der Root.
105
+
106
+ Die Suche verlässt nie den Checkout der Versionsverwaltung: Sie endet im nächsten Verzeichnis, das einen `.git`-Eintrag enthält. Eine verirrte `package.json` oder `pom.xml` oberhalb des Repositorys wird daher nie für dessen Root gehalten. Manifeste, die sich nicht lesen lassen, werden übersprungen.
107
+
108
+ ### Paketmanager-Schutz (Yarn und Bun)
109
+
110
+ Elevate unterstützt für Node.js npm und pnpm. In einem Repository, das Yarn oder Bun verwaltet, verweigert es Scan und Änderungen, weil jedes der beiden Werkzeuge ein zweites Lockfile und ein `node_modules`-Layout anlegen würde, das das Projekt nicht nutzt. Der Paketmanager wird vom Repository-Root aus erkannt, in dieser Reihenfolge: Feld `packageManager` der `package.json` (`npm@`, `pnpm@`, `yarn@`, `bun@`), dann `package-lock.json` / `npm-shrinkwrap.json`, `pnpm-lock.yaml` / `pnpm-workspace.yaml`, `yarn.lock` / `.yarnrc.yml`, `bun.lock` / `bun.lockb`; ohne Treffer gilt das Repository als npm. Startet Elevate innerhalb eines Workspace-Pakets, wird in den übergeordneten Verzeichnissen bis zum Checkout (nächstes Verzeichnis mit `.git`) weitergesucht. Die Ablehnung nennt den Paketmanager und die entscheidende Datei. Maven-Module im selben Repository, lesende Versionsabfragen (`elevate versions`) und ein eigenes `postUpdateScript` sind nicht betroffen.
111
+
112
+ ### pnpm-Workspaces und Catalogs
113
+
114
+ * **Workspace-Datei.** In einem pnpm-Repository bestimmt die Liste `packages` der `pnpm-workspace.yaml` (nicht das Feld `workspaces` der `package.json`) die Module; Muster mit `*`, `**` und `!` funktionieren wie bei npm, der Root ist immer ein Modul, `node_modules` enthält nie Module. Eine `pnpm-workspace.yaml` markiert auch den Repository-Root, selbst ohne `packages`. Eine Datei, die kein gültiges YAML ist, gilt als nicht vorhanden.
115
+ * **Catalogs.** Eine Abhängigkeit mit `catalog:` / `catalog:default` / `catalog:<name>` wird mit dem Bereich aus dem Catalog angeboten; der neue Bereich wird in genau diesen Eintrag der `pnpm-workspace.yaml` geschrieben (Kommentare, Anführungszeichen, Schreibweise und Zeilenenden bleiben; die `package.json` des Moduls wird nicht umgeschrieben). Eine nicht auflösbare Referenz erscheint als `catalog-unresolved`. Die JSON-Ausgabe nennt den Ort: `"declaredIn": {"file": "pnpm-workspace.yaml", "kind": "catalog", "catalog": "default"}`.
116
+ * **Overrides** (`pnpm.overrides`, `overrides` in der `pnpm-workspace.yaml`, `resolutions`) und `peerDependencies` werden nie geändert.
117
+
118
+ ### Befehle, die Elevate für pnpm ausführt
119
+
120
+ Alle im Repository-Root mit dem `pnpm` aus dem `PATH` (Version über `packageManager`/Corepack). Zuerst läuft `pnpm --version`; scheitert es, bricht die Operation mit einer Erklärung ab, bevor etwas verändert wird.
121
+
122
+ | Zweck | Befehl | Timeout |
123
+ | :--- | :--- | :--- |
124
+ | pnpm benutzbar? | `pnpm --version` | 15 s |
125
+ | Installation nach dem Schreiben der Bereiche | `pnpm install --no-frozen-lockfile` | 10 min |
126
+ | Wiederherstellung nach Rollback | `pnpm install --frozen-lockfile` | 10 min |
127
+ | Standard-Verifikation (Lockfile-Konsistenz, ersetzt `npm ls`) | `pnpm install --frozen-lockfile --lockfile-only` | 10 min |
128
+ | Schwachstellen-Zusammenfassung | `pnpm audit --json` | 60 s |
129
+ | Versionen eines Pakets | `pnpm view <name> <field> --json` | 15 s |
130
+ | Registry-Konfiguration | `pnpm config list --json` | 15 s |
131
+
132
+ `--no-frozen-lockfile` wird ausdrücklich übergeben, weil `pnpm install` bei gesetztem `CI` implizit eingefroren ist und am gerade geänderten Manifest scheitern würde. `pnpm ls` taugt nicht zur Verifikation: Es endet auch bei fehlenden Abhängigkeiten mit 0. Die Schwachstellen-Zusammenfassung stammt aus `pnpm audit --json`; ein Audit ohne Ergebnis ist eine Warnung, nie ein Grund für ein Rollback. pnpm-Einstellungen wie `minimumReleaseAge` oder die Freigabe von Build-Skripten liest Elevate nicht; lehnt pnpm deshalb ab, wird mit pnpms eigener Meldung zurückgenommen.
133
+
134
+ ### Abhängigkeitsbereiche (npm)
135
+
136
+ | Bereich | Gescannt | Geschrieben |
137
+ | :--- | :---: | :---: |
138
+ | `dependencies`, `devDependencies`, `optionalDependencies` | ja | ja |
139
+ | `peerDependencies`, `overrides`, `bundleDependencies` | nein | nie |
140
+
141
+ Ein Peer-Bereich sagt Verbrauchern, mit welchen Versionen ein Paket funktioniert; ihn anzuheben, nur weil es eine neuere Version gibt, wäre ein Breaking Change, den niemand beschlossen hat. Ein Name, der in mehreren gescannten Bereichen steht, erhält den neuen Bereich in jedem davon; zur Anzeige haben `optionalDependencies` Vorrang vor `dependencies` (wie bei npm), und ein Name, der auch Entwicklungsabhängigkeit ist, wird als solche angezeigt.
142
+
143
+ ### Angleichen innerhalb des Reactors (Maven)
144
+
145
+ Eine Abhängigkeit von einem anderen Modul wird nur dann an dessen lokale Version angeglichen, wenn beide Module vom selben äußersten Aggregator gebaut werden (derselbe Reactor). Außerhalb eines Reactors löst Maven die Abhängigkeit wie jedes andere Artefakt aus einem Repository auf, auch wenn irgendwo im Checkout ein Projekt mit denselben Koordinaten liegt (ein Beispiel, eine Testdatei, eine alte Kopie). Eine solche Abhängigkeit wird daher abgefragt und als gewöhnliches Update angeboten — `private`, wenn sie zu `internalScopes` passt, sonst `public`. POM-Dateien unterhalb des `src`-Verzeichnisses eines Projekts (Testdateien, `maven-invoker-plugin`-Projekte, Archetype-Vorlagen) sowie unterhalb von `node_modules`, `target`, `build`, `dist`, `out` oder versteckten Verzeichnissen sind keine Module, es sei denn, ein `<modules>`-Abschnitt nennt sie.
146
+
147
+ ### Maven-Plugin-Versionen
148
+
149
+ Elevate startet zwei Maven-Plugins: `maven-help-plugin` (liest die Effective POM, Standard `3.5.2`) und `versions-maven-plugin` (fragt neuere Versionen ab, Standard `2.22.0`). Bietet dein Repository-Manager diese Versionen nicht an, lege mit `mavenPlugins` in der `elevate.config.json` andere fest. Ein Wert muss mit einer Ziffer beginnen und darf nur Buchstaben, Ziffern, `.` und `-` enthalten (höchstens 64 Zeichen); alles andere wird durch den Standard ersetzt und als Warnung gemeldet. Kann Maven ein Plugin nicht herunterladen, sagt Elevate das, nennt das Plugin und die Einstellung, mit der sich seine Version ersetzen lässt, und hängt Mavens eigene Fehlerzeilen an.
150
+
151
+ ### Windows-Pfade
152
+
153
+ Unter Windows sind `npm`, `mvn` und der Maven Wrapper Batch-Dateien, die über `cmd.exe` laufen. Dieses deutet `" % ! ^ & | < >` selbst innerhalb von Anführungszeichen; Elevate setzt kein Argument mit einem dieser Zeichen auf eine Kommandozeile. Das Verzeichnis, in dem das Repository liegt, wird dem Prozess als Arbeitsverzeichnis übergeben, Projektdateien werden relativ dazu benannt — ein Pfad wie `C:\R&D\shop` funktioniert also. Namen *innerhalb* des Repositorys, die auf einer Kommandozeile landen (etwa ein Modulverzeichnis für `-pl`), dürfen diese Zeichen weiterhin nicht enthalten; die Fehlermeldung nennt das Argument und die Abhilfe.
154
+
155
+ ---
156
+
157
+ ## 🏗️ Domain-Driven Clean Architecture
158
+
159
+ Elevate ist strikt nach den Prinzipien des **Domain-Driven Design (DDD)** und der **Hexagonalen Architektur (Ports & Adapters)** aufgebaut. UI und Hooks hängen niemals direkt von Paketmanagern ab:
160
+
161
+ ```text
162
+ src/
163
+ ├── domain/ # 🧠 DOMAIN CORE (Reine Fachlogik, zero I/O)
164
+ │ ├── models.ts # Entities & Value Objects (ProjectModule, UpdateCandidate, DependencyOrigin, …)
165
+ │ ├── origin.ts # Herkunft (workspace / private / public)
166
+ │ ├── versions.ts # Erkennung von Vorabversionen & Versionshilfen
167
+ │ ├── ports.ts # Domain Ports (ModuleDiscoveryPort, RegistryPort, etc.)
168
+ │ ├── ecosystem-strategy.ts # Strategy Pattern: Plattform-agnostisches Interface
169
+ │ └── ecosystem-factory.ts # Factory Pattern: Liefert npm- oder Maven-Strategie
170
+ │
171
+ ├── adapters/ # 🔌 ADAPTERS (Konkrete Implementierungen)
172
+ │ ├── shared/ # 🧰 XML (positionsgenau), Prozesse, Snapshots, Pooling
173
+ │ │
174
+ │ ├── npm/ # 📦 Node / npm Adapter
175
+ │ │ ├── npm-config.ts # Effektive npm-Konfiguration (Registry je Scope)
176
+ │ │ ├── npm-discovery.ts # Workspaces über @npmcli/map-workspaces
177
+ │ │ ├── npm-registry.ts # npm-view-Abfragen & Dist-Tags
178
+ │ │ ├── npm-scanner.ts # Herkunft, Angleichen, SemVer-Diffs
179
+ │ │ ├── npm-lockfile.ts # Prüfung der Workspace-Verlinkung im Lockfile
180
+ │ │ ├── npm-commands.ts # Befehle je Paketmanager (npm / pnpm)
181
+ │ │ ├── npm-protocols.ts # Bereichs-Protokolle workspace: / catalog:
182
+ │ │ ├── pnpm-workspace.ts # pnpm-workspace.yaml: Pakete, Catalogs, Änderung an Ort und Stelle
183
+ │ │ ├── pnpm-lockfile.ts # Verlinkungsprüfung in der pnpm-lock.yaml
184
+ │ │ ├── pnpm-audit.ts # Zusammenfassung von pnpm audit --json
185
+ │ │ ├── npm-updater.ts # Aktualisiert package.json & npm install
186
+ │ │ ├── npm-verifier.ts # npm ls / eigene Verifikation
187
+ │ │ └── npm-strategy.ts # NpmEcosystemStrategy
188
+ │ │
189
+ │ └── maven/ # ☕ Java / Maven Adapter
190
+ │ ├── maven-command.ts # Aufruf über Maven Wrapper / mvn
191
+ │ ├── maven-pom.ts # Rohes POM-Modell mit editierbaren Textbereichen
192
+ │ ├── maven-project.ts # Alle POMs des Repos, Parent-Ketten, Reactors
193
+ │ ├── maven-discovery.ts # Module inkl. Root-POM, Versionen, Aggregator
194
+ │ ├── maven-resolution.ts # Effective POM & Report des versions-maven-plugin
195
+ │ ├── maven-locator.ts # Findet die Stelle, an der eine Version steht
196
+ │ ├── maven-scanner.ts # Herkunft, Angleichen, Update-Kandidaten
197
+ │ ├── maven-registry.ts # `elevate versions` über Maven (jeder Nexus/Artifactory)
198
+ │ ├── maven-updater.ts # Formatierungserhaltende POM-Änderungen
199
+ │ ├── maven-verifier.ts # mvn test-compile -pl … -amd
200
+ │ └── maven-strategy.ts # MavenEcosystemStrategy
201
+ │
202
+ ├── application/ # 🧭 ANWENDUNGSFÄLLE für TUI, CLI und MCP
203
+ │ ├── scan.ts # Scan-Kontext, Modulsuche, JSON-Ausgabe
204
+ │ ├── update-selection.ts # Guardrails für angeforderte Updates
205
+ │ ├── update-workflow.ts # Snapshot ➔ Installation ➔ Integrität ➔ Verifikation ➔ Rücknahme
206
+ │ └── version-lookup.ts # Versionshistorie ohne öffentliche Abfrage interner Namen
207
+ │
208
+ ├── hooks/ # 🎣 APPLICATION HOOKS (Verwenden ausschließlich Ports)
209
+ │ ├── use-workspaces.ts # Modulverwaltung über ModuleDiscoveryPort
210
+ │ ├── use-packages.ts # Scan & Filterung über DependencyReaderPort
211
+ │ └── use-updater.ts # Führt den gemeinsamen Update-Ablauf aus
212
+ │
213
+ ├── components/ # 🎨 PRESENTATIONAL UI (Reine Darstellung mit Ink)
214
+ │ ├── header.tsx # Ökosystem [E], Channel [stable], Sprache [L], Autor
215
+ │ ├── workspace-bar.tsx # Aktives Modul mit statischem Schutzhinweis
216
+ │ ├── mascot.tsx # 🐣 Animiertes Begleiter-Hühnchen ("Pip")
217
+ │ ├── status-bar.tsx # Wackelfreie Statusleiste mit Zählern & Pip
218
+ │ ├── tab-bar.tsx # Ökosystem-spezifische Tabs
219
+ │ ├── package-list.tsx # Scrollbare Liste im Orange-Design
220
+ │ ├── package-row.tsx # Zeile mit Badges ([Patch], [Minor], [MAJOR], [BETA])
221
+ │ ├── controls-bar.tsx # Tastaturkürzel
222
+ │ ├── workspace-modal.tsx # Modalauswahl für Module
223
+ │ ├── version-modal.tsx # 🔍 Modale Version-Suche & Picker
224
+ │ ├── splash-screen.tsx # Initialer Start-Screen
225
+ │ ├── updating-view.tsx # Fortschrittsanzeige während des Updates
226
+ │ └── summary-view.tsx # Ergebnisbericht nach Abschluss
227
+ │
228
+ ├── cli/ # 💻 HEADLESS CLI SUBCOMMANDS (für CI/CD & Shell-Agents)
229
+ │ ├── parser.ts # Befehlszeilen-Parser (node:util.parseArgs)
230
+ │ ├── command-modules.ts # `elevate modules`
231
+ │ ├── command-scan.ts # `elevate scan`
232
+ │ ├── command-versions.ts # `elevate versions`
233
+ │ └── command-update.ts # `elevate update`
234
+ │
235
+ ├── mcp/ # 🤖 MODEL CONTEXT PROTOCOL (MCP Server)
236
+ │ └── mcp-server.ts # Standardisierter stdio MCP-Server mit 5 Tools
237
+ │
238
+ ├── i18n/ # 🌍 Sprachverwaltung (de.ts / en.ts)
239
+ ├── config.ts # ⚙️ Konfigurations-Loader
240
+ ├── theme.ts # 🎨 Farb-Tokens & Icons
241
+ ├── app.tsx # 📱 App-Shell (Container)
242
+ └── index.tsx # 🏁 Universeller Einstiegspunkt (TUI / CLI / MCP)
243
+ ```
244
+
245
+ ---
246
+
247
+ ## 🤖 Agentic & CI/CD Nutzung (Headless CLI & MCP)
248
+
249
+ Elevate kann von KI-Agenten (Claude Code, Antigravity, Cursor, Copilot) sowie automatisierten CI/CD-Pipelines nahtlos angesteuert werden.
250
+
251
+ ### 1. Headless CLI-Befehle (`--json`)
252
+
253
+ ```bash
254
+ # Module im Monorepo auflisten
255
+ node tools/updater/elevate/index.mjs modules --json
256
+
257
+ # Abhängigkeiten aller Module scannen
258
+ # (Exit-Code 0 = aktuell, 1 = Updates verfügbar, 3 = ein Modul konnte nicht gescannt werden)
259
+ node tools/updater/elevate/index.mjs scan --channel=stable --all-modules --json
260
+
261
+ # Vollständige Versionshistorie eines Pakets abfragen
262
+ node tools/updater/elevate/index.mjs versions chalk --json
263
+
264
+ # Updates mit Guardrails simulieren (--dry-run)
265
+ node tools/updater/elevate/index.mjs update --module=apps/e2e-cockpit --packages=chalk@5.6.2 --dry-run --json
266
+
267
+ # Major-Updates gezielt anwenden (--allow-major erforderlich)
268
+ node tools/updater/elevate/index.mjs update --module=apps/e2e-cockpit --packages=pinia@4.0.3 --allow-major --json
269
+
270
+ # Änderungen behalten, wenn die Verifikation fehlschlägt (Standard: Rücknahme)
271
+ node tools/updater/elevate/index.mjs update --module=apps/web --all --keep-on-failure
272
+ ```
273
+
274
+ `scan --json` liefert je Modul die `updates` (mit `action`, `origin` und bei Maven `declaredIn`) und die übersprungenen Abhängigkeiten unter `skipped` mit `reason`. `update` endet mit Exit-Code `2`, wenn das Update fehlschlug und zurückgenommen wurde.
275
+
276
+ ### 2. Model Context Protocol (MCP) Server
277
+
278
+ Elevate bietet einen vollwertigen, stdio-basierten MCP-Server:
279
+ ```bash
280
+ node tools/updater/elevate/index.mjs mcp
281
+ ```
282
+
283
+ In der MCP-Konfiguration hinterlegen (z. B. `claude_desktop_config.json` oder Antigravity MCP):
284
+ ```json
285
+ {
286
+ "mcpServers": {
287
+ "elevate": {
288
+ "command": "npx",
289
+ "args": ["-y", "@dennisrepa/elevate", "mcp"]
290
+ }
291
+ }
292
+ }
293
+ ```
294
+
295
+ #### Verfügbare MCP-Tools für LLMs:
296
+ | Tool | Funktion |
297
+ | :--- | :--- |
298
+ | `elevate_discover_modules` | Erkennt alle Monorepo-Module und Workspaces für npm oder Maven |
299
+ | `elevate_scan` | Scannt ein Modul (oder alle Module) nach Updates und anzugleichenden internen Abhängigkeiten; nennt übersprungene Abhängigkeiten mit Grund |
300
+ | `elevate_get_versions` | Ruft die Versionshistorie aus der Registry ab (keine öffentliche Abfrage interner Pakete) |
301
+ | `elevate_apply_updates` | Wendet Updates mit Verifikation, Major-Guardrail und Rücknahme an (`keepOnFailure` optional) |
302
+ | `elevate_verify` | Führt modulspezifische Build- und Test-Checks aus |
303
+
304
+ ---
305
+
306
+ ## ⌨️ Tastatur-Steuerung (Interaktive TUI)
307
+
308
+ | Taste | Aktion |
309
+ | :--- | :--- |
310
+ | **`E`** | **Ökosystem umschalten (📦 Node/npm ⇄ ☕ Java/Maven)** |
311
+ | **`W`** | Modul- / Workspace-Auswahl öffnen |
312
+ | **`V`** | **Version heraussuchen (Interaktiver Such- & Filterdialog)** |
313
+ | **`L`** | Sprache umschalten (Deutsch ⇄ English) |
314
+ | **`↑` / `↓`** *(oder `k`/`j`)* | In der Liste navigieren |
315
+ | **`Space`** | Markierung des fokussierten Eintrags umschalten |
316
+ | **`A`** | Alle sichtbaren Einträge im aktuellen Tab umschalten |
317
+ | **`Tab`** *(oder `1`, `2`, `3`)* | Zwischen Tabs wechseln |
318
+ | **`U`** | Update für alle ausgewählten Einträge starten |
319
+ | **`R`** | Aktuelles Modul neu scannen |
320
+ | **`Q`** | Elevate beenden |
321
+
322
+ ---
323
+
324
+ ## ⚙️ Konfiguration (`elevate.config.json`)
325
+
326
+ Im Wurzelverzeichnis deines Repositories kann optional eine `elevate.config.json` angelegt werden:
327
+
328
+ ```json
329
+ {
330
+ "author": "Dennis Répa",
331
+ "channel": "stable",
332
+ "locale": "de",
333
+ "internalScopes": ["@my-org", "com.mycompany"],
334
+ "mavenPlugins": { "help": "3.5.2", "versions": "2.22.0" },
335
+ "postUpdateScript": "npm test",
336
+ "postUpdateLabel": "Test-Suite ausführen"
337
+ }
338
+ ```
339
+
340
+ * **`author`:** Optionaler Name, der oben rechts im Header erscheint.
341
+ * **`channel`:** `"stable"` (Standard, schließt Betas/RCs aus) oder `"all"` (zeigt auch Vorabversionen).
342
+ * **`locale`:** `"de"` (Deutsch), `"en"` (Englisch) oder `"auto"` (automatische Erkennung).
343
+ * **`internalScopes`:** Interne npm-Scopes und Maven-groupId-Präfixe. `@my-org` trifft `@my-org/*`; `com.mycompany` trifft `com.mycompany` und `com.mycompany.*` (nicht `com.mycompanyx`). Passende Pakete werden nur in privaten Registries abgefragt. *Früher `excludeScopes`; der alte Name wird weiter gelesen und als veraltet gemeldet.*
344
+ * **`mavenPlugins`:** Optionale Versionen der Maven-Plugins, die Elevate startet: `help` (`maven-help-plugin`, Standard `3.5.2`) und `versions` (`versions-maven-plugin`, Standard `2.22.0`). Nutze es, wenn dein Repository-Manager die Standardversionen nicht anbietet. Ungültige Werte fallen mit einer Warnung auf den Standard zurück.
345
+ * **`postUpdateScript`:** Optionaler Befehl, der die Standard-Verifikation (`npm ls` / `mvn test-compile`) ersetzt. Läuft im Repository-Root (npm) bzw. im Modulverzeichnis (Maven).
346
+
347
+ ---
348
+
349
+ ## 📦 Installation & Bereitstellung
350
+
351
+ Elevate bietet maximale Flexibilität für jede Entwickler-Umgebung:
352
+
353
+ ### 1. ⚡ Sofortstart ohne Installation via `npx` (Empfohlen)
354
+ Startet Elevate sofort, ohne Klonen oder npm-Installationen:
355
+ ```bash
356
+ npx @dennisrepa/elevate
357
+ ```
358
+ > **Für autonome KI-Agenten (Claude Code, Cursor, Antigravity):**
359
+ > Direkt in der MCP-Konfiguration hinterlegen:
360
+ > ```json
361
+ > {
362
+ > "mcpServers": {
363
+ > "elevate": {
364
+ > "command": "npx",
365
+ > "args": ["-y", "@dennisrepa/elevate", "mcp"]
366
+ > }
367
+ > }
368
+ > }
369
+ > ```
370
+
371
+ ---
372
+
373
+ ### 2. 🪟 Standalone Executable (Komplett ohne Node.js)
374
+ Für reine Java-Entwickler, Systemadministratoren oder CI-Server ohne Node-Installation:
375
+ 1. `elevate.exe` (Windows) oder `elevate-linux` aus den **[GitHub Releases](https://github.com/dennisrepa/elevate/releases)** herunterladen.
376
+ 2. Direkt im Terminal oder per Doppelklick starten:
377
+ ```powershell
378
+ .\elevate.exe
379
+ ```
380
+
381
+ ---
382
+
383
+ ### 3. 🌍 Globale System-Installation
384
+ Installiert den Befehl `elevate` dauerhaft in jedem Terminal:
385
+ ```bash
386
+ npm install -g @dennisrepa/elevate
387
+ ```
388
+ Danach überall einfach aufrufen:
389
+ ```bash
390
+ elevate
391
+ ```
392
+
393
+ ---
394
+
395
+ ### 4. 🏢 Monorepo- & Projekt-Integration
396
+ Als devDependency im eigenen Monorepo hinterlegen:
397
+ ```bash
398
+ npm install -D @dennisrepa/elevate
399
+ ```
400
+ Skript in die Root-`package.json` einfügen:
401
+ ```json
402
+ {
403
+ "scripts": {
404
+ "elevate": "elevate"
405
+ }
406
+ }
407
+ ```
408
+ Jedes Teammitglied kann das Dashboard nun starten mit:
409
+ ```bash
410
+ npm run elevate
411
+ ```
412
+
413
+ ---
414
+
415
+ ### 5. 🛠️ Lokale Entwicklung & Mitwirken (In diesem Repo)
416
+ ```bash
417
+ cd tools/updater/elevate
418
+ npm run build
419
+ npm link
420
+ ```
421
+ Direkt aus dem Root-Verzeichnis ausführen:
422
+ ```powershell
423
+ .\elevate.exe
424
+ # oder
425
+ node tools/updater/elevate/dist/cli.js
426
+ ```
427
+
428
+ ---
429
+
430
+ ## ☕ Projekt unterstützen (Ko-fi & Sponsoring)
431
+
432
+ Elevate ist Open-Source und wird mit Leidenschaft entwickelt. Wenn dir das Tool gefällt und es dir oder deinem Team Zeit spart, kannst du die Weiterentwicklung gerne unterstützen:
433
+
434
+ [![Dennis Répa auf Ko-fi unterstützen](https://img.shields.io/badge/Ko--fi-Support%20Dennis%20R%C3%A9pa-F16061?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/dennisrepa)
435
+
436
+ * ☕ **[Dennis Répa auf Ko-fi einen Kaffee spendieren](https://ko-fi.com/dennisrepa)**
437
+ * 💻 Oder im Terminal: `npm fund @dennisrepa/elevate`
438
+