@open-core/framework 0.1.0-alpha.1 → 0.2.1-beta.1

package/dist/{server → runtime/server}/controllers/chat.controller.js

@@ -12,39 +12,51 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatController = void 0;
 const controller_1 = require("../decorators/controller");
 const export_1 = require("../decorators/export");
-const services_1 = require("../services");
 const chat_service_1 = require("../services/chat.service");
+const player_directory_port_1 = require("../services/ports/player-directory.port");
 let ChatController = class ChatController {
-    constructor(chatService, playerService) {
+    constructor(chatService, playerDirectory) {
         this.chatService = chatService;
-        this.playerService = playerService;
+        this.playerDirectory = playerDirectory;
     }
-    apiBroadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
+    coreBroadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
         this.chatService.broadcast(message, author, color);
     }
-    apiSendPrivate(targetId, message, author = 'Private') {
-        const player = this.playerService.getByClient(targetId);
+    coreSendPrivate(targetId, message, author = 'Private') {
+        const player = this.playerDirectory.getByClient(targetId);
         if (!player) {
             throw new Error(`Player with client ID ${targetId} not found`);
         }
         this.chatService.sendPrivate(player, message, author);
     }
+    coreSendToGroupOfPlayers(targets, message, author = 'Private', color) {
+        const players = this.playerDirectory.getMany(targets);
+        for (let i = 0; i < players.length; i++) {
+            this.chatService.sendPrivate(players[i], message, author, color);
+        }
+    }
 };
 exports.ChatController = ChatController;
 __decorate([
-    (0, export_1.Export)('core:broadcast'),
+    (0, export_1.Export)(),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String, String, Object]),
     __metadata("design:returntype", void 0)
-], ChatController.prototype, "apiBroadcast", null);
+], ChatController.prototype, "coreBroadcast", null);
 __decorate([
-    (0, export_1.Export)('core:sendprivate'),
+    (0, export_1.Export)(),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Number, String, String]),
     __metadata("design:returntype", void 0)
-], ChatController.prototype, "apiSendPrivate", null);
+], ChatController.prototype, "coreSendPrivate", null);
+__decorate([
+    (0, export_1.Export)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array, String, String, Object]),
+    __metadata("design:returntype", void 0)
+], ChatController.prototype, "coreSendToGroupOfPlayers", null);
 exports.ChatController = ChatController = __decorate([
     (0, controller_1.Controller)(),
     __metadata("design:paramtypes", [chat_service_1.ChatService,
-        services_1.PlayerService])
+        player_directory_port_1.PlayerDirectoryPort])
 ], ChatController);

package/dist/runtime/server/controllers/command-export.controller.d.ts

