@graphty/remote-logger 0.0.1 → 1.1.1

package/src/server/log-server.ts

@@ -0,0 +1,571 @@
+/**
+ * Remote Log Server - A standalone HTTP/HTTPS log server for remote debugging.
+ *
+ * Features:
+ * - HTTPS with auto-generated self-signed certs or custom certs
+ * - Receives logs from browser via POST /log
+ * - Pretty terminal output with colors
+ * - REST API for querying logs
+ * - Optional file logging for Claude Code to read
+ *
+ * Usage:
+ *   npx remote-log-server --port 9080
+ *   npx remote-log-server --cert /path/to/cert.crt --key /path/to/key.key
+ */
+
+import * as fs from "fs";
+import * as http from "http";
+import * as https from "https";
+import { URL } from "url";
+
+import { certFilesExist, generateSelfSignedCert, readCertFiles } from "./self-signed-cert.js";
+
+// ANSI color codes for terminal output
+const colors = {
+    reset: "\x1b[0m",
+    bright: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m",
+    bgRed: "\x1b[41m",
+    bgYellow: "\x1b[43m",
+};
+
+export interface LogServerOptions {
+    /** Port to listen on (default: 9080) */
+    port?: number;
+    /** Hostname to bind to (default: localhost) */
+    host?: string;
+    /** Path to SSL certificate file */
+    certPath?: string;
+    /** Path to SSL private key file */
+    keyPath?: string;
+    /** Path to file for writing logs (optional) */
+    logFile?: string;
+    /** Use HTTP instead of HTTPS (default: false) */
+    useHttp?: boolean;
+    /** Suppress startup banner (default: false) */
+    quiet?: boolean;
+}
+
+export interface LogEntry {
+    time: string;
+    level: string;
+    message: string;
+}
+
+interface LogBatch {
+    sessionId: string;
+    logs: LogEntry[];
+}
+
+// Store for remote logs by session
+const remoteLogs = new Map<string, LogEntry[]>();
+
+// File stream for log file
+let logFileStream: fs.WriteStream | null = null;
+
+/**
+ * Clear all stored logs.
+ * Useful for testing.
+ */
+export function clearLogs(): void {
+    remoteLogs.clear();
+}
+
+/**
+ * Format log level for terminal output with colors.
+ * @param level - The log level string
+ * @returns Colored and formatted log level string
+ */
+function formatLogLevel(level: string): string {
+    switch (level.toUpperCase()) {
+        case "ERROR":
+            return `${colors.bgRed}${colors.white} ERROR ${colors.reset}`;
+        case "WARN":
+        case "WARNING":
+            return `${colors.bgYellow}${colors.bright} WARN  ${colors.reset}`;
+        case "INFO":
+            return `${colors.blue} INFO  ${colors.reset}`;
+        case "DEBUG":
+            return `${colors.cyan} DEBUG ${colors.reset}`;
+        case "TRACE":
+            return `${colors.dim} TRACE ${colors.reset}`;
+        case "LOG":
+        default:
+            return `${colors.green} LOG   ${colors.reset}`;
+    }
+}
+
+/**
+ * Display a log entry in the terminal.
+ * @param sessionId - The session ID for this log entry
+ * @param log - The log entry to display
+ * @param quiet - If true, suppress terminal output
+ */
+function displayLog(sessionId: string, log: LogEntry, quiet: boolean): void {
+    if (!quiet) {
+        const time = new Date(log.time).toLocaleTimeString();
+        const level = formatLogLevel(log.level);
+        const session = `${colors.cyan}[${sessionId.substring(0, 12)}]${colors.reset}`;
+
+        // Truncate very long messages for display
+        let { message } = log;
+        if (message.length > 1000) {
+            message = `${message.substring(0, 1000)}... [truncated]`;
+        }
+
+        // eslint-disable-next-line no-console
+        console.log(`${time} ${session} ${level} ${message}`);
+    }
+
+    // Write to log file if configured
+    if (logFileStream) {
+        const logLine = JSON.stringify({
+            time: log.time,
+            sessionId,
+            level: log.level,
+            message: log.message,
+        });
+        logFileStream.write(`${logLine}\n`);
+    }
+}
+
+/**
+ * Handle incoming HTTP request.
+ * @param req - The incoming HTTP request
+ * @param res - The HTTP response object
+ * @param host - The server hostname
+ * @param port - The server port number
+ * @param useHttps - Whether HTTPS is being used
+ * @param quiet - If true, suppress terminal output
+ */
+function handleRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    host: string,
+    port: number,
+    useHttps: boolean,
+    quiet: boolean,
+): void {
+    // CORS headers
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+
+    const url = req.url ?? "/";
+    const protocol = useHttps ? "https" : "http";
+
+    // Handle log endpoint - receive logs from browser
+    if (url === "/log" && req.method === "POST") {
+        let body = "";
+        req.on("data", (chunk: Buffer) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => {
+            try {
+                const data = JSON.parse(body) as LogBatch;
+                const { sessionId, logs } = data;
+
+                // Initialize session if new
+                if (!remoteLogs.has(sessionId)) {
+                    remoteLogs.set(sessionId, []);
+                    if (!quiet) {
+                        // eslint-disable-next-line no-console
+                        console.log(
+                            `\n${colors.bright}${colors.magenta}═══════════════════════════════════════════════════════════${colors.reset}`,
+                        );
+                        // eslint-disable-next-line no-console
+                        console.log(`${colors.bright}${colors.magenta}  NEW SESSION: ${sessionId}${colors.reset}`);
+                        // eslint-disable-next-line no-console
+                        console.log(
+                            `${colors.bright}${colors.magenta}═══════════════════════════════════════════════════════════${colors.reset}\n`,
+                        );
+                    }
+                }
+
+                const sessionLogs = remoteLogs.get(sessionId);
+                if (!sessionLogs) {
+                    // Should not happen since we just set it above, but satisfy TypeScript
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Internal error" }));
+                    return;
+                }
+
+                // Display and store each log
+                for (const log of logs) {
+                    sessionLogs.push(log);
+                    displayLog(sessionId, log, quiet);
+                }
+
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ success: true }));
+            } catch (error) {
+                if (!quiet) {
+                    console.error("Error parsing log data:", error);
+                }
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Invalid JSON" }));
+            }
+        });
+        return;
+    }
+
+    // Handle logs viewer endpoint - GET all logs
+    if (url === "/logs" && req.method === "GET") {
+        const allLogs: Record<string, LogEntry[]> = {};
+        for (const [sessionId, logs] of remoteLogs) {
+            allLogs[sessionId] = logs;
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(allLogs, null, 2));
+        return;
+    }
+
+    // Handle recent logs endpoint - GET last N logs across all sessions
+    if (url.startsWith("/logs/recent") && req.method === "GET") {
+        const urlObj = new URL(url, `${protocol}://${host}:${port}`);
+        const count = parseInt(urlObj.searchParams.get("n") ?? "50", 10);
+        const errorsOnly = urlObj.searchParams.get("errors") === "true";
+
+        // Collect all logs with session info
+        const allLogs: (LogEntry & { sessionId: string })[] = [];
+        for (const [sessionId, logs] of remoteLogs) {
+            for (const log of logs) {
+                if (!errorsOnly || log.level.toUpperCase() === "ERROR") {
+                    allLogs.push({ sessionId, ...log });
+                }
+            }
+        }
+
+        // Sort by time descending and take last N
+        allLogs.sort((a, b) => new Date(b.time).getTime() - new Date(a.time).getTime());
+        const recentLogs = allLogs.slice(0, count).reverse(); // Reverse to show oldest first
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+            JSON.stringify(
+                {
+                    total: allLogs.length,
+                    showing: recentLogs.length,
+                    logs: recentLogs,
+                },
+                null,
+                2,
+            ),
+        );
+        return;
+    }
+
+    // Handle errors-only endpoint
+    if (url === "/logs/errors" && req.method === "GET") {
+        const errorLogs: (LogEntry & { sessionId: string })[] = [];
+        for (const [sessionId, logs] of remoteLogs) {
+            for (const log of logs) {
+                if (log.level.toUpperCase() === "ERROR") {
+                    errorLogs.push({ sessionId, ...log });
+                }
+            }
+        }
+        errorLogs.sort((a, b) => new Date(a.time).getTime() - new Date(b.time).getTime());
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+            JSON.stringify(
+                {
+                    total: errorLogs.length,
+                    logs: errorLogs,
+                },
+                null,
+                2,
+            ),
+        );
+        return;
+    }
+
+    // Handle clear logs endpoint
+    if (url === "/logs/clear" && req.method === "POST") {
+        remoteLogs.clear();
+        if (!quiet) {
+            // eslint-disable-next-line no-console
+            console.log(`\n${colors.yellow}Logs cleared${colors.reset}\n`);
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ success: true }));
+        return;
+    }
+
+    // Health check endpoint
+    if (url === "/health" && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok", sessions: remoteLogs.size }));
+        return;
+    }
+
+    // Default: 404
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+}
+
+/**
+ * Print startup banner.
+ * @param host - The server hostname
+ * @param port - The server port number
+ * @param useHttps - Whether HTTPS is being used
+ */
+function printBanner(host: string, port: number, useHttps: boolean): void {
+    const protocol = useHttps ? "https" : "http";
+
+    // eslint-disable-next-line no-console
+    console.log("");
+    // eslint-disable-next-line no-console
+    console.log(
+        `${colors.bright}${colors.cyan}════════════════════════════════════════════════════════════${colors.reset}`,
+    );
+    // eslint-disable-next-line no-console
+    console.log(`${colors.bright}${colors.cyan}  Remote Log Server${colors.reset}`);
+    // eslint-disable-next-line no-console
+    console.log(
+        `${colors.bright}${colors.cyan}════════════════════════════════════════════════════════════${colors.reset}`,
+    );
+    // eslint-disable-next-line no-console
+    console.log("");
+    // eslint-disable-next-line no-console
+    console.log(
+        `${colors.green}Server running at:${colors.reset} ${colors.bright}${protocol}://${host}:${port}/${colors.reset}`,
+    );
+    // eslint-disable-next-line no-console
+    console.log("");
+    // eslint-disable-next-line no-console
+    console.log(`${colors.yellow}API Endpoints:${colors.reset}`);
+    // eslint-disable-next-line no-console
+    console.log(`  ${colors.cyan}POST /log         ${colors.reset} - Receive logs from browser`);
+    // eslint-disable-next-line no-console
+    console.log(`  ${colors.cyan}GET  /logs        ${colors.reset} - Get all logs as JSON`);
+    // eslint-disable-next-line no-console
+    console.log(`  ${colors.cyan}GET  /logs/recent ${colors.reset} - Get last 50 logs (?n=100 for more)`);
+    // eslint-disable-next-line no-console
+    console.log(`  ${colors.cyan}GET  /logs/errors ${colors.reset} - Get only error logs`);
+    // eslint-disable-next-line no-console
+    console.log(`  ${colors.cyan}POST /logs/clear  ${colors.reset} - Clear all logs`);
+    // eslint-disable-next-line no-console
+    console.log(`  ${colors.cyan}GET  /health      ${colors.reset} - Health check`);
+    // eslint-disable-next-line no-console
+    console.log("");
+    // eslint-disable-next-line no-console
+    console.log(`${colors.dim}Remote logs will appear below:${colors.reset}`);
+    // eslint-disable-next-line no-console
+    console.log(`${colors.cyan}────────────────────────────────────────────────────────────${colors.reset}`);
+}
+
+/**
+ * Start the log server.
+ * @param options - Server configuration options
+ * @returns The HTTP or HTTPS server instance
+ */
+export function startLogServer(options: LogServerOptions = {}): http.Server | https.Server {
+    const port = options.port ?? 9080;
+    const host = options.host ?? "localhost";
+    const useHttp = options.useHttp ?? false;
+    const quiet = options.quiet ?? false;
+
+    // Set up log file if specified
+    if (options.logFile) {
+        logFileStream = fs.createWriteStream(options.logFile, { flags: "a" });
+        if (!quiet) {
+            // eslint-disable-next-line no-console
+            console.log(`${colors.green}Writing logs to: ${options.logFile}${colors.reset}`);
+        }
+    }
+
+    // Determine SSL configuration
+    let server: https.Server | http.Server;
+
+    if (useHttp) {
+        // Plain HTTP server
+        server = http.createServer((req, res) => {
+            handleRequest(req, res, host, port, false, quiet);
+        });
+    } else {
+        // HTTPS server
+        let cert: string;
+        let key: string;
+
+        if (options.certPath && options.keyPath && certFilesExist(options.certPath, options.keyPath)) {
+            // Use provided certificates
+            ({ cert, key } = readCertFiles(options.certPath, options.keyPath));
+            if (!quiet) {
+                // eslint-disable-next-line no-console
+                console.log(`${colors.green}Using SSL certificates from: ${options.certPath}${colors.reset}`);
+            }
+        } else {
+            // Generate self-signed certificate
+            if (!quiet) {
+                // eslint-disable-next-line no-console
+                console.log(`${colors.yellow}Generating self-signed certificate for ${host}...${colors.reset}`);
+            }
+
+            ({ cert, key } = generateSelfSignedCert(host));
+            if (!quiet) {
+                // eslint-disable-next-line no-console
+                console.log(
+                    `${colors.yellow}Note: Browser will show certificate warning - this is expected for self-signed certs${colors.reset}`,
+                );
+            }
+        }
+
+        server = https.createServer({ cert, key }, (req, res) => {
+            handleRequest(req, res, host, port, true, quiet);
+        });
+    }
+
+    // Start listening
+    server.listen(port, host, () => {
+        if (!quiet) {
+            printBanner(host, port, !useHttp);
+        }
+    });
+
+    // Handle graceful shutdown
+    process.on("SIGINT", () => {
+        // eslint-disable-next-line no-console
+        console.log(`\n${colors.yellow}Shutting down...${colors.reset}`);
+        if (logFileStream) {
+            logFileStream.end();
+        }
+
+        server.close(() => {
+            process.exit(0);
+        });
+    });
+
+    return server;
+}
+
+/**
+ * Help text displayed when --help is passed.
+ */
+export const HELP_TEXT = `
+Remote Log Server - Remote logging for browser debugging
+
+Usage:
+  npx remote-log-server [options]
+  npx @graphty/remote-logger [options]
+
+Options:
+  --port, -p <port>       Port to listen on (default: 9080)
+  --host, -h <host>       Hostname to bind to (default: localhost)
+  --cert, -c <path>       Path to SSL certificate file
+  --key, -k <path>        Path to SSL private key file
+  --log-file, -l <path>   Write logs to file
+  --http                  Use HTTP instead of HTTPS
+  --quiet, -q             Suppress startup banner
+  --help                  Show this help message
+
+Examples:
+  npx remote-log-server                           # Start with defaults (port 9080, self-signed cert)
+  npx remote-log-server --port 9085               # Custom port
+  npx remote-log-server --http                    # Use HTTP instead of HTTPS
+  npx remote-log-server --cert cert.crt --key key.key  # Custom SSL certs
+  npx remote-log-server --log-file ./tmp/logs.jsonl    # Also write to file
+`;
+
+/**
+ * Result of parsing command line arguments.
+ */
+export interface ParseArgsResult {
+    /** Parsed options for the log server */
+    options: LogServerOptions;
+    /** Whether --help was requested */
+    showHelp: boolean;
+    /** Error message if parsing failed */
+    error?: string;
+}
+
+/**
+ * Parse command line arguments into LogServerOptions.
+ * This is separated from main() to enable testing.
+ * @param args - Array of command line arguments (excluding node and script name)
+ * @returns ParseArgsResult with options, help flag, or error
+ */
+export function parseArgs(args: string[]): ParseArgsResult {
+    const options: LogServerOptions = {};
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const nextArg = args[i + 1];
+
+        switch (arg) {
+            case "--port":
+            case "-p":
+                options.port = parseInt(nextArg, 10);
+                i++;
+                break;
+            case "--host":
+            case "-h":
+                options.host = nextArg;
+                i++;
+                break;
+            case "--cert":
+            case "-c":
+                options.certPath = nextArg;
+                i++;
+                break;
+            case "--key":
+            case "-k":
+                options.keyPath = nextArg;
+                i++;
+                break;
+            case "--log-file":
+            case "-l":
+                options.logFile = nextArg;
+                i++;
+                break;
+            case "--http":
+                options.useHttp = true;
+                break;
+            case "--quiet":
+            case "-q":
+                options.quiet = true;
+                break;
+            case "--help":
+                return { options, showHelp: true };
+            default:
+                return { options, showHelp: false, error: `Unknown option: ${arg}` };
+        }
+    }
+
+    return { options, showHelp: false };
+}
+
+/**
+ * Parse command line arguments and start the server.
+ */
+export function main(): void {
+    const args = process.argv.slice(2);
+    const result = parseArgs(args);
+
+    if (result.showHelp) {
+        // eslint-disable-next-line no-console
+        console.log(HELP_TEXT);
+        process.exit(0);
+    }
+
+    if (result.error) {
+        console.error(result.error);
+        process.exit(1);
+    }
+
+    startLogServer(result.options);
+}

