@graphty/remote-logger 1.1.1 → 1.2.1

package/dist/server/log-storage.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Shared log storage with session metadata support.
+ *
+ * This module provides a centralized storage for logs that can be shared
+ * between HTTP and MCP interfaces. It supports project markers for
+ * filtering logs by git worktree or project.
+ * @module server/log-storage
+ */
+import type { JsonlWriter } from "./jsonl-writer.js";
+/**
+ * A single log entry.
+ */
+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 */
+    data?: Record<string, unknown>;
+}
+/**
+ * A log entry with session information attached.
+ */
+export interface LogEntryWithSession extends LogEntry {
+    /** The session ID this log belongs to */
+    sessionId: string;
+}
+/**
+ * Metadata about a logging session.
+ */
+export interface SessionMetadata {
+    /** Unique identifier for the session */
+    sessionId: string;
+    /** Project marker for filtering (derived or explicit) */
+    projectMarker: string;
+    /** Full worktree path if available */
+    worktreePath?: string;
+    /** Browser page URL if available */
+    pageUrl?: string;
+    /** Timestamp of first log in session */
+    firstLogTime: string;
+    /** Timestamp of most recent log in session */
+    lastLogTime: string;
+    /** Total number of logs in session */
+    logCount: number;
+    /** Number of ERROR level logs */
+    errorCount: number;
+}
+/**
+ * Options when adding logs to storage.
+ */
+export interface AddLogsOptions {
+    /** Explicit project marker (overrides auto-detection) */
+    projectMarker?: string;
+    /** Full worktree path */
+    worktreePath?: string;
+    /** Browser page URL */
+    pageUrl?: string;
+}
+/**
+ * Filter options for querying logs.
+ */
+export interface LogFilter {
+    /** Filter by project marker */
+    projectMarker?: string;
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Filter by log level */
+    level?: string;
+    /** Only return logs after this timestamp */
+    since?: string;
+}
+/**
+ * Filter options for querying sessions.
+ */
+export interface SessionFilter {
+    /** Filter by project marker */
+    projectMarker?: string;
+    /** Only return sessions with errors */
+    hasErrors?: boolean;
+}
+/**
+ * Filter options for clearing logs.
+ */
+export interface ClearFilter {
+    /** Clear only logs for this project marker */
+    projectMarker?: string;
+    /** Clear only logs for this session ID */
+    sessionId?: string;
+}
+/**
+ * Search options for finding logs by content.
+ */
+export interface SearchOptions {
+    /** Search query (substring or regex) */
+    query: string;
+    /** Treat query as regex (default: false) */
+    regex?: boolean;
+    /** Filter by project marker */
+    projectMarker?: string;
+    /** Filter by log level */
+    level?: string;
+    /** Maximum results to return (default: 100) */
+    limit?: number;
+}
+/**
+ * Server mode indicating which interfaces are enabled.
+ */
+export type ServerMode = "mcp-only" | "http-only" | "dual";
+/**
+ * HTTP server configuration.
+ */
+export interface ServerConfig {
+    /** HTTP server port */
+    httpPort: number;
+    /** HTTP server host */
+    httpHost: string;
+    /** Protocol (http or https) */
+    protocol: "http" | "https";
+    /** Full URL for browser clients to send logs to */
+    httpEndpoint: string;
+    /** Server mode (mcp-only, http-only, or dual) */
+    mode: ServerMode;
+}
+/**
+ * Health status of the log storage.
+ */
+export interface HealthStatus {
+    /** Overall status */
+    status: "ok" | "error";
+    /** Number of active sessions */
+    sessionCount: number;
+    /** Total number of logs stored */
+    totalLogs: number;
+    /** Total number of error logs */
+    totalErrors: number;
+    /** Time since storage was created (milliseconds) */
+    uptimeMs: number;
+}
+/**
+ * Full server status including health and configuration.
+ */
+export interface ServerStatus extends HealthStatus {
+    /** HTTP server configuration (undefined if HTTP server not configured) */
+    server?: ServerConfig;
+    /** Number of days logs are retained before automatic cleanup */
+    retentionDays: number;
+}
+/**
+ * Options for LogStorage constructor.
+ */
+export interface LogStorageOptions {
+    /** Optional JSONL writer for streaming logs to disk */
+    jsonlWriter?: JsonlWriter;
+    /** Number of days to retain logs (default: 7, can be set via REMOTE_LOG_RETENTION_DAYS env var) */
+    retentionDays?: number;
+    /** Interval between cleanup checks in milliseconds (default: 1 hour) */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Shared log storage with session metadata support.
+ *
+ * Provides methods for storing, querying, and managing logs across
+ * multiple sessions with support for project marker filtering.
+ */
+export declare class LogStorage {
+    private sessions;
+    private startTime;
+    private jsonlWriter?;
+    private retentionDays;
+    private cleanupTimer?;
+    private serverConfig?;
+    /**
+     * Create a new LogStorage instance.
+     * @param options - Optional configuration including JSONL writer
+     */
+    constructor(options?: LogStorageOptions);
+    /**
+     * Get the JSONL writer if configured.
+     * @returns The JSONL writer or undefined
+     */
+    getJsonlWriter(): JsonlWriter | undefined;
+    /**
+     * Add logs to storage for a session.
+     * @param sessionId - Unique identifier for the session
+     * @param logs - Array of log entries to add
+     * @param options - Additional options (projectMarker, worktreePath, pageUrl)
+     */
+    addLogs(sessionId: string, logs: LogEntry[], options?: AddLogsOptions): void;
+    /**
+     * Get logs with optional filtering.
+     * @param filter - Filter options
+     * @returns Array of log entries with session IDs
+     */
+    getLogs(filter?: LogFilter): LogEntryWithSession[];
+    /**
+     * Get the most recent logs across all sessions.
+     * @param count - Maximum number of logs to return
+     * @param filter - Optional filter to apply before limiting
+     * @returns Array of recent log entries (oldest first)
+     */
+    getRecentLogs(count: number, filter?: LogFilter): LogEntryWithSession[];
+    /**
+     * Get only ERROR level logs.
+     * @param filter - Optional filter options
+     * @returns Array of error log entries
+     */
+    getErrors(filter?: Omit<LogFilter, "level">): LogEntryWithSession[];
+    /**
+     * Get all sessions with their metadata.
+     * @param filter - Optional filter options
+     * @returns Array of session metadata
+     */
+    getSessions(filter?: SessionFilter): SessionMetadata[];
+    /**
+     * Clear logs with optional filtering.
+     * @param filter - Optional filter to limit what is cleared
+     * @returns Object with count of cleared sessions
+     */
+    clearLogs(filter?: ClearFilter): {
+        cleared: number;
+    };
+    /**
+     * Clear all logs (convenience method).
+     */
+    clear(): void;
+    /**
+     * Set the HTTP server configuration.
+     * Call this after the HTTP server starts to make endpoint info available.
+     * @param config - Server configuration
+     */
+    setServerConfig(config: ServerConfig): void;
+    /**
+     * Get the HTTP server configuration.
+     * @returns Server configuration or undefined if not set
+     */
+    getServerConfig(): ServerConfig | undefined;
+    /**
+     * Get health status of the storage.
+     * @returns Health status object
+     */
+    getHealth(): HealthStatus;
+    /**
+     * Get full server status including health and configuration.
+     * @returns Server status object
+     */
+    getStatus(): ServerStatus;
+    /**
+     * Get logs for a specific session.
+     * @param sessionId - The session ID to get logs for
+     * @returns Array of log entries for the session
+     */
+    getLogsForSession(sessionId: string): LogEntry[];
+    /**
+     * Get all logs grouped by session ID.
+     * @param filter - Optional filter options
+     * @param filter.projectMarker - Filter by project marker
+     * @returns Object mapping session IDs to log arrays
+     */
+    getAllLogsBySession(filter?: {
+        projectMarker?: string;
+    }): Record<string, LogEntry[]>;
+    /**
+     * Search logs by content.
+     * @param options - Search options
+     * @returns Array of matching log entries
+     */
+    search(options: SearchOptions): LogEntryWithSession[];
+    /**
+     * Check if a session exists.
+     * @param sessionId - The session ID to check
+     * @returns True if the session exists
+     */
+    hasSession(sessionId: string): boolean;
+    /**
+     * Get metadata for a specific session.
+     * @param sessionId - The session ID
+     * @returns Session metadata or undefined if not found
+     */
+    getSessionMetadata(sessionId: string): SessionMetadata | undefined;
+    /**
+     * Get the configured retention period in days.
+     * @returns Number of days logs are retained
+     */
+    getRetentionDays(): number;
+    /**
+     * Stop the periodic cleanup timer.
+     * Call this when shutting down to prevent memory leaks.
+     */
+    stopCleanupTimer(): void;
+    /**
+     * Clean up logs older than the retention period.
+     * This removes individual logs from sessions, removes sessions
+     * that have no remaining logs, and cleans up old JSONL files.
+     * @returns Number of sessions that were completely removed
+     */
+    cleanupExpiredLogs(): number;
+}
+//# sourceMappingURL=log-storage.d.ts.map

package/dist/server/log-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-storage.d.ts","sourceRoot":"","sources":["../../src/server/log-storage.ts"],"names":[],"mappings":"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"}