c64bridge 0.7.4 → 0.8.1

package/dist/diagnostics.js

@@ -0,0 +1,371 @@
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+let state = null;
+let handlersInstalled = false;
+let spanCounter = 0;
+const DEFAULT_OUTPUT_TAIL_CHARS = 4096;
+export function installProcessDiagnostics(component) {
+    const info = ensureState(component).info;
+    writeDiagnosticEvent("session_start", {
+        argv: process.argv.slice(2),
+        cwd: process.cwd(),
+        node: process.version,
+        pid: process.pid,
+        platform: process.platform,
+    });
+    installGlobalHandlers();
+    return info;
+}
+export function getDiagnosticsSessionInfo() {
+    return state?.info ?? null;
+}
+export function getDiagnosticsDirectory() {
+    return resolveDiagnosticsDirectory();
+}
+export function writeDiagnosticEvent(event, details) {
+    if (!isDiagnosticsEnabled()) {
+        return;
+    }
+    const current = ensureState("runtime");
+    const record = {
+        ts: new Date().toISOString(),
+        pid: process.pid,
+        sessionId: current.info.sessionId,
+        component: current.info.component,
+        event,
+        details: sanitize(details),
+    };
+    try {
+        fs.appendFileSync(current.info.filePath, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    catch (error) {
+        safeStderrWrite(`[diagnostics] failed to append event ${event}: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+export function createOutputTailCapture(name, maxChars = DEFAULT_OUTPUT_TAIL_CHARS) {
+    let stdoutTail = "";
+    let stderrTail = "";
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    return {
+        pushStdout(chunk) {
+            const text = normalizeChunk(chunk);
+            stdoutBytes += Buffer.byteLength(text, "utf8");
+            stdoutTail = keepTail(stdoutTail, text, maxChars);
+        },
+        pushStderr(chunk) {
+            const text = normalizeChunk(chunk);
+            stderrBytes += Buffer.byteLength(text, "utf8");
+            stderrTail = keepTail(stderrTail, text, maxChars);
+        },
+        snapshot() {
+            return {
+                name,
+                stdoutBytes,
+                stderrBytes,
+                stdoutTail: stdoutTail.trim(),
+                stderrTail: stderrTail.trim(),
+            };
+        },
+    };
+}
+export function beginDiagnosticSpan(category, name, details) {
+    const spanId = `${Date.now().toString(36)}-${process.pid}-${++spanCounter}`;
+    const startedAt = process.hrtime.bigint();
+    let closed = false;
+    writeDiagnosticEvent("perf_span_start", {
+        spanId,
+        category,
+        name,
+        details,
+    });
+    return {
+        spanId,
+        category,
+        name,
+        end(outcome = "ok", details) {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            writeDiagnosticEvent("perf_span_end", {
+                spanId,
+                category,
+                name,
+                outcome,
+                durationMs: roundDurationMs(startedAt),
+                details,
+            });
+        },
+    };
+}
+export async function withDiagnosticSpan(category, name, details, fn) {
+    const span = beginDiagnosticSpan(category, name, details);
+    try {
+        const result = await fn();
+        span.end("ok");
+        return result;
+    }
+    catch (error) {
+        span.end("error", { error });
+        throw error;
+    }
+}
+export function listDiagnosticSessionFiles(directory = resolveDiagnosticsDirectory()) {
+    if (!fs.existsSync(directory)) {
+        return [];
+    }
+    return fs.readdirSync(directory)
+        .filter((entry) => entry.endsWith(".ndjson"))
+        .map((entry) => path.join(directory, entry))
+        .sort((left, right) => right.localeCompare(left));
+}
+export function resolveDiagnosticSessionFile(scope = "current") {
+    if (scope === "current") {
+        return getDiagnosticsSessionInfo()?.filePath ?? null;
+    }
+    const [latest] = listDiagnosticSessionFiles();
+    return latest ?? null;
+}
+export function readDiagnosticRecords(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return [];
+    }
+    const text = fs.readFileSync(filePath, "utf8").trim();
+    if (!text) {
+        return [];
+    }
+    return text.split("\n")
+        .map((line) => JSON.parse(line));
+}
+export function summarizeDiagnosticsSession(filePath, options = {}) {
+    const records = readDiagnosticRecords(filePath);
+    const maxEntries = Math.max(1, Math.min(200, Math.trunc(options.maxEntries ?? 25)));
+    const spanGroups = new Map();
+    const toolCalls = new Map();
+    for (const record of records) {
+        if (record.event === "perf_span_end") {
+            const details = (record.details ?? {});
+            const category = String(details.category ?? "unknown");
+            const name = String(details.name ?? "unknown");
+            const key = `${category}:${name}`;
+            const existing = spanGroups.get(key) ?? {
+                category,
+                name,
+                count: 0,
+                totalDurationMs: 0,
+                maxDurationMs: 0,
+                lastOutcome: undefined,
+            };
+            const durationMs = Number(details.durationMs ?? 0);
+            existing.count += 1;
+            existing.totalDurationMs += durationMs;
+            existing.maxDurationMs = Math.max(existing.maxDurationMs, durationMs);
+            existing.lastOutcome = typeof details.outcome === "string" ? details.outcome : existing.lastOutcome;
+            spanGroups.set(key, existing);
+            continue;
+        }
+        if (record.event === "mcp_call_tool_ok" || record.event === "mcp_call_tool_failed") {
+            const details = (record.details ?? {});
+            const name = String(details.name ?? "unknown");
+            const existing = toolCalls.get(name) ?? {
+                name,
+                count: 0,
+                errorCount: 0,
+                totalLatencyMs: 0,
+                maxLatencyMs: 0,
+            };
+            const latencyMs = Number(details.latencyMs ?? 0);
+            existing.count += 1;
+            existing.totalLatencyMs += latencyMs;
+            existing.maxLatencyMs = Math.max(existing.maxLatencyMs, latencyMs);
+            if (record.event === "mcp_call_tool_failed" || details.isError === true) {
+                existing.errorCount += 1;
+            }
+            toolCalls.set(name, existing);
+        }
+    }
+    const topSpans = Array.from(spanGroups.values())
+        .map((entry) => ({
+        category: entry.category,
+        name: entry.name,
+        count: entry.count,
+        totalDurationMs: roundNumber(entry.totalDurationMs),
+        avgDurationMs: roundNumber(entry.totalDurationMs / Math.max(1, entry.count)),
+        maxDurationMs: roundNumber(entry.maxDurationMs),
+        lastOutcome: entry.lastOutcome,
+    }))
+        .sort((left, right) => right.totalDurationMs - left.totalDurationMs)
+        .slice(0, maxEntries);
+    const summarizedToolCalls = Array.from(toolCalls.values())
+        .map((entry) => ({
+        name: entry.name,
+        count: entry.count,
+        errorCount: entry.errorCount,
+        totalLatencyMs: roundNumber(entry.totalLatencyMs),
+        avgLatencyMs: roundNumber(entry.totalLatencyMs / Math.max(1, entry.count)),
+        maxLatencyMs: roundNumber(entry.maxLatencyMs),
+    }))
+        .sort((left, right) => right.totalLatencyMs - left.totalLatencyMs);
+    const startedAt = records[0]?.ts ?? null;
+    const endedAt = records.length > 0 ? (records[records.length - 1]?.ts ?? null) : null;
+    const durationMs = startedAt && endedAt
+        ? roundNumber(new Date(endedAt).getTime() - new Date(startedAt).getTime())
+        : 0;
+    const timeline = options.includeTimeline
+        ? records.slice(-maxEntries).map((record) => ({
+            ts: record.ts,
+            event: record.event,
+            details: record.details,
+        }))
+        : undefined;
+    return {
+        filePath,
+        sessionId: records[0]?.sessionId ?? null,
+        component: records[0]?.component ?? null,
+        eventCount: records.length,
+        startedAt,
+        endedAt,
+        durationMs,
+        topSpans,
+        toolCalls: summarizedToolCalls,
+        ...(timeline ? { timeline } : {}),
+    };
+}
+function ensureState(component) {
+    if (state) {
+        return state;
+    }
+    const info = createSessionInfo(component);
+    state = { info };
+    return state;
+}
+function createSessionInfo(component) {
+    const directory = resolveDiagnosticsDirectory();
+    fs.mkdirSync(directory, { recursive: true });
+    const startedAt = new Date().toISOString().replace(/[:.]/g, "-");
+    const safeComponent = component.replace(/[^a-z0-9_-]+/gi, "-").replace(/^-+|-+$/g, "") || "runtime";
+    const sessionId = `${startedAt}-${process.pid}`;
+    const filePath = path.join(directory, `${sessionId}-${safeComponent}.ndjson`);
+    return { component: safeComponent, directory, filePath, sessionId };
+}
+function resolveDiagnosticsDirectory() {
+    const configured = process.env.C64BRIDGE_DIAGNOSTICS_DIR?.trim();
+    if (configured) {
+        return path.resolve(configured);
+    }
+    return path.join(os.homedir(), ".c64bridge", "diagnostics");
+}
+function installGlobalHandlers() {
+    if (!isDiagnosticsEnabled() || handlersInstalled) {
+        return;
+    }
+    handlersInstalled = true;
+    process.on("warning", (warning) => {
+        writeDiagnosticEvent("process_warning", warning);
+    });
+    process.on("unhandledRejection", (reason, promise) => {
+        writeDiagnosticEvent("unhandled_rejection", {
+            reason,
+            promise: Object.prototype.toString.call(promise),
+        });
+    });
+    process.on("uncaughtExceptionMonitor", (error, origin) => {
+        writeDiagnosticEvent("uncaught_exception", { error, origin });
+    });
+    process.on("beforeExit", (code) => {
+        writeDiagnosticEvent("before_exit", { code });
+    });
+    process.on("exit", (code) => {
+        writeDiagnosticEvent("process_exit", { code });
+    });
+}
+function isDiagnosticsEnabled() {
+    if (process.env.C64BRIDGE_DISABLE_DIAGNOSTICS === "1") {
+        return false;
+    }
+    if (process.env.NODE_ENV === "test" && process.env.C64BRIDGE_ENABLE_TEST_DIAGNOSTICS !== "1") {
+        return false;
+    }
+    return true;
+}
+function sanitize(value, depth = 0) {
+    if (value instanceof Error) {
+        const extra = value;
+        return {
+            name: value.name,
+            message: value.message,
+            stack: limitString(value.stack ?? "", 8000),
+            code: extra.code,
+            cause: depth < 3 ? sanitize(extra.cause, depth + 1) : undefined,
+        };
+    }
+    if (typeof value === "string") {
+        return limitString(value, 8000);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (Buffer.isBuffer(value)) {
+        return {
+            type: "Buffer",
+            byteLength: value.length,
+            previewHex: value.subarray(0, 64).toString("hex"),
+        };
+    }
+    if (ArrayBuffer.isView(value)) {
+        return {
+            type: value.constructor.name,
+            byteLength: value.byteLength,
+        };
+    }
+    if (Array.isArray(value)) {
+        if (depth >= 3) {
+            return `[Array(${value.length})]`;
+        }
+        return value.slice(0, 25).map((entry) => sanitize(entry, depth + 1));
+    }
+    if (typeof value === "object") {
+        if (depth >= 3) {
+            return `[Object ${value?.constructor?.name ?? "Object"}]`;
+        }
+        const entries = Object.entries(value).slice(0, 25);
+        return Object.fromEntries(entries.map(([key, entry]) => [key, sanitize(entry, depth + 1)]));
+    }
+    return String(value);
+}
+function normalizeChunk(chunk) {
+    return typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+}
+function keepTail(existing, next, maxChars) {
+    const combined = `${existing}${next}`;
+    if (combined.length <= maxChars) {
+        return combined;
+    }
+    return combined.slice(combined.length - maxChars);
+}
+function limitString(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, maxChars)}…[truncated ${value.length - maxChars} chars]`;
+}
+function roundDurationMs(startedAt) {
+    return roundNumber(Number(process.hrtime.bigint() - startedAt) / 1000000);
+}
+function roundNumber(value) {
+    return Number(value.toFixed(3));
+}
+function safeStderrWrite(text) {
+    try {
+        process.stderr.write(text);
+    }
+    catch {
+        // Ignore stderr write failures during crash handling.
+    }
+}

package/dist/mcp/metadata.js

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+function readJsonFile(url) {
+    return JSON.parse(readFileSync(url, "utf8"));
+}
+const packageJson = readJsonFile(new URL("../../package.json", import.meta.url));
+const manifestJson = readJsonFile(new URL("../../mcp.json", import.meta.url));
+function normalizeRepositoryUrl(repository) {
+    if (!repository) {
+        return undefined;
+    }
+    if (typeof repository === "string") {
+        return repository.trim().length > 0 ? repository.trim() : undefined;
+    }
+    if (typeof repository === "object"
+        && repository !== null
+        && typeof repository.url === "string"
+        && repository.url.trim().length > 0) {
+        return repository.url.trim();
+    }
+    return undefined;
+}
+const implementationInfo = Object.freeze({
+    name: manifestJson.name ?? packageJson.name ?? "c64bridge",
+    version: packageJson.version ?? manifestJson.version ?? "0.0.0",
+});
+const projectMetadata = Object.freeze({
+    name: implementationInfo.name,
+    version: implementationInfo.version,
+    description: manifestJson.description ?? packageJson.description ?? "",
+    license: manifestJson.license ?? packageJson.license ?? "",
+    repository: normalizeRepositoryUrl(manifestJson.repository ?? packageJson.repository),
+    transports: manifestJson.type === "stdio" ? ["stdio"] : ["stdio"],
+});
+export function getMcpServerImplementationInfo() {
+    return implementationInfo;
+}
+export function getMcpProjectMetadata() {
+    return projectMetadata;
+}