hmgr 0.0.2 → 0.0.4

package/README.md

@@ -26,34 +26,5 @@ npm run build
 
 ## Kommandos
 
-```
-source add <url|pfad>   Quelle hinzufügen (URL wird geklont, Pfad bleibt Arbeitskopie)
-source list             Quellen zeigen
-dir add <pfad>          Arbeitsverzeichnis merken und an seinen Zeiger binden
-dir forget <pfad>       Arbeitsverzeichnis und Bindung vergessen, Links bleiben
-dir list                Arbeitsverzeichnisse mit ihrer Bindung zeigen
-link <skill>            Skill in ein Ziel verlinken
-unlink <skill>          Link entfernen
-adopt [name]            Fremde Links im Ziel durch eigene hmgr-Links ersetzen
-plugin add <name>       Plugin in ein Ziel legen (installieren oder Skills verlinken)
-plugin remove <name>    Plugin aus einem Ziel entfernen
-plugin list             Plugins der Marketplaces aller Quellen
-sync [pfad]             Ziel auf den Stand seines Zeigers bringen
-update                  Alle Checkouts aktualisieren
-status                  Ist-Zustand der Ziele
-```
-
-Optionen:
-
-```
---harness <name>        claude-code, hermes oder agents, Standard claude-code
---ort home|dir:<pfad>|profil:<name>   Standard home
---quelle <teilstring>   Quelle bei mehrdeutigem Skill-Namen
---version <spanne>      Versionseinschränkung nach Composer-Regeln, nur mit Zeiger
---composer <pfad>       composer.json wählen, wenn mehrere in Frage kommen
---local                 Link nur ins Ziel legen, nicht in den Zeiger
---ersetzen              fremden Eintrag am Ziel ersetzen
---probelauf             bei adopt nur melden, nichts schreiben
-```
-
-`hmgr help` zeigt dieselbe Übersicht.
+`hmgr --help` zeigt die Kommandos, `hmgr help <kommando>` Schalter, Beispiele
+und Zusammenhänge.

package/dist/adapter/checkout-pfad.js

