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

package/dist/runtime/server/devmode/player-simulator.service.js

@@ -0,0 +1,199 @@
+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 { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { GLOBAL_CONTAINER } from '../../../kernel/di/container';
+import { loggers } from '../../../kernel/logger';
+import { PlayerSessionLifecyclePort } from '../ports/internal/player-session-lifecycle.port';
+/**
+ * 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.
+ */
+let PlayerSimulatorService = class PlayerSimulatorService {
+    simulatedPlayers = new Map();
+    clientIdCounter = 90000; // Start high to avoid conflicts with real players
+    get events() {
+        return GLOBAL_CONTAINER.resolve(EventsAPI);
+    }
+    get sessionLifecycle() {
+        return GLOBAL_CONTAINER.resolve(PlayerSessionLifecyclePort);
+    }
+    /**
+     * Connects a simulated player.
+     * @param options - Player configuration
+     * @returns Simulated player instance
+     */
+    connect(options) {
+        const clientId = options?.clientId ?? this.clientIdCounter++;
+        const name = options?.name ?? `SimPlayer_${clientId}`;
+        const accountId = options?.accountId ?? `sim_account_${clientId}`;
+        // Create the simulated player data
+        const playerData = {
+            clientId,
+            name,
+            accountId,
+            rank: options?.rank ?? 0,
+            permissions: options?.permissions ?? [],
+            states: options?.states ?? [],
+            metadata: options?.metadata ?? {},
+            connected: true,
+            networkLatency: 0,
+        };
+        this.simulatedPlayers.set(clientId, playerData);
+        // Bind player session via lifecycle port
+        try {
+            this.sessionLifecycle.bind(clientId, {
+                license: `sim_${accountId}`,
+                discord: `sim_${clientId}`,
+            });
+        }
+        catch (error) {
+            loggers.bootstrap.warn('[DevMode] Could not bind player session', {
+                clientId,
+                error: error.message,
+            });
+        }
+        loggers.bootstrap.info(`[DevMode] Simulated player connected: ${name} (${clientId})`);
+        // Return the simulated player interface
+        return this.createSimulatedPlayerInterface(playerData);
+    }
+    /**
+     * Disconnects a simulated player.
+     * @param clientId - Client ID to disconnect
+     */
+    disconnect(clientId) {
+        const player = this.simulatedPlayers.get(clientId);
+        if (!player)
+            return;
+        player.connected = false;
+        // Unbind player session
+        try {
+            this.sessionLifecycle.unbind(clientId);
+        }
+        catch (error) {
+            loggers.bootstrap.warn('[DevMode] Could not unbind player session', {
+                clientId,
+                error: error.message,
+            });
+        }
+        this.simulatedPlayers.delete(clientId);
+        loggers.bootstrap.info(`[DevMode] Simulated player disconnected: ${player.name} (${clientId})`);
+    }
+    /**
+     * 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, baseOptions) {
+        const players = [];
+        for (let i = 0; i < count; i++) {
+            players.push(this.connect({
+                ...baseOptions,
+                name: baseOptions?.name ? `${baseOptions.name}_${i}` : undefined,
+            }));
+        }
+        return players;
+    }
+    /**
+     * Disconnects all simulated players.
+     */
+    disconnectAll() {
+        for (const clientId of this.simulatedPlayers.keys()) {
+            this.disconnect(clientId);
+        }
+    }
+    /**
+     * Gets all simulated players.
+     */
+    getAll() {
+        return Array.from(this.simulatedPlayers.values())
+            .filter((p) => p.connected)
+            .map((p) => this.createSimulatedPlayerInterface(p));
+    }
+    /**
+     * Gets a simulated player by client ID.
+     */
+    get(clientId) {
+        const player = this.simulatedPlayers.get(clientId);
+        if (!player || !player.connected)
+            return null;
+        return this.createSimulatedPlayerInterface(player);
+    }
+    /**
+     * Sets network latency for a simulated player.
+     * @param clientId - Client ID
+     * @param latency - Latency in milliseconds
+     */
+    setNetworkLatency(clientId, latency) {
+        const player = this.simulatedPlayers.get(clientId);
+        if (player) {
+            player.networkLatency = latency;
+        }
+    }
+    /**
+     * Simulates a net event from a player.
+     * @param clientId - Client ID
+     * @param eventName - Event name
+     * @param args - Event arguments
+     */
+    async emitAsPlayer(clientId, eventName, ...args) {
+        const player = this.simulatedPlayers.get(clientId);
+        if (!player || !player.connected) {
+            throw new Error(`Simulated player ${clientId} not found or disconnected`);
+        }
+        // Add artificial latency if configured
+        if (player.networkLatency > 0) {
+            await this.delay(player.networkLatency);
+        }
+        // Use the node transport to simulate the event
+        const events = this.events;
+        if (typeof events.simulateClientEvent === 'function') {
+            events.simulateClientEvent(eventName, clientId, ...args);
+        }
+        else {
+            loggers.bootstrap.warn('[DevMode] Transport does not support event simulation');
+        }
+    }
+    /**
+     * Gets statistics about simulated players.
+     */
+    getStatistics() {
+        const players = Array.from(this.simulatedPlayers.values());
+        const connected = players.filter((p) => p.connected);
+        const avgLatency = connected.length > 0
+            ? connected.reduce((sum, p) => sum + p.networkLatency, 0) / connected.length
+            : 0;
+        return {
+            total: players.length,
+            connected: connected.length,
+            avgLatency,
+        };
+    }
+    createSimulatedPlayerInterface(data) {
+        return {
+            clientId: data.clientId,
+            connected: data.connected,
+            networkLatency: data.networkLatency,
+            emit: (eventName, ...args) => {
+                void this.emitAsPlayer(data.clientId, eventName, ...args);
+            },
+            disconnect: () => {
+                this.disconnect(data.clientId);
+            },
+        };
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+};
+PlayerSimulatorService = __decorate([
+    injectable()
+], PlayerSimulatorService);
+export { PlayerSimulatorService };

package/dist/runtime/server/devmode/state-inspector.service.d.ts

@@ -0,0 +1,57 @@
+import { type DIRegistration, type HandlerInfo, IDevModeInspector } from './contracts/IDevModeInspector';
+import { RuntimeSnapshot } from './types';
+/**
+ * Implementation of the DevMode state inspector.
+ *
+ * Provides runtime introspection capabilities for debugging
+ * and monitoring during development.
+ */
+export declare class StateInspectorService extends IDevModeInspector {
+    private commandHandlers;
+    private netEventHandlers;
+    private exportHandlers;
+    private runtimeEventHandlers;
+    private get players();
+    captureSnapshot(): RuntimeSnapshot;
+    getRegisteredHandlers(): Map<string, HandlerInfo[]>;
+    getDIGraph(): DIRegistration[];
+    getPlayerStates(): Map<number, string[]>;
+    getHandlerInfo(type: string, name: string): HandlerInfo | null;
+    /**
+     * Registers a command handler for tracking.
+     */
+    registerCommandHandler(name: string, info: HandlerInfo): void;
+    /**
+     * Registers a net event handler for tracking.
+     */
+    registerNetEventHandler(name: string, info: HandlerInfo): void;
+    /**
+     * Registers an export handler for tracking.
+     */
+    registerExportHandler(name: string, info: HandlerInfo): void;
+    /**
+     * Registers a runtime event handler for tracking.
+     */
+    registerRuntimeEventHandler(name: string, info: HandlerInfo): void;
+    /**
+     * Gets all commands with their metadata.
+     */
+    getAllCommands(): Array<{
+        name: string;
+        info: HandlerInfo;
+    }>;
+    /**
+     * Gets detailed player information for debugging.
+     */
+    getPlayerDetails(clientId: number): Record<string, unknown> | null;
+    /**
+     * Gets a summary of the current runtime state.
+     */
+    getSummary(): {
+        mode: string;
+        playerCount: number;
+        handlerCounts: Record<string, number>;
+        uptime: number;
+    };
+    private getDIContainerInfo;
+}

package/dist/runtime/server/devmode/state-inspector.service.js

@@ -0,0 +1,175 @@
+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 { getRuntimeContext } from '../runtime';
+import { Players } from '../ports/players.api-port';
+import { IDevModeInspector, } from './contracts/IDevModeInspector';
+/**
+ * Implementation of the DevMode state inspector.
+ *
+ * Provides runtime introspection capabilities for debugging
+ * and monitoring during development.
+ */
+let StateInspectorService = class StateInspectorService extends IDevModeInspector {
+    commandHandlers = new Map();
+    netEventHandlers = new Map();
+    exportHandlers = new Map();
+    runtimeEventHandlers = new Map();
+    get players() {
+        return GLOBAL_CONTAINER.resolve(Players);
+    }
+    captureSnapshot() {
+        const ctx = getRuntimeContext();
+        const allPlayers = this.players.getAll();
+        return {
+            timestamp: Date.now(),
+            mode: ctx.mode,
+            features: Object.fromEntries(Object.entries(ctx.features).map(([key, value]) => [key, value.enabled])),
+            players: {
+                count: allPlayers.length,
+                ids: allPlayers.map((p) => p.clientID),
+            },
+            handlers: {
+                commands: Array.from(this.commandHandlers.keys()),
+                netEvents: Array.from(this.netEventHandlers.keys()),
+                exports: Array.from(this.exportHandlers.keys()),
+                runtimeEvents: Array.from(this.runtimeEventHandlers.keys()),
+            },
+            diContainer: this.getDIContainerInfo(),
+        };
+    }
+    getRegisteredHandlers() {
+        const result = new Map();
+        result.set('commands', Array.from(this.commandHandlers.values()));
+        result.set('netEvents', Array.from(this.netEventHandlers.values()));
+        result.set('exports', Array.from(this.exportHandlers.values()));
+        result.set('runtimeEvents', Array.from(this.runtimeEventHandlers.values()));
+        return result;
+    }
+    getDIGraph() {
+        const registrations = [];
+        // Get registrations from the DI container
+        // Note: This is a simplified implementation
+        // The actual implementation depends on tsyringe internals
+        try {
+            const container = GLOBAL_CONTAINER;
+            if (container._registry) {
+                for (const [token, registration] of container._registry) {
+                    const tokenName = typeof token === 'function' ? token.name : String(token);
+                    registrations.push({
+                        token: tokenName,
+                        implementation: registration?.provider?.useClass?.name ?? 'unknown',
+                        lifecycle: registration?.options?.lifecycle === 0 ? 'transient' : 'singleton',
+                    });
+                }
+            }
+        }
+        catch {
+            // Fallback if we can't access internals
+        }
+        return registrations;
+    }
+    getPlayerStates() {
+        const states = new Map();
+        const allPlayers = this.players.getAll();
+        for (const player of allPlayers) {
+            states.set(player.clientID, player.getStates());
+        }
+        return states;
+    }
+    getHandlerInfo(type, name) {
+        switch (type) {
+            case 'command':
+                return this.commandHandlers.get(name) ?? null;
+            case 'netEvent':
+                return this.netEventHandlers.get(name) ?? null;
+            case 'export':
+                return this.exportHandlers.get(name) ?? null;
+            case 'runtimeEvent':
+                return this.runtimeEventHandlers.get(name) ?? null;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Registers a command handler for tracking.
+     */
+    registerCommandHandler(name, info) {
+        this.commandHandlers.set(name, info);
+    }
+    /**
+     * Registers a net event handler for tracking.
+     */
+    registerNetEventHandler(name, info) {
+        this.netEventHandlers.set(name, info);
+    }
+    /**
+     * Registers an export handler for tracking.
+     */
+    registerExportHandler(name, info) {
+        this.exportHandlers.set(name, info);
+    }
+    /**
+     * Registers a runtime event handler for tracking.
+     */
+    registerRuntimeEventHandler(name, info) {
+        this.runtimeEventHandlers.set(name, info);
+    }
+    /**
+     * Gets all commands with their metadata.
+     */
+    getAllCommands() {
+        return Array.from(this.commandHandlers.entries()).map(([name, info]) => ({
+            name,
+            info,
+        }));
+    }
+    /**
+     * Gets detailed player information for debugging.
+     */
+    getPlayerDetails(clientId) {
+        const player = this.players.getByClient(clientId);
+        if (!player)
+            return null;
+        return {
+            clientId: player.clientID,
+            accountId: player.accountID,
+            name: player.name,
+            states: player.getStates(),
+            position: player.getPosition(),
+        };
+    }
+    /**
+     * Gets a summary of the current runtime state.
+     */
+    getSummary() {
+        const ctx = getRuntimeContext();
+        return {
+            mode: ctx.mode,
+            playerCount: this.players.getAll().length,
+            handlerCounts: {
+                commands: this.commandHandlers.size,
+                netEvents: this.netEventHandlers.size,
+                exports: this.exportHandlers.size,
+                runtimeEvents: this.runtimeEventHandlers.size,
+            },
+            uptime: process.uptime ? process.uptime() * 1000 : 0,
+        };
+    }
+    getDIContainerInfo() {
+        const registrations = this.getDIGraph();
+        return {
+            registrations: registrations.length,
+            singletons: registrations.filter((r) => r.lifecycle === 'singleton').map((r) => r.token),
+        };
+    }
+};
+StateInspectorService = __decorate([
+    injectable()
+], StateInspectorService);
+export { StateInspectorService };

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

@@ -0,0 +1,197 @@
+import { FrameworkMode } from '../runtime';
+/**
+ * Event captured by the DevMode interceptor.
+ */
+export interface DevEvent {
+    /** Unique event identifier */
+    id: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Type of event */
+    type: 'net' | 'command' | 'export' | 'runtime' | 'internal';
+    /** Event name */
+    name: string;
+    /** Direction of the event */
+    direction: 'in' | 'out';
+    /** Event arguments */
+    args: unknown[];
+    /** Result of the event (if completed) */
+    result?: unknown;
+    /** Error message (if failed) */
+    error?: string;
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Source information */
+    source?: {
+        clientId?: number;
+        resource?: string;
+    };
+}
+/**
+ * Message sent through the DevMode bridge.
+ *
+ * @remarks
+ * The bridge acts as a telemetry and control tunnel between the OpenCore runtime
+ * and the external CLI. It allows for real-time log streaming and state inspection.
+ */
+export interface BridgeMessage {
+    /**
+     * Message type:
+     * - 'log': Real-time server log streaming
+     * - 'event': Notification of a captured event (net, command, etc)
+     * - 'state': Runtime state snapshot response
+     * - 'command': Control command from CLI (e.g. trigger simulation)
+     * - 'ping'/'pong': Connection heartbeat
+     */
+    type: 'log' | 'event' | 'state' | 'command' | 'ping' | 'pong';
+    /** Data associated with the message */
+    payload: unknown;
+}
+/**
+ * Snapshot of the runtime state.
+ *
+ * @remarks
+ * Used by the CLI to visualize the current state of the framework without
+ * requiring game access.
+ */
+export interface RuntimeSnapshot {
+    /** Capture timestamp */
+    timestamp: number;
+    /** Current framework mode (CORE, RESOURCE, STANDALONE) */
+    mode: FrameworkMode;
+    /** Enabled features and their status */
+    features: Record<string, boolean>;
+    /** Player information (simulated and real) */
+    players: {
+        count: number;
+        ids: number[];
+    };
+    /** Registered handlers for discovery */
+    handlers: {
+        commands: string[];
+        netEvents: string[];
+        exports: string[];
+        runtimeEvents: string[];
+    };
+    /** DI container information */
+    diContainer: {
+        registrations: number;
+        singletons: string[];
+    };
+}
+/**
+ * Bridge configuration for CLI connection.
+ *
+ * @remarks
+ * The bridge enables advanced development features like log streaming to CLI
+ * and state inspection. It does NOT handle resource restarts (txAdmin handles that).
+ */
+export interface BridgeOptions {
+    /**
+     * WebSocket URL of the OpenCore CLI bridge.
+     * @defaultValue 'ws://localhost:3848'
+     */
+    url: string;
+    /**
+     * Whether to connect to the bridge automatically on startup.
+     * @defaultValue false
+     */
+    autoConnect: boolean;
+    /** Whether to attempt reconnection if connection is lost */
+    reconnect?: boolean;
+    /** Delay between reconnection attempts in milliseconds */
+    reconnectInterval?: number;
+}
+/**
+ * Event interceptor configuration.
+ *
+ * @remarks
+ * The interceptor captures and records all incoming/outgoing events (Net, Commands, etc.)
+ * for debugging purposes.
+ */
+export interface InterceptorOptions {
+    /** Enable event interception */
+    enabled: boolean;
+    /** Whether to keep a history of events in memory */
+    recordHistory: boolean;
+    /** Maximum number of events to keep in the history buffer */
+    maxHistorySize: number;
+}
+/**
+ * Player simulator configuration.
+ *
+ * @remarks
+ * The simulator allows for creating "virtual" players that the framework
+ * treats as real, enabling testing of permissions, economy, and logic without game clients.
+ */
+export interface SimulatorOptions {
+    /** Enable player simulation features */
+    enabled: boolean;
+    /** Number of virtual players to connect automatically on startup */
+    autoConnectPlayers: number;
+}
+/**
+ * Main DevMode configuration.
+ *
+ * @remarks
+ * Development mode provides tools for debugging, inspection, and simulation.
+ * It is dynamically loaded and should be disabled in production.
+ */
+export interface DevModeOptions {
+    /**
+     * Master switch for development mode.
+     * If false, no dev tools will be loaded.
+     */
+    enabled: boolean;
+    /**
+     * CLI Bridge configuration for telemetry and logs.
+     */
+    bridge?: BridgeOptions;
+    /**
+     * Event interceptor for debugging network/command flow.
+     */
+    interceptor?: InterceptorOptions;
+    /**
+     * Virtual player simulator for offline testing.
+     */
+    simulator?: SimulatorOptions;
+}
+/**
+ * Simulated player configuration.
+ */
+export interface SimulatedPlayerOptions {
+    /** Client ID (auto-generated if not provided) */
+    clientId?: number;
+    /** Account ID */
+    accountId?: string;
+    /** Player name */
+    name?: string;
+    /** Player rank */
+    rank?: number;
+    /** Player permissions */
+    permissions?: string[];
+    /** Initial states */
+    states?: string[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Simulated player instance.
+ */
+export interface SimulatedPlayer {
+    /** Client ID */
+    clientId: number;
+    /** Whether the player is connected */
+    connected: boolean;
+    /** Simulated network latency in ms */
+    networkLatency: number;
+    /** Emit a net event as this player */
+    emit(eventName: string, ...args: unknown[]): void;
+    /** Disconnect this player */
+    disconnect(): void;
+}
+/**
+ * Default DevMode configuration.
+ * Centered on telemetry and simulation, delegating resource management to CLI/txAdmin.
+ */
+export declare const DEFAULT_DEVMODE_OPTIONS: DevModeOptions;

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

@@ -0,0 +1,22 @@
+/**
+ * Default DevMode configuration.
+ * Centered on telemetry and simulation, delegating resource management to CLI/txAdmin.
+ */
+export const DEFAULT_DEVMODE_OPTIONS = {
+    enabled: false,
+    bridge: {
+        url: 'ws://localhost:3848',
+        autoConnect: false,
+        reconnect: true,
+        reconnectInterval: 5000,
+    },
+    interceptor: {
+        enabled: true,
+        recordHistory: true,
+        maxHistorySize: 1000,
+    },
+    simulator: {
+        enabled: true,
+        autoConnectPlayers: 0,
+    },
+};

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

@@ -0,0 +1,3 @@
+export * from './player';
+export * from './vehicle';
+export * from './npc';

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

@@ -0,0 +1,3 @@
+export * from './player';
+export * from './vehicle';
+export * from './npc';