@graphty/remote-logger 0.0.1 → 1.2.0

package/dist/vite/plugin.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Vite plugin for automatic project marker injection.
+ *
+ * This plugin injects global variables that the RemoteLogClient
+ * can use to automatically identify which project/worktree logs
+ * are coming from.
+ * @module vite/plugin
+ */
+/**
+ * Vite plugin configuration object.
+ * Matches Vite's Plugin type but without requiring the full vite dependency.
+ */
+interface VitePlugin {
+    name: string;
+    config: () => {
+        define: Record<string, string>;
+    };
+}
+/**
+ * Creates a Vite plugin that injects project marker globals.
+ *
+ * The plugin detects the current working directory and:
+ * 1. Extracts a project marker (worktree name or directory basename)
+ * 2. Injects `__REMOTE_LOG_PROJECT_MARKER__` with the marker
+ * 3. Injects `__REMOTE_LOG_WORKTREE_PATH__` with the full path
+ *
+ * These globals are automatically read by RemoteLogClient when no
+ * explicit projectMarker/worktreePath options are provided.
+ * @returns A Vite plugin configuration object
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { remoteLoggerPlugin } from "@graphty/remote-logger/vite";
+ *
+ * export default defineConfig({
+ *     plugins: [remoteLoggerPlugin()]
+ * });
+ * ```
+ */
+export declare function remoteLoggerPlugin(): VitePlugin;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/vite/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/vite/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;GAGG;AACH,UAAU,UAAU;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM;QACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,CAAC;CACL;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,CAe/C"}

package/dist/vite/plugin.js