@@ -1,6 +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";
 export const BASIS_NAME = '.repo';
 /** Refs mit „/" im Namen werden im Pfad kodiert, damit ein Ref ein Verzeichnis bleibt. */
 export function refKodieren(ref) {
@@ -9,29 +10,13 @@ export function refKodieren(ref) {
 export function refDekodieren(text) {
     return text.replaceAll('%2F', '/').replaceAll('%25', '%');
 }
-function ohneGitSuffix(name) {
-    return name.endsWith('.git') ? name.slice(0, -4) : name;
-}
-function ausSegmenten(host, segmente) {
-    const gefiltert = segmente.filter((s) => s.length > 0);
-    const repo = ohneGitSuffix(gefiltert[gefiltert.length - 1] ?? 'repo');
-    const besitzer = gefiltert[gefiltert.length - 2] ?? '_';
-    return { host, besitzer, repo };
-}
 /** Zerlegt „git@host:besitzer/repo.git", „https://host/besitzer/repo", „file:///pfad" und nackte Pfade. */
 export function urlZerlegen(url) {
-    const text = url.trim().replace(/\/+$/, '');
-    if (text.includes('://')) {
-        const u = new URL(text);
-        if (u.protocol === 'file:')
-            return ausSegmenten('local', decodeURIComponent(u.pathname).split('/'));
-        return ausSegmenten(u.hostname, decodeURIComponent(u.pathname).split('/'));
-    }
-    const scp = /^(?:[^@/]+@)?([^@/:]+):(.+)$/.exec(text);
-    if (scp)
-        return ausSegmenten(scp[1], scp[2].split('/'));
+    const ort = urlOrt(url);
+    if (ort !== undefined)
+        return ort;
     // Nackter lokaler Pfad: Besitzer aus dem Elternverzeichnis.
-    return ausSegmenten('local', path.resolve(text).split(path.sep));
+    return ortAusSegmenten('local', path.resolve(url.trim()).split(path.sep));
 }
 export function quelleZerlegen(quelle) {
     return urlZerlegen(quelle.art === 'git' ? quelle.url : quelle.pfad);

package/dist/adapter/git.js

@@ -1,6 +1,6 @@
 // Git über die CLI, keine Bibliothek. Checkout-Schema und Worktrees nach E22, Discovery nach E11.
 import { execFile, spawn } from 'node:child_process';
-import { readFile, readdir, mkdir, realpath, stat } from 'node:fs/promises';
+import { readFile, readdir, mkdir, realpath, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { marketplaceLesen } from "./marketplace-json.js";
@@ -225,6 +225,15 @@ export class GitQuellen {
         const ausgabe = await this.git(['for-each-ref', '--format=%(refname:short)', 'refs/tags'], basis);
         return ausgabe.split('\n').filter((z) => z.length > 0);
     }
+    /**
+     * Refs vom Remote nachziehen, damit eine Versionseinschränkung auch Tags sieht, die nach dem
+     * Clone entstanden sind (E33). Lokale Quellen haben keinen Clone und keinen Remote (B11).
+     */
+    async refsNachziehen(quelle) {
+        if (quelle.art === 'lokal')
+            return;
+        await this.git(['fetch', '--prune', '--tags', 'origin'], await this.basis(quelle));
+    }
     async standardRef(quelle) {
         if (quelle.art === 'lokal')
             return LOKAL_REF;
@@ -305,6 +314,24 @@ export class GitQuellen {
         await this.git(['checkout', '--detach', checkout.ref], checkout.pfad);
         return { ergebnis: 'aktualisiert', von, nach };
     }
+    /**
+     * Checkout von der Platte nehmen. Ein Worktree steht im Basis-Clone eingetragen, ein blankes
+     * Löschen des Verzeichnisses ließe den Eintrag stehen und ein späterer `worktree add` auf
+     * denselben Pfad scheiterte daran. Bleibt der Eintrag defekt, wird das Verzeichnis entfernt und
+     * der Eintrag danach mit `prune` aufgeräumt. Der Basis-Clone bleibt, er trägt alle Refs.
+     */
+    async entfernen(checkout) {
+        if (checkout.quelle.art === 'lokal')
+            return;
+        const basis = await this.basis(checkout.quelle);
+        try {
+            await this.git(['worktree', 'remove', '--force', checkout.pfad], basis);
+        }
+        catch {
+            await rm(checkout.pfad, { recursive: true, force: true });
+            await this.git(['worktree', 'prune'], basis);
+        }
+    }
     /**
      * Arbeitskopie um einen Pfad herum (B12). Die Wurzel kommt aus `rev-parse --show-toplevel`, vom
      * Verzeichnis des Pfads aus gefragt. Beide Pfade werden über realpath aufgelöst, sonst passen

package/dist/adapter/quelle-text.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+export { quelleAlsText } from "../kern/modell.js";
 /** URL heißt Git-Quelle mit Checkout, ein nackter Pfad heißt lokale Arbeitskopie ohne Clone (B11). */
 export function quelleAusText(text) {
     const roh = text.trim();
@@ -6,6 +7,3 @@ export function quelleAusText(text) {
         return { art: 'git', url: roh };
     return { art: 'lokal', pfad: path.resolve(roh) };
 }
-export function quelleAlsText(quelle) {
-    return quelle.art === 'git' ? quelle.url : quelle.pfad;
-}

package/dist/adapter/terminal.js

@@ -21,4 +21,27 @@ export class TerminalRueckfrage {
             leser.close();
         }
     }
+    /**
+     * Nummerierte Liste, eine gelesene Zahl. Dieselbe Weiche wie bei `bestaetigen`: ohne Terminal auf
+     * beiden Seiten fragt hmgr nicht und gibt nichts aus. Alles, was keine der Nummern ist, auch die
+     * leere Eingabe, gilt als keine Antwort. Der Adapter rät nicht, er reicht das Nichts weiter.
+     */
+    async auswaehlen(frage, optionen) {
+        if (optionen.length === 0)
+            return undefined;
+        if (process.stdin.isTTY !== true || process.stdout.isTTY !== true)
+            return undefined;
+        const leser = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            const liste = optionen.map((option, i) => `  ${i + 1}) ${option}`).join('\n');
+            const antwort = await leser.question(`${frage}\n${liste}\nNummer [1-${optionen.length}]: `);
+            const nummer = Number(antwort.trim());
+            if (!Number.isInteger(nummer) || nummer < 1 || nummer > optionen.length)
+                return undefined;
+            return nummer - 1;
+        }
+        finally {
+            leser.close();
+        }
+    }
 }

package/dist/cli/hilfe.js

@@ -0,0 +1,268 @@
+// Hilfetexte der CLI. Nur Zeichenketten, keine Ausgabe: die macht main.ts (Terminal-I/O).
+/** Ebene 1: Orientierung, je Kommando ein Einzeiler, Verweis auf die Kommando-Hilfe. */
+export const HILFE = `hmgr verlinkt Skills aus Git-Quellen in die Verzeichnisse, aus denen ein Harness sie lädt:
+claude-code, hermes oder agents. Welche Skills und Plugins zu einem Arbeitsverzeichnis gehören,
+steht in seinem Zeiger, dem extra-Abschnitt einer composer.json.
+
+Arbeitszyklus: Skill in seiner Quelle ändern, committen und pushen, dann hmgr update. Ein frisch
+geklontes Vorhaben holt seinen Stand mit hmgr sync.
+
+hmgr <kommando> [schalter]
+
+  source add <url|pfad>   Quelle hinzufügen (URL wird geklont, Pfad bleibt Arbeitskopie)
+  source list             Quellen zeigen
+  dir add <pfad>          Arbeitsverzeichnis merken und an seinen Zeiger binden
+  dir forget <pfad>       Arbeitsverzeichnis und Bindung vergessen, Links bleiben
+  dir list                Arbeitsverzeichnisse mit ihrer Bindung zeigen
+  link <skill>            Skill in ein Ziel verlinken
+  unlink <skill>          Link entfernen
+  adopt [name]            Fremde Links im Ziel durch eigene hmgr-Links ersetzen
+  plugin add <name>       Plugin in ein Ziel legen (installieren oder Skills verlinken)
+  plugin remove <name>    Plugin aus einem Ziel entfernen
+  plugin list             Plugins der Marketplaces aller Quellen
+  sync [pfad]             Ziel auf den Stand seines Zeigers bringen
+  update                  Alle Checkouts aktualisieren
+  status                  Ist-Zustand der Ziele
+
+hmgr help <kommando> zeigt Schalter, Beispiele und Zusammenhänge.`;
+const SOURCE = `hmgr source add <url|pfad>
+hmgr source list
+
+Eine Quelle ist ein Git-Repo mit Skills. source add prüft, ob sie erreichbar ist, liest ihre Skills
+und ihren Marketplace und merkt sie unter ~/.hmgr. Erst danach kennt hmgr die Skill-Namen, mit
+denen link und plugin add arbeiten. Eine URL wird geklont, ein Pfad bleibt die Arbeitskopie, die
+dort schon liegt, und wird von hmgr nicht verändert.
+
+Welche Quelle gemeint ist, hängt an Host, Besitzer und Repo, nicht an der Schreibweise der URL. Ein
+Repo in SSH- und in HTTPS-Form ist dieselbe Quelle, mit und ohne .git-Suffix ebenso. Gefetcht wird
+unter der Schreibweise, die beim ersten source add stand.
+
+Schalter: keine.
+
+Beispiele:
+  hmgr source add https://github.com/tim/skills.git
+  hmgr source add ~/.skills/tim-skills
+  hmgr source list
+
+Häufige Fälle:
+  „Skill … liegt in keiner Quelle": die Quelle fehlt, erst source add, dann link.
+  Neue Commits einer bekannten Quelle holt hmgr update, nicht source add.
+  „Quelle ist schon bekannt": dasselbe Repo steht schon im Zustand, hier in anderer Schreibweise.
+
+Siehe auch: hmgr help link, hmgr help plugin, hmgr help update`;
+const DIR = `hmgr dir add <pfad> [--composer <pfad>]
+hmgr dir forget <pfad>
+hmgr dir list
+
+Ein Arbeitsverzeichnis ist ein Verzeichnis, in dem ein Harness gestartet wird. dir add merkt es und
+bindet es an seinen Zeiger, also an die composer.json, in deren extra-Abschnitt Quellen, Skills und
+Plugins des Vorhabens stehen. Ohne Zeiger bleibt das Verzeichnis gemerkt und jeder Link dort lokal
+(E26). dir forget löst Bindung und Eintrag, die gelegten Links bleiben liegen.
+
+Schalter:
+  --composer <pfad>   nur bei add: composer.json wählen, wenn unter dem Verzeichnis mehrere in
+                      Frage kommen
+
+Beispiele:
+  hmgr dir add ~/Code/site
+  hmgr dir add ~/Code/site --composer ~/Code/site/app/composer.json
+  hmgr dir list
+
+Häufige Fälle:
+  „Mehrere composer.json unter …": hmgr fragt am Terminal, welche es ist. Ohne Antwort, etwa in
+  einem Script, bleibt der Fehler und --composer nennt sie, hmgr rät nicht.
+  link --ort dir:<pfad> merkt das Verzeichnis von selbst. dir add braucht es vorher nur, wenn die
+  composer.json mehrdeutig ist.
+
+Siehe auch: hmgr help link, hmgr help sync`;
+const LINK = `hmgr link <skill> [schalter]
+
+Legt im Ziel einen Symlink auf den Skill an, der aus einer bekannten Quelle stammt, und trägt ihn
+in den Zeiger des Ziels ein, damit hmgr sync ihn anderswo reproduzieren kann. Einen Zeiger gibt es
+nur für ein Arbeitsverzeichnis mit composer.json, an Home und Profil bleibt jeder Link lokal.
+
+Schalter:
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --quelle <teil>     Teilstring der Quelle, wenn der Skill-Name in mehreren Quellen vorkommt
+  --version <spanne>  Versionseinschränkung nach Composer-Regeln (etwa ^1.2) oder ein Tag- oder
+                      Branchname. Nur mit Zeiger, also dir:<pfad> ohne --local (E33)
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             Link nur ins Ziel legen, nicht in den Zeiger
+  --ersetzen          einen fremden Eintrag gleichen Namens am Ziel ersetzen
+
+Beispiele:
+  hmgr link netzwerk
+  hmgr link netzwerk --harness hermes --ort profil:researcher
+  hmgr link tq-schema --ort dir:. --version ^2.0
+
+Häufige Fälle:
+  „liegt in mehreren Quellen": mit --quelle <teilstring der URL oder des Pfads> entscheiden.
+  „liegt bereits ein fremder Eintrag": --ersetzen setzen oder vorher hmgr adopt <name>.
+  „gibt es keinen Zeiger": --version braucht ein Arbeitsverzeichnis mit composer.json und kein
+  --local. Ohne Zeiger den Link ohne --version legen.
+
+Siehe auch: hmgr help unlink, hmgr help sync, hmgr help adopt`;
+const UNLINK = `hmgr unlink <skill> [schalter]
+
+Entfernt den Link aus dem Ziel und, wenn das Ziel an einen Zeiger gebunden ist, den Skill aus dem
+Zeiger. Der Checkout unter ~/.hmgr bleibt liegen, Links anderer Ziele bleiben unberührt.
+
+Schalter:
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             nur den Link entfernen, den Eintrag im Zeiger stehen lassen
+
+Beispiele:
+  hmgr unlink netzwerk
+  hmgr unlink netzwerk --ort dir:. --local
+
+Häufige Fälle:
+  Bleibt der Skill im Zeiger stehen, legt hmgr sync ihn wieder an. Ohne --local räumt unlink
+  beides ab.
+
+Siehe auch: hmgr help link, hmgr help sync`;
+const ADOPT = `hmgr adopt [name] [schalter]
+
+Ersetzt fremde Symlinks im Ziel durch eigene hmgr-Links: hmgr liest, aus welcher Git-Arbeitskopie
+ein Link stammt, nimmt deren remote.origin.url als Quelle, legt einen Checkout am selben Branch an
+und verlinkt den Skill daraus. Ohne Namen laufen alle fremden Einträge des Ziels durch, mit Namen
+nur dieser eine. Was sich nicht auflösen lässt, bleibt liegen und wird mit Grund gemeldet.
+
+Schalter:
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             Übernahme nicht in den Zeiger schreiben
+  --probelauf         nur melden, nichts schreiben
+
+Beispiele:
+  hmgr adopt --probelauf
+  hmgr adopt netzwerk --ort dir:.
+
+Häufige Fälle:
+  „kein Symlink": der Eintrag ist ein echtes Verzeichnis, hmgr fasst ihn nicht an.
+  „liegt in keiner Git-Arbeitskopie" oder „ohne remote.origin.url": die Quelle ist nicht
+  bestimmbar. Mit hmgr source add <url> eine Quelle nennen und mit hmgr link --ersetzen verlinken.
+  „ohne Branch (detached HEAD)": in der Arbeitskopie einen Branch auschecken, dann erneut adopt.
+  „Pfad ist in der Quelle kein Skill": im Repo liegt an der Stelle keine SKILL.md.
+
+Siehe auch: hmgr help link, hmgr help status`;
+const PLUGIN = `hmgr plugin add <name> [schalter]
+hmgr plugin remove <name> [schalter]
+hmgr plugin list
+
+Ein Plugin ist ein Bündel aus einem Marketplace, also aus einer Quelle mit
+.claude-plugin/marketplace.json. Hat der Harness die Plugin-Fähigkeit (claude-code), lässt hmgr das
+Plugin von dessen CLI installieren, sonst verlinkt es die flache Skill-Liste des Plugins samt
+seinen Abhängigkeiten. In den Zeiger kommt das Plugin, nicht seine Einzelskills. plugin list zeigt
+die Marketplaces aller bekannten Quellen mit ihren Plugins.
+
+Schalter (add und remove):
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             Plugin nicht in den Zeiger schreiben
+  --quelle <teil>     nur bei add: Quelle eingrenzen, wenn der Name in mehreren Marketplaces steht
+
+Beispiele:
+  hmgr plugin list
+  hmgr plugin add superpowers --ort dir:.
+  hmgr plugin remove superpowers
+
+Häufige Fälle:
+  „Keine Quelle mit Marketplace": erst hmgr source add <url> der Quelle mit der marketplace.json.
+  „liegt in keinem Marketplace der bekannten Quellen": Namen mit hmgr plugin list prüfen.
+  „liegt in mehreren Marketplaces": mit --quelle <teilstring> entscheiden.
+  „braucht …, das im selben Marketplace nicht steht": die Abhängigkeit fehlt im Marketplace, das
+  kann nur die Quelle beheben.
+
+Siehe auch: hmgr help source, hmgr help sync`;
+const SYNC = `hmgr sync [pfad]
+
+Bringt ein Arbeitsverzeichnis auf den Stand seines Zeigers: fehlende Quellen übernehmen, fehlende
+Links legen, Links auf einen anderen Ref umlegen, Plugins herstellen. Ohne Pfad gilt das aktuelle
+Verzeichnis. Das ist der Befehl nach einem frischen Clone eines Vorhabens und nach jeder Änderung
+am Zeiger. Eigene Links, die im Zeiger fehlen, werden als abweichend gemeldet und nicht entfernt,
+fremde Einträge bleiben unberührt.
+
+Schalter: keine.
+
+Beispiele:
+  hmgr sync
+  hmgr sync ~/Code/site
+
+Häufige Fälle:
+  „Kein Zeiger unter …, nichts zu tun": im Verzeichnis liegt keine composer.json. Mit
+  hmgr dir add <pfad> --composer <pfad> eine nennen.
+  „steht nicht im Zeiger": den Link mit hmgr link <skill> --ort dir:<pfad> eintragen oder mit
+  hmgr unlink <skill> --ort dir:<pfad> --local entfernen.
+  „Kein Harness auf diesem Rechner": weder ~/.claude noch ~/.hermes noch ~/.agents ist angelegt.
+
+Siehe auch: hmgr help dir, hmgr help link, hmgr help update`;
+const UPDATE = `hmgr update
+
+Holt für jeden Checkout unter ~/.hmgr den neuesten Stand seines Refs und zieht bei Harnesses mit
+Plugin-Fähigkeit deren Plugins nach (E14). Die Links zeigen weiter auf dieselben Pfade und müssen
+nicht erneuert werden. Ein Checkout mit lokaler Änderung wird übersprungen und gemeldet (E15),
+damit nichts verloren geht. Lokale Quellen haben keinen Checkout und bleiben unberührt.
+
+Danach räumt update verwaiste Ref-Verzeichnisse auf: Checkouts, in die kein Link mehr zeigt, weil
+ein Link inzwischen auf einen anderen Ref umgelegt wurde. Vor dem Löschen fragt hmgr einmal für
+alle Kandidaten. Ohne Bestätigung, also auch ohne Terminal, bleibt alles liegen und wird nur
+gemeldet. Ein verwaister Checkout mit lokaler Änderung wird nie gelöscht (E15).
+
+So wird eine Änderung an einem Skill überall wirksam: in der Quelle committen und pushen, dann
+hmgr update.
+
+Schalter: keine.
+
+Beispiel:
+  hmgr update
+
+Häufige Fälle:
+  „übersprungen … lokale Änderung (E15)": im Checkout liegt eine Änderung, die durch einen Link
+  hindurch gemacht wurde. Dort committen und pushen, dann erneut hmgr update.
+  „Keine Checkouts": es gibt nur lokale Quellen oder noch keinen Link.
+  „liegen lassen … ohne Bestätigung nicht gelöscht": die Frage kam ohne Ja zurück, etwa in einer
+  Pipe oder einem Composer-Script. In einem Terminal erneut hmgr update aufrufen.
+
+Siehe auch: hmgr help sync, hmgr help status`;
+const STATUS = `hmgr status
+
+Liest den Ist-Zustand vom Dateisystem: je Ziel eines vorhandenen Harness die Einträge mit Quelle
+und Ref, davor die Versionseinschränkung, falls der Zeiger eine nennt. Fremde Einträge und Links
+ohne bekannte Quelle sind eigens gekennzeichnet, dazu kommen die Plugins des Ziels. Am Ende stehen
+die Harnesses, die auf diesem Rechner nicht liegen.
+
+Schalter: keine.
+
+Beispiel:
+  hmgr status
+
+Häufige Fälle:
+  „fremd": der Eintrag stammt nicht von hmgr. hmgr adopt <name> übernimmt ihn.
+  „Link ohne bekannte Quelle": der Link zeigt in einen hmgr-Checkout, dessen Quelle nicht mehr im
+  Zustand steht. Mit hmgr source add <url> die Quelle wieder eintragen.
+  „Nicht vorhanden": der Harness hat sein Verzeichnis auf diesem Rechner nicht angelegt, hmgr
+  überspringt seine Ziele.
+
+Siehe auch: hmgr help adopt, hmgr help sync`;
+/** Ebene 2, je Kommandofamilie ein Text. Unterkommandos teilen sich die Hilfe ihrer Familie. */
+const THEMEN = new Map([
+    ['source', SOURCE],
+    ['dir', DIR],
+    ['link', LINK],
+    ['unlink', UNLINK],
+    ['adopt', ADOPT],
+    ['plugin', PLUGIN],
+    ['sync', SYNC],
+    ['update', UPDATE],
+    ['status', STATUS],
+    ['help', HILFE],
+]);
+/** Hilfetext zu einem Kommando, undefined für ein unbekanntes Thema. */
+export function hilfeText(thema) {
+    return THEMEN.get(thema);
+}

package/dist/cli/main.js

@@ -15,6 +15,7 @@ import { GitQuellen } from "../adapter/git.js";
 import { quelleAlsText, quelleAusText } from "../adapter/quelle-text.js";
 import { TerminalRueckfrage } from "../adapter/terminal.js";
 import { ZustandJson } from "../adapter/zustand-json.js";
+import { HILFE, hilfeText } from "./hilfe.js";
 export function umgebungLesen(env = process.env) {
     const home = env.HOME ?? homedir();
     return { home, hmgrHome: env.HMGR_HOME ?? path.join(home, '.hmgr') };
@@ -35,9 +36,44 @@ export function bauen(umgebung, optionen = {}) {
     };
     return { anwendungsfaelle: new Anwendungsfaelle(ports), ports };
 }
-/** Schalter ohne Wert. Alles andere braucht einen. */
-const FLAGGEN = new Set(['ersetzen', 'local', 'lokal', 'probelauf']);
-function schalterLesen(args) {
+/**
+ * Was jedes Kommando auswertet, gleichlautend mit seiner Hilfe. Alles andere bricht ab. `--help`
+ * steht nirgends, weil der Hilfe-Dispatch vor jedem schalterLesen läuft.
+ */
+const SCHALTER = {
+    source: { werte: [], flaggen: [] },
+    dir: { werte: ['composer'], flaggen: [] },
+    link: {
+        werte: ['harness', 'ort', 'composer', 'quelle', 'version'],
+        flaggen: ['local', 'lokal', 'ersetzen'],
+    },
+    unlink: { werte: ['harness', 'ort', 'composer'], flaggen: ['local', 'lokal'] },
+    adopt: { werte: ['harness', 'ort', 'composer'], flaggen: ['local', 'lokal', 'probelauf'] },
+    plugin: { werte: ['harness', 'ort', 'composer', 'quelle'], flaggen: ['local', 'lokal'] },
+    sync: { werte: [], flaggen: [] },
+    update: { werte: [], flaggen: [] },
+    status: { werte: [], flaggen: [] },
+};
+/**
+ * Was ein einzelnes Unterkommando von seiner Familie liest, gleichlautend mit ihrer Hilfe. Ohne
+ * `schalter` bleibt es bei der Familienliste, das reicht, solange alle Unterkommandos dieselben
+ * Schalter lesen.
+ */
+const UNTERKOMMANDOS = {
+    source: { add: { woerter: 2 }, list: { woerter: 1 } },
+    dir: {
+        add: { woerter: 2, schalter: ['composer'] },
+        forget: { woerter: 2, schalter: [] },
+        list: { woerter: 1, schalter: [] },
+    },
+    plugin: {
+        add: { woerter: 2, schalter: ['harness', 'ort', 'composer', 'quelle', 'local', 'lokal'] },
+        remove: { woerter: 2, schalter: ['harness', 'ort', 'composer', 'local', 'lokal'] },
+        list: { woerter: 1, schalter: [] },
+    },
+};
+function schalterLesen(args, kommando) {
+    const erlaubt = SCHALTER[kommando];
     const rest = [];
     const werte = new Map();
     const flaggen = new Set();
@@ -48,17 +84,50 @@ function schalterLesen(args) {
             continue;
         }
         const name = arg.slice(2);
-        if (FLAGGEN.has(name)) {
+        if (erlaubt.flaggen.includes(name)) {
             flaggen.add(name);
             continue;
         }
+        if (!erlaubt.werte.includes(name))
+            throw new Error(`Unbekannter Schalter --${name} für ${kommando}. hmgr help ${kommando} zeigt die Schalter.`);
         const wert = args[++i];
         if (wert === undefined)
-            throw new Error(`Schalter --${name} braucht einen Wert`);
+            throw new Error(`Schalter --${name} braucht einen Wert, etwa --${name} <wert>. ` +
+                `hmgr help ${kommando} zeigt die Schalter.`);
         werte.set(name, wert);
     }
     return { rest, werte, flaggen };
 }
+/** Ein Wort mehr, als das Kommando liest, ist ein Tippfehler und kein stiller Zusatz. */
+function restPruefen(rest, woerter, kommando, unterkommando) {
+    const zuviel = rest[woerter];
+    if (zuviel === undefined)
+        return;
+    const verwendung = unterkommando === undefined ? kommando : `${kommando} ${unterkommando}`;
+    // Der Name des Unterkommandos zählt zu den Wörtern, aber nicht zu den Argumenten.
+    const argumente = woerter - (unterkommando === undefined ? 0 : 1);
+    throw new Error(`${verwendung} erwartet ${argumente === 0 ? 'kein' : 'kein weiteres'} Argument „${zuviel}". ` +
+        `hmgr help ${kommando} zeigt die Verwendung.`);
+}
+/**
+ * Prüft, was erst mit dem Unterkommando feststeht: liest es die gesetzten Schalter, und steht ein
+ * Wort zu viel da. Ein unbekanntes Unterkommando meldet die Familie selbst.
+ */
+function unterkommandoPruefen(kommando, schalter) {
+    const unterkommando = schalter.rest[0];
+    if (unterkommando === undefined)
+        return;
+    const menge = UNTERKOMMANDOS[kommando][unterkommando];
+    if (menge === undefined)
+        return;
+    const erlaubt = menge.schalter;
+    if (erlaubt !== undefined)
+        for (const name of [...schalter.werte.keys(), ...schalter.flaggen])
+            if (!erlaubt.includes(name))
+                throw new Error(`Unbekannter Schalter --${name} für ${kommando} ${unterkommando}. ` +
+                    `hmgr help ${kommando} zeigt die Schalter.`);
+    restPruefen(schalter.rest, menge.woerter, kommando, unterkommando);
+}
 function ortLesen(text) {
     const roh = text ?? 'home';
     if (roh === 'home')
@@ -69,31 +138,6 @@ function ortLesen(text) {
         return { art: 'profil', name: roh.slice(7) };
     throw new Error(`Unbekannter Ort „${roh}", erwartet home, dir:<pfad> oder profil:<name>`);
 }
-const HILFE = `hmgr <kommando>
-
-  source add <url|pfad>   Quelle hinzufügen (URL wird geklont, Pfad bleibt Arbeitskopie)
-  source list             Quellen zeigen
-  dir add <pfad>          Arbeitsverzeichnis merken und an seinen Zeiger binden
-  dir forget <pfad>       Arbeitsverzeichnis und Bindung vergessen, Links bleiben
-  dir list                Arbeitsverzeichnisse mit ihrer Bindung zeigen
-  link <skill>            Skill in ein Ziel verlinken
-  unlink <skill>          Link entfernen
-  adopt [name]            Fremde Links im Ziel durch eigene hmgr-Links ersetzen
-  plugin add <name>       Plugin in ein Ziel legen (installieren oder Skills verlinken)
-  plugin remove <name>    Plugin aus einem Ziel entfernen
-  plugin list             Plugins der Marketplaces aller Quellen
-  sync [pfad]             Ziel auf den Stand seines Zeigers bringen
-  update                  Alle Checkouts aktualisieren
-  status                  Ist-Zustand der Ziele
-
-  --harness <name>        claude-code, hermes oder agents, Standard claude-code
-  --ort home|dir:<pfad>|profil:<name>   Standard home
-  --quelle <teilstring>   Quelle bei mehrdeutigem Skill-Namen
-  --version <spanne>      Versionseinschränkung nach Composer-Regeln, nur mit Zeiger (E33)
-  --composer <pfad>       composer.json wählen, wenn mehrere in Frage kommen
-  --local                 Link nur ins Ziel legen, nicht in den Zeiger
-  --ersetzen              fremden Eintrag am Ziel ersetzen
-  --probelauf             bei adopt nur melden, nichts schreiben`;
 /** Klartext für den Grund, aus dem ein fremder Eintrag liegen bleibt (B12). */
 const UEBERNAHME_GRUND = {
     'kein-link': 'kein Symlink',
@@ -105,18 +149,46 @@ const UEBERNAHME_GRUND = {
 export async function ausfuehren(argv, umgebung, optionen = {}) {
     const { anwendungsfaelle, ports } = bauen(umgebung, optionen);
     const kommando = argv[0];
-    if (kommando === undefined || kommando === 'help' || kommando === '--help') {
+    // Hilfe zuerst: --help ist überall eine Flagge, damit kein Kommando sie als Wert liest.
+    if (kommando === undefined) {
         console.log(HILFE);
-        return kommando === undefined ? 1 : 0;
+        return 1;
+    }
+    if (kommando === 'help' || kommando === '--help' || kommando === '-h') {
+        const thema = argv[1];
+        if (thema === undefined || thema.startsWith('-')) {
+            console.log(HILFE);
+            return 0;
+        }
+        const text = hilfeText(thema);
+        if (text === undefined)
+            throw new Error(`Unbekanntes Hilfe-Thema „${thema}". hmgr --help zeigt alle Kommandos.`);
+        console.log(text);
+        return 0;
+    }
+    if (argv.slice(1).includes('--help')) {
+        const text = hilfeText(kommando);
+        if (text === undefined)
+            throw new Error(`Unbekanntes Kommando „${kommando}". hmgr --help zeigt alle Kommandos.`);
+        console.log(text);
+        return 0;
     }
     if (kommando === 'source') {
-        const unterkommando = argv[1];
+        const schalter = schalterLesen(argv.slice(1), 'source');
+        unterkommandoPruefen('source', schalter);
+        const rest = schalter.rest;
+        const unterkommando = rest[0];
         if (unterkommando === 'add') {
-            const text = argv[2];
+            const text = rest[1];
             if (text === undefined)
-                throw new Error('source add braucht eine URL oder einen Pfad');
-            const quelle = quelleAusText(text);
-            const { skills, marketplace } = await anwendungsfaelle.quelleHinzufuegen(quelle);
+                throw new Error('source add braucht eine URL oder einen Pfad, etwa hmgr source add https://example.com/skills.git');
+            const genannt = quelleAusText(text);
+            const { quelle, skills, marketplace, bekannt } = await anwendungsfaelle.quelleHinzufuegen(genannt);
+            // Dieselbe Quelle in anderer Schreibweise legt keine zweite an (E36).
+            if (bekannt)
+                console.log(quelleAlsText(quelle) === quelleAlsText(genannt)
+                    ? 'Quelle ist schon bekannt, keine zweite angelegt.'
+                    : `Quelle ist schon bekannt, geführt als ${quelleAlsText(quelle)}. Keine zweite angelegt.`);
             console.log(`Quelle ${quelleAlsText(quelle)} (${quelle.art}), ${skills.length} Skills:`);
             for (const skill of skills)
                 console.log(`  ${skill.name}  ${skill.pfad}`);
@@ -137,15 +209,17 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
                 console.log(`${quelle.art}  ${quelleAlsText(quelle)}`);
             return 0;
         }
-        throw new Error('source add <url|pfad> oder source list');
+        throw new Error(`${unterkommando === undefined ? 'source braucht ein Unterkommando' : `Unbekanntes Unterkommando „${unterkommando}" für source`}: source add <url|pfad> oder source list. hmgr help source zeigt Beispiele.`);
     }
     if (kommando === 'dir') {
-        const { rest, werte } = schalterLesen(argv.slice(1));
+        const schalter = schalterLesen(argv.slice(1), 'dir');
+        unterkommandoPruefen('dir', schalter);
+        const { rest, werte } = schalter;
         const unterkommando = rest[0];
         if (unterkommando === 'add') {
             const pfad = rest[1];
             if (pfad === undefined)
-                throw new Error('dir add braucht einen Pfad');
+                throw new Error('dir add braucht einen Pfad, etwa hmgr dir add .');
             const composer = werte.get('composer');
             const ergebnis = composer === undefined
                 ? await anwendungsfaelle.arbeitsverzeichnisHinzufuegen(pfad)
@@ -160,7 +234,7 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         if (unterkommando === 'forget') {
             const pfad = rest[1];
             if (pfad === undefined)
-                throw new Error('dir forget braucht einen Pfad');
+                throw new Error('dir forget braucht einen Pfad. hmgr dir list zeigt die gemerkten Arbeitsverzeichnisse.');
             await anwendungsfaelle.arbeitsverzeichnisVergessen(pfad);
             console.log(`Arbeitsverzeichnis ${path.resolve(pfad)} vergessen, die Links bleiben liegen.`);
             return 0;
@@ -175,13 +249,15 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
             }
             return 0;
         }
-        throw new Error('dir add <pfad>, dir forget <pfad> oder dir list');
+        throw new Error(`${unterkommando === undefined ? 'dir braucht ein Unterkommando' : `Unbekanntes Unterkommando „${unterkommando}" für dir`}: dir add <pfad>, dir forget <pfad> oder dir list. hmgr help dir zeigt Beispiele.`);
     }
     if (kommando === 'link' || kommando === 'unlink') {
-        const { rest, werte, flaggen } = schalterLesen(argv.slice(1));
+        const { rest, werte, flaggen } = schalterLesen(argv.slice(1), kommando);
+        restPruefen(rest, 1, kommando);
         const skill = rest[0];
         if (skill === undefined)
-            throw new Error(`${kommando} braucht einen Skill-Namen`);
+            throw new Error(`${kommando} braucht einen Skill-Namen, etwa hmgr ${kommando} <skill>. ` +
+                'hmgr status zeigt die verlinkten Skills, hmgr source add <url|pfad> die Skills einer Quelle.');
         const ziel = { harness: werte.get('harness') ?? 'claude-code', ort: ortLesen(werte.get('ort')) };
         const lokal = flaggen.has('local') || flaggen.has('lokal');
         if (ziel.ort.art === 'arbeitsverzeichnis') {
@@ -214,7 +290,8 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         return 0;
     }
     if (kommando === 'adopt') {
-        const { rest, werte, flaggen } = schalterLesen(argv.slice(1));
+        const { rest, werte, flaggen } = schalterLesen(argv.slice(1), 'adopt');
+        restPruefen(rest, 1, 'adopt');
         const ziel = { harness: werte.get('harness') ?? 'claude-code', ort: ortLesen(werte.get('ort')) };
         const probelauf = flaggen.has('probelauf');
         const name = rest[0];
@@ -253,7 +330,9 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         return 0;
     }
     if (kommando === 'plugin') {
-        const { rest, werte, flaggen } = schalterLesen(argv.slice(1));
+        const schalter = schalterLesen(argv.slice(1), 'plugin');
+        unterkommandoPruefen('plugin', schalter);
+        const { rest, werte, flaggen } = schalter;
         const unterkommando = rest[0];
         if (unterkommando === 'list') {
             const marketplaces = await anwendungsfaelle.marketplaces();
@@ -272,10 +351,10 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
             return 0;
         }
         if (unterkommando !== 'add' && unterkommando !== 'remove')
-            throw new Error('plugin add <name>, plugin remove <name> oder plugin list');
+            throw new Error(`${unterkommando === undefined ? 'plugin braucht ein Unterkommando' : `Unbekanntes Unterkommando „${unterkommando}" für plugin`}: plugin add <name>, plugin remove <name> oder plugin list. hmgr help plugin zeigt Beispiele.`);
         const name = rest[1];
         if (name === undefined)
-            throw new Error(`plugin ${unterkommando} braucht einen Plugin-Namen`);
+            throw new Error(`plugin ${unterkommando} braucht einen Plugin-Namen. hmgr plugin list zeigt die Plugins der bekannten Quellen.`);
         const ziel = { harness: werte.get('harness') ?? 'claude-code', ort: ortLesen(werte.get('ort')) };
         const lokal = flaggen.has('local') || flaggen.has('lokal');
         if (ziel.ort.art === 'arbeitsverzeichnis') {
@@ -302,7 +381,8 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         return 0;
     }
     if (kommando === 'sync') {
-        const { rest } = schalterLesen(argv.slice(1));
+        const { rest } = schalterLesen(argv.slice(1), 'sync');
+        restPruefen(rest, 1, 'sync');
         const ergebnis = await anwendungsfaelle.abgleich(rest[0]);
         if (ergebnis.zeigerPfad !== undefined)
             console.log(`Zeiger ${ergebnis.zeigerPfad}`);
@@ -319,7 +399,8 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         return 0;
     }
     if (kommando === 'update') {
-        const { checkouts: liste, pluginHarnesses } = await anwendungsfaelle.aktualisieren();
+        restPruefen(schalterLesen(argv.slice(1), 'update').rest, 0, 'update');
+        const { checkouts: liste, pluginHarnesses, aufraeumen } = await anwendungsfaelle.aktualisieren();
         if (liste.length === 0)
             console.log('Keine Checkouts.');
         for (const { checkout, aktualisierung } of liste) {
@@ -333,9 +414,24 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         }
         for (const name of pluginHarnesses)
             console.log(`  Plugins         ${name} aktualisiert (E14)`);
+        // Zum Schluss die verwaisten Checkouts: was gelöscht wurde und was liegen bleibt.
+        for (const verwaist of aufraeumen.verwaiste) {
+            const kopf = `${quelleAlsText(verwaist.checkout.quelle)} @ ${verwaist.checkout.ref}`;
+            if (verwaist.geloescht)
+                console.log(`  gelöscht        ${kopf}  verwaist (${verwaist.checkout.pfad})`);
+            else if (verwaist.lokaleAenderung)
+                console.log(`  liegen lassen   ${kopf}  verwaist, aber lokale Änderung (E15)`);
+            else
+                console.log(`  liegen lassen   ${kopf}  verwaist, ohne Bestätigung nicht gelöscht`);
+        }
+        if (aufraeumen.verwaiste.length > 0) {
+            const geloescht = aufraeumen.verwaiste.filter((v) => v.geloescht).length;
+            console.log(`${aufraeumen.verwaiste.length} verwaist, ${geloescht} gelöscht, ${aufraeumen.verwaiste.length - geloescht} liegen geblieben.`);
+        }
         return 0;
     }
     if (kommando === 'status') {
+        restPruefen(schalterLesen(argv.slice(1), 'status').rest, 0, 'status');
         for (const zielZustand of await anwendungsfaelle.istZustand()) {
             console.log(`Ziel ${zielZustand.ziel.harness} ${beschreibeOrt(zielZustand.ziel.ort)} (${zielZustand.verzeichnis})`);
             if (zielZustand.eintraege.length === 0)
@@ -360,7 +456,7 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
             console.log(`Nicht vorhanden: ${fehlend.join(', ')}`);
         return 0;
     }
-    throw new Error(`Unbekanntes Kommando „${kommando}"`);
+    throw new Error(`Unbekanntes Kommando „${kommando}". hmgr --help zeigt alle Kommandos.`);
 }
 function beschreibeOrt(ort) {
     if (ort.art === 'home')
@@ -382,13 +478,43 @@ function istModellFehler(fehler) {
         fehler instanceof PluginUnbekannt ||
         fehler instanceof AbhaengigkeitFehlt);
 }
+/**
+ * Der nächste Schritt zu einem Fehler aus dem Kern. Die Fehlertexte selbst bleiben, wie das Modell
+ * sie schreibt, die Handlungsanweisung gehört an die CLI, weil sie Kommandos nennt.
+ */
+function naechsterSchritt(fehler) {
+    if (fehler instanceof SkillMehrdeutig)
+        return `Quelle eingrenzen: hmgr link ${fehler.name} --quelle <teilstring einer der genannten Quellen>`;
+    if (fehler instanceof SkillUnbekannt)
+        return 'Erst die Quelle hinzufügen: hmgr source add <url|pfad>. hmgr source list zeigt die bekannten Quellen.';
+    if (fehler instanceof NameBelegt)
+        return `Entweder mit --ersetzen überschreiben oder den fremden Eintrag mit hmgr adopt ${fehler.skillName} übernehmen.`;
+    if (fehler instanceof PluginMehrdeutig)
+        return 'Quelle eingrenzen: --quelle <teilstring der URL oder des Pfads>. hmgr plugin list zeigt die Marketplaces.';
+    if (fehler instanceof PluginUnbekannt)
+        return 'hmgr plugin list zeigt die Plugins der bekannten Quellen. Fehlt der Marketplace, erst hmgr source add <url>.';
+    if (fehler instanceof AbhaengigkeitFehlt)
+        return 'Die Abhängigkeit steht in keinem Plugin desselben Marketplace, das kann nur die Quelle beheben.';
+    if (fehler instanceof KeinPassenderRef)
+        return 'Die Tags der Quelle sind frisch geholt, keiner passt. Sonst einen vorhandenen Tag- oder Branchnamen als --version nennen.';
+    if (fehler instanceof HarnessNichtVorhanden)
+        return 'Der Harness legt sein Verzeichnis beim ersten Start an. hmgr status zeigt, welche Harnesses hier liegen.';
+    if (fehler instanceof OrtNichtUnterstuetzt)
+        return 'profil:<name> kennt nur hermes, claude-code und agents kennen home und dir:<pfad>.';
+    const text = fehler instanceof Error ? fehler.message : '';
+    if (text.startsWith('Unbekannter Harness'))
+        return 'Bekannt sind claude-code, hermes und agents.';
+    return undefined;
+}
 export async function main(argv, umgebung) {
     try {
         return await ausfuehren(argv, umgebung);
     }
     catch (fehler) {
         const text = fehler instanceof Error ? fehler.message : String(fehler);
-        console.error(istModellFehler(fehler) ? text : `Fehler: ${text}`);
+        const kopf = istModellFehler(fehler) ? text : `Fehler: ${text}`;
+        const schritt = naechsterSchritt(fehler);
+        console.error(schritt === undefined ? kopf : `${kopf}\n${schritt}`);
         return 1;
     }
 }

package/dist/kern/anwendungsfaelle.js

@@ -1,18 +1,41 @@
 // 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 { AbhaengigkeitFehlt, EinschraenkungOhneZeiger, HarnessNichtVorhanden, KeinPassenderRef, OrtNichtUnterstuetzt, PluginMehrdeutig, PluginUnbekannt, SkillMehrdeutig, SkillUnbekannt, ZeigerMehrdeutig, marketplaceUrl, pluginSchluessel, pluginSchluesselZerlegen, quelleAlsText, quelleSchluessel, zielSchluessel, } from "./modell.js";
 import { passenderRef } from "./version.js";
 import { kannPlugins, kannProfile } from "../ports/harness.js";
+/**
+ * Frage vor dem Löschen, eine für alle Kandidaten (E28). Der Kern formuliert sie fertig, der
+ * Adapter stellt sie: Anzahl und Pfade, damit der Nutzer sieht, worüber er entscheidet.
+ */
+export function aufraeumFrage(checkouts) {
+    const kopf = checkouts.length === 1
+        ? 'Ein Checkout ist verwaist, kein Link zeigt hinein:'
+        : `${checkouts.length} Checkouts sind verwaist, kein Link zeigt hinein:`;
+    const pfade = checkouts.map((c) => `  ${c.pfad}`).join('\n');
+    return `${kopf}\n${pfade}\nLöschen? [j/N]`;
+}
 function arbeitsverzeichnisZiel(harness, pfad) {
     return { harness, ort: { art: 'arbeitsverzeichnis', pfad } };
 }
 function fehlertext(fehler) {
     return fehler instanceof Error ? fehler.message : String(fehler);
 }
+/**
+ * Quellenhinweis bei Mehrdeutigkeit (E12): Teilstring des Schlüssels oder der Schreibweise. Beides
+ * zählt, damit `host/besitzer/repo` genauso greift wie ein Stück der URL, unter der die Quelle
+ * geführt wird (E36).
+ */
+function quellePasst(quelle, hinweis) {
+    if (hinweis === undefined)
+        return true;
+    return quelleSchluessel(quelle).includes(hinweis) || quelleAlsText(quelle).includes(hinweis);
+}
 export class Anwendungsfaelle {
     p;
     /** Schon beantwortete Orte, je Ziel der Hinweis, der davon übrig blieb (E34). */
     beantwortet = new Map();
+    /** Quellen, deren Refs in diesem Lauf schon nachgezogen wurden (E33). */
+    nachgezogen = new Set();
     constructor(p) {
         this.p = p;
     }
@@ -45,18 +68,25 @@ export class Anwendungsfaelle {
                 ergebnis.push(harness.name);
         return ergebnis;
     }
-    /** Quelle hinzufügen: prüft, dass sie erreichbar ist, und liest Skills und Marketplace (E24). */
+    /**
+     * Quelle hinzufügen: prüft, dass sie erreichbar ist, und liest Skills und Marketplace (E24).
+     * Steht dieselbe Quelle schon in einer anderen Schreibweise im Zustand, kommt keine zweite dazu
+     * (E36). Gelesen wird dann unter der Schreibweise, unter der sie geführt wird, denn mit ihr ist
+     * der Basis-Clone angelegt. `bekannt` sagt, ob es so kam, `quelle` nennt die geführte Fassung.
+     */
     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)) {
+        const gefuehrt = zustand.quellen.find((q) => quelleSchluessel(q) === key);
+        const wirksam = gefuehrt ?? quelle;
+        const ref = await this.p.quellen.standardRef(wirksam);
+        const skills = await this.p.quellen.skills(wirksam, ref);
+        const marketplace = await this.p.quellen.marketplace(wirksam, ref);
+        if (gefuehrt === undefined) {
             zustand.quellen.push(quelle);
             await this.p.zustand.schreiben(zustand);
         }
-        return { skills, marketplace };
+        return { quelle: wirksam, skills, marketplace, bekannt: gefuehrt !== undefined };
     }
     /** Marketplace einer Quelle am Standard-Ref, mit den Plugins als Modellwerte. */
     async marketplaceLesen(quelle) {
@@ -95,7 +125,7 @@ export class Anwendungsfaelle {
         const zustand = await this.p.zustand.lesen();
         const funde = [];
         for (const quelle of zustand.quellen) {
-            if (quelleHinweis && !quelleSchluessel(quelle).includes(quelleHinweis))
+            if (!quellePasst(quelle, quelleHinweis))
                 continue;
             const gelesen = await this.marketplaceLesen(quelle).catch(() => null);
             if (gelesen === null)
@@ -168,7 +198,7 @@ export class Anwendungsfaelle {
             if (fund.ergebnis === 'gefunden')
                 zeigerPfad = fund.pfad;
             else if (fund.ergebnis === 'mehrdeutig')
-                throw new ZeigerMehrdeutig(verzeichnis, fund.kandidaten);
+                zeigerPfad = await this.zeigerWaehlen(verzeichnis, fund.kandidaten);
             else
                 hinweis = `Kein Zeiger unter ${verzeichnis}, alles bleibt lokal (E26).`;
         }
@@ -201,6 +231,20 @@ export class Anwendungsfaelle {
         zustand.bindungen = zustand.bindungen.filter((b) => !(b.ziel.ort.art === 'arbeitsverzeichnis' && b.ziel.ort.pfad === verzeichnis));
         await this.p.zustand.schreiben(zustand);
     }
+    /**
+     * Mehrere composer.json unter einem Verzeichnis (E26): hmgr rät nicht, es fragt. Bleibt die Frage
+     * ohne Antwort, weil niemand antworten kann oder die Eingabe keine der Kandidaten trifft, gilt
+     * wie bisher der Fehler mit dem Weg über --composer. Der Fragetext kommt von hier, der Port kennt
+     * kein Terminal.
+     */
+    async zeigerWaehlen(verzeichnis, kandidaten) {
+        const frage = `Mehrere composer.json unter ${verzeichnis}. Welche ist der Zeiger?`;
+        const gewaehlt = await this.p.rueckfrage.auswaehlen(frage, kandidaten);
+        const pfad = gewaehlt === undefined ? undefined : kandidaten[gewaehlt];
+        if (pfad === undefined)
+            throw new ZeigerMehrdeutig(verzeichnis, kandidaten);
+        return pfad;
+    }
     /** Zeiger eines Arbeitsverzeichnisses aus dem Zustand, egal für welchen Harness (E26). */
     async bindungFuerVerzeichnis(verzeichnis) {
         const zustand = await this.p.zustand.lesen();
@@ -217,7 +261,7 @@ export class Anwendungsfaelle {
         const zustand = await this.p.zustand.lesen();
         const funde = [];
         for (const quelle of zustand.quellen) {
-            if (quelleHinweis && !quelleSchluessel(quelle).includes(quelleHinweis))
+            if (!quellePasst(quelle, quelleHinweis))
                 continue;
             const ref = await this.p.quellen.standardRef(quelle);
             const skills = await this.p.quellen.skills(quelle, ref);
@@ -457,6 +501,19 @@ export class Anwendungsfaelle {
         await this.p.zeiger.schreiben(zeigerPfad, zeiger);
         return { ...ergebnis, imZeiger: true };
     }
+    /**
+     * Refs einer Quelle nachziehen, bevor eine Einschränkung gegen sie ausgewertet wird (E33). Ohne
+     * das sähe die Auswertung nur die Tags, die beim Clone schon da waren, ein später entstandener
+     * Tag bliebe unsichtbar. Einmal je Lauf und Quelle. Scheitert das Nachziehen, etwa ohne Netz,
+     * wird mit dem vorhandenen Stand weitergearbeitet.
+     */
+    async refsNachziehen(quelle) {
+        const schluessel = quelleSchluessel(quelle);
+        if (this.nachgezogen.has(schluessel))
+            return;
+        this.nachgezogen.add(schluessel);
+        await this.p.quellen.refsNachziehen(quelle).catch(() => undefined);
+    }
     /**
      * 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,
@@ -467,8 +524,9 @@ export class Anwendungsfaelle {
         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));
+        const quellen = zustand.quellen.filter((q) => quellePasst(q, quelleHinweis));
         for (const quelle of quellen) {
+            await this.refsNachziehen(quelle);
             const tags = await this.p.quellen.tags(quelle).catch(() => []);
             const ref = passenderRef(tags, einschraenkung);
             if (ref === null)
@@ -502,7 +560,7 @@ export class Anwendungsfaelle {
             if (fund.ergebnis === 'gefunden')
                 zeigerPfad = fund.pfad;
             else if (fund.ergebnis === 'mehrdeutig')
-                throw new ZeigerMehrdeutig(verzeichnis, fund.kandidaten);
+                zeigerPfad = await this.zeigerWaehlen(verzeichnis, fund.kandidaten);
         }
         if (zeigerPfad === undefined) {
             ergebnis.hinweise.push(`Kein Zeiger unter ${verzeichnis}, nichts zu tun.`);
@@ -520,7 +578,7 @@ export class Anwendungsfaelle {
             if (zustand.quellen.some((q) => quelleSchluessel(q) === key))
                 continue;
             zustand.quellen.push(quelle);
-            ergebnis.gelegt.push(`Quelle ${key}`);
+            ergebnis.gelegt.push(`Quelle ${quelleAlsText(quelle)}`);
         }
         if (!zustand.arbeitsverzeichnisse.includes(verzeichnis))
             zustand.arbeitsverzeichnisse.push(verzeichnis);
@@ -615,7 +673,51 @@ export class Anwendungsfaelle {
             await harness.plugins.aktualisieren();
             pluginHarnesses.push(harness.name);
         }
-        return { checkouts, pluginHarnesses };
+        return { checkouts, pluginHarnesses, aufraeumen: await this.verwaisteAufraeumen(checkouts) };
+    }
+    /**
+     * Pfade, in die ein Link zeigt. Gelesen wird wie beim Ist-Zustand (E19): die Ziele der
+     * vorhandenen Harnesses, die Arbeitsverzeichnisse aus dem Zustand. Ein Link, dessen Quelle nicht
+     * im Zustand steht, zeigt trotzdem in einen Checkout und hält ihn.
+     */
+    async belegteCheckoutPfade() {
+        const pfade = new Set();
+        for (const zielZustand of await this.istZustand())
+            for (const eintrag of zielZustand.eintraege) {
+                if (eintrag.art === 'link')
+                    pfade.add(path.resolve(eintrag.link.checkout.pfad));
+                else if (eintrag.art === 'link-ohne-quelle')
+                    pfade.add(path.resolve(eintrag.checkoutPfad));
+            }
+        return pfade;
+    }
+    /**
+     * Verwaiste Ref-Checkouts aufräumen. Verwaist heißt: kein Link in irgendeinem Ziel zeigt hinein.
+     * Der Basis-Clone je Repo ist nie dabei, er steht in keiner Checkout-Liste (E22). Ein Checkout
+     * mit lokaler Änderung bleibt liegen und wird nur gemeldet (E15), er kommt gar nicht erst in die
+     * Frage. Gefragt wird einmal für alle Kandidaten (E28); wo niemand antwortet, gilt Nein und es
+     * wird nichts gelöscht.
+     */
+    async verwaisteAufraeumen(checkouts) {
+        const belegt = await this.belegteCheckoutPfade();
+        const verwaiste = [];
+        for (const { checkout, aktualisierung } of checkouts) {
+            if (belegt.has(path.resolve(checkout.pfad)))
+                continue;
+            // Übersprungen wird genau der Checkout mit lokaler Änderung, ein zweites Nachfragen erübrigt sich.
+            const lokaleAenderung = aktualisierung.ergebnis === 'uebersprungen';
+            verwaiste.push({ checkout, lokaleAenderung, geloescht: false });
+        }
+        const kandidaten = verwaiste.filter((v) => !v.lokaleAenderung);
+        if (kandidaten.length === 0)
+            return { verwaiste, gefragt: false };
+        if (!(await this.p.rueckfrage.bestaetigen(aufraeumFrage(kandidaten.map((k) => k.checkout)))))
+            return { verwaiste, gefragt: true };
+        for (const kandidat of kandidaten) {
+            await this.p.quellen.entfernen(kandidat.checkout);
+            kandidat.geloescht = true;
+        }
+        return { verwaiste, gefragt: true };
     }
     /**
      * Übernahme (B12, E31): fremde Symlinks eines Ziels durch eigene Links auf einen hmgr-Checkout
@@ -633,7 +735,10 @@ export class Anwendungsfaelle {
             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));
+        // Je Identität die Quelle, unter deren Schreibweise sie geführt wird (E36).
+        const bekannt = new Map();
+        for (const q of (await this.p.zustand.lesen()).quellen)
+            bekannt.set(quelleSchluessel(q), q);
         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.
@@ -661,7 +766,9 @@ export class Anwendungsfaelle {
                 liegenLassen('kein-branch');
                 continue;
             }
-            const quelle = { art: 'git', url: kopie.url };
+            // Kennt hmgr das Repo schon in anderer Schreibweise, zählt die geführte Fassung (E36).
+            const gefuehrt = bekannt.get(quelleSchluessel({ art: 'git', url: kopie.url }));
+            const quelle = gefuehrt ?? { 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);
@@ -669,8 +776,8 @@ export class Anwendungsfaelle {
                 liegenLassen('skill-unbekannt');
                 continue;
             }
-            const quelleNeu = !bekannt.has(quelleSchluessel(quelle));
-            bekannt.add(quelleSchluessel(quelle));
+            const quelleNeu = gefuehrt === undefined;
+            bekannt.set(quelleSchluessel(quelle), quelle);
             if (!probelauf) {
                 if (quelleNeu)
                     await this.quelleHinzufuegen(quelle);

package/dist/kern/modell.js

@@ -1,4 +1,5 @@
 // Begriffe aus CONTEXT.md. Nur Werte und Regeln, keine Pfade zu Dateien außerhalb des Modells.
+import { ortSchluessel, urlOrt } from "./quelle-ort.js";
 /** Ansprache eines Plugins im Zeiger und gegenüber der claude-CLI: `<plugin>@<marketplace>`. */
 export function pluginSchluessel(plugin) {
     return `${plugin.name}@${plugin.marketplace}`;
@@ -45,8 +46,22 @@ export function zielSchluessel(ziel) {
     const ort = o.art === 'home' ? 'home' : o.art === 'profil' ? `profil:${o.name}` : `dir:${o.pfad}`;
     return `${ziel.harness}/${ort}`;
 }
+/** Wie eine Quelle geschrieben steht: ihre URL oder ihr Pfad. Für Ausgaben, nicht für Vergleiche. */
+export function quelleAlsText(quelle) {
+    return quelle.art === 'git' ? quelle.url : quelle.pfad;
+}
+/**
+ * Identität einer Quelle (E36): bei einer Git-Quelle Host, Besitzer und Repo, nicht die
+ * Schreibweise der URL. SSH- und HTTPS-Form desselben Repos sind dieselbe Quelle, mit und ohne
+ * `.git`-Suffix ebenso, und der Host zählt ohne Rücksicht auf Groß- und Kleinschreibung. Ein Text,
+ * der sich nicht als URL lesen lässt, bleibt sein eigener Schlüssel. Lokale Quellen bleiben ihr
+ * Pfad (B11).
+ */
 export function quelleSchluessel(quelle) {
-    return quelle.art === 'git' ? quelle.url : `lokal:${quelle.pfad}`;
+    if (quelle.art === 'lokal')
+        return `lokal:${quelle.pfad}`;
+    const ort = urlOrt(quelle.url);
+    return ort === undefined ? quelle.url : ortSchluessel(ort);
 }
 export class NameBelegt extends Error {
     ziel;

package/dist/kern/quelle-ort.js

@@ -0,0 +1,42 @@
+// Identität einer Git-Quelle (E36): Host, Besitzer und Repo, nicht die Schreibweise der URL.
+function ohneGitSuffix(name) {
+    return name.endsWith('.git') ? name.slice(0, -4) : name;
+}
+/**
+ * Die letzten beiden nicht leeren Segmente sind Besitzer und Repo. Der Host wird kleingeschrieben,
+ * Hostnamen sind case-insensitiv; der Pfadanteil bleibt, wie er geschrieben steht (E36).
+ */
+export function ortAusSegmenten(host, segmente) {
+    const gefiltert = segmente.filter((s) => s.length > 0);
+    const repo = ohneGitSuffix(gefiltert[gefiltert.length - 1] ?? 'repo');
+    const besitzer = gefiltert[gefiltert.length - 2] ?? '_';
+    return { host: host.toLowerCase(), besitzer, repo };
+}
+/**
+ * Zerlegt eine Git-URL: `git@host:besitzer/repo.git`, `ssh://git@host/besitzer/repo`,
+ * `https://host/besitzer/repo.git`, `file:///pfad`. Ein Text, der keine URL ist, gibt undefined.
+ */
+export function urlOrt(url) {
+    const text = url.trim().replace(/\/+$/, '');
+    if (text.includes('://')) {
+        let zerlegt;
+        try {
+            zerlegt = new URL(text);
+        }
+        catch {
+            return undefined;
+        }
+        const segmente = decodeURIComponent(zerlegt.pathname).split('/');
+        // file: hat keinen Host, alle lokalen Quellen liegen unter „local".
+        if (zerlegt.protocol === 'file:')
+            return ortAusSegmenten('local', segmente);
+        return ortAusSegmenten(zerlegt.hostname, segmente);
+    }
+    const scp = /^(?:[^@/]+@)?([^@/:]+):(.+)$/.exec(text);
+    if (scp)
+        return ortAusSegmenten(scp[1], scp[2].split('/'));
+    return undefined;
+}
+export function ortSchluessel(ort) {
+    return `${ort.host}/${ort.besitzer}/${ort.repo}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmgr",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Harness Manager: Skills und Plugins für AI-Harnesses verwalten",
   "license": "MIT",
   "author": "Tim Kaufmann",