@@ -0,0 +1,74 @@
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { Player } from '../entities';
+import { CommandExecutionPort, type CommandInfo } from '../services/ports/command-execution.port';
+import { PlayerDirectoryPort } from '../services/ports/player-directory.port';
+import { PrincipalPort } from '../services/ports/principal.port';
+import { RateLimiterService } from '../services/rate-limiter.service';
+import { CommandRegistrationDto, CoreCommandsExports } from '../types/core-exports';
+/**
+ * Export controller for command system (CORE mode only).
+ *
+ * @remarks
+ * Exposes command registration and execution to RESOURCE mode instances.
+ * Maintains a registry of both local and remote commands, delegating
+ * remote command execution back to the owning resource via net events.
+ */
+export declare class CommandExportController implements CoreCommandsExports {
+    private commandService;
+    private playerDirectory;
+    private principalPort;
+    private rateLimiter;
+    private engineEvents;
+    private remoteCommands;
+    constructor(commandService: CommandExecutionPort, playerDirectory: PlayerDirectoryPort, principalPort: PrincipalPort, rateLimiter: RateLimiterService, engineEvents: IEngineEvents);
+    /**
+     * Receives command execution requests from clients.
+     *
+     * @remarks
+     * This is the entry point for all command execution in CORE mode.
+     * Handles both local commands (registered in CORE) and remote commands
+     * (registered by RESOURCE mode instances).
+     */
+    onCommandReceived(player: Player, command: string, args: string[]): Promise<void>;
+    /**
+     * Registers a command from a RESOURCE with CORE.
+     *
+     * @remarks
+     * The command handler remains in the resource. CORE stores metadata
+     * and delegates execution back to the resource when invoked.
+     *
+     * Exported as: `exports[coreResourceName].registerCommand`
+     */
+    registerCommand(metadata: CommandRegistrationDto): void;
+    /**
+     * Executes a command (local or remote).
+     *
+     * @remarks
+     * If the command is registered locally in CORE, executes it directly.
+     * If it's a remote command, delegates to the owning resource via net event.
+     *
+     * Exported as: `exports[coreResourceName].executeCommand`
+     */
+    executeCommand(clientID: number, commandName: string, args: string[]): Promise<void>;
+    /**
+     * Returns all registered commands (local + remote).
+     *
+     * Exported as: `exports[coreResourceName].getAllCommands`
+     */
+    getAllCommands(): CommandInfo[];
+    /**
+     * Validates security decorators before delegating to RESOURCE.
+     *
+     * @remarks
+     * Validation order: @Guard → @Throttle → @RequiresState
+     * Throws on first failure to prevent execution.
+     *
+     * @param player - Player executing the command
+     * @param commandName - Command name (for rate limit key)
+     * @param security - Security metadata from command decorators
+     *
+     * @throws AppError - If @Guard or @RequiresState validation fails
+     * @throws SecurityError - If @Throttle rate limit is exceeded
+     */
+    private validateSecurity;
+}

package/dist/runtime/server/controllers/command-export.controller.js

