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

package/dist/runtime/server/controllers/remote-command-execution.controller.js

@@ -0,0 +1,172 @@
+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); }
+};
+import { inject } from 'tsyringe';
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { IResourceInfo } from '../../../adapters/contracts/IResourceInfo';
+import { loggers } from '../../../kernel/logger';
+import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
+import { Controller } from '../decorators';
+import { normalizeToAppError } from '../helpers/normalize-app-error';
+import { getRuntimeContext } from '../runtime';
+import { CommandExecutionPort } from '../ports/internal/command-execution.port';
+import { Players } from '../ports/players.api-port';
+/**
+ * Controller for executing remote commands in RESOURCE mode.
+ *
+ * @remarks
+ * Listens for command execution events from CORE and invokes
+ * the local handler stored in RemoteCommandService.
+ *
+ * Flow:
+ * 1. Player executes command → sent to CORE
+ * 2. CORE validates and emits local event to owning resource
+ * 3. This controller receives event → looks up handler → executes
+ *
+ * @note Uses IEngineEvents.on() (local event) not @OnNet (network event)
+ * because CORE→RESOURCE communication is server-to-server.
+ * Event registration happens in constructor via adapter layer.
+ */
+let RemoteCommandExecutionController = class RemoteCommandExecutionController {
+    commandService;
+    playerDirectory;
+    commandErrorObserver;
+    engineEvents;
+    resourceInfo;
+    constructor(commandService, playerDirectory, commandErrorObserver, engineEvents, resourceInfo) {
+        this.commandService = commandService;
+        this.playerDirectory = playerDirectory;
+        this.commandErrorObserver = commandErrorObserver;
+        this.engineEvents = engineEvents;
+        this.resourceInfo = resourceInfo;
+        this.registerEventHandler();
+    }
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break command execution.
+     */
+    async safeObserve(ctx) {
+        try {
+            await this.commandErrorObserver.onError(ctx);
+        }
+        catch (e) {
+            loggers.command.fatal(`Command error observer failed`, ctx, e);
+        }
+    }
+    /**
+     * Registers the event handler for command execution from CORE.
+     *
+     * @remarks
+     * Event format: `opencore:command:execute:{resourceName}`
+     * Uses adapter layer instead of direct FiveM globals.
+     */
+    registerEventHandler() {
+        const resourceName = this.resourceInfo.getCurrentResourceName();
+        const eventName = `opencore:command:execute:${resourceName}`;
+        this.engineEvents.on(eventName, async (clientID, commandName, args) => {
+            await this.handleCommandExecution(clientID, commandName, args);
+        });
+        loggers.command.debug(`Registered remote command handler for resource: ${resourceName}`);
+    }
+    /**
+     * Handles command execution requests from CORE.
+     *
+     * @param clientID - The client ID of the player executing the command
+     * @param commandName - The command to execute
+     * @param args - Command arguments
+     */
+    async handleCommandExecution(clientID, commandName, args) {
+        loggers.command.debug(`Received command execution request`, {
+            command: commandName,
+            clientID,
+            args,
+        });
+        const player = this.playerDirectory.getByClient(clientID);
+        if (!player) {
+            loggers.command.warn(`Command execution failed: player not found`, {
+                command: commandName,
+                clientID,
+            });
+            return;
+        }
+        loggers.command.debug(`Executing command for player`, {
+            command: commandName,
+            playerName: player.name,
+            clientID,
+        });
+        try {
+            await this.commandService.execute(player, commandName, args);
+            loggers.command.debug(`Command executed successfully`, {
+                command: commandName,
+                clientID,
+            });
+        }
+        catch (error) {
+            // Do not notify the player here. Report through the global observer.
+            const runtime = getRuntimeContext();
+            const appError = normalizeToAppError(error, 'server');
+            const meta = this.commandService.getCommandMeta(commandName);
+            const stage = appError.code === 'GAME:BAD_REQUEST' || appError.code.startsWith('SCHEMA:')
+                ? 'validation'
+                : appError.code === 'COMMAND:NOT_FOUND'
+                    ? 'dispatch'
+                    : 'handler';
+            await this.safeObserve({
+                mode: runtime.mode,
+                scope: runtime.mode === 'CORE'
+                    ? 'core'
+                    : runtime.mode === 'RESOURCE'
+                        ? 'resource'
+                        : 'standalone',
+                stage,
+                error: appError,
+                commandName,
+                args,
+                player: {
+                    clientId: player.clientID,
+                    accountId: player.accountID,
+                    name: player.name,
+                },
+                playerRef: player,
+                command: meta
+                    ? {
+                        command: meta.command,
+                        description: meta.description,
+                        usage: meta.usage,
+                        isPublic: meta.isPublic,
+                        methodName: meta.methodName,
+                        expectsPlayer: meta.expectsPlayer,
+                        paramNames: meta.paramNames,
+                    }
+                    : undefined,
+                commandMeta: meta,
+                ownerResourceName: this.resourceInfo.getCurrentResourceName(),
+            });
+        }
+    }
+};
+RemoteCommandExecutionController = __decorate([
+    Controller(),
+    __param(0, inject(CommandExecutionPort)),
+    __param(1, inject(Players)),
+    __param(2, inject(CommandErrorObserverContract)),
+    __param(3, inject(IEngineEvents)),
+    __param(4, inject(IResourceInfo)),
+    __metadata("design:paramtypes", [CommandExecutionPort,
+        Players,
+        CommandErrorObserverContract,
+        IEngineEvents,
+        IResourceInfo])
+], RemoteCommandExecutionController);
+export { RemoteCommandExecutionController };

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

