kimal3 0.1.5 → 0.1.6

package/README.md

@@ -35,7 +35,8 @@ auf und bestätigst den Code dort in deinem eingeloggten Konto — so wie bei `g
 kimal3                    Zeigt, ob dieser Rechner angemeldet ist
 kimal3 login              Diesen Rechner mit deinem Konto verbinden
 kimal3 skill install      Claude beibringen, dieses Werkzeug zu benutzen — und dir die /k3-Befehle geben
-kimal3 arbeitsplatz neu   Deine KI-Arbeitsplatz-Vorlage als Ordner anlegen
+kimal3 arbeitsplatz neu   Den ganzen KI-Arbeitsplatz anlegen — Firmenebene und Werkbank
+kimal3 werkbank neu       Nur eine eigene Werkbank in einer bestehenden Firma anlegen
 kimal3 projekt neu …      Ein Projekt ins Erfolgsprofil eintragen
 kimal3 projekt liste      Deine eingetragenen Projekte anzeigen
 kimal3 firma daten        Die Daten deiner Firma holen, damit Claude sie auswerten kann
@@ -68,6 +69,23 @@ Für Skripte und für Claude selbst:
 Der Unterschied zwischen `3` und `4` ist Absicht: Bei `3` lohnt ein zweiter Versuch,
 bei `4` nie.
 
+## Update-Hinweise
+
+Steht eine neuere Fassung bereit, schreibt `kimal3` nach dem Befehl eine eingerückte
+Zeile — höchstens **einmal am Tag**:
+
+```
+  →  kimal3 0.2.0 ist da.  npm i -g kimal3@latest && kimal3 skill install
+```
+
+Sie geht auf **stderr**, nicht auf stdout: `kimal3 firma daten > firma.json` bleibt
+damit sauberes JSON. Sie **ändert den Rückgabewert nicht** — eine `0` bleibt eine `0`.
+Und `kimal3` **installiert nichts von selbst**; der Befehl steht in der Zeile, ausführen
+tust du ihn.
+
+Dasselbe gilt für die Skill-Dateien: Sind die in `~/.claude/skills/kimal3/` älter als
+das installierte Werkzeug, sagt `kimal3` es — dafür braucht es kein Netz.
+
 ## Voraussetzungen
 
 Node.js 20 oder neuer. Sonst nichts — das Werkzeug bringt **keine fremden Bibliotheken**

package/dist/api.js

@@ -1,4 +1,6 @@
 import { BASIS_URL, leseAnmeldung } from "./anmeldung.js";
+import { hinweisAusAntwort } from "./nachricht.js";
+import { eigeneVersion } from "./version.js";
 export class NichtAngemeldet extends Error {
     constructor() { super("nicht angemeldet"); }
 }
@@ -18,6 +20,26 @@ export async function ruf(pfad, optionen = {}) {
             throw new NichtAngemeldet();
         kopf.Authorization = `Bearer ${a.schluessel}`;
     }
+    /*
+      🔴 DIE CLI SAGT, WER SIE IST -- und nur daran haengt der Server den
+      Update-Hinweis an (Befund der fuenften Review-Runde).
+  
+      Ohne diesen Kopf bekaeme JEDER Client das neue Antwortfeld, auch die
+      veroeffentlichte 0.1.5. Und die gibt bei `firma daten` den GANZEN Rumpf als
+      JSON aus: Sobald jemand eine Nachricht einschaltet, stuende ein
+      `"hinweis": {…}` mitten in den Firmendaten -- bei genau den Leuten, fuer
+      die der Kanal ueberhaupt gebaut wurde, und in einer Ausgabe, die SKILL.md
+      als Firmendaten zu lesen anweist. Gemessen am 2026-08-21 mit der echten
+      0.1.5 aus npm.
+  
+      🔑 Damit ist US-7 ("die alte CLI verhaelt sich unveraendert") keine
+      Hoffnung mehr, sondern gebaut: Wer den Kopf nicht schickt, bekommt nichts.
+      Und die Nummer ist ASCII -- der ByteString-Fehler, an dem der Hinweis
+      selbst scheitern wuerde, trifft sie nicht.
+    */
+    const version = eigeneVersion();
+    if (version !== null)
+        kopf["X-Kimal3-Version"] = version;
     const methode = optionen.methode ?? "POST";
     // Content-Type nur, wenn wirklich etwas im Rumpf steht. Ein GET mit
     // "Content-Type: application/json" und ohne Rumpf ist eine Luege ueber die
@@ -29,7 +51,45 @@ export async function ruf(pfad, optionen = {}) {
         headers: kopf,
         body: methode === "POST" ? JSON.stringify(optionen.koerper ?? {}) : undefined,
     });
-    return { status: antwort.status, koerper: await antwort.json().catch(() => null) };
+    const koerper = await antwort.json().catch(() => null);
+    merkeHinweis(koerper);
+    return { status: antwort.status, koerper };
+}
+/**
+ * Der zuletzt mitgereiste Update-Hinweis.
+ *
+ * 🔑 WARUM EINE MODULVARIABLE UND KEINE AUSGABE AN DIESER STELLE: `ruf()`
+ * laeuft MITTEN in einem Befehl, teils mehrfach. Wer hier schreibt, schneidet
+ * die Projektliste entzwei -- die Spec verlangt ausdruecklich, dass die Zeile
+ * NACH der Ausgabe steht, nie mittendrin (US-1). Ausgegeben wird genau einmal,
+ * ganz am Ende, in kimal3.ts.
+ */
+let letzterHinweis = null;
+function merkeHinweis(koerper) {
+    const h = hinweisAusAntwort(koerper);
+    if (h)
+        letzterHinweis = h;
+    /*
+      🔴 UND DANN RAUS AUS DEM RUMPF. Gemessen am 2026-08-21: `firma daten` gibt
+      den GANZEN Rumpf als JSON aus (`console.log(JSON.stringify(koerper))`) --
+      der Hinweis stuende dort mitten in den Firmendaten UND darunter noch einmal
+      als →-Zeile. Zweimal dasselbe, und einmal davon an einer Stelle, an der
+      Claude Daten erwartet.
+  
+      🔑 Warum HIER und nicht in `firma-daten.ts`: Dort waere es eine Kopie, die
+      beim naechsten Befehl fehlt, der einen Rumpf durchreicht. Wer den Hinweis
+      ENTGEGENNIMMT, nimmt ihn auch heraus -- dann kann kein Befehl ihn
+      versehentlich mit ausgeben, auch keiner, den es noch nicht gibt.
+  
+      Das `delete` trifft ein frisch aus `json()` erzeugtes Objekt, das sonst
+      niemand haelt.
+    */
+    if (koerper && typeof koerper === "object") {
+        delete koerper.hinweis;
+    }
+}
+export function gemerkterHinweis() {
+    return letzterHinweis;
 }
 /** Holt ein Textfeld aus einer Antwort, ohne `any`. */
 export function feld(koerper, name) {

package/dist/arbeitsplatz-dateien.js

@@ -0,0 +1,268 @@
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { feld, ruf } from "./api.js";
+import { schlussFehler } from "./fehler.js";
+/*
+  🔁 Die Ableitung „welcher Unterordner ist die Werkbank" wohnt seit dem
+  2026-08-20 in `werkbank-name.ts` -- gemeinsam mit der App, die sie fuer `/pro`
+  genauso braucht. Sie stand vorher hier UND in `src/lib/arbeitsplatz/ausliefern.ts`,
+  wortgleich. *Zwei Kopien einer Ableitung sind dieselbe zweite Wahrheit wie zwei
+  Kopien des Namens, nur besser getarnt.*
+*/
+export { werkbankAusDateien as werkbankOrdner } from "./werkbank-name.js";
+/**
+ * Holt die Vorlage von der App — **eine** Route für beide Befehle.
+ *
+ * 🔑 `werkbank neu` bekommt bewusst KEINE eigene Route: Es sind dieselben
+ * Dateien, dieselbe Pro-Prüfung, derselbe Ausweis. Eine zweite Route wäre eine
+ * zweite Tür, die man einzeln absichern und einzeln nachmessen müsste — für
+ * exakt denselben Inhalt. Der Ausschnitt entsteht hier auf dem Rechner.
+ */
+export async function vorlageHolen() {
+    const antwort = await ruf("/api/cli/arbeitsplatz", { methode: "GET", mitAusweis: true });
+    if (antwort.status === 200) {
+        const daten = alsVorlageAntwort(antwort.koerper);
+        if (daten === null) {
+            console.error("Die Antwort war nicht lesbar. Bitte gleich noch einmal.");
+            return { ok: false, wert: 3 };
+        }
+        return { ok: true, daten };
+    }
+    const meldung = feld(antwort.koerper, "meldung") ?? "Das hat nicht geklappt.";
+    // 402 VOR 401: Beide heissen "kommst hier nicht rein", verlangen aber
+    // Gegenteiliges. Wer sie zusammenwirft, raet `kimal3 login` -- und der
+    // meldet sich dann erfolgreich an, ohne dass es etwas aendert.
+    if (antwort.status === 402) {
+        console.error(meldung);
+        return { ok: false, wert: 4 };
+    }
+    if (antwort.status === 401) {
+        console.error(`${meldung} Bitte \`kimal3 login\` ausführen.`);
+        return { ok: false, wert: 2 };
+    }
+    // 🔑 Den Rest entscheidet `schlussFehler` fuer alle Befehle gemeinsam --
+    // insbesondere die `404` (die App kennt die Route noch nicht) und `429`/
+    // `408` (ueberlastet, wiederholbar).
+    const schluss = schlussFehler(antwort.status, meldung);
+    console.error(schluss.text);
+    return { ok: false, wert: schluss.wert };
+}
+/** Prueft die Antwort-Form, ohne `any` -- eine falsche Form ist unlesbar, keine Ausnahme. */
+function alsVorlageAntwort(koerper) {
+    if (!koerper || typeof koerper !== "object")
+        return null;
+    const wurzel = koerper.wurzel;
+    const dateienRoh = koerper.dateien;
+    if (typeof wurzel !== "string" || wurzel.trim() === "")
+        return null;
+    if (!Array.isArray(dateienRoh))
+        return null;
+    const dateien = [];
+    for (const eintrag of dateienRoh) {
+        if (!eintrag || typeof eintrag !== "object")
+            return null;
+        const pfad = eintrag.pfad;
+        const inhalt = eintrag.inhalt;
+        if (typeof pfad !== "string" || pfad.trim() === "")
+            return null;
+        if (typeof inhalt !== "string")
+            return null;
+        dateien.push({ pfad, inhalt });
+    }
+    return { wurzel, dateien };
+}
+/**
+ * 🔴 **Nie ueberschreiben** -- die wichtigste Eigenschaft dieser Befehle.
+ * Angelegt wird nur, wenn am Zielort NICHTS liegt oder ein LEERER Ordner.
+ *
+ * Genauer, weil hier zwei verschiedene Absagen stecken:
+ * - Zielort ist eine **Datei** (auch eine leere): Abbruch. An einer Datei kann
+ *   kein Ordner entstehen, ohne sie zu loeschen -- und geloescht wird nichts.
+ * - Zielort ist ein **Ordner mit Inhalt**: Abbruch.
+ * - Zielort ist ein **leerer Ordner** oder gibt es nicht: los geht's.
+ *
+ * ⚠️ **Hier stand "eine leere Datei ... ist kein Hindernis"** (Review-Runde 4 zu
+ * PR #24) -- das war nie wahr. Wer `touch Mein-KI-Arbeitsplatz` gemacht hat oder
+ * wessen Editor eine leere Datei dieses Namens liegen liess, bekam den Abbruch,
+ * waehrend der Kommentar Durchlass versprach.
+ * *Die Prueffrage aus CLAUDE.md: Beschreibt das ein Verhalten, das jemand WILL --
+ * oder nur eines, das PASSIERT?* Hier wollte niemand das Beschriebene; der Code
+ * war richtig und der Satz darueber falsch.
+ *
+ * 🆕 **Neu am 2026-08-20:** `hinweis` — was die Absage **im Zweig „Ordner
+ * existiert und ist nicht leer"** zum Weitermachen raet. Nur dort: Seit
+ * Review-Runde 1 traegt er ein `cd` in den Zielordner, und in eine Datei oder
+ * einen unlesbaren Ordner kann man nicht hineinwechseln (Runde 2). Die beiden
+ * anderen Zweige haben ihren eigenen Satz.
+ * Der Rat stand dreimal fest getippt als `kimal3 arbeitsplatz neu <anderer-name>`
+ * im Text. Für `werkbank neu` wäre er falsch — und ein Rat, der in den falschen
+ * Befehl schickt, ist schlimmer als keiner.
+ *
+ * 🔴 **Und er trägt den GANZEN Rat, nicht nur den Befehl** (Messung am selben
+ * Tag, auf der Kundenstrecke). In der ersten Fassung war `hinweis` ein Befehl,
+ * und der Rahmensatz `Gib einen anderen Namen an:` gehörte dieser Datei. Nach
+ * der Umbenennung las sich das so:
+ *
+ *     Gib einen anderen Namen an: kimal3 werkbank neu <dein-vorname>
+ *
+ * Einen anderen Namen kann man für den obersten Ordner seit der Umbenennung
+ * gerade **nicht** mehr geben — genau deshalb wurde der Rat ausgetauscht. *Wer
+ * nur das Ziel eines Satzes austauschbar macht, aber nicht seine Aussage, hat
+ * die halbe Wahrheit festgenagelt.*
+ */
+export function dateienSchreiben(dateien, ordnerName, hinweis) {
+    // 🔴 B-7: eine leere Lieferung ist ein FEHLERFALL, kein Erfolg mit null
+    // Dateien -- sonst meldet der Befehl "✓ 0 Dateien angelegt." und legt dabei
+    // nicht einmal einen Ordner an. Derselbe Rueckgabewert wie bei anderen
+    // unlesbaren Antworten (3): der Nutzer hat hier nichts falsch gemacht.
+    if (dateien.length === 0) {
+        console.error("Die Antwort enthielt keine einzige Datei -- das ist kein gueltiges Ergebnis.");
+        console.error("Bitte gleich noch einmal versuchen.");
+        return 3;
+    }
+    const ziel = resolve(ordnerName);
+    /*
+      🔴 Diese drei Aufrufe brauchen ein eigenes Netz (Review-Runde 3). Sie lagen
+      ausserhalb jedes `try`: Ist der Zielordner vorhanden, aber nicht lesbar
+      (fremder Besitzer, gesperrte Netzfreigabe -- EACCES), flog `readdirSync`
+      bis in den Auffang-Block von `kimal3.ts` durch. Der druckt dann
+      „kimal3 ist gerade nicht erreichbar." und gibt 3 zurueck.
+  
+      Das ist gleich doppelt falsch: Der Mensch sucht den Fehler beim Server,
+      obwohl er auf seiner eigenen Platte sitzt -- und 3 heisst fuer Claude laut
+      SKILL.md „gleich noch einmal versuchen", was hier nie helfen kann.
+      *Ein Fehlerfall darf nie denselben Namen tragen wie ein anderer.*
+    */
+    try {
+        if (existsSync(ziel)) {
+            if (!statSync(ziel).isDirectory()) {
+                /*
+                  🔴 **Hier stand der `hinweis`** (Review-Runde 2 zu PR #25). Seit Runde 1
+                  enthaelt er ein `cd` in den Zielordner -- und in eine DATEI kann man
+                  nicht hineinwechseln. Der Rat war in diesem Zweig unausfuehrbar.
+                  *Ein Parameter, der zu einem Zweig passt, gehoert nicht in alle drei.*
+                */
+                console.error(`„${ordnerName}" gibt es schon -- als DATEI, nicht als Ordner.`);
+                console.error("Benenn die Datei um oder geh in einen anderen Ordner.");
+                return 1;
+            }
+            /*
+              ⚠️ **Betriebssystem-Krimskrams zaehlt nicht als Inhalt** (Review-Runde 5).
+              `readdirSync` zaehlte vorher ALLES. Wer den Ordner angelegt und ihn nur
+              einmal im Finder (`.DS_Store`) oder Explorer (`desktop.ini`) geoeffnet
+              hat, bekam "gibt es schon und ist nicht leer" fuer einen Ordner, der fuer
+              ihn leer AUSSIEHT -- und keine Chance zu verstehen, warum. *Ein Grund, den
+              der Mensch nicht sehen kann, ist keine Begruendung, sondern eine Absage.*
+      
+              Bewusst eine geschlossene Liste und kein "alles, was mit Punkt anfaengt":
+              Eine `.env` oder ein `.git` IST Inhalt, und den fassen wir nicht an.
+            */
+            const OS_KRIMSKRAMS = [".DS_Store", "desktop.ini", "Thumbs.db"];
+            const echterInhalt = readdirSync(ziel).filter((n) => !OS_KRIMSKRAMS.includes(n));
+            if (echterInhalt.length > 0) {
+                console.error(`Der Ordner „${ordnerName}" gibt es schon und ist nicht leer.`);
+                console.error("Ich fasse ihn nicht an -- so geht nie versehentlich eigene Arbeit verloren.");
+                console.error(hinweis);
+                return 1;
+            }
+        }
+    }
+    catch (fehler) {
+        console.error(`Ich komme an den Ordner „${ordnerName}" nicht heran.`);
+        console.error(`Grund: ${fehler instanceof Error ? fehler.message : String(fehler)}`);
+        // ⚠️ Ebenfalls OHNE den `hinweis` (Runde 2): Wer den Ordner nicht lesen darf,
+        // kann auch nicht hineinwechseln. Hier hilft nur, was schon dasteht.
+        console.error("Das liegt an diesem Rechner, nicht am Server -- Rechte pruefen.");
+        return 1;
+    }
+    // 🔴 B-6: ALLE Pfade pruefen, BEVOR die erste Datei geschrieben wird. Wuerde
+    // erst waehrend des Schreibens geprueft, koennte ein unsicherer Pfad mitten
+    // in der Liste einen halb beschriebenen Ordner hinterlassen -- der naechste
+    // Versuch liefe dann in die "nicht leer"-Absage oben, ohne dass der Nutzer
+    // je erfaehrt, dass der Ordner unvollstaendig ist.
+    for (const datei of dateien) {
+        if (istUnsichererPfad(datei.pfad)) {
+            console.error(`Die Antwort enthaelt einen unsicheren Pfad: „${datei.pfad}". Bitte melden.`);
+            return 3;
+        }
+    }
+    try {
+        for (const datei of dateien) {
+            const ort = join(ziel, ...datei.pfad.split("/"));
+            mkdirSync(dirname(ort), { recursive: true });
+            // 🔑 B-2-Folge: Platzhalter wie [DATUM] fuellt seit PR #24 der SERVER
+            // (`src/lib/arbeitsplatz/ausliefern.ts`), fuer beide Auslieferungswege
+            // gleichzeitig -- Download auf `/pro` UND diese CLI. Wuerde die CLI
+            // zusaetzlich selbst ersetzen, gaebe es wieder zwei Wahrheiten ueber
+            // denselben Inhalt (genau das war der urspruengliche Befund). Die CLI
+            // schreibt den Inhalt deshalb hier UNVERAENDERT auf die Platte.
+            writeFileSync(ort, datei.inhalt, "utf8");
+        }
+    }
+    catch (fehler) {
+        /*
+          🔴 **Hier stand `return 3` (Review-Runde 5 zu PR #24).** `3` heisst laut
+          `cli/skill/SKILL.md` "voruebergehende Stoerung -- gleich noch einmal
+          versuchen". Ein voller Datentraeger oder ein EACCES ist aber keine
+          Server-Stoerung, und der zweite Versuch kann gar nicht mehr gutgehen:
+          Der Zielordner EXISTIERT jetzt und ist nicht leer, also faellt der Lauf
+          oben in die Nicht-leer-Wache und endet mit `1` = "Eingabe passt nicht".
+          Claude sagt dem Menschen dann, sein Ordnername sei falsch -- und der
+          wahre Grund (Platte voll) kommt nie an.
+    
+          Dieselbe Begruendung steht 40 Zeilen weiter oben schon einmal, beim
+          `readdirSync`-catch. *Ein Fehler, der einmal verstanden und
+          aufgeschrieben wurde, ist im Nachbar-catch trotzdem wieder neu.*
+        */
+        console.error(`Schreiben fehlgeschlagen: ${fehler instanceof Error ? fehler.message : String(fehler)}`);
+        console.error(`Der Ordner „${ordnerName}" ist dadurch UNVOLLSTAENDIG -- er darf geloescht werden.`);
+        console.error("Das liegt an diesem Rechner, nicht am Server -- Platz und Rechte pruefen.");
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Ein `..`-Segment oder ein absoluter Pfad duerften das Ziel verlassen.
+ *
+ * 🔴 B-8: Zerlegt an `/` UND `\` -- eine fehlerhafte oder manipulierte
+ * Server-Antwort koennte sonst mit `..\..\boese.md` durchkommen. `join()`
+ * trennt unter Windows auch am Backslash, dieser Schutz muss also beide
+ * Trenner kennen wie `join()` selbst.
+ */
+/**
+ * Taugt das als **Ordnername**? — schaerfer als `istUnsichererPfad`.
+ *
+ * 🔴 **Review-Runde 2 zu PR #25, und der Kommentar daneben war der Beweis.**
+ * `istUnsichererPfad` prueft einen PFAD: Es faengt `..` und absolute Pfade. Ein
+ * Ordner_name_ ist aber etwas Engeres — er ist **ein** Pfadteil. Und genau die
+ * beiden Werte, die als Pfadteil sinnlos sind, kommen durch:
+ *
+ *     ""   aus einer Antwort mit `/CLAUDE.md`   -> resolve("")  = das aktuelle Verzeichnis
+ *     "."  aus einer Antwort mit `./CLAUDE.md`  -> resolve(".") = das aktuelle Verzeichnis
+ *
+ * In einem LEEREN Ordner haette `werkbank neu` die Dateien damit einfach dorthin
+ * geschrieben, wo der Mensch steht — und die Firmen-Wache daneben wird dabei
+ * still gruen, weil `firmenEbeneAus` genau diese Pfade ueberspringt.
+ *
+ * ⚠️ **In der Fassung von Runde 1 stand als Begruendung, `""` sei ungefaehrlich,
+ * „weil sonst die Wache oben schon rot waere".** Diese Wache ist in genau
+ * diesem Fall gruen. *Ein Kommentar, der eine Luecke mit einer anderen Wache
+ * begruendet, muss diese Wache im FEHLERFALL gelesen haben, nicht im Normalfall.*
+ *
+ * 🔑 Positiv formuliert statt negativ: Ein Ordnername ist EIN Teil, und dieser
+ * Teil ist weder leer noch `.` noch `..`. Eine Liste dessen, was verboten ist,
+ * waere beim naechsten Sonderfall wieder unvollstaendig.
+ */
+export function istUnsichererOrdnername(name) {
+    if (istUnsichererPfad(name))
+        return true;
+    const teile = name.split(/[\\/]/);
+    if (teile.length !== 1)
+        return true;
+    return teile[0] === "" || teile[0] === ".";
+}
+export function istUnsichererPfad(pfad) {
+    if (pfad.startsWith("/") || /^[a-zA-Z]:/.test(pfad))
+        return true;
+    return pfad.split(/[\\/]/).some((teil) => teil === "..");
+}