kimal3 0.1.5 → 0.2.0

package/dist/kontext-dateien.js

@@ -0,0 +1,248 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { istUnsichererPfad } from "./arbeitsplatz-dateien.js";
+import { MERKZETTEL_PFAD, VERWALTETE_DATEIEN, arbeitsplatzAus, leseMerkzettel, schreibeMerkzettel, sicherungsZiel, } from "./kontext-stand.js";
+/**
+ * Das Dateisystem hinter `kimal3 kontext runter` -- Ordner finden, die
+ * verwalteten Dateien lesen, sichern, schreiben, den Merkzettel lesen und
+ * schreiben.
+ *
+ * 🔴 **Ruling T8-1: Die reine Fundregel `arbeitsplatzAus` wird hier NICHT noch
+ * einmal geschrieben** -- sie steht seit Task 1 in `kontext-stand.ts` und wird
+ * hier nur VERBRAUCHT (`findeArbeitsplatz` unten fuellt sie mit echten
+ * Kandidaten vom Dateisystem). Zwei Fassungen derselben Fundregel waeren
+ * dieselbe zweite Wahrheit, die dieses Projekt schon bei `werkbankAusDateien`
+ * teuer bezahlt hat.
+ *
+ * ⚠️ **Dieselben Netze wie in `arbeitsplatz-dateien.ts`**, aus denselben,
+ * teuer bezahlten Gruenden: `existsSync`/`statSync`/`readFileSync` gehoeren
+ * in ein EIGENES `try` -- ein `EACCES` fluege sonst bis in den Auffang-Block
+ * von `kimal3.ts`, der "kimal3 ist gerade nicht erreichbar" druckt und `3`
+ * zurueckgibt. Der Mensch suchte den Fehler dann beim Server, obwohl er auf
+ * seiner eigenen Platte sitzt -- und `3` heisst "gleich noch einmal", was
+ * hier nie helfen kann. Ein Schreibfehler (Platte voll, `EACCES`) gibt
+ * deshalb `1` zurueck, nicht `3`.
+ */
+/** Ist `pfad` (relativ zu `wurzel`) ein lesbarer ORDNER? Unlesbar zaehlt als "nein". */
+function istLesbarerOrdner(pfad) {
+    try {
+        return existsSync(pfad) && statSync(pfad).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Ist `pfad` (relativ zu `wurzel`) eine lesbare DATEI? Unlesbar zaehlt als "nein". */
+function istLesbareDatei(pfad) {
+    try {
+        return existsSync(pfad) && statSync(pfad).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Von `start` aufwaerts nach dem Arbeitsplatz suchen -- die Kandidaten kommen
+ * von UNTEN NACH OBEN, `start` zuerst.
+ *
+ * 🔑 Diese Funktion FUELLT nur die Kandidatenliste vom Dateisystem; die
+ * eigentliche Entscheidung ("welcher Ordner gewinnt") trifft `arbeitsplatzAus`
+ * in `kontext-stand.ts` (Ruling P-4/T8-1).
+ *
+ * Die Schleife hat eine Sicherheitsgrenze (200 Ebenen): `dirname()` konvergiert
+ * auf jedem realen Dateisystem zur Wurzel, aber ein Netzlaufwerk mit einem
+ * kaputten Elternverweis soll trotzdem nie eine Endlosschleife erzeugen.
+ */
+export function findeArbeitsplatz(start) {
+    const kandidaten = [];
+    let aktuell = resolve(start);
+    for (let i = 0; i < 200; i++) {
+        kandidaten.push({
+            pfad: aktuell,
+            hatKontext: istLesbarerOrdner(join(aktuell, "kontext")),
+            hatClaude: istLesbareDatei(join(aktuell, "CLAUDE.md")),
+        });
+        const eltern = dirname(aktuell);
+        if (eltern === aktuell)
+            break;
+        aktuell = eltern;
+    }
+    return arbeitsplatzAus(kandidaten);
+}
+/**
+ * Eine der verwalteten Dateien lesen -- fehlend wird zu `inhalt: null`,
+ * NICHT zu einem Fehler (ein frisch geklonter Ordner hat oft noch keine).
+ */
+export function leseEineDatei(ordner, pfad) {
+    const ort = join(ordner, ...pfad.split("/"));
+    try {
+        if (!existsSync(ort))
+            return { ok: true, inhalt: null };
+        if (!statSync(ort).isFile()) {
+            return {
+                ok: false,
+                meldung: `„${pfad}" existiert, ist aber keine Datei -- ich fasse das nicht an. Bitte pruefen.`,
+            };
+        }
+        return { ok: true, inhalt: readFileSync(ort, "utf8") };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Ich komme an „${pfad}" nicht heran: ${fehler instanceof Error ? fehler.message : String(fehler)}. ` +
+                "Das liegt an diesem Rechner, nicht am Server -- Rechte pruefen.",
+        };
+    }
+}
+/**
+ * Den lokalen Merkzettel lesen. Unlesbar oder nicht vorhanden -> leeres
+ * Objekt, GENAU wie `leseMerkzettel(null)` -- der sichere Fall aus §7b: "wer
+ * nichts weiss, loescht nichts". Eine unlesbare Datei fuehrt also zur
+ * Sicherung vor dem Ueberschreiben, nie zum stillen Verlust.
+ */
+export function leseMerkzettelDatei(ordner) {
+    try {
+        const ort = join(ordner, MERKZETTEL_PFAD);
+        const roh = existsSync(ort) ? readFileSync(ort, "utf8") : null;
+        return leseMerkzettel(roh);
+    }
+    catch {
+        return leseMerkzettel(null);
+    }
+}
+/** Den Merkzettel schreiben -- MIT dem Stand, der zum ausgelieferten Inhalt passt. */
+export function schreibeMerkzettelDatei(ordner, m) {
+    try {
+        const ort = join(ordner, MERKZETTEL_PFAD);
+        writeFileSync(ort, schreibeMerkzettel(m), "utf8");
+        return { ok: true };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Der Merkzettel liess sich nicht schreiben: ${fehler instanceof Error ? fehler.message : String(fehler)}. Das liegt an diesem Rechner, nicht am Server -- Platz und Rechte pruefen.`,
+        };
+    }
+}
+/**
+ * Der naechste NICHT belegte Sicherungspfad -- reine Rechnung, kein
+ * Dateisystem. `istBelegt(pfad)` sagt, ob dieser Pfad schon existiert (der
+ * Aufrufer entscheidet, WIE das geprueft wird); diese Funktion zaehlt vom
+ * Basisnamen aus hoch, bis eine freie Stelle gefunden ist.
+ *
+ * 🔴 **Ruling T8-2 (Review-Fund 1, Fix-Runde 1).** Vorher gab `sichereDatei`
+ * bei einem belegten Ziel `{ uebersprungen: true }` zurueck und schrieb dabei
+ * GAR NICHTS -- eine zweite Aenderung am selben Tag verschwand beim
+ * anschliessenden Ueberschreiben spurlos, waehrend die Ausgabe im Befehl
+ * "gesichert" behauptete. **Diese Funktion darf deshalb NIE einen belegten
+ * Pfad als Endergebnis zurueckgeben und NIE einen Pfad, der schon existiert,
+ * unkommentiert ueberschreiben lassen** -- sie liefert IMMER einen Pfad, der
+ * (laut `istBelegt`) frei ist.
+ *
+ * ⚠️ **Die erste Sicherung eines Tages -- der Basisname -- bleibt fuer immer
+ * unangetastet.** Das ist US-7 woertlich: "Laeuft der Befehl am selben Tag
+ * ein zweites Mal, wird die erste Sicherung NICHT ueberschrieben." Wer diese
+ * Funktion vereinfacht ("dann eben doch den Basisnamen nehmen, wenn `nummer`
+ * gross wird") loescht genau die Sicherung, die US-7 ausdruecklich schuetzt.
+ * Eine dritte, vierte, ... Aenderung bekommt stattdessen einen weiteren,
+ * eigenen Namen daneben -- nie einen schon vergebenen.
+ */
+export function naechstesFreiesSicherungsziel(basisZielRel, istBelegt) {
+    if (!istBelegt(basisZielRel))
+        return basisZielRel;
+    for (let nummer = 2; nummer <= 1000; nummer++) {
+        const kandidat = nummeriertesZiel(basisZielRel, nummer);
+        if (!istBelegt(kandidat))
+            return kandidat;
+    }
+    /*
+      Praktisch unerreichbar (1000 Sicherungen derselben Datei am selben Tag).
+      Diese reine Funktion wirft nicht -- sie liefert den letzten geprueften
+      Namen, und der Aufrufer (`sichereDatei`) trifft beim tatsaechlichen
+      Schreiben erneut auf `existsSync` und meldet dort einen echten Fehler,
+      statt dass eine reine Rechnung selbst eine Ausnahme auslöst.
+    */
+    return nummeriertesZiel(basisZielRel, 1000);
+}
+/**
+ * `kontext/vorher-2026-08-21/firma.md` + 2 -> `.../firma-2.md`.
+ *
+ * Nur der DATEINAME bekommt die Nummer, nicht der Ordner -- alle
+ * verwalteten Dateien landen weiter FLACH im selben `vorher-<datum>/`
+ * (unveraendert gegenueber `sicherungsZiel`).
+ */
+function nummeriertesZiel(basisZielRel, nummer) {
+    const teile = basisZielRel.split("/");
+    const dateiname = teile.pop() ?? "";
+    const punkt = dateiname.lastIndexOf(".");
+    const name = punkt === -1 ? dateiname : dateiname.slice(0, punkt);
+    const endung = punkt === -1 ? "" : dateiname.slice(punkt);
+    return [...teile, `${name}-${nummer}${endung}`].join("/");
+}
+/**
+ * Die lokale Fassung von `pfad` nach `kontext/vorher-<datum>/` sichern --
+ * FLACH, mit dem Basisnamen (`sicherungsZiel`), oder -- ist der schon belegt
+ * -- unter einem durchnummerierten Namen DANEBEN (`naechstesFreiesSicherungsziel`,
+ * Ruling T8-2).
+ *
+ * 🔴 **Es wird NIE uebersprungen und NIE ueberschrieben.** Beides waere eine
+ * stille Datenvernichtung: Ueberspringen ohne Kopie loescht die zweite
+ * Aenderung eines Tages beim anschliessenden Ueberschreiben der Arbeitsdatei;
+ * Ueberschreiben der ersten Sicherung verstoesst woertlich gegen US-7.
+ * `nebenVorhandener: true` im Ergebnis sagt dem Aufrufer, dass HEUTE schon
+ * eine andere Sicherung derselben Datei existiert -- er muss das in der
+ * Ausgabe unterscheiden (§8: kein Fehlerfall traegt den Namen eines
+ * Erfolgsfalls, und hier sind es zwei verschiedene ECHTE Erfolgsfaelle).
+ */
+export function sichereDatei(ordner, pfad, inhalt, datum) {
+    const basisZielRel = sicherungsZiel(datum, pfad);
+    const istBelegt = (zielRel) => existsSync(join(ordner, ...zielRel.split("/")));
+    const zielRel = naechstesFreiesSicherungsziel(basisZielRel, istBelegt);
+    const ort = join(ordner, ...zielRel.split("/"));
+    try {
+        mkdirSync(dirname(ort), { recursive: true });
+        writeFileSync(ort, inhalt, "utf8");
+        return { ok: true, ziel: zielRel, nebenVorhandener: zielRel !== basisZielRel };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Sichern von „${pfad}" ist fehlgeschlagen: ${fehler instanceof Error ? fehler.message : String(fehler)}. Das liegt an diesem Rechner, nicht am Server -- Platz und Rechte pruefen.`,
+        };
+    }
+}
+/**
+ * Eine der verwalteten Dateien schreiben.
+ *
+ * 🔴 **Positivliste, keine Verbotsliste** (Auflage aus dem Brief): `pfad` muss
+ * WOERTLICH einer der Eintraege aus `VERWALTETE_DATEIEN` sein, sonst wird
+ * NICHTS geschrieben. Diese Funktion bekommt `pfad` im echten Ablauf immer aus
+ * der eigenen Iteration ueber `VERWALTETE_DATEIEN` (nie roh aus der Server-
+ * Antwort) -- die Pruefung hier ist trotzdem ausdruecklich verlangt und bleibt
+ * als zweites Netz stehen, falls sich der Aufrufer einmal aendert.
+ *
+ * ⚠️ `istUnsichererPfad` zusaetzlich, aus demselben Grund wie in
+ * `dateienSchreiben` (`arbeitsplatz-dateien.ts`): Ein Pfad kommt letztlich aus
+ * einer Server-Antwort, und eine Pruefung, die nur dort gilt, wo man sie
+ * gerade braucht, ist keine Pruefung dieser Funktion.
+ */
+export function schreibeVerwalteteDatei(ordner, pfad, inhalt) {
+    if (!VERWALTETE_DATEIEN.includes(pfad)) {
+        return { ok: false, meldung: `„${pfad}" ist keine verwaltete Datei -- wird nicht geschrieben. Bitte melden.` };
+    }
+    if (istUnsichererPfad(pfad)) {
+        return { ok: false, meldung: `„${pfad}" ist kein sicherer Pfad -- wird nicht geschrieben. Bitte melden.` };
+    }
+    const ort = join(ordner, ...pfad.split("/"));
+    try {
+        mkdirSync(dirname(ort), { recursive: true });
+        writeFileSync(ort, inhalt, "utf8");
+        return { ok: true };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Schreiben von „${pfad}" ist fehlgeschlagen: ${fehler instanceof Error ? fehler.message : String(fehler)}. Das liegt an diesem Rechner, nicht am Server -- Platz und Rechte pruefen.`,
+        };
+    }
+}