hmgr 0.0.4 → 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,26 +1,42 @@
-// Claude Code: Grundverhalten plus Plugins über die claude-CLI (E16, E24, E27).
-import { execFile } 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 { promisify } from 'node:util';
-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/';
-const ausfuehrenRoh = promisify(execFile);
-/** Standard-Ausführer: `claude` vom PATH. Ein Fehlschlag wird zum Code, nicht zur Ausnahme. */
-export const claudeAusfuehrer = async (args, cwd) => {
-    try {
-        const { stdout } = await ausfuehrenRoh('claude', args, {
-            ...(cwd === undefined ? {} : { cwd }),
-            maxBuffer: 32 * 1024 * 1024,
-        });
-        return { stdout, code: 0 };
-    }
-    catch (fehler) {
-        const f = fehler;
-        return { stdout: `${f.stdout ?? ''}${f.stderr ?? ''}`, code: typeof f.code === 'number' ? f.code : 1 };
-    }
-};
+/**
+ * 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, {
+        ...(cwd === undefined ? {} : { cwd }),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 120_000,
+        killSignal: 'SIGKILL',
+    });
+    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 }));
+    kind.on('close', (code) => aufloesen({ stdout: code === 0 ? stdout : `${stdout}${stderr}`, code: code ?? 1 }));
+});
 export class PluginListeUnbekannteForm extends Error {
     constructor(text) {
         super(`claude plugin list --json: ${text}`);
@@ -139,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

@@ -1,16 +1,59 @@
 // Ziele im Dateisystem: Links legen, lesen und entfernen. Fremde Einträge bleiben unangetastet (E12).
+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, skillName } from "./skill-md.js";
+import { SKILL_DATEI, skillAusPfad } from "./skill-md.js";
+/** Dateien eines Ordners rekursiv, `.git` und `node_modules` ausgenommen, Symlinks nicht gefolgt. */
+async function ordnerDateien(wurzel, unter, ergebnis) {
+    const eintraege = await readdir(path.join(wurzel, unter), { withFileTypes: true }).catch(() => []);
+    for (const eintrag of eintraege) {
+        if (eintrag.name === '.git' || eintrag.name === 'node_modules')
+            continue;
+        const rel = unter ? `${unter}/${eintrag.name}` : eintrag.name;
+        if (eintrag.isDirectory())
+            await ordnerDateien(wurzel, rel, ergebnis);
+        else if (eintrag.isFile())
+            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;
-    constructor(wurzel, zustand) {
+    /** $XDG_STATE_HOME, falls gesetzt und nicht leer, für den vorrangigen Lockfile-Ort (E50). */
+    xdgStateHome;
+    constructor(wurzel, zustand, xdgStateHome) {
         this.wurzel = wurzel;
         this.zustand = zustand;
+        this.xdgStateHome = xdgStateHome;
     }
     async quellen() {
         return (await this.zustand.lesen()).quellen;
@@ -18,12 +61,14 @@ export class DateisystemZiele {
     /**
      * Der Skill hinter einem Linkziel. Der Name kommt aus der SKILL.md am Linkziel, nicht aus dem
      * Namen des Eintrags im Ziel: derselbe Skill soll überall gleich heißen, auch wenn ein Eintrag
-     * von Hand umbenannt wurde (E32).
+     * von Hand umbenannt wurde (E32). Über `skillAusPfad` kommt zugleich die Beschreibung (E39) und
+     * die übrigen Frontmatter-Felder (E55) mit, die die Ziel-Tabellen der GUI zeigen (E60) — vorher
+     * fehlten sie hier, weil nur der Name gelesen wurde. Ein Aufruf, ein Lesen, ein Parsen des
+     * Frontmatters: bei vielen Links summiert sich jedes zweite Parsen derselben Datei.
      */
     async skill(zielPfad, skillPfad, ersatz) {
-        const verzeichnisname = skillPfad.split('/').filter((t) => t.length > 0).at(-1) ?? ersatz;
         const inhalt = await readFile(path.join(zielPfad, SKILL_DATEI), 'utf8').catch(() => undefined);
-        return { name: skillName(verzeichnisname, inhalt), pfad: skillPfad };
+        return skillAusPfad(skillPfad, inhalt, ersatz);
     }
     /** Liest aus dem Linkziel Quelle, Ref und Skill zurück. Undefined heißt: kein eigener Link. */
     async deuten(zielPfad) {
@@ -65,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,
@@ -101,6 +148,10 @@ export class DateisystemZiele {
         return ergebnis;
     }
     async linkLegen(ziel, verzeichnis, name, checkout, skill, ersetzen) {
+        // Ein leerer Name oder einer mit Pfadtrenner ergäbe keinen Eintrag im Ziel, sondern einen Pfad:
+        // `path.join` fiele auf das Zielverzeichnis selbst zurück, und `ersetzen` löschte es (E12, E32).
+        if (name.length === 0 || name.includes('/') || name.includes(path.sep))
+            throw new Error(`Ungültiger Name für einen Link: „${name}"`);
         await mkdir(verzeichnis, { recursive: true });
         const pfad = path.join(verzeichnis, name);
         const info = await lstat(pfad).catch(() => undefined);
@@ -114,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);
@@ -123,4 +184,81 @@ export class DateisystemZiele {
         if (await this.deuten(zielPfad))
             await unlink(path.join(verzeichnis, name));
     }
+    /**
+     * Löscht einen fremden Eintrag von der Platte (E46): ein Symlink wird als Link entfernt, ohne
+     * ihm zu folgen, die Arbeitskopie dahinter bleibt unangetastet; ein Verzeichnis wird rekursiv
+     * gelöscht. Ob der Eintrag tatsächlich fremd ist, hat der Kern schon geprüft.
+     */
+    async eintragLoeschen(_ziel, verzeichnis, name) {
+        const pfad = path.join(verzeichnis, name);
+        const info = await lstat(pfad).catch(() => undefined);
+        if (info === undefined)
+            return;
+        if (info.isSymbolicLink())
+            await unlink(pfad);
+        else
+            await rm(pfad, { recursive: true, force: true });
+    }
+    /**
+     * Lockfile-Kandidaten in Suchreihenfolge (E50): zuerst $XDG_STATE_HOME/skills/.skill-lock.json,
+     * nur wenn die Variable gesetzt und nicht leer ist, sonst wie bisher neben `skillsVerzeichnis`.
+     */
+    lockPfadKandidaten(skillsVerzeichnis) {
+        const kandidaten = [];
+        if (this.xdgStateHome !== undefined && this.xdgStateHome.length > 0)
+            kandidaten.push(path.join(this.xdgStateHome, 'skills', '.skill-lock.json'));
+        kandidaten.push(path.join(path.dirname(skillsVerzeichnis), '.skill-lock.json'));
+        return kandidaten;
+    }
+    /** Eintrag zu `name` aus dem Lockfile-Inhalt. Kaputtes JSON oder fehlende Felder: undefined. */
+    lockEintragAusInhalt(roh, name) {
+        try {
+            const geparst = JSON.parse(ohneBom(roh));
+            const eintrag = geparst.skills?.[name];
+            if (eintrag === undefined)
+                return undefined;
+            const sourceUrl = eintrag.sourceUrl;
+            const skillFolderHash = eintrag.skillFolderHash;
+            if (typeof sourceUrl !== 'string' || typeof skillFolderHash !== 'string')
+                return undefined;
+            const ref = eintrag.ref;
+            const skillPath = eintrag.skillPath;
+            return {
+                sourceUrl,
+                skillFolderHash,
+                ...(typeof ref === 'string' ? { ref } : {}),
+                ...(typeof skillPath === 'string' ? { skillPath } : {}),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Lockfile der skills-CLI (E48 b, E50, HARNESS-FAKTEN). Fehlt die Datei am ersten Kandidaten,
+     * wird der nächste versucht; ist sie da, aber kein gültiges JSON oder trägt der Eintrag nicht die
+     * nötigen Felder, gibt es undefined zurück statt zu werfen: ein kaputtes Lockfile bricht die
+     * Erhebung nicht ab.
+     */
+    async skillLockEintrag(skillsVerzeichnis, name) {
+        for (const lockPfad of this.lockPfadKandidaten(skillsVerzeichnis)) {
+            const roh = await readFile(lockPfad, 'utf8').catch(() => undefined);
+            if (roh === undefined)
+                continue;
+            return this.lockEintragAusInhalt(roh, name);
+        }
+        return undefined;
+    }
+    /** SHA-256 über relativen Pfad und Inhalt aller Dateien, wie `computeSkillFolderHash` (E48 b). */
+    async ordnerHash(verzeichnis, name) {
+        const dateien = [];
+        await ordnerDateien(path.join(verzeichnis, name), '', dateien);
+        dateien.sort((a, b) => a.relativerPfad.localeCompare(b.relativerPfad));
+        const hash = createHash('sha256');
+        for (const datei of dateien) {
+            hash.update(datei.relativerPfad);
+            hash.update(datei.inhalt);
+        }
+        return hash.digest('hex');
+    }
 }