@@ -0,0 +1,260 @@
+"use strict";
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandExportController = void 0;
+const tsyringe_1 = require("tsyringe");
+const IEngineEvents_1 = require("../../../adapters/contracts/IEngineEvents");
+const logger_1 = require("../../../kernel/shared/logger");
+const utils_1 = require("../../../kernel/utils");
+const security_error_1 = require("../../../kernel/utils/error/security.error");
+const decorators_1 = require("../decorators");
+const onNet_1 = require("../decorators/onNet");
+const entities_1 = require("../entities");
+const command_execution_port_1 = require("../services/ports/command-execution.port");
+const player_directory_port_1 = require("../services/ports/player-directory.port");
+const principal_port_1 = require("../services/ports/principal.port");
+const rate_limiter_service_1 = require("../services/rate-limiter.service");
+/**
+ * Export controller for command system (CORE mode only).
+ *
+ * @remarks
+ * Exposes command registration and execution to RESOURCE mode instances.
+ * Maintains a registry of both local and remote commands, delegating
+ * remote command execution back to the owning resource via net events.
+ */
+let CommandExportController = class CommandExportController {
+    constructor(commandService, playerDirectory, principalPort, rateLimiter, engineEvents) {
+        this.commandService = commandService;
+        this.playerDirectory = playerDirectory;
+        this.principalPort = principalPort;
+        this.rateLimiter = rateLimiter;
+        this.engineEvents = engineEvents;
+        this.remoteCommands = new Map();
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Network Event Handler (receives commands from clients)
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Receives command execution requests from clients.
+     *
+     * @remarks
+     * This is the entry point for all command execution in CORE mode.
+     * Handles both local commands (registered in CORE) and remote commands
+     * (registered by RESOURCE mode instances).
+     */
+    async onCommandReceived(player, command, args) {
+        try {
+            if (command.startsWith('/'))
+                command = command.slice(1);
+            // Basic input validation
+            if (args.length > 10 || !/^[a-zA-Z0-9:_-]+$/.test(command)) {
+                logger_1.loggers.command.warn(`Rejected suspicious command: ${command}`, {
+                    playerId: player.clientID,
+                    playerName: player.name,
+                });
+                return;
+            }
+            logger_1.loggers.command.trace(`Received: /${command}`, {
+                playerId: player.clientID,
+                playerName: player.name,
+            });
+            // Use unified execution that handles both local and remote commands
+            await this.executeCommand(player.clientID, command, args);
+        }
+        catch (error) {
+            if (error instanceof utils_1.AppError) {
+                if (error.code === 'GAME:BAD_REQUEST' || error.code === 'COMMAND:NOT_FOUND') {
+                    player.send(error.message, 'error');
+                }
+                else {
+                    player.send('An error occurred while executing the command', 'error');
+                }
+                logger_1.loggers.command.error(`Execution failed: /${command}`, { playerId: player.clientID }, error);
+            }
+            else if (error instanceof security_error_1.SecurityError) {
+                player.send(error.message, 'error');
+                logger_1.loggers.command.warn(`Security error: /${command}`, {
+                    playerId: player.clientID,
+                    error: error.message,
+                });
+            }
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Command Registration (for RESOURCE mode)
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Registers a command from a RESOURCE with CORE.
+     *
+     * @remarks
+     * The command handler remains in the resource. CORE stores metadata
+     * and delegates execution back to the resource when invoked.
+     *
+     * Exported as: `exports[coreResourceName].registerCommand`
+     */
+    registerCommand(metadata) {
+        var _a;
+        const commandKey = metadata.command.toLowerCase();
+        if (this.remoteCommands.has(commandKey)) {
+            logger_1.loggers.command.warn(`Remote command '${metadata.command}' already registered`, {
+                command: metadata.command,
+                existingResource: (_a = this.remoteCommands.get(commandKey)) === null || _a === void 0 ? void 0 : _a.resourceName,
+                newResource: metadata.resourceName,
+            });
+            return;
+        }
+        this.remoteCommands.set(commandKey, {
+            metadata,
+            resourceName: metadata.resourceName,
+        });
+        const publicFlag = metadata.isPublic ? ' [Public]' : '';
+        logger_1.loggers.command.debug(`Registered remote command: /${metadata.command}${publicFlag} (owner: ${metadata.resourceName})`);
+    }
+    /**
+     * Executes a command (local or remote).
+     *
+     * @remarks
+     * If the command is registered locally in CORE, executes it directly.
+     * If it's a remote command, delegates to the owning resource via net event.
+     *
+     * Exported as: `exports[coreResourceName].executeCommand`
+     */
+    async executeCommand(clientID, commandName, args) {
+        const player = this.playerDirectory.getByClient(clientID);
+        if (!player) {
+            throw new utils_1.AppError('GAME:PLAYER_NOT_FOUND', `Player not found: ${clientID}`, 'core');
+        }
+        const commandKey = commandName.toLowerCase();
+        const remoteEntry = this.remoteCommands.get(commandKey);
+        if (remoteEntry) {
+            // Validate security BEFORE delegating to resource
+            await this.validateSecurity(player, commandName, remoteEntry.metadata.security);
+            // Delegate to resource via local event (server-to-server, not network)
+            const eventName = `opencore:command:execute:${remoteEntry.resourceName}`;
+            this.engineEvents.emit(eventName, clientID, commandName, args);
+            logger_1.loggers.command.debug(`Delegated remote command execution to ${remoteEntry.resourceName}`, {
+                command: commandName,
+                clientID,
+                resource: remoteEntry.resourceName,
+            });
+            return;
+        }
+        // Execute local command
+        return await this.commandService.execute(player, commandName, args);
+    }
+    /**
+     * Returns all registered commands (local + remote).
+     *
+     * Exported as: `exports[coreResourceName].getAllCommands`
+     */
+    getAllCommands() {
+        const localCommands = this.commandService.getAllCommands();
+        const remoteCommandsInfo = Array.from(this.remoteCommands.values()).map((entry) => ({
+            command: entry.metadata.command,
+            description: entry.metadata.description,
+            usage: entry.metadata.usage,
+            isPublic: entry.metadata.isPublic,
+        }));
+        return [...localCommands, ...remoteCommandsInfo];
+    }
+    /**
+     * Validates security decorators before delegating to RESOURCE.
+     *
+     * @remarks
+     * Validation order: @Guard → @Throttle → @RequiresState
+     * Throws on first failure to prevent execution.
+     *
+     * @param player - Player executing the command
+     * @param commandName - Command name (for rate limit key)
+     * @param security - Security metadata from command decorators
+     *
+     * @throws AppError - If @Guard or @RequiresState validation fails
+     * @throws SecurityError - If @Throttle rate limit is exceeded
+     */
+    async validateSecurity(player, commandName, security) {
+        if (!security)
+            return;
+        // 1. Validate @Guard (rank/permission)
+        if (security.guard) {
+            await this.principalPort.enforce(player, security.guard);
+        }
+        // 2. Validate @Throttle (rate limiting)
+        if (security.throttle) {
+            const { limit, windowMs, onExceed, message } = security.throttle;
+            const rateLimitKey = `${player.clientID}:remote:${commandName}`;
+            const allowed = this.rateLimiter.checkLimit(rateLimitKey, limit, windowMs);
+            if (!allowed) {
+                const errorMessage = message || `Rate limit exceeded for command: ${commandName}`;
+                if (onExceed === 'KICK') {
+                    DropPlayer(player.clientID.toString(), errorMessage);
+                }
+                throw new security_error_1.SecurityError(onExceed || 'LOG', errorMessage, { clientID: player.clientID });
+            }
+        }
+        // 3. Validate @RequiresState (player state)
+        if (security.requiresState) {
+            const { has, missing, errorMessage } = security.requiresState;
+            if (has) {
+                for (const state of has) {
+                    if (!player.hasState(state)) {
+                        throw new utils_1.AppError('GAME:INVALID_STATE', errorMessage || `Command requires state: ${state}`, 'core');
+                    }
+                }
+            }
+            if (missing) {
+                for (const state of missing) {
+                    if (player.hasState(state)) {
+                        throw new utils_1.AppError('GAME:INVALID_STATE', errorMessage || `Command cannot be used in state: ${state}`, 'core');
+                    }
+                }
+            }
+        }
+    }
+};
+exports.CommandExportController = CommandExportController;
+__decorate([
+    (0, decorators_1.Public)(),
+    (0, onNet_1.OnNet)('core:execute-command'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [entities_1.Player, String, Array]),
+    __metadata("design:returntype", Promise)
+], CommandExportController.prototype, "onCommandReceived", null);
+__decorate([
+    (0, decorators_1.Export)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], CommandExportController.prototype, "registerCommand", null);
+__decorate([
+    (0, decorators_1.Export)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String, Array]),
+    __metadata("design:returntype", Promise)
+], CommandExportController.prototype, "executeCommand", null);
+__decorate([
+    (0, decorators_1.Export)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Array)
+], CommandExportController.prototype, "getAllCommands", null);
+exports.CommandExportController = CommandExportController = __decorate([
+    (0, tsyringe_1.injectable)(),
+    (0, decorators_1.Controller)(),
+    __param(4, (0, tsyringe_1.inject)(IEngineEvents_1.IEngineEvents)),
+    __metadata("design:paramtypes", [command_execution_port_1.CommandExecutionPort,
+        player_directory_port_1.PlayerDirectoryPort,
+        principal_port_1.PrincipalPort,
+        rate_limiter_service_1.RateLimiterService,
+        IEngineEvents_1.IEngineEvents])
+], CommandExportController);

