kimal3 0.1.5 → 0.2.0

package/dist/befehle/kontext-runter.js

@@ -0,0 +1,254 @@
+import { zerlege } from "../argumente.js";
+import { ruf } from "../api.js";
+import { heuteAus } from "../nachricht.js";
+import { istUnsichererPfad } from "../arbeitsplatz-dateien.js";
+import { LEER, VERWALTETE_DATEIEN, alsMerkzettel, sicherungsOrdner, sicherungsZiel, lageFuerDatei, ratNachUnberuehrt, } from "../kontext-stand.js";
+import { leseEineDatei, leseMerkzettelDatei, schreibeMerkzettelDatei, schreibeVerwalteteDatei, sichereDatei, } from "../kontext-dateien.js";
+import { ERLAUBT, absage, arbeitsplatzOderAbsage } from "./kontext-gemeinsam.js";
+/**
+ * Holt den Firmenkontext von der App und legt ihn in den verwalteten Dateien
+ * des gefundenen Arbeitsplatzes ab -- `CLAUDE.md` und die fuenf Dateien in
+ * `kontext/`.
+ *
+ * 🔴 **`kontext/kurzprofil.md` ist seit Ruling K-24 (Task 7) dabei.** Sie wurde
+ * beim ERSTEN Ausliefern gefuellt und danach nie wieder aufgefrischt -- waehrend
+ * sie selbst dem Kunden zusicherte, sie werde „zentral in der App gepflegt".
+ *
+ * 🔴 **R2 (Spec §14): Dieser Befehl fragt NIE `git status`.** Er entscheidet
+ * ausschliesslich ueber den Merkzettel (`.kimal3-stand.json`), egal ob der
+ * Ordner ein Git-Repo ist oder nicht -- sonst gaebe es zwei Verhalten fuer
+ * denselben Befehl, und das schwerer erklaerbare traefe ausgerechnet den, der
+ * Git benutzt.
+ *
+ * ⛔ **Unterhalb von `werkbank-<name>/` wird nichts geschrieben** (Spec §4).
+ * Dieser Befehl kennt genau die Pfade aus `VERWALTETE_DATEIEN`, und in keinem
+ * davon steht ein Personenname.
+ *
+ * 🔁 **Ruling T9-2:** Die Gegenrichtung, `kontextHoch`, wohnt seit dem Split
+ * von `kontext.ts` in `kontext-hoch.ts`. Beide teilen sich Fundregel,
+ * Firmenwahl-Absage und die `--firma`/`--firma-id`-Optionen ueber
+ * `kontext-gemeinsam.ts`.
+ */
+const HILFE = `
+  kimal3 kontext runter [--firma "Name" | --firma-id "…"]
+
+  Holt den Firmenkontext (CLAUDE.md + die fuenf Dateien in kontext/) und legt
+  ihn in deinem KI-Arbeitsplatz ab. Was du selbst geaendert hast, fasst der
+  Befehl nicht an -- er sagt dir, wie du es einbringst.
+
+  --firma "Name"   Noetig, wenn du zu mehreren Firmen gehoerst.
+                   Die Absage nennt dir die Namen als fertige Befehle.
+
+  --firma-id "…"   Fuer den Fall, dass zwei deiner Firmen GLEICH heissen.
+                   Auch diese Absage nennt dir fertige Befehle.
+`;
+export async function kontextRunter(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(HILFE);
+        return 0;
+    }
+    const zerlegt = zerlege(argv, ERLAUBT);
+    if (!zerlegt.ok) {
+        console.error(zerlegt.meldung);
+        return 1;
+    }
+    // 📌 Seit Task 7 gemeinsam mit `kontext hoch` und `kontext fragen`
+    // (`arbeitsplatzOderAbsage`). Hier standen dieselben vier Zeilen abgetippt;
+    // bei drei Aufrufern ist das keine Wiederholung mehr, sondern eine Falle --
+    // wer eine Zeile schaerft, schaerft eine von dreien.
+    const ordner = arbeitsplatzOderAbsage();
+    if (ordner === null)
+        return 1;
+    const wunsch = zerlegt.werte.optionen.firma;
+    const wunschId = zerlegt.werte.optionen["firma-id"];
+    const suche = new URLSearchParams();
+    if (wunsch !== undefined)
+        suche.set("firma", wunsch);
+    if (wunschId !== undefined)
+        suche.set("firma-id", wunschId);
+    const pfad = suche.toString() ? `/api/cli/kontext?${suche.toString()}` : "/api/cli/kontext";
+    const antwort = await ruf(pfad, { methode: "GET", mitAusweis: true });
+    if (antwort.status !== 200) {
+        return absage(antwort, "kontext runter");
+    }
+    // 🔴 Ein `200` mit unlesbarem Rumpf ist KEIN Erfolg -- dasselbe Muster wie
+    // in `firma-daten.ts`. `ruf` verschluckt Parse-Fehler zu `null`.
+    if (antwort.koerper === null || typeof antwort.koerper !== "object") {
+        console.error("Die Antwort war nicht lesbar. Bitte gleich noch einmal.");
+        return 3;
+    }
+    const daten = alsKontextAntwort(antwort.koerper);
+    if (daten === null) {
+        console.error("Die Antwort war nicht lesbar. Bitte gleich noch einmal.");
+        return 3;
+    }
+    const lokalerMerkzettel = leseMerkzettelDatei(ordner);
+    const heute = heuteAus(new Date());
+    const geschrieben = [];
+    const gesicherte = [];
+    const unberuehrt = [];
+    for (const verwalteterPfad of VERWALTETE_DATEIEN) {
+        const serverDatei = daten.dateien.find((d) => d.pfad === verwalteterPfad);
+        if (!serverDatei) {
+            console.error(`Die Antwort enthaelt keine Datei „${verwalteterPfad}". Bitte melden.`);
+            return 3;
+        }
+        // Zweites Netz -- s. Kommentar an `schreibeVerwalteteDatei`: `pfad` kommt
+        // hier aus der eigenen Iteration, nicht roh vom Server, trotzdem geprueft.
+        if (istUnsichererPfad(serverDatei.pfad)) {
+            console.error(`Die Antwort enthaelt einen unsicheren Pfad: „${serverDatei.pfad}". Bitte melden.`);
+            return 3;
+        }
+        const lokalGelesen = leseEineDatei(ordner, verwalteterPfad);
+        if (!lokalGelesen.ok) {
+            console.error(lokalGelesen.meldung);
+            return 1;
+        }
+        const eintrag = lokalerMerkzettel.dateien[verwalteterPfad] ?? null;
+        const serverStand = daten.merkzettel.dateien[verwalteterPfad]?.stand ?? LEER;
+        const lage = lageFuerDatei({
+            lokalerInhalt: lokalGelesen.inhalt,
+            serverInhalt: serverDatei.inhalt,
+            eintrag,
+            serverStand,
+        });
+        if (lage === "beides") {
+            // `lokalGelesen.inhalt` ist hier garantiert eine Zeichenkette:
+            // `lageFuerDatei` liefert "beides" nie, wenn `lokalerInhalt === null`.
+            const sicherung = sichereDatei(ordner, verwalteterPfad, lokalGelesen.inhalt, heute);
+            if (!sicherung.ok) {
+                console.error(sicherung.meldung);
+                return 1;
+            }
+            // Ruling T8-2: `sichereDatei` ueberschreibt nie und ueberspringt nie --
+            // `nebenVorhandener` sagt nur, ob HEUTE schon eine andere Sicherung
+            // dieser Datei existiert. Beide Faelle sind echte Erfolge und werden
+            // unten bewusst UNTERSCHIEDLICH gemeldet (§8).
+            gesicherte.push({
+                pfad: verwalteterPfad,
+                ziel: sicherung.ziel,
+                nebenVorhandener: sicherung.nebenVorhandener,
+            });
+        }
+        if (lage === "server-neuer" || lage === "beides") {
+            const geschriebenErg = schreibeVerwalteteDatei(ordner, verwalteterPfad, serverDatei.inhalt);
+            if (!geschriebenErg.ok) {
+                console.error(geschriebenErg.meldung);
+                return 1;
+            }
+            geschrieben.push(verwalteterPfad);
+        }
+        if (lage === "lokal-geaendert") {
+            unberuehrt.push(verwalteterPfad);
+        }
+    }
+    /*
+      🔴 Der Merkzettel des SERVERS wird geschrieben -- unabhaengig davon, ob in
+      diesem Lauf ueberhaupt etwas geaendert wurde. Er traegt fuer JEDE der fuenf
+      Dateien den Stand, der zum jetzt ausgelieferten Inhalt passt (§7b), auch
+      fuer die, die "schon aktuell" waren oder lokal geaendert blieben -- ein
+      lokal geaenderter Eintrag bleibt so beim naechsten Lauf ERKENNBAR lokal
+      geaendert, statt durch einen fehlenden Merkzettel-Eintrag neu "sicher" zu
+      werden.
+  
+      🔴 Task 10a: `firma_id` kommt ausdruecklich aus `daten.firma.id` -- der
+      Firma, die diese Antwort tatsaechlich beantwortet hat (`waehleFirma` in
+      der Route), nicht aus dem Merkzettel-Feld selbst. Wer zu MEHREREN Firmen
+      gehoert, soll im Ordner von Firma A niemals lesen "B hat sich geaendert".
+    */
+    const merkzettelZumSchreiben = { firma_id: daten.firma.id, dateien: daten.merkzettel.dateien };
+    const merkzettelSchreiben = schreibeMerkzettelDatei(ordner, merkzettelZumSchreiben);
+    if (!merkzettelSchreiben.ok) {
+        console.error(merkzettelSchreiben.meldung);
+        return 1;
+    }
+    // ---- Ausgabe --------------------------------------------------------
+    // 🔴 Ruling T8-2 (Fix-Runde 1): ZWEI ehrlich verschiedene Faelle, keine
+    // Pauschalmeldung mehr. "Frisch gesichert" und "zusaetzlich neben einer
+    // schon vorhandenen Sicherung von heute" sind beide echte Erfolge -- aber
+    // verschiedene, und der Mensch muss wissen, WAS mit seinem Text passiert
+    // ist. Nie ein Satz, der eine Sicherung behauptet, wo keine (mehr)
+    // entstanden ist (der urspruengliche Befund).
+    //
+    // US-7 bleibt erfuellt: Die Meldung steht VOR der "aktualisiert"-Zeile
+    // (vor dem Ergebnis) und nennt den Ordner. Die eigentliche Reihenfolge
+    // (erst sichern, dann ueberschreiben) erzwingt schon der Code oben.
+    if (gesicherte.length > 0) {
+        console.log(`Ich sichere deine lokale Fassung, bevor ich sie ersetze -- Ordner: ${sicherungsOrdner(heute)}`);
+        for (const g of gesicherte) {
+            if (g.nebenVorhandener) {
+                const bisherige = sicherungsZiel(heute, g.pfad).split("/").pop();
+                const neue = g.ziel.split("/").pop();
+                console.log(`  „${g.pfad}": Von heute gibt es schon eine Sicherung (${bisherige}) -- die bleibt ` +
+                    `unveraendert stehen. Deine neuere Fassung sichere ich zusaetzlich als ${neue}, ` +
+                    "bevor ich die Datei im Ordner ersetze.");
+            }
+            else {
+                console.log(`  „${g.pfad}" -> ${g.ziel.split("/").pop()}`);
+            }
+        }
+    }
+    if (geschrieben.length > 0) {
+        console.log(`✓ aktualisiert: ${geschrieben.join(", ")}`);
+    }
+    // §8: Ein Fehlerfall darf nie denselben Namen tragen wie ein Erfolgsfall --
+    // "nichts geschrieben" heisst hier DREI verschiedene Dinge, und die Ausgabe
+    // muss sie unterscheiden, nicht nur die Rueckgabe (alle drei geben 0).
+    if (unberuehrt.length > 0) {
+        console.log(`Ich fasse nichts an -- du hast lokal geaendert: ${unberuehrt.join(", ")}`);
+        // 🔴 Der Rat haengt an der DATEI, nicht nur an der Rolle -- s.
+        // `ratNachUnberuehrt` (kontext-stand.ts), Review-Befund F-3.
+        for (const zeile of ratNachUnberuehrt(unberuehrt, daten.rolle, daten.adminName)) {
+            console.log(zeile);
+        }
+    }
+    if (geschrieben.length === 0 && unberuehrt.length === 0) {
+        const alleLeer = VERWALTETE_DATEIEN.every((p) => (daten.merkzettel.dateien[p]?.stand ?? LEER) === LEER);
+        if (alleLeer) {
+            console.log("Deine Firma hat noch nichts hinterlegt. Bis dahin bleiben die Vordrucke stehen.");
+        }
+        else {
+            console.log("Dein Firmenkontext ist aktuell.");
+        }
+    }
+    return 0;
+}
+/** Prueft die Antwort-Form, ohne `any` -- eine falsche Form ist unlesbar, keine Ausnahme. */
+function alsKontextAntwort(koerper) {
+    if (!koerper || typeof koerper !== "object")
+        return null;
+    const k = koerper;
+    // 🔴 Task 10a: `firma.id` ist die Quelle, aus der `kontextRunter` gleich
+    // den lokalen Merkzettel stempelt -- s. Kommentar an der Schreibstelle.
+    const firmaRoh = k.firma;
+    if (!firmaRoh || typeof firmaRoh !== "object")
+        return null;
+    const firmaId = firmaRoh.id;
+    if (typeof firmaId !== "string" || firmaId.trim() === "")
+        return null;
+    const rolle = k.rolle;
+    if (rolle !== "admin" && rolle !== "member")
+        return null;
+    const adminName = k.admin_name;
+    if (adminName !== null && typeof adminName !== "string")
+        return null;
+    const dateienRoh = k.dateien;
+    if (!Array.isArray(dateienRoh))
+        return null;
+    const dateien = [];
+    for (const eintrag of dateienRoh) {
+        if (!eintrag || typeof eintrag !== "object")
+            return null;
+        const p = eintrag.pfad;
+        const i = eintrag.inhalt;
+        if (typeof p !== "string" || p.trim() === "")
+            return null;
+        if (typeof i !== "string")
+            return null;
+        dateien.push({ pfad: p, inhalt: i });
+    }
+    const merkzettel = alsMerkzettel(k.merkzettel);
+    if (merkzettel === null)
+        return null;
+    return { firma: { id: firmaId }, rolle, adminName, dateien, merkzettel };
+}