@@ -0,0 +1,11 @@
+import { PlayerPersistenceService } from '../services/persistence.service';
+import { PlayerSessionLifecyclePort } from '../ports/internal/player-session-lifecycle.port';
+import { Players } from '../ports/players.api-port';
+export declare class SessionController {
+    private readonly playerSessionLifecycle;
+    private readonly playerDirectory;
+    private readonly persistance;
+    constructor(playerSessionLifecycle: PlayerSessionLifecyclePort, playerDirectory: Players, persistance: PlayerPersistenceService);
+    onPlayerJoining(clientId: number, identifiers?: Record<string, string>): Promise<void>;
+    onPlayerDropped(clientId: number): Promise<void>;
+}

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

@@ -0,0 +1,84 @@
+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); }
+};
+import { RUNTIME_EVENTS } from '../../../adapters/contracts/runtime';
+import { inject } from 'tsyringe';
+import { loggers } from '../../../kernel/logger';
+import { emitFrameworkEvent } from '../bus/internal-event.bus';
+import { Controller } from '../decorators';
+import { OnRuntimeEvent } from '../decorators/onRuntimeEvent';
+import { PlayerPersistenceService } from '../services/persistence.service';
+import { PlayerSessionLifecyclePort } from '../ports/internal/player-session-lifecycle.port';
+import { Players } from '../ports/players.api-port';
+let SessionController = class SessionController {
+    playerSessionLifecycle;
+    playerDirectory;
+    persistance;
+    constructor(playerSessionLifecycle, playerDirectory, persistance) {
+        this.playerSessionLifecycle = playerSessionLifecycle;
+        this.playerDirectory = playerDirectory;
+        this.persistance = persistance;
+    }
+    async onPlayerJoining(clientId, identifiers) {
+        const player = this.playerSessionLifecycle.bind(clientId, {
+            license: identifiers?.license,
+            ...identifiers,
+        });
+        loggers.session.info(`Player session created`, {
+            clientId,
+            license: identifiers?.license ?? 'none',
+        });
+        await this.persistance.handleSessionLoad(player);
+        emitFrameworkEvent('internal:playerSessionCreated', {
+            clientId,
+            license: identifiers?.license,
+        });
+        setImmediate(() => {
+            const currentPlayer = this.playerDirectory.getByClient(clientId);
+            if (!currentPlayer)
+                return;
+            const payload = { player: currentPlayer };
+            emitFrameworkEvent('internal:playerFullyConnected', payload);
+        });
+    }
+    async onPlayerDropped(clientId) {
+        const player = this.playerDirectory.getByClient(clientId);
+        if (player) {
+            await this.persistance.handleSessionSave(player);
+        }
+        this.playerSessionLifecycle.unbind(clientId);
+        emitFrameworkEvent('internal:playerSessionDestroyed', { clientId });
+        loggers.session.info(`Player session destroyed`, { clientId });
+    }
+};
+__decorate([
+    OnRuntimeEvent(RUNTIME_EVENTS.playerJoining),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, Object]),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "onPlayerJoining", null);
+__decorate([
+    OnRuntimeEvent(RUNTIME_EVENTS.playerDropped),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "onPlayerDropped", null);
+SessionController = __decorate([
+    Controller(),
+    __param(0, inject(PlayerSessionLifecyclePort)),
+    __param(1, inject(Players)),
+    __param(2, inject(PlayerPersistenceService)),
+    __metadata("design:paramtypes", [PlayerSessionLifecyclePort,
+        Players,
+        PlayerPersistenceService])
+], SessionController);
+export { SessionController };

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

@@ -0,0 +1,22 @@
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { Player } from '../entities/player';
+import { Vehicles } from '../apis/vehicles.api';
+/**
+ * Controller for handling vehicle-related network events.
+ *
+ * All client requests for vehicle operations go through this controller
+ * for validation and security checks.
+ */
+export declare class VehicleController {
+    private readonly vehicleService;
+    private readonly events;
+    constructor(vehicleService: Vehicles, events: EventsAPI<'server'>);
+    /**
+     * Handles client request to get vehicle data.
+     */
+    handleGetData(player: Player, networkId: number): import("..").SerializedVehicleData | null;
+    /**
+     * Handles client request to get all player vehicles.
+     */
+    handleGetPlayerVehicles(player: Player): import("..").SerializedVehicleData[];
+}

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

@@ -0,0 +1,73 @@
+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); }
+};
+import { inject } from 'tsyringe';
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { Controller, OnNet } from '../decorators';
+import { Player } from '../entities/player';
+import { Vehicles } from '../apis/vehicles.api';
+/**
+ * Controller for handling vehicle-related network events.
+ *
+ * All client requests for vehicle operations go through this controller
+ * for validation and security checks.
+ */
+let VehicleController = class VehicleController {
+    vehicleService;
+    events;
+    constructor(vehicleService, events) {
+        this.vehicleService = vehicleService;
+        this.events = events;
+    }
+    /**
+     * Handles client request to get vehicle data.
+     */
+    handleGetData(player, networkId) {
+        const vehicle = this.vehicleService.getByNetworkId(networkId);
+        if (!vehicle) {
+            this.events.emit('opencore:vehicle:dataResult', player.clientID, null);
+            return null;
+        }
+        const data = vehicle.serialize();
+        this.events.emit('opencore:vehicle:dataResult', player.clientID, data);
+        return data;
+    }
+    /**
+     * Handles client request to get all player vehicles.
+     */
+    handleGetPlayerVehicles(player) {
+        const vehicles = this.vehicleService.getPlayerVehicles(player.clientID);
+        const serialized = vehicles.map((v) => v.serialize());
+        this.events.emit('opencore:vehicle:playerVehiclesResult', player.clientID, serialized);
+        return serialized;
+    }
+};
+__decorate([
+    OnNet('opencore:vehicle:getData'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Player, Number]),
+    __metadata("design:returntype", void 0)
+], VehicleController.prototype, "handleGetData", null);
+__decorate([
+    OnNet('opencore:vehicle:getPlayerVehicles'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Player]),
+    __metadata("design:returntype", void 0)
+], VehicleController.prototype, "handleGetPlayerVehicles", null);
+VehicleController = __decorate([
+    Controller(),
+    __param(0, inject(Vehicles)),
+    __param(1, inject(EventsAPI)),
+    __metadata("design:paramtypes", [Vehicles,
+        EventsAPI])
+], VehicleController);
+export { VehicleController };

