hmgr 0.0.5 → 0.0.6

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/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;

package/dist/adapter/git.js

@@ -28,13 +28,17 @@ async function existiert(pfad) {
 }
 /**
  * Aus Dateipfaden die Skill-Verzeichnisse bilden: ein Verzeichnis mit SKILL.md ist ein Skill.
- * Bekannte Orte zuerst (E11). Den Namen bekommt der Skill erst aus seiner SKILL.md (E32).
+ * Bekannte Orte zuerst (E11). Den Namen bekommt der Skill erst aus seiner SKILL.md (E32). Eine
+ * SKILL.md direkt an der Wurzel (`teile.length === 1`) ergibt den Pfad `''`: das Repo ist selbst
+ * ein Skill (E11-Nachtrag 2026-09-05). `''` ist die einzige interne Schreibweise dafür, nie `.` —
+ * `checkoutZerlegen`, `skillAusPfad` und die Sparse-Checkout-Muster (unten) sind darauf abgestimmt.
+ * Wurzel-Skill und `skills/`-Unterordner schließen sich nicht aus, beide landen in der Liste.
  */
 export function skillPfadeAusDateien(dateien) {
     const verzeichnisse = new Set();
     for (const datei of dateien) {
         const teile = datei.split('/');
-        if (teile.at(-1) !== SKILL_DATEI || teile.length < 2)
+        if (teile.at(-1) !== SKILL_DATEI)
             continue;
         verzeichnisse.add(teile.slice(0, -1).join('/'));
     }
@@ -94,6 +98,14 @@ async function inhalteAufPlatte(wurzel, pfade) {
     }
     return ergebnis;
 }
