hmgr 0.0.5 → 0.0.7

package/README.md

@@ -24,6 +24,16 @@ npm run build
 
 `npm run dev` startet `src/cli/main.ts`, `npm run build` erzeugt `dist/`.
 
+## GUI
+
+`npm run gui` startet die Electron-Oberfläche im Dev-Modus (`electron dist/gui/main.js`).
+
+`npm run gui:app` baut ein macOS-App-Bundle „hmgr.app" mit eigenem Icon und Namen im Dock/Finder (statt „Electron"), über [electron-builder](https://www.electron.build/). Das Ergebnis liegt in `release/mac-arm64/hmgr.app`, dazu ein `.zip` zum Weitergeben. Nur arm64, unsigniert, keine Notarisierung, kein Auto-Update — für den lokalen Gebrauch. Das Icon (`build/icon.icns`) entsteht aus `entwurf/icon/icon-1024.png`.
+
+`npm run gui:app:win` baut den Windows-Installer, auch auf dem Mac: NSIS braucht dort kein Wine, electron-builder lädt sich die nötigen Teile selbst. Es entsteht `release/hmgr-Setup-<version>-x64.exe` (rund 107 MiB) samt `.blockmap`, daneben die ungepackte App in `release/win-unpacked/`. Nur x64, installiert wird pro Benutzer nach `%LOCALAPPDATA%\Programs\hmgr` — ohne Administratorrechte, das Zielverzeichnis lässt sich im Installer ändern. Das Windows-Icon (`build/icon.ico`) erzeugt `entwurf/icon/erzeuge-ico.py` aus derselben `icon-1024.png`.
+
+Der Installer ist nicht signiert. Windows SmartScreen meldet sich deshalb beim ersten Start mit „Der Computer wurde durch Windows geschützt"; der Weg dahinter führt über „Weitere Informationen" und „Trotzdem ausführen".
+
 ## Kommandos
 
 `hmgr --help` zeigt die Kommandos, `hmgr help <kommando>` Schalter, Beispiele

package/dist/adapter/bundle-yaml.js

@@ -0,0 +1,87 @@
+// Liest eine Bundle-Definition aus einer Quelle (E69). hmgr schreibt solche Dateien nie.
+import { parseDocument } from 'yaml';
+import { BundleDateiFehler } from "../kern/modell.js";
+import { quelleAusText } from "./quelle-text.js";
+/** Konvention für Bundle-Definitionen in einer Quelle (E69): `bundles/<name>.yaml`. */
+export const BUNDLE_VERZEICHNIS = 'bundles';
+/**
+ * Ob ein Pfad in der Quelle eine Bundle-Definition ist: eine Datei direkt unter `bundles/`, mit
+ * Endung `.yaml` oder `.yml`. Nichts Verschachteltes — die Konvention nennt genau eine Ebene, und
+ * ein Unterordner wäre eine stille zweite Bedeutung.
+ */
+export function istBundleDatei(pfad) {
+    return /^bundles\/[^/]+\.(?:yaml|yml)$/.test(pfad);
+}
+/** Der Dateiname ohne Verzeichnis und Endung: Ersatzname, wenn das Feld `name` fehlt. */
+export function bundleDateiName(pfad) {
+    return pfad.replace(/^bundles\//, '').replace(/\.(?:yaml|yml)$/, '');
+}
+function fehlertext(fehler) {
+    return fehler instanceof Error ? fehler.message : String(fehler);
+}
+function istObjekt(wert) {
+    return typeof wert === 'object' && wert !== null && !Array.isArray(wert);
+}
+/** Erlaubte Felder auf oberster Ebene und je Mitglied. Alles andere ist ein Fehler mit Feldnamen. */
+const FELDER = new Set(['name', 'description', 'skills']);
+const MITGLIED_FELDER = new Set(['source', 'path']);
+function mitgliedLesen(datei, roh, i) {
+    if (!istObjekt(roh))
+        throw new BundleDateiFehler(datei, `skills[${i}] muss ein Objekt mit source und path sein`);
+    for (const feld of Object.keys(roh))
+        if (!MITGLIED_FELDER.has(feld))
+            throw new BundleDateiFehler(datei, `skills[${i}]: unbekanntes Feld „${feld}"`);
+    const source = roh['source'];
+    if (typeof source !== 'string' || source.trim().length === 0)
+        throw new BundleDateiFehler(datei, `skills[${i}].source muss die Adresse einer Quelle sein (URL oder Pfad)`);
+    const pfad = roh['path'];
+    if (typeof pfad !== 'string' || pfad.trim().length === 0)
+        throw new BundleDateiFehler(datei, `skills[${i}].path muss der Pfad des Skills in der Quelle sein`);
+    // Führende und abschließende Schrägstriche fallen weg: `skills/x/` und `skills/x` meinen denselben
+    // Ordner, und der Katalog führt ihn ohne (E11). Ein Wurzel-Skill (leerer Pfad) ist nicht
+    // adressierbar — er hieße in der Definition „", das ist kein Text und fliegt oben schon auf.
+    return { quelle: quelleAusText(source.trim()), pfad: pfad.trim().replace(/^\/+/, '').replace(/\/+$/, '') };
+}
+/**
+ * Eine Bundle-Definition aus dem YAML-Text lesen und validieren (E69). `datei` ist der Pfad in der
+ * Quelle, er dient als Ersatzname (ohne Verzeichnis und Endung), wenn das Feld `name` fehlt: der
+ * Dateiname ist Konvention, das Feld ist die Aussage des Autors — dieselbe Rangfolge wie beim
+ * Skill-Namen (E32). `quelle` ist die Quelle, in der die Datei liegt.
+ */
+export function bundleLesen(text, datei, quelle) {
+    let daten;
+    try {
+        const dokument = parseDocument(text, { strict: true });
+        // `parseDocument` sammelt Syntaxfehler, statt zu werfen: ohne diese Prüfung käme eine kaputte
+        // Datei als halb gelesenes Objekt durch und der Nutzer bekäme eine Meldung über ein Feld statt
+        // über die Datei.
+        const erster = dokument.errors[0];
+        if (erster !== undefined)
+            throw new BundleDateiFehler(datei, `kaputtes YAML: ${erster.message}`);
+        daten = dokument.toJS();
+    }
+    catch (fehler) {
+        if (fehler instanceof BundleDateiFehler)
+            throw fehler;
+        throw new BundleDateiFehler(datei, `kaputtes YAML: ${fehlertext(fehler)}`);
+    }
+    if (!istObjekt(daten))
+        throw new BundleDateiFehler(datei, 'die Datei muss ein Objekt mit name, description und skills sein');
+    for (const feld of Object.keys(daten))
+        if (!FELDER.has(feld))
+            throw new BundleDateiFehler(datei, `unbekanntes Feld „${feld}"`);
+    const rohName = daten['name'];
+    if (rohName !== undefined && (typeof rohName !== 'string' || rohName.trim().length === 0))
+        throw new BundleDateiFehler(datei, 'name muss nicht leerer Text sein');
+    const name = typeof rohName === 'string' ? rohName.trim() : bundleDateiName(datei);
+    const beschreibung = daten['description'];
+    if (typeof beschreibung !== 'string' || beschreibung.trim().length === 0)
+        throw new BundleDateiFehler(datei, 'description muss nicht leerer Text sein');
+    const skills = daten['skills'];
+    if (!Array.isArray(skills))
+        throw new BundleDateiFehler(datei, 'skills muss eine Liste sein');
+    if (skills.length === 0)
+        throw new BundleDateiFehler(datei, 'skills darf nicht leer sein');
+    const mitglieder = skills.map((roh, i) => mitgliedLesen(datei, roh, i));
+    return { name, beschreibung: beschreibung.trim(), mitglieder, quelle, datei };
+}

package/dist/adapter/checkout-pfad.js

@@ -1,7 +1,7 @@
 // Pfadschema der Checkouts (E22): <wurzel>/<host>/<besitzer>/<repo>/<ref>/,
 // je Repo ein Basis-Clone unter <wurzel>/<host>/<besitzer>/<repo>/.repo.
 import path from 'node:path';
-import { ortAusSegmenten, urlOrt } from "../kern/quelle-ort.js";
+import { istWindowsLaufwerkspfad, ortAusSegmenten, urlOrt } from "../kern/quelle-ort.js";
 export const BASIS_NAME = '.repo';
 /** Refs mit „/" im Namen werden im Pfad kodiert, damit ein Ref ein Verzeichnis bleibt. */
 export function refKodieren(ref) {
@@ -15,8 +15,16 @@ export function urlZerlegen(url) {
     const ort = urlOrt(url);
     if (ort !== undefined)
         return ort;
+    const text = url.trim();
+    // Windows-Laufwerkspfad (E65/B12): an beiden Trennern zerlegen und ohne den Laufwerksbuchstaben,
+    // denn ein Doppelpunkt ist unter Windows kein erlaubtes Zeichen in einem Verzeichnisnamen —
+    // „C:" als Besitzer ergäbe einen Checkout-Pfad, den das Dateisystem nicht anlegen kann. Ohne das
+    // Laufwerk ist es derselbe Fall wie ein POSIX-Pfad, dessen erstes Segment leer ist. Bewusst ohne
+    // `path.resolve`: die Zerlegung soll auf jeder Plattform dasselbe ergeben.
+    if (istWindowsLaufwerkspfad(text))
+        return ortAusSegmenten('local', text.slice(2).split(/[\\/]/));
     // Nackter lokaler Pfad: Besitzer aus dem Elternverzeichnis.
-    return ortAusSegmenten('local', path.resolve(url.trim()).split(path.sep));
+    return ortAusSegmenten('local', path.resolve(text).split(path.sep));
 }
 export function quelleZerlegen(quelle) {
     return urlZerlegen(quelle.art === 'git' ? quelle.url : quelle.pfad);

package/dist/adapter/claude-code.js

@@ -1,15 +1,25 @@
-// Claude Code: Grundverhalten plus Plugins über die claude-CLI (E16, E24, E27).
-import { spawn } from 'node:child_process';
-import { mkdir, stat } from 'node:fs/promises';
+// Claude Code: Grundverhalten plus Plugins und MCP-Server über die claude-CLI (E16, E24, E27, E61).
+import spawn from 'cross-spawn';
+import { realpathSync } from 'node:fs';
+import { mkdir, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { OrtNichtUnterstuetzt, pluginSchluessel } from "../kern/modell.js";
+import { McpAbweichenderEintrag, McpNichtInGeteilterDatei, McpNurGeteilterFundort, McpUebernahmeNichtMoeglich, McpUebernahmeUnvollstaendig, OrtNichtUnterstuetzt, pluginSchluessel, } from "../kern/modell.js";
+import { ohneBom } from "./datei-text.js";
 import { gitignoreEintragen, istGitRepo } from "./gitignore.js";
+import { tiefGleich } from "./vergleich.js";
 const GITIGNORE_ZEILE = '.claude/';
 /**
  * Standard-Ausführer: `claude` vom PATH. Ein Fehlschlag wird zum Code, nicht zur Ausnahme.
  * stdin ist zu, sonst hängt eine CLI, die auf Eingabe wartet, den ganzen Ablauf; der Timeout
  * fängt alles Übrige (beobachtet: 13 Minuten ohne Rückkehr in der GUI). SIGKILL, weil die
  * CLI SIGTERM überleben kann.
+ *
+ * `spawn` kommt von cross-spawn, nicht aus node:child_process (E65/B7): unter Windows ist die
+ * npm-installierte `claude` ein `.cmd`-Shim, und Node startet `.cmd`/`.bat` seit dem Fix zu
+ * CVE-2024-27980 ohne `shell: true` nicht mehr (EINVAL). Der error-Handler machte daraus Code 1,
+ * `vorhanden()` hielt die CLI für abwesend und alle MCP- und Plugin-Fähigkeiten fielen weg.
+ * cross-spawn setzt den Aufruf selbst auf cmd.exe um und quotet dabei richtig — nötig für
+ * Argumente wie das JSON von `mcp add-json`. Auf macOS und Linux ändert sich nichts.
  */
 export const claudeAusfuehrer = (args, cwd) => new Promise((aufloesen) => {
     const kind = spawn('claude', args, {
@@ -20,6 +30,8 @@ export const claudeAusfuehrer = (args, cwd) => new Promise((aufloesen) => {
     });
     let stdout = '';
     let stderr = '';
+    // `!`, weil cross-spawn nur den allgemeinen ChildProcess-Typ mit nullbaren Strömen kennt;
+    // das `stdio` oben verlangt für beide eine Pipe, also sind sie da.
     kind.stdout.on('data', (d) => (stdout += d));
     kind.stderr.on('data', (d) => (stderr += d));
     kind.on('error', (fehler) => aufloesen({ stdout: fehler.message, code: 1 }));
@@ -143,28 +155,240 @@ class ClaudePlugins {
             .map((eintrag) => pluginSchluessel(eintrag));
     }
 }
+/** Der JSON-Block für `claude mcp add-json`, aus dem neutralen Katalog-Konfigblock (E61). */
+export function claudeMcpJson(konfig) {
+    if ('command' in konfig)
+        return JSON.stringify({
+            type: 'stdio',
+            command: konfig.command,
+            ...(konfig.args === undefined ? {} : { args: konfig.args }),
+            ...(konfig.env === undefined ? {} : { env: konfig.env }),
+        });
+    return JSON.stringify({
+        type: 'http',
+        url: konfig.url,
+        ...(konfig.headers === undefined ? {} : { headers: konfig.headers }),
+    });
+}
+function objektFeld(daten, feld) {
+    if (typeof daten !== 'object' || daten === null)
+        return undefined;
+    return daten[feld];
+}
+function mcpServersVon(daten) {
+    const mcp = objektFeld(daten, 'mcpServers');
+    if (typeof mcp !== 'object' || mcp === null || Array.isArray(mcp))
+        return {};
+    return mcp;
+}
+/** Der aufgelöste Pfad, oder der Pfad selbst, wenn es ihn nicht (mehr) gibt. */
+function aufgeloest(pfad) {
+    try {
+        return realpathSync(pfad);
+    }
+    catch {
+        return pfad;
+    }
+}
+/**
+ * Die MCP-Server der geteilten `.mcp.json` eines Arbeitsverzeichnisses (E61-Nachtrag, Format
+ * `{"mcpServers": {<name>: {...}}}`, wie `~/.claude.json`). Nur gelesen, nie geschrieben: fehlende
+ * Datei heißt nichts, kaputtes JSON oder fremde Struktur ebenso, derselbe tolerante Umgang wie beim
+ * Lesen von `~/.claude.json`. Eine BOM zählt nicht als kaputt (E65/B11), sonst wirkt eine unter
+ * Windows angelegte Datei leer.
+ */
+async function projektMcpJsonLesen(verzeichnis) {
+    try {
+        const text = await readFile(path.join(verzeichnis, '.mcp.json'), 'utf8');
+        return mcpServersVon(JSON.parse(ohneBom(text)));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * MCP-Server über `claude mcp …` (E61). Schreiben ausschließlich über die CLI, dieselbe
+ * Ausführer-Infrastruktur wie bei Plugins. Für die Übersicht wird NUR `~/.claude.json` gelesen, nie
+ * geschrieben: user-Scope unter `mcpServers`, local-Scope je Projekt unter
+ * `projects.<pfad>.mcpServers`. Die geteilte `.mcp.json` in der Projektwurzel bleibt beim Ein- und
+ * Aushängen unangetastet (E57), `geteilteFundorte` liest sie für die Übersicht mit (E61-Nachtrag);
+ * geschrieben wird sie einzig von `geteiltenUebernehmen` auf ausdrücklichen Auftrag (E64). Format
+ * und Verhalten der CLI stehen in HARNESS-FAKTEN.md, geprüft an Claude Code 2.1.261 gegen ein
+ * eigenes CLAUDE_CONFIG_DIR, nie an einer echten Nutzerdatei.
+ */
+class ClaudeMcp {
+    harness;
+    ausfuehrer;
+    home;
+    constructor(harness, ausfuehrer, home) {
+        this.harness = harness;
+        this.ausfuehrer = ausfuehrer;
+        this.home = home;
+    }
+    ebenen() {
+        return ['home', 'arbeitsverzeichnis'];
+    }
+    hinweisNachAenderung() {
+        return 'Claude Code übernimmt die Änderung mit der nächsten Sitzung.';
+    }
+    scope(ort) {
+        if (ort.art === 'home')
+            return { scope: 'user' };
+        if (ort.art === 'arbeitsverzeichnis')
+            return { scope: 'local', cwd: ort.pfad };
+        throw new OrtNichtUnterstuetzt(this.harness.name, ort.art);
+    }
+    /**
+     * Die CLI legt keinen Eintrag über einen bestehenden: sie bricht mit Code 1 und „already exists"
+     * ab (belegt an 2.1.261). Deshalb wird danach in `~/.claude.json` nachgesehen: derselbe Block
+     * heißt „schon eingehängt" und ist idempotent wie bei Hermes, ein abweichender Block ist ein
+     * eigener Fehler statt einer englischen CLI-Zeile. hmgr überschreibt ihn nicht (E61).
+     */
+    async einhaengen(name, konfig, ort) {
+        const { scope, cwd } = this.scope(ort);
+        const json = claudeMcpJson(konfig);
+        const { stdout, code } = await this.ausfuehrer(['mcp', 'add-json', name, json, '--scope', scope], cwd);
+        if (code === 0)
+            return;
+        const bestehend = await this.eintrag(name, ort);
+        if (bestehend !== undefined) {
+            if (tiefGleich(bestehend, JSON.parse(json)))
+                return;
+            throw new McpAbweichenderEintrag({ harness: this.harness.name, ort }, name);
+        }
+        throw new Error(`claude mcp add-json ${name} scheiterte (Code ${code}): ${stdout.trim()}`);
+    }
+    /**
+     * Ist der Name am Ort gar nicht eingehängt, bricht die CLI mit Code 1 ab („No MCP server named",
+     * belegt an 2.1.261). Das ist kein Fehler, sondern das gewünschte Ergebnis: aushängen ist
+     * idempotent wie bei Hermes. Ausnahme (E61-Nachtrag): steht der Name nur in der geteilten
+     * `.mcp.json` der Projektwurzel, bleibt dort tatsächlich ein Eintrag liegen — das darf nicht als
+     * Erfolg durchgehen, sondern bekommt eine eigene Meldung.
+     */
+    async aushaengen(name, ort) {
+        const { scope, cwd } = this.scope(ort);
+        const { stdout, code } = await this.ausfuehrer(['mcp', 'remove', name, '--scope', scope], cwd);
+        if (code === 0)
+            return;
+        if ((await this.eintrag(name, ort)) !== undefined)
+            throw new Error(`claude mcp remove ${name} scheiterte (Code ${code}): ${stdout.trim()}`);
+        if (ort.art === 'arbeitsverzeichnis') {
+            const geteilt = await projektMcpJsonLesen(ort.pfad);
+            if (name in geteilt)
+                throw new McpNurGeteilterFundort({ harness: this.harness.name, ort }, name, path.join(ort.pfad, '.mcp.json'));
+        }
+    }
+    async eingehaengte(ort) {
+        return Object.keys(await this.mcpServersAm(ort));
+    }
+    /**
+     * Die geteilte `.mcp.json` eines Arbeitsverzeichnisses (E61-Nachtrag): im Alltag nur gelesen,
+     * weder beim Ein- noch beim Aushängen angefasst. Home kennt keine solche Datei.
+     */
+    async geteilteFundorte(ort) {
+        if (ort.art !== 'arbeitsverzeichnis')
+            return [];
+        const datei = path.join(ort.pfad, '.mcp.json');
+        const server = await projektMcpJsonLesen(ort.pfad);
+        return Object.keys(server).map((name) => ({ name, datei, scope: 'project' }));
+    }
+    /**
+     * Übernehmen (E64): den Block aus der geteilten `.mcp.json` der Projektwurzel 1:1 in den privaten
+     * local-Scope schreiben und ihn dort entfernen. Geschrieben wird ausschließlich über die CLI
+     * (E61), auch die geteilte Datei — `claude mcp remove <name> --scope project` mit der
+     * Projektwurzel als cwd kann das, ein eigener JSON-Schreibweg wäre eine zweite Wahrheit über das
+     * Dateiformat. Preis dafür: die CLI schreibt die Datei komplett neu und behält nur `mcpServers`,
+     * zusätzliche Top-Level-Schlüssel gehen verloren (belegt an 2.1.261, siehe HARNESS-FAKTEN.md) —
+     * dasselbe passiert dem Nutzer, wenn er die CLI selbst aufruft.
+     *
+     * Die Reihenfolge ist fail-safe: erst eintragen, dann entfernen. Scheitert der erste Schritt, ist
+     * nichts geschehen. Scheitert der zweite, steht der Eintrag doppelt statt nirgends — und weil
+     * local Vorrang vor project hat (belegt an 2.1.261), wirkt schon der private. Der Block kommt aus
+     * der Datei, nicht aus dem Katalog: auch ein Eintrag, den der Katalog nicht kennt, lässt sich so
+     * übernehmen.
+     */
+    async geteiltenUebernehmen(name, ort) {
+        const ziel = { harness: this.harness.name, ort };
+        if (ort.art !== 'arbeitsverzeichnis')
+            throw new McpUebernahmeNichtMoeglich(ziel);
+        const datei = path.join(ort.pfad, '.mcp.json');
+        const block = (await projektMcpJsonLesen(ort.pfad))[name];
+        if (block === undefined)
+            throw new McpNichtInGeteilterDatei(ziel, name, datei);
+        const hin = await this.ausfuehrer(['mcp', 'add-json', name, JSON.stringify(block), '--scope', 'local'], ort.pfad);
+        if (hin.code !== 0) {
+            // Der einzige harmlose Fehlschlag: derselbe Block liegt schon im privaten Scope, etwa weil ein
+            // früherer Lauf zwischen den beiden Schritten abgebrochen ist. Ein abweichender Block wird
+            // nicht überschrieben (E61), und die geteilte Datei bleibt dann unangetastet.
+            const bestehend = await this.eintrag(name, ort);
+            if (bestehend === undefined)
+                throw new Error(`claude mcp add-json ${name} scheiterte (Code ${hin.code}): ${hin.stdout.trim()}`);
+            if (!tiefGleich(bestehend, block))
+                throw new McpAbweichenderEintrag(ziel, name);
+        }
+        const weg = await this.ausfuehrer(['mcp', 'remove', name, '--scope', 'project'], ort.pfad);
+        // Nicht der Code entscheidet, sondern die Datei danach: steht der Name nicht mehr drin, ist die
+        // Übernahme fertig, egal wie die CLI den Fall genannt hat.
+        if (weg.code !== 0 && name in (await projektMcpJsonLesen(ort.pfad)))
+            throw new McpUebernahmeUnvollstaendig(ziel, name, datei, weg.stdout.trim());
+        return { datei };
+    }
+    /** Der eingehängte Block unter diesem Namen, oder undefined. */
+    async eintrag(name, ort) {
+        return (await this.mcpServersAm(ort))[name];
+    }
+    /**
+     * Die MCP-Server, die `~/.claude.json` für diesen Ort führt. Ein Arbeitsverzeichnis steht dort
+     * unter dem aufgelösten Pfad, weil Claude Code den cwd auflöst (belegt an 2.1.261); hmgr merkt
+     * sich Arbeitsverzeichnisse aber so, wie der Nutzer sie genannt hat, also zählen beide.
+     */
+    async mcpServersAm(ort) {
+        const daten = await this.claudeJsonLesen();
+        if (ort.art === 'home')
+            return mcpServersVon(daten);
+        if (ort.art === 'arbeitsverzeichnis') {
+            const projects = objektFeld(daten, 'projects');
+            const projekt = objektFeld(projects, ort.pfad) ?? objektFeld(projects, aufgeloest(ort.pfad));
+            return mcpServersVon(projekt);
+        }
+        throw new OrtNichtUnterstuetzt(this.harness.name, ort.art);
+    }
+    async claudeJsonLesen() {
+        try {
+            const text = await readFile(path.join(this.home, '.claude.json'), 'utf8');
+            return JSON.parse(ohneBom(text));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
 export class ClaudeCode {
     name = 'claude-code';
     home;
     ausfuehrer;
     /** Wird von `vorhanden()` gesetzt, sobald die claude-CLI auf dem PATH liegt. */
     plugins;
+    /** Wird von `vorhanden()` gesetzt, sobald die claude-CLI auf dem PATH liegt (E61). */
+    mcp;
     geprueft = false;
     constructor(home, ausfuehrer = claudeAusfuehrer) {
         this.home = home;
         this.ausfuehrer = ausfuehrer;
     }
     /**
-     * Claude Code liegt auf dem Rechner, wenn es sein Home angelegt hat. Die Plugin-Fähigkeit
-     * kommt dazu, sobald `claude --version` durchläuft: ohne CLI gibt es keine Plugins.
+     * Claude Code liegt auf dem Rechner, wenn es sein Home angelegt hat. Die Plugin- und
+     * MCP-Fähigkeit kommen dazu, sobald `claude --version` durchläuft: ohne CLI gibt es beides nicht.
      */
     async vorhanden() {
         const da = (await stat(path.join(this.home, '.claude')).catch(() => undefined)) !== undefined;
         if (!this.geprueft) {
             this.geprueft = true;
             const { code } = await this.ausfuehrer(['--version']).catch(() => ({ code: 1 }));
-            if (code === 0)
+            if (code === 0) {
                 this.plugins = new ClaudePlugins(this, this.ausfuehrer);
+                this.mcp = new ClaudeMcp(this, this.ausfuehrer, this.home);
+            }
         }
         return da;
     }

package/dist/adapter/composer.js

@@ -1,6 +1,7 @@
 // Zeiger in der composer.json des Repos, unter extra.hmgr (B8, E25, E26).
 import { readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { ohneBom } from "./datei-text.js";
 import { quelleAusText } from "./quelle-text.js";
 const DATEI = 'composer.json';
 /** Ruft hmgr nur auf, wenn es vorhanden ist, und lässt composer nie scheitern (E20). */
@@ -40,7 +41,7 @@ export class ComposerZeiger {
         return { ergebnis: 'mehrdeutig', kandidaten };
     }
     async lesen(pfad) {
-        const daten = JSON.parse(await readFile(pfad, 'utf8'));
+        const daten = JSON.parse(ohneBom(await readFile(pfad, 'utf8')));
         const eintrag = daten.extra?.hmgr ?? {};
         const verzeichnis = path.dirname(pfad);
         return {
@@ -50,7 +51,7 @@ export class ComposerZeiger {
         };
     }
     async schreiben(pfad, zeiger) {
-        const daten = JSON.parse(await readFile(pfad, 'utf8'));
+        const daten = JSON.parse(ohneBom(await readFile(pfad, 'utf8')));
         const eintrag = {
             sources: zeiger.quellen.map(quelleAlsEintrag),
             skills: Object.fromEntries(zeiger.skills),
@@ -64,7 +65,7 @@ export class ComposerZeiger {
      * und ihre Reihenfolge bleiben, der Rest der Datei bleibt unberührt. Idempotent.
      */
     async scriptEintragen(pfad) {
-        const daten = JSON.parse(await readFile(pfad, 'utf8'));
+        const daten = JSON.parse(ohneBom(await readFile(pfad, 'utf8')));
         const scripts = { ...(daten.scripts ?? {}) };
         let geaendert = false;
         for (const schluessel of SCRIPT_SCHLUESSEL) {

package/dist/adapter/datei-text.js

@@ -0,0 +1,18 @@
+// Gemeinsames Modul der Adapter: Text aus Dateien, die von Hand geschrieben sein können.
+/**
+ * Streift eine führende UTF-8-BOM ab (E65/B11). Windows-Editoren und PowerShell 5.1
+ * (`Set-Content -Encoding utf8`) schreiben sie an den Dateianfang. `JSON.parse` bricht daran ab
+ * („Unexpected token"), und wo dieser Fehler in einem `catch` landet, wirkt die Datei leer statt
+ * kaputt: `hmgr mcp migrate` meldete deshalb „steht nicht in der Datei", obwohl der Eintrag in der
+ * `.mcp.json` stand.
+ *
+ * Nur JSON braucht das. Der YAML-Parser kennt die BOM, und `String.trim()` streift sie mit ab —
+ * beides geprüft, deshalb bleiben config.yaml, mcp.yaml, `.gitignore` und `.env` unberührt.
+ *
+ * Beim Zurückschreiben geht die BOM verloren: hmgr schreibt jede JSON-Datei, die es ändert,
+ * vollständig neu (`JSON.stringify`). Das ist gewollt — die Datei bleibt gültiges UTF-8 und ist
+ * danach auch für Werkzeuge lesbar, die über die BOM stolpern.
+ */
+export function ohneBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

package/dist/adapter/dateisystem.js

@@ -2,8 +2,9 @@
 import { createHash } from 'node:crypto';
 import { lstat, mkdir, readFile, readdir, readlink, rm, stat, symlink, unlink } from 'node:fs/promises';
 import path from 'node:path';
-import { NameBelegt } from "../kern/modell.js";
+import { LinkAnlegenFehlgeschlagen, NameBelegt, } from "../kern/modell.js";
 import { checkoutZerlegen, quelleZerlegen } from "./checkout-pfad.js";
+import { ohneBom } from "./datei-text.js";
 import { LOKAL_REF } from "./git.js";
 import { SKILL_DATEI, skillAusPfad } from "./skill-md.js";
 /** Dateien eines Ordners rekursiv, `.git` und `node_modules` ausgenommen, Symlinks nicht gefolgt. */
@@ -19,6 +20,31 @@ async function ordnerDateien(wurzel, unter, ergebnis) {
             ergebnis.push({ relativerPfad: rel, inhalt: await readFile(path.join(wurzel, rel)) });
     }
 }
+/**
+ * Typ-Argument für `fs.symlink` (E66). Unter Windows eine Junction: einen Verzeichnis-Symlink
+ * verweigert das System dem unprivilegierten Nutzer, eine Junction legt es ohne Sonderrechte an
+ * (HARNESS-FAKTEN „Windows"). Sonst `undefined` — das ist für Node dasselbe wie kein drittes
+ * Argument, geprüft an Node 22: beide Aufrufe legen denselben Link.
+ */
+export function symlinkTyp(plattform = process.platform) {
+    return plattform === 'win32' ? 'junction' : undefined;
+}
+/**
+ * Streift das Windows-Präfix `\\?\` von einem Pfad ab (E66). `fs.readlink` gibt das Ziel einer
+ * Junction mitsamt diesem Präfix zurück; unverkürzt verglichen sähe derselbe Link auf einen
+ * anderen Pfad aus, und `deuten` hielte einen eigenen Link für fremd. Gekürzt wird nur die
+ * Laufwerksform: bei `\\?\UNC\server\share` gehört das Präfix zum Pfad. Auf POSIX ändert die
+ * Funktion nichts, dort kommt das Präfix nicht vor.
+ */
+export function ohneWindowsPraefix(pfad) {
+    return /^\\\\\?\\[A-Za-z]:/.test(pfad) ? pfad.slice(4) : pfad;
+}
+/** Was der Nutzer tun kann, wenn das Anlegen eines Links gescheitert ist (E66). */
+export function linkFehlerHinweis(plattform = process.platform) {
+    return plattform === 'win32'
+        ? 'Aktiviere den Windows-Entwicklermodus (Einstellungen → System → Für Entwickler) oder starte hmgr mit Administratorrechten.'
+        : 'Prüfe die Schreibrechte auf das Zielverzeichnis und ob das Linkziel vorhanden ist.';
+}
 export class DateisystemZiele {
     wurzel;
     zustand;
@@ -84,7 +110,9 @@ export class DateisystemZiele {
         const info = await lstat(pfad).catch(() => undefined);
         if (!info || !info.isSymbolicLink())
             return undefined;
-        return path.resolve(verzeichnis, await readlink(pfad));
+        // Junctions meldet Node als Symlink, ihr Ziel aber mit `\\?\`-Präfix (E66): erst kürzen, dann
+        // auflösen, sonst ergäbe `path.resolve` einen Pfad, der zu keinem Soll-Ziel passt.
+        return path.resolve(verzeichnis, ohneWindowsPraefix(await readlink(pfad)));
     }
     /**
      * Ein Skill ist ein Verzeichnis. Dateien wie .DS_Store zählen nicht als fremder Eintrag,
@@ -137,7 +165,17 @@ export class DateisystemZiele {
             else
                 throw new NameBelegt(ziel, name);
         }
-        await symlink(path.join(checkout.pfad, skill.pfad), pfad);
+        // Eine Junction verlangt ein absolutes Ziel (E66). `checkout.pfad` ist es in der Praxis immer
+        // — die Wurzel unter dem hmgr-Home, eine lokale Quelle über `path.resolve` in `quelle-text` —,
+        // nur garantiert das nichts: aus einer von Hand geänderten zustand.json käme auch ein
+        // relativer Pfad. `path.resolve` kostet nichts und macht die Zusage hier fest.
+        const checkoutZiel = path.resolve(checkout.pfad, skill.pfad);
+        try {
+            await symlink(checkoutZiel, pfad, symlinkTyp());
+        }
+        catch (ursache) {
+            throw new LinkAnlegenFehlgeschlagen(pfad, checkoutZiel, ursache instanceof Error ? ursache.message : String(ursache), linkFehlerHinweis());
+        }
     }
     async linkEntfernen(_ziel, verzeichnis, name) {
         const zielPfad = await this.linkZiel(verzeichnis, name);
@@ -175,7 +213,7 @@ export class DateisystemZiele {
     /** Eintrag zu `name` aus dem Lockfile-Inhalt. Kaputtes JSON oder fehlende Felder: undefined. */
     lockEintragAusInhalt(roh, name) {
         try {
-            const geparst = JSON.parse(roh);
+            const geparst = JSON.parse(ohneBom(roh));
             const eintrag = geparst.skills?.[name];
             if (eintrag === undefined)
                 return undefined;