package/dist/runtime/server/core.d.ts

@@ -0,0 +1,9 @@
+import { type OpenCorePlugin } from './library/plugin';
+import { type FrameworkMode, type ServerInitOptions } from './runtime';
+import { OpenCoreServerAdapter } from './adapter';
+export declare let _mode: FrameworkMode;
+export interface OpenCoreInitOptions extends ServerInitOptions {
+    plugins?: OpenCorePlugin[];
+}
+export declare function useAdapter(adapter: OpenCoreServerAdapter): void;
+export declare function init(options: OpenCoreInitOptions): Promise<void>;

package/dist/runtime/server/core.js

@@ -0,0 +1,45 @@
+import { GLOBAL_CONTAINER } from '../../kernel/di/container';
+import { PluginRegistry } from './library/plugin';
+import { Server } from './server.runtime';
+import { initServer } from './bootstrap';
+import { resolveRuntimeOptions, } from './runtime';
+export let _mode;
+let _pendingAdapter;
+export function useAdapter(adapter) {
+    _pendingAdapter = adapter;
+}
+function createConfigAccessor(options) {
+    const runtimeOptions = { ...options };
+    return {
+        get(key) {
+            const segments = key.split('.').filter(Boolean);
+            let current = runtimeOptions;
+            for (const segment of segments) {
+                if (typeof current !== 'object' || current === null) {
+                    return undefined;
+                }
+                current = current[segment];
+            }
+            return current;
+        },
+    };
+}
+export async function init(options) {
+    if (!options.adapter && _pendingAdapter) {
+        options = { ...options, adapter: _pendingAdapter };
+    }
+    const resolved = resolveRuntimeOptions(options);
+    _mode = resolved.mode;
+    const registry = new PluginRegistry();
+    const pluginContext = {
+        server: Server,
+        di: {
+            register(token, value) {
+                GLOBAL_CONTAINER.registerInstance(token, value);
+            },
+        },
+        config: createConfigAccessor(resolved),
+    };
+    await registry.installAll(options.plugins ?? [], pluginContext);
+    await initServer(resolved, { registry, context: pluginContext });
+}

