@dennisrepa/elevate 1.2.0

package/docs/plans/transactional-updates.md

@@ -0,0 +1,142 @@
+# 🪶 Elevate — Plan: Transaktionale Updates & lokaler MCP-Betrieb
+
+> **Status:** geplant · **Stand:** 2026-09-25
+> **Betriebsmodell:** Elevate läuft lokal beim Entwickler. Sein Harness (Continue, Cline, Claude Code, Cursor …) startet `elevate mcp` als stdio-Server im Projektordner. Keine Container, kein Gateway (siehe Parity ADR 0006, gilt für die ganze Tool-Familie).
+
+---
+
+## 1. Ziele
+
+1. **Transaktionale Updates:** Schlägt die Verifikation fehl, bleibt das Repository unverändert.
+2. **Ein zentraler Update-Ablauf** statt drei Kopien in CLI, TUI und MCP.
+3. **Saubere Workspace-Bestimmung** im MCP-Betrieb (MCP Roots).
+4. **`init` für alle gängigen Harnesses**, inklusive Continue und Cline.
+
+## 2. Ausgangslage
+
+| Thema | Heute |
+|---|---|
+| Update-Ablauf | Manifest schreiben → `npm install` / `mvn dependency:resolve` → Verifikation, alles direkt im Repo ([npm-updater.ts](../../src/adapters/npm/npm-updater.ts), [maven-updater.ts](../../src/adapters/maven/maven-updater.ts), [npm-verifier.ts](../../src/adapters/npm/npm-verifier.ts), [maven-verifier.ts](../../src/adapters/maven/maven-verifier.ts)) |
+| Fehlgeschlagene Verifikation | Repo bleibt im geänderten Zustand, man muss selbst zurückrollen |
+| Duplikation | Ablauf „anwenden → verifizieren“ dreifach: [command-update.ts:173](../../src/cli/command-update.ts#L173), [use-updater.ts:34](../../src/hooks/use-updater.ts#L34), [mcp-server.ts:410](../../src/mcp/mcp-server.ts#L410) |
+| Workspace | `findMonorepoRoot(process.cwd())` ([config.ts:67](../../src/config.ts#L67)), MCP Roots werden nicht genutzt |
+| `init` | erkennt Cursor, Claude Desktop, Claude Code, Antigravity, VS Code, Windsurf ([command-init.ts](../../src/cli/command-init.ts)). **Continue und Cline fehlen.** |
+
+## 3. Zentraler Update-Workflow
+
+Neuer Application Service `src/application/update-workflow.ts`, den CLI, TUI und MCP gemeinsam nutzen:
+
+```ts
+export class UpdateWorkflow {
+  constructor(private strategy: EcosystemStrategy, private sandbox: WorkspaceSandboxPort) {}
+
+  async run(input: {
+    module: ProjectModule;
+    rootDir: string;
+    updates: UpdateCandidate[];
+    verify: boolean;
+    onProgress: (msg: string) => void;
+  }): Promise<UpdateWorkflowResult>;   // updateSummary, verifyResult, committed, changedFiles, followUps
+}
+```
+
+Dieser Schritt ändert **kein** Verhalten. Er beseitigt nur die Duplikation und schafft die Stelle, an der die Transaktion eingebaut wird.
+
+## 4. Transaktion über einen austauschbaren Arbeitsort
+
+### 4.1 Port
+
+```ts
+// src/domain/ports.ts
+export interface WorkspaceSandbox {
+  readonly workDir: string;
+  resolve(module: ProjectModule): ProjectModule;   // Modulpfade über relPath auf workDir abbilden
+}
+
+export interface WorkspaceSandboxPort {
+  open(rootDir: string): Promise<WorkspaceSandbox>;
+  commit(sandbox: WorkspaceSandbox, files: string[]): Promise<void>;
+  discard(sandbox: WorkspaceSandbox): Promise<void>;
+}
+```
+
+### 4.2 Adapter
+
+| Adapter | Verhalten | Einsatz |
+|---|---|---|
+| `SnapshotSandboxAdapter` | Arbeitet **direkt im Repo**, sichert vorher Manifeste + Lockfiles. Bei `discard` werden diese zurückgespielt und die Installation erneut ausgeführt, um `node_modules` wiederherzustellen. | **Standard.** Schnell, nutzt vorhandenes `node_modules` |
+| `CopySandboxAdapter` | Kopiert das Repo (git-getrackte + nicht ignorierte Dateien, ohne `node_modules`/`target`/`dist`) in ein Temp-Verzeichnis, arbeitet dort und schreibt bei Erfolg nur Manifeste + Lockfiles zurück. Danach wird im echten Repo installiert. | `--isolated`: maximale Sicherheit, z. B. für riskante Major-Updates. Das Repo wird während der Prüfung **nie** berührt. |
+| `InPlaceSandboxAdapter` | Heutiges Verhalten ohne Rollback | `--no-rollback`, für Sonderfälle |
+
+### 4.3 Ablauf
+
+```
+1. open        Snapshot anlegen bzw. Kopie erstellen
+2. apply       Manifest ändern, installieren
+3. verify      Build + Tests
+4a. grün       commit: Snapshot verwerfen bzw. Manifeste + Lockfiles zurückschreiben
+4b. rot        discard: Dateien zurückspielen + Installation wiederherstellen → Repo wie vorher
+5. Ergebnis    inkl. changedFiles und ggf. followUps
+```
+
+### 4.4 Updater melden geänderte Dateien
+
+`DependencyUpdaterPort.applyUpdates()` liefert zusätzlich die geänderten Dateien (relativ zum Root). Das braucht die Transaktion:
+
+| Ökosystem | Dateien |
+|---|---|
+| npm | betroffene `package.json` + `package-lock.json` |
+| Maven | betroffene `pom.xml` |
+| künftig pnpm / Yarn / Gradle | `pnpm-lock.yaml` / `yarn.lock` / `gradle.lockfile`, `libs.versions.toml` |
+
+### 4.5 Schutz vor parallelen Änderungen
+
+Beim `open` wird ein Hash der betroffenen Dateien gespeichert. Hat der Entwickler (oder ein anderer Agent) sie während des Laufs geändert, bricht `commit`/`discard` ab, statt fremde Änderungen zu überschreiben, und meldet den Konflikt.
+
+## 5. MCP-Betrieb
+
+### 5.1 Workspace-Bestimmung
+
+In dieser Reihenfolge:
+
+1. **MCP Roots** des Clients (bei mehreren Roots: Parameter `workspace` wählt aus, Default der erste; auf `roots/list_changed` reagieren)
+2. `--root <pfad>` bzw. `ELEVATE_ROOT`
+3. `findMonorepoRoot(process.cwd())` (heutiges Verhalten)
+
+Pfade außerhalb der Roots werden abgelehnt. Diese Logik wandert später ins gemeinsame Toolkit-Paket der Tool-Familie.
+
+### 5.2 Antworten
+
+- `elevate_apply_updates` meldet `rolledBack: true` samt Grund, wenn die Verifikation fehlschlug.
+- Parameter `isolated: boolean` (entspricht `--isolated`).
+- Keine verschachtelten Parameter mehr für einfache Fälle: zusätzlich `identifiers: string[]` (Update auf latest) neben dem bestehenden `updates`-Array. Das ist für lokale Modelle deutlich robuster.
+
+## 6. `init` für alle Harnesses
+
+Neu: **Continue** (`.continue/mcpServers/elevate.yaml` bzw. globale `config.yaml`) und **Cline** (`cline_mcp_settings.json`). Vorhandene Detektoren bleiben. Ziel ist eine Liste, die in der ganzen Tool-Familie identisch ist:
+
+`continue · cline · claude-code · claude-desktop · cursor · windsurf · vscode · antigravity`
+
+## 7. Tests
+
+- **Unit:** `UpdateWorkflow` mit Fake-Ports: grün → commit, rot → discard, Konflikt → Abbruch.
+- **Adapter:** Snapshot (Rückspielen, EOL-Erhalt, Wiederherstellung von `node_modules`), Copy (Kopierregeln, `resolve()` für verschachtelte Module, Rückschreiben).
+- **Integration:** Beispiel-Repo mit absichtlich brechendem Update. Danach ist das Repo per `git status` sauber und die Tests laufen wieder grün.
+- **MCP:** Roots-Handling mit Test-Client (ein Root, mehrere Roots, Wechsel).
+- **Regression:** TUI, CLI und MCP liefern bei grünen Updates dieselben Ergebnisse wie vorher.
+
+## 8. Umsetzungsschritte
+
+| Schritt | Inhalt | Fertig, wenn |
+|---|---|---|
+| 1 | `UpdateWorkflow`, CLI/TUI/MCP umstellen | Duplikation entfernt, Verhalten unverändert |
+| 2 | Port + `InPlaceSandboxAdapter`, Updater liefern `changedFiles` | Heutiges Verhalten läuft über den Port |
+| 3 | `SnapshotSandboxAdapter` als Standard, Konfliktschutz | Rote Verifikation hinterlässt ein unverändertes Repo |
+| 4 | `CopySandboxAdapter` + `--isolated` | Repo wird während isolierter Prüfung nicht berührt |
+| 5 | MCP Roots, `--root`, `rolledBack`, `identifiers` | Roots-Tests grün |
+| 6 | `init` für Continue und Cline, Doku (de/en) | Beide Harnesses per `elevate init` eingerichtet |
+
+## 9. Offene Fragen
+
+1. Soll bei einem Rollback die Wiederherstellung von `node_modules` per `npm ci` (exakt, langsamer) oder `npm install` (schneller) erfolgen? *Vorschlag:* `npm ci`, wenn ein Lockfile existiert.
+2. Workspace-Bestimmung und `init` zuerst in Elevate bauen und danach ins Toolkit-Paket verschieben, oder direkt im Toolkit starten? *Vorschlag:* direkt im Toolkit, damit Register und Parity sofort profitieren.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@dennisrepa/elevate",
+  "version": "1.2.0",
+  "description": "🪶 Elevate — Interactive Polyglot Terminal Dashboard & Agentic MCP Server for safe dependency updates across monorepos.",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "bin": {
+    "elevate": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cli",
+    "tui",
+    "dependencies",
+    "updater",
+    "monorepo",
+    "npm",
+    "maven",
+    "mcp",
+    "agentic"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DennisRepa/Elevate.git"
+  },
+  "homepage": "https://github.com/DennisRepa/Elevate#readme",
+  "bugs": {
+    "url": "https://github.com/DennisRepa/Elevate/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "build:binary": "node scripts/build-binary.mjs",
+    "dev": "tsx src/index.tsx",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "author": {
+    "name": "Dennis Répa",
+    "email": "dennis.maier.1989@gmail.com",
+    "url": "https://de.linkedin.com/in/dennismaier1989"
+  },
+  "funding": {
+    "type": "ko-fi",
+    "url": "https://ko-fi.com/dennisrepa"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "ink": "^6.3.0",
+    "picocolors": "^1.1.1",
+    "react": "^19.0.0",
+    "semver": "^7.6.3",
+    "tsx": "^4.19.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "@types/react": "^19.3.0",
+    "@types/semver": "^7.8.0",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2"
+  }
+}