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

package/dist/runtime/server/default/default-command-error-observer.d.ts

@@ -0,0 +1,14 @@
+import { type CommandErrorContext, CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
+/**
+ * Default implementation for {@link CommandErrorObserverContract}.
+ *
+ * @remarks
+ * The framework ships with a safe default that only logs.
+ * Projects can override this by registering their own observer in the DI container.
+ */
+export declare class DefaultCommandErrorObserver extends CommandErrorObserverContract {
+    /**
+     * Logs the error context using the command logger.
+     */
+    onError(ctx: CommandErrorContext): Promise<void>;
+}

package/dist/runtime/server/default/default-command-error-observer.js

@@ -0,0 +1,40 @@
+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 { loggers } from '../../../kernel/logger';
+import { CommandErrorObserverContract, } from '../contracts/security/command-error-observer.contract';
+/**
+ * Default implementation for {@link CommandErrorObserverContract}.
+ *
+ * @remarks
+ * The framework ships with a safe default that only logs.
+ * Projects can override this by registering their own observer in the DI container.
+ */
+let DefaultCommandErrorObserver = class DefaultCommandErrorObserver extends CommandErrorObserverContract {
+    /**
+     * Logs the error context using the command logger.
+     */
+    async onError(ctx) {
+        loggers.command.error(`Command error`, {
+            mode: ctx.mode,
+            scope: ctx.scope,
+            stage: ctx.stage,
+            command: ctx.commandName,
+            ownerResourceName: ctx.ownerResourceName,
+            playerId: ctx.player.clientId,
+            accountId: ctx.player.accountId,
+            code: ctx.error.code,
+            origin: ctx.error.origin,
+            message: ctx.error.message,
+            details: ctx.error.details,
+        });
+    }
+};
+DefaultCommandErrorObserver = __decorate([
+    injectable()
+], DefaultCommandErrorObserver);
+export { DefaultCommandErrorObserver };

package/dist/runtime/server/default/default-net-event-security-observer.d.ts

@@ -0,0 +1,15 @@
+import { type NetEventInvalidPayloadContext, NetEventSecurityObserverContract } from '../contracts/security/net-event-security-observer.contract';
+import { Player } from '../entities/player';
+/**
+ * Default net-event security observer.
+ *
+ * @remarks
+ * This implementation is a no-op. Projects can provide an implementation via DI to log invalid
+ * payloads, emit metrics, or apply additional security actions.
+ */
+export declare class DefaultNetEventSecurityObserver extends NetEventSecurityObserverContract {
+    /**
+     * Called when a net event payload fails validation.
+     */
+    onInvalidPayload(_player: Player, _ctx: NetEventInvalidPayloadContext): Promise<void>;
+}

package/dist/runtime/server/default/default-net-event-security-observer.js

@@ -0,0 +1,25 @@
+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 { NetEventSecurityObserverContract, } from '../contracts/security/net-event-security-observer.contract';
+/**
+ * Default net-event security observer.
+ *
+ * @remarks
+ * This implementation is a no-op. Projects can provide an implementation via DI to log invalid
+ * payloads, emit metrics, or apply additional security actions.
+ */
+let DefaultNetEventSecurityObserver = class DefaultNetEventSecurityObserver extends NetEventSecurityObserverContract {
+    /**
+     * Called when a net event payload fails validation.
+     */
+    async onInvalidPayload(_player, _ctx) { }
+};
+DefaultNetEventSecurityObserver = __decorate([
+    injectable()
+], DefaultNetEventSecurityObserver);
+export { DefaultNetEventSecurityObserver };

package/dist/runtime/server/default/default-principal.provider.d.ts

@@ -0,0 +1,13 @@
+import { Principal } from '../types/principal.type';
+import { PrincipalProviderContract } from '../contracts/security/principal-provider.contract';
+import { LinkedID } from '../types/linked-id';
+import { Player } from '../entities';
+/**
+ * Default principal provider that grants no permissions.
+ * Used when no custom principal provider is configured.
+ */
+export declare class DefaultPrincipalProvider extends PrincipalProviderContract {
+    getPrincipal(player: Player): Promise<Principal | null>;
+    refreshPrincipal(_player: Player): Promise<void>;
+    getPrincipalByLinkedID(linkedID: LinkedID): Promise<Principal | null>;
+}

package/dist/runtime/server/default/default-principal.provider.js

@@ -0,0 +1,35 @@
+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 { PrincipalProviderContract } from '../contracts/security/principal-provider.contract';
+/**
+ * Default principal provider that grants no permissions.
+ * Used when no custom principal provider is configured.
+ */
+let DefaultPrincipalProvider = class DefaultPrincipalProvider extends PrincipalProviderContract {
+    async getPrincipal(player) {
+        return {
+            id: player.accountID || player.clientID.toString(),
+            permissions: [],
+            rank: 0,
+        };
+    }
+    async refreshPrincipal(_player) {
+        // No-op
+    }
+    async getPrincipalByLinkedID(linkedID) {
+        return {
+            id: String(linkedID),
+            permissions: [],
+            rank: 0,
+        };
+    }
+};
+DefaultPrincipalProvider = __decorate([
+    injectable()
+], DefaultPrincipalProvider);
+export { DefaultPrincipalProvider };

package/dist/runtime/server/default/default-security.handler.d.ts

@@ -0,0 +1,19 @@
+import { SecurityError } from '../../../kernel/error/security.error';
+import { SecurityHandlerContract } from '../contracts/security/security-handler.contract';
+import { Player } from '../entities';
+/**
+ * Default implementation of the security handler.
+ *
+ * @remarks
+ * The default behavior is to log security violations. Projects can provide their own
+ * implementation via DI to apply stricter policies (kick/ban/metrics).
+ */
+export declare class DefaultSecurityHandler extends SecurityHandlerContract {
+    /**
+     * Handles a detected security violation.
+     *
+     * @param player - Player who triggered the violation.
+     * @param error - Security error describing the violation.
+     */
+    handleViolation(player: Player, error: SecurityError): Promise<void>;
+}

package/dist/runtime/server/default/default-security.handler.js

@@ -0,0 +1,36 @@
+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 { loggers } from '../../../kernel/logger';
+import { SecurityHandlerContract } from '../contracts/security/security-handler.contract';
+/**
+ * Default implementation of the security handler.
+ *
+ * @remarks
+ * The default behavior is to log security violations. Projects can provide their own
+ * implementation via DI to apply stricter policies (kick/ban/metrics).
+ */
+let DefaultSecurityHandler = class DefaultSecurityHandler extends SecurityHandlerContract {
+    /**
+     * Handles a detected security violation.
+     *
+     * @param player - Player who triggered the violation.
+     * @param error - Security error describing the violation.
+     */
+    async handleViolation(player, error) {
+        loggers.security.warn(`Security violation detected`, {
+            playerName: player.name,
+            playerId: player.clientID,
+            message: error.message,
+            suggestedAction: error.action,
+        });
+    }
+};
+DefaultSecurityHandler = __decorate([
+    injectable()
+], DefaultSecurityHandler);
+export { DefaultSecurityHandler };

package/dist/runtime/server/devmode/contracts/IDevModeBridge.d.ts

@@ -0,0 +1,36 @@
+import { BridgeMessage } from '../types';
+/**
+ * Contract for the WebSocket bridge between framework and CLI.
+ *
+ * Enables real-time communication for log streaming, event monitoring,
+ * and remote commands during development.
+ */
+export declare abstract class IDevModeBridge {
+    /**
+     * Connects to the CLI WebSocket server.
+     * @param url - WebSocket URL to connect to
+     */
+    abstract connect(url: string): Promise<void>;
+    /**
+     * Disconnects from the CLI.
+     */
+    abstract disconnect(): void;
+    /**
+     * Sends a message to the CLI.
+     * @param message - Message to send
+     */
+    abstract send(message: BridgeMessage): void;
+    /**
+     * Registers a message handler.
+     * @param handler - Function to handle incoming messages
+     */
+    abstract onMessage(handler: (message: BridgeMessage) => void): void;
+    /**
+     * Checks if currently connected.
+     */
+    abstract isConnected(): boolean;
+    /**
+     * Gets the current connection URL.
+     */
+    abstract getUrl(): string | null;
+}

package/dist/runtime/server/devmode/contracts/IDevModeBridge.js

@@ -0,0 +1,8 @@
+/**
+ * Contract for the WebSocket bridge between framework and CLI.
+ *
+ * Enables real-time communication for log streaming, event monitoring,
+ * and remote commands during development.
+ */
+export class IDevModeBridge {
+}

package/dist/runtime/server/devmode/contracts/IDevModeInspector.d.ts

@@ -0,0 +1,52 @@
+import { RuntimeSnapshot } from '../types';
+/**
+ * Handler metadata for inspection.
+ */
+export interface HandlerInfo {
+    name: string;
+    controller: string;
+    method: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * DI registration info for inspection.
+ */
+export interface DIRegistration {
+    token: string;
+    implementation: string;
+    lifecycle: 'singleton' | 'transient';
+}
+/**
+ * Contract for inspecting runtime state during development.
+ *
+ * Provides insights into registered handlers, DI container state,
+ * and player information for debugging purposes.
+ */
+export declare abstract class IDevModeInspector {
+    /**
+     * Captures a complete snapshot of the current runtime state.
+     * @returns Runtime snapshot with all relevant information
+     */
+    abstract captureSnapshot(): RuntimeSnapshot;
+    /**
+     * Gets all registered handlers grouped by type.
+     * @returns Map of handler type to handler info array
+     */
+    abstract getRegisteredHandlers(): Map<string, HandlerInfo[]>;
+    /**
+     * Gets the DI container registration graph.
+     * @returns Array of DI registrations
+     */
+    abstract getDIGraph(): DIRegistration[];
+    /**
+     * Gets player states for all connected players.
+     * @returns Map of client ID to state array
+     */
+    abstract getPlayerStates(): Map<number, string[]>;
+    /**
+     * Gets detailed info for a specific handler.
+     * @param type - Handler type (command, netEvent, export, etc.)
+     * @param name - Handler name
+     */
+    abstract getHandlerInfo(type: string, name: string): HandlerInfo | null;
+}

package/dist/runtime/server/devmode/contracts/IDevModeInspector.js

@@ -0,0 +1,8 @@
+/**
+ * Contract for inspecting runtime state during development.
+ *
+ * Provides insights into registered handlers, DI container state,
+ * and player information for debugging purposes.
+ */
+export class IDevModeInspector {
+}

package/dist/runtime/server/devmode/contracts/IDevModeInterceptor.d.ts

@@ -0,0 +1,41 @@
+import { DevEvent } from '../types';
+/**
+ * Contract for intercepting and recording runtime events.
+ *
+ * Used for debugging, monitoring, and replaying events during development.
+ */
+export declare abstract class IDevModeInterceptor {
+    /**
+     * Called before an event is processed.
+     * @param event - Event data without result/duration
+     */
+    abstract onEventBefore(event: Omit<DevEvent, 'result' | 'duration'>): void;
+    /**
+     * Called after an event completes successfully.
+     * @param event - Complete event data including result and duration
+     */
+    abstract onEventAfter(event: DevEvent): void;
+    /**
+     * Called when an event fails with an error.
+     * @param event - Event data with error information
+     */
+    abstract onEventError(event: DevEvent): void;
+    /**
+     * Gets the recorded event history.
+     * @returns Array of recorded events
+     */
+    abstract getEventHistory(): DevEvent[];
+    /**
+     * Clears the event history.
+     */
+    abstract clearHistory(): void;
+    /**
+     * Enables or disables event interception.
+     * @param enabled - Whether to enable interception
+     */
+    abstract setEnabled(enabled: boolean): void;
+    /**
+     * Checks if interception is enabled.
+     */
+    abstract isEnabled(): boolean;
+}

package/dist/runtime/server/devmode/contracts/IDevModeInterceptor.js

@@ -0,0 +1,7 @@
+/**
+ * Contract for intercepting and recording runtime events.
+ *
+ * Used for debugging, monitoring, and replaying events during development.
+ */
+export class IDevModeInterceptor {
+}

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

@@ -0,0 +1,3 @@
+export { IDevModeBridge } from './IDevModeBridge';
+export { type DIRegistration, type HandlerInfo, IDevModeInspector } from './IDevModeInspector';
+export { IDevModeInterceptor } from './IDevModeInterceptor';

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

@@ -0,0 +1,3 @@
+export { IDevModeBridge } from './IDevModeBridge';
+export { IDevModeInspector } from './IDevModeInspector';
+export { IDevModeInterceptor } from './IDevModeInterceptor';

package/dist/runtime/server/devmode/dev-mode.service.d.ts

@@ -0,0 +1,109 @@
+import { EventInterceptorService } from './event-interceptor.service';
+import { PlayerSimulatorService } from './player-simulator.service';
+import { StateInspectorService } from './state-inspector.service';
+import { BridgeMessage, DevEvent, DevModeOptions, RuntimeSnapshot } from './types';
+/**
+ * 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
+ */
+export declare class DevModeService {
+    private enabled;
+    private options;
+    private logTransport;
+    private get interceptor();
+    private get inspector();
+    private get simulator();
+    /**
+     * Enables DevMode with the specified options.
+     * @param options - DevMode configuration
+     */
+    enable(options: DevModeOptions): Promise<void>;
+    /**
+     * Disables DevMode and cleans up resources.
+     */
+    disable(): void;
+    /**
+     * Checks if DevMode is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Gets the current DevMode options.
+     */
+    getOptions(): DevModeOptions | null;
+    /**
+     * 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)
+     */
+    connectToBridge(url: string): Promise<void>;
+    /**
+     * Disconnects from the CLI bridge.
+     */
+    disconnectFromBridge(): Promise<void>;
+    /**
+     * 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: BridgeMessage): void;
+    /**
+     * Captures a snapshot of the current runtime state.
+     */
+    captureSnapshot(): RuntimeSnapshot;
+    /**
+     * Gets a summary of the current runtime state.
+     */
+    getSummary(): ReturnType<StateInspectorService['getSummary']>;
+    /**
+     * Gets detailed information about a specific player.
+     * @param clientId - Client ID
+     */
+    getPlayerDetails(clientId: number): Record<string, unknown> | null;
+    /**
+     * Gets the recorded event history.
+     */
+    getEventHistory(): DevEvent[];
+    /**
+     * Clears the event history.
+     */
+    clearEventHistory(): void;
+    /**
+     * Gets event statistics.
+     */
+    getEventStatistics(): ReturnType<EventInterceptorService['getStatistics']>;
+    /**
+     * Adds a listener for events.
+     * @param listener - Event listener function
+     * @returns Unsubscribe function
+     */
+    onEvent(listener: (event: DevEvent) => void): () => void;
+    /**
+     * Connects a simulated player.
+     * @param options - Player options
+     */
+    connectPlayer(options?: Parameters<PlayerSimulatorService['connect']>[0]): import("./types").SimulatedPlayer;
+    /**
+     * Disconnects a simulated player.
+     * @param clientId - Client ID
+     */
+    disconnectPlayer(clientId: number): void;
+    /**
+     * Connects multiple simulated players.
+     * @param count - Number of players
+     * @param options - Base options
+     */
+    connectPlayers(count: number, options?: Parameters<PlayerSimulatorService['connect']>[0]): import("./types").SimulatedPlayer[];
+    /**
+     * Gets simulated player statistics.
+     */
+    getSimulatorStatistics(): ReturnType<PlayerSimulatorService['getStatistics']>;
+    private handleBridgeMessage;
+    private handleRemoteCommand;
+}