package/dist/runtime/server/decorators/binaryCall.d.ts

@@ -0,0 +1,15 @@
+export interface BinaryCallOptions {
+    action?: string;
+    timeoutMs?: number;
+    service?: string;
+}
+/**
+ * marks a method as a remote binary action executed by a BinaryService. When a method decorated with @BinaryCall is invoked, its implementation is never executed locally. Instead, OpenCore replaces the method at runtime with an asynchronous proxy that:
+ * - Serializes the method arguments
+ * - Sends a request to the associated binary process
+ * - Waits for a response
+ * - Resolves or rejects the returned Promise
+ *
+ * From the developer’s perspective, the method behaves like a normal async function, while the actual logic is executed externally.
+ */
+export declare function BinaryCall(options?: BinaryCallOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;

package/dist/runtime/server/decorators/binaryCall.js

@@ -0,0 +1,23 @@
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * marks a method as a remote binary action executed by a BinaryService. When a method decorated with @BinaryCall is invoked, its implementation is never executed locally. Instead, OpenCore replaces the method at runtime with an asynchronous proxy that:
+ * - Serializes the method arguments
+ * - Sends a request to the associated binary process
+ * - Waits for a response
+ * - Resolves or rejects the returned Promise
+ *
+ * From the developer’s perspective, the method behaves like a normal async function, while the actual logic is executed externally.
+ */
+export function BinaryCall(options = {}) {
+    return (target, propertyKey, descriptor) => {
+        if (!descriptor.value) {
+            throw new Error(`@BinaryCall(): descriptor.value is undefined for method '${propertyKey}'`);
+        }
+        Reflect.defineMetadata(METADATA_KEYS.BINARY_CALL, {
+            methodName: propertyKey,
+            action: options.action ?? propertyKey,
+            timeoutMs: options.timeoutMs,
+            service: options.service,
+        }, target, propertyKey);
+    };
+}

package/dist/runtime/server/decorators/binaryEvent.d.ts

@@ -0,0 +1,21 @@
+export interface BinaryEventOptions {
+    event?: string;
+    service?: string;
+}
+export interface BinaryEventMetadata {
+    methodName: string;
+    event: string;
+    service?: string;
+}
+/**
+ * Registers a method as a listener for events emitted by a BinaryService process.
+ * When the binary writes an event message to stdout, the framework dispatches it
+ * to the matching handler automatically.
+ *
+ * The binary must emit a JSON line with the shape:
+ * `{ "type": "event", "event": "<name>", "data": <any> }`
+ *
+ * @param options.event - Event name to listen for. Defaults to the method name.
+ * @param options.service - Target BinaryService name. Only needed when the handler lives outside the service class.
+ */
+export declare function BinaryEvent(options?: BinaryEventOptions): (target: any, propertyKey: string, _descriptor: PropertyDescriptor) => void;

package/dist/runtime/server/decorators/binaryEvent.js

@@ -0,0 +1,22 @@
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * Registers a method as a listener for events emitted by a BinaryService process.
+ * When the binary writes an event message to stdout, the framework dispatches it
+ * to the matching handler automatically.
+ *
+ * The binary must emit a JSON line with the shape:
+ * `{ "type": "event", "event": "<name>", "data": <any> }`
+ *
+ * @param options.event - Event name to listen for. Defaults to the method name.
+ * @param options.service - Target BinaryService name. Only needed when the handler lives outside the service class.
+ */
+export function BinaryEvent(options = {}) {
+    return (target, propertyKey, _descriptor) => {
+        const metadata = {
+            methodName: propertyKey,
+            event: options.event ?? propertyKey,
+            service: options.service,
+        };
+        Reflect.defineMetadata(METADATA_KEYS.BINARY_EVENT, metadata, target, propertyKey);
+    };
+}

package/dist/runtime/server/decorators/binaryService.d.ts

@@ -0,0 +1,27 @@
+import { ClassConstructor } from '../../../kernel/di/class-constructor';
+export interface BinaryServiceOptions {
+    /** Logical identifier of the service inside OpenCore. This name is used to route binary calls and must be unique per resource. */
+    name: string;
+    /** Logical binary filename (without extension). The framework resolves the correct executable automatically depending on the platform */
+    binary: string;
+    /**
+     * Default timeout for binary calls in milliseconds. If the binary does not respond within this time, the call is rejected automatically.
+     */
+    timeoutMs?: number;
+}
+export interface BinaryServiceMetadata extends BinaryServiceOptions {
+    serviceClass: ClassConstructor;
+}
+export declare const _serverBinaryServiceRegistryByResource: Map<string, Set<ClassConstructor>>;
+export declare function getServerBinaryServiceRegistry(resourceName?: string): ClassConstructor[];
+/**
+ * Declares a native external binary service managed by OpenCore.
+ * A BinaryService represents a persistent operating system process executed outside the FiveM runtime, allowing heavy or sensitive logic to run in complete isolation while being consumed from TypeScript as normal asynchronous methods.
+ * Binary services communicate with OpenCore using a simple JSON-based RPC protocol over stdin / stdout.
+ *
+ * @remarks
+ * - The binary name is logical (no extensions). The framework resolves platform-specific files.
+ * - A single process is spawned and kept alive for the resource lifecycle.
+ * - This system is language-agnostic and can be implemented in any language capable of reading from standard input and writing to standard output.
+ */
+export declare function BinaryService(options: BinaryServiceOptions): (target: ClassConstructor) => void;

package/dist/runtime/server/decorators/binaryService.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+import { Bind } from './bind';
+export const _serverBinaryServiceRegistryByResource = new Map();
+function getCurrentResourceNameSafe() {
+    const fn = globalThis.GetCurrentResourceName;
+    if (typeof fn === 'function') {
+        const name = fn();
+        if (typeof name === 'string' && name.trim())
+            return name;
+    }
+    return 'default';
+}
+export function getServerBinaryServiceRegistry(resourceName) {
+    const key = resourceName ?? getCurrentResourceNameSafe();
+    let registry = _serverBinaryServiceRegistryByResource.get(key);
+    if (!registry) {
+        registry = new Set();
+        _serverBinaryServiceRegistryByResource.set(key, registry);
+    }
+    return Array.from(registry);
+}
+function assertValidBinaryName(binary) {
+    if (!binary || !binary.trim()) {
+        throw new Error('[OpenCore] BinaryService requires a non-empty binary name');
+    }
+    if (binary.includes('.') || path.extname(binary)) {
+        throw new Error(`[OpenCore] BinaryService binary name must not include extensions: ${binary}`);
+    }
+    if (/[/\\]/.test(binary)) {
+        throw new Error(`[OpenCore] BinaryService binary name must not include path separators: ${binary}`);
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(binary)) {
+        throw new Error(`[OpenCore] BinaryService binary name has invalid characters: ${binary}`);
+    }
+}
+function assertValidServiceName(name) {
+    if (!name || !name.trim()) {
+        throw new Error('[OpenCore] BinaryService requires a non-empty service name');
+    }
+}
+/**
+ * Declares a native external binary service managed by OpenCore.
+ * A BinaryService represents a persistent operating system process executed outside the FiveM runtime, allowing heavy or sensitive logic to run in complete isolation while being consumed from TypeScript as normal asynchronous methods.
+ * Binary services communicate with OpenCore using a simple JSON-based RPC protocol over stdin / stdout.
+ *
+ * @remarks
+ * - The binary name is logical (no extensions). The framework resolves platform-specific files.
+ * - A single process is spawned and kept alive for the resource lifecycle.
+ * - This system is language-agnostic and can be implemented in any language capable of reading from standard input and writing to standard output.
+ */
+export function BinaryService(options) {
+    return (target) => {
+        assertValidServiceName(options.name);
+        assertValidBinaryName(options.binary);
+        Bind('singleton')(target);
+        const metadata = {
+            ...options,
+            serviceClass: target,
+        };
+        Reflect.defineMetadata(METADATA_KEYS.BINARY_SERVICE, metadata, target);
+        Reflect.defineMetadata(METADATA_KEYS.BINARY_SERVICE_NAME, metadata.name, target);
+        const key = getCurrentResourceNameSafe();
+        let registry = _serverBinaryServiceRegistryByResource.get(key);
+        if (!registry) {
+            registry = new Set();
+            _serverBinaryServiceRegistryByResource.set(key, registry);
+        }
+        registry.add(target);
+    };
+}

package/dist/runtime/server/decorators/bind.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Supported binding scopes for {@link Bind}.
+ */
+export type BindingScope = 'singleton' | 'transient';
+/**
+ * Marks a class as injectable and binds it into the framework DI container.
+ *
+ * @remarks
+ * - This decorator is a small wrapper around tsyringe's `@injectable()` plus a lifecycle binding.
+ * - Use `singleton` for shared stateless/stateful services.
+ * - Use `transient` when you want a new instance per resolution scope.
+ *
+ * @param scope - Binding scope. Defaults to `singleton`.
+ *
+ * @example
+ * ```ts
+ * @Server.Bind('singleton')
+ * export class InventoryService {}
+ * ```
+ */
+export declare function Bind(scope?: BindingScope): (target: any) => void;

package/dist/runtime/server/decorators/bind.js

@@ -0,0 +1,28 @@
+import { injectable, Lifecycle, scoped, singleton } from 'tsyringe';
+/**
+ * Marks a class as injectable and binds it into the framework DI container.
+ *
+ * @remarks
+ * - This decorator is a small wrapper around tsyringe's `@injectable()` plus a lifecycle binding.
+ * - Use `singleton` for shared stateless/stateful services.
+ * - Use `transient` when you want a new instance per resolution scope.
+ *
+ * @param scope - Binding scope. Defaults to `singleton`.
+ *
+ * @example
+ * ```ts
+ * @Server.Bind('singleton')
+ * export class InventoryService {}
+ * ```
+ */
+export function Bind(scope = 'singleton') {
+    return (target) => {
+        injectable()(target);
+        if (scope === 'singleton') {
+            singleton()(target);
+        }
+        else {
+            scoped(Lifecycle.ResolutionScoped)(target);
+        }
+    };
+}