+/**
+ * Ersatzname für einen Skill, dessen Pfad kein Segment hergibt (Wurzel-Skill, E11-Nachtrag): der
+ * Repo-Name der Quelle. Ohne ihn hieße der Skill „" und ein Link auf ihn zeigte nicht auf einen
+ * Eintrag im Ziel, sondern auf das Zielverzeichnis (E32).
+ */
+function ersatznameDerQuelle(quelle) {
+    return quelle.art === 'lokal' ? path.basename(quelle.pfad) : quelleZerlegen(quelle).repo;
+}
 async function dateienAufPlatte(wurzel, unter = '') {
     const eintraege = await readdir(path.join(wurzel, unter), { withFileTypes: true }).catch(() => []);
     const dateien = [];
@@ -180,24 +192,32 @@ export class GitQuellen {
     async skillMdInhalte(basis, ref, pfade) {
         if (pfade.length === 0)
             return new Map();
-        const eingabe = `${pfade.map((p) => `${ref}:${p}/${SKILL_DATEI}`).join('\n')}\n`;
+        // Ein Wurzel-Skill hat den Pfad `''`: `${ref}:${p}/${SKILL_DATEI}` ergäbe `ref:/SKILL.md` mit
+        // führendem Schrägstrich, den git als eigenen (ungültigen) Pfad läse statt als Wurzel (E39).
+        const eingabe = `${pfade.map((p) => `${ref}:${p.length === 0 ? SKILL_DATEI : `${p}/${SKILL_DATEI}`}`).join('\n')}\n`;
         const ausgabe = await this.gitMitEingabe(['cat-file', '--batch'], basis, eingabe).catch(() => undefined);
         if (ausgabe === undefined)
             return new Map();
         return batchInhalte(ausgabe, pfade);
     }
-    /** Skills der Quelle, Namen aus dem Frontmatter der SKILL.md (E32). */
+    /**
+     * Skills der Quelle, Namen aus dem Frontmatter der SKILL.md (E32). Ein Wurzel-Skill (Pfad `''`,
+     * E11-Nachtrag) hat keinen Verzeichnisnamen, aus dem `skillAusPfad` einen Namen ableiten könnte:
+     * der Repo-Name ist der Ersatzname, nie der leere String, sonst zeigte ein Link ohne Frontmatter
+     * `name` auf einen Eintrag mit leerem Namen im Ziel (E32).
+     */
     async skills(quelle, ref) {
+        const ersatzname = ersatznameDerQuelle(quelle);
         if (quelle.art === 'lokal') {
             const pfade = skillPfadeAusDateien(await dateienAufPlatte(quelle.pfad));
             const inhalte = await inhalteAufPlatte(quelle.pfad, pfade);
-            return pfade.map((pfad) => skillAusPfad(pfad, inhalte.get(pfad)));
+            return pfade.map((pfad) => skillAusPfad(pfad, inhalte.get(pfad), ersatzname));
         }
         const basis = await this.basis(quelle);
         const ausgabe = await this.git(['ls-tree', '-r', '--name-only', ref], basis);
         const pfade = skillPfadeAusDateien(ausgabe.split('\n').filter((z) => z.length > 0));
         const inhalte = await this.skillMdInhalte(basis, ref, pfade);
-        return pfade.map((pfad) => skillAusPfad(pfad, inhalte.get(pfad)));
+        return pfade.map((pfad) => skillAusPfad(pfad, inhalte.get(pfad), ersatzname));
     }
     /**
      * Marketplace einer Quelle (E24). Der Inhalt kommt aus dem Git-Baum, nicht aus einem Checkout:
@@ -227,7 +247,9 @@ export class GitQuellen {
             plugins: gelesen.plugins.map((p) => ({
                 name: p.name,
                 dependencies: p.dependencies,
-                skills: p.skills.map((pfad) => skillAusPfad(pfad, inhalte.get(pfad))),
+                // Auch hier kann ein Pfad leer sein (`"source": "."` mit `"skills": ["."]`): derselbe
+                // Ersatzname wie im Katalog, damit nie ein Skill ohne Namen entsteht (E32).
+                skills: p.skills.map((pfad) => skillAusPfad(pfad, inhalte.get(pfad), ersatznameDerQuelle(quelle))),
             })),
         };
     }
@@ -287,7 +309,11 @@ export class GitQuellen {
             if (!WURZEL_MUSTER.includes(eintrag))
                 muster.add(eintrag);
         // Ein Wurzel-Skill (E48 a, leerer Pfad) ist der ganze Baum: `/**` nimmt ihn nach `!/*/` wieder
-        // rekursiv auf, ein Muster `//` wäre kein gültiges Sparse-Checkout-Muster.
+        // rekursiv auf, ein Muster `//` wäre kein gültiges Sparse-Checkout-Muster. Der Link, den
+        // `linkLegen` darauf setzt, zeigt dann auf die Worktree-Wurzel selbst (E11-Nachtrag 2026-09-05):
+        // die ganze Arbeitskopie samt `.git` wird sichtbar, nicht nur die SKILL.md und ihre
+        // Unterordner. Ein Harness liest ohnehin nur SKILL.md und referenzierte Unterordner, das `.git`
+        // stört nicht — wohl aber sähe ein Nutzer, der den Link im Finder öffnet, den vollen Worktree.
         for (const skill of skills)
             muster.add(skill.pfad === '' ? '/**' : `/${skill.pfad}/`);
         await this.git(['sparse-checkout', 'set', '--no-cone', '--', ...muster], pfad);

package/dist/adapter/hermes.js

@@ -4,8 +4,9 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { Document, isMap, isScalar, isSeq, parseDocument } from 'yaml';
-import { OrtNichtUnterstuetzt, SkillOrdnerUngueltig } from "../kern/modell.js";
+import { McpAbweichenderEintrag, OrtNichtUnterstuetzt, SkillOrdnerUngueltig, } from "../kern/modell.js";
 import { gitignoreEintragen, istGitRepo } from "./gitignore.js";
+import { tiefGleich } from "./vergleich.js";
 const HERMES_VERZEICHNIS = '.hermes';
 const PROFILE_VERZEICHNIS = 'profiles';
 const CONFIG = 'config.yaml';
@@ -46,9 +47,39 @@ function trustedProjectDirs(daten) {
         return [];
     return dirs.filter((d) => typeof d === 'string');
 }
+/** Liest mcp_servers aus einer geparsten config.yaml (E61). Fehlt der Abschnitt, ist er leer. */
+function mcpServers(daten) {
+    if (typeof daten !== 'object' || daten === null)
+        return {};
+    const mcp = daten['mcp_servers'];
+    if (typeof mcp !== 'object' || mcp === null || Array.isArray(mcp))
+        return {};
+    return mcp;
+}
+/** Der neutrale Konfigblock als reines Objekt, für die config.yaml und für den Vergleich (E61). */
+function mcpKonfigAlsObjekt(konfig) {
+    if ('command' in konfig)
+        return {
+            command: konfig.command,
+            ...(konfig.args === undefined ? {} : { args: konfig.args }),
+            ...(konfig.env === undefined ? {} : { env: konfig.env }),
+        };
+    return { url: konfig.url, ...(konfig.headers === undefined ? {} : { headers: konfig.headers }) };
+}
 export class Hermes {
     name = 'hermes';
     home;
+    /**
+     * MCP-Server (E61): nur Home und Profil, denn Hermes kennt keine Projektebene für MCPs. Bindung
+     * über Arrow-Funktionen auf `this`, damit die Fähigkeit ohne eigene Klasse auskommt.
+     */
+    mcp = {
+        ebenen: () => ['home', 'profil'],
+        einhaengen: async (mcpName, konfig, ort) => this.mcpEinhaengen(ort, mcpName, konfig),
+        aushaengen: async (mcpName, ort) => this.mcpAushaengen(ort, mcpName),
+        eingehaengte: async (ort) => this.mcpEingehaengte(ort),
+        envDatei: (ort) => path.join(this.mcpHermesHome(ort), '.env'),
+    };
     /** `home` ist das HOME des Nutzers, das Hermes-Home liegt darunter als `.hermes`. */
     constructor(home) {
         this.home = home;
@@ -358,6 +389,47 @@ export class Hermes {
         await mkdir(hermesHome, { recursive: true });
         await writeFile(pfad, doc.toString());
     }
+    /** Home oder Profil als Hermes-Home (E61): mcp kennt nur diese beiden Orte. */
+    mcpHermesHome(ort) {
+        if (ort.art !== 'home' && ort.art !== 'profil')
+            throw new OrtNichtUnterstuetzt(this.name, ort.art);
+        return this.hermesHome(ort);
+    }
+    async mcpEingehaengte(ort) {
+        return Object.keys(mcpServers(this.gelesen(this.mcpHermesHome(ort))));
+    }
+    /**
+     * Trägt `mcp_servers.<name>` ein (E61). Steht dort schon ein Eintrag, der vom Katalogblock
+     * abweicht (egal, wer ihn gelegt hat), bricht es ab, ohne stillschweigend zu überschreiben; ein
+     * gleicher Eintrag ist idempotent. Kommentare bleiben erhalten.
+     */
+    async mcpEinhaengen(ort, mcpName, konfig) {
+        const hermesHome = this.mcpHermesHome(ort);
+        const pfad = path.join(hermesHome, CONFIG);
+        const text = await readFile(pfad, 'utf8').catch(() => undefined);
+        const doc = text === undefined ? new Document({}) : parseDocument(text);
+        const bestehend = mcpServers(doc.toJS())[mcpName];
+        const wert = mcpKonfigAlsObjekt(konfig);
+        if (bestehend !== undefined && !tiefGleich(bestehend, wert))
+            throw new McpAbweichenderEintrag({ harness: this.name, ort }, mcpName);
+        doc.setIn(['mcp_servers', mcpName], wert);
+        await mkdir(hermesHome, { recursive: true });
+        await writeFile(pfad, doc.toString());
+    }
+    /** Entfernt genau diesen Eintrag aus mcp_servers (E61). Kommentare bleiben erhalten. */
+    async mcpAushaengen(ort, mcpName) {
+        const hermesHome = this.mcpHermesHome(ort);
+        const pfad = path.join(hermesHome, CONFIG);
+        const text = await readFile(pfad, 'utf8').catch(() => undefined);
+        if (text === undefined)
+            return;
+        const doc = parseDocument(text);
+        const mcp = doc.get('mcp_servers');
+        if (!isMap(mcp) || !mcp.has(mcpName))
+            return;
+        mcp.delete(mcpName);
+        await writeFile(pfad, doc.toString());
+    }
     /** Fähigkeit Profile entdecken: Verzeichnisse mit config.yaml, bei jedem Aufruf frisch gelesen (E19). */
     async profile() {
         const basis = path.join(this.home, HERMES_VERZEICHNIS, PROFILE_VERZEICHNIS);