package/dist/runtime/server/controllers/command.controller.d.ts

@@ -0,0 +1,15 @@
+import { CommandExecutionPort } from '../services/ports/command-execution.port'
+import { Player } from '../entities'
+/**
+ * Network controller for command execution.
+ *
+ * @remarks
+ * Receives command execution requests from clients and delegates to CommandExecutionPort.
+ * In CORE mode, executes commands directly or delegates to owning resource.
+ * In RESOURCE mode, delegates to CORE via exports.
+ */
+export declare class CommandNetworkController {
+  private readonly commandService
+  constructor(commandService: CommandExecutionPort)
+  onCommandReceived(player: Player, command: string, args: string[]): Promise<void>
+}

package/dist/runtime/server/controllers/command.controller.js

@@ -0,0 +1,100 @@
+'use strict'
+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) ||
+  ((k, v) => {
+    if (typeof Reflect === 'object' && typeof Reflect.metadata === 'function')
+      return Reflect.metadata(k, v)
+  })
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.CommandNetworkController = void 0
+const onNet_1 = require('../decorators/onNet')
+const command_execution_port_1 = require('../services/ports/command-execution.port')
+const entities_1 = require('../entities')
+const decorators_1 = require('../decorators')
+const logger_1 = require('../../../kernel/shared/logger')
+const utils_1 = require('../../../kernel/utils')
+/**
+ * Network controller for command execution.
+ *
+ * @remarks
+ * Receives command execution requests from clients and delegates to CommandExecutionPort.
+ * In CORE mode, executes commands directly or delegates to owning resource.
+ * In RESOURCE mode, delegates to CORE via exports.
+ */
+let CommandNetworkController = class CommandNetworkController {
+  constructor(commandService) {
+    this.commandService = commandService
+  }
+  async onCommandReceived(player, command, args) {
+    try {
+      if (command.startsWith('/')) command = command.slice(1)
+      if (!player.clientID || player.clientID === null || player.clientID === undefined) {
+        console.log('DEBUG; Player entity not received in core:execute-command')
+      }
+      if (args.length > 10 || !/^[a-zA-Z0-9:_-]+$/.test(command)) {
+        logger_1.loggers.command.warn(`Rejected suspicious command: ${command}`, {
+          playerId: player.clientID,
+          playerName: player.name,
+        })
+        return
+      }
+      logger_1.loggers.command.trace(`Received: /${command}`, {
+        playerId: player.clientID,
+        playerName: player.name,
+      })
+      await this.commandService.execute(player, command, args)
+    } catch (error) {
+      if (error instanceof utils_1.AppError) {
+        if (error.code === 'GAME:BAD_REQUEST' || error.code === 'COMMAND:NOT_FOUND')
+          player.send(error.message, 'error')
+        else player.send('An error occurred while executing the command', 'error')
+        logger_1.loggers.command.error(
+          `Execution failed: /${command}`,
+          {
+            playerId: player.clientID,
+          },
+          error,
+        )
+      }
+    }
+  }
+}
+exports.CommandNetworkController = CommandNetworkController
+__decorate(
+  [
+    (0, decorators_1.Public)(),
+    (0, onNet_1.OnNet)('core:execute-command'),
+    __metadata('design:type', Function),
+    __metadata('design:paramtypes', [entities_1.Player, String, Array]),
+    __metadata('design:returntype', Promise),
+  ],
+  CommandNetworkController.prototype,
+  'onCommandReceived',
+  null,
+)
+exports.CommandNetworkController = CommandNetworkController = __decorate(
+  [
+    (0, decorators_1.Controller)(),
+    __metadata('design:paramtypes', [command_execution_port_1.CommandExecutionPort]),
+  ],
+  CommandNetworkController,
+)