package/dist/befehle/skill-install.js

@@ -1,7 +1,9 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
+import { STEMPEL_MARKE } from "../nachricht.js";
+import { eigeneVersion } from "../version.js";
 /**
  * Namen, die frueher einmal ausgeliefert wurden und heute nicht mehr.
  *
@@ -25,6 +27,62 @@ const VERALTETE_BEFEHLE = [];
  * wird sie NICHT ueberschrieben, sondern uebersprungen und gemeldet.
  */
 const MARKE = "kimal3:erzeugt";
+/**
+ * Wohin das Skill installiert wird -- an EINER Stelle.
+ *
+ * 🔑 WARUM EXPORTIERT (Befund der vierten Review-Runde): `kimal3.ts` baute
+ * denselben Pfad ein zweites Mal zusammen, um dort den Stempel zu lesen. Zoege
+ * das Ziel je um, faende `existsSync` dort nichts, `skillZustand` antwortete
+ * "still" -- und Weg 2 waere lautlos tot. Kein Fehler, keine Meldung, nichts
+ * zum Bemerken.
+ *
+ * Dieselbe Lehre wie bei `version.ts`, nur eine Stunde spaeter: *Zwei
+ * Wahrheiten ueber denselben Ort driften, und die zweite verrottet, ohne
+ * dass jemand hinsieht.*
+ */
+export function skillOrdner() {
+    return join(homedir(), ".claude", "skills", "kimal3");
+}
+export function skillDatei() {
+    return join(skillOrdner(), "SKILL.md");
+}
+/**
+ * Haengt die eigene Versionsnummer ans ENDE des Skill-Textes.
+ *
+ * 🔴 DER STEMPEL BESCHREIBT DIE SKILL.md -- NICHT DEN GANZEN LAUF.
+ * Diese Zuordnung hat drei Review-Runden gekostet und wurde zweimal falsch
+ * entschieden; sie steht hier ausfuehrlich, damit es kein viertes Mal gibt:
+ *
+ *   Runde 2 verschob den Stempel ans Ende des Befehls, damit ein halber Lauf
+ *   nicht "alles aktuell" behauptet. Runde 3 fand eine Luecke darin, Runde 4
+ *   flickte den Rueckgabewert -- und Runde 5 zeigte, dass die ganze Richtung
+ *   falsch war: Bei JEDEM stabilen Fehlschlag danach (fremde k3*.md im
+ *   Ordner, schreibgeschuetzter Befehlsordner) ist die SKILL.md geschrieben,
+ *   aber ungestempelt. `skillZustand` antwortet dann "veraltet", die CLI
+ *   meldet TAEGLICH "deine Skilldateien sind aelter, tippe kimal3 skill
+ *   install" -- und genau dieser Befehl stellt denselben Zustand wieder her.
+ *
+ * *`skillZustand` liest die SKILL.md. Also muss der Stempel ueber die SKILL.md
+ * sprechen und ueber nichts sonst.* Ist sie geschrieben, ist sie aktuell --
+ * unabhaengig davon, was mit den Slash-Befehlen passiert ist. Deren Zustand
+ * meldet der Befehl mit Text und Rueckgabewert, sofort und einmalig; das ist
+ * der richtige Kanal dafuer, nicht ein taeglicher Hinweis, den niemand
+ * abstellen kann.
+ *
+ * 🔑 Und er entsteht in DERSELBEN Schreiboperation wie die Datei. Kein zweites
+ * Lesen, kein zweites Schreiben, kein Zustand dazwischen, in dem die Datei
+ * ohne ihren Stempel dasteht.
+ *
+ * ⚠️ Ohne eigene Nummer GAR KEIN Stempel. Ein erfundener Ersatzwert waere
+ * schlimmer als keiner: Die CLI vergliche spaeter gegen ihre eigene Erfindung.
+ * Ohne Stempel antwortet `skillZustand` "veraltet" -- die harmlose Seite.
+ */
+function mitStempel(inhalt) {
+    const eigene = eigeneVersion();
+    if (eigene === null)
+        return inhalt;
+    return `${inhalt.trimEnd()}\n\n<!-- ${STEMPEL_MARKE}${eigene} -->\n`;
+}
 /**
  * Legt das Skill UND die Slash-Befehle GLOBAL ab, damit Claude dieses Werkzeug
  * ueberall kennt -- und damit der Mensch es auch selbst ausloesen kann.
@@ -63,14 +121,46 @@ export async function skillInstall() {
     // Erfolgsprofil ein" gilt in JEDEM Ordner, nicht in einem. Wer projektlokal
     // installiert, hat das Werkzeug im naechsten Projekt nicht -- und merkt es
     // erst, wenn er dort vergeblich "fertig" sagt.
-    const zielOrdner = join(homedir(), ".claude", "skills", "kimal3");
-    const ziel = join(zielOrdner, "SKILL.md");
+    const zielOrdner = skillOrdner();
+    const ziel = skillDatei();
     // Vorher merken: "angelegt" und "aktualisiert" sind zwei verschiedene
     // Wirklichkeiten und bekommen deshalb zwei verschiedene Meldungen.
     const gabEsSchon = existsSync(ziel);
     try {
         mkdirSync(zielOrdner, { recursive: true });
-        copyFileSync(quelle, ziel);
+        /*
+          🔴 DER STEMPEL GEHOERT ANS ENDE, NIEMALS AN DEN ANFANG. SKILL.md beginnt
+          in Zeile 1 mit YAML-Frontmatter (`---`, dann `name:`). Steht davor
+          irgendetwas, ist es kein Frontmatter mehr -- der Skill wird dann gar
+          nicht geladen, und zwar OHNE Fehlermeldung. Ein Update-Hinweis, der den
+          Skill abschaltet, den er aktuell halten soll, ist der teuerste denkbare
+          Fehler in dieser Scheibe.
+    
+          Deshalb auch lesen-anhaengen-schreiben statt copyFileSync: Der Stempel
+          entsteht beim KOPIEREN, er steht nicht in der Quelle -- sonst truege das
+          Paket seine Versionsnummer an zwei Orten, und die zweite verrottet.
+    
+          🔴 OHNE eigene Versionsnummer wird GAR KEIN Stempel geschrieben, sondern
+          unveraendert kopiert. `eigeneVersion()` liefert `null`, wenn
+          `cli/package.json` fehlt oder Unsinn enthaelt. Ein Stempel mit einem
+          erfundenen Ersatzwert waere hier schlimmer als keiner: Die CLI vergliche
+          spaeter gegen ihre eigene Erfindung und meldete entweder ein Update, das
+          es nicht gibt, oder schwiege zu einem, das faellig ist. Ohne Stempel
+          antwortet `skillZustand` dagegen "veraltet" -- die harmlose Seite, denn
+          ein zweites `kimal3 skill install` kostet nichts.
+    
+          ⚠️ Die Marke `kimal3:erzeugt` (Konstante MARKE oben) steckt in
+          `STEMPEL_MARKE` und bleibt damit erhalten. Der Stempel ist eine
+          ERWEITERUNG dieser Marke, kein Ersatz -- `raeumeVeralteteAuf` und die
+          Ueberschreib-Pruefung erkennen unsere eigenen Dateien genau daran.
+    
+          📌 Er entsteht HIER, in derselben Schreiboperation wie die Datei -- und
+          zwar wieder, nachdem er drei Runden lang am Ende des Befehls stand.
+          Warum die Ruecknahme richtig ist, steht ausfuehrlich bei `mitStempel`:
+          Der Stempel spricht ueber die SKILL.md, nicht ueber den ganzen Lauf.
+        */
+        const inhalt = readFileSync(quelle, "utf8");
+        writeFileSync(ziel, mitStempel(inhalt), "utf8");
     }
     catch (fehler) {
         console.error(`Das Skill liess sich nicht schreiben: ${String(fehler)}`);
@@ -142,6 +232,22 @@ export async function skillInstall() {
         console.error("  Die oben genannten stehen; ein zweiter Lauf holt den Rest.");
         return 3;
     }
+    /*
+      🔴 Eine nicht lesbare Datei ist ein UNVOLLSTAENDIGER Lauf und bekommt
+      deshalb `3`, genau wie `gestoert` (Befund der vierten Review-Runde).
+      `3` heisst laut SKILL.md "einmal wiederholen", und das passt zur Lage:
+      Eine Datei in Benutzung ist gleich wieder frei.
+  
+      📌 Der STEMPEL haengt hier nicht mehr dran -- er entsteht beim Schreiben
+      der SKILL.md und beschreibt nur sie (ausfuehrliche Begruendung bei
+      `mitStempel` oben). Bis zur fuenften Review-Runde stand er an dieser
+      Stelle, und jeder stabile Fehlschlag danach erzeugte einen taeglichen
+      Hinweis, den kein Befolgen aufloesen konnte.
+    */
+    if (unlesbar.length > 0) {
+        console.error("  Der Lauf ist damit unvollstaendig -- ein zweiter Versuch holt den Rest.");
+        return 3;
+    }
     /*
       ⚠️ **Nicht auf einen Befehl verweisen, den wir gerade NICHT installiert
       haben** (Review-Runde 3, 2026-08-18, gemessen). Mit einer fremden