package/src/server/self-signed-cert.ts

@@ -0,0 +1,93 @@
+/**
+ * Self-signed certificate generation for the log server.
+ * Uses the 'selfsigned' npm package to generate proper X.509 certificates.
+ */
+
+import * as fs from "fs";
+import selfsigned from "selfsigned";
+
+export interface GeneratedCert {
+    cert: string;
+    key: string;
+}
+
+/**
+ * Generate a self-signed certificate for HTTPS.
+ * The certificate is valid for localhost and common local development hostnames.
+ * @param hostname - Optional hostname to include in the certificate (default: localhost)
+ * @returns Object containing PEM-encoded certificate and private key
+ */
+export function generateSelfSignedCert(hostname = "localhost"): GeneratedCert {
+    const attrs = [
+        { name: "commonName", value: hostname },
+        { name: "organizationName", value: "Remote Log Server" },
+        { name: "countryName", value: "US" },
+    ];
+
+    const options = {
+        keySize: 2048,
+        days: 365,
+        algorithm: "sha256" as const,
+        extensions: [
+            {
+                name: "basicConstraints",
+                cA: false,
+            },
+            {
+                name: "keyUsage",
+                keyCertSign: false,
+                digitalSignature: true,
+                keyEncipherment: true,
+            },
+            {
+                name: "extKeyUsage",
+                serverAuth: true,
+            },
+            {
+                name: "subjectAltName",
+                altNames: [
+                    { type: 2, value: hostname }, // DNS name
+                    { type: 2, value: "localhost" },
+                    { type: 7, ip: "127.0.0.1" }, // IP address
+                    { type: 7, ip: "::1" }, // IPv6 localhost
+                ],
+            },
+        ],
+    };
+
+    const pems = selfsigned.generate(attrs, options);
+
+    return {
+        cert: pems.cert,
+        key: pems.private,
+    };
+}
+
+/**
+ * Check if certificate files exist and are readable.
+ * @param certPath - Path to the certificate file
+ * @param keyPath - Path to the private key file
+ * @returns true if both files exist and are readable
+ */
+export function certFilesExist(certPath: string, keyPath: string): boolean {
+    try {
+        fs.accessSync(certPath, fs.constants.R_OK);
+        fs.accessSync(keyPath, fs.constants.R_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Read certificate and key from files.
+ * @param certPath - Path to the certificate file
+ * @param keyPath - Path to the private key file
+ * @returns Object containing PEM-encoded certificate and private key
+ */
+export function readCertFiles(certPath: string, keyPath: string): GeneratedCert {
+    return {
+        cert: fs.readFileSync(certPath, "utf-8"),
+        key: fs.readFileSync(keyPath, "utf-8"),
+    };
+}