package/dist/runtime/server/controllers/player-export.controller.d.ts

@@ -0,0 +1,29 @@
+import { PlayerDirectoryPort } from '../services/ports/player-directory.port';
+import { CorePlayerExports, SerializedPlayerData } from '../types/core-exports';
+/**
+ * Exports player directory functionality for RESOURCE mode access.
+ *
+ * @remarks
+ * This controller provides a complete API for remote resources to:
+ * - Query player data (by client ID, account ID, or all players)
+ * - Check online status and player count
+ * - Read/write session metadata
+ * - Manage player state flags
+ */
+export declare class PlayerExportController implements CorePlayerExports {
+    private playerService;
+    constructor(playerService: PlayerDirectoryPort);
+    getPlayerId(clientID: number): string | undefined;
+    getPlayerData(clientID: number): SerializedPlayerData | null;
+    getManyData(clientIds: number[]): SerializedPlayerData[];
+    getAllPlayersData(): SerializedPlayerData[];
+    getPlayerByAccountId(accountId: string): SerializedPlayerData | null;
+    getPlayerCount(): number;
+    isPlayerOnline(accountId: string): boolean;
+    getPlayerMeta(clientID: number, key: string): Promise<any>;
+    setPlayerMeta(clientID: number, key: string, value: any): void;
+    getPlayerStates(clientID: number): string[];
+    hasPlayerState(clientID: number, state: string): boolean;
+    addPlayerState(clientID: number, state: string): void;
+    removePlayerState(clientID: number, state: string): void;
+}