@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.1

package/dist/runtime/server/devmode/dev-mode.service.js

@@ -0,0 +1,290 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from 'tsyringe';
+import { GLOBAL_CONTAINER } from '../../../kernel/di/container';
+import { loggers } from '../../../kernel/logger';
+import { createDevTransport, detectEnvironment, isWebSocketTransport, startDevTransport, stopDevTransport, } from '../../../kernel/logger/transports/dev-transport.factory';
+import { EventInterceptorService } from './event-interceptor.service';
+import { PlayerSimulatorService } from './player-simulator.service';
+import { StateInspectorService } from './state-inspector.service';
+/**
+ * Main DevMode service that orchestrates all development tools.
+ *
+ * @remarks
+ * Provides a unified interface for internal framework debugging and telemetry.
+ * It coordinates:
+ * - Event interception and recording (Net, Commands, etc)
+ * - Runtime state inspection (DI, Players, Services)
+ * - Player simulation for offline logic testing
+ * - Telemetry bridge for external CLI integration
+ */
+let DevModeService = class DevModeService {
+    enabled = false;
+    options = null;
+    logTransport = null;
+    get interceptor() {
+        return GLOBAL_CONTAINER.resolve(EventInterceptorService);
+    }
+    get inspector() {
+        return GLOBAL_CONTAINER.resolve(StateInspectorService);
+    }
+    get simulator() {
+        return GLOBAL_CONTAINER.resolve(PlayerSimulatorService);
+    }
+    /**
+     * Enables DevMode with the specified options.
+     * @param options - DevMode configuration
+     */
+    async enable(options) {
+        if (this.enabled) {
+            loggers.bootstrap.warn('[DevMode] Already enabled, skipping');
+            return;
+        }
+        this.options = options;
+        this.enabled = true;
+        loggers.bootstrap.info('[DevMode] Enabling development mode...', {
+            bridge: options.bridge?.autoConnect,
+            interceptor: options.interceptor?.enabled,
+            simulator: options.simulator?.enabled,
+        });
+        // Configure event interceptor
+        if (options.interceptor) {
+            this.interceptor.configure(options.interceptor);
+        }
+        // Connect to CLI bridge
+        if (options.bridge?.autoConnect) {
+            await this.connectToBridge(options.bridge.url);
+        }
+        // Auto-connect simulated players
+        if (options.simulator?.enabled && options.simulator.autoConnectPlayers > 0) {
+            this.simulator.connectMany(options.simulator.autoConnectPlayers);
+        }
+        loggers.bootstrap.info('[DevMode] Development mode enabled successfully');
+    }
+    /**
+     * Disables DevMode and cleans up resources.
+     */
+    disable() {
+        if (!this.enabled)
+            return;
+        loggers.bootstrap.info('[DevMode] Disabling development mode...');
+        // Disconnect log transport
+        if (this.logTransport) {
+            void stopDevTransport(this.logTransport);
+            this.logTransport = null;
+        }
+        // Disconnect all simulated players
+        this.simulator.disconnectAll();
+        // Clear event history
+        this.interceptor.clearHistory();
+        this.enabled = false;
+        this.options = null;
+        loggers.bootstrap.info('[DevMode] Development mode disabled');
+    }
+    /**
+     * Checks if DevMode is enabled.
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Gets the current DevMode options.
+     */
+    getOptions() {
+        return this.options;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Bridge Connection
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Connects to the CLI bridge for log streaming.
+     * Uses HTTP transport in FiveM, WebSocket in Node.js.
+     * @param url - Base URL (will be adapted based on environment)
+     */
+    async connectToBridge(url) {
+        if (this.logTransport) {
+            await stopDevTransport(this.logTransport);
+        }
+        const env = detectEnvironment();
+        const httpUrl = `${url.replace('ws://', 'http://').replace('wss://', 'https://')}/logs`;
+        const wsUrl = url.startsWith('http')
+            ? url.replace('http://', 'ws://').replace('https://', 'wss://')
+            : url;
+        this.logTransport = createDevTransport({
+            httpUrl,
+            wsUrl,
+        });
+        try {
+            await startDevTransport(this.logTransport);
+            // Setup message handler for WebSocket transport only
+            if (isWebSocketTransport(this.logTransport)) {
+                this.logTransport.onMessage((data) => {
+                    this.handleBridgeMessage(data);
+                });
+            }
+            loggers.bootstrap.info(`[DevMode] Connected to CLI bridge (${env} mode)`, { url });
+        }
+        catch (error) {
+            loggers.bootstrap.warn('[DevMode] Could not connect to CLI bridge', {
+                url,
+                error: error.message,
+            });
+        }
+    }
+    /**
+     * Disconnects from the CLI bridge.
+     */
+    async disconnectFromBridge() {
+        if (this.logTransport) {
+            await stopDevTransport(this.logTransport);
+            this.logTransport = null;
+            loggers.bootstrap.info('[DevMode] Disconnected from CLI bridge');
+        }
+    }
+    /**
+     * Sends a message to the CLI bridge (WebSocket only).
+     * In HTTP mode, messages are sent via log transport automatically.
+     * @param message - Message to send
+     */
+    sendToBridge(message) {
+        if (this.logTransport &&
+            isWebSocketTransport(this.logTransport) &&
+            this.logTransport.isConnected()) {
+            this.logTransport.send(message);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // State Inspection
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Captures a snapshot of the current runtime state.
+     */
+    captureSnapshot() {
+        return this.inspector.captureSnapshot();
+    }
+    /**
+     * Gets a summary of the current runtime state.
+     */
+    getSummary() {
+        return this.inspector.getSummary();
+    }
+    /**
+     * Gets detailed information about a specific player.
+     * @param clientId - Client ID
+     */
+    getPlayerDetails(clientId) {
+        return this.inspector.getPlayerDetails(clientId);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Event Interception
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Gets the recorded event history.
+     */
+    getEventHistory() {
+        return this.interceptor.getEventHistory();
+    }
+    /**
+     * Clears the event history.
+     */
+    clearEventHistory() {
+        this.interceptor.clearHistory();
+    }
+    /**
+     * Gets event statistics.
+     */
+    getEventStatistics() {
+        return this.interceptor.getStatistics();
+    }
+    /**
+     * Adds a listener for events.
+     * @param listener - Event listener function
+     * @returns Unsubscribe function
+     */
+    onEvent(listener) {
+        return this.interceptor.addListener(listener);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Player Simulation
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Connects a simulated player.
+     * @param options - Player options
+     */
+    connectPlayer(options) {
+        return this.simulator.connect(options);
+    }
+    /**
+     * Disconnects a simulated player.
+     * @param clientId - Client ID
+     */
+    disconnectPlayer(clientId) {
+        this.simulator.disconnect(clientId);
+    }
+    /**
+     * Connects multiple simulated players.
+     * @param count - Number of players
+     * @param options - Base options
+     */
+    connectPlayers(count, options) {
+        return this.simulator.connectMany(count, options);
+    }
+    /**
+     * Gets simulated player statistics.
+     */
+    getSimulatorStatistics() {
+        return this.simulator.getStatistics();
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Internal
+    // ─────────────────────────────────────────────────────────────────────────────
+    handleBridgeMessage(message) {
+        switch (message.type) {
+            case 'ping':
+                this.sendToBridge({ type: 'pong', payload: Date.now() });
+                break;
+            case 'command':
+                this.handleRemoteCommand(message.payload);
+                break;
+            default:
+                loggers.bootstrap.debug('[DevMode] Unknown bridge message type', { type: message.type });
+        }
+    }
+    handleRemoteCommand(command) {
+        loggers.bootstrap.debug('[DevMode] Remote command received', command);
+        switch (command.name) {
+            case 'snapshot':
+                this.sendToBridge({ type: 'state', payload: this.captureSnapshot() });
+                break;
+            case 'events':
+                this.sendToBridge({ type: 'event', payload: this.getEventHistory() });
+                break;
+            case 'clear-events':
+                this.clearEventHistory();
+                this.sendToBridge({ type: 'command', payload: { success: true } });
+                break;
+            case 'connect-player': {
+                const player = this.connectPlayer(command.args[0]);
+                this.sendToBridge({
+                    type: 'command',
+                    payload: { success: true, clientId: player.clientId },
+                });
+                break;
+            }
+            case 'disconnect-player':
+                this.disconnectPlayer(command.args[0]);
+                this.sendToBridge({ type: 'command', payload: { success: true } });
+                break;
+            default:
+                loggers.bootstrap.warn('[DevMode] Unknown remote command', { name: command.name });
+        }
+    }
+};
+DevModeService = __decorate([
+    injectable()
+], DevModeService);
+export { DevModeService };

package/dist/runtime/server/devmode/event-interceptor.service.d.ts

@@ -0,0 +1,80 @@
+import { IDevModeInterceptor } from './contracts/IDevModeInterceptor';
+import { DevEvent, InterceptorOptions } from './types';
+/**
+ * Implementation of the DevMode event interceptor.
+ *
+ * Captures and records all framework events for debugging and analysis.
+ * Events are stored in a circular buffer with configurable size.
+ */
+export declare class EventInterceptorService extends IDevModeInterceptor {
+    private enabled;
+    private history;
+    private pendingEvents;
+    private options;
+    private eventCounter;
+    private listeners;
+    constructor();
+    /**
+     * Configures the interceptor options.
+     */
+    configure(options: Partial<InterceptorOptions>): void;
+    onEventBefore(event: Omit<DevEvent, 'result' | 'duration'>): void;
+    onEventAfter(event: DevEvent): void;
+    onEventError(event: DevEvent): void;
+    getEventHistory(): DevEvent[];
+    clearHistory(): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    /**
+     * Creates an event ID for tracking.
+     */
+    createEventId(): string;
+    /**
+     * Records a net event.
+     */
+    recordNetEvent(name: string, direction: 'in' | 'out', args: unknown[], source?: {
+        clientId?: number;
+    }): string;
+    /**
+     * Records a command execution.
+     */
+    recordCommand(name: string, args: string[], source?: {
+        clientId?: number;
+    }): string;
+    /**
+     * Records an export call.
+     */
+    recordExport(name: string, args: unknown[]): string;
+    /**
+     * Completes an event with result.
+     */
+    completeEvent(id: string, result: unknown, startTime: number): void;
+    /**
+     * Fails an event with error.
+     */
+    failEvent(id: string, error: string, startTime: number): void;
+    /**
+     * Adds a listener for events.
+     */
+    addListener(listener: (event: DevEvent) => void): () => void;
+    /**
+     * Gets events filtered by type.
+     */
+    getEventsByType(type: DevEvent['type']): DevEvent[];
+    /**
+     * Gets events within a time range.
+     */
+    getEventsByTimeRange(startTime: number, endTime: number): DevEvent[];
+    /**
+     * Gets statistics about recorded events.
+     */
+    getStatistics(): {
+        total: number;
+        byType: Record<string, number>;
+        avgDuration: number;
+        errors: number;
+    };
+    private generateEventId;
+    private addToHistory;
+    private notifyListeners;
+}

package/dist/runtime/server/devmode/event-interceptor.service.js

@@ -0,0 +1,233 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { injectable } from 'tsyringe';
+import { IDevModeInterceptor } from './contracts/IDevModeInterceptor';
+/**
+ * Implementation of the DevMode event interceptor.
+ *
+ * Captures and records all framework events for debugging and analysis.
+ * Events are stored in a circular buffer with configurable size.
+ */
+let EventInterceptorService = class EventInterceptorService extends IDevModeInterceptor {
+    enabled = false;
+    history = [];
+    pendingEvents = new Map();
+    options;
+    eventCounter = 0;
+    listeners = [];
+    constructor() {
+        super();
+        this.options = {
+            enabled: true,
+            recordHistory: true,
+            maxHistorySize: 1000,
+        };
+    }
+    /**
+     * Configures the interceptor options.
+     */
+    configure(options) {
+        this.options = { ...this.options, ...options };
+        this.enabled = this.options.enabled;
+    }
+    onEventBefore(event) {
+        if (!this.enabled)
+            return;
+        const fullEvent = {
+            ...event,
+            id: this.generateEventId(),
+        };
+        this.notifyListeners(fullEvent);
+    }
+    onEventAfter(event) {
+        if (!this.enabled)
+            return;
+        if (this.options.recordHistory) {
+            this.addToHistory(event);
+        }
+        this.notifyListeners(event);
+    }
+    onEventError(event) {
+        if (!this.enabled)
+            return;
+        if (this.options.recordHistory) {
+            this.addToHistory(event);
+        }
+        this.notifyListeners(event);
+    }
+    getEventHistory() {
+        return [...this.history];
+    }
+    clearHistory() {
+        this.history = [];
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Creates an event ID for tracking.
+     */
+    createEventId() {
+        return this.generateEventId();
+    }
+    /**
+     * Records a net event.
+     */
+    recordNetEvent(name, direction, args, source) {
+        const id = this.generateEventId();
+        const event = {
+            id,
+            timestamp: Date.now(),
+            type: 'net',
+            name,
+            direction,
+            args,
+            source,
+        };
+        this.pendingEvents.set(id, event);
+        this.onEventBefore(event);
+        return id;
+    }
+    /**
+     * Records a command execution.
+     */
+    recordCommand(name, args, source) {
+        const id = this.generateEventId();
+        const event = {
+            id,
+            timestamp: Date.now(),
+            type: 'command',
+            name,
+            direction: 'in',
+            args,
+            source,
+        };
+        this.pendingEvents.set(id, event);
+        this.onEventBefore(event);
+        return id;
+    }
+    /**
+     * Records an export call.
+     */
+    recordExport(name, args) {
+        const id = this.generateEventId();
+        const event = {
+            id,
+            timestamp: Date.now(),
+            type: 'export',
+            name,
+            direction: 'in',
+            args,
+        };
+        this.pendingEvents.set(id, event);
+        this.onEventBefore(event);
+        return id;
+    }
+    /**
+     * Completes an event with result.
+     */
+    completeEvent(id, result, startTime) {
+        const event = this.pendingEvents.get(id);
+        if (event) {
+            event.result = result;
+            event.duration = Date.now() - startTime;
+            this.pendingEvents.delete(id);
+            this.onEventAfter(event);
+        }
+    }
+    /**
+     * Fails an event with error.
+     */
+    failEvent(id, error, startTime) {
+        const event = this.pendingEvents.get(id);
+        if (event) {
+            event.error = error;
+            event.duration = Date.now() - startTime;
+            this.pendingEvents.delete(id);
+            this.onEventError(event);
+        }
+    }
+    /**
+     * Adds a listener for events.
+     */
+    addListener(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index !== -1) {
+                this.listeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Gets events filtered by type.
+     */
+    getEventsByType(type) {
+        return this.history.filter((e) => e.type === type);
+    }
+    /**
+     * Gets events within a time range.
+     */
+    getEventsByTimeRange(startTime, endTime) {
+        return this.history.filter((e) => e.timestamp >= startTime && e.timestamp <= endTime);
+    }
+    /**
+     * Gets statistics about recorded events.
+     */
+    getStatistics() {
+        const byType = {};
+        let totalDuration = 0;
+        let durationCount = 0;
+        let errors = 0;
+        for (const event of this.history) {
+            byType[event.type] = (byType[event.type] || 0) + 1;
+            if (event.duration !== undefined) {
+                totalDuration += event.duration;
+                durationCount++;
+            }
+            if (event.error) {
+                errors++;
+            }
+        }
+        return {
+            total: this.history.length,
+            byType,
+            avgDuration: durationCount > 0 ? totalDuration / durationCount : 0,
+            errors,
+        };
+    }
+    generateEventId() {
+        return `evt_${Date.now()}_${++this.eventCounter}`;
+    }
+    addToHistory(event) {
+        this.history.push(event);
+        if (this.history.length > this.options.maxHistorySize) {
+            this.history.shift();
+        }
+    }
+    notifyListeners(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+};
+EventInterceptorService = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [])
+], EventInterceptorService);
+export { EventInterceptorService };

package/dist/runtime/server/devmode/index.d.ts

@@ -0,0 +1,6 @@
+export { DevModeService } from './dev-mode.service';
+export { EventInterceptorService } from './event-interceptor.service';
+export { PlayerSimulatorService } from './player-simulator.service';
+export { StateInspectorService } from './state-inspector.service';
+export type { BridgeMessage, BridgeOptions, DevEvent, DevModeOptions, InterceptorOptions, RuntimeSnapshot, SimulatedPlayer, SimulatedPlayerOptions, SimulatorOptions, } from './types';
+export { DEFAULT_DEVMODE_OPTIONS } from './types';

package/dist/runtime/server/devmode/index.js

@@ -0,0 +1,7 @@
+// DevMode - Development tools for OpenCore
+// Contracts
+export { DevModeService } from './dev-mode.service';
+export { EventInterceptorService } from './event-interceptor.service';
+export { PlayerSimulatorService } from './player-simulator.service';
+export { StateInspectorService } from './state-inspector.service';
+export { DEFAULT_DEVMODE_OPTIONS } from './types';

package/dist/runtime/server/devmode/player-simulator.service.d.ts

@@ -0,0 +1,66 @@
+import { SimulatedPlayer, SimulatedPlayerOptions } from './types';
+/**
+ * Service for simulating player connections during development.
+ *
+ * Allows developers to test their code without needing actual FiveM clients.
+ * Simulated players can emit events and execute commands.
+ */
+export declare class PlayerSimulatorService {
+    private simulatedPlayers;
+    private clientIdCounter;
+    private get events();
+    private get sessionLifecycle();
+    /**
+     * Connects a simulated player.
+     * @param options - Player configuration
+     * @returns Simulated player instance
+     */
+    connect(options?: Partial<SimulatedPlayerOptions>): SimulatedPlayer;
+    /**
+     * Disconnects a simulated player.
+     * @param clientId - Client ID to disconnect
+     */
+    disconnect(clientId: number): void;
+    /**
+     * Connects multiple simulated players.
+     * @param count - Number of players to connect
+     * @param baseOptions - Base options for all players
+     * @returns Array of simulated players
+     */
+    connectMany(count: number, baseOptions?: Partial<SimulatedPlayerOptions>): SimulatedPlayer[];
+    /**
+     * Disconnects all simulated players.
+     */
+    disconnectAll(): void;
+    /**
+     * Gets all simulated players.
+     */
+    getAll(): SimulatedPlayer[];
+    /**
+     * Gets a simulated player by client ID.
+     */
+    get(clientId: number): SimulatedPlayer | null;
+    /**
+     * Sets network latency for a simulated player.
+     * @param clientId - Client ID
+     * @param latency - Latency in milliseconds
+     */
+    setNetworkLatency(clientId: number, latency: number): void;
+    /**
+     * Simulates a net event from a player.
+     * @param clientId - Client ID
+     * @param eventName - Event name
+     * @param args - Event arguments
+     */
+    emitAsPlayer(clientId: number, eventName: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Gets statistics about simulated players.
+     */
+    getStatistics(): {
+        total: number;
+        connected: number;
+        avgLatency: number;
+    };
+    private createSimulatedPlayerInterface;
+    private delay;
+}