layoutbridge-light 0.0.0-stage → 1.0.1

package/dist/src/mcp/logging.js

@@ -0,0 +1,271 @@
+/**
+ * Protokoll: eine Zeile je Aufruf (Spezifikation, allgemeine Anforderung 11).
+ * Jede Instanz schreibt in eine eigene Datei, damit sich mehrere Server nicht
+ * gegenseitig ins Protokoll schreiben.
+ *
+ * Wichtig: nie auf die Standardausgabe schreiben – dort laeuft das
+ * MCP-Protokoll. Nur in die Datei und notfalls auf die Standardfehlerausgabe.
+ *
+ * Datensparsamkeit (Auftrag A-8 des Vermarktungsprojekts, 13.09.2026,
+ * Vermerk E-64): Der Aufrufsatz `args` wird nicht mehr roh geschrieben.
+ * Festgehalten werden die Parameternamen; Werte nur dort, wo sie fuer die
+ * Fehlersuche noetig und harmlos sind – Zahlen, Wahrheitswerte, Kennungen,
+ * Indizes, Aufzaehlungswerte. Zeichenketten, die Dokumentinhalt sein
+ * koennen, werden durch eine Laengenangabe ersetzt. Pfade behalten ihre
+ * Form, das Benutzerverzeichnis wird durch "~" ersetzt. Wie tief
+ * protokolliert wird, steuert LAYOUTBRIDGE_SPM_LOG_LEVEL.
+ */
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { LICENSE_TERMS_URL, SUPPORT_EMAIL } from './product-info.js';
+import { envName, PRODUCT } from './product.js';
+export const DEFAULT_LOG_LEVEL = 'basic';
+export const DEFAULT_LOG_KEEP_DAYS = 30;
+/** Laengste Zeichenkette, die auch ausserhalb der Inhaltsfelder im Klartext bleibt. */
+const MAX_PLAIN_STRING = 60;
+/** Laengster Pfad, der im Klartext bleibt. */
+const MAX_PATH_STRING = 300;
+/** Hoechstzahl protokollierter Eintraege je Liste oder Objekt. */
+const MAX_ITEMS = 20;
+/**
+ * Parameter, deren Wert Dokumentinhalt sein kann. Ihr Wert wird immer
+ * ersetzt – bei Zeichenketten durch die Laengenangabe, bei Listen und
+ * Objekten durch die Zahl der Eintraege. Zahlen und Wahrheitswerte bleiben
+ * (z. B. `rows` als Zeilenzahl in create_table).
+ */
+const CONTENT_KEYS = [
+    'cells',
+    'content',
+    'find',
+    'initial_text',
+    'marker',
+    'replace',
+    'rows',
+    'style_map',
+    'template',
+    'text',
+    'text_after',
+    'text_before',
+    'values',
+];
+function isContentKey(key) {
+    if (CONTENT_KEYS.includes(key))
+        return true;
+    return key.endsWith('_text') || key.endsWith('_texts');
+}
+/** Zeichen zaehlen, nicht Bytes. */
+export function charCount(value) {
+    return Array.from(value).length;
+}
+function textNote(value) {
+    return '<Text, ' + String(charCount(value)) + ' Zeichen>';
+}
+/** Benutzerverzeichnis in einem Text durch "~" ersetzen. */
+export function maskHome(value, home = homedir()) {
+    if (home.length < 2)
+        return value;
+    return value.split(home).join('~');
+}
+function looksLikePath(value) {
+    return value.includes('/') || value.includes('\\') || /^[A-Za-z]:/.test(value);
+}
+function filterValue(key, value, home, depth) {
+    if (value === null)
+        return null;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (isContentKey(key)) {
+        if (typeof value === 'string')
+            return textNote(value);
+        if (Array.isArray(value))
+            return '<Liste, ' + String(value.length) + ' Eintraege>';
+        if (typeof value === 'object')
+            return '<Objekt, ' + String(Object.keys(value).length) + ' Felder>';
+        return '<Wert>';
+    }
+    if (typeof value === 'string') {
+        const masked = maskHome(value, home);
+        if (value.includes('\n'))
+            return textNote(value);
+        /*
+         * Pfade bleiben lesbar – ohne sie ist ein Ablagefehler nicht zu finden.
+         * Der Benutzername ist heraus, und eine Zeile ohne Umbruch, die einen
+         * Trenner enthaelt, ist kein Fliesstext.
+         */
+        if (looksLikePath(value))
+            return charCount(value) > MAX_PATH_STRING ? textNote(value) : masked;
+        if (charCount(value) > MAX_PLAIN_STRING)
+            return textNote(value);
+        return masked;
+    }
+    if (depth >= 3)
+        return '<verschachtelt>';
+    if (Array.isArray(value)) {
+        const shown = value.slice(0, MAX_ITEMS).map((item) => filterValue(key, item, home, depth + 1));
+        if (value.length > MAX_ITEMS)
+            shown.push('<' + String(value.length - MAX_ITEMS) + ' weitere>');
+        return shown;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        const out = {};
+        let count = 0;
+        for (const innerKey of Object.keys(record)) {
+            if (count >= MAX_ITEMS) {
+                out['…'] = '<' + String(Object.keys(record).length - MAX_ITEMS) + ' weitere>';
+                break;
+            }
+            out[innerKey] = filterValue(innerKey, record[innerKey], home, depth + 1);
+            count += 1;
+        }
+        return out;
+    }
+    return '<Wert>';
+}
+/** Aufrufsatz fuer das Protokoll entschaerfen (Stufe "basic"). */
+export function filterArgs(args, home = homedir()) {
+    const out = {};
+    for (const key of Object.keys(args)) {
+        out[key] = filterValue(key, args[key], home, 0);
+    }
+    return out;
+}
+/** Protokollzeile fuer die Stufe "basic" aufbereiten. */
+export function filterEntry(entry, home = homedir()) {
+    return {
+        ...entry,
+        args: filterArgs(entry.args, home),
+        error_message: entry.error_message === null ? null : maskHome(entry.error_message, home),
+        warnings: entry.warnings.map((warning) => maskHome(warning, home)),
+    };
+}
+export function readLogLevel(env = process.env, product = PRODUCT) {
+    const raw = env[envName('LOG_LEVEL', product)];
+    if (raw === undefined)
+        return DEFAULT_LOG_LEVEL;
+    const value = raw.trim().toLowerCase();
+    if (value === 'off' || value === 'basic' || value === 'full')
+        return value;
+    return DEFAULT_LOG_LEVEL;
+}
+/** Aufbewahrungsfrist in Tagen; 0 schaltet das Aufraeumen ab. */
+export function readLogKeepDays(env = process.env, product = PRODUCT) {
+    const raw = env[envName('LOG_KEEP_DAYS', product)];
+    if (raw === undefined || raw.trim().length === 0)
+        return DEFAULT_LOG_KEEP_DAYS;
+    const value = Number(raw.trim());
+    if (!Number.isFinite(value) || value < 0)
+        return DEFAULT_LOG_KEEP_DAYS;
+    return Math.floor(value);
+}
+export function defaultLogDirectory(product = PRODUCT) {
+    const fromEnv = process.env[envName('LOG_DIR', product)];
+    if (fromEnv !== undefined && fromEnv.length > 0)
+        return fromEnv;
+    if (platform() === 'darwin') {
+        return join(homedir(), 'Library', 'Logs', product.dataDirName);
+    }
+    return join(homedir(), '.' + product.dataDirName, 'logs');
+}
+function twoDigits(value) {
+    return String(value).padStart(2, '0');
+}
+/**
+ * Protokolldateien loeschen, die aelter als `keepDays` Tage sind. Das Datum
+ * kommt aus dem Dateinamen; gerechnet wird ab dem Ende des genannten Tages,
+ * damit nichts zu frueh verschwindet. Gibt die geloeschten Namen zurueck.
+ */
+export function removeOldLogs(directory, keepDays, now = new Date()) {
+    if (keepDays <= 0)
+        return [];
+    const cutoff = now.getTime() - keepDays * 24 * 60 * 60 * 1000;
+    let names;
+    try {
+        names = readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+    const removed = [];
+    for (const name of names) {
+        const match = /^(\d{4})-(\d{2})-(\d{2})_pid\d+\.log$/.exec(name);
+        if (match === null)
+            continue;
+        const endOfDay = Date.parse(match[1] + '-' + match[2] + '-' + match[3] + 'T23:59:59.999Z');
+        if (Number.isNaN(endOfDay) || endOfDay >= cutoff)
+            continue;
+        try {
+            unlinkSync(join(directory, name));
+            removed.push(name);
+        }
+        catch {
+            /* schon weg oder nicht loeschbar – kein Grund fuer einen Abbruch */
+        }
+    }
+    return removed;
+}
+export class CallLogger {
+    file;
+    level;
+    removedLogs;
+    home;
+    broken = false;
+    constructor(directory = defaultLogDirectory(), now = new Date(), options = {}) {
+        this.level = options.level ?? readLogLevel();
+        this.home = options.home ?? homedir();
+        const stamp = now.getFullYear() +
+            '-' + twoDigits(now.getMonth() + 1) +
+            '-' + twoDigits(now.getDate());
+        this.file = join(directory, `${stamp}_pid${process.pid}.log`);
+        this.removedLogs = removeOldLogs(directory, options.keepDays ?? readLogKeepDays(), now);
+        if (this.level === 'off') {
+            this.broken = true;
+            return;
+        }
+        try {
+            mkdirSync(directory, { recursive: true });
+        }
+        catch (error) {
+            this.broken = true;
+            process.stderr.write(`[${PRODUCT.packageName}] no log directory: ${String(error)}\n`);
+            return;
+        }
+        this.writeLine({
+            ts: new Date().toISOString(),
+            event: 'start',
+            log_level: this.level,
+            note: this.level === 'full'
+                ? 'Log level "full": tool arguments are written unfiltered, including document text and paths with your user name. Set ' + envName('LOG_LEVEL') + '=basic when the support case is closed.'
+                : 'Log level "basic": argument names with harmless values only; text is reduced to its length, paths hide the user name.',
+            removed_old_logs: this.removedLogs.length,
+            /* Lizenzbedingungen und Support-Adresse in der Startzeile des Protokolls (A-11 Nr. 3, A-10 Nr. 1). */
+            license_terms: LICENSE_TERMS_URL,
+            support: SUPPORT_EMAIL,
+        });
+    }
+    log(entry) {
+        if (this.broken)
+            return;
+        const prepared = this.level === 'full' ? entry : filterEntry(entry, this.home);
+        this.writeLine({ ts: new Date().toISOString(), ...prepared });
+    }
+    writeLine(record) {
+        if (this.broken)
+            return;
+        try {
+            appendFileSync(this.file, JSON.stringify(record) + '\n', 'utf8');
+        }
+        catch (error) {
+            this.broken = true;
+            process.stderr.write(`[${PRODUCT.packageName}] cannot write log: ${String(error)}\n`);
+        }
+    }
+}
+/** Protokollsenke, die nichts tut – fuer Tests. */
+export class NullLogger {
+    log() {
+        /* absichtlich leer */
+    }
+}
+//# sourceMappingURL=logging.js.map