hmgr 0.0.1

package/dist/kern/anwendungsfaelle.js

@@ -0,0 +1,683 @@
+// Anwendungsfälle. Pfade werden hier nur als Zeichenketten normalisiert, gelesen wird über die Ports.
+import path from 'node:path';
+import { AbhaengigkeitFehlt, EinschraenkungOhneZeiger, HarnessNichtVorhanden, KeinPassenderRef, OrtNichtUnterstuetzt, PluginMehrdeutig, PluginUnbekannt, SkillMehrdeutig, SkillUnbekannt, ZeigerMehrdeutig, marketplaceUrl, pluginSchluessel, pluginSchluesselZerlegen, quelleSchluessel, zielSchluessel, } from "./modell.js";
+import { passenderRef } from "./version.js";
+import { kannPlugins, kannProfile } from "../ports/harness.js";
+function arbeitsverzeichnisZiel(harness, pfad) {
+    return { harness, ort: { art: 'arbeitsverzeichnis', pfad } };
+}
+function fehlertext(fehler) {
+    return fehler instanceof Error ? fehler.message : String(fehler);
+}
+export class Anwendungsfaelle {
+    p;
+    constructor(p) {
+        this.p = p;
+    }
+    harness(name) {
+        const h = this.p.harnesses.find((h) => h.name === name);
+        if (!h)
+            throw new Error(`Unbekannter Harness „${name}"`);
+        return h;
+    }
+    /** Ein namentlich genannter Harness muss auf dem Rechner liegen, sonst passiert nichts Stilles. */
+    async harnessGeprueft(name) {
+        const h = this.harness(name);
+        if (!(await h.vorhanden()))
+            throw new HarnessNichtVorhanden(name);
+        return h;
+    }
+    /** Harnesses, die auf dem Rechner liegen. Alle anderen überspringt hmgr. */
+    async vorhandeneHarnesses() {
+        const ergebnis = [];
+        for (const harness of this.p.harnesses)
+            if (await harness.vorhanden())
+                ergebnis.push(harness);
+        return ergebnis;
+    }
+    /** Namen der Harnesses, die nicht auf dem Rechner liegen. Für die Ausgabe von `status`. */
+    async nichtVorhandeneHarnesses() {
+        const ergebnis = [];
+        for (const harness of this.p.harnesses)
+            if (!(await harness.vorhanden()))
+                ergebnis.push(harness.name);
+        return ergebnis;
+    }
+    /** Quelle hinzufügen: prüft, dass sie erreichbar ist, und liest Skills und Marketplace (E24). */
+    async quelleHinzufuegen(quelle) {
+        const ref = await this.p.quellen.standardRef(quelle);
+        const skills = await this.p.quellen.skills(quelle, ref);
+        const marketplace = await this.p.quellen.marketplace(quelle, ref);
+        const zustand = await this.p.zustand.lesen();
+        const key = quelleSchluessel(quelle);
+        if (!zustand.quellen.some((q) => quelleSchluessel(q) === key)) {
+            zustand.quellen.push(quelle);
+            await this.p.zustand.schreiben(zustand);
+        }
+        return { skills, marketplace };
+    }
+    /** Marketplace einer Quelle am Standard-Ref, mit den Plugins als Modellwerte. */
+    async marketplaceLesen(quelle) {
+        const ref = await this.p.quellen.standardRef(quelle);
+        const beschreibung = await this.p.quellen.marketplace(quelle, ref);
+        if (beschreibung === null)
+            return null;
+        return {
+            ref,
+            name: beschreibung.name,
+            plugins: beschreibung.plugins.map((p) => ({
+                name: p.name,
+                marketplace: beschreibung.name,
+                skills: p.skills,
+                dependencies: p.dependencies,
+            })),
+        };
+    }
+    /** Alle Marketplaces der bekannten Quellen, für `hmgr plugin list`. */
+    async marketplaces() {
+        const zustand = await this.p.zustand.lesen();
+        const ergebnis = [];
+        for (const quelle of zustand.quellen) {
+            const gelesen = await this.marketplaceLesen(quelle);
+            if (gelesen === null)
+                continue;
+            ergebnis.push({ quelle, name: gelesen.name, plugins: gelesen.plugins });
+        }
+        return ergebnis;
+    }
+    /**
+     * Plugin über die Marketplaces aller bekannten Quellen suchen. Mehrere Treffer sind nur mit
+     * Quellenhinweis erlaubt, wie bei Skills (E12). `marketplace` grenzt zusätzlich ein.
+     */
+    async pluginFinden(name, quelleHinweis, marketplace) {
+        const zustand = await this.p.zustand.lesen();
+        const funde = [];
+        for (const quelle of zustand.quellen) {
+            if (quelleHinweis && !quelleSchluessel(quelle).includes(quelleHinweis))
+                continue;
+            const gelesen = await this.marketplaceLesen(quelle).catch(() => null);
+            if (gelesen === null)
+                continue;
+            for (const plugin of gelesen.plugins) {
+                if (plugin.name !== name)
+                    continue;
+                if (marketplace !== undefined && plugin.marketplace !== marketplace)
+                    continue;
+                funde.push({ quelle, ref: gelesen.ref, plugin });
+            }
+        }
+        if (funde.length === 0)
+            throw new PluginUnbekannt(name);
+        if (funde.length > 1)
+            throw new PluginMehrdeutig(name, funde.map((f) => f.quelle));
+        return funde[0];
+    }
+    /**
+     * Flache Skill-Liste (B5): das Plugin plus alle Abhängigkeiten, rekursiv im selben Marketplace,
+     * ohne Dubletten. Ein Zyklus wird abgefangen, ein Plugin kommt nur einmal vor.
+     */
+    async flacheSkillListe(pluginName, quelle) {
+        const gelesen = await this.marketplaceLesen(quelle);
+        if (gelesen === null)
+            throw new PluginUnbekannt(pluginName);
+        const nachName = new Map(gelesen.plugins.map((p) => [p.name, p]));
+        if (!nachName.has(pluginName))
+            throw new PluginUnbekannt(pluginName);
+        const gesehen = new Set();
+        const skills = [];
+        const pfade = new Set();
+        const offen = [pluginName];
+        while (offen.length > 0) {
+            const name = offen.shift();
+            if (gesehen.has(name))
+                continue; // Zyklus oder Dublette
+            gesehen.add(name);
+            const plugin = nachName.get(name);
+            if (plugin === undefined)
+                throw new AbhaengigkeitFehlt(pluginName, name);
+            for (const skill of plugin.skills)
+                if (!pfade.has(skill.pfad)) {
+                    pfade.add(skill.pfad);
+                    skills.push(skill);
+                }
+            offen.push(...plugin.dependencies);
+        }
+        return skills;
+    }
+    /**
+     * Arbeitsverzeichnis hinzufügen (E21, E26): Zeiger suchen, Bindung je vorhandenem Harness merken.
+     * Kein Zeiger heißt: Verzeichnis merken, keine Bindung, Hinweis. Mehrdeutig heißt: Fehler,
+     * es sei denn, der Nutzer nennt eine composer.json. Nie Zufall.
+     */
+    async arbeitsverzeichnisHinzufuegen(pfad, composerPfad) {
+        const verzeichnis = path.resolve(pfad);
+        let zeigerPfad;
+        let hinweis;
+        // Eine schon gemerkte Bindung gewinnt, sonst würde ein zweiter Aufruf erneut mehrdeutig werden.
+        const bekannt = await this.bindungFuerVerzeichnis(verzeichnis);
+        if (composerPfad !== undefined) {
+            zeigerPfad = path.resolve(composerPfad);
+        }
+        else if (bekannt !== undefined) {
+            zeigerPfad = bekannt;
+        }
+        else {
+            const fund = await this.p.zeiger.finden(verzeichnis);
+            if (fund.ergebnis === 'gefunden')
+                zeigerPfad = fund.pfad;
+            else if (fund.ergebnis === 'mehrdeutig')
+                throw new ZeigerMehrdeutig(verzeichnis, fund.kandidaten);
+            else
+                hinweis = `Kein Zeiger unter ${verzeichnis}, alles bleibt lokal (E26).`;
+        }
+        const zustand = await this.p.zustand.lesen();
+        if (!zustand.arbeitsverzeichnisse.includes(verzeichnis))
+            zustand.arbeitsverzeichnisse.push(verzeichnis);
+        if (zeigerPfad !== undefined) {
+            const gebunden = zeigerPfad;
+            for (const harness of await this.vorhandeneHarnesses()) {
+                if (!harness.orte().includes('arbeitsverzeichnis'))
+                    continue;
+                const ziel = arbeitsverzeichnisZiel(harness.name, verzeichnis);
+                const schluessel = zielSchluessel(ziel);
+                zustand.bindungen = zustand.bindungen.filter((b) => zielSchluessel(b.ziel) !== schluessel);
+                zustand.bindungen.push({ ziel, zeigerPfad: gebunden });
+            }
+        }
+        await this.p.zustand.schreiben(zustand);
+        return {
+            pfad: verzeichnis,
+            ...(zeigerPfad === undefined ? {} : { zeigerPfad }),
+            ...(hinweis === undefined ? {} : { hinweis }),
+        };
+    }
+    /** Arbeitsverzeichnis vergessen: Verzeichnis und Bindungen weg, die Links bleiben liegen (E26). */
+    async arbeitsverzeichnisVergessen(pfad) {
+        const verzeichnis = path.resolve(pfad);
+        const zustand = await this.p.zustand.lesen();
+        zustand.arbeitsverzeichnisse = zustand.arbeitsverzeichnisse.filter((p) => p !== verzeichnis);
+        zustand.bindungen = zustand.bindungen.filter((b) => !(b.ziel.ort.art === 'arbeitsverzeichnis' && b.ziel.ort.pfad === verzeichnis));
+        await this.p.zustand.schreiben(zustand);
+    }
+    /** Zeiger eines Arbeitsverzeichnisses aus dem Zustand, egal für welchen Harness (E26). */
+    async bindungFuerVerzeichnis(verzeichnis) {
+        const zustand = await this.p.zustand.lesen();
+        return zustand.bindungen.find((b) => b.ziel.ort.art === 'arbeitsverzeichnis' && b.ziel.ort.pfad === verzeichnis)?.zeigerPfad;
+    }
+    /** Zeiger eines Ziels aus dem Zustand. Undefined heißt: keine Bindung. */
+    async bindungFinden(ziel) {
+        const schluessel = zielSchluessel(ziel);
+        const zustand = await this.p.zustand.lesen();
+        return zustand.bindungen.find((b) => zielSchluessel(b.ziel) === schluessel)?.zeigerPfad;
+    }
+    /** Skill über alle Quellen suchen. Mehrere Treffer sind nur mit Quellenhinweis erlaubt. */
+    async skillFinden(name, quelleHinweis) {
+        const zustand = await this.p.zustand.lesen();
+        const funde = [];
+        for (const quelle of zustand.quellen) {
+            if (quelleHinweis && !quelleSchluessel(quelle).includes(quelleHinweis))
+                continue;
+            const ref = await this.p.quellen.standardRef(quelle);
+            const skills = await this.p.quellen.skills(quelle, ref);
+            for (const skill of skills)
+                if (skill.name === name)
+                    funde.push({ quelle, ref, skill });
+        }
+        if (funde.length === 0)
+            throw new SkillUnbekannt(name);
+        if (funde.length > 1)
+            throw new SkillMehrdeutig(name, funde.map((f) => f.quelle));
+        return funde[0];
+    }
+    /** Checkout anlegen oder erweitern, Ziel vorbereiten, Link setzen. Ohne Zeiger-Arbeit. */
+    async linkAnlegen(harness, ziel, fund, ersetzen) {
+        if (!harness.orte().includes(ziel.ort.art))
+            throw new OrtNichtUnterstuetzt(harness.name, ziel.ort.art);
+        const verzeichnis = harness.zielVerzeichnis(ziel.ort);
+        // Die Prüfung auf einen fremden Eintrag macht der Ziele-Port unmittelbar vor dem Anlegen (E12).
+        const checkout = await this.p.quellen.checkout(fund.quelle, fund.ref, [fund.skill]);
+        await harness.vorbereiten(ziel.ort);
+        await this.p.ziele.linkLegen(ziel, verzeichnis, fund.skill.name, checkout, fund.skill, ersetzen);
+        return { ziel, name: fund.skill.name, checkout, skill: fund.skill };
+    }
+    /**
+     * Quelle und Skill in den Zeiger schreiben, dann das Composer-Script sichern (E17, E20, E25).
+     * Eine genannte Einschränkung ersetzt die bisherige, ohne Einschränkung bleibt ein vorhandener
+     * Eintrag stehen.
+     */
+    async zeigerErgaenzen(zeigerPfad, fund, einschraenkung) {
+        const zeiger = await this.p.zeiger.lesen(zeigerPfad);
+        const key = quelleSchluessel(fund.quelle);
+        if (!zeiger.quellen.some((q) => quelleSchluessel(q) === key))
+            zeiger.quellen.push(fund.quelle);
+        if (einschraenkung !== undefined)
+            zeiger.skills.set(fund.skill.name, einschraenkung);
+        else if (!zeiger.skills.has(fund.skill.name))
+            zeiger.skills.set(fund.skill.name, null);
+        await this.p.zeiger.schreiben(zeigerPfad, zeiger);
+        await this.p.zeiger.scriptEintragen(zeigerPfad);
+    }
+    /**
+     * Link legen. In ein Arbeitsverzeichnis ist der Link standardmäßig geteilt und landet im Zeiger
+     * (E17). `lokal` unterdrückt das, für Home und Profil gibt es keinen Zeiger. Eine
+     * Versionseinschränkung wird sofort aufgelöst und in den Zeiger geschrieben (E33), ohne Zeiger
+     * hätte sie keinen Platz und der Aufruf schlägt fehl.
+     */
+    async linkLegen(args) {
+        const harness = await this.harnessGeprueft(args.ziel.harness);
+        if (!harness.orte().includes(args.ziel.ort.art))
+            throw new OrtNichtUnterstuetzt(harness.name, args.ziel.ort.art);
+        const version = args.version;
+        if (version === undefined) {
+            const fund = await this.skillFinden(args.skill, args.quelle);
+            return await this.linkAusFund(harness, args.ziel, fund, args.ersetzen, args.lokal);
+        }
+        if (args.lokal === true || args.ziel.ort.art !== 'arbeitsverzeichnis')
+            throw new EinschraenkungOhneZeiger(args.ziel, version);
+        const zeigerPfad = await this.bindungFinden(args.ziel);
+        if (zeigerPfad === undefined)
+            throw new EinschraenkungOhneZeiger(args.ziel, version);
+        const fund = await this.fundAusZeiger(args.skill, version, args.quelle);
+        const link = await this.linkAnlegen(harness, args.ziel, fund, args.ersetzen);
+        await this.zeigerErgaenzen(zeigerPfad, fund, version);
+        return link;
+    }
+    /** Link legen, wenn Quelle, Ref und Skill schon feststehen. Die Zeiger-Arbeit ist dieselbe. */
+    async linkAusFund(harness, ziel, fund, ersetzen, lokal) {
+        const link = await this.linkAnlegen(harness, ziel, fund, ersetzen);
+        if (lokal === true || ziel.ort.art !== 'arbeitsverzeichnis')
+            return link;
+        const zeigerPfad = await this.bindungFinden(ziel);
+        // Ziel ohne Zeiger: der Link wird trotzdem gelegt, hmgr weist darauf hin (E26).
+        if (zeigerPfad === undefined)
+            return { ...link, hinweis: `Ohne Zeiger bleibt „${link.name}" lokal, der Link ist gelegt (E26).` };
+        await this.zeigerErgaenzen(zeigerPfad, fund);
+        return link;
+    }
+    /** Link entfernen. Ohne `lokal` verschwindet der Skill auch aus dem Zeiger (E17). */
+    async linkEntfernen(args) {
+        const harness = await this.harnessGeprueft(args.ziel.harness);
+        await this.p.ziele.linkEntfernen(args.ziel, harness.zielVerzeichnis(args.ziel.ort), args.skill);
+        if (args.lokal === true || args.ziel.ort.art !== 'arbeitsverzeichnis')
+            return;
+        const zeigerPfad = await this.bindungFinden(args.ziel);
+        if (zeigerPfad === undefined)
+            return;
+        const zeiger = await this.p.zeiger.lesen(zeigerPfad);
+        if (!zeiger.skills.delete(args.skill))
+            return;
+        await this.p.zeiger.schreiben(zeigerPfad, zeiger);
+    }
+    /**
+     * Plugin an einem Ziel herstellen: mit Plugin-Fähigkeit über die CLI des Harness, sonst als
+     * flache Skill-Liste (E16, B5). Der Zeiger wird hier nicht angefasst.
+     */
+    async pluginHerstellen(harness, ziel, fund) {
+        if (!harness.orte().includes(ziel.ort.art))
+            throw new OrtNichtUnterstuetzt(harness.name, ziel.ort.art);
+        if (kannPlugins(harness)) {
+            if (!(await harness.plugins.marketplaceBekannt(fund.plugin.marketplace)))
+                await harness.plugins.marketplaceHinzufuegen(fund.plugin.marketplace, marketplaceUrl(fund.quelle));
+            await harness.vorbereiten(ziel.ort);
+            await harness.plugins.installieren(fund.plugin.name, fund.plugin.marketplace, ziel);
+            return { plugin: fund.plugin, art: 'installiert', skills: [], imZeiger: false };
+        }
+        const skills = await this.flacheSkillListe(fund.plugin.name, fund.quelle);
+        for (const skill of skills)
+            await this.linkAnlegen(harness, ziel, { quelle: fund.quelle, ref: fund.ref, skill });
+        return { plugin: fund.plugin, art: 'verlinkt', skills: skills.map((s) => s.name), imZeiger: false };
+    }
+    /**
+     * Plugin legen (E16, E17, E24, E27). In ein Arbeitsverzeichnis mit Zeiger ist das Plugin
+     * standardmäßig geteilt: in den Zeiger kommt das Plugin, nicht seine Einzelskills.
+     */
+    async pluginLegen(args) {
+        const harness = await this.harnessGeprueft(args.ziel.harness);
+        const fund = await this.pluginFinden(args.plugin, args.quelle);
+        const ergebnis = await this.pluginHerstellen(harness, args.ziel, fund);
+        if (args.lokal === true || args.ziel.ort.art !== 'arbeitsverzeichnis')
+            return ergebnis;
+        const zeigerPfad = await this.bindungFinden(args.ziel);
+        if (zeigerPfad === undefined)
+            return { ...ergebnis, hinweis: `Ohne Zeiger bleibt „${args.plugin}" lokal, das Plugin liegt am Ziel (E26).` };
+        const zeiger = await this.p.zeiger.lesen(zeigerPfad);
+        const key = quelleSchluessel(fund.quelle);
+        if (!zeiger.quellen.some((q) => quelleSchluessel(q) === key))
+            zeiger.quellen.push(fund.quelle);
+        const schluessel = pluginSchluessel(fund.plugin);
+        if (!zeiger.plugins.includes(schluessel))
+            zeiger.plugins.push(schluessel);
+        await this.p.zeiger.schreiben(zeigerPfad, zeiger);
+        await this.p.zeiger.scriptEintragen(zeigerPfad);
+        return { ...ergebnis, imZeiger: true };
+    }
+    /**
+     * Namen der Skills, die andere am Ziel liegende Plugins brauchen. Quellen sind der Zeiger und,
+     * bei einem Harness mit Plugin-Fähigkeit, die installierten Plugins.
+     */
+    async fremdeSkillNamen(harness, ziel, ausser) {
+        const schluessel = new Set();
+        const zeigerPfad = await this.bindungFinden(ziel);
+        if (zeigerPfad !== undefined)
+            for (const eintrag of (await this.p.zeiger.lesen(zeigerPfad)).plugins)
+                schluessel.add(eintrag);
+        if (kannPlugins(harness))
+            for (const eintrag of await harness.plugins.installierte(ziel).catch(() => []))
+                schluessel.add(eintrag);
+        schluessel.delete(ausser);
+        const namen = new Set();
+        for (const eintrag of schluessel) {
+            const zerlegt = pluginSchluesselZerlegen(eintrag);
+            const fund = await this.pluginFinden(zerlegt.name, undefined, zerlegt.marketplace).catch(() => undefined);
+            if (fund === undefined)
+                continue;
+            const skills = await this.flacheSkillListe(fund.plugin.name, fund.quelle).catch(() => []);
+            for (const skill of skills)
+                namen.add(skill.name);
+        }
+        return namen;
+    }
+    /** Plugin entfernen. Gegenstück zu `pluginLegen`. */
+    async pluginEntfernen(args) {
+        const harness = await this.harnessGeprueft(args.ziel.harness);
+        const fund = await this.pluginFinden(args.plugin);
+        const schluessel = pluginSchluessel(fund.plugin);
+        const entfernt = [];
+        if (kannPlugins(harness)) {
+            await harness.plugins.entfernen(fund.plugin.name, fund.plugin.marketplace, args.ziel);
+        }
+        else {
+            // Ein Skill bleibt liegen, wenn ihn ein anderes Plugin am selben Ziel braucht.
+            const gebraucht = await this.fremdeSkillNamen(harness, args.ziel, schluessel);
+            const verzeichnis = harness.zielVerzeichnis(args.ziel.ort);
+            for (const skill of await this.flacheSkillListe(fund.plugin.name, fund.quelle)) {
+                if (gebraucht.has(skill.name))
+                    continue;
+                await this.p.ziele.linkEntfernen(args.ziel, verzeichnis, skill.name);
+                entfernt.push(skill.name);
+            }
+        }
+        const ergebnis = {
+            plugin: fund.plugin,
+            art: kannPlugins(harness) ? 'installiert' : 'verlinkt',
+            skills: entfernt,
+            imZeiger: false,
+        };
+        if (args.lokal === true || args.ziel.ort.art !== 'arbeitsverzeichnis')
+            return ergebnis;
+        const zeigerPfad = await this.bindungFinden(args.ziel);
+        if (zeigerPfad === undefined)
+            return ergebnis;
+        const zeiger = await this.p.zeiger.lesen(zeigerPfad);
+        const vorher = zeiger.plugins.length;
+        zeiger.plugins = zeiger.plugins.filter((p) => p !== schluessel);
+        if (zeiger.plugins.length === vorher)
+            return ergebnis;
+        await this.p.zeiger.schreiben(zeigerPfad, zeiger);
+        return { ...ergebnis, imZeiger: true };
+    }
+    /**
+     * Fund zu einem Skill aus dem Zeiger (E33). Die Einschränkung wird zuerst nach Composer-Regeln
+     * gegen die Tags der Quellen ausgewertet, der höchste passende Tag gewinnt. Findet sich keiner,
+     * gilt der Text als genauer Ref-Name gegen alle Refs, damit Tags und Branches ohne
+     * Versions-Schema erreichbar bleiben. Nie auf den Standard-Ref ausweichen (B8).
+     */
+    async fundAusZeiger(name, einschraenkung, quelleHinweis) {
+        if (einschraenkung === null)
+            return await this.skillFinden(name, quelleHinweis);
+        const zustand = await this.p.zustand.lesen();
+        const quellen = zustand.quellen.filter((q) => quelleHinweis === undefined || quelleSchluessel(q).includes(quelleHinweis));
+        for (const quelle of quellen) {
+            const tags = await this.p.quellen.tags(quelle).catch(() => []);
+            const ref = passenderRef(tags, einschraenkung);
+            if (ref === null)
+                continue;
+            const skill = (await this.p.quellen.skills(quelle, ref)).find((s) => s.name === name);
+            if (skill)
+                return { quelle, ref, skill };
+        }
+        for (const quelle of quellen) {
+            const refs = await this.p.quellen.refs(quelle).catch(() => []);
+            if (!refs.includes(einschraenkung))
+                continue;
+            const skill = (await this.p.quellen.skills(quelle, einschraenkung)).find((s) => s.name === name);
+            if (skill)
+                return { quelle, ref: einschraenkung, skill };
+        }
+        throw new KeinPassenderRef(name, einschraenkung);
+    }
+    /**
+     * Abgleich (E20, E25, E26): Zeiger des Verzeichnisses lesen, fehlende Quellen übernehmen,
+     * fehlende Links legen, Abweichungen melden. Ohne Zeiger oder ohne Harness passiert nichts.
+     */
+    async abgleich(pfad) {
+        const verzeichnis = path.resolve(pfad ?? process.cwd());
+        const ergebnis = { gelegt: [], vorhanden: [], abweichend: [], fehler: [], hinweise: [] };
+        const zustand = await this.p.zustand.lesen();
+        // Zeiger nach E26: erst die gemerkte Bindung, dann die Suche im Verzeichnis.
+        let zeigerPfad = await this.bindungFuerVerzeichnis(verzeichnis);
+        if (zeigerPfad === undefined) {
+            const fund = await this.p.zeiger.finden(verzeichnis);
+            if (fund.ergebnis === 'gefunden')
+                zeigerPfad = fund.pfad;
+            else if (fund.ergebnis === 'mehrdeutig')
+                throw new ZeigerMehrdeutig(verzeichnis, fund.kandidaten);
+        }
+        if (zeigerPfad === undefined) {
+            ergebnis.hinweise.push(`Kein Zeiger unter ${verzeichnis}, nichts zu tun.`);
+            return ergebnis;
+        }
+        ergebnis.zeigerPfad = zeigerPfad;
+        const harnesses = (await this.vorhandeneHarnesses()).filter((h) => h.orte().includes('arbeitsverzeichnis'));
+        if (harnesses.length === 0) {
+            ergebnis.hinweise.push('Kein Harness auf diesem Rechner, nichts zu tun (E20).');
+            return ergebnis;
+        }
+        const zeiger = await this.p.zeiger.lesen(zeigerPfad);
+        for (const quelle of zeiger.quellen) {
+            const key = quelleSchluessel(quelle);
+            if (zustand.quellen.some((q) => quelleSchluessel(q) === key))
+                continue;
+            zustand.quellen.push(quelle);
+            ergebnis.gelegt.push(`Quelle ${key}`);
+        }
+        if (!zustand.arbeitsverzeichnisse.includes(verzeichnis))
+            zustand.arbeitsverzeichnisse.push(verzeichnis);
+        for (const harness of harnesses) {
+            const ziel = arbeitsverzeichnisZiel(harness.name, verzeichnis);
+            const schluessel = zielSchluessel(ziel);
+            if (zustand.bindungen.some((b) => zielSchluessel(b.ziel) === schluessel))
+                continue;
+            zustand.bindungen.push({ ziel, zeigerPfad });
+        }
+        // Vor dem ersten Link schreiben, damit Quellen und Bindung für die Ports sichtbar sind.
+        await this.p.zustand.schreiben(zustand);
+        for (const harness of harnesses) {
+            const ziel = arbeitsverzeichnisZiel(harness.name, verzeichnis);
+            const zielVerzeichnis = harness.zielVerzeichnis(ziel.ort);
+            const eintraege = await this.p.ziele.eintraege(ziel, zielVerzeichnis).catch(() => []);
+            // Skills, die über ein Plugin des Zeigers ans Ziel kommen, sind keine Abweichung.
+            const ausPlugins = new Set();
+            for (const eintrag of zeiger.plugins) {
+                const zerlegt = pluginSchluesselZerlegen(eintrag);
+                try {
+                    const fund = await this.pluginFinden(zerlegt.name, undefined, zerlegt.marketplace);
+                    for (const skill of await this.flacheSkillListe(fund.plugin.name, fund.quelle))
+                        ausPlugins.add(skill.name);
+                    if (await this.pluginLiegt(harness, ziel, fund, eintraege)) {
+                        ergebnis.vorhanden.push(`${harness.name}: Plugin ${eintrag}`);
+                        continue;
+                    }
+                    await this.pluginHerstellen(harness, ziel, fund);
+                    ergebnis.gelegt.push(`${harness.name}: Plugin ${eintrag}`);
+                }
+                catch (fehler) {
+                    ergebnis.fehler.push(`${harness.name}: Plugin ${eintrag}: ${fehlertext(fehler)}`);
+                }
+            }
+            for (const [name, einschraenkung] of zeiger.skills) {
+                try {
+                    const fund = await this.fundAusZeiger(name, einschraenkung);
+                    const gefunden = eintraege.find((e) => e.art === 'link' && e.link.name === name);
+                    // Ein eigener Link auf einen anderen Ref weicht ab und wird umgelegt (E33). Das trifft
+                    // die Einschränkung, die inzwischen einen höheren Tag findet.
+                    const alt = gefunden?.art === 'link' ? gefunden.link.checkout.ref : undefined;
+                    if (alt === fund.ref) {
+                        ergebnis.vorhanden.push(`${harness.name}: ${name}`);
+                        continue;
+                    }
+                    await this.linkAnlegen(harness, ziel, fund);
+                    ergebnis.gelegt.push(alt === undefined ? `${harness.name}: ${name}` : `${harness.name}: ${name} (${alt} → ${fund.ref})`);
+                }
+                catch (fehler) {
+                    ergebnis.fehler.push(`${harness.name}: ${name}: ${fehlertext(fehler)}`);
+                }
+            }
+            // Eigene Links, die im Zeiger fehlen, werden gemeldet und nicht entfernt. Fremde bleiben unberührt.
+            for (const eintrag of eintraege) {
+                const name = eintrag.art === 'fremd' ? undefined : eintrag.art === 'link' ? eintrag.link.name : eintrag.name;
+                if (name === undefined || zeiger.skills.has(name) || ausPlugins.has(name))
+                    continue;
+                ergebnis.abweichend.push(`${harness.name}: ${name} steht nicht im Zeiger`);
+            }
+        }
+        return ergebnis;
+    }
+    /** Liegt das Plugin schon am Ziel: installiert, oder mit allen Skills der flachen Liste verlinkt. */
+    async pluginLiegt(harness, ziel, fund, eintraege) {
+        if (kannPlugins(harness)) {
+            const installiert = await harness.plugins.installierte(ziel).catch(() => []);
+            return installiert.includes(pluginSchluessel(fund.plugin));
+        }
+        const namen = new Set(eintraege.map((e) => (e.art === 'link' ? e.link.name : e.art === 'fremd' ? e.name : e.name)));
+        const skills = await this.flacheSkillListe(fund.plugin.name, fund.quelle);
+        return skills.length > 0 && skills.every((s) => namen.has(s.name));
+    }
+    /**
+     * Aktualisieren (E14, E15): jeden Checkout unter der Wurzel auf den Stand seines Refs bringen.
+     * Lokale Quellen haben keinen Checkout und bleiben unberührt (B11). Links zeigen auf die
+     * Worktree-Pfade, die dabei stehen bleiben, also müssen sie nicht erneuert werden.
+     */
+    async aktualisieren() {
+        const checkouts = [];
+        for (const checkout of await this.p.quellen.checkouts())
+            checkouts.push({ checkout, aktualisierung: await this.p.quellen.aktualisieren(checkout) });
+        // Nach den Checkouts die Plugins nachziehen (E14).
+        const pluginHarnesses = [];
+        for (const harness of await this.vorhandeneHarnesses()) {
+            if (!kannPlugins(harness))
+                continue;
+            await harness.plugins.aktualisieren();
+            pluginHarnesses.push(harness.name);
+        }
+        return { checkouts, pluginHarnesses };
+    }
+    /**
+     * Übernahme (B12, E31): fremde Symlinks eines Ziels durch eigene Links auf einen hmgr-Checkout
+     * derselben Quelle am selben Ref ersetzen. Die Arbeitskopie bleibt unberührt und wird nicht als
+     * Quelle registriert, das ist B11. Ein Eintrag, der nicht auflösbar ist, bleibt liegen und wird
+     * gemeldet, damit ein Lauf über viele Einträge nicht an einem einzelnen abbricht.
+     *
+     * `probelauf` schreibt weder Zustand noch Checkout noch Link. Die Skill-Liste der Quelle wird
+     * trotzdem gelesen, sonst wäre der Grund „skill-unbekannt" nicht zu haben. Der Git-Adapter legt
+     * dabei den Basis-Clone der Quelle an, das Ziel und der Zustand bleiben unangetastet.
+     */
+    async uebernehmen(args) {
+        const harness = await this.harnessGeprueft(args.ziel.harness);
+        if (!harness.orte().includes(args.ziel.ort.art))
+            throw new OrtNichtUnterstuetzt(harness.name, args.ziel.ort.art);
+        const probelauf = args.probelauf === true;
+        const verzeichnis = harness.zielVerzeichnis(args.ziel.ort);
+        const bekannt = new Set((await this.p.zustand.lesen()).quellen.map(quelleSchluessel));
+        const eintraege = [];
+        for (const eintrag of await this.p.ziele.eintraege(args.ziel, verzeichnis)) {
+            // Eigene Links sind schon fertig, sie kommen nicht in die Meldung.
+            if (eintrag.art !== 'fremd')
+                continue;
+            if (args.name !== undefined && eintrag.name !== args.name)
+                continue;
+            const name = eintrag.name;
+            const liegenLassen = (grund) => void eintraege.push({ ergebnis: 'uebersprungen', name, grund });
+            if (eintrag.linkZiel === undefined) {
+                liegenLassen('kein-link');
+                continue;
+            }
+            const kopie = await this.p.quellen.arbeitskopie(eintrag.linkZiel);
+            if (kopie === null) {
+                liegenLassen('keine-arbeitskopie');
+                continue;
+            }
+            if (kopie.url === null) {
+                liegenLassen('keine-url');
+                continue;
+            }
+            // Ohne Branch gibt es keinen Ref, auf den ein Checkout zeigen könnte (detached HEAD).
+            if (kopie.ref === null) {
+                liegenLassen('kein-branch');
+                continue;
+            }
+            const quelle = { art: 'git', url: kopie.url };
+            const ref = kopie.ref;
+            const skills = await this.p.quellen.skills(quelle, ref);
+            const skill = skills.find((s) => s.pfad === kopie.relativerPfad);
+            if (skill === undefined) {
+                liegenLassen('skill-unbekannt');
+                continue;
+            }
+            const quelleNeu = !bekannt.has(quelleSchluessel(quelle));
+            bekannt.add(quelleSchluessel(quelle));
+            if (!probelauf) {
+                if (quelleNeu)
+                    await this.quelleHinzufuegen(quelle);
+                await this.linkAusFund(harness, args.ziel, { quelle, ref, skill }, true, args.lokal);
+            }
+            eintraege.push({ ergebnis: 'uebernommen', name, quelle, ref, skill, quelleNeu });
+        }
+        return { ziel: args.ziel, probelauf, eintraege };
+    }
+    /** Versionseinschränkungen des Zeigers, an den ein Ziel gebunden ist (E33). Ohne Zeiger leer. */
+    async einschraenkungen(ziel) {
+        const ergebnis = new Map();
+        const zeigerPfad = await this.bindungFinden(ziel);
+        if (zeigerPfad === undefined)
+            return ergebnis;
+        const zeiger = await this.p.zeiger.lesen(zeigerPfad).catch(() => undefined);
+        if (zeiger === undefined)
+            return ergebnis;
+        for (const [name, einschraenkung] of zeiger.skills)
+            if (einschraenkung !== null)
+                ergebnis.set(name, einschraenkung);
+        return ergebnis;
+    }
+    /** Ist-Zustand: alle Ziele der vorhandenen Harnesses, aus dem Dateisystem gelesen. */
+    async istZustand() {
+        const zustand = await this.p.zustand.lesen();
+        const ergebnis = [];
+        for (const harness of await this.vorhandeneHarnesses()) {
+            const ziele = [];
+            if (harness.orte().includes('home'))
+                ziele.push({ harness: harness.name, ort: { art: 'home' } });
+            if (harness.orte().includes('profil') && kannProfile(harness))
+                for (const name of await harness.profile())
+                    ziele.push({ harness: harness.name, ort: { art: 'profil', name } });
+            if (harness.orte().includes('arbeitsverzeichnis'))
+                for (const pfad of zustand.arbeitsverzeichnisse)
+                    ziele.push(arbeitsverzeichnisZiel(harness.name, pfad));
+            for (const ziel of ziele) {
+                const verzeichnis = harness.zielVerzeichnis(ziel.ort);
+                const eintraege = await this.p.ziele.eintraege(ziel, verzeichnis).catch(() => []);
+                const plugins = kannPlugins(harness)
+                    ? await harness.plugins.installierte(ziel).catch(() => [])
+                    : undefined;
+                ergebnis.push({
+                    ziel,
+                    verzeichnis,
+                    eintraege,
+                    einschraenkungen: await this.einschraenkungen(ziel),
+                    ...(plugins === undefined ? {} : { plugins }),
+                });
+            }
+        }
+        return ergebnis;
+    }
+}