@@ -0,0 +1,46 @@
+/**
+ * Vite plugin for automatic project marker injection.
+ *
+ * This plugin injects global variables that the RemoteLogClient
+ * can use to automatically identify which project/worktree logs
+ * are coming from.
+ * @module vite/plugin
+ */
+import { extractMarkerFromPath } from "../server/marker-utils.js";
+/**
+ * Creates a Vite plugin that injects project marker globals.
+ *
+ * The plugin detects the current working directory and:
+ * 1. Extracts a project marker (worktree name or directory basename)
+ * 2. Injects `__REMOTE_LOG_PROJECT_MARKER__` with the marker
+ * 3. Injects `__REMOTE_LOG_WORKTREE_PATH__` with the full path
+ *
+ * These globals are automatically read by RemoteLogClient when no
+ * explicit projectMarker/worktreePath options are provided.
+ * @returns A Vite plugin configuration object
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { remoteLoggerPlugin } from "@graphty/remote-logger/vite";
+ *
+ * export default defineConfig({
+ *     plugins: [remoteLoggerPlugin()]
+ * });
+ * ```
+ */
+export function remoteLoggerPlugin() {
+    return {
+        name: "remote-logger",
+        config() {
+            const cwd = process.cwd();
+            const marker = extractMarkerFromPath(cwd);
+            return {
+                define: {
+                    __REMOTE_LOG_PROJECT_MARKER__: JSON.stringify(marker),
+                    __REMOTE_LOG_WORKTREE_PATH__: JSON.stringify(cwd),
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/vite/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/vite/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAalE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB;IAC9B,OAAO;QACH,IAAI,EAAE,eAAe;QACrB,MAAM;YACF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;YAE1C,OAAO;gBACH,MAAM,EAAE;oBACJ,6BAA6B,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;oBACrD,4BAA4B,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;iBACpD;aACJ,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC"}

package/package.json

@@ -1,10 +1,93 @@
 {
   "name": "@graphty/remote-logger",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @graphty/remote-logger",
+  "version": "1.2.0",
+  "description": "Remote logging client and server for browser debugging",
+  "author": "Adam Powers <apowers@ato.ms>",
+  "main": "dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server/index.js",
+      "types": "./dist/server/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client/index.js",
+      "types": "./dist/client/index.d.ts"
+    },
+    "./ui": {
+      "import": "./dist/ui/index.js",
+      "types": "./dist/ui/index.d.ts"
+    },
+    "./mcp": {
+      "import": "./dist/mcp/index.js",
+      "types": "./dist/mcp/index.d.ts"
+    },
+    "./vite": {
+      "import": "./dist/vite/index.js",
+      "types": "./dist/vite/index.d.ts"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "bin": {
+    "remote-log-server": "./bin/remote-log-server.js"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphty-org/graphty-monorepo.git",
+    "directory": "remote-logger"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "logging",
+    "remote-logging",
+    "debug",
+    "browser",
+    "server",
+    "typescript"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bugs": {
+    "url": "https://github.com/graphty-org/graphty-monorepo/issues"
+  },
+  "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/remote-logger#readme",
+  "engines": {
+    "node": ">=18.19.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "selfsigned": "^2.4.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^3.2.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "coverage": "vitest run --coverage",
+    "coverage:preview": "npx serve coverage -p 9055",
+    "lint": "eslint && tsc --noEmit -p tsconfig.eslint.json",
+    "lint:fix": "eslint --fix",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "dev": "tsc --watch"
+  }
+}

package/src/client/RemoteLogClient.ts

@@ -0,0 +1,328 @@
+/**
+ * Browser client for sending log messages to a remote server.
+ * Provides batching and automatic retry with exponential backoff.
+ * @module client/RemoteLogClient
+ */
+
+import type { LogEntry, RemoteLogClientOptions, ThrottlePattern } from "./types.js";
+
+/**
+ * Global variables that may be injected by the Vite plugin.
+ * These provide automatic project marker detection.
+ */
+declare const __REMOTE_LOG_PROJECT_MARKER__: string | undefined;
+declare const __REMOTE_LOG_WORKTREE_PATH__: string | undefined;
+
+/**
+ * Safely read a global variable that may or may not be defined.
+ * @param name - Name of the global variable
+ * @returns The value of the global variable, or undefined if not defined
+ */
+function getGlobalValue(name: "__REMOTE_LOG_PROJECT_MARKER__" | "__REMOTE_LOG_WORKTREE_PATH__"): string | undefined {
+    try {
+        if (name === "__REMOTE_LOG_PROJECT_MARKER__") {
+            return typeof __REMOTE_LOG_PROJECT_MARKER__ !== "undefined" ? __REMOTE_LOG_PROJECT_MARKER__ : undefined;
+        }
+        if (name === "__REMOTE_LOG_WORKTREE_PATH__") {
+            return typeof __REMOTE_LOG_WORKTREE_PATH__ !== "undefined" ? __REMOTE_LOG_WORKTREE_PATH__ : undefined;
+        }
+    } catch {
+        // ReferenceError if the global is not defined at all
+        return undefined;
+    }
+    return undefined;
+}
+
+/** Default configuration values */
+const DEFAULT_BATCH_INTERVAL_MS = 1000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_DELAY_MS = 1000;
+const DEFAULT_SESSION_PREFIX = "session";
+
+/**
+ * Generates a unique session ID with the given prefix.
+ * Format: {prefix}-{timestamp}-{random}
+ * @param prefix - The prefix to use for the session ID
+ * @returns A unique session ID string
+ */
+function generateSessionId(prefix: string): string {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `${prefix}-${timestamp}-${random}`;
+}
+
+/**
+ * Client for sending log messages to a remote logging server.
+ *
+ * Features:
+ * - Batches multiple log entries before sending
+ * - Automatic retry with exponential backoff on network failures
+ * - Unique session ID for correlating logs
+ * @example
+ * ```typescript
+ * const client = new RemoteLogClient({
+ *     serverUrl: "http://localhost:9080",
+ *     sessionPrefix: "myapp",
+ * });
+ *
+ * client.log("INFO", "User logged in", { userId: 123 });
+ * client.log("DEBUG", "Loading data...");
+ *
+ * // Flush immediately when needed
+ * await client.flush();
+ *
+ * // Clean up when done
+ * await client.close();
+ * ```
+ */
+export class RemoteLogClient {
+    /** Unique identifier for this logging session */
+    readonly sessionId: string;
+
+    private readonly serverUrl: string;
+    private readonly batchIntervalMs: number;
+    private readonly maxRetries: number;
+    private readonly retryDelayMs: number;
+    private readonly throttlePatterns: ThrottlePattern[];
+    private readonly projectMarker: string | undefined;
+    private readonly worktreePath: string | undefined;
+
+    private pendingLogs: LogEntry[] = [];
+    private batchTimer: ReturnType<typeof setTimeout> | null = null;
+    private isClosed = false;
+    private flushPromise: Promise<void> | null = null;
+
+    /** Tracks when each throttle pattern was last allowed through */
+    private throttleLastTimes = new Map<string, number>();
+
+    /**
+     * Creates a new RemoteLogClient.
+     * @param options - Configuration options
+     */
+    constructor(options: RemoteLogClientOptions) {
+        this.serverUrl = options.serverUrl;
+        this.sessionId = generateSessionId(options.sessionPrefix ?? DEFAULT_SESSION_PREFIX);
+        this.batchIntervalMs = options.batchIntervalMs ?? DEFAULT_BATCH_INTERVAL_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+        this.throttlePatterns = options.throttlePatterns ?? [];
+
+        // Priority: explicit option > global variable
+        this.projectMarker = options.projectMarker ?? getGlobalValue("__REMOTE_LOG_PROJECT_MARKER__");
+        this.worktreePath = options.worktreePath ?? getGlobalValue("__REMOTE_LOG_WORKTREE_PATH__");
+    }
+
+    /**
+     * Checks if a message should be throttled based on configured patterns.
+     * Updates the last time tracking if the message is allowed through.
+     * @param message - The message to check
+     * @returns true if the message should be dropped (throttled)
+     */
+    private shouldThrottle(message: string): boolean {
+        const now = Date.now();
+
+        for (const { pattern, intervalMs } of this.throttlePatterns) {
+            if (pattern.test(message)) {
+                const key = pattern.source;
+                const lastTime = this.throttleLastTimes.get(key) ?? 0;
+
+                if (now - lastTime < intervalMs) {
+                    // Within throttle window, drop this message
+                    return true;
+                }
+
+                // Outside throttle window, update timestamp and allow through
+                this.throttleLastTimes.set(key, now);
+                return false;
+            }
+        }
+
+        // No matching pattern, allow through
+        return false;
+    }
+
+    /**
+     * Logs a message at the specified level.
+     * @param level - Log level (e.g., "INFO", "DEBUG", "WARN", "ERROR")
+     * @param message - The log message
+     * @param data - Optional additional data to include
+     */
+    log(level: string, message: string, data?: Record<string, unknown>): void {
+        if (this.isClosed) {
+            return;
+        }
+
+        // Check throttling before adding to buffer
+        if (this.shouldThrottle(message)) {
+            return;
+        }
+
+        const entry: LogEntry = {
+            time: new Date().toISOString(),
+            level,
+            message,
+            ...(data !== undefined && { data }),
+        };
+
+        this.pendingLogs.push(entry);
+        this.scheduleBatchSend();
+    }
+
+    /**
+     * Schedules a batch send after the configured interval.
+     * If a timer is already scheduled, does nothing.
+     */
+    private scheduleBatchSend(): void {
+        if (this.batchTimer !== null || this.isClosed) {
+            return;
+        }
+
+        this.batchTimer = setTimeout(() => {
+            this.batchTimer = null;
+            void this.sendBatch();
+        }, this.batchIntervalMs);
+    }
+
+    /**
+     * Sends the current batch of logs to the server.
+     * Uses retry logic with exponential backoff on failure.
+     */
+    private async sendBatch(): Promise<void> {
+        if (this.pendingLogs.length === 0) {
+            return;
+        }
+
+        // Take the current logs and clear the pending array
+        const logsToSend = this.pendingLogs;
+        this.pendingLogs = [];
+
+        await this.sendWithRetry(logsToSend);
+    }
+
+    /**
+     * Sends logs with retry logic using exponential backoff.
+     * @param logs - The log entries to send
+     */
+    private async sendWithRetry(logs: LogEntry[]): Promise<void> {
+        let lastError: Error | null = null;
+
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                await this.sendRequest(logs);
+                return; // Success!
+            } catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+
+                if (attempt < this.maxRetries) {
+                    // Exponential backoff: delay * 2^attempt
+                    const delay = this.retryDelayMs * Math.pow(2, attempt);
+                    await this.sleep(delay);
+                }
+            }
+        }
+
+        // All retries exhausted - log the error but don't throw
+        // In a browser context, we don't want to break the application
+        console.error("[RemoteLogClient] Failed to send logs after retries:", lastError?.message);
+    }
+
+    /**
+     * Makes the actual HTTP request to send logs.
+     * @param logs - The log entries to send
+     * @throws Error if the request fails
+     */
+    private async sendRequest(logs: LogEntry[]): Promise<void> {
+        const requestBody: {
+            sessionId: string;
+            logs: LogEntry[];
+            projectMarker?: string;
+            worktreePath?: string;
+        } = {
+            sessionId: this.sessionId,
+            logs,
+        };
+
+        // Only include these fields if they have values
+        if (this.projectMarker !== undefined) {
+            requestBody.projectMarker = this.projectMarker;
+        }
+        if (this.worktreePath !== undefined) {
+            requestBody.worktreePath = this.worktreePath;
+        }
+
+        const response = await fetch(`${this.serverUrl}/log`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(requestBody),
+        });
+
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+    }
+
+    /**
+     * Helper to sleep for the specified duration.
+     * @param ms - Milliseconds to sleep
+     * @returns A promise that resolves after the specified time
+     */
+    private sleep(ms: number): Promise<void> {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+
+    /**
+     * Immediately flushes all pending logs to the server.
+     * Useful before page unload or when immediate delivery is needed.
+     */
+    async flush(): Promise<void> {
+        // Cancel any scheduled batch
+        if (this.batchTimer !== null) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+        }
+
+        // Wait for any in-progress flush
+        if (this.flushPromise !== null) {
+            await this.flushPromise;
+        }
+
+        // Send any remaining logs
+        if (this.pendingLogs.length > 0) {
+            this.flushPromise = this.sendBatch();
+            await this.flushPromise;
+            this.flushPromise = null;
+        }
+    }
+
+    /**
+     * Closes the client, flushing any pending logs and stopping the batch timer.
+     * After calling close(), no more logs will be accepted.
+     */
+    async close(): Promise<void> {
+        if (this.isClosed) {
+            return;
+        }
+
+        this.isClosed = true;
+
+        // Flush remaining logs
+        await this.flush();
+    }
+}
+
+/**
+ * Factory function to create a RemoteLogClient.
+ * @param options - Configuration options
+ * @returns A new RemoteLogClient instance
+ * @example
+ * ```typescript
+ * const client = createRemoteLogClient({
+ *     serverUrl: "http://localhost:9080",
+ * });
+ * ```
+ */
+export function createRemoteLogClient(options: RemoteLogClientOptions): RemoteLogClient {
+    return new RemoteLogClient(options);
+}

package/src/client/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Browser client for remote logging.
+ * @module client
+ */
+
+export { createRemoteLogClient, RemoteLogClient } from "./RemoteLogClient.js";
+export type { LogEntry, RemoteLogClientOptions, ThrottlePattern } from "./types.js";

package/src/client/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Type definitions for the remote logging client.
+ * @module client/types
+ */
+
+/**
+ * A single log entry to be sent to the remote server.
+ */
+export interface LogEntry {
+    /** ISO 8601 timestamp when the log was created */
+    time: string;
+    /** Log level (e.g., "INFO", "DEBUG", "WARN", "ERROR") */
+    level: string;
+    /** The log message */
+    message: string;
+    /** Optional additional data to include with the log */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Configuration for throttling specific message patterns.
+ */
+export interface ThrottlePattern {
+    /** Regular expression pattern to match log messages */
+    pattern: RegExp;
+    /** Minimum interval in milliseconds between matching messages */
+    intervalMs: number;
+}
+
+/**
+ * Configuration options for the RemoteLogClient.
+ */
+export interface RemoteLogClientOptions {
+    /** URL of the remote log server (e.g., "http://localhost:9080") */
+    serverUrl: string;
+    /** Prefix for the generated session ID (default: "session") */
+    sessionPrefix?: string;
+    /** Interval in milliseconds between batch sends (default: 1000) */
+    batchIntervalMs?: number;
+    /** Maximum number of retry attempts for failed sends (default: 3) */
+    maxRetries?: number;
+    /** Base delay in milliseconds between retries (uses exponential backoff) (default: 1000) */
+    retryDelayMs?: number;
+    /**
+     * Patterns to throttle to prevent log flooding.
+     * Messages matching a pattern will only be sent once per the configured interval.
+     */
+    throttlePatterns?: ThrottlePattern[];
+    /**
+     * Project marker to identify logs from this project.
+     * If not provided, the client will attempt to read from the
+     * __REMOTE_LOG_PROJECT_MARKER__ global variable (injected by Vite plugin).
+     */
+    projectMarker?: string;
+    /**
+     * Full path to the worktree or project directory.
+     * Used for debugging and log organization.
+     * If not provided, the client will attempt to read from the
+     * __REMOTE_LOG_WORKTREE_PATH__ global variable (injected by Vite plugin).
+     */
+    worktreePath?: string;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Remote logging client and server for browser debugging.
+ *
+ * Client usage (Browser):
+ *   import { RemoteLogClient } from "@graphty/remote-logger";
+ *   const client = new RemoteLogClient({ serverUrl: "http://localhost:9080" });
+ *   client.log("INFO", "Hello from browser");
+ *
+ * Server usage (Node.js):
+ *   import { startLogServer } from "@graphty/remote-logger/server";
+ *   startLogServer({ port: 9080 });
+ *
+ * Or via CLI:
+ *   npx remote-log-server --port 9080
+ *
+ * UI usage (Browser):
+ *   import { initConsoleCaptureUI } from "@graphty/remote-logger/ui";
+ *   initConsoleCaptureUI();
+ */
+
+// Client exports (primary exports for browser usage)
+// Note: Server components are NOT re-exported here because they use Node.js APIs.
+// Import from "@graphty/remote-logger/server" for server-side usage.
+export type { LogEntry, RemoteLogClientOptions, ThrottlePattern } from "./client/index.js";
+export { createRemoteLogClient, RemoteLogClient } from "./client/index.js";
+
+// Note: UI components are NOT re-exported here to keep the main entry lightweight.
+// Import from "@graphty/remote-logger/ui" for UI usage.

package/src/mcp/index.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP server module exports.
+ *
+ * Provides Model Context Protocol interface for log queries.
+ * @module mcp
+ */
+
+export { createMcpServer, getToolNames, startMcpServer } from "./mcp-server.js";
+export {
+    logsGetRecentHandler,
+    type LogsGetRecentInput,
+    logsGetRecentInputSchema,
+    type LogsGetRecentOutput,
+    logsGetRecentTool,
+    logsListSessionsHandler,
+    type LogsListSessionsInput,
+    logsListSessionsInputSchema,
+    type LogsListSessionsOutput,
+    logsListSessionsTool,
+    logsStatusHandler,
+    type LogsStatusInput,
+    logsStatusInputSchema,
+    type LogsStatusOutput,
+    logsStatusTool,
+} from "./tools/index.js";